gsk4/auto/
transform.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, TransformCategory};
6use glib::translate::*;
7
8glib::wrapper! {
9    /// An object to describe transform matrices.
10    ///
11    /// Unlike [`graphene::Matrix`][crate::graphene::Matrix], [`Transform`][crate::Transform] retains the steps in how
12    /// a transform was constructed, and allows inspecting them. It is modeled
13    /// after the way CSS describes transforms.
14    ///
15    /// [`Transform`][crate::Transform] objects are immutable and cannot be changed after creation.
16    /// This means code can safely expose them as properties of objects without
17    /// having to worry about others changing them.
18    #[derive(Debug, PartialOrd, Ord, Hash)]
19    pub struct Transform(Shared<ffi::GskTransform>);
20
21    match fn {
22        ref => |ptr| ffi::gsk_transform_ref(ptr),
23        unref => |ptr| ffi::gsk_transform_unref(ptr),
24        type_ => || ffi::gsk_transform_get_type(),
25    }
26}
27
28impl Transform {
29    /// Creates a new identity transform.
30    ///
31    /// This function is meant to be used by language
32    /// bindings. For C code, this is equivalent to using `NULL`.
33    ///
34    /// # Returns
35    ///
36    /// A new identity transform
37    #[doc(alias = "gsk_transform_new")]
38    pub fn new() -> Transform {
39        assert_initialized_main_thread!();
40        unsafe { from_glib_full(ffi::gsk_transform_new()) }
41    }
42
43    #[doc(alias = "gsk_transform_equal")]
44    fn equal(&self, second: &Transform) -> bool {
45        unsafe {
46            from_glib(ffi::gsk_transform_equal(
47                self.to_glib_none().0,
48                second.to_glib_none().0,
49            ))
50        }
51    }
52
53    /// Returns the category this transform belongs to.
54    ///
55    /// # Returns
56    ///
57    /// The category of the transform
58    #[doc(alias = "gsk_transform_get_category")]
59    #[doc(alias = "get_category")]
60    pub fn category(&self) -> TransformCategory {
61        unsafe { from_glib(ffi::gsk_transform_get_category(self.to_glib_none().0)) }
62    }
63
64    /// Multiplies @self with the given @matrix.
65    ///
66    /// This function consumes @self. Use `Gsk::Transform::ref()` first
67    /// if you want to keep it around.
68    /// ## `matrix`
69    /// the matrix to multiply @self with
70    ///
71    /// # Returns
72    ///
73    /// The new transform
74    #[doc(alias = "gsk_transform_matrix")]
75    #[must_use]
76    pub fn matrix(self, matrix: &graphene::Matrix) -> Transform {
77        unsafe {
78            from_glib_full(ffi::gsk_transform_matrix(
79                self.into_glib_ptr(),
80                matrix.to_glib_none().0,
81            ))
82        }
83    }
84
85    /// Applies a perspective projection transform.
86    ///
87    /// This transform scales points in X and Y based on their Z value,
88    /// scaling points with positive Z values away from the origin, and
89    /// those with negative Z values towards the origin. Points
90    /// on the z=0 plane are unchanged.
91    ///
92    /// This function consumes @self. Use `Gsk::Transform::ref()` first
93    /// if you want to keep it around.
94    /// ## `depth`
95    /// distance of the z=0 plane. Lower values give a more
96    ///   flattened pyramid and therefore a more pronounced
97    ///   perspective effect.
98    ///
99    /// # Returns
100    ///
101    /// The new transform
102    #[doc(alias = "gsk_transform_perspective")]
103    #[must_use]
104    pub fn perspective(self, depth: f32) -> Transform {
105        unsafe { from_glib_full(ffi::gsk_transform_perspective(self.into_glib_ptr(), depth)) }
106    }
107
108    /// Converts a transform to a 2D transformation matrix.
109    ///
110    /// @self must be a 2D transformation. If you are not
111    /// sure, use
112    ///
113    ///     gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D
114    ///
115    /// to check.
116    ///
117    /// The returned values are a subset of the full 4x4 matrix that
118    /// is computed by [`to_matrix()`][Self::to_matrix()] and have the
119    /// following layout:
120    ///
121    /// ```text
122    ///   | xx yx |   |  a  b  0 |
123    ///   | xy yy | = |  c  d  0 |
124    ///   | dx dy |   | tx ty  1 |
125    /// ```
126    ///
127    /// This function can be used to convert between a [`Transform`][crate::Transform]
128    /// and a matrix type from other 2D drawing libraries, in particular
129    /// Cairo.
130    ///
131    /// # Returns
132    ///
133    ///
134    /// ## `out_xx`
135    /// return location for the xx member
136    ///
137    /// ## `out_yx`
138    /// return location for the yx member
139    ///
140    /// ## `out_xy`
141    /// return location for the xy member
142    ///
143    /// ## `out_yy`
144    /// return location for the yy member
145    ///
146    /// ## `out_dx`
147    /// return location for the x0 member
148    ///
149    /// ## `out_dy`
150    /// return location for the y0 member
151    #[doc(alias = "gsk_transform_to_2d")]
152    pub fn to_2d(&self) -> (f32, f32, f32, f32, f32, f32) {
153        unsafe {
154            let mut out_xx = std::mem::MaybeUninit::uninit();
155            let mut out_yx = std::mem::MaybeUninit::uninit();
156            let mut out_xy = std::mem::MaybeUninit::uninit();
157            let mut out_yy = std::mem::MaybeUninit::uninit();
158            let mut out_dx = std::mem::MaybeUninit::uninit();
159            let mut out_dy = std::mem::MaybeUninit::uninit();
160            ffi::gsk_transform_to_2d(
161                self.to_glib_none().0,
162                out_xx.as_mut_ptr(),
163                out_yx.as_mut_ptr(),
164                out_xy.as_mut_ptr(),
165                out_yy.as_mut_ptr(),
166                out_dx.as_mut_ptr(),
167                out_dy.as_mut_ptr(),
168            );
169            (
170                out_xx.assume_init(),
171                out_yx.assume_init(),
172                out_xy.assume_init(),
173                out_yy.assume_init(),
174                out_dx.assume_init(),
175                out_dy.assume_init(),
176            )
177        }
178    }
179
180    /// Converts a transform to 2D transformation factors.
181    ///
182    /// To recreate an equivalent transform from the factors returned
183    /// by this function, use
184    ///
185    ///     gsk_transform_skew (
186    ///         gsk_transform_scale (
187    ///             gsk_transform_rotate (
188    ///                 gsk_transform_translate (NULL, &GRAPHENE_POINT_T (dx, dy)),
189    ///                 angle),
190    ///             scale_x, scale_y),
191    ///         skew_x, skew_y)
192    ///
193    /// @self must be a 2D transformation. If you are not sure, use
194    ///
195    ///     gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D
196    ///
197    /// to check.
198    ///
199    /// # Returns
200    ///
201    ///
202    /// ## `out_skew_x`
203    /// return location for the skew factor
204    ///   in the  x direction
205    ///
206    /// ## `out_skew_y`
207    /// return location for the skew factor
208    ///   in the  y direction
209    ///
210    /// ## `out_scale_x`
211    /// return location for the scale
212    ///   factor in the x direction
213    ///
214    /// ## `out_scale_y`
215    /// return location for the scale
216    ///   factor in the y direction
217    ///
218    /// ## `out_angle`
219    /// return location for the rotation angle
220    ///
221    /// ## `out_dx`
222    /// return location for the translation
223    ///   in the x direction
224    ///
225    /// ## `out_dy`
226    /// return location for the translation
227    ///   in the y direction
228    #[cfg(feature = "v4_6")]
229    #[cfg_attr(docsrs, doc(cfg(feature = "v4_6")))]
230    #[doc(alias = "gsk_transform_to_2d_components")]
231    pub fn to_2d_components(&self) -> (f32, f32, f32, f32, f32, f32, f32) {
232        unsafe {
233            let mut out_skew_x = std::mem::MaybeUninit::uninit();
234            let mut out_skew_y = std::mem::MaybeUninit::uninit();
235            let mut out_scale_x = std::mem::MaybeUninit::uninit();
236            let mut out_scale_y = std::mem::MaybeUninit::uninit();
237            let mut out_angle = std::mem::MaybeUninit::uninit();
238            let mut out_dx = std::mem::MaybeUninit::uninit();
239            let mut out_dy = std::mem::MaybeUninit::uninit();
240            ffi::gsk_transform_to_2d_components(
241                self.to_glib_none().0,
242                out_skew_x.as_mut_ptr(),
243                out_skew_y.as_mut_ptr(),
244                out_scale_x.as_mut_ptr(),
245                out_scale_y.as_mut_ptr(),
246                out_angle.as_mut_ptr(),
247                out_dx.as_mut_ptr(),
248                out_dy.as_mut_ptr(),
249            );
250            (
251                out_skew_x.assume_init(),
252                out_skew_y.assume_init(),
253                out_scale_x.assume_init(),
254                out_scale_y.assume_init(),
255                out_angle.assume_init(),
256                out_dx.assume_init(),
257                out_dy.assume_init(),
258            )
259        }
260    }
261
262    /// Converts a transform to 2D affine transformation factors.
263    ///
264    /// To recreate an equivalent transform from the factors returned
265    /// by this function, use
266    ///
267    ///     gsk_transform_scale (
268    ///         gsk_transform_translate (
269    ///             NULL,
270    ///             &GRAPHENE_POINT_T (dx, dy)),
271    ///         sx, sy)
272    ///
273    /// @self must be a 2D affine transformation. If you are not
274    /// sure, use
275    ///
276    ///     gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D_AFFINE
277    ///
278    /// to check.
279    ///
280    /// # Returns
281    ///
282    ///
283    /// ## `out_scale_x`
284    /// return location for the scale
285    ///   factor in the x direction
286    ///
287    /// ## `out_scale_y`
288    /// return location for the scale
289    ///   factor in the y direction
290    ///
291    /// ## `out_dx`
292    /// return location for the translation
293    ///   in the x direction
294    ///
295    /// ## `out_dy`
296    /// return location for the translation
297    ///   in the y direction
298    #[doc(alias = "gsk_transform_to_affine")]
299    pub fn to_affine(&self) -> (f32, f32, f32, f32) {
300        unsafe {
301            let mut out_scale_x = std::mem::MaybeUninit::uninit();
302            let mut out_scale_y = std::mem::MaybeUninit::uninit();
303            let mut out_dx = std::mem::MaybeUninit::uninit();
304            let mut out_dy = std::mem::MaybeUninit::uninit();
305            ffi::gsk_transform_to_affine(
306                self.to_glib_none().0,
307                out_scale_x.as_mut_ptr(),
308                out_scale_y.as_mut_ptr(),
309                out_dx.as_mut_ptr(),
310                out_dy.as_mut_ptr(),
311            );
312            (
313                out_scale_x.assume_init(),
314                out_scale_y.assume_init(),
315                out_dx.assume_init(),
316                out_dy.assume_init(),
317            )
318        }
319    }
320
321    /// Computes the 4x4 matrix for the transform.
322    ///
323    /// The previous value of @out_matrix will be ignored.
324    ///
325    /// # Returns
326    ///
327    ///
328    /// ## `out_matrix`
329    /// return location for the matrix
330    #[doc(alias = "gsk_transform_to_matrix")]
331    pub fn to_matrix(&self) -> graphene::Matrix {
332        unsafe {
333            let mut out_matrix = graphene::Matrix::uninitialized();
334            ffi::gsk_transform_to_matrix(self.to_glib_none().0, out_matrix.to_glib_none_mut().0);
335            out_matrix
336        }
337    }
338
339    /// Converts the transform into a human-readable string.
340    ///
341    /// The resulting string can be parsed with [`parse()`][Self::parse()].
342    ///
343    /// This is a wrapper around `Gsk::Transform::print()`.
344    ///
345    /// # Returns
346    ///
347    /// A new string for @self
348    #[doc(alias = "gsk_transform_to_string")]
349    #[doc(alias = "to_string")]
350    pub fn to_str(&self) -> glib::GString {
351        unsafe { from_glib_full(ffi::gsk_transform_to_string(self.to_glib_none().0)) }
352    }
353
354    /// Converts a transform to a translation operation.
355    ///
356    /// @self must be a 2D transformation. If you are not
357    /// sure, use
358    ///
359    ///     gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D_TRANSLATE
360    ///
361    /// to check.
362    ///
363    /// # Returns
364    ///
365    ///
366    /// ## `out_dx`
367    /// return location for the translation
368    ///   in the x direction
369    ///
370    /// ## `out_dy`
371    /// return location for the translation
372    ///   in the y direction
373    #[doc(alias = "gsk_transform_to_translate")]
374    pub fn to_translate(&self) -> (f32, f32) {
375        unsafe {
376            let mut out_dx = std::mem::MaybeUninit::uninit();
377            let mut out_dy = std::mem::MaybeUninit::uninit();
378            ffi::gsk_transform_to_translate(
379                self.to_glib_none().0,
380                out_dx.as_mut_ptr(),
381                out_dy.as_mut_ptr(),
382            );
383            (out_dx.assume_init(), out_dy.assume_init())
384        }
385    }
386
387    /// Transforms a rectangle using the given transform.
388    ///
389    /// The result is the bounding box containing the coplanar quad.
390    /// ## `rect`
391    /// the rectangle to transform
392    ///
393    /// # Returns
394    ///
395    ///
396    /// ## `out_rect`
397    /// return location for the bounds
398    ///   of the transformed rectangle
399    #[doc(alias = "gsk_transform_transform_bounds")]
400    pub fn transform_bounds(&self, rect: &graphene::Rect) -> graphene::Rect {
401        unsafe {
402            let mut out_rect = graphene::Rect::uninitialized();
403            ffi::gsk_transform_transform_bounds(
404                self.to_glib_none().0,
405                rect.to_glib_none().0,
406                out_rect.to_glib_none_mut().0,
407            );
408            out_rect
409        }
410    }
411
412    /// Transforms a point using the given transform.
413    /// ## `point`
414    /// the point to transform
415    ///
416    /// # Returns
417    ///
418    ///
419    /// ## `out_point`
420    /// return location for
421    ///   the transformed point
422    #[doc(alias = "gsk_transform_transform_point")]
423    pub fn transform_point(&self, point: &graphene::Point) -> graphene::Point {
424        unsafe {
425            let mut out_point = graphene::Point::uninitialized();
426            ffi::gsk_transform_transform_point(
427                self.to_glib_none().0,
428                point.to_glib_none().0,
429                out_point.to_glib_none_mut().0,
430            );
431            out_point
432        }
433    }
434}
435
436impl Default for Transform {
437    fn default() -> Self {
438        Self::new()
439    }
440}
441
442impl PartialEq for Transform {
443    #[inline]
444    fn eq(&self, other: &Self) -> bool {
445        self.equal(other)
446    }
447}
448
449impl Eq for Transform {}
450
451impl std::fmt::Display for Transform {
452    #[inline]
453    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
454        f.write_str(&self.to_str())
455    }
456}