GskRenderNode

GskRenderNode — Simple scene graph element

Functions

GskRenderNode * gsk_render_node_ref ()
void gsk_render_node_unref ()
GskRenderNodeType gsk_render_node_get_node_type ()
void gsk_render_node_draw ()
GBytes * gsk_render_node_serialize ()
GskRenderNode * gsk_render_node_deserialize ()
gboolean gsk_render_node_write_to_file ()
void gsk_render_node_set_name ()
const char * gsk_render_node_get_name ()
void gsk_render_node_get_bounds ()
GskRenderNode * gsk_color_node_new ()
GskRenderNode * gsk_linear_gradient_node_new ()
GskRenderNode * gsk_repeating_linear_gradient_node_new ()
GskRenderNode * gsk_border_node_new ()
GskRenderNode * gsk_texture_node_new ()
GskRenderNode * gsk_inset_shadow_node_new ()
GskRenderNode * gsk_outset_shadow_node_new ()
GskRenderNode * gsk_cairo_node_new ()
cairo_t * gsk_cairo_node_get_draw_context ()
GskRenderNode * gsk_container_node_new ()
guint gsk_container_node_get_n_children ()
GskRenderNode * gsk_container_node_get_child ()
GskRenderNode * gsk_transform_node_new ()
GskRenderNode * gsk_transform_node_get_child ()
GskRenderNode * gsk_opacity_node_new ()
GskRenderNode * gsk_opacity_node_get_child ()
GskRenderNode * gsk_color_matrix_node_new ()
GskRenderNode * gsk_repeat_node_new ()
GskRenderNode * gsk_clip_node_new ()
GskRenderNode * gsk_clip_node_get_child ()
GskRenderNode * gsk_rounded_clip_node_new ()
GskRenderNode * gsk_rounded_clip_node_get_child ()
GskRenderNode * gsk_shadow_node_new ()
GskRenderNode * gsk_blend_node_new ()
GskRenderNode * gsk_cross_fade_node_new ()

Types and Values

Object Hierarchy

    GBoxed
    ╰── GskRenderNode

Description

GskRenderNode is the basic block in a scene graph to be rendered using GskRenderer.

Each node has a parent, except the top-level node; each node may have children nodes.

Each node has an associated drawing surface, which has the size of the rectangle set using gsk_render_node_set_bounds(). Nodes have an associated transformation matrix, which is used to position and transform the node on the scene graph; additionally, they also have a child transformation matrix, which will be applied to each child.

Render nodes are meant to be transient; once they have been associated to a GskRenderer it's safe to release any reference you have on them. All GskRenderNodes are immutable, you can only specify their properties during construction.

Functions

gsk_render_node_ref ()

GskRenderNode *
gsk_render_node_ref (GskRenderNode *node);

Acquires a reference on the given GskRenderNode.

Parameters

node

a GskRenderNode

 

Returns

the GskRenderNode with an additional reference.

[transfer none]

Since: 3.90


gsk_render_node_unref ()

void
gsk_render_node_unref (GskRenderNode *node);

Releases a reference on the given GskRenderNode.

If the reference was the last, the resources associated to the node are freed.

Parameters

node

a GskRenderNode

 

Since: 3.90


gsk_render_node_get_node_type ()

GskRenderNodeType
gsk_render_node_get_node_type (GskRenderNode *node);

Returns the type of the node .

Parameters

node

a GskRenderNode

 

Returns

the type of the GskRenderNode

Since: 3.90


gsk_render_node_draw ()

void
gsk_render_node_draw (GskRenderNode *node,
                      cairo_t *cr);

Draw the contents of node to the given cairo context.

Typically, you'll use this function to implement fallback rendering of GskRenderNodes on an intermediate Cairo context, instead of using the drawing context associated to a GdkWindow's rendering buffer.

For advanced nodes that cannot be supported using Cairo, in particular for nodes doing 3D operations, this function may fail.

Parameters

node

a GskRenderNode

 

cr

cairo context to draw to

 

gsk_render_node_serialize ()

GBytes *
gsk_render_node_serialize (GskRenderNode *node);

Serializes the node for later deserialization via gsk_render_node_deserialize(). No guarantees are made about the format used other than that the same version of GTK+ will be able to deserialize the result of a call to gsk_render_node_serialize() and gsk_render_node_deserialize() will correctly reject files it cannot open that were created with previous versions of GTK+.

The intended use of this functions is testing, benchmarking and debugging. The format is not meant as a permanent storage format.

Parameters

node

a GskRenderNode

 

Returns

a GBytes representing the node.


gsk_render_node_deserialize ()

GskRenderNode *
gsk_render_node_deserialize (GBytes *bytes,
                             GError **error);

Loads data previously created via gsk_render_node_serialize(). For a discussion of the supported format, see that function.

Parameters

bytes

the bytes containing the data

 

error

location to store error or NULL.

[allow-none]

Returns

a new GskRenderNode or NULL on error.

[nullable][transfer full]


gsk_render_node_write_to_file ()

gboolean
gsk_render_node_write_to_file (GskRenderNode *node,
                               const char *filename,
                               GError **error);

This function is equivalent to calling gsk_render_node_serialize() followed by g_file_set_contents(). See those two functions for details on the arguments.

It is mostly intended for use inside a debugger to quickly dump a render node to a file for later inspection.

Parameters

node

a GskRenderNode

 

filename

the file to save it to.

 

error

Return location for a potential error

 

Returns

TRUE if saving was successful


gsk_render_node_set_name ()

void
gsk_render_node_set_name (GskRenderNode *node,
                          const char *name);

Sets the name of the node.

A name is generally useful for debugging purposes.

Parameters

node

a GskRenderNode

 

name

a name for the node.

[nullable]

Since: 3.90


gsk_render_node_get_name ()

const char *
gsk_render_node_get_name (GskRenderNode *node);

Retrieves the name previously set via gsk_render_node_set_name(). If no name has been set, NULL is returned.

Parameters

node

a GskRenderNode

 

Returns

The name previously set via gsk_render_node_set_name() or NULL.

[nullable]

Since: 3.90


gsk_render_node_get_bounds ()

void
gsk_render_node_get_bounds (GskRenderNode *node,
                            graphene_rect_t *bounds);

Retrieves the boundaries of the node . The node will not draw outside of its boundaries.

Parameters

node

a GskRenderNode

 

bounds

return location for the boundaries.

[out caller-allocates]

Since: 3.90


gsk_color_node_new ()

GskRenderNode *
gsk_color_node_new (const GdkRGBA *rgba,
                    const graphene_rect_t *bounds);

Creates a GskRenderNode that will render the color specified by rgba into the area given by bounds .

Parameters

rgba

a GdkRGBA specifying a color

 

bounds

the rectangle to render the color into

 

Returns

A new GskRenderNode

Since: 3.90


gsk_linear_gradient_node_new ()

GskRenderNode *
gsk_linear_gradient_node_new (const graphene_rect_t *bounds,
                              const graphene_point_t *start,
                              const graphene_point_t *end,
                              const GskColorStop *color_stops,
                              gsize n_color_stops);

Creates a GskRenderNode that will create a linear gradient from the given points and color stops, and render that into the area given by bounds .

Parameters

bounds

the rectangle to render the linear gradient into

 

start

the point at which the linear gradient will begin

 

end

the point at which the linear gradient will finish

 

color_stops

a pointer to an array of GskColorStop defining the gradient

 

n_color_stops

the number of elements in color_stops

 

Returns

A new GskRenderNode

Since: 3.90


gsk_repeating_linear_gradient_node_new ()

GskRenderNode *
gsk_repeating_linear_gradient_node_new
                               (const graphene_rect_t *bounds,
                                const graphene_point_t *start,
                                const graphene_point_t *end,
                                const GskColorStop *color_stops,
                                gsize n_color_stops);

gsk_border_node_new ()

GskRenderNode *
gsk_border_node_new (const GskRoundedRect *outline,
                     const float border_width[4],
                     const GdkRGBA border_color[4]);

Creates a GskRenderNode that will stroke a border rectangle inside the given outline . The 4 sides of the border can have different widths and colors.

Parameters

outline

a GskRoundedRect describing 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.

 

Returns

A new GskRenderNode

Since: 3.90


gsk_texture_node_new ()

GskRenderNode *
gsk_texture_node_new (GskTexture *texture,
                      const graphene_rect_t *bounds);

Creates a GskRenderNode that will render the given texture into the area given by bounds .

Parameters

texture

the GskTexture

 

bounds

the rectangle to render the texture into

 

Returns

A new GskRenderNode

Since: 3.90


gsk_inset_shadow_node_new ()

GskRenderNode *
gsk_inset_shadow_node_new (const GskRoundedRect *outline,
                           const GdkRGBA *color,
                           float dx,
                           float dy,
                           float spread,
                           float blur_radius);

Creates a GskRenderNode that will render an inset shadow into the box given by outline .

Parameters

outline

outline of the region containing the 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

 

Returns

A new GskRenderNode

Since: 3.90


gsk_outset_shadow_node_new ()

GskRenderNode *
gsk_outset_shadow_node_new (const GskRoundedRect *outline,
                            const GdkRGBA *color,
                            float dx,
                            float dy,
                            float spread,
                            float blur_radius);

Creates a GskRenderNode that will render an outset shadow around the box given by outline .

Parameters

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

 

Returns

A new GskRenderNode

Since: 3.90


gsk_cairo_node_new ()

GskRenderNode *
gsk_cairo_node_new (const graphene_rect_t *bounds);

Creates a GskRenderNode that will render a cairo surface into the area given by bounds . You can draw to the cairo surface using gsk_cairo_node_get_draw_context()

Parameters

bounds

the rectangle to render to

 

Returns

A new GskRenderNode

Since: 3.90


gsk_cairo_node_get_draw_context ()

cairo_t *
gsk_cairo_node_get_draw_context (GskRenderNode *node,
                                 GskRenderer *renderer);

Creates a Cairo context for drawing using the surface associated to the render node. If no surface exists yet, a surface will be created optimized for rendering to renderer .

Parameters

node

a cairo GskRenderNode

 

renderer

Renderer to optimize for or NULL for any.

[nullable]

Returns

a Cairo context used for drawing; use cairo_destroy() when done drawing.

[transfer full]

Since: 3.90


gsk_container_node_new ()

GskRenderNode *
gsk_container_node_new (GskRenderNode **children,
                        guint n_children);

Creates a new GskRenderNode instance for holding the given children . The new node will acquire a reference to each of the children.

Parameters

children

The children of the node.

[array length=n_children][transfer none]

n_children

Number of children in the children array

 

Returns

the new GskRenderNode.

[transfer full]

Since: 3.90


gsk_container_node_get_n_children ()

guint
gsk_container_node_get_n_children (GskRenderNode *node);

Retrieves the number of direct children of node .

Parameters

node

a container GskRenderNode

 

Returns

the number of children of the GskRenderNode

Since: 3.90


gsk_container_node_get_child ()

GskRenderNode *
gsk_container_node_get_child (GskRenderNode *node,
                              guint idx);

gsk_transform_node_new ()

GskRenderNode *
gsk_transform_node_new (GskRenderNode *child,
                        const graphene_matrix_t *transform);

Creates a GskRenderNode that will transform the given child with the given transform .

Parameters

child

The node to transform

 

transform

The transform to apply

 

Returns

A new GskRenderNode

Since: 3.90


gsk_transform_node_get_child ()

GskRenderNode *
gsk_transform_node_get_child (GskRenderNode *node);

Gets the child node that is getting transformed by the given node .

Parameters

node

a transform GskRenderNode

 

Returns

The child that is getting transformed.

[transfer none]


gsk_opacity_node_new ()

GskRenderNode *
gsk_opacity_node_new (GskRenderNode *child,
                      double opacity);

Creates a GskRenderNode that will drawn the child with reduced opacity .

Parameters

child

The node to draw

 

opacity

The opacity to apply

 

Returns

A new GskRenderNode

Since: 3.90


gsk_opacity_node_get_child ()

GskRenderNode *
gsk_opacity_node_get_child (GskRenderNode *node);

Gets the child node that is getting opacityed by the given node .

Parameters

node

a opacity GskRenderNode

 

Returns

The child that is getting opacityed.

[transfer none]


gsk_color_matrix_node_new ()

GskRenderNode *
gsk_color_matrix_node_new (GskRenderNode *child,
                           const graphene_matrix_t *color_matrix,
                           const graphene_vec4_t *color_offset);

Creates a GskRenderNode that will drawn the child with reduced color_matrix .

In particular, the node will transform the operation pixel = color_matrix * pixel + color_offset for every pixel.

Parameters

child

The node to draw

 

color_matrix

The matrix to apply

 

color_offset

Values to add to the color

 

Returns

A new GskRenderNode

Since: 3.90


gsk_repeat_node_new ()

GskRenderNode *
gsk_repeat_node_new (const graphene_rect_t *bounds,
                     GskRenderNode *child,
                     const graphene_rect_t *child_bounds);

Creates a GskRenderNode that will repeat the drawing of child across the given bounds .

Parameters

bounds

The bounds of the area to be painted

 

child

The child to repeat

 

child_bounds

The area of the child to repeat or NULL to use the child's bounds.

[allow-none]

Returns

A new GskRenderNode

Since: 3.90


gsk_clip_node_new ()

GskRenderNode *
gsk_clip_node_new (GskRenderNode *child,
                   const graphene_rect_t *clip);

Creates a GskRenderNode that will clip the child to the area given by clip .

Parameters

child

The node to draw

 

clip

The clip to apply

 

Returns

A new GskRenderNode

Since: 3.90


gsk_clip_node_get_child ()

GskRenderNode *
gsk_clip_node_get_child (GskRenderNode *node);

Gets the child node that is getting clipped by the given node .

Parameters

node

a clip GskRenderNode

 

Returns

The child that is getting clipped.

[transfer none]


gsk_rounded_clip_node_new ()

GskRenderNode *
gsk_rounded_clip_node_new (GskRenderNode *child,
                           const GskRoundedRect *clip);

Creates a GskRenderNode that will clip the child to the area given by clip .

Parameters

child

The node to draw

 

clip

The clip to apply

 

Returns

A new GskRenderNode

Since: 3.90


gsk_rounded_clip_node_get_child ()

GskRenderNode *
gsk_rounded_clip_node_get_child (GskRenderNode *node);

Gets the child node that is getting clipped by the given node .

Parameters

node

a clip GskRenderNode

 

Returns

The child that is getting clipped.

[transfer none]


gsk_shadow_node_new ()

GskRenderNode *
gsk_shadow_node_new (GskRenderNode *child,
                     const GskShadow *shadows,
                     gsize n_shadows);

Creates a GskRenderNode that will draw a child with the given shadows below it.

Parameters

child

The node to draw

 

shadows

The shadows to apply.

[array length=n_shadows]

n_shadows

number of entries in the shadows array

 

Returns

A new GskRenderNode

Since: 3.90


gsk_blend_node_new ()

GskRenderNode *
gsk_blend_node_new (GskRenderNode *bottom,
                    GskRenderNode *top,
                    GskBlendMode blend_mode);

Creates a GskRenderNode that will use blend_mode to blend the top node onto the bottom node.

Parameters

bottom

The bottom node to be drawn

 

top

The node to be blended onto the bottom node

 

blend_mode

The blend mode to use

 

Returns

A new GskRenderNode

Since: 3.90


gsk_cross_fade_node_new ()

GskRenderNode *
gsk_cross_fade_node_new (GskRenderNode *start,
                         GskRenderNode *end,
                         double progress);

Creates a GskRenderNode that will do a cross-fade between start and end .

Parameters

start

The start node to be drawn

 

end

The node to be cross_fadeed onto the start node

 

progress

How far the fade has progressed from start to end. The value will be clamped to the range [0 ... 1]

 

Returns

A new GskRenderNode

Since: 3.90

Types and Values

enum GskRenderNodeType

The type of a node determines what the node is rendering.

Members

GSK_NOT_A_RENDER_NODE

Error type. No node will ever have this type.

 

GSK_CONTAINER_NODE

A node containing a stack of children

 

GSK_CAIRO_NODE

A node drawing a cairo_surface_t

 

GSK_COLOR_NODE

A node drawing a single color rectangle

 

GSK_LINEAR_GRADIENT_NODE

A node drawing a linear gradient

 

GSK_REPEATING_LINEAR_GRADIENT_NODE

A node drawing a repeating linear gradient

 

GSK_BORDER_NODE

A node stroking a border around an area

 

GSK_TEXTURE_NODE

A node drawing a GskTexture

 

GSK_INSET_SHADOW_NODE

A node drawing an inset shadow

 

GSK_OUTSET_SHADOW_NODE

A node drawing an outset shadow

 

GSK_TRANSFORM_NODE

A node that renders its child after applying a matrix transform

 

GSK_OPACITY_NODE

A node that changes the opacity of its child

 

GSK_COLOR_MATRIX_NODE

A node that applies a color matrix to every pixel

 

GSK_REPEAT_NODE

A node that repeats the child's contents

 

GSK_CLIP_NODE

A node that clips its child to a rectangular area

 

GSK_ROUNDED_CLIP_NODE

A node that clips its child to a rounded rectangle

 

GSK_SHADOW_NODE

A node that draws a shadow below its child

 

GSK_BLEND_NODE

A node the blends two children together

 

GSK_CROSS_FADE_NODE

A node the cross-fades between two children

 

Since: 3.90


enum GskSerializationError

Errors that can happen during (de)serialization.

Members

GSK_SERIALIZATION_UNSUPPORTED_FORMAT

The format can not be identified

 

GSK_SERIALIZATION_UNSUPPORTED_VERSION

The version of the data is not understood

 

GSK_SERIALIZATION_INVALID_DATA

The given data may not exist in a proper serialization

 

enum GskScalingFilter

The filters used when scaling texture data.

The actual implementation of each filter is deferred to the rendering pipeline.

Members

GSK_SCALING_FILTER_LINEAR

linear interpolation filter

 

GSK_SCALING_FILTER_NEAREST

nearest neighbor interpolation filter

 

GSK_SCALING_FILTER_TRILINEAR

linear interpolation along each axis, plus mipmap generation, with linear interpolation along the mipmap levels

 

Since: 3.90


struct GskShadow

struct GskShadow {
  GdkRGBA color;
  float dx;
  float dy;
  float radius;
};

enum GskBlendMode

The blend modes available for render nodes.

The implementation of each blend mode is deferred to the rendering pipeline.

Members

GSK_BLEND_MODE_DEFAULT

The default blend mode, which specifies no blending

 

GSK_BLEND_MODE_MULTIPLY

The source color is multiplied by the destination and replaces the destination

 

GSK_BLEND_MODE_SCREEN

...

 

GSK_BLEND_MODE_OVERLAY

...

 

GSK_BLEND_MODE_DARKEN

...

 

GSK_BLEND_MODE_LIGHTEN

...

 

GSK_BLEND_MODE_COLOR_DODGE

...

 

GSK_BLEND_MODE_COLOR_BURN

...

 

GSK_BLEND_MODE_HARD_LIGHT

...

 

GSK_BLEND_MODE_SOFT_LIGHT

...

 

GSK_BLEND_MODE_DIFFERENCE

...

 

GSK_BLEND_MODE_EXCLUSION

...

 

GSK_BLEND_MODE_COLOR

...

 

GSK_BLEND_MODE_HUE

...

 

GSK_BLEND_MODE_SATURATION

...

 

GSK_BLEND_MODE_LUMINOSITY

...

 

Since: 3.90