Gnome::GdkPixbuf::Pixbuf
Description
Gnome::Gtk4::Snapshot assists in creating Gnome::Gsk4::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 [method $Snapshot
.pop] to change the current node.
The typical way to obtain a Gnome::Gtk4::Snapshot object is as an argument to the [vfunc $Gtk
.Widget.snapshot] vfunc. If you need to create your own Gnome::Gtk4::Snapshot, use .newsnapshot()
.
Class initialization
new
:native-object
Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.
multi method new ( N-Object :$native-object! )
new-snapshot
Creates a new Gnome::Gtk4::Snapshot.
method new-snapshot ( --> Gnome::Gtk4::Snapshot \)
Methods
append-border
Appends a stroked border rectangle inside the given $outline
.
The four sides of the border can have different widths and colors.
method append-border ( N-Object $outline, Num() $border-width, N-Object $border-color )
$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.
append-cairo
Creates a new Gnome::Gsk4::CairoNode and appends it to the current render node of $snapshot
, without changing the current node.
method append-cairo ( N-Object $bounds --> UInt )
$bounds; the bounds for the new node
Return value; a Gnome::Cairo::N-Context suitable for drawing the contents of the newly created render node.
append-color
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.
method append-color ( N-Object $color, N-Object $bounds )
$color; the color to draw
$bounds; the bounds for the new node
append-conic-gradient
Appends a conic gradient node with the given stops to $snapshot
.
method append-conic-gradient ( N-Object $bounds, N-Object $center, Num() $rotation, N-Object $stops, Int() $n-stops )
$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
$n-stops; the number of elements in
$stops
.
append-fill
A convenience method to fill a path with a color.
See .push-fill()
if you need to fill a path with more complex content than a color.
method append-fill ( N-Object $path, GskFillRule $fill-rule, N-Object $color )
$path; The path describing the area to fill
$fill-rule; The fill rule to use.
$color; the color to fill the path with
append-inset-shadow
Appends an inset shadow into the box given by $outline
.
method append-inset-shadow ( N-Object $outline, N-Object $color, Num() $dx, Num() $dy, Num() $spread, Num() $blur-radius )
$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.
append-layout
No documentation of method.
method append-layout ( N-Object() $layout, N-Object $color )
$layout; .
$color;
append-linear-gradient
Appends a linear gradient node with the given stops to $snapshot
.
method append-linear-gradient ( N-Object $bounds, N-Object $start-point, N-Object $end-point, N-Object $stops, Int() $n-stops )
$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
$n-stops; the number of elements in
$stops
.
append-node
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.
method append-node ( N-Object() $node )
$node; a Gnome::Gsk4::RenderNode.
append-outset-shadow
Appends an outset shadow node around the box given by $outline
.
method append-outset-shadow ( N-Object $outline, N-Object $color, Num() $dx, Num() $dy, Num() $spread, Num() $blur-radius )
$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.
append-radial-gradient
Appends a radial gradient node with the given stops to $snapshot
.
method append-radial-gradient ( N-Object $bounds, N-Object $center, Num() $hradius, Num() $vradius, Num() $start, Num() $end, N-Object $stops, Int() $n-stops )
$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
$n-stops; the number of elements in
$stops
.
append-repeating-linear-gradient
Appends a repeating linear gradient node with the given stops to $snapshot
.
method append-repeating-linear-gradient ( N-Object $bounds, N-Object $start-point, N-Object $end-point, N-Object $stops, Int() $n-stops )
$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
$n-stops; the number of elements in
$stops
.
append-repeating-radial-gradient
Appends a repeating radial gradient node with the given stops to $snapshot
.
method append-repeating-radial-gradient ( N-Object $bounds, N-Object $center, Num() $hradius, Num() $vradius, Num() $start, Num() $end, N-Object $stops, Int() $n-stops )
$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
$n-stops; the number of elements in
$stops
.
append-scaled-texture
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 .append-texture()
, this function provides control about how the filter that is used when scaling.
method append-scaled-texture ( N-Object() $texture, GskScalingFilter $filter, N-Object $bounds )
$texture; the texture to render.
$filter; the filter to use.
$bounds; the bounds for the new node
append-stroke
A convenience method to stroke a path with a color.
See .push-stroke()
if you need to stroke a path with more complex content than a color.
method append-stroke ( N-Object $path, N-Object $stroke, N-Object $color )
$path; The path describing the area to fill
$stroke; The stroke attributes
$color; the color to fill the path with
append-texture
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 .append-scaled-texture()
if you need other filtering, such as nearest-neighbour.
method append-texture ( N-Object() $texture, N-Object $bounds )
$texture; the texture to render.
$bounds; the bounds for the new node
free-to-node
Returns the node that was constructed by $snapshot
and frees $snapshot
.
See also .to-node()
.
method free-to-node (--> N-Object )
Return value; a newly-created Gnome::Gsk4::RenderNode.
free-to-paintable
Returns a paintable for the node that was constructed by $snapshot
and frees $snapshot
.
method free-to-paintable ( N-Object $size --> N-Object )
$size; The size of the resulting paintable or undefined to use the bounds of the snapshot
Return value; a newly-created Gnome::Gdk4::R-Paintable.
gl-shader-pop-texture
Removes the top element from the stack of render nodes and adds it to the nearest Gnome::Gsk4::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()
.
method gl-shader-pop-texture ( )
perspective
Applies a perspective projection transform.
See .perspective()
in class Gnome::Gsk4::N-Transform
for a discussion on the details.
method perspective ( Num() $depth )
$depth; distance of the z=0 plane.
pop
Removes the top element from the stack of render nodes, and appends it to the node underneath it.
method pop ( )
push-blend
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()
.
method push-blend ( GskBlendMode $blend-mode )
$blend-mode; blend mode to use.
push-blur
Blurs an image.
The image is recorded until the next call to .pop()
.
method push-blur ( Num() $radius )
$radius; the blur radius to use. Must be positive.
push-clip
Clips an image to a rectangle.
The image is recorded until the next call to .pop()
.
method push-clip ( N-Object $bounds )
$bounds; the rectangle to clip to
push-color-matrix
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()
.
method push-color-matrix ( N-Object $color-matrix, N-Object $color-offset )
$color-matrix; the color matrix to use
$color-offset; the color offset to use
push-cross-fade
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()
.
method push-cross-fade ( Num() $progress )
$progress; progress between 0.0 and 1.0.
push-debug This function is not yet available
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.
method push-debug ( Str $message, … )
$message; a printf-style format string.
…; …. Note that each argument must be specified as a type followed by its value!
push-fill
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()
.
If you want to fill the path with a color, .append-fill()
may be more convenient.
method push-fill ( N-Object $path, GskFillRule $fill-rule )
$path; The path describing the area to fill
$fill-rule; The fill rule to use.
push-gl-shader
Push a Gnome::Gsk4::GLShaderNode.
The node uses the given Gnome::Gsk4::GLShader and uniform values Additionally this takes a list of $n-children
other nodes which will be passed to the Gnome::Gsk4::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 .format-args()
in class Gnome::Gsk4::GLShader
or Gnome::Gsk4::N-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 .compile()
in class Gnome::Gsk4::GLShader
to ensure the $shader
will work for the renderer before using it.
If the shader requires textures (see .get-n-textures()
in class Gnome::Gsk4::GLShader
), 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 Gnome::Gsk4::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 Gnome::Gsk4::GLShader.
method push-gl-shader ( N-Object() $shader, N-Object $bounds, N-Object $take-args )
$shader; The code to run.
$bounds; the rectangle to render into
$take-args; (transfer ownership: full) Data block with arguments for the shader.
push-mask
Until the first call to .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()
.
Calling this function requires 2 subsequent calls to .pop()
.
method push-mask ( GskMaskMode $mask-mode )
$mask-mode; mask mode to use.
push-opacity
Modifies the opacity of an image.
The image is recorded until the next call to .pop()
.
method push-opacity ( Num() $opacity )
$opacity; the opacity to use.
push-repeat
Creates a node that repeats the child node.
The child is recorded until the next call to .pop()
.
method push-repeat ( N-Object $bounds, N-Object $child-bounds )
$bounds; the bounds within which to repeat
$child-bounds; the bounds of the child or undefined to use the full size of the collected child node
push-rounded-clip
Clips an image to a rounded rectangle.
The image is recorded until the next call to .pop()
.
method push-rounded-clip ( N-Object $bounds )
$bounds; the rounded rectangle to clip to
push-shadow
Applies a shadow to an image.
The image is recorded until the next call to .pop()
.
method push-shadow ( N-Object $shadow, Int() $n-shadows )
$shadow; the first shadow specification
$n-shadows; number of shadow specifications.
push-stroke
Strokes the given $path
with the attributes given by $stroke
and an image.
The image is recorded until the next call to .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()
may be more convenient.
method push-stroke ( N-Object $path, N-Object $stroke )
$path; The path to stroke
$stroke; The stroke attributes
render-background
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
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.
method render-background ( N-Object() $context, Num() $x, Num() $y, Num() $width, Num() $height )
$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.
render-focus
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
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.
method render-focus ( N-Object() $context, Num() $x, Num() $y, Num() $width, Num() $height )
$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.
render-frame
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
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.
method render-frame ( N-Object() $context, Num() $x, Num() $y, Num() $width, Num() $height )
$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.
render-insertion-cursor
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
Draws a text caret using $snapshot
at the specified index of $layout
.
method render-insertion-cursor ( N-Object() $context, Num() $x, Num() $y, N-Object() $layout, Int() $index, PangoDirection $direction )
$context; a Gnome::Gtk4::StyleContext.
$x; X origin.
$y; Y origin.
$layout; the Gnome::Pango::Layout of the text.
$index; the index in the Gnome::Pango::Layout.
$direction; the
enumeration PangoDirection defined in Gnome::Pango::T-direction
of the text.
render-layout
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
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.
method render-layout ( N-Object() $context, Num() $x, Num() $y, N-Object() $layout )
$context; the style context that defines the text.
$x; X origin of the rectangle.
$y; Y origin of the rectangle.
$layout; the Gnome::Pango::Layout to render.
restore
Restores $snapshot
to the state saved by a preceding call to [method $Snapshot
.save] and removes that state from the stack of saved states.
method restore ( )
rotate
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 .rotate3d()
in class Gnome::Gsk4::N-Transform
.
method rotate ( Num() $angle )
$angle; the rotation angle, in degrees (clockwise).
rotate3d
Rotates $snapshot
's coordinate system by $angle
degrees around $axis
.
For a rotation in 2D space, use .rotate()
in class Gnome::Gsk4::N-Transform
.
method rotate3d ( Num() $angle, N-Object $axis )
$angle; the rotation angle, in degrees (clockwise).
$axis; The rotation axis
save
Makes a copy of the current state of $snapshot
and saves it on an internal stack.
When .restore()
is called, $snapshot
will be restored to the saved state.
Multiple calls to .save()
and .restore()
can be nested; each call to C<.restore()>` restores the state from the matching paired C<.save()>`.
It is necessary to clear all saved states with corresponding calls to C<.restore()>`.
method save ( )
scale
Scales $snapshot
's coordinate system in 2-dimensional space by the given factors.
Use .scale3d()
to scale in all 3 dimensions.
method scale ( Num() $factor-x, Num() $factor-y )
$factor-x; scaling factor on the X axis.
$factor-y; scaling factor on the Y axis.
scale3d
Scales $snapshot
's coordinate system by the given factors.
method scale3d ( Num() $factor-x, Num() $factor-y, Num() $factor-z )
$factor-x; scaling factor on the X axis.
$factor-y; scaling factor on the Y axis.
$factor-z; scaling factor on the Z axis.
to-node
Returns the render node that was constructed by $snapshot
.
Note that this function may return undefined 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 .unref()
in class Gnome::GObject::Object
.
method to-node (--> N-Object )
Return value; the constructed Gnome::Gsk4::RenderNode or undefined if there are no nodes to render..
to-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 .unref()
in class Gnome::GObject::Object
.
method to-paintable ( N-Object $size --> N-Object )
$size; The size of the resulting paintable or undefined to use the bounds of the snapshot
Return value; a new Gnome::Gdk4::R-Paintable.
transform
Transforms $snapshot
's coordinate system with the given $transform
.
method transform ( N-Object $transform )
$transform; the transform to apply
transform-matrix
Transforms $snapshot
's coordinate system with the given $matrix
.
method transform-matrix ( N-Object $matrix )
$matrix; the matrix to multiply the transform with
translate
Translates $snapshot
's coordinate system by $point
in 2-dimensional space.
method translate ( N-Object $point )
$point; the point to translate the snapshot by
translate3d
Translates $snapshot
's coordinate system by $point
.
method translate3d ( N-Object $point )
$point; the point to translate the snapshot by