graphene/auto/

matrix.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{ffi, Box, Euler, Point, Point3D, Quad, Quaternion, Ray, Rect, Sphere, Vec3, Vec4};
use glib::translate::*;

glib::wrapper! {
    /// A structure capable of holding a 4x4 matrix.
    ///
    /// The contents of the [`Matrix`][crate::Matrix] structure are private and
    /// should never be accessed directly.
    pub struct Matrix(BoxedInline<ffi::graphene_matrix_t>);

    match fn {
        copy => |ptr| glib::gobject_ffi::g_boxed_copy(ffi::graphene_matrix_get_type(), ptr as *mut _) as *mut ffi::graphene_matrix_t,
        free => |ptr| glib::gobject_ffi::g_boxed_free(ffi::graphene_matrix_get_type(), ptr as *mut _),
        type_ => || ffi::graphene_matrix_get_type(),
    }
}

impl Matrix {
    /// Decomposes a transformation matrix into its component transformations.
    ///
    /// The algorithm for decomposing a matrix is taken from the
    /// [CSS3 Transforms specification](http://dev.w3.org/csswg/css-transforms/);
    /// specifically, the decomposition code is based on the equivalent code
    /// published in "Graphics Gems II", edited by Jim Arvo, and
    /// [available online](http://web.archive.org/web/20150512160205/http://tog.acm.org/resources/GraphicsGems/gemsii/unmatrix.c).
    ///
    /// # 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
    #[doc(alias = "graphene_matrix_decompose")]
    pub fn decompose(&self) -> Option<(Vec3, Vec3, Quaternion, Vec3, Vec4)> {
        unsafe {
            let mut translate = Vec3::uninitialized();
            let mut scale = Vec3::uninitialized();
            let mut rotate = Quaternion::uninitialized();
            let mut shear = Vec3::uninitialized();
            let mut perspective = Vec4::uninitialized();
            let ret = ffi::graphene_matrix_decompose(
                self.to_glib_none().0,
                translate.to_glib_none_mut().0,
                scale.to_glib_none_mut().0,
                rotate.to_glib_none_mut().0,
                shear.to_glib_none_mut().0,
                perspective.to_glib_none_mut().0,
            );
            if ret {
                Some((translate, scale, rotate, shear, perspective))
            } else {
                None
            }
        }
    }

    /// Computes the determinant of the given matrix.
    ///
    /// # Returns
    ///
    /// the value of the determinant
    #[doc(alias = "graphene_matrix_determinant")]
    pub fn determinant(&self) -> f32 {
        unsafe { ffi::graphene_matrix_determinant(self.to_glib_none().0) }
    }

    #[doc(alias = "graphene_matrix_equal")]
    fn equal(&self, b: &Matrix) -> bool {
        unsafe { ffi::graphene_matrix_equal(self.to_glib_none().0, b.to_glib_none().0) }
    }

    /// Checks whether the two given [`Matrix`][crate::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()`][Self::near()]. For instance:
    ///
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```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`][crate::Matrix]
    ///
    /// # Returns
    ///
    /// `true` if the matrices are equal. and `false` otherwise
    #[doc(alias = "graphene_matrix_equal_fast")]
    pub fn equal_fast(&self, b: &Matrix) -> bool {
        unsafe { ffi::graphene_matrix_equal_fast(self.to_glib_none().0, b.to_glib_none().0) }
    }

    /// 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`][crate::Vec4]
    ///  that is used to store the row vector
    #[doc(alias = "graphene_matrix_get_row")]
    #[doc(alias = "get_row")]
    pub fn row(&self, index_: u32) -> Vec4 {
        unsafe {
            let mut res = Vec4::uninitialized();
            ffi::graphene_matrix_get_row(self.to_glib_none().0, index_, res.to_glib_none_mut().0);
            res
        }
    }

    /// 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
    #[doc(alias = "graphene_matrix_get_value")]
    #[doc(alias = "get_value")]
    pub fn value(&self, row: u32, col: u32) -> f32 {
        unsafe { ffi::graphene_matrix_get_value(self.to_glib_none().0, row, col) }
    }

    /// Retrieves the scaling factor on the X axis in `self`.
    ///
    /// # Returns
    ///
    /// the value of the scaling factor
    #[doc(alias = "graphene_matrix_get_x_scale")]
    #[doc(alias = "get_x_scale")]
    pub fn x_scale(&self) -> f32 {
        unsafe { ffi::graphene_matrix_get_x_scale(self.to_glib_none().0) }
    }

    /// Retrieves the translation component on the X axis from `self`.
    ///
    /// # Returns
    ///
    /// the translation component
    #[doc(alias = "graphene_matrix_get_x_translation")]
    #[doc(alias = "get_x_translation")]
    pub fn x_translation(&self) -> f32 {
        unsafe { ffi::graphene_matrix_get_x_translation(self.to_glib_none().0) }
    }

    /// Retrieves the scaling factor on the Y axis in `self`.
    ///
    /// # Returns
    ///
    /// the value of the scaling factor
    #[doc(alias = "graphene_matrix_get_y_scale")]
    #[doc(alias = "get_y_scale")]
    pub fn y_scale(&self) -> f32 {
        unsafe { ffi::graphene_matrix_get_y_scale(self.to_glib_none().0) }
    }

    /// Retrieves the translation component on the Y axis from `self`.
    ///
    /// # Returns
    ///
    /// the translation component
    #[doc(alias = "graphene_matrix_get_y_translation")]
    #[doc(alias = "get_y_translation")]
    pub fn y_translation(&self) -> f32 {
        unsafe { ffi::graphene_matrix_get_y_translation(self.to_glib_none().0) }
    }

    /// Retrieves the scaling factor on the Z axis in `self`.
    ///
    /// # Returns
    ///
    /// the value of the scaling factor
    #[doc(alias = "graphene_matrix_get_z_scale")]
    #[doc(alias = "get_z_scale")]
    pub fn z_scale(&self) -> f32 {
        unsafe { ffi::graphene_matrix_get_z_scale(self.to_glib_none().0) }
    }

    /// Retrieves the translation component on the Z axis from `self`.
    ///
    /// # Returns
    ///
    /// the translation component
    #[doc(alias = "graphene_matrix_get_z_translation")]
    #[doc(alias = "get_z_translation")]
    pub fn z_translation(&self) -> f32 {
        unsafe { ffi::graphene_matrix_get_z_translation(self.to_glib_none().0) }
    }

    /// Linearly interpolates the two given [`Matrix`][crate::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`][crate::Matrix]
    /// ## `factor`
    /// the linear interpolation factor
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the
    ///  interpolated matrix
    #[doc(alias = "graphene_matrix_interpolate")]
    #[must_use]
    pub fn interpolate(&self, b: &Matrix, factor: f64) -> Matrix {
        unsafe {
            let mut res = Matrix::uninitialized();
            ffi::graphene_matrix_interpolate(
                self.to_glib_none().0,
                b.to_glib_none().0,
                factor,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// Inverts the given matrix.
    ///
    /// # Returns
    ///
    /// `true` if the matrix is invertible
    ///
    /// ## `res`
    /// return location for the
    ///  inverse matrix
    #[doc(alias = "graphene_matrix_inverse")]
    pub fn inverse(&self) -> Option<Matrix> {
        unsafe {
            let mut res = Matrix::uninitialized();
            let ret = ffi::graphene_matrix_inverse(self.to_glib_none().0, res.to_glib_none_mut().0);
            if ret {
                Some(res)
            } else {
                None
            }
        }
    }

    /// Checks whether the given [`Matrix`][crate::Matrix] is compatible with an
    /// a 2D affine transformation matrix.
    ///
    /// # Returns
    ///
    /// `true` if the matrix is compatible with an affine
    ///  transformation matrix
    #[doc(alias = "graphene_matrix_is_2d")]
    pub fn is_2d(&self) -> bool {
        unsafe { ffi::graphene_matrix_is_2d(self.to_glib_none().0) }
    }

    /// Checks whether a [`Matrix`][crate::Matrix] has a visible back face.
    ///
    /// # Returns
    ///
    /// `true` if the back face of the matrix is visible
    #[doc(alias = "graphene_matrix_is_backface_visible")]
    pub fn is_backface_visible(&self) -> bool {
        unsafe { ffi::graphene_matrix_is_backface_visible(self.to_glib_none().0) }
    }

    /// Checks whether the given [`Matrix`][crate::Matrix] is the identity matrix.
    ///
    /// # Returns
    ///
    /// `true` if the matrix is the identity matrix
    #[doc(alias = "graphene_matrix_is_identity")]
    pub fn is_identity(&self) -> bool {
        unsafe { ffi::graphene_matrix_is_identity(self.to_glib_none().0) }
    }

    /// Checks whether a matrix is singular.
    ///
    /// # Returns
    ///
    /// `true` if the matrix is singular
    #[doc(alias = "graphene_matrix_is_singular")]
    pub fn is_singular(&self) -> bool {
        unsafe { ffi::graphene_matrix_is_singular(self.to_glib_none().0) }
    }

    /// Multiplies two [`Matrix`][crate::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`][crate::Matrix]
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the matrix
    ///  result
    #[doc(alias = "graphene_matrix_multiply")]
    #[must_use]
    pub fn multiply(&self, b: &Matrix) -> Matrix {
        unsafe {
            let mut res = Matrix::uninitialized();
            ffi::graphene_matrix_multiply(
                self.to_glib_none().0,
                b.to_glib_none().0,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// Compares the two given [`Matrix`][crate::Matrix] matrices and checks
    /// whether their values are within the given `epsilon` of each
    /// other.
    /// ## `b`
    /// a [`Matrix`][crate::Matrix]
    /// ## `epsilon`
    /// the threshold between the two matrices
    ///
    /// # Returns
    ///
    /// `true` if the two matrices are near each other, and
    ///  `false` otherwise
    #[doc(alias = "graphene_matrix_near")]
    pub fn near(&self, b: &Matrix, epsilon: f32) -> bool {
        unsafe { ffi::graphene_matrix_near(self.to_glib_none().0, b.to_glib_none().0, epsilon) }
    }

    /// Normalizes the given [`Matrix`][crate::Matrix].
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the normalized matrix
    #[doc(alias = "graphene_matrix_normalize")]
    #[must_use]
    pub fn normalize(&self) -> Matrix {
        unsafe {
            let mut res = Matrix::uninitialized();
            ffi::graphene_matrix_normalize(self.to_glib_none().0, res.to_glib_none_mut().0);
            res
        }
    }

    /// Applies a perspective of `depth` to the matrix.
    /// ## `depth`
    /// the depth of the perspective
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the
    ///  perspective matrix
    #[doc(alias = "graphene_matrix_perspective")]
    #[must_use]
    pub fn perspective(&self, depth: f32) -> Matrix {
        unsafe {
            let mut res = Matrix::uninitialized();
            ffi::graphene_matrix_perspective(
                self.to_glib_none().0,
                depth,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// 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.
    #[doc(alias = "graphene_matrix_print")]
    pub fn print(&self) {
        unsafe {
            ffi::graphene_matrix_print(self.to_glib_none().0);
        }
    }

    /// Projects a [`Point`][crate::Point] using the matrix `self`.
    /// ## `p`
    /// a [`Point`][crate::Point]
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the projected
    ///  point
    #[doc(alias = "graphene_matrix_project_point")]
    pub fn project_point(&self, p: &Point) -> Point {
        unsafe {
            let mut res = Point::uninitialized();
            ffi::graphene_matrix_project_point(
                self.to_glib_none().0,
                p.to_glib_none().0,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// Projects all corners of a [`Rect`][crate::Rect] using the given matrix.
    ///
    /// See also: [`project_point()`][Self::project_point()]
    /// ## `r`
    /// a [`Rect`][crate::Rect]
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the projected
    ///  rectangle
    #[doc(alias = "graphene_matrix_project_rect")]
    pub fn project_rect(&self, r: &Rect) -> Quad {
        unsafe {
            let mut res = Quad::uninitialized();
            ffi::graphene_matrix_project_rect(
                self.to_glib_none().0,
                r.to_glib_none().0,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// Projects a [`Rect`][crate::Rect] using the given matrix.
    ///
    /// The resulting rectangle is the axis aligned bounding rectangle capable
    /// of fully containing the projected rectangle.
    /// ## `r`
    /// a [`Rect`][crate::Rect]
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the projected
    ///  rectangle
    #[doc(alias = "graphene_matrix_project_rect_bounds")]
    pub fn project_rect_bounds(&self, r: &Rect) -> Rect {
        unsafe {
            let mut res = Rect::uninitialized();
            ffi::graphene_matrix_project_rect_bounds(
                self.to_glib_none().0,
                r.to_glib_none().0,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// Adds a rotation transformation to `self`, using the given `angle`
    /// and `axis` vector.
    ///
    /// This is the equivalent of calling [`new_rotate()`][Self::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`][crate::Vec3]
    #[doc(alias = "graphene_matrix_rotate")]
    pub fn rotate(&mut self, angle: f32, axis: &Vec3) {
        unsafe {
            ffi::graphene_matrix_rotate(self.to_glib_none_mut().0, angle, axis.to_glib_none().0);
        }
    }

    /// Adds a rotation transformation to `self`, using the given
    /// [`Euler`][crate::Euler].
    /// ## `e`
    /// a rotation described by a [`Euler`][crate::Euler]
    #[doc(alias = "graphene_matrix_rotate_euler")]
    pub fn rotate_euler(&mut self, e: &Euler) {
        unsafe {
            ffi::graphene_matrix_rotate_euler(self.to_glib_none_mut().0, e.to_glib_none().0);
        }
    }

    /// Adds a rotation transformation to `self`, using the given
    /// [`Quaternion`][crate::Quaternion].
    ///
    /// This is the equivalent of calling [`Quaternion::to_matrix()`][crate::Quaternion::to_matrix()] and
    /// then multiplying `self` with the rotation matrix.
    /// ## `q`
    /// a rotation described by a [`Quaternion`][crate::Quaternion]
    #[doc(alias = "graphene_matrix_rotate_quaternion")]
    pub fn rotate_quaternion(&mut self, q: &Quaternion) {
        unsafe {
            ffi::graphene_matrix_rotate_quaternion(self.to_glib_none_mut().0, q.to_glib_none().0);
        }
    }

    /// Adds a rotation transformation around the X axis to `self`, using
    /// the given `angle`.
    ///
    /// See also: [`rotate()`][Self::rotate()]
    /// ## `angle`
    /// the rotation angle, in degrees
    #[doc(alias = "graphene_matrix_rotate_x")]
    pub fn rotate_x(&mut self, angle: f32) {
        unsafe {
            ffi::graphene_matrix_rotate_x(self.to_glib_none_mut().0, angle);
        }
    }

    /// Adds a rotation transformation around the Y axis to `self`, using
    /// the given `angle`.
    ///
    /// See also: [`rotate()`][Self::rotate()]
    /// ## `angle`
    /// the rotation angle, in degrees
    #[doc(alias = "graphene_matrix_rotate_y")]
    pub fn rotate_y(&mut self, angle: f32) {
        unsafe {
            ffi::graphene_matrix_rotate_y(self.to_glib_none_mut().0, angle);
        }
    }

    /// Adds a rotation transformation around the Z axis to `self`, using
    /// the given `angle`.
    ///
    /// See also: [`rotate()`][Self::rotate()]
    /// ## `angle`
    /// the rotation angle, in degrees
    #[doc(alias = "graphene_matrix_rotate_z")]
    pub fn rotate_z(&mut self, angle: f32) {
        unsafe {
            ffi::graphene_matrix_rotate_z(self.to_glib_none_mut().0, angle);
        }
    }

    /// Adds a scaling transformation to `self`, using the three
    /// given factors.
    ///
    /// This is the equivalent of calling [`new_scale()`][Self::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
    #[doc(alias = "graphene_matrix_scale")]
    pub fn scale(&mut self, factor_x: f32, factor_y: f32, factor_z: f32) {
        unsafe {
            ffi::graphene_matrix_scale(self.to_glib_none_mut().0, factor_x, factor_y, factor_z);
        }
    }

    /// Adds a skew of `factor` on the X and Y axis to the given matrix.
    /// ## `factor`
    /// skew factor
    #[doc(alias = "graphene_matrix_skew_xy")]
    pub fn skew_xy(&mut self, factor: f32) {
        unsafe {
            ffi::graphene_matrix_skew_xy(self.to_glib_none_mut().0, factor);
        }
    }

    /// Adds a skew of `factor` on the X and Z axis to the given matrix.
    /// ## `factor`
    /// skew factor
    #[doc(alias = "graphene_matrix_skew_xz")]
    pub fn skew_xz(&mut self, factor: f32) {
        unsafe {
            ffi::graphene_matrix_skew_xz(self.to_glib_none_mut().0, factor);
        }
    }

    /// Adds a skew of `factor` on the Y and Z axis to the given matrix.
    /// ## `factor`
    /// skew factor
    #[doc(alias = "graphene_matrix_skew_yz")]
    pub fn skew_yz(&mut self, factor: f32) {
        unsafe {
            ffi::graphene_matrix_skew_yz(self.to_glib_none_mut().0, factor);
        }
    }

    /// Converts a [`Matrix`][crate::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 ⚠️**
    ///
    /// ```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`][crate::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
    #[doc(alias = "graphene_matrix_to_2d")]
    pub fn to_2d(&self) -> Option<(f64, f64, f64, f64, f64, f64)> {
        unsafe {
            let mut xx = std::mem::MaybeUninit::uninit();
            let mut yx = std::mem::MaybeUninit::uninit();
            let mut xy = std::mem::MaybeUninit::uninit();
            let mut yy = std::mem::MaybeUninit::uninit();
            let mut x_0 = std::mem::MaybeUninit::uninit();
            let mut y_0 = std::mem::MaybeUninit::uninit();
            let ret = ffi::graphene_matrix_to_2d(
                self.to_glib_none().0,
                xx.as_mut_ptr(),
                yx.as_mut_ptr(),
                xy.as_mut_ptr(),
                yy.as_mut_ptr(),
                x_0.as_mut_ptr(),
                y_0.as_mut_ptr(),
            );
            if ret {
                Some((
                    xx.assume_init(),
                    yx.assume_init(),
                    xy.assume_init(),
                    yy.assume_init(),
                    x_0.assume_init(),
                    y_0.assume_init(),
                ))
            } else {
                None
            }
        }
    }

    /// Transforms each corner of a [`Rect`][crate::Rect] using the given matrix `self`.
    ///
    /// The result is the axis aligned bounding rectangle containing the coplanar
    /// quadrilateral.
    ///
    /// See also: [`transform_point()`][Self::transform_point()]
    /// ## `r`
    /// a [`Rect`][crate::Rect]
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the bounds
    ///  of the transformed rectangle
    #[doc(alias = "graphene_matrix_transform_bounds")]
    pub fn transform_bounds(&self, r: &Rect) -> Rect {
        unsafe {
            let mut res = Rect::uninitialized();
            ffi::graphene_matrix_transform_bounds(
                self.to_glib_none().0,
                r.to_glib_none().0,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// Transforms the vertices of a [`Box`][crate::Box] using the given matrix `self`.
    ///
    /// The result is the axis aligned bounding box containing the transformed
    /// vertices.
    /// ## `b`
    /// a [`Box`][crate::Box]
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the bounds
    ///  of the transformed box
    #[doc(alias = "graphene_matrix_transform_box")]
    pub fn transform_box(&self, b: &Box) -> Box {
        unsafe {
            let mut res = Box::uninitialized();
            ffi::graphene_matrix_transform_box(
                self.to_glib_none().0,
                b.to_glib_none().0,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// Transforms the given [`Point`][crate::Point] using the matrix `self`.
    ///
    /// Unlike [`transform_vec3()`][Self::transform_vec3()], this function will take into
    /// account the fourth row vector of the [`Matrix`][crate::Matrix] when computing
    /// the dot product of each row vector of the matrix.
    ///
    /// See also: `graphene_simd4x4f_point3_mul()`
    /// ## `p`
    /// a [`Point`][crate::Point]
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the
    ///  transformed [`Point`][crate::Point]
    #[doc(alias = "graphene_matrix_transform_point")]
    pub fn transform_point(&self, p: &Point) -> Point {
        unsafe {
            let mut res = Point::uninitialized();
            ffi::graphene_matrix_transform_point(
                self.to_glib_none().0,
                p.to_glib_none().0,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// Transforms the given [`Point3D`][crate::Point3D] using the matrix `self`.
    ///
    /// Unlike [`transform_vec3()`][Self::transform_vec3()], this function will take into
    /// account the fourth row vector of the [`Matrix`][crate::Matrix] when computing
    /// the dot product of each row vector of the matrix.
    ///
    /// See also: `graphene_simd4x4f_point3_mul()`
    /// ## `p`
    /// a [`Point3D`][crate::Point3D]
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the result
    #[doc(alias = "graphene_matrix_transform_point3d")]
    pub fn transform_point3d(&self, p: &Point3D) -> Point3D {
        unsafe {
            let mut res = Point3D::uninitialized();
            ffi::graphene_matrix_transform_point3d(
                self.to_glib_none().0,
                p.to_glib_none().0,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// Transform a [`Ray`][crate::Ray] using the given matrix `self`.
    /// ## `r`
    /// a [`Ray`][crate::Ray]
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the
    ///  transformed ray
    #[doc(alias = "graphene_matrix_transform_ray")]
    pub fn transform_ray(&self, r: &Ray) -> Ray {
        unsafe {
            let mut res = Ray::uninitialized();
            ffi::graphene_matrix_transform_ray(
                self.to_glib_none().0,
                r.to_glib_none().0,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// Transforms each corner of a [`Rect`][crate::Rect] using the given matrix `self`.
    ///
    /// The result is a coplanar quadrilateral.
    ///
    /// See also: [`transform_point()`][Self::transform_point()]
    /// ## `r`
    /// a [`Rect`][crate::Rect]
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the
    ///  transformed quad
    #[doc(alias = "graphene_matrix_transform_rect")]
    pub fn transform_rect(&self, r: &Rect) -> Quad {
        unsafe {
            let mut res = Quad::uninitialized();
            ffi::graphene_matrix_transform_rect(
                self.to_glib_none().0,
                r.to_glib_none().0,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// Transforms a [`Sphere`][crate::Sphere] using the given matrix `self`. The
    /// result is the bounding sphere containing the transformed sphere.
    /// ## `s`
    /// a [`Sphere`][crate::Sphere]
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the bounds
    ///  of the transformed sphere
    #[doc(alias = "graphene_matrix_transform_sphere")]
    pub fn transform_sphere(&self, s: &Sphere) -> Sphere {
        unsafe {
            let mut res = Sphere::uninitialized();
            ffi::graphene_matrix_transform_sphere(
                self.to_glib_none().0,
                s.to_glib_none().0,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// Transforms the given [`Vec3`][crate::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`][crate::Vec3]
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for a [`Vec3`][crate::Vec3]
    #[doc(alias = "graphene_matrix_transform_vec3")]
    pub fn transform_vec3(&self, v: &Vec3) -> Vec3 {
        unsafe {
            let mut res = Vec3::uninitialized();
            ffi::graphene_matrix_transform_vec3(
                self.to_glib_none().0,
                v.to_glib_none().0,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// Transforms the given [`Vec4`][crate::Vec4] using the matrix `self`.
    ///
    /// See also: `graphene_simd4x4f_vec4_mul()`
    /// ## `v`
    /// a [`Vec4`][crate::Vec4]
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for a [`Vec4`][crate::Vec4]
    #[doc(alias = "graphene_matrix_transform_vec4")]
    pub fn transform_vec4(&self, v: &Vec4) -> Vec4 {
        unsafe {
            let mut res = Vec4::uninitialized();
            ffi::graphene_matrix_transform_vec4(
                self.to_glib_none().0,
                v.to_glib_none().0,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// Adds a translation transformation to `self` using the coordinates
    /// of the given [`Point3D`][crate::Point3D].
    ///
    /// This is the equivalent of calling [`new_translate()`][Self::new_translate()] and
    /// then multiplying `self` with the translation matrix.
    /// ## `pos`
    /// a [`Point3D`][crate::Point3D]
    #[doc(alias = "graphene_matrix_translate")]
    pub fn translate(&mut self, pos: &Point3D) {
        unsafe {
            ffi::graphene_matrix_translate(self.to_glib_none_mut().0, pos.to_glib_none().0);
        }
    }

    /// Transposes the given matrix.
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the
    ///  transposed matrix
    #[doc(alias = "graphene_matrix_transpose")]
    #[must_use]
    pub fn transpose(&self) -> Matrix {
        unsafe {
            let mut res = Matrix::uninitialized();
            ffi::graphene_matrix_transpose(self.to_glib_none().0, res.to_glib_none_mut().0);
            res
        }
    }

    /// Unprojects the given `point` using the `self` matrix and
    /// a `modelview` matrix.
    /// ## `modelview`
    /// a [`Matrix`][crate::Matrix] for the modelview matrix; this is
    ///  the inverse of the modelview used when projecting the point
    /// ## `point`
    /// a [`Point3D`][crate::Point3D] with the coordinates of the point
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the unprojected
    ///  point
    #[doc(alias = "graphene_matrix_unproject_point3d")]
    pub fn unproject_point3d(&self, modelview: &Matrix, point: &Point3D) -> Point3D {
        unsafe {
            let mut res = Point3D::uninitialized();
            ffi::graphene_matrix_unproject_point3d(
                self.to_glib_none().0,
                modelview.to_glib_none().0,
                point.to_glib_none().0,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// Undoes the transformation on the corners of a [`Rect`][crate::Rect] using the
    /// given matrix, within the given axis aligned rectangular `bounds`.
    /// ## `r`
    /// a [`Rect`][crate::Rect]
    /// ## `bounds`
    /// the bounds of the transformation
    ///
    /// # Returns
    ///
    ///
    /// ## `res`
    /// return location for the
    ///  untransformed rectangle
    #[doc(alias = "graphene_matrix_untransform_bounds")]
    pub fn untransform_bounds(&self, r: &Rect, bounds: &Rect) -> Rect {
        unsafe {
            let mut res = Rect::uninitialized();
            ffi::graphene_matrix_untransform_bounds(
                self.to_glib_none().0,
                r.to_glib_none().0,
                bounds.to_glib_none().0,
                res.to_glib_none_mut().0,
            );
            res
        }
    }

    /// Undoes the transformation of a [`Point`][crate::Point] using the
    /// given matrix, within the given axis aligned rectangular `bounds`.
    /// ## `p`
    /// a [`Point`][crate::Point]
    /// ## `bounds`
    /// the bounds of the transformation
    ///
    /// # Returns
    ///
    /// `true` if the point was successfully untransformed
    ///
    /// ## `res`
    /// return location for the
    ///  untransformed point
    #[doc(alias = "graphene_matrix_untransform_point")]
    pub fn untransform_point(&self, p: &Point, bounds: &Rect) -> Option<Point> {
        unsafe {
            let mut res = Point::uninitialized();
            let ret = ffi::graphene_matrix_untransform_point(
                self.to_glib_none().0,
                p.to_glib_none().0,
                bounds.to_glib_none().0,
                res.to_glib_none_mut().0,
            );
            if ret {
                Some(res)
            } else {
                None
            }
        }
    }
}

impl PartialEq for Matrix {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        self.equal(other)
    }
}

impl Eq for Matrix {}