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 [classGdk.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 [methodGdk.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.
function "+"
(Widget : access Gtk_Graphics_Offload_Record'Class)
return Gtk.Accessible.Gtk_Accessible
function "+"
(Widget : access Gtk_Graphics_Offload_Record'Class)
return Gtk.Buildable.Gtk_Buildable
function "+"
(Widget : access Gtk_Graphics_Offload_Record'Class)
return Gtk.Constraint_Target.Gtk_Constraint_Target
function "-"
(Interf : Gtk.Accessible.Gtk_Accessible)
return Gtk_Graphics_Offload
function "-"
(Interf : Gtk.Buildable.Gtk_Buildable)
return Gtk_Graphics_Offload
function "-"
(Interf : Gtk.Constraint_Target.Gtk_Constraint_Target)
return Gtk_Graphics_Offload
procedure Announce
(Self : not null access Gtk_Graphics_Offload_Record;
Message : UTF8_String;
Priority : Gtk.Accessible.Gtk_Accessible_Announcement_Priority)
Black_Background_Property : constant Glib.Properties.Property_Boolean;
Whether to draw a black background.
Child_Property : constant Glib.Properties.Property_Object;
Type: Gtk.Widget.Gtk_Widget The child widget.
Enabled_Property : constant Gtk.Graphics_Offload.Property_Gtk_Graphics_Offload_Enabled;
Type: Gtk_Graphics_Offload_Enabled Whether graphics offload is enabled.
function Get_Accessible_Id
(Self : not null access Gtk_Graphics_Offload_Record)
return UTF8_String
function Get_Accessible_Parent
(Self : not null access Gtk_Graphics_Offload_Record)
return Gtk.Accessible.Gtk_Accessible
function Get_Accessible_Role
(Self : not null access Gtk_Graphics_Offload_Record)
return Gtk.Accessible.Gtk_Accessible_Role
function Get_At_Context
(Self : not null access Gtk_Graphics_Offload_Record)
return Gtk.Atcontext.Gtk_Atcontext
function Get_Black_Background
(Self : not null access Gtk_Graphics_Offload_Record) return Boolean
Returns whether the widget draws a black background. See [methodGtk.GraphicsOffload.set_black_background]. Since: gtk+ 4.16
TRUE if black background is drawn
function Get_Bounds
(Self : not null access Gtk_Graphics_Offload_Record;
X : out Glib.Gint;
Y : out Glib.Gint;
Width : out Glib.Gint;
Height : out Glib.Gint) return Boolean
function Get_Child
(Self : not null access Gtk_Graphics_Offload_Record)
return Gtk.Widget.Gtk_Widget
Gets the child of Self. Since: gtk+ 4.14
the child widget. Has transfer-ownership='none'.
function Get_Enabled
(Self : not null access Gtk_Graphics_Offload_Record)
return Gtk_Graphics_Offload_Enabled
Returns whether offload is enabled for Self. Since: gtk+ 4.14
whether offload is enabled
function Get_First_Accessible_Child
(Self : not null access Gtk_Graphics_Offload_Record)
return Gtk.Accessible.Gtk_Accessible
function Get_Next_Accessible_Sibling
(Self : not null access Gtk_Graphics_Offload_Record)
return Gtk.Accessible.Gtk_Accessible
function Get_Platform_State
(Self : not null access Gtk_Graphics_Offload_Record;
State : Gtk.Accessible.Gtk_Accessible_Platform_State) return Boolean
function Get_Type return Glib.GType
type Gtk_Graphics_Offload is access all Gtk_Graphics_Offload_Record'Class;
type Gtk_Graphics_Offload_Enabled is (
Enabled,
Disabled);
Represents the state of graphics offloading.
package Gtk_Graphics_Offload_Enabled_Properties is
new Generic_Internal_Discrete_Property (Gtk_Graphics_Offload_Enabled);
function Gtk_Graphics_Offload_New
(Child : access Gtk.Widget.Gtk_Widget_Record'Class)
return Gtk_Graphics_Offload
Creates a new GtkGraphicsOffload widget. Since: gtk+ 4.14
the child widget
type Gtk_Graphics_Offload_Record is new Gtk_Widget_Record with null record;
procedure Gtk_New
(Self : out Gtk_Graphics_Offload;
Child : access Gtk.Widget.Gtk_Widget_Record'Class)
Creates a new GtkGraphicsOffload widget. Since: gtk+ 4.14 Initialize does nothing if the object was already created with another call to Initialize* or G_New.
the child widget
package Implements_Gtk_Accessible is new Glib.Types.Implements
(Gtk.Accessible.Gtk_Accessible, Gtk_Graphics_Offload_Record, Gtk_Graphics_Offload);
package Implements_Gtk_Buildable is new Glib.Types.Implements
(Gtk.Buildable.Gtk_Buildable, Gtk_Graphics_Offload_Record, Gtk_Graphics_Offload);
package Implements_Gtk_Constraint_Target is new Glib.Types.Implements
(Gtk.Constraint_Target.Gtk_Constraint_Target, Gtk_Graphics_Offload_Record, Gtk_Graphics_Offload);
procedure Initialize
(Self : not null access Gtk_Graphics_Offload_Record'Class;
Child : access Gtk.Widget.Gtk_Widget_Record'Class)
Creates a new GtkGraphicsOffload widget. Since: gtk+ 4.14 Initialize does nothing if the object was already created with another call to Initialize* or G_New.
the child widget
type Property_Gtk_Graphics_Offload_Enabled is new Gtk_Graphics_Offload_Enabled_Properties.Property;
procedure Reset_Property
(Self : not null access Gtk_Graphics_Offload_Record;
Property : Gtk.Accessible.Gtk_Accessible_Property)
procedure Reset_Relation
(Self : not null access Gtk_Graphics_Offload_Record;
Relation : Gtk.Accessible.Gtk_Accessible_Relation)
procedure Reset_State
(Self : not null access Gtk_Graphics_Offload_Record;
State : Gtk.Accessible.Gtk_Accessible_State)
procedure Set_Accessible_Parent
(Self : not null access Gtk_Graphics_Offload_Record;
Parent : Gtk.Accessible.Gtk_Accessible;
Next_Sibling : Gtk.Accessible.Gtk_Accessible)
procedure Set_Black_Background
(Self : not null access Gtk_Graphics_Offload_Record;
Value : Boolean)
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. Since: gtk+ 4.16
whether to draw a black background behind the content
procedure Set_Child
(Self : not null access Gtk_Graphics_Offload_Record;
Child : access Gtk.Widget.Gtk_Widget_Record'Class)
Sets the child of Self. Since: gtk+ 4.14
the child widget
procedure Set_Enabled
(Self : not null access Gtk_Graphics_Offload_Record;
Enabled : Gtk_Graphics_Offload_Enabled)
Sets whether this GtkGraphicsOffload widget will attempt to offload the content of its child widget. Since: gtk+ 4.14
whether to enable offload
procedure Update_Next_Accessible_Sibling
(Self : not null access Gtk_Graphics_Offload_Record;
New_Sibling : Gtk.Accessible.Gtk_Accessible)
procedure Update_Platform_State
(Self : not null access Gtk_Graphics_Offload_Record;
State : Gtk.Accessible.Gtk_Accessible_Platform_State)