[][src]Struct amethyst_core::transform::components::Transform

pub struct Transform { /* fields omitted */ }

Local position, rotation, and scale (from parent if it exists).

Used for rendering position and orientation.

The transforms are preformed in this order: scale, then rotation, then translation.

Methods

impl Transform[src]

pub fn isometry(&self) -> &Isometry3<f32>[src]

Translation + rotation value

pub fn scale(&self) -> &Vector3<f32>[src]

Scale vector

pub fn global_matrix(&self) -> &Matrix4<f32>[src]

The global transformation matrix.

impl Transform[src]

pub fn set_isometry(&mut self, val: Isometry3<f32>) -> &mut Self[src]

Translation + rotation value

impl Transform[src]

pub fn isometry_mut(&mut self) -> &mut Isometry3<f32>[src]

Translation + rotation value

pub fn scale_mut(&mut self) -> &mut Vector3<f32>[src]

Scale vector

impl Transform[src]

pub fn new<N: RealField + SubsetOf<f32>>(
    position: Translation3<N>,
    rotation: UnitQuaternion<N>,
    scale: Vector3<N>
) -> Self
[src]

Create a new Transform.

Examples

let position = Translation3::new(0.0, 2.0, 4.0);
let rotation = UnitQuaternion::from_euler_angles(0.4, 0.2, 0.0);
let scale = Vector3::new(1.0, 1.0, 1.0);

let t = Transform::new(position, rotation, scale);

assert_eq!(t.translation().y, 2.0);

pub fn set_scale<N: RealField + SubsetOf<f32>>(&mut self, scale: Vector3<N>)[src]

Set the scaling factor of this transform.

pub fn face_towards<N: RealField + SubsetOf<f32>>(
    &mut self,
    target: Vector3<N>,
    up: Vector3<N>
) -> &mut Self
[src]

Makes the entity point towards target.

up says which direction the entity should be 'rolled' to once it is pointing at position. If up is parallel to the direction the entity is looking, the result will be garbage.

This function only works with respect to the coordinate system of its parent, so when used with an object that's not a sibling it will not do what you expect.

Examples

let mut t = Transform::default();
// No rotation by default
assert_eq!(*t.rotation().quaternion(), Quaternion::identity());
// look up with up pointing backwards
t.face_towards(
    Vector3::new(0.0, 1.0, 0.0),
    Vector3::new(0.0, 0.0, 1.0),
);
// our rotation should match the angle from straight ahead to straight up
let rotation = UnitQuaternion::rotation_between(
    &Vector3::new(0.0, 1.0, 0.0),
    &Vector3::new(0.0, 0.0, 1.0),
).unwrap();
assert_eq!(*t.rotation(), rotation);
// now if we move forwards by 1.0, we'll end up at the point we are facing
// (modulo some floating point error)
t.move_forward(1.0);
assert!((*t.translation() - Vector3::new(0.0, 1.0, 0.0)).magnitude() <= 0.0001);

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

Returns the local object matrix for the transform.

pub fn translation(&self) -> &Vector3<f32>[src]

Returns a reference to the translation vector.

pub fn translation_mut(&mut self) -> &mut Vector3<f32>[src]

Returns a mutable reference to the translation vector.

pub fn rotation(&self) -> &UnitQuaternion<f32>[src]

Returns a reference to the rotation quaternion.

pub fn rotation_mut(&mut self) -> &mut UnitQuaternion<f32>[src]

Returns a mutable reference to the rotation quaternion.

pub fn prepend_translation(&mut self, translation: Vector3<f32>) -> &mut Self[src]

Move relatively to its current position, but the parent's (or global, if no parent exists) orientation.

For example, if the object is rotated 45 degrees about its Y axis, then you prepend a translation along the Z axis, it will still move along the parent's Z axis rather than its local Z axis (which is rotated 45 degrees).

pub fn append_translation(&mut self, translation: Vector3<f32>) -> &mut Self[src]

Move relatively to its current position and orientation.

For example, if the object is rotated 45 degrees about its Y axis, then you append a translation along the Z axis, that Z axis is now rotated 45 degrees, and so the appended translation will go along that rotated Z axis.

Equivalent to rotating the translation by the transform's current rotation before applying.

pub fn prepend_translation_along(
    &mut self,
    direction: Unit<Vector3<f32>>,
    distance: f32
) -> &mut Self
[src]

Move a distance along an axis relative to the parent's orientation (or the global orientation if no parent exists).

For example, if the object is rotated 45 degrees about its Y axis, then you prepend a translation along the Z axis, it will still move along the parent's Z axis rather than its local Z axis (which is rotated 45 degrees).

pub fn append_translation_along(
    &mut self,
    direction: Unit<Vector3<f32>>,
    distance: f32
) -> &mut Self
[src]

Move a distance along an axis relative to the local orientation.

pub fn move_forward(&mut self, amount: f32) -> &mut Self[src]

Move forward relative to current position and orientation.

pub fn move_backward(&mut self, amount: f32) -> &mut Self[src]

Move backward relative to current position and orientation.

pub fn move_right(&mut self, amount: f32) -> &mut Self[src]

Move right relative to current position and orientation.

pub fn move_left(&mut self, amount: f32) -> &mut Self[src]

Move left relative to current position and orientation.

pub fn move_up(&mut self, amount: f32) -> &mut Self[src]

Move up relative to current position and orientation.

pub fn move_down(&mut self, amount: f32) -> &mut Self[src]

Move down relative to current position and orientation.

pub fn prepend_translation_x(&mut self, amount: f32) -> &mut Self[src]

Adds the specified amount to the translation vector's x component. i.e. move relative to the parent's (or global, if no parent exists) x axis.

pub fn prepend_translation_y(&mut self, amount: f32) -> &mut Self[src]

Adds the specified amount to the translation vector's y component. i.e. move relative to the parent's (or global, if no parent exists) y axis.

pub fn prepend_translation_z(&mut self, amount: f32) -> &mut Self[src]

Adds the specified amount to the translation vector's z component. i.e. move relative to the parent's (or global, if no parent exists) z axis.

pub fn set_translation_x(&mut self, value: f32) -> &mut Self[src]

Sets the translation vector's x component to the specified value.

pub fn set_translation_y(&mut self, value: f32) -> &mut Self[src]

Sets the translation vector's y component to the specified value.

pub fn set_translation_z(&mut self, value: f32) -> &mut Self[src]

Sets the translation vector's z component to the specified value.

pub fn prepend_rotation_x_axis(&mut self, delta_angle: f32) -> &mut Self[src]

Premultiply a rotation about the x axis, i.e. perform a rotation about the parent's x axis (or the global x axis if no parent exists).

delta_angle is specified in radians.

pub fn append_rotation_x_axis(&mut self, delta_angle: f32) -> &mut Self[src]

Postmultiply a rotation about the x axis, i.e. perform a rotation about the local x-axis, including any prior rotations that have been performed.

delta_angle is specified in radians.

pub fn set_rotation_x_axis(&mut self, angle: f32) -> &mut Self[src]

Set the rotation about the parent's x axis (or the global x axis if no parent exists). This will clear any other rotations that have previously been performed!

angle is specified in radians.

pub fn prepend_rotation_y_axis(&mut self, delta_angle: f32) -> &mut Self[src]

Premultiply a rotation about the y axis, i.e. perform a rotation about the parent's y axis (or the global y axis if no parent exists).

delta_angle is specified in radians.

pub fn append_rotation_y_axis(&mut self, delta_angle: f32) -> &mut Self[src]

Postmultiply a rotation about the y axis, i.e. perform a rotation about the local y-axis, including any prior rotations that have been performed.

delta_angle is specified in radians.

pub fn set_rotation_y_axis(&mut self, angle: f32) -> &mut Self[src]

Set the rotation about the parent's y axis (or the global y axis if no parent exists). This will clear any other rotations that have previously been performed!

angle is specified in radians.

pub fn prepend_rotation_z_axis(&mut self, delta_angle: f32) -> &mut Self[src]

Premultiply a rotation about the z axis, i.e. perform a rotation about the parent's z axis (or the global z axis if no parent exists).

delta_angle is specified in radians.

pub fn append_rotation_z_axis(&mut self, delta_angle: f32) -> &mut Self[src]

Postmultiply a rotation about the z axis, i.e. perform a rotation about the local z-axis, including any prior rotations that have been performed.

delta_angle is specified in radians.

pub fn set_rotation_z_axis(&mut self, angle: f32) -> &mut Self[src]

Set the rotation about the parent's z axis (or the global z axis if no parent exists). This will clear any other rotations that have previously been performed!

angle is specified in radians.

pub fn rotate_2d(&mut self, delta_angle: f32) -> &mut Self[src]

Perform a rotation about the axis perpendicular to X and Y, i.e. the most common way to rotate an object in a 2d game.

delta_angle is specified in radians.

pub fn set_rotation_2d(&mut self, angle: f32) -> &mut Self[src]

Set the rotation about the axis perpendicular to X and Y, i.e. the most common way to rotate an object in a 2d game.

angle is specified in radians.

pub fn prepend_rotation(
    &mut self,
    axis: Unit<Vector3<f32>>,
    angle: f32
) -> &mut Self
[src]

Premultiply a rotation, i.e. rotate relatively to the parent's orientation (or the global orientation if no parent exists), about a specified axis.

delta_angle is specified in radians.

pub fn append_rotation(
    &mut self,
    axis: Unit<Vector3<f32>>,
    angle: f32
) -> &mut Self
[src]

Postmultiply a rotation, i.e. rotate relatively to the local orientation (the currently applied rotations), about a specified axis.

delta_angle is specified in radians.

pub fn set_translation<N: RealField + SubsetOf<f32>>(
    &mut self,
    position: Vector3<N>
) -> &mut Self
[src]

Set the position.

pub fn append_translation_xyz(&mut self, x: f32, y: f32, z: f32) -> &mut Self[src]

Adds the specified amounts to the translation vector.

pub fn set_translation_xyz(&mut self, x: f32, y: f32, z: f32) -> &mut Self[src]

Sets the specified values of the translation vector.

pub fn set_rotation<N: RealField + SubsetOf<f32>>(
    &mut self,
    rotation: UnitQuaternion<N>
) -> &mut Self
[src]

Sets the rotation of the transform.

pub fn set_rotation_euler(&mut self, x: f32, y: f32, z: f32) -> &mut Self[src]

Set the rotation using x, y, z Euler axes.

All angles are specified in radians. Euler order is x → y → z.

Arguments

  • x - The angle to apply around the x axis.
  • y - The angle to apply around the y axis.
  • z - The angle to apply around the z axis.

Note on Euler angle semantics and nalgebra

nalgebra has a few methods related to Euler angles, and they use roll, pitch, and yaw as arguments instead of x, y, and z axes specifically. Yaw has the semantic meaning of rotation about the "up" axis, roll about the "forward axis", and pitch about the "right" axis respectively. However, nalgebra assumes a +Z = up coordinate system for its roll, pitch, and yaw semantics, while Amethyst uses a +Y = up coordinate system. Therefore, the nalgebra Euler angle methods are slightly confusing to use in concert with Amethyst, and so we've provided our own with semantics that match the rest of Amethyst. If you do end up using nalgebra's euler_angles or from_euler_angles methods, be aware that 'roll' in that context will mean rotation about the x axis, 'pitch' will mean rotation about the y axis, and 'yaw' will mean rotation about the z axis.

let mut transform = Transform::default();

transform.set_rotation_euler(1.0, 0.0, 0.0);

assert_eq!(transform.rotation().euler_angles().0, 1.0);

pub fn euler_angles(&self) -> (f32, f32, f32)[src]

Get the Euler angles of the current rotation. Returns in a tuple of the form (x, y, z), where x, y, and z are the current rotation about that axis in radians.

Note on Euler angle semantics and nalgebra

nalgebra has a few methods related to Euler angles, and they use roll, pitch, and yaw as arguments instead of x, y, and z axes specifically. Yaw has the semantic meaning of rotation about the "up" axis, roll about the "forward axis", and pitch about the "right" axis respectively. However, nalgebra assumes a +Z = up coordinate system for its roll, pitch, and yaw semantics, while Amethyst uses a +Y = up coordinate system. Therefore, the nalgebra Euler angle methods are slightly confusing to use in concert with Amethyst, and so we've provided our own with semantics that match the rest of Amethyst. If you do end up using nalgebra's euler_angles or from_euler_angles methods, be aware that 'roll' in that context will mean rotation about the x axis, 'pitch' will mean rotation about the y axis, and 'yaw' will mean rotation about the z axis.

pub fn concat(&mut self, other: &Self) -> &mut Self[src]

Concatenates another transform onto self.

Concatenating is roughly equivalent to doing matrix multiplication except for the fact that it's done on Transform which is decomposed.

pub fn is_finite(&self) -> bool[src]

Verifies that the global Matrix4 doesn't contain any NaN values.

pub fn view_matrix(&self) -> Matrix4<f32>[src]

Calculates the inverse of this transform, which is in effect the 'view matrix' as commonly seen in computer graphics. This function computes the view matrix for ONLY the local transformation, and ignores any Parents of this entity.

We can exploit the extra information we have to perform this inverse faster than O(n^3).

pub fn global_view_matrix(&self) -> Matrix4<f32>[src]

Calculates the inverse of this transform, which is in effect the 'view matrix' as commonly seen in computer graphics. This function computes the view matrix for the global transformation of the entity, and so takes into account Parents.

We can exploit the extra information we have to perform this inverse faster than O(n^3).

pub fn copy_local_to_global(&mut self)[src]

This function allows for test cases of copying the local matrix to the global matrix. Useful for tests or other debug type access.

Trait Implementations

impl Default for Transform[src]

fn default() -> Self[src]

The default transform does nothing when used to transform an entity.

impl Clone for Transform[src]

fn clone_from(&mut self, source: &Self)1.0.0[src]

Performs copy-assignment from source. Read more

impl PartialEq<Transform> for Transform[src]

impl From<Matrix<f32, U3, U1, <DefaultAllocator as Allocator<f32, U3, U1>>::Buffer>> for Transform[src]

Creates a Transform using the Vector3 as the translation vector.

let transform = Transform::from(Vector3::new(100.0, 200.0, 300.0));
assert_eq!(transform.translation().x, 100.0);

impl From<Matrix<f64, U3, U1, <DefaultAllocator as Allocator<f64, U3, U1>>::Buffer>> for Transform[src]

Creates a Transform using the Vector3<f64> as the translation vector. Provided for convinience when providing constants.

let transform = Transform::from(Vector3::new(100.0, 200.0, 300.0));
assert_eq!(transform.translation().x, 100.0);

impl Debug for Transform[src]

impl Serialize for Transform[src]

impl<'de> Deserialize<'de> for Transform[src]

impl Component for Transform[src]

type Storage = FlaggedStorage<Self, DenseVecStorage<Self>>

Associated storage type for this component.

Auto Trait Implementations

impl Unpin for Transform

impl Sync for Transform

impl Send for Transform

impl UnwindSafe for Transform

impl RefUnwindSafe for Transform

Blanket Implementations

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<SS, SP> SupersetOf<SS> for SP where
    SS: SubsetOf<SP>, 
[src]

impl<T> DeserializeOwned for T where
    T: Deserialize<'de>, 
[src]

impl<T> Same<T> for T[src]

type Output = T

Should always be Self

impl<T> Resource for T where
    T: Any + Send + Sync
[src]

impl<T> TryDefault for T where
    T: Default
[src]

fn unwrap_default() -> Self[src]

Calls try_default and panics on an error case.

impl<T> Event for T where
    T: Send + Sync + 'static, 
[src]

impl<T> Any for T where
    T: Any
[src]