gsk4/

transform.rs

// Take a look at the license at the top of the repository in the LICENSE file.

use glib::translate::*;

use crate::{ffi, Transform};

impl Transform {
    /// Parses the given @string into a transform and puts it in
    /// @out_transform.
    ///
    /// Strings printed via [`to_str()`][Self::to_str()]
    /// can be read in again successfully using this function.
    ///
    /// If @string does not describe a valid transform, [`false`] is
    /// returned and [`None`] is put in @out_transform.
    /// ## `string`
    /// the string to parse
    ///
    /// # Returns
    ///
    /// [`true`] if @string described a valid transform.
    ///
    /// ## `out_transform`
    /// The location to put the transform in
    #[doc(alias = "gsk_transform_parse")]
    pub fn parse(string: impl IntoGStr) -> Result<Self, glib::BoolError> {
        assert_initialized_main_thread!();
        unsafe {
            string.run_with_gstr(|string| {
                let mut out_transform = std::ptr::null_mut();
                let ret = from_glib(ffi::gsk_transform_parse(
                    string.as_ptr(),
                    &mut out_transform,
                ));
                if ret {
                    Ok(from_glib_full(out_transform))
                } else {
                    Err(glib::bool_error!("Can't parse Transform"))
                }
            })
        }
    }

    /// Inverts the given transform.
    ///
    /// If @self is not invertible, [`None`] is returned.
    /// Note that inverting [`None`] also returns [`None`], which is
    /// the correct inverse of [`None`]. If you need to differentiate
    /// between those cases, you should check @self is not [`None`]
    /// before calling this function.
    ///
    /// This function consumes @self. Use `Gsk::Transform::ref()` first
    /// if you want to keep it around.
    ///
    /// # Returns
    ///
    /// The inverted transform
    #[doc(alias = "gsk_transform_invert")]
    pub fn invert(self) -> Result<Self, glib::BoolError> {
        unsafe {
            let matrix = self.to_matrix();
            if matrix == graphene::Matrix::new_identity() {
                return Ok(self);
            }

            let res: Option<Self> = from_glib_full(ffi::gsk_transform_invert(self.into_glib_ptr()));
            res.ok_or_else(|| glib::bool_error!("Failed to invert the transform"))
        }
    }

    /// Rotates @self @angle degrees in 2D - or in 3D-speak, around the Z axis.
    /// The rotation happens around the origin point of (0, 0).
    ///
    /// This function consumes @self. Use `Gsk::Transform::ref()` first
    /// if you want to keep it around.
    /// ## `angle`
    /// the rotation angle, in degrees (clockwise)
    ///
    /// # Returns
    ///
    /// The new transform
    #[doc(alias = "gsk_transform_rotate")]
    #[must_use]
    pub fn rotate(self, angle: f32) -> Self {
        unsafe {
            let res: Option<Self> =
                from_glib_full(ffi::gsk_transform_rotate(self.into_glib_ptr(), angle));
            res.unwrap_or_default()
        }
    }

    /// Rotates @self @angle degrees around @axis.
    ///
    /// For a rotation in 2D space, use [`rotate()`][Self::rotate()]
    ///
    /// This function consumes @self. Use `Gsk::Transform::ref()` first
    /// if you want to keep it around.
    /// ## `angle`
    /// the rotation angle, in degrees (clockwise)
    /// ## `axis`
    /// The rotation axis
    ///
    /// # Returns
    ///
    /// The new transform
    #[doc(alias = "gsk_transform_rotate_3d")]
    #[must_use]
    pub fn rotate_3d(self, angle: f32, axis: &graphene::Vec3) -> Self {
        unsafe {
            let res: Option<Self> = from_glib_full(ffi::gsk_transform_rotate_3d(
                self.into_glib_ptr(),
                angle,
                axis.to_glib_none().0,
            ));
            res.unwrap_or_default()
        }
    }

    /// Scales @self in 2-dimensional space by the given factors.
    ///
    /// Use [`scale_3d()`][Self::scale_3d()] to scale in all 3 dimensions.
    ///
    /// This function consumes @self. Use `Gsk::Transform::ref()` first
    /// if you want to keep it around.
    /// ## `factor_x`
    /// scaling factor on the X axis
    /// ## `factor_y`
    /// scaling factor on the Y axis
    ///
    /// # Returns
    ///
    /// The new transform
    #[doc(alias = "gsk_transform_scale")]
    #[must_use]
    pub fn scale(self, factor_x: f32, factor_y: f32) -> Self {
        unsafe {
            let res: Option<Self> = from_glib_full(ffi::gsk_transform_scale(
                self.into_glib_ptr(),
                factor_x,
                factor_y,
            ));
            res.unwrap_or_default()
        }
    }

    /// Scales @self by the given factors.
    ///
    /// This function consumes @self. Use `Gsk::Transform::ref()` first
    /// if you want to keep it around.
    /// ## `factor_x`
    /// scaling factor on the X axis
    /// ## `factor_y`
    /// scaling factor on the Y axis
    /// ## `factor_z`
    /// scaling factor on the Z axis
    ///
    /// # Returns
    ///
    /// The new transform
    #[doc(alias = "gsk_transform_scale_3d")]
    #[must_use]
    pub fn scale_3d(self, factor_x: f32, factor_y: f32, factor_z: f32) -> Self {
        unsafe {
            let res: Option<Self> = from_glib_full(ffi::gsk_transform_scale_3d(
                self.into_glib_ptr(),
                factor_x,
                factor_y,
                factor_z,
            ));
            res.unwrap_or_default()
        }
    }

    /// Applies a skew transform.
    ///
    /// This function consumes @self. Use `Gsk::Transform::ref()` first
    /// if you want to keep it around.
    /// ## `skew_x`
    /// skew factor, in degrees, on the X axis
    /// ## `skew_y`
    /// skew factor, in degrees, on the Y axis
    ///
    /// # Returns
    ///
    /// The new transform
    #[cfg(feature = "v4_6")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_6")))]
    #[doc(alias = "gsk_transform_skew")]
    #[must_use]
    pub fn skew(self, skew_x: f32, skew_y: f32) -> Self {
        unsafe {
            let res: Option<Self> = from_glib_full(ffi::gsk_transform_skew(
                self.into_glib_ptr(),
                skew_x,
                skew_y,
            ));
            res.unwrap_or_default()
        }
    }

    /// Applies all the operations from @other to @self.
    ///
    /// This function consumes @self. Use `Gsk::Transform::ref()` first
    /// if you want to keep it around.
    /// ## `other`
    /// Transform to apply
    ///
    /// # Returns
    ///
    /// The new transform
    #[doc(alias = "gsk_transform_transform")]
    #[must_use]
    pub fn transform(self, other: Option<&Self>) -> Self {
        unsafe {
            let res: Option<Self> = from_glib_full(ffi::gsk_transform_transform(
                self.into_glib_ptr(),
                other.to_glib_none().0,
            ));
            res.unwrap_or_default()
        }
    }

    /// Translates @self in 2-dimensional space by @point.
    ///
    /// This function consumes @self. Use `Gsk::Transform::ref()` first
    /// if you want to keep it around.
    /// ## `point`
    /// the point to translate the transform by
    ///
    /// # Returns
    ///
    /// The new transform
    #[doc(alias = "gsk_transform_translate")]
    #[must_use]
    pub fn translate(self, point: &graphene::Point) -> Self {
        unsafe {
            let res: Option<Self> = from_glib_full(ffi::gsk_transform_translate(
                self.into_glib_ptr(),
                point.to_glib_none().0,
            ));
            res.unwrap_or_default()
        }
    }

    /// Translates @self by @point.
    ///
    /// This function consumes @self. Use `Gsk::Transform::ref()` first
    /// if you want to keep it around.
    /// ## `point`
    /// the point to translate the transform by
    ///
    /// # Returns
    ///
    /// The new transform
    #[doc(alias = "gsk_transform_translate_3d")]
    #[must_use]
    pub fn translate_3d(self, point: &graphene::Point3D) -> Self {
        unsafe {
            let res: Option<Self> = from_glib_full(ffi::gsk_transform_translate_3d(
                self.into_glib_ptr(),
                point.to_glib_none().0,
            ));
            res.unwrap_or_default()
        }
    }
}

impl std::str::FromStr for Transform {
    type Err = glib::BoolError;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        skip_assert_initialized!();
        Self::parse(s)
    }
}

#[test]
fn invert_identity_is_identity() {
    let transform = Transform::new();
    let output = transform.clone().invert();
    assert_eq!(output.unwrap(), transform);
}