Enum GridRotation 

#[repr(u8)]
pub enum GridRotation {
    RXYZ = 0,
    RXYz = 1,
    RXyZ = 2,
    RXyz = 3,
    RxYZ = 4,
    RxYz = 5,
    RxyZ = 6,
    Rxyz = 7,
    RXZY = 8,
    RXZy = 9,
    RXzY = 10,
    RXzy = 11,
    RxZY = 12,
    RxZy = 13,
    RxzY = 14,
    Rxzy = 15,
    RYXZ = 16,
    RYXz = 17,
    RYxZ = 18,
    RYxz = 19,
    RyXZ = 20,
    RyXz = 21,
    RyxZ = 22,
    Ryxz = 23,
    RYZX = 24,
    RYZx = 25,
    RYzX = 26,
    RYzx = 27,
    RyZX = 28,
    RyZx = 29,
    RyzX = 30,
    Ryzx = 31,
    RZXY = 32,
    RZXy = 33,
    RZxY = 34,
    RZxy = 35,
    RzXY = 36,
    RzXy = 37,
    RzxY = 38,
    Rzxy = 39,
    RZYX = 40,
    RZYx = 41,
    RZyX = 42,
    RZyx = 43,
    RzYX = 44,
    RzYx = 45,
    RzyX = 46,
    Rzyx = 47,
}

Represents a discrete (grid-aligned) rotation, or exchange of axes.

Compared to a GridMatrix, this cannot specify scale, translation, or skew; it is used for identifying the rotations of blocks.

Each of the variant names specifies the three unit vectors which (x, y, z), respectively, should be multiplied by to perform the rotation. Lowercase refers to a negated unit vector.

See also:

• Face6 is less general, in that it specifies a single axis but not rotation about that axis.
  • Face6::clockwise() and Face6::counterclockwise() can be used to obtain GridRotation values.
• GridMatrix is more general, specifying an affine transformation.

Serialization stability warning

This type implements [serde::Serialize] and [serde::Deserialize], but serialization support is still experimental (as is the game data model in general). We do not guarantee that future versions of all-is-cubes will be able to deserialize data which is serialized by this version.

Additionally, the serialization schema is designed with serde_json in mind. It is not guaranteed that using a different data format crate, which may use a different subset of the information exposed via [serde::Serialize], will produce stable results.

Variants

RXYZ = 0

RXYz = 1

RXyZ = 2

RXyz = 3

RxYZ = 4

RxYz = 5

RxyZ = 6

Rxyz = 7

RXZY = 8

RXZy = 9

RXzY = 10

RXzy = 11

RxZY = 12

RxZy = 13

RxzY = 14

Rxzy = 15

RYXZ = 16

RYXz = 17

RYxZ = 18

RYxz = 19

RyXZ = 20

RyXz = 21

RyxZ = 22

Ryxz = 23

RYZX = 24

RYZx = 25

RYzX = 26

RYzx = 27

RyZX = 28

RyZx = 29

RyzX = 30

Ryzx = 31

RZXY = 32

RZXy = 33

RZxY = 34

RZxy = 35

RzXY = 36

RzXy = 37

RzxY = 38

Rzxy = 39

RZYX = 40

RZYx = 41

RZyX = 42

RZyx = 43

RzYX = 44

RzYx = 45

RzyX = 46

Rzyx = 47

Implementations

impl GridRotation

pub const ALL: [Self; 48]

All 48 possible rotations.

Warning: TODO: The ordering of these rotations is not yet stable. The current ordering is based on the six axis permutations followed by rotations.

pub const ALL_BUT_REFLECTIONS: [Self; 24]

All possible rotations that are not reflections.

Warning: TODO: The ordering of these rotations is not yet stable.

pub const IDENTITY: Self = Self::RXYZ

The identity rotation, also known as RXYZ.

pub fn from_basis(basis: impl Into<[Face6; 3]>) -> Self

Constructs a rotation from a basis: that is, the returned rotation will rotate PX into basis[0], PY into basis[1], and PZ into basis[2].

Panics if the three provided axes are not mutually perpendicular.

pub fn from_to(source: Face6, destination: Face6, up: Face6) -> Option<Self>

Find the rotation (without reflection) which rotates source to destination. and leaves up unaffected. (This might also be considered a “look at” operation).

If it is not possible to leave up unaffected, returns None. (Trying two perpendicular up directions will always succeed.)

pub const fn to_positive_octant_transform(self, size: GridCoordinate) -> Gridgid

Expresses this rotation as a Gridgid transform which rotates “in place” the points within the volume defined by coordinates in the range [0, size].

That is, a GridAab of that volume will be unchanged by rotation:

use all_is_cubes::block::Resolution;
use all_is_cubes::math::{Face6, GridAab, GridRotation};

let b = GridAab::for_block(Resolution::R8);
let rotation = Face6::PY.clockwise().to_positive_octant_transform(8);
assert_eq!(b.transform(rotation), Some(b));

Such matrices are suitable for rotating the voxels of a block, provided that the voxel coordinates are then transformed with GridMatrix::transform_cube, not GridMatrix::transform_point (due to the lower-corner format of cube coordinates).

let rotation = Face6::PY.clockwise().to_positive_octant_transform(4);
assert_eq!(rotation.transform_cube(Cube::new(0, 0, 0)), Cube::new(3, 0, 0));
assert_eq!(rotation.transform_cube(Cube::new(3, 0, 0)), Cube::new(3, 0, 3));
assert_eq!(rotation.transform_cube(Cube::new(3, 0, 3)), Cube::new(0, 0, 3));
assert_eq!(rotation.transform_cube(Cube::new(0, 0, 3)), Cube::new(0, 0, 0));

pub fn to_rotation_matrix(self) -> GridMatrix

Expresses this rotation as a matrix without any translation.

pub fn transform(self, face: Face6) -> Face6

Rotate the face by this rotation.

pub fn transform_vector(self, vector: GridVector) -> GridVector

Rotate the vector by this rotation.

May panic or wrap if vector has any components equal to GridCoordinate::MIN.

pub fn checked_transform_vector(self, vector: GridVector) -> Option<GridVector>

Rotate the vector by this rotation.

Returns None if vector has any components equal to GridCoordinate::MIN, which would overflow.

pub fn transform_size(self, size: GridSize) -> GridSize

Rotate the size value by this rotation.

This is similar to GridRotation::transform_vector() except that the components are only swapped, not negated, and there is no possibility of numeric overflow.

pub const fn is_reflection(self) -> bool

Returns whether this is a reflection.

use all_is_cubes::math::{GridRotation, Face6::*};

assert!(!GridRotation::IDENTITY.is_reflection());
assert!(!GridRotation::from_basis([PX, PZ, NY]).is_reflection());
assert!(GridRotation::from_basis([PX, PZ, PY]).is_reflection());

pub const fn inverse(self) -> Self

Returns the inverse of this rotation; the one which undoes this.

use all_is_cubes::math::GridRotation;

for &rotation in &GridRotation::ALL {
    assert_eq!(rotation * rotation.inverse(), GridRotation::IDENTITY);
}

pub fn iterate(self) -> impl Iterator<Item = Self>

Generates the sequence of rotations that may be obtained by concatenating/multiplying this rotation with itself repeatedly.

The first element of the iterator will always be the identity, i.e. this rotation applied zero times. The iterator ends when the sequence would repeat itself, i.e. just before it would produce the identity again.

Example results of iteration

use all_is_cubes::math::{Face6::*, GridRotation};

// The identity rotation remains itself when iterated.
assert_eq!(
    GridRotation::IDENTITY.iterate().collect::<Vec<_>>(),
    vec![GridRotation::IDENTITY],
);

// Any reflection or 180° rotation will produce itself and the identity.
let x_reflection = GridRotation::from_basis([NX, PY, PZ]);
assert_eq!(
    x_reflection.iterate().collect::<Vec<_>>(),
    vec![GridRotation::IDENTITY, x_reflection],
);

// Any 90° rotation produces four distinct rotations.
assert_eq!(
    PY.clockwise().iterate().collect::<Vec<_>>(),
    vec![
        GridRotation::IDENTITY,
        PY.clockwise(),
        PY.r180(),
        PY.counterclockwise(),
   ],
);

Trait Implementations

impl Clone for GridRotation

fn clone(&self) -> GridRotation

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for GridRotation

impl Debug for GridRotation

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

Formats the value using the given formatter.

impl Default for GridRotation

fn default() -> Self

Returns the identity (no rotation).

impl Eq for GridRotation

impl From<GridRotation> for Gridgid

fn from(value: GridRotation) -> Self

Converts to this type from the input type.

impl Hash for GridRotation

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Mul for GridRotation

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

Multiplication is concatenation: self * rhs is equivalent to applying rhs and then applying self.

use all_is_cubes::math::{Face6, Face6::*, GridRotation, GridPoint};

let transform_1 = GridRotation::from_basis([NY, PX, PZ]);
let transform_2 = GridRotation::from_basis([PY, PZ, PX]);

// Demonstrate the directionality of concatenation.
for face in Face6::ALL {
    assert_eq!(
        (transform_1 * transform_2).transform(face),
        transform_1.transform(transform_2.transform(face)),
    );
}

type Output = GridRotation

The resulting type after applying the * operator.

impl One for GridRotation

fn one() -> Self

Returns the identity (no rotation).

fn set_one(&mut self)

Sets self to the multiplicative identity element of Self, 1.

fn is_one(&self) -> bool

where Self: PartialEq,

Returns true if self is equal to the multiplicative identity.

impl PartialEq for GridRotation

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