graphene

Struct Matrix

source
pub struct Matrix { /* private fields */ }
Expand description

A structure capable of holding a 4x4 matrix.

The contents of the Matrix structure are private and should never be accessed directly.

GLib type: Inline allocated boxed type with stack copy semantics.

Implementations§

source§

impl Matrix

source

pub fn as_ptr(&self) -> *mut graphene_matrix_t

source

pub unsafe fn from_glib_ptr_borrow<'a>( ptr: *const graphene_matrix_t, ) -> &'a Self

Borrows the underlying C value.

source

pub unsafe fn from_glib_ptr_borrow_mut<'a>( ptr: *mut graphene_matrix_t, ) -> &'a mut Self

Borrows the underlying C value mutably.

source§

impl Matrix

source

pub fn decompose(&self) -> Option<(Vec3, Vec3, Quaternion, Vec3, Vec4)>

Decomposes a transformation matrix into its component transformations.

The algorithm for decomposing a matrix is taken from the CSS3 Transforms specification; specifically, the decomposition code is based on the equivalent code published in “Graphics Gems II”, edited by Jim Arvo, and available online.

§Returns

true if the matrix could be decomposed

§translate

the translation vector

§scale

the scale vector

§rotate

the rotation quaternion

§shear

the shear vector

§perspective

the perspective vector

source

pub fn determinant(&self) -> f32

Computes the determinant of the given matrix.

§Returns

the value of the determinant

source

pub fn equal_fast(&self, b: &Matrix) -> bool

Checks whether the two given Matrix matrices are byte-by-byte equal.

While this function is faster than graphene_matrix_equal(), it can also return false negatives, so it should be used in conjuction with either graphene_matrix_equal() or near(). For instance:

⚠️ The following code is in C ⚠️

  if (graphene_matrix_equal_fast (a, b))
    {
      // matrices are definitely the same
    }
  else
    {
      if (graphene_matrix_equal (a, b))
        // matrices contain the same values within an epsilon of FLT_EPSILON
      else if (graphene_matrix_near (a, b, 0.0001))
        // matrices contain the same values within an epsilon of 0.0001
      else
        // matrices are not equal
    }
§b

a Matrix

§Returns

true if the matrices are equal. and false otherwise

source

pub fn row(&self, index_: u32) -> Vec4

Retrieves the given row vector at index_ inside a matrix.

§index_

the index of the row vector, between 0 and 3

§Returns
§res

return location for the Vec4 that is used to store the row vector

source

pub fn value(&self, row: u32, col: u32) -> f32

Retrieves the value at the given row and col index.

§row

the row index

§col

the column index

§Returns

the value at the given indices

source

pub fn x_scale(&self) -> f32

Retrieves the scaling factor on the X axis in self.

§Returns

the value of the scaling factor

source

pub fn x_translation(&self) -> f32

Retrieves the translation component on the X axis from self.

§Returns

the translation component

source

pub fn y_scale(&self) -> f32

Retrieves the scaling factor on the Y axis in self.

§Returns

the value of the scaling factor

source

pub fn y_translation(&self) -> f32

Retrieves the translation component on the Y axis from self.

§Returns

the translation component

source

pub fn z_scale(&self) -> f32

Retrieves the scaling factor on the Z axis in self.

§Returns

the value of the scaling factor

source

pub fn z_translation(&self) -> f32

Retrieves the translation component on the Z axis from self.

§Returns

the translation component

source

pub fn interpolate(&self, b: &Matrix, factor: f64) -> Matrix

Linearly interpolates the two given Matrix by interpolating the decomposed transformations separately.

If either matrix cannot be reduced to their transformations then the interpolation cannot be performed, and this function will return an identity matrix.

§b

a Matrix

§factor

the linear interpolation factor

§Returns
§res

return location for the interpolated matrix

source

pub fn inverse(&self) -> Option<Matrix>

Inverts the given matrix.

§Returns

true if the matrix is invertible

§res

return location for the inverse matrix

source

pub fn is_2d(&self) -> bool

Checks whether the given Matrix is compatible with an a 2D affine transformation matrix.

§Returns

true if the matrix is compatible with an affine transformation matrix

source

pub fn is_backface_visible(&self) -> bool

Checks whether a Matrix has a visible back face.

§Returns

true if the back face of the matrix is visible

source

pub fn is_identity(&self) -> bool

Checks whether the given Matrix is the identity matrix.

§Returns

true if the matrix is the identity matrix

source

pub fn is_singular(&self) -> bool

Checks whether a matrix is singular.

§Returns

true if the matrix is singular

source

pub fn multiply(&self, b: &Matrix) -> Matrix

Multiplies two Matrix.

Matrix multiplication is not commutative in general; the order of the factors matters. The product of this multiplication is (self × b)

§b

a Matrix

§Returns
§res

return location for the matrix result

source

pub fn near(&self, b: &Matrix, epsilon: f32) -> bool

Compares the two given Matrix matrices and checks whether their values are within the given epsilon of each other.

§b

a Matrix

§epsilon

the threshold between the two matrices

§Returns

true if the two matrices are near each other, and false otherwise

source

pub fn normalize(&self) -> Matrix

Normalizes the given Matrix.

§Returns
§res

return location for the normalized matrix

source

pub fn perspective(&self, depth: f32) -> Matrix

Applies a perspective of depth to the matrix.

§depth

the depth of the perspective

§Returns
§res

return location for the perspective matrix

source

pub fn print(&self)

Prints the contents of a matrix to the standard error stream.

This function is only useful for debugging; there are no guarantees made on the format of the output.

source

pub fn project_point(&self, p: &Point) -> Point

Projects a Point using the matrix self.

§p

a Point

§Returns
§res

return location for the projected point

source

pub fn project_rect(&self, r: &Rect) -> Quad

Projects all corners of a Rect using the given matrix.

See also: project_point()

§r

a Rect

§Returns
§res

return location for the projected rectangle

source

pub fn project_rect_bounds(&self, r: &Rect) -> Rect

Projects a Rect using the given matrix.

The resulting rectangle is the axis aligned bounding rectangle capable of fully containing the projected rectangle.

§r

a Rect

§Returns
§res

return location for the projected rectangle

source

pub fn rotate(&mut self, angle: f32, axis: &Vec3)

Adds a rotation transformation to self, using the given angle and axis vector.

This is the equivalent of calling new_rotate() and then multiplying the matrix self with the rotation matrix.

§angle

the rotation angle, in degrees

§axis

the rotation axis, as a Vec3

source

pub fn rotate_euler(&mut self, e: &Euler)

Adds a rotation transformation to self, using the given Euler.

§e

a rotation described by a Euler

source

pub fn rotate_quaternion(&mut self, q: &Quaternion)

Adds a rotation transformation to self, using the given Quaternion.

This is the equivalent of calling Quaternion::to_matrix() and then multiplying self with the rotation matrix.

§q

a rotation described by a Quaternion

source

pub fn rotate_x(&mut self, angle: f32)

Adds a rotation transformation around the X axis to self, using the given angle.

See also: rotate()

§angle

the rotation angle, in degrees

source

pub fn rotate_y(&mut self, angle: f32)

Adds a rotation transformation around the Y axis to self, using the given angle.

See also: rotate()

§angle

the rotation angle, in degrees

source

pub fn rotate_z(&mut self, angle: f32)

Adds a rotation transformation around the Z axis to self, using the given angle.

See also: rotate()

§angle

the rotation angle, in degrees

source

pub fn scale(&mut self, factor_x: f32, factor_y: f32, factor_z: f32)

Adds a scaling transformation to self, using the three given factors.

This is the equivalent of calling new_scale() and then multiplying the matrix self with the scale matrix.

§factor_x

scaling factor on the X axis

§factor_y

scaling factor on the Y axis

§factor_z

scaling factor on the Z axis

source

pub fn skew_xy(&mut self, factor: f32)

Adds a skew of factor on the X and Y axis to the given matrix.

§factor

skew factor

source

pub fn skew_xz(&mut self, factor: f32)

Adds a skew of factor on the X and Z axis to the given matrix.

§factor

skew factor

source

pub fn skew_yz(&mut self, factor: f32)

Adds a skew of factor on the Y and Z axis to the given matrix.

§factor

skew factor

source

pub fn to_2d(&self) -> Option<(f64, f64, f64, f64, f64, f64)>

Converts a Matrix to an affine transformation matrix, if the given matrix is compatible.

The returned values have the following layout:

⚠️ The following code is in plain ⚠️

  ⎛ xx  yx ⎞   ⎛  a   b  0 ⎞
  ⎜ xy  yy ⎟ = ⎜  c   d  0 ⎟
  ⎝ x0  y0 ⎠   ⎝ tx  ty  1 ⎠

This function can be used to convert between a Matrix and an affine matrix type from other libraries.

§Returns

true if the matrix is compatible with an affine transformation matrix

§xx

return location for the xx member

§yx

return location for the yx member

§xy

return location for the xy member

§yy

return location for the yy member

§x_0

return location for the x0 member

§y_0

return location for the y0 member

source

pub fn transform_bounds(&self, r: &Rect) -> Rect

Transforms each corner of a Rect using the given matrix self.

The result is the axis aligned bounding rectangle containing the coplanar quadrilateral.

See also: transform_point()

§r

a Rect

§Returns
§res

return location for the bounds of the transformed rectangle

source

pub fn transform_box(&self, b: &Box) -> Box

Transforms the vertices of a Box using the given matrix self.

The result is the axis aligned bounding box containing the transformed vertices.

§b

a Box

§Returns
§res

return location for the bounds of the transformed box

source

pub fn transform_point(&self, p: &Point) -> Point

Transforms the given Point using the matrix self.

Unlike transform_vec3(), this function will take into account the fourth row vector of the Matrix when computing the dot product of each row vector of the matrix.

See also: graphene_simd4x4f_point3_mul()

§p

a Point

§Returns
§res

return location for the transformed Point

source

pub fn transform_point3d(&self, p: &Point3D) -> Point3D

Transforms the given Point3D using the matrix self.

Unlike transform_vec3(), this function will take into account the fourth row vector of the Matrix when computing the dot product of each row vector of the matrix.

See also: graphene_simd4x4f_point3_mul()

§p

a Point3D

§Returns
§res

return location for the result

source

pub fn transform_ray(&self, r: &Ray) -> Ray

Transform a Ray using the given matrix self.

§r

a Ray

§Returns
§res

return location for the transformed ray

source

pub fn transform_rect(&self, r: &Rect) -> Quad

Transforms each corner of a Rect using the given matrix self.

The result is a coplanar quadrilateral.

See also: transform_point()

§r

a Rect

§Returns
§res

return location for the transformed quad

source

pub fn transform_sphere(&self, s: &Sphere) -> Sphere

Transforms a Sphere using the given matrix self. The result is the bounding sphere containing the transformed sphere.

§s

a Sphere

§Returns
§res

return location for the bounds of the transformed sphere

source

pub fn transform_vec3(&self, v: &Vec3) -> Vec3

Transforms the given Vec3 using the matrix self.

This function will multiply the X, Y, and Z row vectors of the matrix self with the corresponding components of the vector v. The W row vector will be ignored.

See also: graphene_simd4x4f_vec3_mul()

§v

a Vec3

§Returns
§res

return location for a Vec3

source

pub fn transform_vec4(&self, v: &Vec4) -> Vec4

Transforms the given Vec4 using the matrix self.

See also: graphene_simd4x4f_vec4_mul()

§v

a Vec4

§Returns
§res

return location for a Vec4

source

pub fn translate(&mut self, pos: &Point3D)

Adds a translation transformation to self using the coordinates of the given Point3D.

This is the equivalent of calling new_translate() and then multiplying self with the translation matrix.

§pos

a Point3D

source

pub fn transpose(&self) -> Matrix

Transposes the given matrix.

§Returns
§res

return location for the transposed matrix

source

pub fn unproject_point3d(&self, modelview: &Matrix, point: &Point3D) -> Point3D

Unprojects the given point using the self matrix and a modelview matrix.

§modelview

a Matrix for the modelview matrix; this is the inverse of the modelview used when projecting the point

§point

a Point3D with the coordinates of the point

§Returns
§res

return location for the unprojected point

source

pub fn untransform_bounds(&self, r: &Rect, bounds: &Rect) -> Rect

Undoes the transformation on the corners of a Rect using the given matrix, within the given axis aligned rectangular bounds.

§r

a Rect

§bounds

the bounds of the transformation

§Returns
§res

return location for the untransformed rectangle

source

pub fn untransform_point(&self, p: &Point, bounds: &Rect) -> Option<Point>

Undoes the transformation of a Point using the given matrix, within the given axis aligned rectangular bounds.

§p

a Point

§bounds

the bounds of the transformation

§Returns

true if the point was successfully untransformed

§res

return location for the untransformed point

source§

impl Matrix

source

pub fn from_2d(xx: f64, yx: f64, xy: f64, yy: f64, x_0: f64, y_0: f64) -> Self

Initializes a Matrix from the values of an affine transformation matrix.

The arguments map to the following matrix layout:

⚠️ The following code is in plain ⚠️

  ⎛ xx  yx ⎞   ⎛  a   b  0 ⎞
  ⎜ xy  yy ⎟ = ⎜  c   d  0 ⎟
  ⎝ x0  y0 ⎠   ⎝ tx  ty  1 ⎠

This function can be used to convert between an affine matrix type from other libraries and a Matrix.

§xx

the xx member

§yx

the yx member

§xy

the xy member

§yy

the yy member

§x_0

the x0 member

§y_0

the y0 member

§Returns

the initialized matrix

source

pub fn from_float(v: [f32; 16]) -> Self

Initializes a Matrix with the given array of floating point values.

§v

an array of at least 16 floating point values

§Returns

the initialized matrix

source

pub fn from_vec4(v0: &Vec4, v1: &Vec4, v2: &Vec4, v3: &Vec4) -> Self

Initializes a Matrix with the given four row vectors.

§v0

the first row vector

§v1

the second row vector

§v2

the third row vector

§v3

the fourth row vector

§Returns

the initialized matrix

source

pub fn new_frustum( left: f32, right: f32, bottom: f32, top: f32, z_near: f32, z_far: f32, ) -> Self

Initializes a Matrix compatible with Frustum.

See also: Frustum::from_matrix()

§left

distance of the left clipping plane

distance of the right clipping plane

§bottom

distance of the bottom clipping plane

§top

distance of the top clipping plane

§z_near

distance of the near clipping plane

§z_far

distance of the far clipping plane

§Returns

the initialized matrix

source

pub fn new_identity() -> Self

Initializes a Matrix with the identity matrix.

§Returns

the initialized matrix

source

pub fn new_look_at(eye: &Vec3, center: &Vec3, up: &Vec3) -> Self

Initializes a Matrix so that it positions the “camera” at the given eye coordinates towards an object at the center coordinates. The top of the camera is aligned to the direction of the up vector.

Before the transform, the camera is assumed to be placed at the origin, looking towards the negative Z axis, with the top side of the camera facing in the direction of the Y axis and the right side in the direction of the X axis.

In theory, one could use self to transform a model of such a camera into world-space. However, it is more common to use the inverse of self to transform another object from world coordinates to the view coordinates of the camera. Typically you would then apply the camera projection transform to get from view to screen coordinates.

§eye

the vector describing the position to look from

§center

the vector describing the position to look at

§up

the vector describing the world’s upward direction; usually, this is the Vec3::y_axis() vector

§Returns

the initialized matrix

source

pub fn new_ortho( left: f32, right: f32, top: f32, bottom: f32, z_near: f32, z_far: f32, ) -> Self

Initializes a Matrix with an orthographic projection.

§left

the left edge of the clipping plane

§right

the right edge of the clipping plane

§top

the top edge of the clipping plane

§bottom

the bottom edge of the clipping plane

§z_near

the distance of the near clipping plane

§z_far

the distance of the far clipping plane

§Returns

the initialized matrix

source

pub fn new_perspective(fovy: f32, aspect: f32, z_near: f32, z_far: f32) -> Self

Initializes a Matrix with a perspective projection.

§fovy

the field of view angle, in degrees

§aspect

the aspect value

§z_near

the near Z plane

§z_far

the far Z plane

§Returns

the initialized matrix

source

pub fn new_rotate(angle: f32, axis: &Vec3) -> Self

Initializes self to represent a rotation of angle degrees on the axis represented by the axis vector.

§angle

the rotation angle, in degrees

§axis

the axis vector as a Vec3

§Returns

the initialized matrix

source

pub fn new_scale(x: f32, y: f32, z: f32) -> Self

Initializes a Matrix with the given scaling factors.

§x

the scale factor on the X axis

§y

the scale factor on the Y axis

§z

the scale factor on the Z axis

§Returns

the initialized matrix

source

pub fn new_skew(x_skew: f32, y_skew: f32) -> Self

Initializes a Matrix with a skew transformation with the given factors.

§x_skew

skew factor, in radians, on the X axis

§y_skew

skew factor, in radians, on the Y axis

§Returns

the initialized matrix

source

pub fn new_translate(p: &Point3D) -> Self

Initializes a Matrix with a translation to the given coordinates.

§p

the translation coordinates

§Returns

the initialized matrix

source

pub fn to_float(&self) -> [f32; 16]

Converts a Matrix to an array of floating point values.

§Returns
§v

return location for an array of floating point values. The array must be capable of holding at least 16 values.

source

pub fn values(&self) -> &[[f32; 4]; 4]

Trait Implementations§

source§

impl Clone for Matrix

source§

fn clone(&self) -> Self

Copies the inline boxed type by value with the type-specific copy function.

1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Matrix

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for Matrix

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

impl HasParamSpec for Matrix

source§

type ParamSpec = ParamSpecBoxed

source§

type SetValue = Matrix

Preferred value to be used as setter for the associated ParamSpec.
source§

type BuilderFn = fn(_: &str) -> ParamSpecBoxedBuilder<'_, Matrix>

source§

fn param_spec_builder() -> Self::BuilderFn

source§

impl PartialEq for Matrix

source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl StaticType for Matrix

source§

fn static_type() -> Type

Returns the type identifier of Self.
source§

impl Copy for Matrix

source§

impl Eq for Matrix

Auto Trait Implementations§

§

impl Freeze for Matrix

§

impl RefUnwindSafe for Matrix

§

impl Send for Matrix

§

impl Sync for Matrix

§

impl Unpin for Matrix

§

impl UnwindSafe for Matrix

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> FromGlibContainerAsVec<<T as GlibPtrDefault>::GlibType, *const GList> for T

source§

impl<T> FromGlibContainerAsVec<<T as GlibPtrDefault>::GlibType, *const GPtrArray> for T

source§

impl<T> FromGlibContainerAsVec<<T as GlibPtrDefault>::GlibType, *const GSList> for T

source§

impl<T> FromGlibContainerAsVec<<T as GlibPtrDefault>::GlibType, *mut GList> for T

source§

impl<T> FromGlibContainerAsVec<<T as GlibPtrDefault>::GlibType, *mut GPtrArray> for T

source§

impl<T> FromGlibContainerAsVec<<T as GlibPtrDefault>::GlibType, *mut GSList> for T

source§

impl<T> FromGlibPtrArrayContainerAsVec<<T as GlibPtrDefault>::GlibType, *const GList> for T

source§

impl<T> FromGlibPtrArrayContainerAsVec<<T as GlibPtrDefault>::GlibType, *const GPtrArray> for T

source§

impl<T> FromGlibPtrArrayContainerAsVec<<T as GlibPtrDefault>::GlibType, *const GSList> for T

source§

impl<T> FromGlibPtrArrayContainerAsVec<<T as GlibPtrDefault>::GlibType, *mut GList> for T

source§

impl<T> FromGlibPtrArrayContainerAsVec<<T as GlibPtrDefault>::GlibType, *mut GPtrArray> for T

source§

impl<T> FromGlibPtrArrayContainerAsVec<<T as GlibPtrDefault>::GlibType, *mut GSList> for T

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoClosureReturnValue for T
where T: Into<Value>,

source§

impl<T> Property for T
where T: HasParamSpec,

source§

type Value = T

source§

impl<T> PropertyGet for T
where T: HasParamSpec,

source§

type Value = T

source§

fn get<R, F>(&self, f: F) -> R
where F: Fn(&<T as PropertyGet>::Value) -> R,

source§

impl<T> StaticTypeExt for T
where T: StaticType,

source§

fn ensure_type()

Ensures that the type has been registered with the type system.
source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToSendValue for T
where T: Send + ToValue + ?Sized,

source§

fn to_send_value(&self) -> SendValue

Returns a SendValue clone of self.
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T> TryFromClosureReturnValue for T
where T: for<'a> FromValue<'a> + StaticType + 'static,

source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

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

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<'a, T, C, E> FromValueOptional<'a> for T
where T: FromValue<'a, Checker = C>, C: ValueTypeChecker<Error = ValueTypeMismatchOrNoneError<E>>, E: Error + Send + 'static,