Class GraphicsOffload

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.gnome.gtk.Widget
org.gnome.gtk.GraphicsOffload
All Implemented Interfaces:
Accessible, Buildable, ConstraintTarget, Proxy
@Generated("org.javagi.JavaGI") public class GraphicsOffload extends Widget implements 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 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 Display#getDmabufFormats)

  • 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.

Since:
4.14

  • Constructor Details

    • GraphicsOffload

      public GraphicsOffload(MemorySegment address)
      Create a GraphicsOffload instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • GraphicsOffload

      public GraphicsOffload(@Nullable Widget child)
      Creates a new GtkGraphicsOffload widget.
      Parameters:
      child - the child widget
      Since:
      4.14

    • GraphicsOffload

      public GraphicsOffload()
      Create a new GraphicsOffload.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the GraphicsOffload class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected GraphicsOffload 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 Widget
      Returns:
      the instance as if it were its parent type

    • getBlackBackground

      public boolean getBlackBackground()

      Returns whether the widget draws a black background.

      See setBlackBackground(boolean).

      Returns:
      TRUE if black background is drawn
      Since:
      4.16

    • getChild

      public @Nullable Widget getChild()
      Gets the child of self.
      Returns:
      the child widget
      Since:
      4.14

    • getEnabled

      public GraphicsOffloadEnabled getEnabled()
      Returns whether offload is enabled for self.
      Returns:
      whether offload is enabled
      Since:
      4.14

    • setBlackBackground

      public void setBlackBackground(boolean value)

      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
      Since:
      4.16

    • setChild

      public void setChild(@Nullable Widget child)
      Sets the child of self.
      Parameters:
      child - the child widget
      Since:
      4.14

    • setEnabled

      public void setEnabled(GraphicsOffloadEnabled enabled)
      Sets whether this GtkGraphicsOffload widget will attempt to offload the content of its child widget.
      Parameters:
      enabled - whether to enable offload
      Since:
      4.14

    • builder

      public static GraphicsOffload.Builder<? extends GraphicsOffload.Builder> builder()
      A GraphicsOffload.Builder object constructs a GraphicsOffload with the specified properties. Use the various set...() methods to set properties, and finish construction with GraphicsOffload.Builder.build().
      Returns:
      the builder object