gtk4/auto/
snapshot.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#![allow(deprecated)]
5
6use crate::{ffi, StyleContext};
7use glib::{prelude::*, translate::*};
8
9glib::wrapper! {
10    /// Assists in creating [`gsk::RenderNode`][crate::gsk::RenderNode]s for widgets.
11    ///
12    /// It functions in a similar way to a cairo context, and maintains a stack
13    /// of render nodes and their associated transformations.
14    ///
15    /// The node at the top of the stack is the one that `gtk_snapshot_append_…()`
16    /// functions operate on. Use the `gtk_snapshot_push_…()` functions and
17    /// [`SnapshotExt::pop()`][crate::prelude::SnapshotExt::pop()] to change the current node.
18    ///
19    /// The typical way to obtain a [`Snapshot`][crate::Snapshot] object is as an argument to
20    /// the [`WidgetImpl::snapshot()`][crate::subclass::prelude::WidgetImpl::snapshot()] vfunc. If you need to create your own
21    /// [`Snapshot`][crate::Snapshot], use [`new()`][Self::new()].
22    ///
23    /// # Implements
24    ///
25    /// [`SnapshotExt`][trait@crate::prelude::SnapshotExt], [`trait@gdk::prelude::SnapshotExt`], [`trait@glib::ObjectExt`], [`SnapshotExtManual`][trait@crate::prelude::SnapshotExtManual]
26    #[doc(alias = "GtkSnapshot")]
27    pub struct Snapshot(Object<ffi::GtkSnapshot, ffi::GtkSnapshotClass>) @extends gdk::Snapshot;
28
29    match fn {
30        type_ => || ffi::gtk_snapshot_get_type(),
31    }
32}
33
34impl Snapshot {
35    pub const NONE: Option<&'static Snapshot> = None;
36
37    /// Creates a new [`Snapshot`][crate::Snapshot].
38    ///
39    /// # Returns
40    ///
41    /// a newly-allocated [`Snapshot`][crate::Snapshot]
42    #[doc(alias = "gtk_snapshot_new")]
43    pub fn new() -> Snapshot {
44        assert_initialized_main_thread!();
45        unsafe { from_glib_full(ffi::gtk_snapshot_new()) }
46    }
47}
48
49impl Default for Snapshot {
50    fn default() -> Self {
51        Self::new()
52    }
53}
54
55/// Trait containing all [`struct@Snapshot`] methods.
56///
57/// # Implementors
58///
59/// [`Snapshot`][struct@crate::Snapshot]
60pub trait SnapshotExt: IsA<Snapshot> + 'static {
61    /// Creates a new [`gsk::CairoNode`][crate::gsk::CairoNode] and appends it to the current
62    /// render node of @self, without changing the current node.
63    /// ## `bounds`
64    /// the bounds for the new node
65    ///
66    /// # Returns
67    ///
68    /// a [`cairo::Context`][crate::cairo::Context] suitable for drawing the contents of
69    ///   the newly created render node
70    #[doc(alias = "gtk_snapshot_append_cairo")]
71    fn append_cairo(&self, bounds: &graphene::Rect) -> cairo::Context {
72        unsafe {
73            from_glib_full(ffi::gtk_snapshot_append_cairo(
74                self.as_ref().to_glib_none().0,
75                bounds.to_glib_none().0,
76            ))
77        }
78    }
79
80    /// Creates a new render node drawing the @color into the
81    /// given @bounds and appends it to the current render node
82    /// of @self.
83    ///
84    /// You should try to avoid calling this function if
85    /// @color is transparent.
86    /// ## `color`
87    /// the color to draw
88    /// ## `bounds`
89    /// the bounds for the new node
90    #[doc(alias = "gtk_snapshot_append_color")]
91    fn append_color(&self, color: &gdk::RGBA, bounds: &graphene::Rect) {
92        unsafe {
93            ffi::gtk_snapshot_append_color(
94                self.as_ref().to_glib_none().0,
95                color.to_glib_none().0,
96                bounds.to_glib_none().0,
97            );
98        }
99    }
100
101    /// Appends a conic gradient node with the given stops to @self.
102    /// ## `bounds`
103    /// the rectangle to render the gradient into
104    /// ## `center`
105    /// the center point of the conic gradient
106    /// ## `rotation`
107    /// the clockwise rotation in degrees of the starting angle.
108    ///   0 means the starting angle is the top.
109    /// ## `stops`
110    /// the color stops defining the gradient
111    #[doc(alias = "gtk_snapshot_append_conic_gradient")]
112    fn append_conic_gradient(
113        &self,
114        bounds: &graphene::Rect,
115        center: &graphene::Point,
116        rotation: f32,
117        stops: &[gsk::ColorStop],
118    ) {
119        let n_stops = stops.len() as _;
120        unsafe {
121            ffi::gtk_snapshot_append_conic_gradient(
122                self.as_ref().to_glib_none().0,
123                bounds.to_glib_none().0,
124                center.to_glib_none().0,
125                rotation,
126                stops.to_glib_none().0,
127                n_stops,
128            );
129        }
130    }
131
132    /// A convenience method to fill a path with a color.
133    ///
134    /// See [`push_fill()`][Self::push_fill()] if you need
135    /// to fill a path with more complex content than
136    /// a color.
137    /// ## `path`
138    /// The path describing the area to fill
139    /// ## `fill_rule`
140    /// The fill rule to use
141    /// ## `color`
142    /// the color to fill the path with
143    #[cfg(feature = "v4_14")]
144    #[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
145    #[doc(alias = "gtk_snapshot_append_fill")]
146    fn append_fill(&self, path: &gsk::Path, fill_rule: gsk::FillRule, color: &gdk::RGBA) {
147        unsafe {
148            ffi::gtk_snapshot_append_fill(
149                self.as_ref().to_glib_none().0,
150                path.to_glib_none().0,
151                fill_rule.into_glib(),
152                color.to_glib_none().0,
153            );
154        }
155    }
156
157    /// Appends an inset shadow into the box given by @outline.
158    /// ## `outline`
159    /// outline of the region surrounded by shadow
160    /// ## `color`
161    /// color of the shadow
162    /// ## `dx`
163    /// horizontal offset of shadow
164    /// ## `dy`
165    /// vertical offset of shadow
166    /// ## `spread`
167    /// how far the shadow spreads towards the inside
168    /// ## `blur_radius`
169    /// how much blur to apply to the shadow
170    #[doc(alias = "gtk_snapshot_append_inset_shadow")]
171    fn append_inset_shadow(
172        &self,
173        outline: &gsk::RoundedRect,
174        color: &gdk::RGBA,
175        dx: f32,
176        dy: f32,
177        spread: f32,
178        blur_radius: f32,
179    ) {
180        unsafe {
181            ffi::gtk_snapshot_append_inset_shadow(
182                self.as_ref().to_glib_none().0,
183                outline.to_glib_none().0,
184                color.to_glib_none().0,
185                dx,
186                dy,
187                spread,
188                blur_radius,
189            );
190        }
191    }
192
193    /// Creates render nodes for rendering @layout in the given foregound @color
194    /// and appends them to the current node of @self without changing the
195    /// current node. The current theme's foreground color for a widget can be
196    /// obtained with [`WidgetExt::color()`][crate::prelude::WidgetExt::color()].
197    ///
198    /// Note that if the layout does not produce any visible output, then nodes
199    /// may not be added to the @self.
200    /// ## `layout`
201    /// the [`pango::Layout`][crate::pango::Layout] to render
202    /// ## `color`
203    /// the foreground color to render the layout in
204    #[doc(alias = "gtk_snapshot_append_layout")]
205    fn append_layout(&self, layout: &pango::Layout, color: &gdk::RGBA) {
206        unsafe {
207            ffi::gtk_snapshot_append_layout(
208                self.as_ref().to_glib_none().0,
209                layout.to_glib_none().0,
210                color.to_glib_none().0,
211            );
212        }
213    }
214
215    /// Appends a linear gradient node with the given stops to @self.
216    /// ## `bounds`
217    /// the rectangle to render the linear gradient into
218    /// ## `start_point`
219    /// the point at which the linear gradient will begin
220    /// ## `end_point`
221    /// the point at which the linear gradient will finish
222    /// ## `stops`
223    /// the color stops defining the gradient
224    #[doc(alias = "gtk_snapshot_append_linear_gradient")]
225    fn append_linear_gradient(
226        &self,
227        bounds: &graphene::Rect,
228        start_point: &graphene::Point,
229        end_point: &graphene::Point,
230        stops: &[gsk::ColorStop],
231    ) {
232        let n_stops = stops.len() as _;
233        unsafe {
234            ffi::gtk_snapshot_append_linear_gradient(
235                self.as_ref().to_glib_none().0,
236                bounds.to_glib_none().0,
237                start_point.to_glib_none().0,
238                end_point.to_glib_none().0,
239                stops.to_glib_none().0,
240                n_stops,
241            );
242        }
243    }
244
245    /// Appends @node to the current render node of @self,
246    /// without changing the current node.
247    ///
248    /// If @self does not have a current node yet, @node
249    /// will become the initial node.
250    /// ## `node`
251    /// a [`gsk::RenderNode`][crate::gsk::RenderNode]
252    #[doc(alias = "gtk_snapshot_append_node")]
253    fn append_node(&self, node: impl AsRef<gsk::RenderNode>) {
254        unsafe {
255            ffi::gtk_snapshot_append_node(
256                self.as_ref().to_glib_none().0,
257                node.as_ref().to_glib_none().0,
258            );
259        }
260    }
261
262    /// Appends an outset shadow node around the box given by @outline.
263    /// ## `outline`
264    /// outline of the region surrounded by shadow
265    /// ## `color`
266    /// color of the shadow
267    /// ## `dx`
268    /// horizontal offset of shadow
269    /// ## `dy`
270    /// vertical offset of shadow
271    /// ## `spread`
272    /// how far the shadow spreads towards the outside
273    /// ## `blur_radius`
274    /// how much blur to apply to the shadow
275    #[doc(alias = "gtk_snapshot_append_outset_shadow")]
276    fn append_outset_shadow(
277        &self,
278        outline: &gsk::RoundedRect,
279        color: &gdk::RGBA,
280        dx: f32,
281        dy: f32,
282        spread: f32,
283        blur_radius: f32,
284    ) {
285        unsafe {
286            ffi::gtk_snapshot_append_outset_shadow(
287                self.as_ref().to_glib_none().0,
288                outline.to_glib_none().0,
289                color.to_glib_none().0,
290                dx,
291                dy,
292                spread,
293                blur_radius,
294            );
295        }
296    }
297
298    /// Appends a radial gradient node with the given stops to @self.
299    /// ## `bounds`
300    /// the rectangle to render the readial gradient into
301    /// ## `center`
302    /// the center point for the radial gradient
303    /// ## `hradius`
304    /// the horizontal radius
305    /// ## `vradius`
306    /// the vertical radius
307    /// ## `start`
308    /// the start position (on the horizontal axis)
309    /// ## `end`
310    /// the end position (on the horizontal axis)
311    /// ## `stops`
312    /// the color stops defining the gradient
313    #[doc(alias = "gtk_snapshot_append_radial_gradient")]
314    fn append_radial_gradient(
315        &self,
316        bounds: &graphene::Rect,
317        center: &graphene::Point,
318        hradius: f32,
319        vradius: f32,
320        start: f32,
321        end: f32,
322        stops: &[gsk::ColorStop],
323    ) {
324        let n_stops = stops.len() as _;
325        unsafe {
326            ffi::gtk_snapshot_append_radial_gradient(
327                self.as_ref().to_glib_none().0,
328                bounds.to_glib_none().0,
329                center.to_glib_none().0,
330                hradius,
331                vradius,
332                start,
333                end,
334                stops.to_glib_none().0,
335                n_stops,
336            );
337        }
338    }
339
340    /// Appends a repeating linear gradient node with the given stops to @self.
341    /// ## `bounds`
342    /// the rectangle to render the linear gradient into
343    /// ## `start_point`
344    /// the point at which the linear gradient will begin
345    /// ## `end_point`
346    /// the point at which the linear gradient will finish
347    /// ## `stops`
348    /// the color stops defining the gradient
349    #[doc(alias = "gtk_snapshot_append_repeating_linear_gradient")]
350    fn append_repeating_linear_gradient(
351        &self,
352        bounds: &graphene::Rect,
353        start_point: &graphene::Point,
354        end_point: &graphene::Point,
355        stops: &[gsk::ColorStop],
356    ) {
357        let n_stops = stops.len() as _;
358        unsafe {
359            ffi::gtk_snapshot_append_repeating_linear_gradient(
360                self.as_ref().to_glib_none().0,
361                bounds.to_glib_none().0,
362                start_point.to_glib_none().0,
363                end_point.to_glib_none().0,
364                stops.to_glib_none().0,
365                n_stops,
366            );
367        }
368    }
369
370    /// Appends a repeating radial gradient node with the given stops to @self.
371    /// ## `bounds`
372    /// the rectangle to render the readial gradient into
373    /// ## `center`
374    /// the center point for the radial gradient
375    /// ## `hradius`
376    /// the horizontal radius
377    /// ## `vradius`
378    /// the vertical radius
379    /// ## `start`
380    /// the start position (on the horizontal axis)
381    /// ## `end`
382    /// the end position (on the horizontal axis)
383    /// ## `stops`
384    /// the color stops defining the gradient
385    #[doc(alias = "gtk_snapshot_append_repeating_radial_gradient")]
386    fn append_repeating_radial_gradient(
387        &self,
388        bounds: &graphene::Rect,
389        center: &graphene::Point,
390        hradius: f32,
391        vradius: f32,
392        start: f32,
393        end: f32,
394        stops: &[gsk::ColorStop],
395    ) {
396        let n_stops = stops.len() as _;
397        unsafe {
398            ffi::gtk_snapshot_append_repeating_radial_gradient(
399                self.as_ref().to_glib_none().0,
400                bounds.to_glib_none().0,
401                center.to_glib_none().0,
402                hradius,
403                vradius,
404                start,
405                end,
406                stops.to_glib_none().0,
407                n_stops,
408            );
409        }
410    }
411
412    /// Creates a new render node drawing the @texture
413    /// into the given @bounds and appends it to the
414    /// current render node of @self.
415    ///
416    /// In contrast to [`append_texture()`][Self::append_texture()],
417    /// this function provides control about how the filter
418    /// that is used when scaling.
419    /// ## `texture`
420    /// the texture to render
421    /// ## `filter`
422    /// the filter to use
423    /// ## `bounds`
424    /// the bounds for the new node
425    #[cfg(feature = "v4_10")]
426    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
427    #[doc(alias = "gtk_snapshot_append_scaled_texture")]
428    fn append_scaled_texture(
429        &self,
430        texture: &impl IsA<gdk::Texture>,
431        filter: gsk::ScalingFilter,
432        bounds: &graphene::Rect,
433    ) {
434        unsafe {
435            ffi::gtk_snapshot_append_scaled_texture(
436                self.as_ref().to_glib_none().0,
437                texture.as_ref().to_glib_none().0,
438                filter.into_glib(),
439                bounds.to_glib_none().0,
440            );
441        }
442    }
443
444    /// A convenience method to stroke a path with a color.
445    ///
446    /// See [`push_stroke()`][Self::push_stroke()] if you need
447    /// to stroke a path with more complex content than
448    /// a color.
449    /// ## `path`
450    /// The path describing the area to fill
451    /// ## `stroke`
452    /// The stroke attributes
453    /// ## `color`
454    /// the color to fill the path with
455    #[cfg(feature = "v4_14")]
456    #[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
457    #[doc(alias = "gtk_snapshot_append_stroke")]
458    fn append_stroke(&self, path: &gsk::Path, stroke: &gsk::Stroke, color: &gdk::RGBA) {
459        unsafe {
460            ffi::gtk_snapshot_append_stroke(
461                self.as_ref().to_glib_none().0,
462                path.to_glib_none().0,
463                stroke.to_glib_none().0,
464                color.to_glib_none().0,
465            );
466        }
467    }
468
469    /// Creates a new render node drawing the @texture
470    /// into the given @bounds and appends it to the
471    /// current render node of @self.
472    ///
473    /// If the texture needs to be scaled to fill @bounds,
474    /// linear filtering is used. See [`append_scaled_texture()`][Self::append_scaled_texture()]
475    /// if you need other filtering, such as nearest-neighbour.
476    /// ## `texture`
477    /// the texture to render
478    /// ## `bounds`
479    /// the bounds for the new node
480    #[doc(alias = "gtk_snapshot_append_texture")]
481    fn append_texture(&self, texture: &impl IsA<gdk::Texture>, bounds: &graphene::Rect) {
482        unsafe {
483            ffi::gtk_snapshot_append_texture(
484                self.as_ref().to_glib_none().0,
485                texture.as_ref().to_glib_none().0,
486                bounds.to_glib_none().0,
487            );
488        }
489    }
490
491    /// Returns the node that was constructed by @self
492    /// and frees @self.
493    ///
494    /// See also `Gtk::Snapshot::to_node()`.
495    ///
496    /// # Returns
497    ///
498    /// a newly-created [`gsk::RenderNode`][crate::gsk::RenderNode]
499    #[doc(alias = "gtk_snapshot_free_to_node")]
500    #[doc(alias = "free_to_node")]
501    fn to_node(self) -> Option<gsk::RenderNode> {
502        unsafe {
503            from_glib_full(ffi::gtk_snapshot_free_to_node(
504                self.upcast().into_glib_ptr(),
505            ))
506        }
507    }
508
509    /// Returns a paintable for the node that was
510    /// constructed by @self and frees @self.
511    /// ## `size`
512    /// The size of the resulting paintable
513    ///   or [`None`] to use the bounds of the snapshot
514    ///
515    /// # Returns
516    ///
517    /// a newly-created [`gdk::Paintable`][crate::gdk::Paintable]
518    #[doc(alias = "gtk_snapshot_free_to_paintable")]
519    #[doc(alias = "free_to_paintable")]
520    fn to_paintable(self, size: Option<&graphene::Size>) -> Option<gdk::Paintable> {
521        unsafe {
522            from_glib_full(ffi::gtk_snapshot_free_to_paintable(
523                self.upcast().into_glib_ptr(),
524                size.to_glib_none().0,
525            ))
526        }
527    }
528
529    /// Removes the top element from the stack of render nodes and
530    /// adds it to the nearest [`gsk::GLShaderNode`][crate::gsk::GLShaderNode] below it.
531    ///
532    /// This must be called the same number of times as the number
533    /// of textures is needed for the shader in
534    /// [`push_gl_shader()`][Self::push_gl_shader()].
535    ///
536    /// # Deprecated since 4.16
537    ///
538    /// GTK's new Vulkan-focused rendering
539    ///   does not support this feature. Use [`GLArea`][crate::GLArea] for
540    ///   OpenGL rendering.
541    #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
542    #[allow(deprecated)]
543    #[doc(alias = "gtk_snapshot_gl_shader_pop_texture")]
544    fn gl_shader_pop_texture(&self) {
545        unsafe {
546            ffi::gtk_snapshot_gl_shader_pop_texture(self.as_ref().to_glib_none().0);
547        }
548    }
549
550    /// Applies a perspective projection transform.
551    ///
552    /// See [`gsk::Transform::perspective()`][crate::gsk::Transform::perspective()] for a discussion on the details.
553    /// ## `depth`
554    /// distance of the z=0 plane
555    #[doc(alias = "gtk_snapshot_perspective")]
556    fn perspective(&self, depth: f32) {
557        unsafe {
558            ffi::gtk_snapshot_perspective(self.as_ref().to_glib_none().0, depth);
559        }
560    }
561
562    /// Removes the top element from the stack of render nodes,
563    /// and appends it to the node underneath it.
564    #[doc(alias = "gtk_snapshot_pop")]
565    fn pop(&self) {
566        unsafe {
567            ffi::gtk_snapshot_pop(self.as_ref().to_glib_none().0);
568        }
569    }
570
571    /// Blends together two images with the given blend mode.
572    ///
573    /// Until the first call to [`pop()`][Self::pop()], the
574    /// bottom image for the blend operation will be recorded.
575    /// After that call, the top image to be blended will be
576    /// recorded until the second call to [`pop()`][Self::pop()].
577    ///
578    /// Calling this function requires two subsequent calls
579    /// to [`pop()`][Self::pop()].
580    /// ## `blend_mode`
581    /// blend mode to use
582    #[doc(alias = "gtk_snapshot_push_blend")]
583    fn push_blend(&self, blend_mode: gsk::BlendMode) {
584        unsafe {
585            ffi::gtk_snapshot_push_blend(self.as_ref().to_glib_none().0, blend_mode.into_glib());
586        }
587    }
588
589    /// Blurs an image.
590    ///
591    /// The image is recorded until the next call to [`pop()`][Self::pop()].
592    /// ## `radius`
593    /// the blur radius to use. Must be positive
594    #[doc(alias = "gtk_snapshot_push_blur")]
595    fn push_blur(&self, radius: f64) {
596        unsafe {
597            ffi::gtk_snapshot_push_blur(self.as_ref().to_glib_none().0, radius);
598        }
599    }
600
601    /// Clips an image to a rectangle.
602    ///
603    /// The image is recorded until the next call to [`pop()`][Self::pop()].
604    /// ## `bounds`
605    /// the rectangle to clip to
606    #[doc(alias = "gtk_snapshot_push_clip")]
607    fn push_clip(&self, bounds: &graphene::Rect) {
608        unsafe {
609            ffi::gtk_snapshot_push_clip(self.as_ref().to_glib_none().0, bounds.to_glib_none().0);
610        }
611    }
612
613    /// Modifies the colors of an image by applying an affine transformation
614    /// in RGB space.
615    ///
616    /// In particular, the colors will be transformed by applying
617    ///
618    ///     pixel = transpose(color_matrix) * pixel + color_offset
619    ///
620    /// for every pixel. The transformation operates on unpremultiplied
621    /// colors, with color components ordered R, G, B, A.
622    ///
623    /// The image is recorded until the next call to [`pop()`][Self::pop()].
624    /// ## `color_matrix`
625    /// the color matrix to use
626    /// ## `color_offset`
627    /// the color offset to use
628    #[doc(alias = "gtk_snapshot_push_color_matrix")]
629    fn push_color_matrix(&self, color_matrix: &graphene::Matrix, color_offset: &graphene::Vec4) {
630        unsafe {
631            ffi::gtk_snapshot_push_color_matrix(
632                self.as_ref().to_glib_none().0,
633                color_matrix.to_glib_none().0,
634                color_offset.to_glib_none().0,
635            );
636        }
637    }
638
639    /// Snapshots a cross-fade operation between two images with the
640    /// given @progress.
641    ///
642    /// Until the first call to [`pop()`][Self::pop()], the start image
643    /// will be snapshot. After that call, the end image will be recorded
644    /// until the second call to [`pop()`][Self::pop()].
645    ///
646    /// Calling this function requires two subsequent calls
647    /// to [`pop()`][Self::pop()].
648    /// ## `progress`
649    /// progress between 0.0 and 1.0
650    #[doc(alias = "gtk_snapshot_push_cross_fade")]
651    fn push_cross_fade(&self, progress: f64) {
652        unsafe {
653            ffi::gtk_snapshot_push_cross_fade(self.as_ref().to_glib_none().0, progress);
654        }
655    }
656
657    /// Fills the area given by @path and @fill_rule with an image and discards everything
658    /// outside of it.
659    ///
660    /// The image is recorded until the next call to [`pop()`][Self::pop()].
661    ///
662    /// If you want to fill the path with a color, [`append_fill()`][Self::append_fill()]
663    /// than rendering new ones, use [`append_fill()`][Self::append_fill()]
664    /// may be more convenient.
665    /// ## `path`
666    /// The path describing the area to fill
667    /// ## `fill_rule`
668    /// The fill rule to use
669    #[cfg(feature = "v4_14")]
670    #[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
671    #[doc(alias = "gtk_snapshot_push_fill")]
672    fn push_fill(&self, path: &gsk::Path, fill_rule: gsk::FillRule) {
673        unsafe {
674            ffi::gtk_snapshot_push_fill(
675                self.as_ref().to_glib_none().0,
676                path.to_glib_none().0,
677                fill_rule.into_glib(),
678            );
679        }
680    }
681
682    /// Push a [`gsk::GLShaderNode`][crate::gsk::GLShaderNode].
683    ///
684    /// The node uses the given [`gsk::GLShader`][crate::gsk::GLShader] and uniform values
685    /// Additionally this takes a list of @n_children other nodes
686    /// which will be passed to the [`gsk::GLShaderNode`][crate::gsk::GLShaderNode].
687    ///
688    /// The @take_args argument is a block of data to use for uniform
689    /// arguments, as per types and offsets defined by the @shader.
690    /// Normally this is generated by `Gsk::GLShader::format_args()`
691    /// or `Gsk::ShaderArgsBuilder`.
692    ///
693    /// The snapshotter takes ownership of @take_args, so the caller should
694    /// not free it after this.
695    ///
696    /// If the renderer doesn't support GL shaders, or if there is any
697    /// problem when compiling the shader, then the node will draw pink.
698    /// You should use [`GLShader::compile()`][crate::gsk::GLShader::compile()] to ensure the @shader
699    /// will work for the renderer before using it.
700    ///
701    /// If the shader requires textures (see [`GLShader::n_textures()`][crate::gsk::GLShader::n_textures()]),
702    /// then it is expected that you call [`gl_shader_pop_texture()`][Self::gl_shader_pop_texture()]
703    /// the number of times that are required. Each of these calls will generate
704    /// a node that is added as a child to the [`gsk::GLShaderNode`][crate::gsk::GLShaderNode], which in turn
705    /// will render these offscreen and pass as a texture to the shader.
706    ///
707    /// Once all textures (if any) are pop:ed, you must call the regular
708    /// [`pop()`][Self::pop()].
709    ///
710    /// If you want to use pre-existing textures as input to the shader rather
711    /// than rendering new ones, use [`append_texture()`][Self::append_texture()] to
712    /// push a texture node. These will be used directly rather than being
713    /// re-rendered.
714    ///
715    /// For details on how to write shaders, see [`gsk::GLShader`][crate::gsk::GLShader].
716    ///
717    /// # Deprecated since 4.16
718    ///
719    /// GTK's new Vulkan-focused rendering
720    ///   does not support this feature. Use [`GLArea`][crate::GLArea] for
721    ///   OpenGL rendering.
722    /// ## `shader`
723    /// The code to run
724    /// ## `bounds`
725    /// the rectangle to render into
726    /// ## `take_args`
727    /// Data block with arguments for the shader.
728    #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
729    #[allow(deprecated)]
730    #[doc(alias = "gtk_snapshot_push_gl_shader")]
731    fn push_gl_shader(
732        &self,
733        shader: &gsk::GLShader,
734        bounds: &graphene::Rect,
735        take_args: glib::Bytes,
736    ) {
737        unsafe {
738            ffi::gtk_snapshot_push_gl_shader(
739                self.as_ref().to_glib_none().0,
740                shader.to_glib_none().0,
741                bounds.to_glib_none().0,
742                take_args.into_glib_ptr(),
743            );
744        }
745    }
746
747    /// Until the first call to [`pop()`][Self::pop()], the
748    /// mask image for the mask operation will be recorded.
749    ///
750    /// After that call, the source image will be recorded until
751    /// the second call to [`pop()`][Self::pop()].
752    ///
753    /// Calling this function requires 2 subsequent calls to gtk_snapshot_pop().
754    /// ## `mask_mode`
755    /// mask mode to use
756    #[cfg(feature = "v4_10")]
757    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
758    #[doc(alias = "gtk_snapshot_push_mask")]
759    fn push_mask(&self, mask_mode: gsk::MaskMode) {
760        unsafe {
761            ffi::gtk_snapshot_push_mask(self.as_ref().to_glib_none().0, mask_mode.into_glib());
762        }
763    }
764
765    /// Modifies the opacity of an image.
766    ///
767    /// The image is recorded until the next call to [`pop()`][Self::pop()].
768    /// ## `opacity`
769    /// the opacity to use
770    #[doc(alias = "gtk_snapshot_push_opacity")]
771    fn push_opacity(&self, opacity: f64) {
772        unsafe {
773            ffi::gtk_snapshot_push_opacity(self.as_ref().to_glib_none().0, opacity);
774        }
775    }
776
777    /// Creates a node that repeats the child node.
778    ///
779    /// The child is recorded until the next call to [`pop()`][Self::pop()].
780    /// ## `bounds`
781    /// the bounds within which to repeat
782    /// ## `child_bounds`
783    /// the bounds of the child or [`None`]
784    ///   to use the full size of the collected child node
785    #[doc(alias = "gtk_snapshot_push_repeat")]
786    fn push_repeat(&self, bounds: &graphene::Rect, child_bounds: Option<&graphene::Rect>) {
787        unsafe {
788            ffi::gtk_snapshot_push_repeat(
789                self.as_ref().to_glib_none().0,
790                bounds.to_glib_none().0,
791                child_bounds.to_glib_none().0,
792            );
793        }
794    }
795
796    /// Clips an image to a rounded rectangle.
797    ///
798    /// The image is recorded until the next call to [`pop()`][Self::pop()].
799    /// ## `bounds`
800    /// the rounded rectangle to clip to
801    #[doc(alias = "gtk_snapshot_push_rounded_clip")]
802    fn push_rounded_clip(&self, bounds: &gsk::RoundedRect) {
803        unsafe {
804            ffi::gtk_snapshot_push_rounded_clip(
805                self.as_ref().to_glib_none().0,
806                bounds.to_glib_none().0,
807            );
808        }
809    }
810
811    /// Applies a shadow to an image.
812    ///
813    /// The image is recorded until the next call to [`pop()`][Self::pop()].
814    /// ## `shadow`
815    /// the first shadow specification
816    #[doc(alias = "gtk_snapshot_push_shadow")]
817    fn push_shadow(&self, shadow: &[gsk::Shadow]) {
818        let n_shadows = shadow.len() as _;
819        unsafe {
820            ffi::gtk_snapshot_push_shadow(
821                self.as_ref().to_glib_none().0,
822                shadow.to_glib_none().0,
823                n_shadows,
824            );
825        }
826    }
827
828    /// Strokes the given @path with the attributes given by @stroke and
829    /// an image.
830    ///
831    /// The image is recorded until the next call to [`pop()`][Self::pop()].
832    ///
833    /// Note that the strokes are subject to the same transformation as
834    /// everything else, so uneven scaling will cause horizontal and vertical
835    /// strokes to have different widths.
836    ///
837    /// If you want to stroke the path with a color, [`append_stroke()`][Self::append_stroke()]
838    /// may be more convenient.
839    /// ## `path`
840    /// The path to stroke
841    /// ## `stroke`
842    /// The stroke attributes
843    #[cfg(feature = "v4_14")]
844    #[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
845    #[doc(alias = "gtk_snapshot_push_stroke")]
846    fn push_stroke(&self, path: &gsk::Path, stroke: &gsk::Stroke) {
847        unsafe {
848            ffi::gtk_snapshot_push_stroke(
849                self.as_ref().to_glib_none().0,
850                path.to_glib_none().0,
851                stroke.to_glib_none().0,
852            );
853        }
854    }
855
856    /// Creates a render node for the CSS background according to @context,
857    /// and appends it to the current node of @self, without changing
858    /// the current node.
859    ///
860    /// # Deprecated since 4.10
861    ///
862    /// ## `context`
863    /// the style context that defines the background
864    /// ## `x`
865    /// X origin of the rectangle
866    /// ## `y`
867    /// Y origin of the rectangle
868    /// ## `width`
869    /// rectangle width
870    /// ## `height`
871    /// rectangle height
872    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
873    #[allow(deprecated)]
874    #[doc(alias = "gtk_snapshot_render_background")]
875    fn render_background(
876        &self,
877        context: &impl IsA<StyleContext>,
878        x: f64,
879        y: f64,
880        width: f64,
881        height: f64,
882    ) {
883        unsafe {
884            ffi::gtk_snapshot_render_background(
885                self.as_ref().to_glib_none().0,
886                context.as_ref().to_glib_none().0,
887                x,
888                y,
889                width,
890                height,
891            );
892        }
893    }
894
895    /// Creates a render node for the focus outline according to @context,
896    /// and appends it to the current node of @self, without changing
897    /// the current node.
898    ///
899    /// # Deprecated since 4.10
900    ///
901    /// ## `context`
902    /// the style context that defines the focus ring
903    /// ## `x`
904    /// X origin of the rectangle
905    /// ## `y`
906    /// Y origin of the rectangle
907    /// ## `width`
908    /// rectangle width
909    /// ## `height`
910    /// rectangle height
911    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
912    #[allow(deprecated)]
913    #[doc(alias = "gtk_snapshot_render_focus")]
914    fn render_focus(
915        &self,
916        context: &impl IsA<StyleContext>,
917        x: f64,
918        y: f64,
919        width: f64,
920        height: f64,
921    ) {
922        unsafe {
923            ffi::gtk_snapshot_render_focus(
924                self.as_ref().to_glib_none().0,
925                context.as_ref().to_glib_none().0,
926                x,
927                y,
928                width,
929                height,
930            );
931        }
932    }
933
934    /// Creates a render node for the CSS border according to @context,
935    /// and appends it to the current node of @self, without changing
936    /// the current node.
937    ///
938    /// # Deprecated since 4.10
939    ///
940    /// ## `context`
941    /// the style context that defines the frame
942    /// ## `x`
943    /// X origin of the rectangle
944    /// ## `y`
945    /// Y origin of the rectangle
946    /// ## `width`
947    /// rectangle width
948    /// ## `height`
949    /// rectangle height
950    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
951    #[allow(deprecated)]
952    #[doc(alias = "gtk_snapshot_render_frame")]
953    fn render_frame(
954        &self,
955        context: &impl IsA<StyleContext>,
956        x: f64,
957        y: f64,
958        width: f64,
959        height: f64,
960    ) {
961        unsafe {
962            ffi::gtk_snapshot_render_frame(
963                self.as_ref().to_glib_none().0,
964                context.as_ref().to_glib_none().0,
965                x,
966                y,
967                width,
968                height,
969            );
970        }
971    }
972
973    /// Draws a text caret using @self at the specified index of @layout.
974    ///
975    /// # Deprecated since 4.10
976    ///
977    /// ## `context`
978    /// a [`StyleContext`][crate::StyleContext]
979    /// ## `x`
980    /// X origin
981    /// ## `y`
982    /// Y origin
983    /// ## `layout`
984    /// the [`pango::Layout`][crate::pango::Layout] of the text
985    /// ## `index`
986    /// the index in the [`pango::Layout`][crate::pango::Layout]
987    /// ## `direction`
988    /// the [`pango::Direction`][crate::pango::Direction] of the text
989    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
990    #[allow(deprecated)]
991    #[doc(alias = "gtk_snapshot_render_insertion_cursor")]
992    fn render_insertion_cursor(
993        &self,
994        context: &impl IsA<StyleContext>,
995        x: f64,
996        y: f64,
997        layout: &pango::Layout,
998        index: i32,
999        direction: pango::Direction,
1000    ) {
1001        unsafe {
1002            ffi::gtk_snapshot_render_insertion_cursor(
1003                self.as_ref().to_glib_none().0,
1004                context.as_ref().to_glib_none().0,
1005                x,
1006                y,
1007                layout.to_glib_none().0,
1008                index,
1009                direction.into_glib(),
1010            );
1011        }
1012    }
1013
1014    /// Creates a render node for rendering @layout according to the style
1015    /// information in @context, and appends it to the current node of @self,
1016    /// without changing the current node.
1017    ///
1018    /// # Deprecated since 4.10
1019    ///
1020    /// ## `context`
1021    /// the style context that defines the text
1022    /// ## `x`
1023    /// X origin of the rectangle
1024    /// ## `y`
1025    /// Y origin of the rectangle
1026    /// ## `layout`
1027    /// the [`pango::Layout`][crate::pango::Layout] to render
1028    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
1029    #[allow(deprecated)]
1030    #[doc(alias = "gtk_snapshot_render_layout")]
1031    fn render_layout(
1032        &self,
1033        context: &impl IsA<StyleContext>,
1034        x: f64,
1035        y: f64,
1036        layout: &pango::Layout,
1037    ) {
1038        unsafe {
1039            ffi::gtk_snapshot_render_layout(
1040                self.as_ref().to_glib_none().0,
1041                context.as_ref().to_glib_none().0,
1042                x,
1043                y,
1044                layout.to_glib_none().0,
1045            );
1046        }
1047    }
1048
1049    /// Restores @self to the state saved by a preceding call to
1050    /// [`save()`][Self::save()] and removes that state from the stack of
1051    /// saved states.
1052    #[doc(alias = "gtk_snapshot_restore")]
1053    fn restore(&self) {
1054        unsafe {
1055            ffi::gtk_snapshot_restore(self.as_ref().to_glib_none().0);
1056        }
1057    }
1058
1059    /// Rotates @@self's coordinate system by @angle degrees in 2D space -
1060    /// or in 3D speak, rotates around the Z axis. The rotation happens around
1061    /// the origin point of (0, 0) in the @self's current coordinate system.
1062    ///
1063    /// To rotate around axes other than the Z axis, use [`gsk::Transform::rotate_3d()`][crate::gsk::Transform::rotate_3d()].
1064    /// ## `angle`
1065    /// the rotation angle, in degrees (clockwise)
1066    #[doc(alias = "gtk_snapshot_rotate")]
1067    fn rotate(&self, angle: f32) {
1068        unsafe {
1069            ffi::gtk_snapshot_rotate(self.as_ref().to_glib_none().0, angle);
1070        }
1071    }
1072
1073    /// Rotates @self's coordinate system by @angle degrees around @axis.
1074    ///
1075    /// For a rotation in 2D space, use [`gsk::Transform::rotate()`][crate::gsk::Transform::rotate()].
1076    /// ## `angle`
1077    /// the rotation angle, in degrees (clockwise)
1078    /// ## `axis`
1079    /// The rotation axis
1080    #[doc(alias = "gtk_snapshot_rotate_3d")]
1081    fn rotate_3d(&self, angle: f32, axis: &graphene::Vec3) {
1082        unsafe {
1083            ffi::gtk_snapshot_rotate_3d(
1084                self.as_ref().to_glib_none().0,
1085                angle,
1086                axis.to_glib_none().0,
1087            );
1088        }
1089    }
1090
1091    /// Makes a copy of the current state of @self and saves it
1092    /// on an internal stack.
1093    ///
1094    /// When [`restore()`][Self::restore()] is called, @self will
1095    /// be restored to the saved state.
1096    ///
1097    /// Multiple calls to [`save()`][Self::save()] and [`restore()`][Self::restore()]
1098    /// can be nested; each call to `gtk_snapshot_restore()` restores the state from
1099    /// the matching paired `gtk_snapshot_save()`.
1100    ///
1101    /// It is necessary to clear all saved states with corresponding
1102    /// calls to `gtk_snapshot_restore()`.
1103    #[doc(alias = "gtk_snapshot_save")]
1104    fn save(&self) {
1105        unsafe {
1106            ffi::gtk_snapshot_save(self.as_ref().to_glib_none().0);
1107        }
1108    }
1109
1110    /// Scales @self's coordinate system in 2-dimensional space by
1111    /// the given factors.
1112    ///
1113    /// Use [`scale_3d()`][Self::scale_3d()] to scale in all 3 dimensions.
1114    /// ## `factor_x`
1115    /// scaling factor on the X axis
1116    /// ## `factor_y`
1117    /// scaling factor on the Y axis
1118    #[doc(alias = "gtk_snapshot_scale")]
1119    fn scale(&self, factor_x: f32, factor_y: f32) {
1120        unsafe {
1121            ffi::gtk_snapshot_scale(self.as_ref().to_glib_none().0, factor_x, factor_y);
1122        }
1123    }
1124
1125    /// Scales @self's coordinate system by the given factors.
1126    /// ## `factor_x`
1127    /// scaling factor on the X axis
1128    /// ## `factor_y`
1129    /// scaling factor on the Y axis
1130    /// ## `factor_z`
1131    /// scaling factor on the Z axis
1132    #[doc(alias = "gtk_snapshot_scale_3d")]
1133    fn scale_3d(&self, factor_x: f32, factor_y: f32, factor_z: f32) {
1134        unsafe {
1135            ffi::gtk_snapshot_scale_3d(
1136                self.as_ref().to_glib_none().0,
1137                factor_x,
1138                factor_y,
1139                factor_z,
1140            );
1141        }
1142    }
1143
1144    /// Transforms @self's coordinate system with the given @transform.
1145    /// ## `transform`
1146    /// the transform to apply
1147    #[doc(alias = "gtk_snapshot_transform")]
1148    fn transform(&self, transform: Option<&gsk::Transform>) {
1149        unsafe {
1150            ffi::gtk_snapshot_transform(self.as_ref().to_glib_none().0, transform.to_glib_none().0);
1151        }
1152    }
1153
1154    /// Transforms @self's coordinate system with the given @matrix.
1155    /// ## `matrix`
1156    /// the matrix to multiply the transform with
1157    #[doc(alias = "gtk_snapshot_transform_matrix")]
1158    fn transform_matrix(&self, matrix: &graphene::Matrix) {
1159        unsafe {
1160            ffi::gtk_snapshot_transform_matrix(
1161                self.as_ref().to_glib_none().0,
1162                matrix.to_glib_none().0,
1163            );
1164        }
1165    }
1166
1167    /// Translates @self's coordinate system by @point in 2-dimensional space.
1168    /// ## `point`
1169    /// the point to translate the snapshot by
1170    #[doc(alias = "gtk_snapshot_translate")]
1171    fn translate(&self, point: &graphene::Point) {
1172        unsafe {
1173            ffi::gtk_snapshot_translate(self.as_ref().to_glib_none().0, point.to_glib_none().0);
1174        }
1175    }
1176
1177    /// Translates @self's coordinate system by @point.
1178    /// ## `point`
1179    /// the point to translate the snapshot by
1180    #[doc(alias = "gtk_snapshot_translate_3d")]
1181    fn translate_3d(&self, point: &graphene::Point3D) {
1182        unsafe {
1183            ffi::gtk_snapshot_translate_3d(self.as_ref().to_glib_none().0, point.to_glib_none().0);
1184        }
1185    }
1186}
1187
1188impl<O: IsA<Snapshot>> SnapshotExt for O {}