Class: Gtk::Snapshot

Inherits:
Gdk::Snapshot show all
Defined in:
lib/gtk4/snapshot.rb

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Gtk::Snapshot

Creates a new GtkSnapshot.

Instance Method Details

#append_border(outline, border_width, border_color) ⇒ nil

Appends a stroked border rectangle inside the given outline.

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

Parameters:

  • outline (Gsk::RoundedRect) —

    the outline of the border

  • border_width (Array<Gtk::gfloat>) —

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

  • border_color (Array<Gdk::RGBA>) —

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

Returns:

  • (nil)

#append_cairo(bounds) ⇒ cairo::Context

Creates a new [classGsk.CairoNode] and appends it to the current render node of snapshot, without changing the current node.

Parameters:

  • bounds (Graphene::Rect) —

    the bounds for the new node

Returns:

  • (cairo::Context) —

    a cairo_t suitable for drawing the contents of the newly created render node

#append_color(color, bounds) ⇒ nil

Creates a new render node drawing the color into the given bounds and appends it to the current render node of snapshot.

You should try to avoid calling this function if color is transparent.

Parameters:

  • color (Gdk::RGBA) —

    the color to draw

  • bounds (Graphene::Rect) —

    the bounds for the new node

Returns:

  • (nil)

#append_conic_gradient(bounds, center, rotation, stops, n_stops) ⇒ nil

Appends a conic gradient node with the given stops to snapshot.

Parameters:

  • bounds (Graphene::Rect) —

    the rectangle to render the gradient into

  • center (Graphene::Point) —

    the center point of the conic gradient

  • rotation (Gtk::gfloat) —

    the clockwise rotation in degrees of the starting angle. 0 means the starting angle is the top.

  • stops (Array<Gsk::ColorStop>) —

    the color stops defining the gradient

  • n_stops (Integer) —

    the number of elements in stops

Returns:

  • (nil)

#append_fill(path, fill_rule, color) ⇒ nil

A convenience method to fill a path with a color.

See [methodGtk.Snapshot.push_fill] if you need to fill a path with more complex content than a color.

Parameters:

  • path (Gsk::Path) —

    The path describing the area to fill

  • fill_rule (Gsk::FillRule) —

    The fill rule to use

  • color (Gdk::RGBA) —

    the color to fill the path with

Returns:

  • (nil)

#append_inset_shadow(outline, color, dx, dy, spread, blur_radius) ⇒ nil

Appends an inset shadow into the box given by outline.

Parameters:

  • outline (Gsk::RoundedRect) —

    outline of the region surrounded by shadow

  • color (Gdk::RGBA) —

    color of the shadow

  • dx (Gtk::gfloat) —

    horizontal offset of shadow

  • dy (Gtk::gfloat) —

    vertical offset of shadow

  • spread (Gtk::gfloat) —

    how far the shadow spreads towards the inside

  • blur_radius (Gtk::gfloat) —

    how much blur to apply to the shadow

Returns:

  • (nil)

#append_layout(layout, color) ⇒ nil

Parameters:

  • layout (Pango::Layout)
  • color (Gdk::RGBA)

Returns:

  • (nil)

#append_linear_gradient(bounds, start_point, end_point, stops, n_stops) ⇒ nil

Appends a linear gradient node with the given stops to snapshot.

Parameters:

  • bounds (Graphene::Rect) —

    the rectangle to render the linear gradient into

  • start_point (Graphene::Point) —

    the point at which the linear gradient will begin

  • end_point (Graphene::Point) —

    the point at which the linear gradient will finish

  • stops (Array<Gsk::ColorStop>) —

    the color stops defining the gradient

  • n_stops (Integer) —

    the number of elements in stops

Returns:

  • (nil)

#append_node(node) ⇒ nil

Appends node to the current render node of snapshot, without changing the current node.

If snapshot does not have a current node yet, node will become the initial node.

Parameters:

  • node (Gsk::RenderNode) —

    a GskRenderNode

Returns:

  • (nil)

#append_outset_shadow(outline, color, dx, dy, spread, blur_radius) ⇒ nil

Appends an outset shadow node around the box given by outline.

Parameters:

  • outline (Gsk::RoundedRect) —

    outline of the region surrounded by shadow

  • color (Gdk::RGBA) —

    color of the shadow

  • dx (Gtk::gfloat) —

    horizontal offset of shadow

  • dy (Gtk::gfloat) —

    vertical offset of shadow

  • spread (Gtk::gfloat) —

    how far the shadow spreads towards the outside

  • blur_radius (Gtk::gfloat) —

    how much blur to apply to the shadow

Returns:

  • (nil)

#append_radial_gradient(bounds, center, hradius, vradius, start, end, stops, n_stops) ⇒ nil

Appends a radial gradient node with the given stops to snapshot.

Parameters:

  • bounds (Graphene::Rect) —

    the rectangle to render the readial gradient into

  • center (Graphene::Point) —

    the center point for the radial gradient

  • hradius (Gtk::gfloat) —

    the horizontal radius

  • vradius (Gtk::gfloat) —

    the vertical radius

  • start (Gtk::gfloat) —

    the start position (on the horizontal axis)

  • end (Gtk::gfloat) —

    the end position (on the horizontal axis)

  • stops (Array<Gsk::ColorStop>) —

    the color stops defining the gradient

  • n_stops (Integer) —

    the number of elements in stops

Returns:

  • (nil)

#append_repeating_linear_gradient(bounds, start_point, end_point, stops, n_stops) ⇒ nil

Appends a repeating linear gradient node with the given stops to snapshot.

Parameters:

  • bounds (Graphene::Rect) —

    the rectangle to render the linear gradient into

  • start_point (Graphene::Point) —

    the point at which the linear gradient will begin

  • end_point (Graphene::Point) —

    the point at which the linear gradient will finish

  • stops (Array<Gsk::ColorStop>) —

    the color stops defining the gradient

  • n_stops (Integer) —

    the number of elements in stops

Returns:

  • (nil)

#append_repeating_radial_gradient(bounds, center, hradius, vradius, start, end, stops, n_stops) ⇒ nil

Appends a repeating radial gradient node with the given stops to snapshot.

Parameters:

  • bounds (Graphene::Rect) —

    the rectangle to render the readial gradient into

  • center (Graphene::Point) —

    the center point for the radial gradient

  • hradius (Gtk::gfloat) —

    the horizontal radius

  • vradius (Gtk::gfloat) —

    the vertical radius

  • start (Gtk::gfloat) —

    the start position (on the horizontal axis)

  • end (Gtk::gfloat) —

    the end position (on the horizontal axis)

  • stops (Array<Gsk::ColorStop>) —

    the color stops defining the gradient

  • n_stops (Integer) —

    the number of elements in stops

Returns:

  • (nil)

#append_scaled_texture(texture, filter, bounds) ⇒ nil

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

In contrast to [methodGtk.Snapshot.append_texture], this function provides control about how the filter that is used when scaling.

Parameters:

  • texture (Gdk::Texture) —

    the texture to render

  • filter (Gsk::ScalingFilter) —

    the filter to use

  • bounds (Graphene::Rect) —

    the bounds for the new node

Returns:

  • (nil)

#append_stroke(path, stroke, color) ⇒ nil

A convenience method to stroke a path with a color.

See [methodGtk.Snapshot.push_stroke] if you need to stroke a path with more complex content than a color.

Parameters:

  • path (Gsk::Path) —

    The path describing the area to fill

  • stroke (Gsk::Stroke) —

    The stroke attributes

  • color (Gdk::RGBA) —

    the color to fill the path with

Returns:

  • (nil)

#append_texture(texture, bounds) ⇒ nil

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

If the texture needs to be scaled to fill bounds, linear filtering is used. See [methodGtk.Snapshot.append_scaled_texture] if you need other filtering, such as nearest-neighbour.

Parameters:

  • texture (Gdk::Texture) —

    the texture to render

  • bounds (Graphene::Rect) —

    the bounds for the new node

Returns:

  • (nil)

#free_to_node ⇒ Gsk::RenderNode

Returns the node that was constructed by snapshot and frees snapshot.

See also [methodGtk.Snapshot.to_node].

Returns:

  • (Gsk::RenderNode) —

    a newly-created [classGsk.RenderNode]

#free_to_paintable(size) ⇒ Gdk::Paintable

Returns a paintable for the node that was constructed by snapshot and frees snapshot.

Parameters:

  • size (Graphene::Size) —

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

Returns:

#gl_shader_pop_texture ⇒ nil

Removes the top element from the stack of render nodes and adds it to the nearest [classGsk.GLShaderNode] below it.

This must be called the same number of times as the number of textures is needed for the shader in [methodGtk.Snapshot.push_gl_shader].

Returns:

  • (nil)

#perspective(depth) ⇒ nil

Applies a perspective projection transform.

See [methodGsk.Transform.perspective] for a discussion on the details.

Parameters:

  • depth (Gtk::gfloat) —

    distance of the z=0 plane

Returns:

  • (nil)

#pop ⇒ nil

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

Returns:

  • (nil)

#push_blend(blend_mode) ⇒ nil

Blends together two images with the given blend mode.

Until the first call to [methodGtk.Snapshot.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 [methodGtk.Snapshot.pop].

Calling this function requires two subsequent calls to [methodGtk.Snapshot.pop].

Parameters:

  • blend_mode (Gsk::BlendMode) —

    blend mode to use

Returns:

  • (nil)

#push_blur(radius) ⇒ nil

Blurs an image.

The image is recorded until the next call to [methodGtk.Snapshot.pop].

Parameters:

  • radius (Float) —

    the blur radius to use. Must be positive

Returns:

  • (nil)

#push_clip(bounds) ⇒ nil

Clips an image to a rectangle.

The image is recorded until the next call to [methodGtk.Snapshot.pop].

Parameters:

  • bounds (Graphene::Rect) —

    the rectangle to clip to

Returns:

  • (nil)

#push_color_matrix(color_matrix, color_offset) ⇒ nil

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 [methodGtk.Snapshot.pop].

Parameters:

  • color_matrix (Graphene::Matrix) —

    the color matrix to use

  • color_offset (Graphene::Vec4) —

    the color offset to use

Returns:

  • (nil)

#push_cross_fade(progress) ⇒ nil

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

Until the first call to [methodGtk.Snapshot.pop], the start image will be snapshot. After that call, the end image will be recorded until the second call to [methodGtk.Snapshot.pop].

Calling this function requires two subsequent calls to [methodGtk.Snapshot.pop].

Parameters:

  • progress (Float) —

    progress between 0.0 and 1.0

Returns:

  • (nil)

#push_debug(message, array) ⇒ nil

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.

Parameters:

  • message (String) —

    a printf-style format string

  • array (Array) —

    arguments for message

Returns:

  • (nil)

#push_fill(path, fill_rule) ⇒ nil

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 [methodGtk.Snapshot.pop].

If you want to fill the path with a color, [methodGtk.Snapshot.append_fill] may be more convenient.

Parameters:

  • path (Gsk::Path) —

    The path describing the area to fill

  • fill_rule (Gsk::FillRule) —

    The fill rule to use

Returns:

  • (nil)

#push_gl_shader(shader, bounds, take_args) ⇒ nil

Push a [classGsk.GLShaderNode].

The node uses the given [classGsk.GLShader] and uniform values Additionally this takes a list of n_children other nodes which will be passed to the [classGsk.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 [methodGsk.GLShader.format_args] or [structGsk.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 [methodGsk.GLShader.compile] to ensure the shader will work for the renderer before using it.

If the shader requires textures (see [methodGsk.GLShader.get_n_textures]), then it is expected that you call [methodGtk.Snapshot.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 GskGLShaderNode, 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 [methodGtk.Snapshot.pop].

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

Parameters:

  • shader (Gsk::GLShader) —

    The code to run

  • bounds (Graphene::Rect) —

    the rectangle to render into

  • take_args (GLib::Bytes) —

    Data block with arguments for the shader.

Returns:

  • (nil)

#push_mask(mask_mode) ⇒ nil

Until the first call to [methodGtk.Snapshot.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 [methodGtk.Snapshot.pop].

Calling this function requires 2 subsequent calls to gtk_snapshot_pop().

Parameters:

  • mask_mode (Gsk::MaskMode) —

    mask mode to use

Returns:

  • (nil)

#push_opacity(opacity) ⇒ nil

Modifies the opacity of an image.

The image is recorded until the next call to [methodGtk.Snapshot.pop].

Parameters:

  • opacity (Float) —

    the opacity to use

Returns:

  • (nil)

#push_repeat(bounds, child_bounds) ⇒ nil

Creates a node that repeats the child node.

The child is recorded until the next call to [methodGtk.Snapshot.pop].

Parameters:

  • bounds (Graphene::Rect) —

    the bounds within which to repeat

  • child_bounds (Graphene::Rect) —

    the bounds of the child or nil to use the full size of the collected child node

Returns:

  • (nil)

#push_rounded_clip(bounds) ⇒ nil

Clips an image to a rounded rectangle.

The image is recorded until the next call to [methodGtk.Snapshot.pop].

Parameters:

  • bounds (Gsk::RoundedRect) —

    the rounded rectangle to clip to

Returns:

  • (nil)

#push_shadow(shadow, n_shadows) ⇒ nil

Applies a shadow to an image.

The image is recorded until the next call to [methodGtk.Snapshot.pop].

Parameters:

  • shadow (Array<Gsk::Shadow>) —

    the first shadow specification

  • n_shadows (Integer) —

    number of shadow specifications

Returns:

  • (nil)

#push_stroke(path, stroke) ⇒ nil

Strokes the given path with the attributes given by stroke and an image.

The image is recorded until the next call to [methodGtk.Snapshot.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, [methodGtk.Snapshot.append_stroke] may be more convenient.

Parameters:

  • path (Gsk::Path) —

    The path to stroke

  • stroke (Gsk::Stroke) —

    The stroke attributes

Returns:

  • (nil)

#render_background(context, x, y, width, height) ⇒ nil

Creates a render node for the CSS background according to context, and appends it to the current node of snapshot, without changing the current node.

Parameters:

  • context (Gtk::StyleContext) —

    the style context that defines the background

  • x (Float) —

    X origin of the rectangle

  • y (Float) —

    Y origin of the rectangle

  • width (Float) —

    rectangle width

  • height (Float) —

    rectangle height

Returns:

  • (nil)

#render_focus(context, x, y, width, height) ⇒ nil

Creates a render node for the focus outline according to context, and appends it to the current node of snapshot, without changing the current node.

Parameters:

  • context (Gtk::StyleContext) —

    the style context that defines the focus ring

  • x (Float) —

    X origin of the rectangle

  • y (Float) —

    Y origin of the rectangle

  • width (Float) —

    rectangle width

  • height (Float) —

    rectangle height

Returns:

  • (nil)

#render_frame(context, x, y, width, height) ⇒ nil

Creates a render node for the CSS border according to context, and appends it to the current node of snapshot, without changing the current node.

Parameters:

  • context (Gtk::StyleContext) —

    the style context that defines the frame

  • x (Float) —

    X origin of the rectangle

  • y (Float) —

    Y origin of the rectangle

  • width (Float) —

    rectangle width

  • height (Float) —

    rectangle height

Returns:

  • (nil)

#render_insertion_cursor(context, x, y, layout, index, direction) ⇒ nil

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

Parameters:

  • context (Gtk::StyleContext) —

    a GtkStyleContext

  • x (Float) —

    X origin

  • y (Float) —

    Y origin

  • layout (Pango::Layout) —

    the PangoLayout of the text

  • index (Integer) —

    the index in the PangoLayout

  • direction (Pango::Direction) —

    the PangoDirection of the text

Returns:

  • (nil)

#render_layout(context, x, y, layout) ⇒ nil

Creates a render node for rendering layout according to the style information in context, and appends it to the current node of snapshot, without changing the current node.

Parameters:

  • context (Gtk::StyleContext) —

    the style context that defines the text

  • x (Float) —

    X origin of the rectangle

  • y (Float) —

    Y origin of the rectangle

  • layout (Pango::Layout) —

    the PangoLayout to render

Returns:

  • (nil)

#restore ⇒ nil

Restores snapshot to the state saved by a preceding call to [methodSnapshot.save] and removes that state from the stack of saved states.

Returns:

  • (nil)

#rotate(angle) ⇒ nil

Rotates @snapshot'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 snapshot's current coordinate system.

To rotate around axes other than the Z axis, use [methodGsk.Transform.rotate_3d].

Parameters:

  • angle (Gtk::gfloat) —

    the rotation angle, in degrees (clockwise)

Returns:

  • (nil)

#rotate_3d(angle, axis) ⇒ nil

Rotates snapshot's coordinate system by angle degrees around axis.

For a rotation in 2D space, use [methodGsk.Transform.rotate].

Parameters:

  • angle (Gtk::gfloat) —

    the rotation angle, in degrees (clockwise)

  • axis (Graphene::Vec3) —

    The rotation axis

Returns:

  • (nil)

#save ⇒ nil

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

When [methodGtk.Snapshot.restore] is called, snapshot will be restored to the saved state.

Multiple calls to [methodGtk.Snapshot.save] and [methodGtk.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().

Returns:

  • (nil) 


20
21
22
23
24
25
26
27
28
29
 
# File 'lib/gtk4/snapshot.rb', line 20

def save
  save_raw
  if block_given?
    begin
      yield
    ensure
      restore
    end
  end
end

#save_raw ⇒ nil

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

When [methodGtk.Snapshot.restore] is called, snapshot will be restored to the saved state.

Multiple calls to [methodGtk.Snapshot.save] and [methodGtk.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().

Returns:

  • (nil) 



# File 'lib/gtk4/snapshot.rb', line 19

#scale(factor_x, factor_y) ⇒ nil

Scales snapshot's coordinate system in 2-dimensional space by the given factors.

Use [methodGtk.Snapshot.scale_3d] to scale in all 3 dimensions.

Parameters:

  • factor_x (Gtk::gfloat) —

    scaling factor on the X axis

  • factor_y (Gtk::gfloat) —

    scaling factor on the Y axis

Returns:

  • (nil)

#scale_3d(factor_x, factor_y, factor_z) ⇒ nil

Scales snapshot's coordinate system by the given factors.

Parameters:

  • factor_x (Gtk::gfloat) —

    scaling factor on the X axis

  • factor_y (Gtk::gfloat) —

    scaling factor on the Y axis

  • factor_z (Gtk::gfloat) —

    scaling factor on the Z axis

Returns:

  • (nil)

#to_node ⇒ Gsk::RenderNode

Returns the render node that was constructed by snapshot.

Note that this function may return nil if nothing has been added to the snapshot or if its content does not produce pixels to be rendered.

After calling this function, it is no longer possible to add more nodes to snapshot. The only function that should be called after this is [methodGObject.Object.unref].

Returns:

  • (Gsk::RenderNode) —

    the constructed GskRenderNode or nil if there are no nodes to render.

#to_paintable(size) ⇒ Gdk::Paintable

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

After calling this function, it is no longer possible to add more nodes to snapshot. The only function that should be called after this is [methodGObject.Object.unref].

Parameters:

  • size (Graphene::Size) —

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

Returns:

#transform(transform) ⇒ nil

Transforms snapshot's coordinate system with the given transform.

Parameters:

  • transform (Gsk::Transform) —

    the transform to apply

Returns:

  • (nil)

#transform_matrix(matrix) ⇒ nil

Transforms snapshot's coordinate system with the given matrix.

Parameters:

  • matrix (Graphene::Matrix) —

    the matrix to multiply the transform with

Returns:

  • (nil)

#translate(point) ⇒ nil

Translates snapshot's coordinate system by point in 2-dimensional space.

Parameters:

  • point (Graphene::Point) —

    the point to translate the snapshot by

Returns:

  • (nil)

#translate_3d(point) ⇒ nil

Translates snapshot's coordinate system by point.

Parameters:

  • point (Graphene::Point3D) —

    the point to translate the snapshot by

Returns:

  • (nil)