gtk4/auto/

snapshot.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT
#![allow(deprecated)]

use crate::{ffi, StyleContext};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// Assists in creating [`gsk::RenderNode`][crate::gsk::RenderNode]s for widgets.
    ///
    /// It functions in a similar way to a cairo context, and maintains a stack
    /// of render nodes and their associated transformations.
    ///
    /// The node at the top of the stack is the one that `gtk_snapshot_append_…()`
    /// functions operate on. Use the `gtk_snapshot_push_…()` functions and
    /// [`SnapshotExt::pop()`][crate::prelude::SnapshotExt::pop()] to change the current node.
    ///
    /// The typical way to obtain a [`Snapshot`][crate::Snapshot] object is as an argument to
    /// the [`WidgetImpl::snapshot()`][crate::subclass::prelude::WidgetImpl::snapshot()] vfunc. If you need to create your own
    /// [`Snapshot`][crate::Snapshot], use [`new()`][Self::new()].
    ///
    /// # Implements
    ///
    /// [`SnapshotExt`][trait@crate::prelude::SnapshotExt], [`trait@gdk::prelude::SnapshotExt`], [`trait@glib::ObjectExt`], [`SnapshotExtManual`][trait@crate::prelude::SnapshotExtManual]
    #[doc(alias = "GtkSnapshot")]
    pub struct Snapshot(Object<ffi::GtkSnapshot, ffi::GtkSnapshotClass>) @extends gdk::Snapshot;

    match fn {
        type_ => || ffi::gtk_snapshot_get_type(),
    }
}

impl Snapshot {
    pub const NONE: Option<&'static Snapshot> = None;

    /// Creates a new [`Snapshot`][crate::Snapshot].
    ///
    /// # Returns
    ///
    /// a newly-allocated [`Snapshot`][crate::Snapshot]
    #[doc(alias = "gtk_snapshot_new")]
    pub fn new() -> Snapshot {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gtk_snapshot_new()) }
    }
}

impl Default for Snapshot {
    fn default() -> Self {
        Self::new()
    }
}

/// Trait containing all [`struct@Snapshot`] methods.
///
/// # Implementors
///
/// [`Snapshot`][struct@crate::Snapshot]
pub trait SnapshotExt: IsA<Snapshot> + 'static {
    /// Creates a new [`gsk::CairoNode`][crate::gsk::CairoNode] and appends it to the current
    /// render node of @self, without changing the current node.
    /// ## `bounds`
    /// the bounds for the new node
    ///
    /// # Returns
    ///
    /// a [`cairo::Context`][crate::cairo::Context] suitable for drawing the contents of
    ///   the newly created render node
    #[doc(alias = "gtk_snapshot_append_cairo")]
    fn append_cairo(&self, bounds: &graphene::Rect) -> cairo::Context {
        unsafe {
            from_glib_full(ffi::gtk_snapshot_append_cairo(
                self.as_ref().to_glib_none().0,
                bounds.to_glib_none().0,
            ))
        }
    }

    /// Creates a new render node drawing the @color into the
    /// given @bounds and appends it to the current render node
    /// of @self.
    ///
    /// You should try to avoid calling this function if
    /// @color is transparent.
    /// ## `color`
    /// the color to draw
    /// ## `bounds`
    /// the bounds for the new node
    #[doc(alias = "gtk_snapshot_append_color")]
    fn append_color(&self, color: &gdk::RGBA, bounds: &graphene::Rect) {
        unsafe {
            ffi::gtk_snapshot_append_color(
                self.as_ref().to_glib_none().0,
                color.to_glib_none().0,
                bounds.to_glib_none().0,
            );
        }
    }

    /// Appends a conic gradient node with the given stops to @self.
    /// ## `bounds`
    /// the rectangle to render the gradient into
    /// ## `center`
    /// the center point of the conic gradient
    /// ## `rotation`
    /// the clockwise rotation in degrees of the starting angle.
    ///   0 means the starting angle is the top.
    /// ## `stops`
    /// the color stops defining the gradient
    #[doc(alias = "gtk_snapshot_append_conic_gradient")]
    fn append_conic_gradient(
        &self,
        bounds: &graphene::Rect,
        center: &graphene::Point,
        rotation: f32,
        stops: &[gsk::ColorStop],
    ) {
        let n_stops = stops.len() as _;
        unsafe {
            ffi::gtk_snapshot_append_conic_gradient(
                self.as_ref().to_glib_none().0,
                bounds.to_glib_none().0,
                center.to_glib_none().0,
                rotation,
                stops.to_glib_none().0,
                n_stops,
            );
        }
    }

    /// A convenience method to fill a path with a color.
    ///
    /// See [`push_fill()`][Self::push_fill()] if you need
    /// to fill a path with more complex content than
    /// a color.
    /// ## `path`
    /// The path describing the area to fill
    /// ## `fill_rule`
    /// The fill rule to use
    /// ## `color`
    /// the color to fill the path with
    #[cfg(feature = "v4_14")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
    #[doc(alias = "gtk_snapshot_append_fill")]
    fn append_fill(&self, path: &gsk::Path, fill_rule: gsk::FillRule, color: &gdk::RGBA) {
        unsafe {
            ffi::gtk_snapshot_append_fill(
                self.as_ref().to_glib_none().0,
                path.to_glib_none().0,
                fill_rule.into_glib(),
                color.to_glib_none().0,
            );
        }
    }

    /// Appends an inset shadow into the box given by @outline.
    /// ## `outline`
    /// outline of the region surrounded by shadow
    /// ## `color`
    /// color of the shadow
    /// ## `dx`
    /// horizontal offset of shadow
    /// ## `dy`
    /// vertical offset of shadow
    /// ## `spread`
    /// how far the shadow spreads towards the inside
    /// ## `blur_radius`
    /// how much blur to apply to the shadow
    #[doc(alias = "gtk_snapshot_append_inset_shadow")]
    fn append_inset_shadow(
        &self,
        outline: &gsk::RoundedRect,
        color: &gdk::RGBA,
        dx: f32,
        dy: f32,
        spread: f32,
        blur_radius: f32,
    ) {
        unsafe {
            ffi::gtk_snapshot_append_inset_shadow(
                self.as_ref().to_glib_none().0,
                outline.to_glib_none().0,
                color.to_glib_none().0,
                dx,
                dy,
                spread,
                blur_radius,
            );
        }
    }

    /// Creates render nodes for rendering @layout in the given foregound @color
    /// and appends them to the current node of @self without changing the
    /// current node. The current theme's foreground color for a widget can be
    /// obtained with [`WidgetExt::color()`][crate::prelude::WidgetExt::color()].
    ///
    /// Note that if the layout does not produce any visible output, then nodes
    /// may not be added to the @self.
    /// ## `layout`
    /// the [`pango::Layout`][crate::pango::Layout] to render
    /// ## `color`
    /// the foreground color to render the layout in
    #[doc(alias = "gtk_snapshot_append_layout")]
    fn append_layout(&self, layout: &pango::Layout, color: &gdk::RGBA) {
        unsafe {
            ffi::gtk_snapshot_append_layout(
                self.as_ref().to_glib_none().0,
                layout.to_glib_none().0,
                color.to_glib_none().0,
            );
        }
    }

    /// Appends a linear gradient node with the given stops to @self.
    /// ## `bounds`
    /// the rectangle to render the linear gradient into
    /// ## `start_point`
    /// the point at which the linear gradient will begin
    /// ## `end_point`
    /// the point at which the linear gradient will finish
    /// ## `stops`
    /// the color stops defining the gradient
    #[doc(alias = "gtk_snapshot_append_linear_gradient")]
    fn append_linear_gradient(
        &self,
        bounds: &graphene::Rect,
        start_point: &graphene::Point,
        end_point: &graphene::Point,
        stops: &[gsk::ColorStop],
    ) {
        let n_stops = stops.len() as _;
        unsafe {
            ffi::gtk_snapshot_append_linear_gradient(
                self.as_ref().to_glib_none().0,
                bounds.to_glib_none().0,
                start_point.to_glib_none().0,
                end_point.to_glib_none().0,
                stops.to_glib_none().0,
                n_stops,
            );
        }
    }

    /// Appends @node to the current render node of @self,
    /// without changing the current node.
    ///
    /// If @self does not have a current node yet, @node
    /// will become the initial node.
    /// ## `node`
    /// a [`gsk::RenderNode`][crate::gsk::RenderNode]
    #[doc(alias = "gtk_snapshot_append_node")]
    fn append_node(&self, node: impl AsRef<gsk::RenderNode>) {
        unsafe {
            ffi::gtk_snapshot_append_node(
                self.as_ref().to_glib_none().0,
                node.as_ref().to_glib_none().0,
            );
        }
    }

    /// Appends an outset shadow node around the box given by @outline.
    /// ## `outline`
    /// outline of the region surrounded by shadow
    /// ## `color`
    /// color of the shadow
    /// ## `dx`
    /// horizontal offset of shadow
    /// ## `dy`
    /// vertical offset of shadow
    /// ## `spread`
    /// how far the shadow spreads towards the outside
    /// ## `blur_radius`
    /// how much blur to apply to the shadow
    #[doc(alias = "gtk_snapshot_append_outset_shadow")]
    fn append_outset_shadow(
        &self,
        outline: &gsk::RoundedRect,
        color: &gdk::RGBA,
        dx: f32,
        dy: f32,
        spread: f32,
        blur_radius: f32,
    ) {
        unsafe {
            ffi::gtk_snapshot_append_outset_shadow(
                self.as_ref().to_glib_none().0,
                outline.to_glib_none().0,
                color.to_glib_none().0,
                dx,
                dy,
                spread,
                blur_radius,
            );
        }
    }

    /// Appends a radial gradient node with the given stops to @self.
    /// ## `bounds`
    /// the rectangle to render the readial gradient into
    /// ## `center`
    /// the center point for the radial gradient
    /// ## `hradius`
    /// the horizontal radius
    /// ## `vradius`
    /// the vertical radius
    /// ## `start`
    /// the start position (on the horizontal axis)
    /// ## `end`
    /// the end position (on the horizontal axis)
    /// ## `stops`
    /// the color stops defining the gradient
    #[doc(alias = "gtk_snapshot_append_radial_gradient")]
    fn append_radial_gradient(
        &self,
        bounds: &graphene::Rect,
        center: &graphene::Point,
        hradius: f32,
        vradius: f32,
        start: f32,
        end: f32,
        stops: &[gsk::ColorStop],
    ) {
        let n_stops = stops.len() as _;
        unsafe {
            ffi::gtk_snapshot_append_radial_gradient(
                self.as_ref().to_glib_none().0,
                bounds.to_glib_none().0,
                center.to_glib_none().0,
                hradius,
                vradius,
                start,
                end,
                stops.to_glib_none().0,
                n_stops,
            );
        }
    }

    /// Appends a repeating linear gradient node with the given stops to @self.
    /// ## `bounds`
    /// the rectangle to render the linear gradient into
    /// ## `start_point`
    /// the point at which the linear gradient will begin
    /// ## `end_point`
    /// the point at which the linear gradient will finish
    /// ## `stops`
    /// the color stops defining the gradient
    #[doc(alias = "gtk_snapshot_append_repeating_linear_gradient")]
    fn append_repeating_linear_gradient(
        &self,
        bounds: &graphene::Rect,
        start_point: &graphene::Point,
        end_point: &graphene::Point,
        stops: &[gsk::ColorStop],
    ) {
        let n_stops = stops.len() as _;
        unsafe {
            ffi::gtk_snapshot_append_repeating_linear_gradient(
                self.as_ref().to_glib_none().0,
                bounds.to_glib_none().0,
                start_point.to_glib_none().0,
                end_point.to_glib_none().0,
                stops.to_glib_none().0,
                n_stops,
            );
        }
    }

    /// Appends a repeating radial gradient node with the given stops to @self.
    /// ## `bounds`
    /// the rectangle to render the readial gradient into
    /// ## `center`
    /// the center point for the radial gradient
    /// ## `hradius`
    /// the horizontal radius
    /// ## `vradius`
    /// the vertical radius
    /// ## `start`
    /// the start position (on the horizontal axis)
    /// ## `end`
    /// the end position (on the horizontal axis)
    /// ## `stops`
    /// the color stops defining the gradient
    #[doc(alias = "gtk_snapshot_append_repeating_radial_gradient")]
    fn append_repeating_radial_gradient(
        &self,
        bounds: &graphene::Rect,
        center: &graphene::Point,
        hradius: f32,
        vradius: f32,
        start: f32,
        end: f32,
        stops: &[gsk::ColorStop],
    ) {
        let n_stops = stops.len() as _;
        unsafe {
            ffi::gtk_snapshot_append_repeating_radial_gradient(
                self.as_ref().to_glib_none().0,
                bounds.to_glib_none().0,
                center.to_glib_none().0,
                hradius,
                vradius,
                start,
                end,
                stops.to_glib_none().0,
                n_stops,
            );
        }
    }

    /// Creates a new render node drawing the @texture
    /// into the given @bounds and appends it to the
    /// current render node of @self.
    ///
    /// In contrast to [`append_texture()`][Self::append_texture()],
    /// this function provides control about how the filter
    /// that is used when scaling.
    /// ## `texture`
    /// the texture to render
    /// ## `filter`
    /// the filter to use
    /// ## `bounds`
    /// the bounds for the new node
    #[cfg(feature = "v4_10")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
    #[doc(alias = "gtk_snapshot_append_scaled_texture")]
    fn append_scaled_texture(
        &self,
        texture: &impl IsA<gdk::Texture>,
        filter: gsk::ScalingFilter,
        bounds: &graphene::Rect,
    ) {
        unsafe {
            ffi::gtk_snapshot_append_scaled_texture(
                self.as_ref().to_glib_none().0,
                texture.as_ref().to_glib_none().0,
                filter.into_glib(),
                bounds.to_glib_none().0,
            );
        }
    }

    /// A convenience method to stroke a path with a color.
    ///
    /// See [`push_stroke()`][Self::push_stroke()] if you need
    /// to stroke a path with more complex content than
    /// a color.
    /// ## `path`
    /// The path describing the area to fill
    /// ## `stroke`
    /// The stroke attributes
    /// ## `color`
    /// the color to fill the path with
    #[cfg(feature = "v4_14")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
    #[doc(alias = "gtk_snapshot_append_stroke")]
    fn append_stroke(&self, path: &gsk::Path, stroke: &gsk::Stroke, color: &gdk::RGBA) {
        unsafe {
            ffi::gtk_snapshot_append_stroke(
                self.as_ref().to_glib_none().0,
                path.to_glib_none().0,
                stroke.to_glib_none().0,
                color.to_glib_none().0,
            );
        }
    }

    /// Creates a new render node drawing the @texture
    /// into the given @bounds and appends it to the
    /// current render node of @self.
    ///
    /// If the texture needs to be scaled to fill @bounds,
    /// linear filtering is used. See [`append_scaled_texture()`][Self::append_scaled_texture()]
    /// if you need other filtering, such as nearest-neighbour.
    /// ## `texture`
    /// the texture to render
    /// ## `bounds`
    /// the bounds for the new node
    #[doc(alias = "gtk_snapshot_append_texture")]
    fn append_texture(&self, texture: &impl IsA<gdk::Texture>, bounds: &graphene::Rect) {
        unsafe {
            ffi::gtk_snapshot_append_texture(
                self.as_ref().to_glib_none().0,
                texture.as_ref().to_glib_none().0,
                bounds.to_glib_none().0,
            );
        }
    }

    /// Returns the node that was constructed by @self
    /// and frees @self.
    ///
    /// See also `Gtk::Snapshot::to_node()`.
    ///
    /// # Returns
    ///
    /// a newly-created [`gsk::RenderNode`][crate::gsk::RenderNode]
    #[doc(alias = "gtk_snapshot_free_to_node")]
    #[doc(alias = "free_to_node")]
    fn to_node(self) -> Option<gsk::RenderNode> {
        unsafe {
            from_glib_full(ffi::gtk_snapshot_free_to_node(
                self.upcast().into_glib_ptr(),
            ))
        }
    }

    /// Returns a paintable for the node that was
    /// constructed by @self and frees @self.
    /// ## `size`
    /// The size of the resulting paintable
    ///   or [`None`] to use the bounds of the snapshot
    ///
    /// # Returns
    ///
    /// a newly-created [`gdk::Paintable`][crate::gdk::Paintable]
    #[doc(alias = "gtk_snapshot_free_to_paintable")]
    #[doc(alias = "free_to_paintable")]
    fn to_paintable(self, size: Option<&graphene::Size>) -> Option<gdk::Paintable> {
        unsafe {
            from_glib_full(ffi::gtk_snapshot_free_to_paintable(
                self.upcast().into_glib_ptr(),
                size.to_glib_none().0,
            ))
        }
    }

    /// Removes the top element from the stack of render nodes and
    /// adds it to the nearest [`gsk::GLShaderNode`][crate::gsk::GLShaderNode] below it.
    ///
    /// This must be called the same number of times as the number
    /// of textures is needed for the shader in
    /// [`push_gl_shader()`][Self::push_gl_shader()].
    ///
    /// # Deprecated since 4.16
    ///
    /// GTK's new Vulkan-focused rendering
    ///   does not support this feature. Use [`GLArea`][crate::GLArea] for
    ///   OpenGL rendering.
    #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_snapshot_gl_shader_pop_texture")]
    fn gl_shader_pop_texture(&self) {
        unsafe {
            ffi::gtk_snapshot_gl_shader_pop_texture(self.as_ref().to_glib_none().0);
        }
    }

    /// Applies a perspective projection transform.
    ///
    /// See [`gsk::Transform::perspective()`][crate::gsk::Transform::perspective()] for a discussion on the details.
    /// ## `depth`
    /// distance of the z=0 plane
    #[doc(alias = "gtk_snapshot_perspective")]
    fn perspective(&self, depth: f32) {
        unsafe {
            ffi::gtk_snapshot_perspective(self.as_ref().to_glib_none().0, depth);
        }
    }

    /// Removes the top element from the stack of render nodes,
    /// and appends it to the node underneath it.
    #[doc(alias = "gtk_snapshot_pop")]
    fn pop(&self) {
        unsafe {
            ffi::gtk_snapshot_pop(self.as_ref().to_glib_none().0);
        }
    }

    /// Blends together two images with the given blend mode.
    ///
    /// Until the first call to [`pop()`][Self::pop()], the
    /// bottom image for the blend operation will be recorded.
    /// After that call, the top image to be blended will be
    /// recorded until the second call to [`pop()`][Self::pop()].
    ///
    /// Calling this function requires two subsequent calls
    /// to [`pop()`][Self::pop()].
    /// ## `blend_mode`
    /// blend mode to use
    #[doc(alias = "gtk_snapshot_push_blend")]
    fn push_blend(&self, blend_mode: gsk::BlendMode) {
        unsafe {
            ffi::gtk_snapshot_push_blend(self.as_ref().to_glib_none().0, blend_mode.into_glib());
        }
    }

    /// Blurs an image.
    ///
    /// The image is recorded until the next call to [`pop()`][Self::pop()].
    /// ## `radius`
    /// the blur radius to use. Must be positive
    #[doc(alias = "gtk_snapshot_push_blur")]
    fn push_blur(&self, radius: f64) {
        unsafe {
            ffi::gtk_snapshot_push_blur(self.as_ref().to_glib_none().0, radius);
        }
    }

    /// Clips an image to a rectangle.
    ///
    /// The image is recorded until the next call to [`pop()`][Self::pop()].
    /// ## `bounds`
    /// the rectangle to clip to
    #[doc(alias = "gtk_snapshot_push_clip")]
    fn push_clip(&self, bounds: &graphene::Rect) {
        unsafe {
            ffi::gtk_snapshot_push_clip(self.as_ref().to_glib_none().0, bounds.to_glib_none().0);
        }
    }

    /// Modifies the colors of an image by applying an affine transformation
    /// in RGB space.
    ///
    /// In particular, the colors will be transformed by applying
    ///
    ///     pixel = transpose(color_matrix) * pixel + color_offset
    ///
    /// for every pixel. The transformation operates on unpremultiplied
    /// colors, with color components ordered R, G, B, A.
    ///
    /// The image is recorded until the next call to [`pop()`][Self::pop()].
    /// ## `color_matrix`
    /// the color matrix to use
    /// ## `color_offset`
    /// the color offset to use
    #[doc(alias = "gtk_snapshot_push_color_matrix")]
    fn push_color_matrix(&self, color_matrix: &graphene::Matrix, color_offset: &graphene::Vec4) {
        unsafe {
            ffi::gtk_snapshot_push_color_matrix(
                self.as_ref().to_glib_none().0,
                color_matrix.to_glib_none().0,
                color_offset.to_glib_none().0,
            );
        }
    }

    /// Modifies the colors of an image by applying a transfer
    /// function for each component.
    ///
    /// The transfer functions operate on unpremultiplied colors.
    ///
    /// The image is recorded until the next call to [`pop()`][Self::pop()].
    /// ## `red`
    /// the transfer for the red component
    /// ## `green`
    /// the transfer for the green component
    /// ## `blue`
    /// the transfer for the blue component
    /// ## `alpha`
    /// the transfer for the alpha component
    #[cfg(feature = "v4_20")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_20")))]
    #[doc(alias = "gtk_snapshot_push_component_transfer")]
    fn push_component_transfer(
        &self,
        red: &gsk::ComponentTransfer,
        green: &gsk::ComponentTransfer,
        blue: &gsk::ComponentTransfer,
        alpha: &gsk::ComponentTransfer,
    ) {
        unsafe {
            ffi::gtk_snapshot_push_component_transfer(
                self.as_ref().to_glib_none().0,
                red.to_glib_none().0,
                green.to_glib_none().0,
                blue.to_glib_none().0,
                alpha.to_glib_none().0,
            );
        }
    }

    /// Snapshots a cross-fade operation between two images with the
    /// given @progress.
    ///
    /// Until the first call to [`pop()`][Self::pop()], the start image
    /// will be snapshot. After that call, the end image will be recorded
    /// until the second call to [`pop()`][Self::pop()].
    ///
    /// Calling this function requires two subsequent calls
    /// to [`pop()`][Self::pop()].
    /// ## `progress`
    /// progress between 0.0 and 1.0
    #[doc(alias = "gtk_snapshot_push_cross_fade")]
    fn push_cross_fade(&self, progress: f64) {
        unsafe {
            ffi::gtk_snapshot_push_cross_fade(self.as_ref().to_glib_none().0, progress);
        }
    }

    /// Fills the area given by @path and @fill_rule with an image and discards everything
    /// outside of it.
    ///
    /// The image is recorded until the next call to [`pop()`][Self::pop()].
    ///
    /// If you want to fill the path with a color, [`append_fill()`][Self::append_fill()]
    /// than rendering new ones, use [`append_fill()`][Self::append_fill()]
    /// may be more convenient.
    /// ## `path`
    /// The path describing the area to fill
    /// ## `fill_rule`
    /// The fill rule to use
    #[cfg(feature = "v4_14")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
    #[doc(alias = "gtk_snapshot_push_fill")]
    fn push_fill(&self, path: &gsk::Path, fill_rule: gsk::FillRule) {
        unsafe {
            ffi::gtk_snapshot_push_fill(
                self.as_ref().to_glib_none().0,
                path.to_glib_none().0,
                fill_rule.into_glib(),
            );
        }
    }

    /// Push a [`gsk::GLShaderNode`][crate::gsk::GLShaderNode].
    ///
    /// The node uses the given [`gsk::GLShader`][crate::gsk::GLShader] and uniform values
    /// Additionally this takes a list of @n_children other nodes
    /// which will be passed to the [`gsk::GLShaderNode`][crate::gsk::GLShaderNode].
    ///
    /// The @take_args argument is a block of data to use for uniform
    /// arguments, as per types and offsets defined by the @shader.
    /// Normally this is generated by `Gsk::GLShader::format_args()`
    /// or `Gsk::ShaderArgsBuilder`.
    ///
    /// The snapshotter takes ownership of @take_args, so the caller should
    /// not free it after this.
    ///
    /// If the renderer doesn't support GL shaders, or if there is any
    /// problem when compiling the shader, then the node will draw pink.
    /// You should use [`GLShader::compile()`][crate::gsk::GLShader::compile()] to ensure the @shader
    /// will work for the renderer before using it.
    ///
    /// If the shader requires textures (see [`GLShader::n_textures()`][crate::gsk::GLShader::n_textures()]),
    /// then it is expected that you call [`gl_shader_pop_texture()`][Self::gl_shader_pop_texture()]
    /// the number of times that are required. Each of these calls will generate
    /// a node that is added as a child to the [`gsk::GLShaderNode`][crate::gsk::GLShaderNode], which in turn
    /// will render these offscreen and pass as a texture to the shader.
    ///
    /// Once all textures (if any) are pop:ed, you must call the regular
    /// [`pop()`][Self::pop()].
    ///
    /// If you want to use pre-existing textures as input to the shader rather
    /// than rendering new ones, use [`append_texture()`][Self::append_texture()] to
    /// push a texture node. These will be used directly rather than being
    /// re-rendered.
    ///
    /// For details on how to write shaders, see [`gsk::GLShader`][crate::gsk::GLShader].
    ///
    /// # Deprecated since 4.16
    ///
    /// GTK's new Vulkan-focused rendering
    ///   does not support this feature. Use [`GLArea`][crate::GLArea] for
    ///   OpenGL rendering.
    /// ## `shader`
    /// The code to run
    /// ## `bounds`
    /// the rectangle to render into
    /// ## `take_args`
    /// Data block with arguments for the shader.
    #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_snapshot_push_gl_shader")]
    fn push_gl_shader(
        &self,
        shader: &gsk::GLShader,
        bounds: &graphene::Rect,
        take_args: glib::Bytes,
    ) {
        unsafe {
            ffi::gtk_snapshot_push_gl_shader(
                self.as_ref().to_glib_none().0,
                shader.to_glib_none().0,
                bounds.to_glib_none().0,
                take_args.into_glib_ptr(),
            );
        }
    }

    /// Until the first call to [`pop()`][Self::pop()], the
    /// mask image for the mask operation will be recorded.
    ///
    /// After that call, the source image will be recorded until
    /// the second call to [`pop()`][Self::pop()].
    ///
    /// Calling this function requires 2 subsequent calls to gtk_snapshot_pop().
    /// ## `mask_mode`
    /// mask mode to use
    #[cfg(feature = "v4_10")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
    #[doc(alias = "gtk_snapshot_push_mask")]
    fn push_mask(&self, mask_mode: gsk::MaskMode) {
        unsafe {
            ffi::gtk_snapshot_push_mask(self.as_ref().to_glib_none().0, mask_mode.into_glib());
        }
    }

    /// Modifies the opacity of an image.
    ///
    /// The image is recorded until the next call to [`pop()`][Self::pop()].
    /// ## `opacity`
    /// the opacity to use
    #[doc(alias = "gtk_snapshot_push_opacity")]
    fn push_opacity(&self, opacity: f64) {
        unsafe {
            ffi::gtk_snapshot_push_opacity(self.as_ref().to_glib_none().0, opacity);
        }
    }

    /// Creates a node that repeats the child node.
    ///
    /// The child is recorded until the next call to [`pop()`][Self::pop()].
    /// ## `bounds`
    /// the bounds within which to repeat
    /// ## `child_bounds`
    /// the bounds of the child or [`None`]
    ///   to use the full size of the collected child node
    #[doc(alias = "gtk_snapshot_push_repeat")]
    fn push_repeat(&self, bounds: &graphene::Rect, child_bounds: Option<&graphene::Rect>) {
        unsafe {
            ffi::gtk_snapshot_push_repeat(
                self.as_ref().to_glib_none().0,
                bounds.to_glib_none().0,
                child_bounds.to_glib_none().0,
            );
        }
    }

    /// Clips an image to a rounded rectangle.
    ///
    /// The image is recorded until the next call to [`pop()`][Self::pop()].
    /// ## `bounds`
    /// the rounded rectangle to clip to
    #[doc(alias = "gtk_snapshot_push_rounded_clip")]
    fn push_rounded_clip(&self, bounds: &gsk::RoundedRect) {
        unsafe {
            ffi::gtk_snapshot_push_rounded_clip(
                self.as_ref().to_glib_none().0,
                bounds.to_glib_none().0,
            );
        }
    }

    /// Applies a shadow to an image.
    ///
    /// The image is recorded until the next call to [`pop()`][Self::pop()].
    /// ## `shadow`
    /// the first shadow specification
    #[doc(alias = "gtk_snapshot_push_shadow")]
    fn push_shadow(&self, shadow: &[gsk::Shadow]) {
        let n_shadows = shadow.len() as _;
        unsafe {
            ffi::gtk_snapshot_push_shadow(
                self.as_ref().to_glib_none().0,
                shadow.to_glib_none().0,
                n_shadows,
            );
        }
    }

    /// Strokes the given @path with the attributes given by @stroke and
    /// an image.
    ///
    /// The image is recorded until the next call to [`pop()`][Self::pop()].
    ///
    /// Note that the strokes are subject to the same transformation as
    /// everything else, so uneven scaling will cause horizontal and vertical
    /// strokes to have different widths.
    ///
    /// If you want to stroke the path with a color, [`append_stroke()`][Self::append_stroke()]
    /// may be more convenient.
    /// ## `path`
    /// The path to stroke
    /// ## `stroke`
    /// The stroke attributes
    #[cfg(feature = "v4_14")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
    #[doc(alias = "gtk_snapshot_push_stroke")]
    fn push_stroke(&self, path: &gsk::Path, stroke: &gsk::Stroke) {
        unsafe {
            ffi::gtk_snapshot_push_stroke(
                self.as_ref().to_glib_none().0,
                path.to_glib_none().0,
                stroke.to_glib_none().0,
            );
        }
    }

    /// Creates a render node for the CSS background according to @context,
    /// and appends it to the current node of @self, without changing
    /// the current node.
    ///
    /// # Deprecated since 4.10
    ///
    /// ## `context`
    /// the style context that defines the background
    /// ## `x`
    /// X origin of the rectangle
    /// ## `y`
    /// Y origin of the rectangle
    /// ## `width`
    /// rectangle width
    /// ## `height`
    /// rectangle height
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_snapshot_render_background")]
    fn render_background(
        &self,
        context: &impl IsA<StyleContext>,
        x: f64,
        y: f64,
        width: f64,
        height: f64,
    ) {
        unsafe {
            ffi::gtk_snapshot_render_background(
                self.as_ref().to_glib_none().0,
                context.as_ref().to_glib_none().0,
                x,
                y,
                width,
                height,
            );
        }
    }

    /// Creates a render node for the focus outline according to @context,
    /// and appends it to the current node of @self, without changing
    /// the current node.
    ///
    /// # Deprecated since 4.10
    ///
    /// ## `context`
    /// the style context that defines the focus ring
    /// ## `x`
    /// X origin of the rectangle
    /// ## `y`
    /// Y origin of the rectangle
    /// ## `width`
    /// rectangle width
    /// ## `height`
    /// rectangle height
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_snapshot_render_focus")]
    fn render_focus(
        &self,
        context: &impl IsA<StyleContext>,
        x: f64,
        y: f64,
        width: f64,
        height: f64,
    ) {
        unsafe {
            ffi::gtk_snapshot_render_focus(
                self.as_ref().to_glib_none().0,
                context.as_ref().to_glib_none().0,
                x,
                y,
                width,
                height,
            );
        }
    }

    /// Creates a render node for the CSS border according to @context,
    /// and appends it to the current node of @self, without changing
    /// the current node.
    ///
    /// # Deprecated since 4.10
    ///
    /// ## `context`
    /// the style context that defines the frame
    /// ## `x`
    /// X origin of the rectangle
    /// ## `y`
    /// Y origin of the rectangle
    /// ## `width`
    /// rectangle width
    /// ## `height`
    /// rectangle height
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_snapshot_render_frame")]
    fn render_frame(
        &self,
        context: &impl IsA<StyleContext>,
        x: f64,
        y: f64,
        width: f64,
        height: f64,
    ) {
        unsafe {
            ffi::gtk_snapshot_render_frame(
                self.as_ref().to_glib_none().0,
                context.as_ref().to_glib_none().0,
                x,
                y,
                width,
                height,
            );
        }
    }

    /// Draws a text caret using @self at the specified index of @layout.
    ///
    /// # Deprecated since 4.10
    ///
    /// ## `context`
    /// a [`StyleContext`][crate::StyleContext]
    /// ## `x`
    /// X origin
    /// ## `y`
    /// Y origin
    /// ## `layout`
    /// the [`pango::Layout`][crate::pango::Layout] of the text
    /// ## `index`
    /// the index in the [`pango::Layout`][crate::pango::Layout]
    /// ## `direction`
    /// the [`pango::Direction`][crate::pango::Direction] of the text
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_snapshot_render_insertion_cursor")]
    fn render_insertion_cursor(
        &self,
        context: &impl IsA<StyleContext>,
        x: f64,
        y: f64,
        layout: &pango::Layout,
        index: i32,
        direction: pango::Direction,
    ) {
        unsafe {
            ffi::gtk_snapshot_render_insertion_cursor(
                self.as_ref().to_glib_none().0,
                context.as_ref().to_glib_none().0,
                x,
                y,
                layout.to_glib_none().0,
                index,
                direction.into_glib(),
            );
        }
    }

    /// Creates a render node for rendering @layout according to the style
    /// information in @context, and appends it to the current node of @self,
    /// without changing the current node.
    ///
    /// # Deprecated since 4.10
    ///
    /// ## `context`
    /// the style context that defines the text
    /// ## `x`
    /// X origin of the rectangle
    /// ## `y`
    /// Y origin of the rectangle
    /// ## `layout`
    /// the [`pango::Layout`][crate::pango::Layout] to render
    #[cfg_attr(feature = "v4_10", deprecated = "Since 4.10")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_snapshot_render_layout")]
    fn render_layout(
        &self,
        context: &impl IsA<StyleContext>,
        x: f64,
        y: f64,
        layout: &pango::Layout,
    ) {
        unsafe {
            ffi::gtk_snapshot_render_layout(
                self.as_ref().to_glib_none().0,
                context.as_ref().to_glib_none().0,
                x,
                y,
                layout.to_glib_none().0,
            );
        }
    }

    /// Restores @self to the state saved by a preceding call to
    /// [`save()`][Self::save()] and removes that state from the stack of
    /// saved states.
    #[doc(alias = "gtk_snapshot_restore")]
    fn restore(&self) {
        unsafe {
            ffi::gtk_snapshot_restore(self.as_ref().to_glib_none().0);
        }
    }

    /// Rotates @@self's coordinate system by @angle degrees in 2D space -
    /// or in 3D speak, rotates around the Z axis. The rotation happens around
    /// the origin point of (0, 0) in the @self's current coordinate system.
    ///
    /// To rotate around axes other than the Z axis, use [`gsk::Transform::rotate_3d()`][crate::gsk::Transform::rotate_3d()].
    /// ## `angle`
    /// the rotation angle, in degrees (clockwise)
    #[doc(alias = "gtk_snapshot_rotate")]
    fn rotate(&self, angle: f32) {
        unsafe {
            ffi::gtk_snapshot_rotate(self.as_ref().to_glib_none().0, angle);
        }
    }

    /// Rotates @self's coordinate system by @angle degrees around @axis.
    ///
    /// For a rotation in 2D space, use [`gsk::Transform::rotate()`][crate::gsk::Transform::rotate()].
    /// ## `angle`
    /// the rotation angle, in degrees (clockwise)
    /// ## `axis`
    /// The rotation axis
    #[doc(alias = "gtk_snapshot_rotate_3d")]
    fn rotate_3d(&self, angle: f32, axis: &graphene::Vec3) {
        unsafe {
            ffi::gtk_snapshot_rotate_3d(
                self.as_ref().to_glib_none().0,
                angle,
                axis.to_glib_none().0,
            );
        }
    }

    /// Makes a copy of the current state of @self and saves it
    /// on an internal stack.
    ///
    /// When [`restore()`][Self::restore()] is called, @self will
    /// be restored to the saved state.
    ///
    /// Multiple calls to [`save()`][Self::save()] and [`restore()`][Self::restore()]
    /// can be nested; each call to `gtk_snapshot_restore()` restores the state from
    /// the matching paired `gtk_snapshot_save()`.
    ///
    /// It is necessary to clear all saved states with corresponding
    /// calls to `gtk_snapshot_restore()`.
    #[doc(alias = "gtk_snapshot_save")]
    fn save(&self) {
        unsafe {
            ffi::gtk_snapshot_save(self.as_ref().to_glib_none().0);
        }
    }

    /// Scales @self's coordinate system in 2-dimensional space by
    /// the given factors.
    ///
    /// Use [`scale_3d()`][Self::scale_3d()] to scale in all 3 dimensions.
    /// ## `factor_x`
    /// scaling factor on the X axis
    /// ## `factor_y`
    /// scaling factor on the Y axis
    #[doc(alias = "gtk_snapshot_scale")]
    fn scale(&self, factor_x: f32, factor_y: f32) {
        unsafe {
            ffi::gtk_snapshot_scale(self.as_ref().to_glib_none().0, factor_x, factor_y);
        }
    }

    /// Scales @self's coordinate system by the given factors.
    /// ## `factor_x`
    /// scaling factor on the X axis
    /// ## `factor_y`
    /// scaling factor on the Y axis
    /// ## `factor_z`
    /// scaling factor on the Z axis
    #[doc(alias = "gtk_snapshot_scale_3d")]
    fn scale_3d(&self, factor_x: f32, factor_y: f32, factor_z: f32) {
        unsafe {
            ffi::gtk_snapshot_scale_3d(
                self.as_ref().to_glib_none().0,
                factor_x,
                factor_y,
                factor_z,
            );
        }
    }

    /// Transforms @self's coordinate system with the given @transform.
    /// ## `transform`
    /// the transform to apply
    #[doc(alias = "gtk_snapshot_transform")]
    fn transform(&self, transform: Option<&gsk::Transform>) {
        unsafe {
            ffi::gtk_snapshot_transform(self.as_ref().to_glib_none().0, transform.to_glib_none().0);
        }
    }

    /// Transforms @self's coordinate system with the given @matrix.
    /// ## `matrix`
    /// the matrix to multiply the transform with
    #[doc(alias = "gtk_snapshot_transform_matrix")]
    fn transform_matrix(&self, matrix: &graphene::Matrix) {
        unsafe {
            ffi::gtk_snapshot_transform_matrix(
                self.as_ref().to_glib_none().0,
                matrix.to_glib_none().0,
            );
        }
    }

    /// Translates @self's coordinate system by @point in 2-dimensional space.
    /// ## `point`
    /// the point to translate the snapshot by
    #[doc(alias = "gtk_snapshot_translate")]
    fn translate(&self, point: &graphene::Point) {
        unsafe {
            ffi::gtk_snapshot_translate(self.as_ref().to_glib_none().0, point.to_glib_none().0);
        }
    }

    /// Translates @self's coordinate system by @point.
    /// ## `point`
    /// the point to translate the snapshot by
    #[doc(alias = "gtk_snapshot_translate_3d")]
    fn translate_3d(&self, point: &graphene::Point3D) {
        unsafe {
            ffi::gtk_snapshot_translate_3d(self.as_ref().to_glib_none().0, point.to_glib_none().0);
        }
    }
}

impl<O: IsA<Snapshot>> SnapshotExt for O {}