Enum Face6 

#[repr(u8)]
pub enum Face6 {
    NX = 1,
    NY = 2,
    NZ = 3,
    PX = 4,
    PY = 5,
    PZ = 6,
}

Identifies a face of a cube or an orthogonal unit vector.

See also the similar type Face7, which adds a “zero” or “within the cube” variant. The two enums use the same discriminant numbering.

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

NX = 1

Negative X; the face whose normal vector is (-1, 0, 0).

NY = 2

Negative Y; the face whose normal vector is (0, -1, 0); downward.

NZ = 3

Negative Z; the face whose normal vector is (0, 0, -1).

PX = 4

Positive X; the face whose normal vector is (1, 0, 0).

PY = 5

Positive Y; the face whose normal vector is (0, 1, 0); upward.

PZ = 6

Positive Z; the face whose normal vector is (0, 0, 1).

Implementations

impl Face6

pub const ALL: [Face6; 6]

All the values of Face6.

pub const fn from_discriminant(d: u8) -> Option<Face6>

Inverse function of face as u8, converting the number to Face6.

pub fn from_snapped_vector(vector: Vector3D<f64, Cube>) -> Option<Face6>

Returns the Face6 whose normal vector is closest in direction to the given vector.

Edge cases:

• Ties are broken by preferring Z faces over Y faces, and Y faces over X faces.
• If all magnitudes are zero, the Z axis’s sign is used. (Remember that floating-point numbers include distinct positive and negative zeroes).
• If any coordinate is NaN, returns None.

pub const fn axis(self) -> Axis

Returns which axis this face’s normal vector is parallel to.

pub const fn is_positive(self) -> bool

Returns whether this face is a “positive” face: one whose unit vector’s nonzero coordinate is positive.

use all_is_cubes::math::Face6;

assert_eq!(Face6::PX.is_positive(), true);
assert_eq!(Face6::NX.is_positive(), false);

pub fn is_negative(self) -> bool

Returns whether this face is a negative face: one whose unit vector’s nonzero coordinate is negative.

use all_is_cubes::math::Face6;

assert_eq!(Face6::PX.is_negative(), false);
assert_eq!(Face6::NX.is_negative(), true);

pub const fn opposite(self) -> Face6

Returns the opposite face (maps PX to NX and so on).

pub const fn cross(self, other: Face6) -> Face7

Returns the face whose normal is the cross product of these faces’ normals. Since cross products may be zero, the result is a Face7.

pub fn normal_vector<S, U>(self) -> Vector3D<S, U>

where S: Zero + One + Neg<Output = S>,

Returns the axis-aligned unit vector normal to this face.

If a vector of a different length is desired, use Face6::vector() instead of multiplying this.

pub fn vector<S, U>(self, magnitude: S) -> Vector3D<S, U>

where S: Zero + Neg<Output = S>,

Returns an axis-aligned vector normal to this face, whose magnitude, and only nonzero component, is magnitude.

This is mathematically equivalent to multiplying Face6::normal_vector() by magnitude, but does not perform those multiplications, and may have better type inference.

Example

use all_is_cubes::math::{Face6, GridVector};

assert_eq!(Face6::PY.vector(3), GridVector::new(0, 3, 0));
assert_eq!(Face6::NY.vector(3), GridVector::new(0, -3, 0));

pub fn dot<S, U>(self, vector: Vector3D<S, U>) -> S

where S: Zero + Neg<Output = S>,

Dot product of this face as a unit vector and the given vector, implemented by selecting the relevant component.

use all_is_cubes::math::{Face6, FreeVector};

let sample_vector = FreeVector::new(1.0, 2.0, 5.0_f64);
for face in Face6::ALL {
    assert_eq!(face.dot(sample_vector), face.normal_vector().dot(sample_vector));
}

pub const fn rotation_from_nz(self) -> GridRotation

Returns a rotation, without reflection, which will rotate Face6::NZ to be self.

The significance of this rotation is that it may be used to obtain a set of coordinate systems for all six faces of some cube. It is arbitrary, but convenient to have the arbitrary choice already made.

pub const fn face_transform(self, scale: i32) -> Gridgid

Returns a Gridgid transformation which, if given points on the square with x ∈ [0, scale], y ∈ [0, scale], and z = 0, converts them to points that lie on the faces of the cube with x ∈ [0, scale], y ∈ [0, scale], and z ∈ [0, scale].

Specifically, Face6::NZ.face_transform() is the identity and all others are consistent with that. Note that there are arbitrary choices in the rotation of all other faces. (TODO: Document those choices and test them.)

The rotations used are equal to Face6::rotation_from_nz(), and this method is equivalent to self.rotation_from_nz().to_positive_octant_transform(scale).

To work with floating-point coordinates, use .face_transform().to_matrix().to_free().

pub const fn clockwise(self) -> GridRotation

Returns the rotation which is clockwise, when looking towards the face self of the rotated object.

Example

use all_is_cubes::math::Face6::*;

assert_eq!(PY.clockwise().transform(PX), PZ);

pub const fn counterclockwise(self) -> GridRotation

Returns the rotation which is counterclockwise (anticlockwise), when looking towards the face self of the rotated object.

Example

use all_is_cubes::math::Face6::*;

assert_eq!(PY.counterclockwise().transform(PZ), PX);

pub const fn r180(self) -> GridRotation

Returns the rotation which is a half turn or 180º, when looking towards the face self of the rotated object.

This result only depends on the axis, not the direction, but it is available here to complete the set [self, self.clockwise(), self.r180(), self.counterclockwise()], which can also be expressed as self.clockwise().iterate().

Example

use all_is_cubes::math::Face6::*;

assert_eq!(PY.r180().transform(PX), NX);

Trait Implementations

impl Add<Face6> for Cube

type Output = Cube

The resulting type after applying the + operator.

fn add(self, rhs: Face6) -> <Cube as Add<Face6>>::Output

Performs the + operation.

impl AddAssign<Face6> for Cube

fn add_assign(&mut self, rhs: Face6)

Performs the += operation.

impl<'arbitrary> Arbitrary<'arbitrary> for Face6

fn arbitrary(u: &mut Unstructured<'arbitrary>) -> Result<Face6, Error>

Generate an arbitrary value of Self from the given unstructured data.

fn arbitrary_take_rest(u: Unstructured<'arbitrary>) -> Result<Face6, Error>

Generate an arbitrary value of Self from the entirety of the given unstructured data.

fn size_hint(depth: usize) -> (usize, Option<usize>)

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

fn try_size_hint( depth: usize, ) -> Result<(usize, Option<usize>), MaxRecursionReached>

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

impl Clone for Face6

fn clone(&self) -> Face6

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Face6

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Face6

fn deserialize<__D>( __deserializer: __D, ) -> Result<Face6, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Exhaust for Face6

type Iter = ExhaustFace6Iter

Iterator type returned by Self::exhaust_factories(). See the trait documentation for what properties this iterator should have.

type Factory = ExhaustFace6Factory

Data which can be used to construct Self.

fn exhaust_factories() -> <Face6 as Exhaust>::Iter

Returns an iterator over factories for all values of this type.

fn from_factory(factory: <Face6 as Exhaust>::Factory) -> Face6

Construct a concrete value of this type from a Self::Factory value produced by its Self::Iter.

fn exhaust() -> Iter<Self>

Returns an iterator over all values of this type.

impl From<Face6> for Face7

fn from(value: Face6) -> Face7

Converts to this type from the input type.

impl Hash for Face6

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

where __H: Hasher,

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<V> Index<Face6> for FaceMap<V>

type Output = V

The returned type after indexing.

fn index(&self, face: Face6) -> &V

Performs the indexing (container[index]) operation.

impl<V> IndexMut<Face6> for FaceMap<V>

fn index_mut(&mut self, face: Face6) -> &mut V

Performs the mutable indexing (container[index]) operation.

impl Neg for Face6

type Output = Face6

The resulting type after applying the - operator.

fn neg(self) -> <Face6 as Neg>::Output

Performs the unary - operation.

impl PartialEq for Face6

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

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 TryFrom<Face7> for Face6

type Error = Faceless

The type returned in the event of a conversion error.

fn try_from(value: Face7) -> Result<Face6, <Face6 as TryFrom<Face7>>::Error>

Performs the conversion.

impl TryFrom<Vector3D<i32, Cube>> for Face6

type Error = Vector3D<i32, Cube>

Returns the original vector on failure. (An error message would probably be too lacking context to be helpful.)

fn try_from( value: Vector3D<i32, Cube>, ) -> Result<Face6, <Face6 as TryFrom<Vector3D<i32, Cube>>>::Error>

Recovers a Face6 from its corresponding unit normal vector. All other vectors are rejected.

use all_is_cubes::math::{Face6, GridVector};

// A Face6 may be converted from its normal vector.
for face in Face6::ALL {
    assert_eq!(Face6::try_from(face.normal_vector()), Ok(face));
}

// If the vector does not correspond to any Face6, it is returned.
let v = GridVector::new(1, 2, 3);
assert_eq!(Face6::try_from(v), Err(v));

impl Copy for Face6

impl Eq for Face6

impl StructuralPartialEq for Face6