Struct gtk4::Snapshot

#[repr(transparent)]
pub struct Snapshot { /* private fields */ }

Snapshot assists in creating gsk::RenderNodes 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 pop() to change the current node.

The typical way to obtain a Snapshot object is as an argument to the vfunc::Gtk::Widget::snapshot vfunc. If you need to create your own Snapshot, use new().

Implements

[trait@gdk::prelude::SnapshotExt], glib::ObjectExt

Implementations

impl Snapshot

pub fn new() -> Snapshot

Creates a new Snapshot.

Returns

a newly-allocated Snapshot

pub fn append_cairo(&self, bounds: &Rect) -> Context

Creates a new 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 suitable for drawing the contents of the newly created render node

pub fn append_color(&self, color: &RGBA, bounds: &Rect)

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

pub fn append_conic_gradient( &self, bounds: &Rect, center: &Point, rotation: f32, stops: &[ColorStop] )

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

pub fn append_inset_shadow( &self, outline: &RoundedRect, color: &RGBA, dx: f32, dy: f32, spread: f32, blur_radius: f32 )

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

pub fn append_layout(&self, layout: &Layout, color: &RGBA)

pub fn append_linear_gradient( &self, bounds: &Rect, start_point: &Point, end_point: &Point, stops: &[ColorStop] )

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

pub fn append_node(&self, node: impl AsRef<RenderNode>)

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

pub fn append_outset_shadow( &self, outline: &RoundedRect, color: &RGBA, dx: f32, dy: f32, spread: f32, blur_radius: f32 )

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

pub fn append_radial_gradient( &self, bounds: &Rect, center: &Point, hradius: f32, vradius: f32, start: f32, end: f32, stops: &[ColorStop] )

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

pub fn append_repeating_linear_gradient( &self, bounds: &Rect, start_point: &Point, end_point: &Point, stops: &[ColorStop] )

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

pub fn append_repeating_radial_gradient( &self, bounds: &Rect, center: &Point, hradius: f32, vradius: f32, start: f32, end: f32, stops: &[ColorStop] )

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

pub fn append_texture(&self, texture: &impl IsA<Texture>, bounds: &Rect)

Creates a new render node drawing the @texture into the given @bounds and appends it to the current render node of @self.

texture

the texture to render

bounds

the bounds for the new node

pub fn gl_shader_pop_texture(&self)

Removes the top element from the stack of render nodes and adds it to the nearest 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().

pub fn perspective(&self, depth: f32)

Applies a perspective projection transform.

See gsk::Transform::perspective() for a discussion on the details.

depth

distance of the z=0 plane

pub fn pop(&self)

Removes the top element from the stack of render nodes, and appends it to the node underneath it.

pub fn push_blend(&self, blend_mode: BlendMode)

Blends together two images with the given blend mode.

Until the first call to 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().

Calling this function requires two subsequent calls to pop().

blend_mode

blend mode to use

pub fn push_blur(&self, radius: f64)

Blurs an image.

The image is recorded until the next call to pop().

radius

the blur radius to use. Must be positive

pub fn push_clip(&self, bounds: &Rect)

Clips an image to a rectangle.

The image is recorded until the next call to pop().

bounds

the rectangle to clip to

pub fn push_color_matrix(&self, color_matrix: &Matrix, color_offset: &Vec4)

Modifies the colors of an image by applying an affine transformation in RGB space.

The image is recorded until the next call to pop().

color_matrix

the color matrix to use

color_offset

the color offset to use

pub fn push_cross_fade(&self, progress: f64)

Snapshots a cross-fade operation between two images with the given @progress.

Until the first call to pop(), the start image will be snapshot. After that call, the end image will be recorded until the second call to pop().

Calling this function requires two subsequent calls to pop().

progress

progress between 0.0 and 1.0

pub fn push_gl_shader( &self, shader: &GLShader, bounds: &Rect, take_args: &Bytes )

Push a gsk::GLShaderNode.

The node uses the given gsk::GLShader and uniform values Additionally this takes a list of @n_children other nodes which will be passed to the 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() to ensure the @shader will work for the renderer before using it.

If the shader requires textures (see GLShader::n_textures()), then it is expected that you call 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, 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().

If you want to use pre-existing textures as input to the shader rather than rendering new ones, use 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.

shader

The code to run

bounds

the rectangle to render into

take_args

Data block with arguments for the shader.

pub fn push_opacity(&self, opacity: f64)

Modifies the opacity of an image.

The image is recorded until the next call to pop().

opacity

the opacity to use

pub fn push_repeat(&self, bounds: &Rect, child_bounds: Option<&Rect>)

Creates a node that repeats the child node.

The child is recorded until the next call to 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

pub fn push_rounded_clip(&self, bounds: &RoundedRect)

Clips an image to a rounded rectangle.

The image is recorded until the next call to pop().

bounds

the rounded rectangle to clip to

pub fn push_shadow(&self, shadow: &[Shadow])

Applies a shadow to an image.

The image is recorded until the next call to pop().

shadow

the first shadow specification

pub fn render_background( &self, context: &impl IsA<StyleContext>, x: f64, y: f64, width: f64, height: f64 )

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.

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

pub fn render_focus( &self, context: &impl IsA<StyleContext>, x: f64, y: f64, width: f64, height: f64 )

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.

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

pub fn render_frame( &self, context: &impl IsA<StyleContext>, x: f64, y: f64, width: f64, height: f64 )

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.

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

pub fn render_insertion_cursor( &self, context: &impl IsA<StyleContext>, x: f64, y: f64, layout: &Layout, index: i32, direction: Direction )

Draws a text caret using @self at the specified index of @layout.

context

a StyleContext

x

X origin

y

Y origin

layout

the pango::Layout of the text

index

the index in the pango::Layout

direction

the pango::Direction of the text

pub fn render_layout( &self, context: &impl IsA<StyleContext>, x: f64, y: f64, layout: &Layout )

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.

context

the style context that defines the text

x

X origin of the rectangle

y

Y origin of the rectangle

layout

the pango::Layout to render

pub fn restore(&self)

Restores @self to the state saved by a preceding call to save() and removes that state from the stack of saved states.

pub fn rotate(&self, angle: f32)

Rotates @@self’s coordinate system by @angle degrees in 2D space - or in 3D speak, rotates around the Z axis.

To rotate around other axes, use gsk::Transform::rotate_3d().

angle

the rotation angle, in degrees (clockwise)

pub fn rotate_3d(&self, angle: f32, axis: &Vec3)

Rotates @self’s coordinate system by @angle degrees around @axis.

For a rotation in 2D space, use gsk::Transform::rotate().

angle

the rotation angle, in degrees (clockwise)

axis

The rotation axis

pub fn save(&self)

Makes a copy of the current state of @self and saves it on an internal stack.

When restore() is called, @self will be restored to the saved state. Multiple calls to save() and Snapshot::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().

pub fn scale(&self, factor_x: f32, factor_y: f32)

Scales @self’s coordinate system in 2-dimensional space by the given factors.

Use scale_3d() to scale in all 3 dimensions.

factor_x

scaling factor on the X axis

factor_y

scaling factor on the Y axis

pub fn scale_3d(&self, factor_x: f32, factor_y: f32, factor_z: f32)

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

pub fn to_node(&self) -> Option<RenderNode>

Returns the render node that was constructed by @self.

After calling this function, it is no longer possible to add more nodes to @self. The only function that should be called after this is GObject::Object::unref().

Returns

the constructed gsk::RenderNode

pub fn to_paintable(&self, size: Option<&Size>) -> Option<Paintable>

Returns a paintable encapsulating the render node that was constructed by @self.

After calling this function, it is no longer possible to add more nodes to @self. The only function that should be called after this is GObject::Object::unref().

size

The size of the resulting paintable or None to use the bounds of the snapshot

Returns

a new gdk::Paintable

pub fn transform(&self, transform: Option<&Transform>)

Transforms @self’s coordinate system with the given @transform.

transform

the transform to apply

pub fn transform_matrix(&self, matrix: &Matrix)

Transforms @self’s coordinate system with the given @matrix.

matrix

the matrix to multiply the transform with

pub fn translate(&self, point: &Point)

Translates @self’s coordinate system by @point in 2-dimensional space.

point

the point to translate the snapshot by

pub fn translate_3d(&self, point: &Point3D)

Translates @self’s coordinate system by @point.

point

the point to translate the snapshot by

impl Snapshot

pub fn append_border( &self, outline: &RoundedRect, border_width: &[f32; 4], border_color: &[RGBA; 4] )

Appends a stroked border rectangle inside the given @outline.

The four sides of the border can have different widths and colors.

outline

the outline of the border

border_width

the stroke width of the border on the top, right, bottom and left side respectively.

border_color

the color used on the top, right, bottom and left side.

pub fn push_debug(&self, message: &str)

Inserts a debug node with a message.

Debug nodes don’t affect the rendering at all, but can be helpful in identifying parts of a render node tree dump, for example in the GTK inspector.

message

a printf-style format string

Trait Implementations

impl Clone for Snapshot

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Snapshot

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Snapshot

fn default() -> Self

Returns the “default value” for a type.

impl Display for Snapshot

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for Snapshot

fn hash<H>(&self, state: &mut H)where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Snapshot

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl ParentClassIs for Snapshot

type Parent = Snapshot

impl<OT: ObjectType> PartialEq<OT> for Snapshot

fn eq(&self, other: &OT) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for Snapshot

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for Snapshot

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for Snapshot

impl IsA<Snapshot> for Snapshot