Gtk.GraphicsOffload¶

Subclasses:: None

Methods¶

Inherited:: Gtk.Widget (181), GObject.Object (37), Gtk.Accessible (16), Gtk.Buildable (1)
Structs:: Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	`new` (child)
	`get_black_background` ()
	`get_child` ()
	`get_enabled` ()
	`set_black_background` (value)
	`set_child` (child)
	`set_enabled` (enabled)

Virtual Methods¶

Inherited:: Gtk.Widget (25), GObject.Object (7), Gtk.Accessible (6), Gtk.Buildable (9)

Properties¶

Inherited:: Gtk.Widget (34), Gtk.Accessible (1)

Name	Type	Flags
`black-background`	`bool`	r/w/en
`child`	`Gtk.Widget`	r/w/en
`enabled`	`Gtk.GraphicsOffloadEnabled`	r/w/en

Signals¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Fields¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Class Details¶

class Gtk.GraphicsOffload(**kwargs)¶

Bases:: Gtk.Widget
Abstract:: No
Structure:: Gtk.GraphicsOffloadClass

A widget that allows to bypass gsk rendering for its child by passing the content 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 [class`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 [method`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.

New in version 4.14.

classmethod new(child)[source]¶

Parameters:: child (Gtk.Widget or None) – the child widget
Returns:: the new widget
Return type:: Gtk.Widget

Creates a new Gtk.GraphicsOffload widget.

New in version 4.14.

get_black_background()[source]¶

Returns:: TRUE if black background is drawn
Return type:: bool

Returns whether the widget draws a black background.

See [method`Gtk`.GraphicsOffload.set_black_background].

New in version 4.16.

get_child()[source]¶

Returns:: the child widget
Return type:: Gtk.Widget or None

Gets the child of self.

New in version 4.14.

get_enabled()[source]¶

Returns:: whether offload is enabled
Return type:: Gtk.GraphicsOffloadEnabled

Returns whether offload is enabled for self.

New in version 4.14.

set_black_background(value)[source]¶

Parameters:: value (bool) – whether to draw a black background behind the content

Sets whether this Gtk.GraphicsOffload 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.

New in version 4.16.

set_child(child)[source]¶

Parameters:: child (Gtk.Widget or None) – the child widget

Sets the child of self.

New in version 4.14.

set_enabled(enabled)[source]¶

Parameters:: enabled (Gtk.GraphicsOffloadEnabled) – whether to enable offload

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

New in version 4.14.

Property Details¶

Gtk.GraphicsOffload.props.black_background¶

Name:: black-background
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether to draw a black background.

New in version 4.16.

Gtk.GraphicsOffload.props.child¶

Name:: child
Type:: Gtk.Widget
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The child widget.

New in version 4.14.

Gtk.GraphicsOffload.props.enabled¶

Name:: enabled
Type:: Gtk.GraphicsOffloadEnabled
Default Value:: Gtk.GraphicsOffloadEnabled.ENABLED
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether graphics offload is enabled.

New in version 4.14.