Skip to content

Gtk.GraphicsOffload

class — extends Widget, Accessible, Buildable, ConstraintTarget

Bypasses gsk rendering by passing the content of its child directly to the compositor.

Graphics offload is an optimization to reduce overhead and battery use that is most useful for video content. It only works on some platforms and in certain situations. GTK will automatically fall back to normal rendering if it doesn't.

Graphics offload is most efficient if there are no controls drawn on top of the video content.

You should consider using graphics offload for your main widget if it shows frequently changing content (such as a video, or a VM display) and you provide the content in the form of dmabuf textures (see Gdk.DmabufTextureBuilder), in particular if it may be fullscreen.

Numerous factors can prohibit graphics offload:

  • Unsupported platforms. Currently, graphics offload only works on Linux with Wayland.

  • Clipping, such as rounded corners that cause the video content to not be rectangular

  • Unsupported dmabuf formats (see Gdk.Display.get_dmabuf_formats)

  • Translucent video content (content with an alpha channel, even if it isn't used)

  • Transforms that are more complex than translations and scales

  • Filters such as opacity, grayscale or similar

To investigate problems related graphics offload, GTK offers debug flags to print out information about graphics offload and dmabuf use:

GDK_DEBUG=offload
GDK_DEBUG=dmabuf

The GTK inspector provides a visual debugging tool for graphics offload.

Constructors

new

@classmethod
def new(cls, child: Widget | None = ...) -> Widget

Creates a new GtkGraphicsOffload widget.

Parameters:

  • child — the child widget

Methods

get_black_background

def get_black_background(self) -> bool

Returns whether the widget draws a black background.

See GraphicsOffload.set_black_background.

get_child

def get_child(self) -> Widget | None

Gets the child of self.

get_enabled

def get_enabled(self) -> GraphicsOffloadEnabled

Returns whether offload is enabled for self.

set_black_background

def set_black_background(self, value: bool) -> None

Sets whether this GtkGraphicsOffload widget will draw a black background.

A main use case for this is letterboxing where black bars are visible next to the content if the aspect ratio of the content does not match the dimensions of the monitor.

Using this property for letterboxing instead of CSS allows compositors to show content with maximum efficiency, using direct scanout to avoid extra copies in the compositor.

On Wayland, this is implemented using the single-pixel buffer protocol.

Parameters:

  • value — whether to draw a black background behind the content

set_child

def set_child(self, child: Widget | None = ...) -> None

Sets the child of self.

Parameters:

  • child — the child widget

set_enabled

def set_enabled(self, enabled: GraphicsOffloadEnabled | int) -> None

Sets whether this GtkGraphicsOffload widget will attempt to offload the content of its child widget.

Parameters:

  • enabled — whether to enable offload

Properties

black_background

black_background: bool  # read/write

Whether to draw a black background.

child

child: Widget  # read/write

The child widget.

enabled

enabled: GraphicsOffloadEnabled | int  # read/write

Whether graphics offload is enabled.