Struct GlobalTransform 

pub struct GlobalTransform { /* private fields */ }

A world-space transformation component.

This component caches the computed world-space transformation matrix for entities in a hierarchy. It is computed by the transform propagation system based on the entity’s local Transform and its parent’s GlobalTransform.

When to Use

• Use Transform for setting local position/rotation/scale
• Use GlobalTransform for reading world-space values (rendering, physics)

Do Not Modify Directly

This component is managed by the transform propagation system. Modifying it directly will cause desynchronization with the entity hierarchy.

Example

use goud_engine::ecs::components::{Transform, GlobalTransform};
use goud_engine::core::math::Vec3;

// For root entities, global equals local
let transform = Transform::from_position(Vec3::new(10.0, 5.0, 0.0));
let global = GlobalTransform::from(transform);

let position = global.translation();
assert!((position - Vec3::new(10.0, 5.0, 0.0)).length() < 0.001);

Implementations

impl GlobalTransform

pub const IDENTITY: GlobalTransform

Identity global transform (no transformation).

pub const fn from_matrix(matrix: Matrix4<f32>) -> GlobalTransform

Creates a GlobalTransform from a 4x4 transformation matrix.

Arguments

• matrix - The world-space transformation matrix

Example

use goud_engine::ecs::components::GlobalTransform;
use cgmath::Matrix4;

let matrix = Matrix4::from_translation(cgmath::Vector3::new(10.0, 0.0, 0.0));
let global = GlobalTransform::from_matrix(matrix);

pub fn from_translation(translation: Vec3) -> GlobalTransform

Creates a GlobalTransform from translation only.

Arguments

• translation - World-space position

Example

use goud_engine::ecs::components::GlobalTransform;
use goud_engine::core::math::Vec3;

let global = GlobalTransform::from_translation(Vec3::new(10.0, 5.0, 0.0));

pub fn from_translation_rotation_scale( translation: Vec3, rotation: Quat, scale: Vec3, ) -> GlobalTransform

Creates a GlobalTransform from translation, rotation, and scale.

Arguments

• translation - World-space position
• rotation - World-space rotation as quaternion
• scale - World-space scale

Example

use goud_engine::ecs::components::GlobalTransform;
use goud_engine::ecs::components::transform::Quat;
use goud_engine::core::math::Vec3;

let global = GlobalTransform::from_translation_rotation_scale(
    Vec3::new(10.0, 0.0, 0.0),
    Quat::IDENTITY,
    Vec3::one(),
);

pub fn matrix(&self) -> Matrix4<f32>

Returns the underlying 4x4 transformation matrix.

This matrix is column-major and can be used directly for rendering.

Example

use goud_engine::ecs::components::GlobalTransform;

let global = GlobalTransform::IDENTITY;
let matrix = global.matrix();

pub fn matrix_ref(&self) -> &Matrix4<f32>

Returns a reference to the underlying matrix.

pub fn to_cols_array(&self) -> [f32; 16]

Returns the matrix as a flat column-major array.

This is useful for FFI and sending to GPU shaders.

Example

use goud_engine::ecs::components::GlobalTransform;

let global = GlobalTransform::IDENTITY;
let cols: [f32; 16] = global.to_cols_array();

// First column (x-axis)
assert_eq!(cols[0], 1.0); // m00

pub fn to_rows_array(&self) -> [f32; 16]

Returns the matrix as a flat row-major array.

Some APIs expect row-major ordering.

impl GlobalTransform

pub fn translation(&self) -> Vec3

Extracts the translation (position) component.

This is the fourth column of the matrix.

Example

use goud_engine::ecs::components::GlobalTransform;
use goud_engine::core::math::Vec3;

let global = GlobalTransform::from_translation(Vec3::new(10.0, 5.0, 3.0));
let pos = global.translation();

assert!((pos.x - 10.0).abs() < 0.001);

pub fn scale(&self) -> Vec3

Extracts the scale component.

This is computed from the lengths of the first three column vectors. Note: This does not handle negative scales correctly.

Example

use goud_engine::ecs::components::GlobalTransform;
use goud_engine::ecs::components::transform::Quat;
use goud_engine::core::math::Vec3;

let global = GlobalTransform::from_translation_rotation_scale(
    Vec3::zero(),
    Quat::IDENTITY,
    Vec3::new(2.0, 3.0, 4.0),
);

let scale = global.scale();
assert!((scale.x - 2.0).abs() < 0.001);

pub fn rotation(&self) -> Quat

Extracts the rotation component as a quaternion.

This removes scale from the rotation matrix, then converts to quaternion. Note: This may have issues with non-uniform scales or negative scales.

Example

use goud_engine::ecs::components::GlobalTransform;
use goud_engine::ecs::components::transform::Quat;
use goud_engine::core::math::Vec3;
use std::f32::consts::PI;

let rotation = Quat::from_axis_angle(Vec3::unit_y(), PI / 4.0);
let global = GlobalTransform::from_translation_rotation_scale(
    Vec3::zero(),
    rotation,
    Vec3::one(),
);

let extracted = global.rotation();
// Quaternion comparison (accounting for sign flip equivalence)
let dot = rotation.x * extracted.x + rotation.y * extracted.y
        + rotation.z * extracted.z + rotation.w * extracted.w;
assert!(dot.abs() > 0.999);

pub fn decompose(&self) -> (Vec3, Quat, Vec3)

Decomposes the transform into translation, rotation, and scale.

Returns (translation, rotation, scale).

Example

use goud_engine::ecs::components::GlobalTransform;
use goud_engine::ecs::components::transform::Quat;
use goud_engine::core::math::Vec3;

let global = GlobalTransform::from_translation_rotation_scale(
    Vec3::new(10.0, 5.0, 3.0),
    Quat::IDENTITY,
    Vec3::new(2.0, 2.0, 2.0),
);

let (translation, rotation, scale) = global.decompose();
assert!((translation.x - 10.0).abs() < 0.001);
assert!((scale.x - 2.0).abs() < 0.001);

pub fn to_transform(&self) -> Transform

Converts this GlobalTransform to a local Transform.

This is useful for extracting a Transform that would produce this GlobalTransform when applied from the origin.

impl GlobalTransform

pub fn mul_transform(&self, other: &GlobalTransform) -> GlobalTransform

Multiplies this transform with another.

This combines two transformations: self * other applies self first, then other.

Example

use goud_engine::ecs::components::GlobalTransform;
use goud_engine::core::math::Vec3;

let parent = GlobalTransform::from_translation(Vec3::new(10.0, 0.0, 0.0));
let child_local = GlobalTransform::from_translation(Vec3::new(5.0, 0.0, 0.0));

let child_global = parent.mul_transform(&child_local);
let pos = child_global.translation();
assert!((pos.x - 15.0).abs() < 0.001);

pub fn transform_by(&self, local: &Transform) -> GlobalTransform

Multiplies this transform by a local Transform.

This is the primary method used by transform propagation.

Example

use goud_engine::ecs::components::{GlobalTransform, Transform};
use goud_engine::core::math::Vec3;

let parent_global = GlobalTransform::from_translation(Vec3::new(10.0, 0.0, 0.0));
let child_local = Transform::from_position(Vec3::new(5.0, 0.0, 0.0));

let child_global = parent_global.transform_by(&child_local);
let pos = child_global.translation();
assert!((pos.x - 15.0).abs() < 0.001);

pub fn transform_point(&self, point: Vec3) -> Vec3

Transforms a point from local space to world space.

Example

use goud_engine::ecs::components::GlobalTransform;
use goud_engine::core::math::Vec3;

let global = GlobalTransform::from_translation(Vec3::new(10.0, 0.0, 0.0));
let local_point = Vec3::new(5.0, 0.0, 0.0);
let world_point = global.transform_point(local_point);

assert!((world_point.x - 15.0).abs() < 0.001);

pub fn transform_direction(&self, direction: Vec3) -> Vec3

Transforms a direction from local space to world space.

Unlike points, directions are not affected by translation.

pub fn inverse(&self) -> Option<GlobalTransform>

Returns the inverse of this transform.

The inverse transforms from world space back to local space. Returns None if the matrix is not invertible (e.g., has zero scale).

pub fn forward(&self) -> Vec3

Returns the forward direction vector (negative Z in local space).

pub fn right(&self) -> Vec3

Returns the right direction vector (positive X in local space).

pub fn up(&self) -> Vec3

Returns the up direction vector (positive Y in local space).

pub fn back(&self) -> Vec3

Returns the back direction vector (positive Z in local space).

pub fn left(&self) -> Vec3

Returns the left direction vector (negative X in local space).

pub fn down(&self) -> Vec3

Returns the down direction vector (negative Y in local space).

pub fn lerp(&self, other: &GlobalTransform, t: f32) -> GlobalTransform

Linearly interpolates between two global transforms.

This decomposes both transforms, interpolates components separately (slerp for rotation), then recomposes.

Example

use goud_engine::ecs::components::GlobalTransform;
use goud_engine::core::math::Vec3;

let a = GlobalTransform::from_translation(Vec3::zero());
let b = GlobalTransform::from_translation(Vec3::new(10.0, 0.0, 0.0));

let mid = a.lerp(&b, 0.5);
let pos = mid.translation();
assert!((pos.x - 5.0).abs() < 0.001);

Trait Implementations

impl Clone for GlobalTransform

fn clone(&self) -> GlobalTransform

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GlobalTransform

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for GlobalTransform

fn default() -> GlobalTransform

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for GlobalTransform

fn deserialize<D>( deserializer: D, ) -> Result<GlobalTransform, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<&Transform> for GlobalTransform

fn from(transform: &Transform) -> GlobalTransform

Converts to this type from the input type.

impl From<Matrix4<f32>> for GlobalTransform

fn from(matrix: Matrix4<f32>) -> GlobalTransform

Converts to this type from the input type.

impl From<Transform> for GlobalTransform

fn from(transform: Transform) -> GlobalTransform

Converts a local Transform to a GlobalTransform.

This is used for root entities where local == global.

impl Mul<&GlobalTransform> for GlobalTransform

type Output = GlobalTransform

The resulting type after applying the * operator.

fn mul(self, rhs: &GlobalTransform) -> GlobalTransform

Performs the * operation.

impl Mul<&Transform> for GlobalTransform

type Output = GlobalTransform

The resulting type after applying the * operator.

fn mul(self, rhs: &Transform) -> GlobalTransform

Performs the * operation.

impl Mul<Transform> for GlobalTransform

type Output = GlobalTransform

The resulting type after applying the * operator.

fn mul(self, rhs: Transform) -> GlobalTransform

Performs the * operation.

impl Mul for GlobalTransform

type Output = GlobalTransform

The resulting type after applying the * operator.

fn mul(self, rhs: GlobalTransform) -> GlobalTransform

Performs the * operation.

impl PartialEq for GlobalTransform

fn eq(&self, other: &GlobalTransform) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for GlobalTransform

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Component for GlobalTransform

impl Copy for GlobalTransform

impl StructuralPartialEq for GlobalTransform