Struct Rotation

pub struct Rotation {
    pub cos: Scalar,
    pub sin: Scalar,
}

The global counterclockwise physics rotation of a rigid body or a collider in radians.

The rotation angle is wrapped to be within the (-pi, pi] range.

Relation to Transform and GlobalTransform

Rotation is used for physics internally and kept in sync with Transform by the SyncPlugin. It rarely needs to be used directly in your own code, as Transform can still be used for almost everything. Using Rotation should only be required for managing rotations in systems running in the SubstepSchedule, but if you prefer, you can also use Rotation for everything.

The reasons why the engine uses a separate Rotation component can be found here.

Example

use avian2d::prelude::*;
use bevy::prelude::*;

fn setup(mut commands: Commands) {
    // Spawn a dynamic rigid body rotated by 90 degrees
    commands.spawn((RigidBody::Dynamic, Rotation::degrees(90.0)));
}

Fields

cos: Scalar

The cosine of the rotation angle in radians.

This is the real part of the unit complex number representing the rotation.

sin: Scalar

The sine of the rotation angle in radians.

This is the imaginary part of the unit complex number representing the rotation.

Implementations

impl Rotation

pub const IDENTITY: Self

No rotation.

pub const PI: Self

A rotation of π radians.

pub const FRAC_PI_2: Self

A counterclockwise rotation of π/2 radians.

pub const FRAC_PI_3: Self

A counterclockwise rotation of π/3 radians.

pub const FRAC_PI_4: Self

A counterclockwise rotation of π/4 radians.

pub const FRAC_PI_6: Self

A counterclockwise rotation of π/6 radians.

pub const FRAC_PI_8: Self

A counterclockwise rotation of π/8 radians.

pub fn radians(radians: Scalar) -> Self

Creates a Rotation from a counterclockwise angle in radians.

pub fn degrees(degrees: Scalar) -> Self

Creates a Rotation from a counterclockwise angle in degrees.

pub fn from_radians(radians: Scalar) -> Self

👎Deprecated: renamed to just radians to match Bevy

Creates a Rotation from radians.

pub fn from_degrees(degrees: Scalar) -> Self

👎Deprecated: renamed to just degrees to match Bevy

Creates a Rotation from degrees.

pub fn from_sin_cos(sin: Scalar, cos: Scalar) -> Self

Creates a Rotation from the sine and cosine of an angle in radians.

The rotation is only valid if sin * sin + cos * cos == 1.0.

Panics

Panics if sin * sin + cos * cos != 1.0 when the glam_assert feature is enabled.

pub fn as_radians(self) -> Scalar

Returns the rotation in radians in the (-pi, pi] range.

pub fn as_degrees(self) -> Scalar

Returns the rotation in degrees in the (-180, 180] range.

pub const fn sin_cos(self) -> (Scalar, Scalar)

Returns the sine and cosine of the rotation angle in radians.

pub fn rotate(&self, vec: Vector) -> Vector

👎Deprecated: use the Mul impl instead, like rot * vec

Rotates the given vector by self.

pub fn length(self) -> Scalar

Computes the length or norm of the complex number used to represent the rotation.

The length is typically expected to be 1.0. Unexpectedly denormalized rotations can be a result of incorrect construction or floating point error caused by successive operations.

pub fn length_squared(self) -> Scalar

Computes the squared length or norm of the complex number used to represent the rotation.

This is generally faster than Rotation::length(), as it avoids a square root operation.

The length is typically expected to be 1.0. Unexpectedly denormalized rotations can be a result of incorrect construction or floating point error caused by successive operations.

pub fn length_recip(self) -> Scalar

Computes 1.0 / self.length().

For valid results, self must not have a length of zero.

pub fn try_normalize(self) -> Option<Self>

Returns self with a length of 1.0 if possible, and None otherwise.

None will be returned if the sine and cosine of self are both zero (or very close to zero), or if either of them is NaN or infinite.

Note that Rotation should typically already be normalized by design. Manual normalization is only needed when successive operations result in accumulated floating point error, or if the rotation was constructed with invalid values.

pub fn normalize(self) -> Self

Returns self with a length of 1.0.

Note that Rotation should typically already be normalized by design. Manual normalization is only needed when successive operations result in accumulated floating point error, or if the rotation was constructed with invalid values.

Panics

Panics if self has a length of zero, NaN, or infinity when debug assertions are enabled.

pub fn fast_renormalize(self) -> Self

Returns self after an approximate normalization, assuming the value is already nearly normalized. Useful for preventing numerical error accumulation.

pub fn is_finite(self) -> bool

Returns true if the rotation is neither infinite nor NaN.

pub fn is_nan(self) -> bool

Returns true if the rotation is NaN.

pub fn is_normalized(self) -> bool

Returns whether self has a length of 1.0 or not.

Uses a precision threshold of approximately 1e-4.

pub fn is_near_identity(self) -> bool

Returns true if the rotation is near Rotation::IDENTITY.

pub fn angle_between(self, other: Self) -> Scalar

Returns the angle in radians needed to make self and other coincide.

pub fn inverse(self) -> Self

Returns the inverse of the rotation. This is also the conjugate of the unit complex number representing the rotation.

pub fn add_angle(&self, radians: Scalar) -> Self

Adds the given counterclockiwise angle in radians to the Rotation. Uses small-angle approximation

pub fn nlerp(self, end: Self, s: Scalar) -> Self

Performs a linear interpolation between self and rhs based on the value s, and normalizes the rotation afterwards.

When s == 0.0, the result will be equal to self. When s == 1.0, the result will be equal to rhs.

This is slightly more efficient than slerp, and produces a similar result when the difference between the two rotations is small. At larger differences, the result resembles a kind of ease-in-out effect.

If you would like the angular velocity to remain constant, consider using slerp instead.

Details

nlerp corresponds to computing an angle for a point at position s on a line drawn between the endpoints of the arc formed by self and rhs on a unit circle, and normalizing the result afterwards.

Note that if the angles are opposite like 0 and π, the line will pass through the origin, and the resulting angle will always be either self or rhs depending on s. If s happens to be 0.5 in this case, a valid rotation cannot be computed, and self will be returned as a fallback.

Example

let rot1 = Rotation::IDENTITY;
let rot2 = Rotation::degrees(135.0);

let result1 = rot1.nlerp(rot2, 1.0 / 3.0);
assert_relative_eq!(result1.as_degrees(), 28.675055, epsilon = 0.0001);

let result2 = rot1.nlerp(rot2, 0.5);
assert_relative_eq!(result2.as_degrees(), 67.5);

pub fn slerp(self, end: Self, s: Scalar) -> Self

Performs a spherical linear interpolation between self and end based on the value s.

This corresponds to interpolating between the two angles at a constant angular velocity.

When s == 0.0, the result will be equal to self. When s == 1.0, the result will be equal to rhs.

If you would like the rotation to have a kind of ease-in-out effect, consider using the slightly more efficient nlerp instead.

Example

let rot1 = Rotation::IDENTITY;
let rot2 = Rotation::degrees(135.0);

let result1 = rot1.slerp(rot2, 1.0 / 3.0);
assert_eq!(result1.as_degrees(), 45.0);

let result2 = rot1.slerp(rot2, 0.5);
assert_eq!(result2.as_degrees(), 67.5);

Trait Implementations

impl Clone for Rotation

fn clone(&self) -> Rotation

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Component for Rotation

where Self: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy::ecs::component::StorageType::Table

A constant indicating the storage type used for this component.

fn register_required_components( requiree: ComponentId, components: &mut Components, storages: &mut Storages, required_components: &mut RequiredComponents, inheritance_depth: u16, )

Registers required components.

fn register_component_hooks(hooks: &mut ComponentHooks)

Called when registering this component, allowing mutable access to its ComponentHooks.

impl Debug for Rotation

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

Formats the value using the given formatter.

impl Default for Rotation

fn default() -> Self

Returns the “default value” for a type.

impl From<&GlobalTransform> for Rotation

fn from(value: &GlobalTransform) -> Self

Converts to this type from the input type.

impl From<DQuat> for Rotation

fn from(quat: DQuat) -> Self

Converts to this type from the input type.

impl From<GlobalTransform> for Rotation

fn from(value: GlobalTransform) -> Self

Converts to this type from the input type.

impl From<Quat> for Rotation

fn from(quat: Quat) -> Self

Converts to this type from the input type.

impl From<Rot2> for Rotation

fn from(rot: Rot2) -> Self

Creates a Rotation from a Rot2.

impl From<Rotation> for Matrix

fn from(rot: Rotation) -> Self

Creates a Matrix rotation matrix from a Rotation.

impl From<Rotation> for PreSolveRotation

fn from(value: Rotation) -> Self

Converts to this type from the input type.

impl From<Rotation> for Quaternion

fn from(rot: Rotation) -> Self

Converts to this type from the input type.

impl From<Rotation> for Rot2

fn from(rot: Rotation) -> Self

Creates a Rot2 from a Rotation.

impl From<Rotation> for Scalar

fn from(rot: Rotation) -> Self

Converts to this type from the input type.

impl From<Transform> for Rotation

fn from(value: Transform) -> Self

Converts to this type from the input type.

impl From<f32> for Rotation

fn from(rotation: Scalar) -> Self

Creates a Rotation from a counterclockwise angle in radians.

impl FromReflect for Rotation

where Rotation: Any + Send + Sync, Scalar: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn from_reflect(reflect: &dyn PartialReflect) -> Option<Self>

Constructs a concrete instance of Self from a reflected value.

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

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

impl GetTypeRegistration for Rotation

where Rotation: Any + Send + Sync, Scalar: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn get_type_registration() -> TypeRegistration

Returns the default TypeRegistration for this type.

fn register_type_dependencies(registry: &mut TypeRegistry)

Registers other types needed by this type.

impl Mul<&Dir2> for &Rotation

type Output = Dir2

The resulting type after applying the * operator.

fn mul(self, direction: &Dir2) -> Self::Output

Performs the * operation.

impl Mul<&Dir2> for &mut Rotation

type Output = Dir2

The resulting type after applying the * operator.

fn mul(self, direction: &Dir2) -> Self::Output

Performs the * operation.

impl Mul<&Dir2> for Rotation

type Output = Dir2

The resulting type after applying the * operator.

fn mul(self, direction: &Dir2) -> Self::Output

Performs the * operation.

impl Mul<&Vec2> for &Rotation

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, vector: &Vector) -> Self::Output

Performs the * operation.

impl Mul<&Vec2> for &mut Rotation

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, vector: &Vector) -> Self::Output

Performs the * operation.

impl Mul<&Vec2> for Rotation

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, vector: &Vector) -> Self::Output

Performs the * operation.

impl Mul<&Vec3> for &Rotation

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: &Vector3) -> Self::Output

Performs the * operation.

impl Mul<&Vec3> for &mut Rotation

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: &Vector3) -> Self::Output

Performs the * operation.

impl Mul<&Vec3> for Rotation

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: &Vector3) -> Self::Output

Performs the * operation.

impl Mul<&mut Dir2> for &Rotation

type Output = Dir2

The resulting type after applying the * operator.

fn mul(self, direction: &mut Dir2) -> Self::Output

Performs the * operation.

impl Mul<&mut Dir2> for &mut Rotation

type Output = Dir2

The resulting type after applying the * operator.

fn mul(self, direction: &mut Dir2) -> Self::Output

Performs the * operation.

impl Mul<&mut Dir2> for Rotation

type Output = Dir2

The resulting type after applying the * operator.

fn mul(self, direction: &mut Dir2) -> Self::Output

Performs the * operation.

impl Mul<&mut Vec2> for &Rotation

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, vector: &mut Vector) -> Self::Output

Performs the * operation.

impl Mul<&mut Vec2> for &mut Rotation

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, vector: &mut Vector) -> Self::Output

Performs the * operation.

impl Mul<&mut Vec2> for Rotation

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, vector: &mut Vector) -> Self::Output

Performs the * operation.

impl Mul<&mut Vec3> for &Rotation

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: &mut Vector3) -> Self::Output

Performs the * operation.

impl Mul<&mut Vec3> for &mut Rotation

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: &mut Vector3) -> Self::Output

Performs the * operation.

impl Mul<&mut Vec3> for Rotation

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: &mut Vector3) -> Self::Output

Performs the * operation.

impl Mul<Dir2> for &Rotation

type Output = Dir2

The resulting type after applying the * operator.

fn mul(self, direction: Dir2) -> Self::Output

Performs the * operation.

impl Mul<Dir2> for &mut Rotation

type Output = Dir2

The resulting type after applying the * operator.

fn mul(self, direction: Dir2) -> Self::Output

Performs the * operation.

impl Mul<Dir2> for Rotation

type Output = Dir2

The resulting type after applying the * operator.

fn mul(self, direction: Dir2) -> Self::Output

Performs the * operation.

impl Mul<Vec2> for &Rotation

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, vector: Vector) -> Self::Output

Performs the * operation.

impl Mul<Vec2> for &mut Rotation

type Output = Vec2

The resulting type after applying the * operator.

fn mul(self, vector: Vector) -> Self::Output

Performs the * operation.

impl Mul<Vec2> for Rotation

fn mul(self, rhs: Vector) -> Self::Output

Rotates a Vector by a Rotation.

type Output = Vec2

The resulting type after applying the * operator.

impl Mul<Vec3> for &Rotation

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: Vector3) -> Self::Output

Performs the * operation.

impl Mul<Vec3> for &mut Rotation

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: Vector3) -> Self::Output

Performs the * operation.

impl Mul<Vec3> for Rotation

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: Vector3) -> Self::Output

Performs the * operation.

impl Mul for Rotation

type Output = Rotation

The resulting type after applying the * operator.

fn mul(self, rhs: Self) -> Self::Output

Performs the * operation.

impl MulAssign for Rotation

fn mul_assign(&mut self, rhs: Self)

Performs the *= operation.

impl PartialEq for Rotation

fn eq(&self, other: &Rotation) -> 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 PartialReflect for Rotation

where Rotation: Any + Send + Sync, Scalar: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

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

Returns the TypeInfo of the type represented by this value.

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

Clones the value as a Reflect trait object.

fn try_apply(&mut self, value: &dyn PartialReflect) -> Result<(), ApplyError>

Tries to apply 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<Self>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<Self>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>

Attempts to cast this type to a boxed, fully-reflected value.

fn try_as_reflect(&self) -> Option<&dyn Reflect>

Attempts to cast this type to a fully-reflected value.

fn try_as_reflect_mut(&mut self) -> Option<&mut dyn Reflect>

Attempts to cast this type to a mutable, fully-reflected value.

fn into_partial_reflect(self: Box<Self>) -> Box<dyn PartialReflect>

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &dyn PartialReflect

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut dyn PartialReflect

Casts this type to a mutable, reflected value.

fn reflect_partial_eq(&self, value: &dyn PartialReflect) -> Option<bool>

Returns a “partial equality” comparison result.

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

Debug formatter for the value.

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

Applies a reflected value to this value.

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

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

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 Reflect for Rotation

where Rotation: Any + Send + Sync, Scalar: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

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

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &dyn Any

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut dyn Any

Returns the value as a &mut dyn Any.

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

Casts this type to a boxed, fully-reflected value.

fn as_reflect(&self) -> &dyn Reflect

Casts this type to a fully-reflected value.

fn as_reflect_mut(&mut self) -> &mut dyn Reflect

Casts this type to a mutable, fully-reflected value.

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

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

impl Struct for Rotation

where Rotation: Any + Send + Sync, Scalar: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn field(&self, name: &str) -> Option<&dyn PartialReflect>

Returns a reference to the value of the field named name as a &dyn PartialReflect.

fn field_mut(&mut self, name: &str) -> Option<&mut dyn PartialReflect>

Returns a mutable reference to the value of the field named name as a &mut dyn PartialReflect.

fn field_at(&self, index: usize) -> Option<&dyn PartialReflect>

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

fn field_at_mut(&mut self, index: usize) -> Option<&mut dyn PartialReflect>

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

fn name_at(&self, index: usize) -> Option<&str>

Returns the name of the field with index index.

fn field_len(&self) -> usize

Returns the number of fields in the struct.

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

Returns an iterator over the values of the reflectable fields for this struct.

fn clone_dynamic(&self) -> DynamicStruct

Clones the struct into a DynamicStruct.

fn get_represented_struct_info(&self) -> Option<&'static StructInfo>

Will return None if TypeInfo is not available.

impl TypePath for Rotation

where Rotation: 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 Rotation

where Rotation: Any + Send + Sync, Scalar: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl Copy for Rotation

impl StructuralPartialEq for Rotation