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}