gsk4/auto/

transform.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, TransformCategory};
use glib::translate::*;

glib::wrapper! {
    /// An object to describe transform matrices.
    ///
    /// Unlike [`graphene::Matrix`][crate::graphene::Matrix], [`Transform`][crate::Transform] retains the steps in how
    /// a transform was constructed, and allows inspecting them. It is modeled
    /// after the way CSS describes transforms.
    ///
    /// [`Transform`][crate::Transform] objects are immutable and cannot be changed after creation.
    /// This means code can safely expose them as properties of objects without
    /// having to worry about others changing them.
    #[derive(Debug, PartialOrd, Ord, Hash)]
    pub struct Transform(Shared<ffi::GskTransform>);

    match fn {
        ref => |ptr| ffi::gsk_transform_ref(ptr),
        unref => |ptr| ffi::gsk_transform_unref(ptr),
        type_ => || ffi::gsk_transform_get_type(),
    }
}

impl Transform {
    /// Creates a new identity transform.
    ///
    /// This function is meant to be used by language
    /// bindings. For C code, this is equivalent to using `NULL`.
    ///
    /// # Returns
    ///
    /// A new identity transform
    #[doc(alias = "gsk_transform_new")]
    pub fn new() -> Transform {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gsk_transform_new()) }
    }

    #[doc(alias = "gsk_transform_equal")]
    fn equal(&self, second: &Transform) -> bool {
        unsafe {
            from_glib(ffi::gsk_transform_equal(
                self.to_glib_none().0,
                second.to_glib_none().0,
            ))
        }
    }

    /// Returns the category this transform belongs to.
    ///
    /// # Returns
    ///
    /// The category of the transform
    #[doc(alias = "gsk_transform_get_category")]
    #[doc(alias = "get_category")]
    pub fn category(&self) -> TransformCategory {
        unsafe { from_glib(ffi::gsk_transform_get_category(self.to_glib_none().0)) }
    }

    /// Multiplies @self with the given @matrix.
    ///
    /// This function consumes @self. Use `Gsk::Transform::ref()` first
    /// if you want to keep it around.
    /// ## `matrix`
    /// the matrix to multiply @self with
    ///
    /// # Returns
    ///
    /// The new transform
    #[doc(alias = "gsk_transform_matrix")]
    #[must_use]
    pub fn matrix(self, matrix: &graphene::Matrix) -> Transform {
        unsafe {
            from_glib_full(ffi::gsk_transform_matrix(
                self.into_glib_ptr(),
                matrix.to_glib_none().0,
            ))
        }
    }

    /// Applies a perspective projection transform.
    ///
    /// This transform scales points in X and Y based on their Z value,
    /// scaling points with positive Z values away from the origin, and
    /// those with negative Z values towards the origin. Points
    /// on the z=0 plane are unchanged.
    ///
    /// This function consumes @self. Use `Gsk::Transform::ref()` first
    /// if you want to keep it around.
    /// ## `depth`
    /// distance of the z=0 plane. Lower values give a more
    ///   flattened pyramid and therefore a more pronounced
    ///   perspective effect.
    ///
    /// # Returns
    ///
    /// The new transform
    #[doc(alias = "gsk_transform_perspective")]
    #[must_use]
    pub fn perspective(self, depth: f32) -> Transform {
        unsafe { from_glib_full(ffi::gsk_transform_perspective(self.into_glib_ptr(), depth)) }
    }

    /// Converts a transform to a 2D transformation matrix.
    ///
    /// @self must be a 2D transformation. If you are not
    /// sure, use
    ///
    ///     gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D
    ///
    /// to check.
    ///
    /// The returned values are a subset of the full 4x4 matrix that
    /// is computed by [`to_matrix()`][Self::to_matrix()] and have the
    /// following layout:
    ///
    /// ```text
    ///   | xx yx |   |  a  b  0 |
    ///   | xy yy | = |  c  d  0 |
    ///   | dx dy |   | tx ty  1 |
    /// ```
    ///
    /// This function can be used to convert between a [`Transform`][crate::Transform]
    /// and a matrix type from other 2D drawing libraries, in particular
    /// Cairo.
    ///
    /// # Returns
    ///
    ///
    /// ## `out_xx`
    /// return location for the xx member
    ///
    /// ## `out_yx`
    /// return location for the yx member
    ///
    /// ## `out_xy`
    /// return location for the xy member
    ///
    /// ## `out_yy`
    /// return location for the yy member
    ///
    /// ## `out_dx`
    /// return location for the x0 member
    ///
    /// ## `out_dy`
    /// return location for the y0 member
    #[doc(alias = "gsk_transform_to_2d")]
    pub fn to_2d(&self) -> (f32, f32, f32, f32, f32, f32) {
        unsafe {
            let mut out_xx = std::mem::MaybeUninit::uninit();
            let mut out_yx = std::mem::MaybeUninit::uninit();
            let mut out_xy = std::mem::MaybeUninit::uninit();
            let mut out_yy = std::mem::MaybeUninit::uninit();
            let mut out_dx = std::mem::MaybeUninit::uninit();
            let mut out_dy = std::mem::MaybeUninit::uninit();
            ffi::gsk_transform_to_2d(
                self.to_glib_none().0,
                out_xx.as_mut_ptr(),
                out_yx.as_mut_ptr(),
                out_xy.as_mut_ptr(),
                out_yy.as_mut_ptr(),
                out_dx.as_mut_ptr(),
                out_dy.as_mut_ptr(),
            );
            (
                out_xx.assume_init(),
                out_yx.assume_init(),
                out_xy.assume_init(),
                out_yy.assume_init(),
                out_dx.assume_init(),
                out_dy.assume_init(),
            )
        }
    }

    /// Converts a transform to 2D transformation factors.
    ///
    /// To recreate an equivalent transform from the factors returned
    /// by this function, use
    ///
    ///     gsk_transform_skew (
    ///         gsk_transform_scale (
    ///             gsk_transform_rotate (
    ///                 gsk_transform_translate (NULL, &GRAPHENE_POINT_T (dx, dy)),
    ///                 angle),
    ///             scale_x, scale_y),
    ///         skew_x, skew_y)
    ///
    /// @self must be a 2D transformation. If you are not sure, use
    ///
    ///     gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D
    ///
    /// to check.
    ///
    /// # Returns
    ///
    ///
    /// ## `out_skew_x`
    /// return location for the skew factor
    ///   in the  x direction
    ///
    /// ## `out_skew_y`
    /// return location for the skew factor
    ///   in the  y direction
    ///
    /// ## `out_scale_x`
    /// return location for the scale
    ///   factor in the x direction
    ///
    /// ## `out_scale_y`
    /// return location for the scale
    ///   factor in the y direction
    ///
    /// ## `out_angle`
    /// return location for the rotation angle
    ///
    /// ## `out_dx`
    /// return location for the translation
    ///   in the x direction
    ///
    /// ## `out_dy`
    /// return location for the translation
    ///   in the y direction
    #[cfg(feature = "v4_6")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_6")))]
    #[doc(alias = "gsk_transform_to_2d_components")]
    pub fn to_2d_components(&self) -> (f32, f32, f32, f32, f32, f32, f32) {
        unsafe {
            let mut out_skew_x = std::mem::MaybeUninit::uninit();
            let mut out_skew_y = std::mem::MaybeUninit::uninit();
            let mut out_scale_x = std::mem::MaybeUninit::uninit();
            let mut out_scale_y = std::mem::MaybeUninit::uninit();
            let mut out_angle = std::mem::MaybeUninit::uninit();
            let mut out_dx = std::mem::MaybeUninit::uninit();
            let mut out_dy = std::mem::MaybeUninit::uninit();
            ffi::gsk_transform_to_2d_components(
                self.to_glib_none().0,
                out_skew_x.as_mut_ptr(),
                out_skew_y.as_mut_ptr(),
                out_scale_x.as_mut_ptr(),
                out_scale_y.as_mut_ptr(),
                out_angle.as_mut_ptr(),
                out_dx.as_mut_ptr(),
                out_dy.as_mut_ptr(),
            );
            (
                out_skew_x.assume_init(),
                out_skew_y.assume_init(),
                out_scale_x.assume_init(),
                out_scale_y.assume_init(),
                out_angle.assume_init(),
                out_dx.assume_init(),
                out_dy.assume_init(),
            )
        }
    }

    /// Converts a transform to 2D affine transformation factors.
    ///
    /// To recreate an equivalent transform from the factors returned
    /// by this function, use
    ///
    ///     gsk_transform_scale (
    ///         gsk_transform_translate (
    ///             NULL,
    ///             &GRAPHENE_POINT_T (dx, dy)),
    ///         sx, sy)
    ///
    /// @self must be a 2D affine transformation. If you are not
    /// sure, use
    ///
    ///     gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D_AFFINE
    ///
    /// to check.
    ///
    /// # Returns
    ///
    ///
    /// ## `out_scale_x`
    /// return location for the scale
    ///   factor in the x direction
    ///
    /// ## `out_scale_y`
    /// return location for the scale
    ///   factor in the y direction
    ///
    /// ## `out_dx`
    /// return location for the translation
    ///   in the x direction
    ///
    /// ## `out_dy`
    /// return location for the translation
    ///   in the y direction
    #[doc(alias = "gsk_transform_to_affine")]
    pub fn to_affine(&self) -> (f32, f32, f32, f32) {
        unsafe {
            let mut out_scale_x = std::mem::MaybeUninit::uninit();
            let mut out_scale_y = std::mem::MaybeUninit::uninit();
            let mut out_dx = std::mem::MaybeUninit::uninit();
            let mut out_dy = std::mem::MaybeUninit::uninit();
            ffi::gsk_transform_to_affine(
                self.to_glib_none().0,
                out_scale_x.as_mut_ptr(),
                out_scale_y.as_mut_ptr(),
                out_dx.as_mut_ptr(),
                out_dy.as_mut_ptr(),
            );
            (
                out_scale_x.assume_init(),
                out_scale_y.assume_init(),
                out_dx.assume_init(),
                out_dy.assume_init(),
            )
        }
    }

    /// Computes the 4x4 matrix for the transform.
    ///
    /// The previous value of @out_matrix will be ignored.
    ///
    /// # Returns
    ///
    ///
    /// ## `out_matrix`
    /// return location for the matrix
    #[doc(alias = "gsk_transform_to_matrix")]
    pub fn to_matrix(&self) -> graphene::Matrix {
        unsafe {
            let mut out_matrix = graphene::Matrix::uninitialized();
            ffi::gsk_transform_to_matrix(self.to_glib_none().0, out_matrix.to_glib_none_mut().0);
            out_matrix
        }
    }

    /// Converts the transform into a human-readable string.
    ///
    /// The resulting string can be parsed with [`parse()`][Self::parse()].
    ///
    /// This is a wrapper around `Gsk::Transform::print()`.
    ///
    /// # Returns
    ///
    /// A new string for @self
    #[doc(alias = "gsk_transform_to_string")]
    #[doc(alias = "to_string")]
    pub fn to_str(&self) -> glib::GString {
        unsafe { from_glib_full(ffi::gsk_transform_to_string(self.to_glib_none().0)) }
    }

    /// Converts a transform to a translation operation.
    ///
    /// @self must be a 2D transformation. If you are not
    /// sure, use
    ///
    ///     gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D_TRANSLATE
    ///
    /// to check.
    ///
    /// # Returns
    ///
    ///
    /// ## `out_dx`
    /// return location for the translation
    ///   in the x direction
    ///
    /// ## `out_dy`
    /// return location for the translation
    ///   in the y direction
    #[doc(alias = "gsk_transform_to_translate")]
    pub fn to_translate(&self) -> (f32, f32) {
        unsafe {
            let mut out_dx = std::mem::MaybeUninit::uninit();
            let mut out_dy = std::mem::MaybeUninit::uninit();
            ffi::gsk_transform_to_translate(
                self.to_glib_none().0,
                out_dx.as_mut_ptr(),
                out_dy.as_mut_ptr(),
            );
            (out_dx.assume_init(), out_dy.assume_init())
        }
    }

    /// Transforms a rectangle using the given transform.
    ///
    /// The result is the bounding box containing the coplanar quad.
    /// ## `rect`
    /// the rectangle to transform
    ///
    /// # Returns
    ///
    ///
    /// ## `out_rect`
    /// return location for the bounds
    ///   of the transformed rectangle
    #[doc(alias = "gsk_transform_transform_bounds")]
    pub fn transform_bounds(&self, rect: &graphene::Rect) -> graphene::Rect {
        unsafe {
            let mut out_rect = graphene::Rect::uninitialized();
            ffi::gsk_transform_transform_bounds(
                self.to_glib_none().0,
                rect.to_glib_none().0,
                out_rect.to_glib_none_mut().0,
            );
            out_rect
        }
    }

    /// Transforms a point using the given transform.
    /// ## `point`
    /// the point to transform
    ///
    /// # Returns
    ///
    ///
    /// ## `out_point`
    /// return location for
    ///   the transformed point
    #[doc(alias = "gsk_transform_transform_point")]
    pub fn transform_point(&self, point: &graphene::Point) -> graphene::Point {
        unsafe {
            let mut out_point = graphene::Point::uninitialized();
            ffi::gsk_transform_transform_point(
                self.to_glib_none().0,
                point.to_glib_none().0,
                out_point.to_glib_none_mut().0,
            );
            out_point
        }
    }
}

impl Default for Transform {
    fn default() -> Self {
        Self::new()
    }
}

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

impl Eq for Transform {}

impl std::fmt::Display for Transform {
    #[inline]
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        f.write_str(&self.to_str())
    }
}