Transformações no Scene Graph

A transformação de uma entidade do Scene Graph define a translação (localização), a rotação (orientação) e a escala (tamanho) de uma entidade. Para transformar uma entidade do Scene Graph, a entidade deve ter um transform_component. O transform_component contém dois campos que você pode manipular por meio do código UEFN ou Verse:

• Origin: uma origem opcional a partir da qual o LocalTransform é calculado.

• LocalTransform: uma (/Verse.org/SpatialMath:)transformação em relação ao pai da entidade ou à Origem se o campo opcional Origem estiver definido.  

A origem de uma entidade é a entidade da qual o LocalTransform do transform_component de uma entidade é calculado. Este é o valor do campo Origem se o campo Origem no transform_component estiver definido, ou o pai da entidade na hierarquia do Scene Graph se o campo Origem não estiver definido.

É importante fazer a distinção entre uma transformação e o transform_component. Uma transformação é um tipo de dados composto definido no módulo /Verse.org/SpatialMath que armazena as seguintes quantidades no sistema de coordenadas Left-Up-Forward (LUF):

• Translação (vector3): a localização de um objeto.

• Rotação (rotation): a orientação do objeto.

• Escala (vector3): o tamanho do objeto.

O transform_component é uma classe do Verse definida no módulo /Verse.org/SceneGraph que armazena o LocalTransform de uma entidade do Scene Graph e, opcionalmente, uma origem alternativa. Você pode pensar no transform_component como um contêiner fornecido a uma entidade para uma transformação que define seu lugar na simulação.

Transformações Verse 

O Scene Graph usa transformações do módulo/Verse.org/SpatialMath. As transformações do módulo Verse usam o sistema de coordenadas LUF para a direita. Para construir uma transformação de Verse, você pode usar o arquétipo de classe e métodos integrados para criar rotações.

# Transform specifying all fields
MyTransform:transform = transform:
	Translation := vector3{Left := 2.0, Up := -4.0, Forward := 8.0}
	Rotation := MakeRotationFromEulerDegrees(-90.0, 180.0, 0.0)
	Scale := vector3{Left := 2.0, Up := 4.0, Forward := 2.0}

# Transform specifying only Translation
MyOtherTransform:transform = transform:
	Translation := vector3{Up := 512.0}

Para obter mais informações sobre o sistema de coordenadas no UEFN, consulte a página Sistema de coordenadas Left-Up-Forward. Isso também inclui informações sobre a conversão entre a transformação XYZ no módulo /UnrealEngine.com/Temporary/SpatialMath e a transformar do módulo Verse.

Construir uma entidade com um transform_component  

Você pode construir uma entidade no Organizador do UEFN ou por meio do Verse. 

No UEFN

Você pode adicionar rapidamente uma entidade do Scene Graph ao seu projeto por meio do menu Colocar atores.

Quando você adiciona uma entidade do Scene Graph ao seu projeto por meio do menu Colocar atores, a entidade é equipada com um transform_component por padrão.

Se quiser, você pode remover o componente transform_component navegando até a sua entidade colocada recentemente no painel Organizador, encontrando o componente e selecionando Remover componente.

Você pode ver abaixo que a entidade em questão não tem mais um transform_component.

No Verse

Quando você cria uma entidade do Scene Graph por meio do código Verse com o arquétipo da classe:

MyEntity:entity = entity{}

A entidade não está equipada com um transform_component. Em vez disso, um transform_component deve ser adicionado à sua entidade. Os métodos preferenciais para trabalhar com transformações são SetLocalTransform e SetGlobalTransform. Essas funções lidam com a criação do transform_component, definindo os valores e adicionando o componente de transformação à entidade ao mesmo tempo.

MyEntity:entity = entity{}

# Add entity to simulation entity so MyEntity begins simulating when play begins
if (SimEntity := Entity.GetSimulationEntity[]):
	SimEntity.AddEntities(array{MyEntity})

# Identity transform
IdentityTransform:transform = transform:
	Translation := vector3{Left := 0.0, Up := 0.0, Forward := 0.0}
	Rotation := MakeRotationFromEulerDegrees(0.0, 0.0, 0.0)

Você também pode adicionar o componente diretamente com AddComponents:

# Add entity to simulation entity so MyEntity begins simulating when play begins
if (SimEntity := Entity.GetSimulationEntity[]):
	SimEntity.AddEntities(array{MyEntity})

# Use AddComponents
MyEntity.AddComponents(array{ transform_component{ Entity := MyEntity }})

# Same as above, but more readable if adding multiple components at once
MyEntity.AddComponents of array:
    transform_component{Entity := MyEntity}

Métodos adicionais para adicionar um transform_component a uma entidade do Scene Graph por meio de código Verse são discutidos no segmento Como trabalhar com o transform_component em Verse.

 Como a transformação de uma entidade é calculada

A operação mais importante que você pode realizar em uma entidade do Scene Graph com o transform_component é obter ou definir a transformação de uma entidade.

Existem dois tipos de transformação nas quais você pode estar interessado: transformação local e transformação global. Para manipular efetivamente a transformação de uma entidade, é importante entender como essas transformações são calculadas.

A transformação local é a transformação em relação à origem de uma entidade. A transformação local de qualquer entidade do Scene Graph é o valor do campo local no transform_component de uma entidade do Scene Graph.

A transformação global é a transformação em relação à origem do sistema de coordenadas no espaço global. A transformação global de uma entidade do Scene Graph é calculada compondo o LocalTransform de uma entidade com:

• A transformação global do pai da entidade se o campo não estiver definido no transform_component da entidade; ou

• A transformação global da origem da entidade se o campo Origem estiver definido no transform_component da entidade.

O código a seguir funciona com um exemplo disso usando a translação sem rotação ou escala, para que as transformações resultantes possam ser calculadas adicionando as translações. Como este exemplo assume que a rotação e a escala são deixadas como suas respectivas identidades em todas as transformações, a abreviação é usada para se referir à transformação de uma entidade pelo vetor de translação da transformação da entidade.

Considere três entidades do Scene Graph organizadas como:

• BaseEntity: LocalTransform (0,0, 0,0, 0,0) no sistema de coordenadas LUF.

  • A: LocalTransform (750,0, 100,0, 0,0).

    • B: LocalTransform (-250,0, 100,0, 0,0).

Abaixo estão as três entidades em uma cena em que BaseEntity não tem mesh_component, A é um cubo e B é um cone:

Por exemplo, digamos que você deseja determinar a transformação local e a transformação global da entidade B. A transformação local é rápida de ver: é o valor do campo LocalTransform da entidade B transform_component, conforme mostrado abaixo:

A transformação local da entidade B é (-250,0, 100,0, 0,0).

Para calcular a transformar global da entidade B, você rastrearia a hierarquia da entidade B até a entidade de simulação e comporia as transformações começando na entidade de simulação e depois até a entidade B. A entidade de simulação é a raiz da simulação atual, sob a qual todas as outras entidades de simulação são filhas.

Estas são as etapas para calcular a transformação global da entidade B:

1. A entidade de simulação é a raiz da simulação atual.

   • Transformação global de entidade de simulação: (0,0, 0,0, 0,0).

2. A BaseEntity é uma filha da entidade de simulação. A BaseEntity tem uma transformação local de (0,0, 0,0, 0,0), conforme visto na Imagem 1.0. A composição da transformação global da entidade de simulação com a transformação local de BaseEntity produz:

   • Transformação global de BaseEntity: (0,0, 0,0, 0,0) + (0,0, 0,0, 0,0) = (0,0, 0,0, 0,0).

3. A entidade A é filha da BaseEntity. A entidade A tem uma transformação local de (750,0, 100,0, 0,0) como visto na Imagem 1.1. A composição da transformação global da BaseEntity com a transformação de posição da entidade A produz:

   • Transformação global da entidade A: (0,0, 0,0, 0,0) + (750,0, 100,0, 0,0) = (750,0, 100,0, 0,0).

4. A entidade B é filha da entidade A. A entidade B tem uma transformação local de (-250,0, 100,0, 0,0) como visto na Imagem 1.2. A composição da transformação global de A com a transformação de posição da entidade B produz:

   • Transformação global da entidade B: (750,0, 100,0, 0,0) + (-250,0, 100,0, 0,0) = (500,0, 200,0, 0,0).

Portanto, a transformação global da entidade B é (500,0, 200,0, 0,0) no sistema de coordenadas do LUF.

Como trabalhar com o transform_component no Editor 

Ao usar LocalTransform e Origem, você pode transformar uma entidade. 

Transformação local

O campo LocalTransform do transform_component de uma entidade é a (/Verse.org/SpatialMath:)transformação de uma entidade em relação à sua origem. Se o campo Origem não for definido explicitamente, a origem de uma entidade assume como padrão seu pai na hierarquia do Scene Graph. O campo LocalTransform é um campo editável que aparece no UEFN onde você edita diretamente uma entidade:

1. Translação: localização relativa à origem pai ou definida manualmente.

   • Altere a translação de uma entidade para movê-la pelo nível.

2. Rotação: orientação relativa à origem pai ou definida manualmente.

   • Altere a rotação de uma entidade para girá-la em torno do ponto de pivô da entidade.

3. Escala: tamanho relativo à origem pai ou definida manualmente.

   • Altere a escala de uma entidade para torná-la maior ou menor.

Origem

A Origem do transform_component de uma entidade é o objeto em relação ao qual o LocalTransform é calculado. Este campo no transform_component é opcional. Por padrão, o LocalTransform do transform_component é a transformação da entidade com base na origem da entidade, calculada em relação à entidade pai da entidade do proprietário. Opcionalmente, você pode definir o campo Origem no transform_component de uma entidade para calcular a LocalTransform em relação a um objeto que não seja o pai da entidade.

Por exemplo, você pode definir a Origem de uma entidade para ser uma entidade totalmente diferente. Você pode definir esse campo com qualquer classe que implementa a interface de origem do Verse. Em particular, para definir o campo Origem como outra entidade do Scene Graph, escolha a classe entity_origin e selecione a entidade que você deseja que seja a nova origem.

Veja a seguir um exemplo de como o campo Origem e o LocalTransform funcionam na prática. Considere uma BaseEntity localizada na origem do espaço do mundo com a entidade filha A representada pelo mesh_component do cubo, e a entidade filha B representada pelo mesh_component do cone.

Como pode ser visto na imagem acima, BaseEntity está localizada na origem do espaço do mundo, pois seu campo Origem não está definido no transform_component, e LocalTransform está configurada como a origem do espaço do mundo.

Como mostrado abaixo, você pode ver que o campo Origem da entidade A também não está definido, então a LocalTransform é calculada em relação ao transform_component de seu pai, BaseEntity.

Como BaseEntity está localizada na origem do espaço do mundo e a translação da LocalTransform da entidade A está definida como vector3{Left := 750.0, Up := 100.0, Forward := 0.0}, a entidade A está localizada no vector3{Left := 750.0, Up := 100.0, Forward := 0.0}. A rotação e a escala da entidade A permanecem inalteradas, pois a rotação e a escala do LocalTransform na BaseEntity são as respectivas identidades.

Na imagem abaixo, você pode ver que a entidade B, que também é uma filha de BaseEntity, tem o campo Origem no transform_component definido como a entidade A.

Como resultado, o campo LocalTransform da entidade B em seu transform_component é relativo à transformação calculada da entidade A. Como o LocalTransform da entidade B está definido como vector3,{Left := -250.0, Up := 100.0, Forward := 0.0} e o LocalTransform da entidade A está definido como vector3,{Left := 750.0, Up := 100.0, Forward := 0.0}, a transformação global da entidade B é vector3{Left := 500.0, Up := 200.0, Forward := 0.0}.

Se você alterar o componente rotação do campo LocalTransform do transform_component da entidade A para -90,0 graus em torno do eixo para a frente, a entidade B também girará -90,0 graus em torno do eixo para a frente. Isso ocorre porque a rotação de um filho também é herdada do pai.

Como trabalhar com o transform_component em Verse

  Você pode verificar se uma entidade tem um transform_component com GetComponent:

MyEntityNoTransform:entity = entity{}

if (SimEntity := Entity.GetSimulationEntity[]):
	SimEntity.AddEntities(array{MyEntityNoTransform})

MyEntityWithTransform:entity = entity{}
MyEntityWithTransform.AddComponents of array:
    transform_component{Entity := MyEntityWithTransform}

if (SimEntity := Entity.GetSimulationEntity[]):

Em vez de recuperar o transform_component com GetComponent e trabalhar diretamente com o transform_component, a maneira recomendada de interagir com o transform_component é por meio dos métodos de extensão de entidade. 

Transform

Você pode definir diretamente a transformação local ou global da sua entidade com os métodos de extensão de entidade SetLocalTransform ou SetGlobalTransform.

MyEntity:entity = entity{}
MyTransform:transform = transform{}

if (SimEntity := Entity.GetSimulationEntity[]):
	SimEntity.AddEntities(array{MyEntity})

# Set the local transform
MyEntity.SetLocalTransform(MyTransform)

MyOtherEntity:entity = entity{}

Esses métodos de extensão são a forma preferencial de definir a transformação em uma entidade do Scene Graph no código Verse. Esses métodos definem explicitamente a transformação local (em relação ao pai da entidade) ou global (em relação à origem do mundo) da entidade em questão. Se a entidade não tiver um transform_component quando qualquer uma dessas funções for chamada, um transform_component será criado implicitamente e adicionado à entidade. Após qualquer uma dessas chamadas de função, a entidade agora tem um transform_component. Você pode confirmar isso com uma chamada subsequente para GetComponent.

if (MyEntity.GetComponent[transform_component]):
	# success, entity has a transform_component
else:
	# failure, entity does not have a transform_component

Usando métodos de extensão, você pode obter a transformação local ou a transformação global do transform_component associado de uma entidade. GetLocalTransform retorna a transformação de uma entidade em relação a sua entidade pai ou campo de origem especificado, se estiver definido. Se a entidade não tiver um transform_component, essa função retornará a transformação de identidade.

# Entity object
MyEntity:entity = entity{}

if (SimEntity := Entity.GetSimulationEntity[]):
	SimEntity.AddEntities(array{MyEntity})

# Obtain the local transform with respect to Parent or Origin (if set)
EntityLocalTransform := MyEntity.GetLocalTransform() # no transform component, returns identity

MyOtherEntity:entity = entity{}

GetGlobalTransform retorna a transformação de uma entidade em relação à origem do mundo. Se a entidade não tiver um transform_component, essa função retornará a transformação global do anterior mais próximo com um transform_component.

# Entity object
MyEntity:entity

if (SimEntity := Entity.GetSimulationEntity[]):
	SimEntity.AddEntities(array{MyEntity})

# Obtain the global transform
EntityGlobalTransform := MyEntity.GetGlobalTransform() # returns global transform of Simulation Entity

Origem

Você também pode usar métodos de extensão de entidade para operações que envolvem o campo Origem do transform_component. Você pode definir diretamente o campo Origem do transform_component da sua entidade com o método de extensão de entidade SetOrigin. 

MyEntity:entity = entity{}
MyOtherEntity:entity = entity{}

if (SimEntity := Entity.GetSimulationEntity[]):
	SimEntity.AddEntities(array{MyEntity, MyOtherEntity})

MyEntity.SetLocalTransform(transform{Translation := vector3{Left := 100.0}})

# Construct an entity_origin object and set the new origin of MyEntity to MyOtherEntity
NewOrigin:entity_origin = entity_origin{Entity := MyOtherEntity}

Para obter a origem de uma entidade no código Verse, use GetOrigin.

MyEntity:entity = entity{}

if (SimEntity := Entity.GetSimulationEntity[]):
	SimEntity.AddEntities(array{MyEntity})

if (OriginValue := MyEntity.GetOrigin[]):
	# should not succeed
else:
	# should fail, no transform_component on entity MyEntity

GetOrigin decide se uma entidade tem seu campo Origem definido e, se tiver, retorna o valor desse campo. Caso contrário, a chamada falhará. Em caso de sucesso, o tipo de retorno de GetOrigin é um objeto de origem, uma classe do Verse que implementa a interface de origem. Essa interface fornece uma única função GetTransform para obter a transformação da origem especificada da entidade. Você também pode verificar se o campo alternativo Origem está definido como uma entidade e determinar qual entidade está definida como a origem da sua entidade.

if:
	OriginValue := MyOtherEntity.GetOrigin[]		# get Origin object
	OriginEntityCast := entity_origin[OriginValue]		# cast to entity_origin
then:
	# Obtain the entity that is set as MyOtherEntity's Origin field on its transform_component
	MyOtherEntityOrigin := OriginEntityCast.Entity
	# Obtain the origin's transform
	TransformOfOrigin := OriginEntityCast.GetTransform()

Finalmente, você pode restaurar o campo Origem do transform_component de uma entidade com ResetOrigin.

MyEntity.ResetOrigin()

Depois de chamar ResetOrigin, o campo Origem do transform_component de MyEntity é restaurado, e a transformação de MyEntity agora é calculada em relação à entidade pai de MyEntity na hierarquia do Scene Graph.

Componentes Dependentes

Alguns outros componentes do Scene Graph dependem do transform_component para funcionar. Esses incluem:

• light_component e suas classes filhas

• mesh_component

• particle_system_component

Se você adicionar qualquer um desses componentes a uma entidade do Scene Graph que ainda não tem um transform_component, o transform_component será adicionado à entidade por padrão.

Nota sobre transformações XYZ

As transformações usando o sistema de coordenadas XYZ ainda existem no módulo Verse/UnrealEngine.com/Temporary/SpatialMath. Essas transformações ainda são usadas por dispositivos e adereços do Modo Criativo no módulo Verse/Fortnite.com. Para obter mais informações sobre o status dessas transformações e a conversão entre diferentes tipos de transformação em Verse, consulte a página Sistema de coordenadas Left-Up-Forward.