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 {}