Class Renderer

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gsk.Renderer

All Implemented Interfaces:

Proxy

Direct Known Subclasses:

BroadwayRenderer, CairoRenderer, GLRenderer, NglRenderer, Renderer.Renderer$Impl, VulkanRenderer

@Generated("org.javagi.JavaGI")
public abstract class Renderer
extends GObject

Renders a scene graph defined via a tree of RenderNode instances.

Typically you will use a GskRenderer instance to repeatedly call render(RenderNode, Region) to update the contents of its associated Surface.

It is necessary to realize a GskRenderer instance using realize(Surface) before calling render(RenderNode, Region), in order to create the appropriate windowing system resources needed to render the scene.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Renderer.Builder<B extends Renderer.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static class	Renderer.Renderer$Impl	The Renderer$Impl type represents a native instance of the abstract Renderer class.
static class	Renderer.RendererClass

Nested classes/interfaces inherited from class GObject

GObject.NotifyCallback, GObject.ObjectClass

Constructor Summary

Constructors

Constructor	Description
Renderer()	Create a new Renderer.
Renderer(MemorySegment address)	Create a Renderer instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
protected Renderer	asParent()	Return this instance as if it were its parent type.
static @Nullable Renderer	forSurface(Surface surface)	Creates an appropriate GskRenderer instance for the given surface.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
@Nullable Surface	getSurface()	Retrieves the surface that the renderer is associated with.
static @Nullable Type	getType()	Get the GType of the Renderer class.
boolean	isRealized()	Checks whether the renderer is realized or not.
boolean	realize(@Nullable Surface surface)	Creates the resources needed by the renderer.
boolean	realizeForDisplay(Display display)	Creates the resources needed by the renderer.
void	render(RenderNode root, @Nullable org.freedesktop.cairo.Region region)	Renders the scene graph, described by a tree of GskRenderNode instances to the renderer's surface, ensuring that the given region gets redrawn.
Texture	renderTexture(RenderNode root, @Nullable Rect viewport)	Renders a scene graph, described by a tree of GskRenderNode instances, to a texture.
void	unrealize()	Releases all the resources created by realize(Surface).

Methods inherited from class GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, builder, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newv, notify, notify, notifyByPspec, onNotify, ref, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, unref, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class TypeInstance

callParent, callParent, cast, getPrivate, readGClass, writeGClass

Methods inherited from class ProxyInstance

equals, handle, hashCode

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Renderer

public Renderer(MemorySegment address)

Create a Renderer instance for the provided memory address.

Parameters:

address - the memory address of the native object

Renderer

public Renderer()

Create a new Renderer.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the Renderer class.

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

asParent

protected Renderer asParent()

Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.

Overrides:

asParent in class GObject

Returns:

the instance as if it were its parent type

forSurface

public static @Nullable Renderer forSurface(Surface surface)

Creates an appropriate GskRenderer instance for the given surface.

If the GSK_RENDERER environment variable is set, GSK will try that renderer first, before trying the backend-specific default. The ultimate fallback is the cairo renderer.

The renderer will be realized before it is returned.

Parameters:

surface - a surface

Returns:

the realized renderer

getSurface

public @Nullable Surface getSurface()

Retrieves the surface that the renderer is associated with.

If the renderer has not been realized yet, NULL will be returned.

Returns:

the surface

isRealized

public boolean isRealized()

Checks whether the renderer is realized or not.

Returns:

true if the renderer was realized, false otherwise

realize

public boolean realize(@Nullable Surface surface)
                throws GErrorException

Creates the resources needed by the renderer.

Since GTK 4.6, the surface may be NULL, which allows using renderers without having to create a surface. Since GTK 4.14, it is recommended to use realizeForDisplay(Display) for this case.

Note that it is mandatory to call unrealize() before destroying the renderer.

Parameters:

surface - the surface that renderer will be used on

Returns:

whether the renderer was successfully realized

Throws:

GErrorException - see GError

realizeForDisplay

public boolean realizeForDisplay(Display display)
                          throws GErrorException

Creates the resources needed by the renderer.

Note that it is mandatory to call unrealize() before destroying the renderer.

Parameters:

display - the display that the renderer will be used on

Returns:

whether the renderer was successfully realized

Throws:

GErrorException - see GError

Since:

4.14

render

public void render(RenderNode root,
 @Nullable org.freedesktop.cairo.Region region)

Renders the scene graph, described by a tree of GskRenderNode instances to the renderer's surface, ensuring that the given region gets redrawn.

If the renderer has no associated surface, this function does nothing.

Renderers must ensure that changes of the contents given by the root node as well as the area given by region are redrawn. They are however free to not redraw any pixel outside of region if they can guarantee that it didn't change.

The renderer will acquire a reference on the GskRenderNode tree while the rendering is in progress.

Parameters:

root - the render node to render

region - the cairo_region_t that must be redrawn or NULL for the whole surface

renderTexture

public Texture renderTexture(RenderNode root,
 @Nullable Rect viewport)

Renders a scene graph, described by a tree of GskRenderNode instances, to a texture.

The renderer will acquire a reference on the GskRenderNode tree while the rendering is in progress.

If you want to apply any transformations to root, you should put it into a transform node and pass that node instead.

Parameters:

root - the render node to render

viewport - the section to draw or NULL to use root's bounds

Returns:

a texture with the rendered contents of root

unrealize

public void unrealize()

Releases all the resources created by realize(Surface).