class Gtk::Snapshot

Overview

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 Snapshot::pop to change the current node.

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

Defined in:

lib/gi-crystal/src/auto/gtk-4.0/snapshot.cr
lib/gtk4/src/bindings/gtk/snapshot.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class Gdk::Snapshot

==(other : self) ==, hash(hasher) hash

Constructor methods inherited from class Gdk::Snapshot

new new

Class methods inherited from class Gdk::Snapshot

g_type : UInt64 g_type

Instance methods inherited from class GObject::Object

==(other : self) ==, bind_property(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags) : GObject::Binding bind_property, bind_property_full(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags, transform_to : GObject::Closure, transform_from : GObject::Closure) : GObject::Binding bind_property_full, data(key : String) : Pointer(Void) | Nil data, finalize finalize, freeze_notify : Nil freeze_notify, getv(names : Enumerable(String), values : Enumerable(_)) : Nil getv, hash(hasher) hash, notify(property_name : String) : Nil notify, notify_by_pspec(pspec : GObject::ParamSpec) : Nil notify_by_pspec, notify_signal notify_signal, property(property_name : String, value : _) : Nil property, qdata(quark : UInt32) : Pointer(Void) | Nil qdata, ref_count : UInt32 ref_count, run_dispose : Nil run_dispose, set_data(key : String, data : Pointer(Void) | Nil) : Nil set_data, set_property(property_name : String, value : _) : Nil set_property, steal_data(key : String) : Pointer(Void) | Nil steal_data, steal_qdata(quark : UInt32) : Pointer(Void) | Nil steal_qdata, thaw_notify : Nil thaw_notify, to_unsafe : Pointer(Void) to_unsafe, watch_closure(closure : GObject::Closure) : Nil watch_closure

Constructor methods inherited from class GObject::Object

cast(obj : GObject::Object) : self cast, new(pointer : Pointer(Void), transfer : GICrystal::Transfer)
new new, newv(object_type : UInt64, parameters : Enumerable(GObject::Parameter)) : self newv

Class methods inherited from class GObject::Object

cast?(obj : GObject::Object) : self | Nil cast?, compat_control(what : UInt64, data : Pointer(Void) | Nil) : UInt64 compat_control, g_type : UInt64 g_type, interface_find_property(g_iface : GObject::TypeInterface, property_name : String) : GObject::ParamSpec interface_find_property, interface_list_properties(g_iface : GObject::TypeInterface) : Enumerable(GObject::ParamSpec) interface_list_properties

Macros inherited from class GObject::Object

previous_vfunc(*args) previous_vfunc, previous_vfunc!(*args) previous_vfunc!, signal(signature) signal

Constructor Detail

def self.new : self #

Creates a new Gtk::Snapshot.


Class Method Detail

def self.g_type : UInt64 #

Returns the type id (GType) registered in GLib type system.


Instance Method Detail

def ==(other : self) #
Description copied from class Reference

Returns true if this reference is the same as other. Invokes same?.


def append_border(outline : Gsk::RoundedRect, border_width : Enumerable(Float32), border_color : Enumerable(Gdk::RGBA)) : Nil #

Appends a stroked border rectangle inside the given outline.

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


def append_cairo(bounds : Graphene::Rect) : Cairo::Context #

Creates a new Gsk::CairoNode and appends it to the current render node of snapshot, without changing the current node.


def append_color(color : Gdk::RGBA, bounds : Graphene::Rect) : 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.


def append_conic_gradient(bounds : Graphene::Rect, center : Graphene::Point, rotation : Float32, stops : Enumerable(Gsk::ColorStop)) : Nil #

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


def append_fill(path : Gsk::Path, fill_rule : Gsk::FillRule, color : Gdk::RGBA) : Nil #

A convenience method to fill a path with a color.

See Gtk::Snapshot#push_fill if you need to fill a path with more complex content than a color.


def append_inset_shadow(outline : Gsk::RoundedRect, color : Gdk::RGBA, dx : Float32, dy : Float32, spread : Float32, blur_radius : Float32) : Nil #

Appends an inset shadow into the box given by outline.


def append_layout(layout : Pango::Layout, color : Gdk::RGBA) : Nil #

Creates render nodes for rendering layout in the given foregound color and appends them to the current node of snapshot without changing the current node. The current theme's foreground color for a widget can be obtained with Gtk::Widget#color.

Note that if the layout does not produce any visible output, then nodes may not be added to the snapshot.


def append_linear_gradient(bounds : Graphene::Rect, start_point : Graphene::Point, end_point : Graphene::Point, stops : Enumerable(Gsk::ColorStop)) : Nil #

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


def append_node(node : Gsk::RenderNode) : 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.


def append_outset_shadow(outline : Gsk::RoundedRect, color : Gdk::RGBA, dx : Float32, dy : Float32, spread : Float32, blur_radius : Float32) : Nil #

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


def append_radial_gradient(bounds : Graphene::Rect, center : Graphene::Point, hradius : Float32, vradius : Float32, start : Float32, end _end : Float32, stops : Enumerable(Gsk::ColorStop)) : Nil #

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


def append_repeating_linear_gradient(bounds : Graphene::Rect, start_point : Graphene::Point, end_point : Graphene::Point, stops : Enumerable(Gsk::ColorStop)) : Nil #

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


def append_repeating_radial_gradient(bounds : Graphene::Rect, center : Graphene::Point, hradius : Float32, vradius : Float32, start : Float32, end _end : Float32, stops : Enumerable(Gsk::ColorStop)) : Nil #

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


def append_scaled_texture(texture : Gdk::Texture, filter : Gsk::ScalingFilter, bounds : Graphene::Rect) : 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 Gtk::Snapshot#append_texture, this function provides control about how the filter that is used when scaling.


def append_stroke(path : Gsk::Path, stroke : Gsk::Stroke, color : Gdk::RGBA) : Nil #

A convenience method to stroke a path with a color.

See Gtk::Snapshot#push_stroke if you need to stroke a path with more complex content than a color.


def append_texture(texture : Gdk::Texture, bounds : Graphene::Rect) : 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 Gtk::Snapshot#append_scaled_texture if you need other filtering, such as nearest-neighbour.


def gl_shader_pop_texture : Nil #

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 Gtk::Snapshot#push_gl_shader.

DEPRECATED


def hash(hasher) #
Description copied from class Reference

See Object#hash(hasher)


def perspective(depth : Float32) : Nil #

Applies a perspective projection transform.

See Gsk::Transform#perspective for a discussion on the details.


def pop : Nil #

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


def push_blend(blend_mode : Gsk::BlendMode) : Nil #

Blends together two images with the given blend mode.

Until the first call to Gtk::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 Gtk::Snapshot#pop.

Calling this function requires two subsequent calls to Gtk::Snapshot#pop.


def push_blur(radius : Float64) : Nil #

Blurs an image.

The image is recorded until the next call to Gtk::Snapshot#pop.


def push_clip(bounds : Graphene::Rect) : Nil #

Clips an image to a rectangle.

The image is recorded until the next call to Gtk::Snapshot#pop.


def push_color_matrix(color_matrix : Graphene::Matrix, color_offset : Graphene::Vec4) : 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 Gtk::Snapshot#pop.


def push_cross_fade(progress : Float64) : Nil #

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

Until the first call to Gtk::Snapshot#pop, the start image will be snapshot. After that call, the end image will be recorded until the second call to Gtk::Snapshot#pop.

Calling this function requires two subsequent calls to Gtk::Snapshot#pop.


def push_fill(path : Gsk::Path, fill_rule : Gsk::FillRule) : 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 Gtk::Snapshot#pop.

If you want to fill the path with a color, Gtk::Snapshot#append_fill may be more convenient.


def push_gl_shader(shader : Gsk::GLShader, bounds : Graphene::Rect, take_args : GLib::Bytes) : Nil #

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 Gsk::GLShader#compile to ensure the shader will work for the renderer before using it.

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

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

DEPRECATED


def push_mask(mask_mode : Gsk::MaskMode) : Nil #

Until the first call to Gtk::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 Gtk::Snapshot#pop.

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


def push_opacity(opacity : Float64) : Nil #

Modifies the opacity of an image.

The image is recorded until the next call to Gtk::Snapshot#pop.


def push_repeat(bounds : Graphene::Rect, child_bounds : Graphene::Rect | Nil) : Nil #

Creates a node that repeats the child node.

The child is recorded until the next call to Gtk::Snapshot#pop.


def push_rounded_clip(bounds : Gsk::RoundedRect) : Nil #

Clips an image to a rounded rectangle.

The image is recorded until the next call to Gtk::Snapshot#pop.


def push_shadow(shadow : Enumerable(Gsk::Shadow)) : Nil #

Applies a shadow to an image.

The image is recorded until the next call to Gtk::Snapshot#pop.


def push_shadow(*shadow : Gsk::Shadow) #

def push_stroke(path : Gsk::Path, stroke : Gsk::Stroke) : Nil #

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

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


def render_background(context : Gtk::StyleContext, x : Float64, y : Float64, width : Float64, height : Float64) : 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.

DEPRECATED


def render_focus(context : Gtk::StyleContext, x : Float64, y : Float64, width : Float64, height : Float64) : 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.

DEPRECATED


def render_frame(context : Gtk::StyleContext, x : Float64, y : Float64, width : Float64, height : Float64) : 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.

DEPRECATED


def render_insertion_cursor(context : Gtk::StyleContext, x : Float64, y : Float64, layout : Pango::Layout, index : Int32, direction : Pango::Direction) : Nil #

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

DEPRECATED


def render_layout(context : Gtk::StyleContext, x : Float64, y : Float64, layout : Pango::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.

DEPRECATED


def restore : Nil #

Restores snapshot to the state saved by a preceding call to Snapshot::save and removes that state from the stack of saved states.


def rotate(angle : Float32) : 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 [method@Gsk.Transform.rotate_3d].


def rotate_3d(angle : Float32, axis : Graphene::Vec3) : Nil #

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

For a rotation in 2D space, use Gsk::Transform#rotate.


def save : Nil #

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

When Gtk::Snapshot#restore is called, snapshot will be restored to the saved state.

Multiple calls to Gtk::Snapshot#save and Gtk::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().


def scale(factor_x : Float32, factor_y : Float32) : Nil #

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

Use [method@Gtk.Snapshot.scale_3d] to scale in all 3 dimensions.


def scale_3d(factor_x : Float32, factor_y : Float32, factor_z : Float32) : Nil #

Scales snapshot's coordinate system by the given factors.


def to_node : Gsk::RenderNode | Nil #

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 GObject::Object#unref.


def to_paintable(size : Graphene::Size | Nil) : Gdk::Paintable | Nil #

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 GObject::Object#unref.


def transform(transform : Gsk::Transform | Nil) : Nil #

Transforms snapshot's coordinate system with the given transform.


def transform_matrix(matrix : Graphene::Matrix) : Nil #

Transforms snapshot's coordinate system with the given matrix.


def translate(point : Graphene::Point) : Nil #

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


def translate_3d(point : Graphene::Point3D) : Nil #

Translates snapshot's coordinate system by point.