# Struct graphene::Matrix

``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.

## Implementations§

source§

### impl Matrix

source

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

the scale vector

###### §`rotate`

the rotation quaternion

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
}
``````
##### §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.

the row index

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.

###### §`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`)

##### §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.

###### §`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`.

##### §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()`

##### §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.

##### §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.

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.

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.

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()`

##### §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.

##### §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()`

##### §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()`

##### §Returns
###### §`res`

return location for the result

source

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

Transform a `Ray` using the given matrix `self`.

##### §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()`

##### §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.

##### §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()`

##### §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()`

##### §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.

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`.

###### §`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`.

###### §`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`.

the xx member

the yx member

the xy member

the yy member

the x0 member

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

the aspect value

the near Z plane

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

## Trait Implementations§

source§

### impl Clone for Matrix

source§

#### fn clone(&self) -> Self

Returns a copy of the value. Read more
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

§

§

#### type SetValue = Matrix

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

source§

source§

### impl PartialEq for Matrix

source§

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

This method tests for `self` and `other` values to be equal, and is used by `==`.
1.0.0 · source§

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

This method 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§

source§

§

§

§

§

§

§

## Blanket Implementations§

source§

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

source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
source§

### impl<T> Borrow<T> for Twhere T: ?Sized,

source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

### impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

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

Mutably borrows from an owned value. Read more
source§

### impl<T> From<T> for T

source§

#### fn from(t: T) -> T

Returns the argument unchanged.

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

source§

### impl<T, U> Into<U> for Twhere 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§

source§

source§

§

source§

§

source§

source§

### impl<T> StaticTypeExt for Twhere T: StaticType,

source§

#### fn ensure_type()

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

### impl<T> ToOwned for Twhere T: Clone,

§

#### 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 Twhere T: Send + ToValue + ?Sized,

source§

#### fn to_send_value(&self) -> SendValue

Returns a `SendValue` clone of `self`.
source§

### impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

#### 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§

source§

source§

### impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

#### 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§