Radient: normalize transforms on update

Author: TheMostDiligent

Radient/include/Math/RadientMath.hpp

@@ -182,8 +182,34 @@ inline RadientQuaternion ToRadientQuaternion(const QuaternionF& Value)
     return RadientQuaternion{Q.q.x, Q.q.y, Q.q.z, Q.q.w};
 }
 
+inline RadientTransform NormalizeTransform(const RadientTransform& Transform)
+{
+    RadientQuaternion Rotation = Transform.Rotation;
+
+    const float LengthSq = Rotation.x * Rotation.x + Rotation.y * Rotation.y + Rotation.z * Rotation.z + Rotation.w * Rotation.w;
+    if (LengthSq > 0.f)
+    {
+        const float InvLength = 1.f / std::sqrt(LengthSq);
+        Rotation.x *= InvLength;
+        Rotation.y *= InvLength;
+        Rotation.z *= InvLength;
+        Rotation.w *= InvLength;
+    }
+    else
+    {
+        Rotation = {};
+    }
+
+    return {
+        Transform.Position,
+        Rotation,
+        Transform.Scale,
+    };
+}
+
 inline RadientMatrix4x4 TransformToMatrix(const RadientTransform& Transform)
 {
+    // Rotation is expected to be normalized when the transform is stored.
     const float sx = Transform.Scale.x;
     const float sy = Transform.Scale.y;
     const float sz = Transform.Scale.z;
@@ -192,12 +218,10 @@ inline RadientMatrix4x4 TransformToMatrix(const RadientTransform& Transform)
     const float ty = Transform.Position.y;
     const float tz = Transform.Position.z;
 
-    const QuaternionF Q = ToQuaternion(Transform.Rotation);
-
-    const float x = Q.q.x;
-    const float y = Q.q.y;
-    const float z = Q.q.z;
-    const float w = Q.q.w;
+    const float x = Transform.Rotation.x;
+    const float y = Transform.Rotation.y;
+    const float z = Transform.Rotation.z;
+    const float w = Transform.Rotation.w;
 
     const float sx2 = sx + sx;
     const float sy2 = sy + sy;

Radient/src/Scene/RadientSceneState.cpp

@@ -412,13 +412,14 @@ RADIENT_STATUS RadientSceneState::CreateEntity(const RadientEntityDesc& Desc, Ra
         m_NextEntityID == std::numeric_limits<RadientEntityID>::max())
         return RADIENT_STATUS_INVALID_OPERATION;
 
-    Entity               = m_NextEntityID++;
-    const entt::entity E = m_Registry.create();
+    Entity                                = m_NextEntityID++;
+    const entt::entity     E              = m_Registry.create();
+    const RadientTransform LocalTransform = RadientMath::NormalizeTransform(Desc.Transform);
 
     m_Registry.emplace<EntityComponent>(E, EntityComponent{Entity, Desc.Name != nullptr ? Desc.Name : ""});
     m_Registry.emplace<EntityStateComponent>(E, EntityStateComponent{Desc.Flags});
     m_Registry.emplace<HierarchyComponent>(E);
-    m_Registry.emplace<LocalTransformComponent>(E, LocalTransformComponent{Desc.Transform});
+    m_Registry.emplace<LocalTransformComponent>(E, LocalTransformComponent{LocalTransform});
     m_Registry.emplace<WorldTransformComponent>(E);
     m_Registry.emplace<EffectiveVisibilityComponent>(E);
     m_Registry.emplace<RenderableMeshStateComponent>(E);
@@ -557,11 +558,12 @@ RADIENT_STATUS RadientSceneState::SetLocalTransform(RadientEntityID Entity, cons
     if (E == entt::null)
         return RADIENT_STATUS_NOT_FOUND;
 
-    LocalTransformComponent& LocalTransform = m_Registry.get<LocalTransformComponent>(E);
-    if (LocalTransform.Transform == Transform)
+    const RadientTransform   NormalizedTransform = RadientMath::NormalizeTransform(Transform);
+    LocalTransformComponent& LocalTransform      = m_Registry.get<LocalTransformComponent>(E);
+    if (LocalTransform.Transform == NormalizedTransform)
         return RADIENT_STATUS_NO_CHANGE;
 
-    LocalTransform.Transform = Transform;
+    LocalTransform.Transform = NormalizedTransform;
     MarkDirty(E, DIRTY_FLAG_TRANSFORM);
     Touch(CHANGE_FLAG_TRANSFORMS);
     return RADIENT_STATUS_OK;

Tests/RadientTest/src/RadientMathTest.cpp

@@ -29,6 +29,8 @@
 
 #include "Math/RadientMath.hpp"
 
+#include <cmath>
+
 using namespace Diligent;
 using namespace Diligent::Testing;
 
@@ -133,6 +135,55 @@ TEST(RadientMathTest, ToQuaternion)
     EXPECT_EQ(NormalizedQuat.q.w, 1.f);
 }
 
+TEST(RadientMathTest, NormalizeTransformNormalizesRotation)
+{
+    RadientTransform Transform;
+    Transform.Position = {1.f, 2.f, 3.f};
+    Transform.Rotation = {1.f, 2.f, 3.f, 4.f};
+    Transform.Scale    = {5.f, 6.f, 7.f};
+
+    const RadientTransform NormalizedTransform = RadientMath::NormalizeTransform(Transform);
+    const float            InvLength           = 1.f / std::sqrt(30.f);
+
+    EXPECT_EQ(NormalizedTransform.Position, Transform.Position);
+    EXPECT_NEAR(NormalizedTransform.Rotation.x, Transform.Rotation.x * InvLength, EPSILON);
+    EXPECT_NEAR(NormalizedTransform.Rotation.y, Transform.Rotation.y * InvLength, EPSILON);
+    EXPECT_NEAR(NormalizedTransform.Rotation.z, Transform.Rotation.z * InvLength, EPSILON);
+    EXPECT_NEAR(NormalizedTransform.Rotation.w, Transform.Rotation.w * InvLength, EPSILON);
+    EXPECT_EQ(NormalizedTransform.Scale, Transform.Scale);
+}
+
+TEST(RadientMathTest, NormalizeTransformKeepsUnitRotation)
+{
+    RadientTransform Transform;
+    Transform.Position = {-1.f, -2.f, -3.f};
+    Transform.Rotation = {0.f, 0.f, 0.6f, 0.8f};
+    Transform.Scale    = {0.5f, 1.5f, 2.5f};
+
+    const RadientTransform NormalizedTransform = RadientMath::NormalizeTransform(Transform);
+
+    EXPECT_EQ(NormalizedTransform.Position, Transform.Position);
+    EXPECT_NEAR(NormalizedTransform.Rotation.x, Transform.Rotation.x, EPSILON);
+    EXPECT_NEAR(NormalizedTransform.Rotation.y, Transform.Rotation.y, EPSILON);
+    EXPECT_NEAR(NormalizedTransform.Rotation.z, Transform.Rotation.z, EPSILON);
+    EXPECT_NEAR(NormalizedTransform.Rotation.w, Transform.Rotation.w, EPSILON);
+    EXPECT_EQ(NormalizedTransform.Scale, Transform.Scale);
+}
+
+TEST(RadientMathTest, NormalizeTransformTreatsZeroRotationAsIdentity)
+{
+    RadientTransform Transform;
+    Transform.Position = {8.f, 9.f, 10.f};
+    Transform.Rotation = {0.f, 0.f, 0.f, 0.f};
+    Transform.Scale    = {2.f, 3.f, 4.f};
+
+    const RadientTransform NormalizedTransform = RadientMath::NormalizeTransform(Transform);
+
+    EXPECT_EQ(NormalizedTransform.Position, Transform.Position);
+    EXPECT_EQ(NormalizedTransform.Rotation, RadientQuaternion{});
+    EXPECT_EQ(NormalizedTransform.Scale, Transform.Scale);
+}
+
 TEST(RadientMathTest, RoundTripsMatrixType)
 {
     // Matrix layout conversion should be lossless in both directions.

Tests/RadientTest/src/RadientSceneStateTest.cpp

@@ -62,6 +62,22 @@ void ExpectTransformEq(const RadientTransform& Transform, const RadientTransform
     EXPECT_EQ(Transform.Scale.z, Reference.Scale.z);
 }
 
+void ExpectTransformNear(const RadientTransform& Transform, const RadientTransform& Reference)
+{
+    EXPECT_NEAR(Transform.Position.x, Reference.Position.x, EPSILON);
+    EXPECT_NEAR(Transform.Position.y, Reference.Position.y, EPSILON);
+    EXPECT_NEAR(Transform.Position.z, Reference.Position.z, EPSILON);
+
+    EXPECT_NEAR(Transform.Rotation.x, Reference.Rotation.x, EPSILON);
+    EXPECT_NEAR(Transform.Rotation.y, Reference.Rotation.y, EPSILON);
+    EXPECT_NEAR(Transform.Rotation.z, Reference.Rotation.z, EPSILON);
+    EXPECT_NEAR(Transform.Rotation.w, Reference.Rotation.w, EPSILON);
+
+    EXPECT_NEAR(Transform.Scale.x, Reference.Scale.x, EPSILON);
+    EXPECT_NEAR(Transform.Scale.y, Reference.Scale.y, EPSILON);
+    EXPECT_NEAR(Transform.Scale.z, Reference.Scale.z, EPSILON);
+}
+
 void ExpectMatrixNear(const RadientMatrix4x4& Matrix, const RadientMatrix4x4& Reference)
 {
     for (Uint32 i = 0; i < 16; ++i)
@@ -1143,41 +1159,50 @@ TEST(RadientSceneStateTest, GetLocalTransform)
     EXPECT_EQ(State.GetLocalTransform(Entity, Transform), RADIENT_STATUS_OK);
     ExpectTransformEq(Transform, RadientTransform{});
 
-    // Creation with an initial transform should preserve the exact TRS values.
+    // Creation with an initial transform should normalize rotation once before
+    // storing local TRS values.
     RadientTransform InitialTransform;
     InitialTransform.Position   = {1.f, 2.f, 3.f};
-    InitialTransform.Rotation.z = 0.70710678f;
-    InitialTransform.Rotation.w = 0.70710678f;
+    InitialTransform.Rotation.z = 2.f;
+    InitialTransform.Rotation.w = 2.f;
     InitialTransform.Scale      = {2.f, 3.f, 4.f};
 
+    RadientTransform ExpectedInitialTransform = InitialTransform;
+    ExpectedInitialTransform.Rotation.z       = 0.70710678f;
+    ExpectedInitialTransform.Rotation.w       = 0.70710678f;
+
     RadientEntityDesc EntityDesc;
     EntityDesc.Transform = InitialTransform;
 
     RadientEntityID TransformedEntity = InvalidRadientEntityID;
     EXPECT_EQ(State.CreateEntity(EntityDesc, TransformedEntity), RADIENT_STATUS_OK);
     EXPECT_EQ(State.GetLocalTransform(TransformedEntity, Transform), RADIENT_STATUS_OK);
-    ExpectTransformEq(Transform, InitialTransform);
+    ExpectTransformNear(Transform, ExpectedInitialTransform);
 
     RadientTransform UpdatedTransform;
     UpdatedTransform.Position   = {4.f, 5.f, 6.f};
-    UpdatedTransform.Rotation.x = 0.70710678f;
-    UpdatedTransform.Rotation.w = 0.70710678f;
+    UpdatedTransform.Rotation.x = 2.f;
+    UpdatedTransform.Rotation.w = 2.f;
     UpdatedTransform.Scale      = {5.f, 6.f, 7.f};
 
+    RadientTransform ExpectedUpdatedTransform = UpdatedTransform;
+    ExpectedUpdatedTransform.Rotation.x       = 0.70710678f;
+    ExpectedUpdatedTransform.Rotation.w       = 0.70710678f;
+
     EXPECT_EQ(State.SetLocalTransform(TransformedEntity, UpdatedTransform), RADIENT_STATUS_OK);
     EXPECT_EQ(State.GetLocalTransform(TransformedEntity, Transform), RADIENT_STATUS_OK);
-    ExpectTransformEq(Transform, UpdatedTransform);
+    ExpectTransformNear(Transform, ExpectedUpdatedTransform);
 
-    // Setting the same transform again should report no change.
+    // Setting an equivalent non-unit transform again should report no change.
     EXPECT_EQ(State.SetLocalTransform(TransformedEntity, UpdatedTransform), RADIENT_STATUS_NO_CHANGE);
     EXPECT_EQ(State.GetLocalTransform(TransformedEntity, Transform), RADIENT_STATUS_OK);
-    ExpectTransformEq(Transform, UpdatedTransform);
+    ExpectTransformNear(Transform, ExpectedUpdatedTransform);
 
     EXPECT_EQ(State.GetLocalTransform(Entity, Transform), RADIENT_STATUS_OK);
     ExpectTransformEq(Transform, RadientTransform{});
 
     EXPECT_EQ(State.DestroyEntity(TransformedEntity), RADIENT_STATUS_OK);
-    Transform = UpdatedTransform;
+    Transform = ExpectedUpdatedTransform;
     // Destroyed entities should report not found and reset output transform.
     EXPECT_EQ(State.GetLocalTransform(TransformedEntity, Transform), RADIENT_STATUS_NOT_FOUND);
     ExpectTransformEq(Transform, RadientTransform{});