Struct bevy::transform::components::GlobalTransform

pub struct GlobalTransform(/* private fields */);

Describe the position of an entity relative to the reference frame.

• To place or move an entity, you should set its Transform.
• GlobalTransform is fully managed by bevy, you cannot mutate it, use Transform instead.
• To get the global transform of an entity, you should get its GlobalTransform.
• For transform hierarchies to work correctly, you must have both a Transform and a GlobalTransform.
  • You may use the TransformBundle to guarantee this.

Transform and GlobalTransform

Transform is the position of an entity relative to its parent position, or the reference frame if it doesn’t have a Parent.

GlobalTransform is the position of an entity relative to the reference frame.

GlobalTransform is updated from Transform by systems in the system set TransformPropagate.

This system runs during PostUpdate. If you update the Transform of an entity in this schedule or after, you will notice a 1 frame lag before the GlobalTransform is updated.

Examples

• transform

Implementations

impl GlobalTransform

pub const IDENTITY: GlobalTransform = _

An identity GlobalTransform that maps all points in space to themselves.

pub fn compute_matrix(&self) -> Mat4

Returns the 3d affine transformation matrix as a Mat4.

pub fn affine(&self) -> Affine3A

Returns the 3d affine transformation matrix as an Affine3A.

Examples found in repository

examples/2d/mesh2d_manual.rs (line 332)

pub fn extract_colored_mesh2d(
    mut commands: Commands,
    mut previous_len: Local<usize>,
    // When extracting, you must use `Extract` to mark the `SystemParam`s
    // which should be taken from the main world.
    query: Extract<
        Query<(Entity, &ViewVisibility, &GlobalTransform, &Mesh2dHandle), With<ColoredMesh2d>>,
    >,
    mut render_mesh_instances: ResMut<RenderMesh2dInstances>,
) {
    let mut values = Vec::with_capacity(*previous_len);
    for (entity, view_visibility, transform, handle) in &query {
        if !view_visibility.get() {
            continue;
        }

        let transforms = Mesh2dTransforms {
            transform: (&transform.affine()).into(),
            flags: MeshFlags::empty().bits(),
        };

        values.push((entity, ColoredMesh2d));
        render_mesh_instances.insert(
            entity,
            RenderMesh2dInstance {
                mesh_asset_id: handle.0.id(),
                transforms,
                material_bind_group_id: Material2dBindGroupId::default(),
                automatic_batching: false,
            },
        );
    }
    *previous_len = values.len();
    commands.insert_or_spawn_batch(values);
}

pub fn compute_transform(&self) -> Transform

Returns the transformation as a Transform.

The transform is expected to be non-degenerate and without shearing, or the output will be invalid.

pub fn reparented_to(&self, parent: &GlobalTransform) -> Transform

Returns the Transform self would have if it was a child of an entity with the parent GlobalTransform.

This is useful if you want to “reparent” an Entity. Say you have an entity e1 that you want to turn into a child of e2, but you want e1 to keep the same global transform, even after re-parenting. You would use:

#[derive(Component)]
struct ToReparent {
    new_parent: Entity,
}
fn reparent_system(
    mut commands: Commands,
    mut targets: Query<(&mut Transform, Entity, &GlobalTransform, &ToReparent)>,
    transforms: Query<&GlobalTransform>,
) {
    for (mut transform, entity, initial, to_reparent) in targets.iter_mut() {
        if let Ok(parent_transform) = transforms.get(to_reparent.new_parent) {
            *transform = initial.reparented_to(parent_transform);
            commands.entity(entity)
                .remove::<ToReparent>()
                .set_parent(to_reparent.new_parent);
        }
    }
}

The transform is expected to be non-degenerate and without shearing, or the output will be invalid.

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

Extracts scale, rotation and translation from self.

The transform is expected to be non-degenerate and without shearing, or the output will be invalid.

pub fn right(&self) -> Vec3

Return the local right vector (X).

pub fn left(&self) -> Vec3

Return the local left vector (-X).

pub fn up(&self) -> Vec3

Return the local up vector (Y).

Examples found in repository

examples/3d/3d_viewport_to_world.rs (line 33)

fn draw_cursor(
    camera_query: Query<(&Camera, &GlobalTransform)>,
    ground_query: Query<&GlobalTransform, With<Ground>>,
    windows: Query<&Window>,
    mut gizmos: Gizmos,
) {
    let (camera, camera_transform) = camera_query.single();
    let ground = ground_query.single();

    let Some(cursor_position) = windows.single().cursor_position() else {
        return;
    };

    // Calculate a ray pointing from the camera into the world based on the cursor's position.
    let Some(ray) = camera.viewport_to_world(camera_transform, cursor_position) else {
        return;
    };

    // Calculate if and where the ray is hitting the ground plane.
    let Some(distance) = ray.intersect_plane(ground.translation(), Plane3d::new(ground.up()))
    else {
        return;
    };
    let point = ray.get_point(distance);

    // Draw a circle just above the ground plane at that position.
    gizmos.circle(
        point + ground.up() * 0.01,
        Direction3d::new_unchecked(ground.up()), // Up vector is already normalized.
        0.2,
        Color::WHITE,
    );
}

pub fn down(&self) -> Vec3

Return the local down vector (-Y).

pub fn back(&self) -> Vec3

Return the local back vector (Z).

pub fn forward(&self) -> Vec3

Return the local forward vector (-Z).

pub fn translation(&self) -> Vec3

Get the translation as a Vec3.

Examples found in repository

examples/ecs/iter_combinations.rs (line 131)

fn interact_bodies(mut query: Query<(&Mass, &GlobalTransform, &mut Acceleration)>) {
    let mut iter = query.iter_combinations_mut();
    while let Some([(Mass(m1), transform1, mut acc1), (Mass(m2), transform2, mut acc2)]) =
        iter.fetch_next()
    {
        let delta = transform2.translation() - transform1.translation();
        let distance_sq: f32 = delta.length_squared();

        let f = GRAVITY_CONSTANT / distance_sq;
        let force_unit_mass = delta * f;
        acc1.0 += force_unit_mass * *m2;
        acc2.0 -= force_unit_mass * *m1;
    }
}

examples/3d/3d_viewport_to_world.rs (line 33)

fn draw_cursor(
    camera_query: Query<(&Camera, &GlobalTransform)>,
    ground_query: Query<&GlobalTransform, With<Ground>>,
    windows: Query<&Window>,
    mut gizmos: Gizmos,
) {
    let (camera, camera_transform) = camera_query.single();
    let ground = ground_query.single();

    let Some(cursor_position) = windows.single().cursor_position() else {
        return;
    };

    // Calculate a ray pointing from the camera into the world based on the cursor's position.
    let Some(ray) = camera.viewport_to_world(camera_transform, cursor_position) else {
        return;
    };

    // Calculate if and where the ray is hitting the ground plane.
    let Some(distance) = ray.intersect_plane(ground.translation(), Plane3d::new(ground.up()))
    else {
        return;
    };
    let point = ray.get_point(distance);

    // Draw a circle just above the ground plane at that position.
    gizmos.circle(
        point + ground.up() * 0.01,
        Direction3d::new_unchecked(ground.up()), // Up vector is already normalized.
        0.2,
        Color::WHITE,
    );
}

examples/3d/blend_modes.rs (line 332)

fn example_control_system(
    mut materials: ResMut<Assets<StandardMaterial>>,
    controllable: Query<(&Handle<StandardMaterial>, &ExampleControls)>,
    mut camera: Query<(&mut Camera, &mut Transform, &GlobalTransform), With<Camera3d>>,
    mut labels: Query<(&mut Style, &ExampleLabel)>,
    mut display: Query<&mut Text, With<ExampleDisplay>>,
    labelled: Query<&GlobalTransform>,
    mut state: Local<ExampleState>,
    time: Res<Time>,
    input: Res<ButtonInput<KeyCode>>,
) {
    if input.pressed(KeyCode::ArrowUp) {
        state.alpha = (state.alpha + time.delta_seconds()).min(1.0);
    } else if input.pressed(KeyCode::ArrowDown) {
        state.alpha = (state.alpha - time.delta_seconds()).max(0.0);
    }

    if input.just_pressed(KeyCode::Space) {
        state.unlit = !state.unlit;
    }

    let randomize_colors = input.just_pressed(KeyCode::KeyC);

    for (material_handle, controls) in &controllable {
        let material = materials.get_mut(material_handle).unwrap();
        material.base_color.set_a(state.alpha);

        if controls.color && randomize_colors {
            material.base_color.set_r(random());
            material.base_color.set_g(random());
            material.base_color.set_b(random());
        }
        if controls.unlit {
            material.unlit = state.unlit;
        }
    }

    let (mut camera, mut camera_transform, camera_global_transform) = camera.single_mut();

    if input.just_pressed(KeyCode::KeyH) {
        camera.hdr = !camera.hdr;
    }

    let rotation = if input.pressed(KeyCode::ArrowLeft) {
        time.delta_seconds()
    } else if input.pressed(KeyCode::ArrowRight) {
        -time.delta_seconds()
    } else {
        0.0
    };

    camera_transform.rotate_around(Vec3::ZERO, Quat::from_rotation_y(rotation));

    for (mut style, label) in &mut labels {
        let world_position = labelled.get(label.entity).unwrap().translation() + Vec3::Y;

        let viewport_position = camera
            .world_to_viewport(camera_global_transform, world_position)
            .unwrap();

        style.top = Val::Px(viewport_position.y);
        style.left = Val::Px(viewport_position.x);
    }

    let mut display = display.single_mut();
    display.sections[0].value = format!(
        "  HDR: {}\nAlpha: {:.2}",
        if camera.hdr { "ON " } else { "OFF" },
        state.alpha
    );
}

pub fn translation_vec3a(&self) -> Vec3A

Get the translation as a Vec3A.

pub fn radius_vec3a(&self, extents: Vec3A) -> f32

Get an upper bound of the radius from the given extents.

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

Transforms the given point, applying shear, scale, rotation and translation.

This moves point into the local space of this GlobalTransform.

Examples found in repository

examples/3d/irradiance_volumes.rs (line 609)

fn create_cubes(
    image_assets: Res<Assets<Image>>,
    mut commands: Commands,
    irradiance_volumes: Query<(&IrradianceVolume, &GlobalTransform)>,
    voxel_cube_parents: Query<Entity, With<VoxelCubeParent>>,
    voxel_cubes: Query<Entity, With<VoxelCube>>,
    example_assets: Res<ExampleAssets>,
    mut voxel_visualization_material_assets: ResMut<Assets<VoxelVisualizationMaterial>>,
) {
    // If voxel cubes have already been spawned, don't do anything.
    if !voxel_cubes.is_empty() {
        return;
    }

    let Some(voxel_cube_parent) = voxel_cube_parents.iter().next() else {
        return;
    };

    for (irradiance_volume, global_transform) in irradiance_volumes.iter() {
        let Some(image) = image_assets.get(&irradiance_volume.voxels) else {
            continue;
        };

        let resolution = image.texture_descriptor.size;

        let voxel_cube_material = voxel_visualization_material_assets.add(ExtendedMaterial {
            base: StandardMaterial::from(Color::RED),
            extension: VoxelVisualizationExtension {
                irradiance_volume_info: VoxelVisualizationIrradianceVolumeInfo {
                    transform: VOXEL_TRANSFORM.inverse(),
                    inverse_transform: VOXEL_TRANSFORM,
                    resolution: uvec3(
                        resolution.width,
                        resolution.height,
                        resolution.depth_or_array_layers,
                    ),
                    intensity: IRRADIANCE_VOLUME_INTENSITY,
                },
            },
        });

        let scale = vec3(
            1.0 / resolution.width as f32,
            1.0 / resolution.height as f32,
            1.0 / resolution.depth_or_array_layers as f32,
        );

        // Spawn a cube for each voxel.
        for z in 0..resolution.depth_or_array_layers {
            for y in 0..resolution.height {
                for x in 0..resolution.width {
                    let uvw = (uvec3(x, y, z).as_vec3() + 0.5) * scale - 0.5;
                    let pos = global_transform.transform_point(uvw);
                    let voxel_cube = commands
                        .spawn(MaterialMeshBundle {
                            mesh: example_assets.voxel_cube.clone(),
                            material: voxel_cube_material.clone(),
                            transform: Transform::from_scale(Vec3::splat(VOXEL_CUBE_SCALE))
                                .with_translation(pos),
                            ..default()
                        })
                        .insert(VoxelCube)
                        .insert(NotShadowCaster)
                        .id();

                    commands.entity(voxel_cube_parent).add_child(voxel_cube);
                }
            }
        }
    }
}

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

Multiplies self with transform component by component, returning the resulting GlobalTransform

Trait Implementations

impl Clone for GlobalTransform

fn clone(&self) -> GlobalTransform

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Component for GlobalTransform

where GlobalTransform: Send + Sync + 'static,

type Storage = TableStorage

A marker type indicating the storage type used for this component. This must be either TableStorage or SparseStorage.

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 From<Affine3A> for GlobalTransform

fn from(affine: Affine3A) -> GlobalTransform

Converts to this type from the input type.

impl From<GlobalTransform> for Transform

The transform is expected to be non-degenerate and without shearing, or the output will be invalid.

fn from(transform: GlobalTransform) -> Transform

Converts to this type from the input type.

impl From<Mat4> for GlobalTransform

fn from(matrix: Mat4) -> GlobalTransform

Converts to this type from the input type.

impl From<Transform> for GlobalTransform

fn from(transform: Transform) -> GlobalTransform

Converts to this type from the input type.

impl FromReflect for GlobalTransform

where GlobalTransform: Any + Send + Sync, Affine3A: FromReflect + TypePath,

fn from_reflect(reflect: &(dyn Reflect + 'static)) -> Option<GlobalTransform>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn Reflect> ) -> Result<Self, Box<dyn Reflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl GetTypeRegistration for GlobalTransform

where GlobalTransform: Any + Send + Sync, Affine3A: FromReflect + TypePath,

fn get_type_registration() -> TypeRegistration

impl Mul<GlobalTransform> for Transform

type Output = GlobalTransform

The resulting type after applying the * operator.

fn mul( self, global_transform: GlobalTransform ) -> <Transform as Mul<GlobalTransform>>::Output

Performs the * operation.

impl Mul<Transform> for GlobalTransform

type Output = GlobalTransform

The resulting type after applying the * operator.

fn mul( self, transform: Transform ) -> <GlobalTransform as Mul<Transform>>::Output

Performs the * operation.

impl Mul<Vec3> for GlobalTransform

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, value: Vec3) -> <GlobalTransform as Mul<Vec3>>::Output

Performs the * operation.

impl Mul for GlobalTransform

type Output = GlobalTransform

The resulting type after applying the * operator.

fn mul( self, global_transform: GlobalTransform ) -> <GlobalTransform as Mul>::Output

Performs the * operation.

impl PartialEq for GlobalTransform

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

This method tests for self and other values to be equal, and is used by ==.

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

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

impl Reflect for GlobalTransform

where GlobalTransform: Any + Send + Sync, Affine3A: FromReflect + TypePath,

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

fn into_any(self: Box<GlobalTransform>) -> Box<dyn Any>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &(dyn Any + 'static)

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<GlobalTransform>) -> Box<dyn Reflect>

Casts this type to a boxed reflected value.

fn as_reflect(&self) -> &(dyn Reflect + 'static)

Casts this type to a reflected value.

fn as_reflect_mut(&mut self) -> &mut (dyn Reflect + 'static)

Casts this type to a mutable reflected value.

fn clone_value(&self) -> Box<dyn Reflect>

Clones the value as a Reflect trait object.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

fn apply(&mut self, value: &(dyn Reflect + 'static))

Applies a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<GlobalTransform>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn reflect_partial_eq(&self, value: &(dyn Reflect + 'static)) -> Option<bool>

Returns a “partial equality” comparison result.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

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

Debug formatter for the value.

fn serializable(&self) -> Option<Serializable<'_>>

Returns a serializable version of the value.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl TransformPoint for GlobalTransform

fn transform_point(&self, point: impl Into<Vec3>) -> Vec3

Transform a point.

impl TupleStruct for GlobalTransform

where GlobalTransform: Any + Send + Sync, Affine3A: FromReflect + TypePath,

fn field(&self, index: usize) -> Option<&(dyn Reflect + 'static)>

Returns a reference to the value of the field with index index as a &dyn Reflect.

fn field_mut(&mut self, index: usize) -> Option<&mut (dyn Reflect + 'static)>

Returns a mutable reference to the value of the field with index index as a &mut dyn Reflect.

fn field_len(&self) -> usize

Returns the number of fields in the tuple struct.

fn iter_fields(&self) -> TupleStructFieldIter<'_>

Returns an iterator over the values of the tuple struct’s fields.

fn clone_dynamic(&self) -> DynamicTupleStruct

Clones the struct into a DynamicTupleStruct.

impl TypePath for GlobalTransform

where GlobalTransform: Any + Send + Sync,

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.

impl Typed for GlobalTransform

where GlobalTransform: Any + Send + Sync, Affine3A: FromReflect + TypePath,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl Copy for GlobalTransform

impl StructuralPartialEq for GlobalTransform