Transformations dans Scene Graph

La transformation d’une entité de Scene Graph définit la translation (localisation), la rotation (orientation), et l’échelle (taille) d’une entité. Pour transformer une entité de Scene Graph, l'entité doit avoir un composant transform_component. Le composant transform_component contient deux champs que vous pouvez manipuler via le code UEFN ou Verse :

• Origine : une origine facultative à partir de laquelle la transformation locale est calculée.

• LocalTransform : une transformation (/Verse.org/SpatialMath:)transform relative au parent de l’entité, ou à l'origine si le champ facultatif Origine est défini.  

L'origine d'une entité est l'entité à partir de laquelle la LocalTransform du composant transform_component d'une entité est calculée. Il s’agit de la valeur du champ Origine si le champ Origine du composant transform_component est défini, ou du parent de l’entité dans la hiérarchie de Scene Graph si le champ Origine n’est pas défini.

Il est important de faire la distinction entre une transformation et le composant transform_component. Une transformation est un type de données composite défini dans le module /Verse.org/SpatialMath qui stocke les quantités suivantes dans le système de coordonnées Gauche-Haut-Avant (LUF) :

• Translation (vector3) : L'emplacement d'un objet.

• Rotation (rotation) : L'orientation de l'objet.

• Échelle (vector3) : La taille de l'objet.

Le composant transform_component est une classe Verse définie dans le module /Verse.org/SceneGraph qui stocke la LocalTransform d'une entité de Scene Graph et, éventuellement, une origine alternative. On peut considérer le composant transform_component comme un conteneur fourni à une entité pour une transformation servant à définir sa position dans la simulation.

Transformations Verse 

Scene Graph utilise les transformations du module /Verse.org/SpatialMath . Les transformations du module Verse utilisent le système de coordonnées LUF droitier. Pour construire une transformation Verse, vous pouvez utiliser l'archétype de classe et les méthodes intégrées pour créer des rotations.

# 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}

Pour plus d'informations sur le système de coordonnées dans l'UEFN, consultez la page Système de coordonnées gauche-haut-avant. Elle comprend également des informations sur la conversion entre la transformation XYZ dans le module /UnrealEngine.com/Temporary/SpatialMath et la transformation du module Verse.

Construire une entité avec un composant transform_component  

Vous pouvez construire une Entité dans l'organiseur UEFN ou via Verse. 

Dans l’UEFN

Vous pouvez ajouter rapidement une entité de Scene Graph à votre projet via le menu Placer des acteurs.

Lorsque vous ajoutez une entité de Scene Graph à votre projet via le menu Placer des acteurs, l'entité est dotée d'un composant transform_component par défaut.

Si vous le souhaitez, vous pouvez supprimer le composant transform_component en accédant à votre entité récemment placée dans le panneau Organiseur, en recherchant le composant transform_component et en sélectionnant Supprimer le composant.

Vous pouvez voir ci-dessous que l'entité en question n'a plus de composant transform_component.

dans Verse

Lorsque vous créez une entité de Scene Graph via le code Verse avec l'archétype de classe :

MyEntity:entity = entity{}

L'entité n'est pas dotée d'un composant transform_component. Au lieu de cela, un composant transform_component doit être ajouté à votre entité. Les méthodes préférées pour travailler avec les transformations sont SetLocalTransform et SetGlobalTransform. Ces fonctions gèrent la création du composant transform_component, la définition des valeurs et l'ajout du composant de transformation à l'entité en même temps.

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)

Vous pouvez également ajouter le composant directement avec 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}

D'autres méthodes permettant d'ajouter un composant transform_component à une entité de Scene Graph via un code Verse sont présentées dans la section Utiliser le composant transform_component dans Verse.

 Comment la transformation d’une entité est-elle calculée ?

L'opération la plus importante que vous pouvez effectuer sur une entité de Scene Graph avec le composant transform_component consiste à obtenir ou à définir la transformation d'une entité.

Il existe deux types de transformation qui pourraient vous intéresser : la transformation locale et la transformation globale. Pour manipuler efficacement la transformation d’une entité, il est important de comprendre comment ces transformations sont calculées.

La transformation locale est la transformation par rapport à l'origine d'une entité. La transformation locale de toute entité de Scene Graph est la valeur du champ LocalTransform du composant transform_component d'une entité de Scene Graph.

La transformation globale est la transformation par rapport à l'origine du système de coordonnées LUF dans l'espace global. La transformation globale d'une entité de Scene Graph est calculée en composant la LocalTransform d'une Entité avec :

• La transformation globale du parent de l'entité si le champ Origine n'est pas défini sur le composant transform_component de l'entité, ou

• La transformation globale de l’origine de l’entité si le champ Origine est défini sur le composant transform_component de l’entité.

Ce qui suit illustre cet exemple en utilisant une translation sans rotation ni mise à l’échelle, de sorte que les transformations résultantes puissent être calculées en additionnant les translations. Puisque cet exemple suppose que la rotation et la mise à l’échelle restent leurs identités respectives dans toutes les transformations, une forme abrégée est utilisée pour désigner la transformation d’une entité par son vecteur de translation.

Considérez trois entités de Scene Graph organisées comme suit :

• BaseEntity : LocalTransform (0,0, 0,0, 0,0) dans le système de coordonnées LUF.

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

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

Vous trouverez ci-dessous les trois entités d'une scène où BaseEntity n'a pas de mesh_component, A est un cube et B est un cône :

Par exemple, supposons que vous souhaitiez déterminer à la fois la transformation locale et la transformation globale de l’entité B. La transformation locale est facile à visualiser : il s’agit de la valeur du champ LocalTransform du composant transform_component de l’entité B, comme indiqué ci-dessous :

La transformée locale de l'entité B est (-250,0, 100,0, 0,0).

Afin de calculer la transformation globale de l'entité B, vous devez tracer la hiérarchie de l'entité B jusqu'à l’entité de simulation et composer les transformations, de l’entité de simulation jusqu'à l'entité B. L’entité de simulation est la racine de la simulation actuelle sous laquelle toutes les autres entités de simulation sont des enfants.

Voici les étapes à suivre pour calculer la transformation globale de l'entité B :

1. L'entité de simulation est la racine de la simulation actuelle.

   • Transformation globale de l'entité de simulation : (0,0, 0,0, 0,0).

2. La BaseEntity est un enfant de l'entité de simulation. La BaseEntity a une transformation locale de (0,0, 0,0, 0,0) comme indiqué dans l’image 1.0. La composition de la transformation globale de l’entité de simulation avec la transformation locale de la BaseEntity donne :

   • Transformation globale de BaseEntity : (0,0, 0,0, 0,0) + (0,0, 0,0, 0,0) = (0,0, 0,0, 0,0).

3. L'entité A est un enfant de BaseEntity. L'Entité A a une transformation locale de (750,0, 100,0, 0,0) comme indiqué dans l'image 1.1. La composition de la transformation globale de BaseEntity avec la transformation de localisation de l'entité A donne :

   • Transformation globale de l’entité A : (0,0, 0,0, 0,0) + (750,0, 100,0, 0,0) = (750,0, 100,0, 0,0).

4. L'entité B est un enfant de l'entité A. L’entité B a une transformation locale de (-250,0, 100,0, 0,0) comme indiqué dans l'image 1.2. La composition de la transformation globale de l’entité A avec la transformation de localisation de l'entité B donne :

   • Transformation globale de l'entité B : (750,0, 100,0, 0,0) + (-250,0, 100,0, 0,0) = (500,0, 200,0, 0,0).

Par conséquent, la transformation globale de l'entité B est (500,0, 200,0, 0,0) dans le système de coordonnées LUF.

Utiliser le composant transform_component dans l'éditeur 

En utilisant LocalTransform et Origin, vous pouvez manipuler la transformation d'une entité. 

Transformation locale

Le champ LocalTransformdu composant transform_component d'une entité est la transformation (/Verse.org/SpatialMath:)transform d'une entité par rapport à son origine. Si le champ Origine n’est pas explicitement défini, l’origine d’une entité est par défaut son parent dans la hiérarchie de Scene Graph. Le champ LocalTransform est un champ modifiable qui apparaît dans l’UEFN et qui vous permet de modifier directement une entité :

1. Translation : Emplacement par rapport à son parent ou à son origine définie manuellement.

   • Modifiez la translation d'une entité pour la déplacer dans le niveau.

2. Rotation : Orientation par rapport à son parent ou à son origine définie manuellement.

   • Modifiez la rotation d'une entité pour la faire pivoter autour du point de pivot de l'entité.

3. Échelle : Taille par rapport à son parent ou à son origine définie manuellement.

   • Modifiez l'échelle d'une entité pour la rendre plus grande ou plus petite.

À l'origine

L'origine du composant transform_component d'une entité est l'objet par rapport auquel la transformation locale est calculée. Ce champ du composant transform_component est facultatif. Par défaut, la transformation locale du composant transform_component est la transformation de l'entité basée sur l'origine de l'entité, calculée par rapport à l’entité parent de l'entité propriétaire. Vous pouvez éventuellement définir le champ Origine du composant transform_component d’une entité afin de calculer la LocalTransform par rapport à un objet autre que le parent de l’entité.

Par exemple, vous pouvez assigner à l’origine d’une entité une autre entité comme référence. Vous pouvez définir dans ce champ n'importe quelle classe qui implémente l'interface d'origine Verse. En particulier, pour définir dans le champ Origine une autre entité de Scene Graph, choisissez la classe entity_origin, puis sélectionnez l'entité que vous souhaitez définir comme nouvelle origine.

Ce qui suit présente un exemple de fonctionnement pratique du champ Origine et de LocalTransform. Considérez une BaseEntity située à l'origine de l'espace du monde avec l'entité enfant A représentée par le cube mesh_component et l'entité enfant B représentée par le cône mesh_component.

Comme on peut le voir dans l'image ci-dessus, BaseEntity se trouve à l'origine de l'espace du monde puisque son champ Origine n’est pas défini dans le composant transform_component et la LocalTransform est définie sur l'origine de l'espace du monde.

Comme illustré ci-dessous, vous pouvez voir que le champ Origine de l’entité A n’est pas défini non plus, donc la LocalTransform est calculée par rapport au composant transform_component de son parent, BaseEntity.

Étant donné que BaseEntity se trouve à l'origine de l'espace du monde et que la translation de la LocalTransform de l'entité A est définie sur vector3{Left := 750.0, Up := 100.0, Forward := 0.0}, l'entité A se trouve à vector3{Left := 750.0, Up := 100.0, Forward := 0.0}. La rotation et l'échelle de l'entité A restent inchangées puisque la rotation et l'échelle de la LocalTransform sur la BaseEntity sont les identités respectives.

Dans l'image ci-dessous, vous pouvez voir que l'entité B, qui est également un enfant de BaseEntity, a son champ Origine sur son composant transform_component défini comme entité A.

Par conséquent, le champ LocalTransform de l'entité B sur son composant transform_component est relatif à la transformation calculée de l'entité A. Étant donné que la LocalTransform de l'entité B est définie sur vector3{Left := -250.0, Up := 100.0, Forward := 0.0} et que la LocalTransform de l'entité A est définie sur vector3{Left := 750.0, Up := 100.0, Forward := 0.0}, la transformation globale de l'entité B est vector3{Left := 500.0, Up := 200.0, Forward := 0.0}.

Si vous modifiez le composant Rotation du champ LocalTransform du composant transform_component de l'entité A à -90,0 degrés autour de l'axe avant, l'entité B pivote également de -90,0 degrés autour de l'axe avant. Cela est dû au fait que la rotation d'un enfant est également héritée du parent.

Utiliser le composant transform_component dans Verse

  Vous pouvez vérifier si une entité possède un composant transform_component avec 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[]):

Au lieu de récupérer le composant transform_component avec GetComponent et de travailler directement avec celui-ci, il est recommandé d'interagir avec le transform_component via les méthodes d'extension d'entité. 

Transform

Vous pouvez définir directement la transformation locale ou globale de votre Entité avec les méthodes d’extension d’entité 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{}

Ces méthodes d’extension sont le moyen recommandé pour définir la transformation d’une entité de Scene Graph dans le code Verse. Ces méthodes définissent explicitement la transformation locale (par rapport au parent de l’entité) ou globale (par rapport à l’origine du monde) de l’entité en question. Si l'entité n'a pas de transform_component lorsque l'une de ces fonctions est appelée, un transform_component est implicitement créé et ajouté à l'entité. Après l’un ou l’autre de ces appels de fonction, l’entité dispose désormais d’un transform_component. Vous pouvez confirmer cela en faisant un appel ultérieur à GetComponent.

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

À l’aide de méthodes d’extension, vous pouvez obtenir la transformation locale ou globale du composant transform_component associé à une entité. GetLocalTransform renvoie la transformation d'une entité par rapport à son entité parent ou au champ Origine spécifié, s'il est défini. Si l'entité n'a pas de transform_component, cette fonction renvoie la transformation de l'identité.

# 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 renvoie la transformation d'une entité par rapport à l'origine du monde. Si l'entité n'a pas de transform_component, cette fonction renvoie la transformation globale de l'ancêtre le plus proche avec un 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

À l'origine

Vous pouvez également utiliser des méthodes d'extension d'entité pour les opérations impliquant le champ Origine du composant transform_component. Vous pouvez définir directement le champ Origine du composant transform_component de votre entité avec la méthode d’extension d’entité 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}

Pour obtenir l'origine d'une entité dans le code Verse, utilisez 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 détermine si le champ Origine d’une entité est défini et, si c'est le cas, renvoie la valeur de ce champ. Sinon, l’appel échoue. En cas de succès, le type de retour de GetOrigin est un objet d'origine, une classe Verse qui implémente l'interface d'origine. Cette interface fournit une fonction unique GetTransform pour obtenir la transformation de l'origine spécifiée de l'entité. Vous pouvez également vérifier si le champ Origine alternatif est défini sur une entité et déterminer quelle entité est définie comme origine de votre entité.

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()

Enfin, vous pouvez réinitialiser le champ Origine du composant transform_component d'une entité avec ResetOrigin.

MyEntity.ResetOrigin()

Après avoir appelé ResetOrigin, le champ Origine du composant transform_component de MyEntity est réinitialisé et la transformation de MyEntity est désormais calculée par rapport à l'entité parent de MyEntity dans la hiérarchie de Scene Graph.

Composants dépendants

Le fonctionnement de certains autres composants de Scene Graph dépend du composant transform_component. Ces types de ressources sont les suivants :

• light_component et ses classes enfants

• mesh_component

• particle_system_component

Si vous ajoutez l'un de ces composants à une entité de Scene Graph qui ne possède pas déjà de transform_component, le transform_component est ajouté à l'entité par défaut.

Remarque sur les transformations XYZ

Les transformations utilisant le système de coordonnées XYZ existent toujours dans le module Verse /UnrealEngine.com/Temporary/SpatialMath . Ces transformations sont toujours utilisées par les appareils et accessoires du mode Créatif dans le module verse /Fortnite.com  . Pour plus d'informations sur l'état de ces transformations et la conversion entre différents types de transformations dans Verse, consultez la page Système de coordonnées gauche-haut-avant.