gi-gtk4-4.0.12: Gtk 4.x bindings
CopyrightWill Thompson and Iñaki García Etxebarria
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria
Safe HaskellNone
LanguageHaskell2010

GI.Gtk.Objects.GraphicsOffload

Description

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 displayGetDmabufFormats)
  • 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

Synopsis

Exported types

class (GObject o, IsDescendantOf GraphicsOffload o) => IsGraphicsOffload o Source #

Type class for types which can be safely cast to GraphicsOffload, for instance with toGraphicsOffload.

Instances

Instances details
(GObject o, IsDescendantOf GraphicsOffload o) => IsGraphicsOffload o Source # 
Instance details

Defined in GI.Gtk.Objects.GraphicsOffload

toGraphicsOffload :: (MonadIO m, IsGraphicsOffload o) => o -> m GraphicsOffload Source #

Cast to GraphicsOffload, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Expand

Methods

actionSetEnabled, activate, activateAction, activateDefault, addController, addCssClass, addMnemonicLabel, addTickCallback, allocate, announce, bindProperty, bindPropertyFull, childFocus, computeBounds, computeExpand, computePoint, computeTransform, contains, createPangoContext, createPangoLayout, disposeTemplate, dragCheckThreshold, errorBell, forceFloating, freezeNotify, getv, grabFocus, hasCssClass, hasDefault, hasFocus, hasVisibleFocus, hide, inDestruction, initTemplate, insertActionGroup, insertAfter, insertBefore, isAncestor, isDrawable, isFloating, isFocus, isSensitive, isVisible, keynavFailed, listMnemonicLabels, map, measure, mnemonicActivate, notify, notifyByPspec, observeChildren, observeControllers, pick, queueAllocate, queueDraw, queueResize, realize, ref, refSink, removeController, removeCssClass, removeMnemonicLabel, removeTickCallback, resetProperty, resetRelation, resetState, runDispose, shouldLayout, show, sizeAllocate, snapshotChild, stealData, stealQdata, thawNotify, translateCoordinates, triggerTooltipQuery, unmap, unparent, unrealize, unref, unsetStateFlags, updateNextAccessibleSibling, updatePlatformState, updateProperty, updateRelation, updateState, watchClosure.

Getters

getAccessibleParent, getAccessibleRole, getAllocatedBaseline, getAllocatedHeight, getAllocatedWidth, getAllocation, getAncestor, getAtContext, getBaseline, getBlackBackground, getBounds, getBuildableId, getCanFocus, getCanTarget, getChild, getChildVisible, getClipboard, getColor, getCssClasses, getCssName, getCursor, getData, getDirection, getDisplay, getEnabled, getFirstAccessibleChild, getFirstChild, getFocusChild, getFocusOnClick, getFocusable, getFontMap, getFontOptions, getFrameClock, getHalign, getHasTooltip, getHeight, getHexpand, getHexpandSet, getLastChild, getLayoutManager, getLimitEvents, getMapped, getMarginBottom, getMarginEnd, getMarginStart, getMarginTop, getName, getNative, getNextAccessibleSibling, getNextSibling, getOpacity, getOverflow, getPangoContext, getParent, getPlatformState, getPreferredSize, getPrevSibling, getPrimaryClipboard, getProperty, getQdata, getRealized, getReceivesDefault, getRequestMode, getRoot, getScaleFactor, getSensitive, getSettings, getSize, getSizeRequest, getStateFlags, getStyleContext, getTemplateChild, getTooltipMarkup, getTooltipText, getValign, getVexpand, getVexpandSet, getVisible, getWidth.

Setters

setAccessibleParent, setBlackBackground, setCanFocus, setCanTarget, setChild, setChildVisible, setCssClasses, setCursor, setCursorFromName, setData, setDataFull, setDirection, setEnabled, setFocusChild, setFocusOnClick, setFocusable, setFontMap, setFontOptions, setHalign, setHasTooltip, setHexpand, setHexpandSet, setLayoutManager, setLimitEvents, setMarginBottom, setMarginEnd, setMarginStart, setMarginTop, setName, setOpacity, setOverflow, setParent, setProperty, setReceivesDefault, setSensitive, setSizeRequest, setStateFlags, setTooltipMarkup, setTooltipText, setValign, setVexpand, setVexpandSet, setVisible.

getBlackBackground

graphicsOffloadGetBlackBackground Source #

Arguments

:: (HasCallStack, MonadIO m, IsGraphicsOffload a) 
=> a

self: a GtkGraphicsOffload

-> m Bool

Returns: TRUE if black background is drawn

Returns whether the widget draws a black background.

See graphicsOffloadSetBlackBackground.

Since: 4.16

getChild

graphicsOffloadGetChild Source #

Arguments

:: (HasCallStack, MonadIO m, IsGraphicsOffload a) 
=> a

self: a GtkGraphicsOffload

-> m (Maybe Widget)

Returns: the child widget

Gets the child of self.

Since: 4.14

getEnabled

graphicsOffloadGetEnabled Source #

Arguments

:: (HasCallStack, MonadIO m, IsGraphicsOffload a) 
=> a

self: a GtkGraphicsOffload

-> m GraphicsOffloadEnabled

Returns: whether offload is enabled

Returns whether offload is enabled for self.

Since: 4.14

new

graphicsOffloadNew Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> Maybe a

child: the child widget

-> m GraphicsOffload

Returns: the new widget

Creates a new GtkGraphicsOffload widget.

Since: 4.14

setBlackBackground

graphicsOffloadSetBlackBackground Source #

Arguments

:: (HasCallStack, MonadIO m, IsGraphicsOffload a) 
=> a

self: a GtkGraphicsOffload

-> Bool

value: whether to draw a black background behind the content

-> m () 

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

setChild

graphicsOffloadSetChild Source #

Arguments

:: (HasCallStack, MonadIO m, IsGraphicsOffload a, IsWidget b) 
=> a

self: a GtkGraphicsOffload

-> Maybe b

child: the child widget

-> m () 

Sets the child of self.

Since: 4.14

setEnabled

graphicsOffloadSetEnabled Source #

Arguments

:: (HasCallStack, MonadIO m, IsGraphicsOffload a) 
=> a

self: a GtkGraphicsOffload

-> GraphicsOffloadEnabled

enabled: whether to enable offload

-> m () 

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

Since: 4.14

Properties

blackBackground

Whether to draw a black background.

Since: 4.16

constructGraphicsOffloadBlackBackground :: (IsGraphicsOffload o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “black-background” property. This is rarely needed directly, but it is used by new.

getGraphicsOffloadBlackBackground :: (MonadIO m, IsGraphicsOffload o) => o -> m Bool Source #

Get the value of the “black-background” property. When overloading is enabled, this is equivalent to

get graphicsOffload #blackBackground

setGraphicsOffloadBlackBackground :: (MonadIO m, IsGraphicsOffload o) => o -> Bool -> m () Source #

Set the value of the “black-background” property. When overloading is enabled, this is equivalent to

set graphicsOffload [ #blackBackground := value ]

child

The child widget.

Since: 4.14

clearGraphicsOffloadChild :: (MonadIO m, IsGraphicsOffload o) => o -> m () Source #

Set the value of the “child” property to Nothing. When overloading is enabled, this is equivalent to

clear #child

constructGraphicsOffloadChild :: (IsGraphicsOffload o, MonadIO m, IsWidget a) => a -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “child” property. This is rarely needed directly, but it is used by new.

getGraphicsOffloadChild :: (MonadIO m, IsGraphicsOffload o) => o -> m (Maybe Widget) Source #

Get the value of the “child” property. When overloading is enabled, this is equivalent to

get graphicsOffload #child

setGraphicsOffloadChild :: (MonadIO m, IsGraphicsOffload o, IsWidget a) => o -> a -> m () Source #

Set the value of the “child” property. When overloading is enabled, this is equivalent to

set graphicsOffload [ #child := value ]

enabled

Whether graphics offload is enabled.

Since: 4.14

constructGraphicsOffloadEnabled :: (IsGraphicsOffload o, MonadIO m) => GraphicsOffloadEnabled -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “enabled” property. This is rarely needed directly, but it is used by new.

getGraphicsOffloadEnabled :: (MonadIO m, IsGraphicsOffload o) => o -> m GraphicsOffloadEnabled Source #

Get the value of the “enabled” property. When overloading is enabled, this is equivalent to

get graphicsOffload #enabled

setGraphicsOffloadEnabled :: (MonadIO m, IsGraphicsOffload o) => o -> GraphicsOffloadEnabled -> m () Source #

Set the value of the “enabled” property. When overloading is enabled, this is equivalent to

set graphicsOffload [ #enabled := value ]