gi-gtk4-4.0.12: Gtk 4.x bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gtk.Objects.GraphicsOffload

Contents

- Exported types
- Methods
  - getBlackBackground
  - getChild
  - getEnabled
  - new
  - setBlackBackground
  - setChild
  - setEnabled
- Properties
  - blackBackground
  - child
  - enabled

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

- newtype GraphicsOffload = GraphicsOffload (ManagedPtr GraphicsOffload)
- class (GObject o, IsDescendantOf GraphicsOffload o) => IsGraphicsOffload o
- toGraphicsOffload :: (MonadIO m, IsGraphicsOffload o) => o -> m GraphicsOffload
- graphicsOffloadGetBlackBackground :: (HasCallStack, MonadIO m, IsGraphicsOffload a) => a -> m Bool
- graphicsOffloadGetChild :: (HasCallStack, MonadIO m, IsGraphicsOffload a) => a -> m (Maybe Widget)
- graphicsOffloadGetEnabled :: (HasCallStack, MonadIO m, IsGraphicsOffload a) => a -> m GraphicsOffloadEnabled
- graphicsOffloadNew :: (HasCallStack, MonadIO m, IsWidget a) => Maybe a -> m GraphicsOffload
- graphicsOffloadSetBlackBackground :: (HasCallStack, MonadIO m, IsGraphicsOffload a) => a -> Bool -> m ()
- graphicsOffloadSetChild :: (HasCallStack, MonadIO m, IsGraphicsOffload a, IsWidget b) => a -> Maybe b -> m ()
- graphicsOffloadSetEnabled :: (HasCallStack, MonadIO m, IsGraphicsOffload a) => a -> GraphicsOffloadEnabled -> m ()
- constructGraphicsOffloadBlackBackground :: (IsGraphicsOffload o, MonadIO m) => Bool -> m (GValueConstruct o)
- getGraphicsOffloadBlackBackground :: (MonadIO m, IsGraphicsOffload o) => o -> m Bool
- setGraphicsOffloadBlackBackground :: (MonadIO m, IsGraphicsOffload o) => o -> Bool -> m ()
- clearGraphicsOffloadChild :: (MonadIO m, IsGraphicsOffload o) => o -> m ()
- constructGraphicsOffloadChild :: (IsGraphicsOffload o, MonadIO m, IsWidget a) => a -> m (GValueConstruct o)
- getGraphicsOffloadChild :: (MonadIO m, IsGraphicsOffload o) => o -> m (Maybe Widget)
- setGraphicsOffloadChild :: (MonadIO m, IsGraphicsOffload o, IsWidget a) => o -> a -> m ()
- constructGraphicsOffloadEnabled :: (IsGraphicsOffload o, MonadIO m) => GraphicsOffloadEnabled -> m (GValueConstruct o)
- getGraphicsOffloadEnabled :: (MonadIO m, IsGraphicsOffload o) => o -> m GraphicsOffloadEnabled
- setGraphicsOffloadEnabled :: (MonadIO m, IsGraphicsOffload o) => o -> GraphicsOffloadEnabled -> m ()

# Exported types

newtype GraphicsOffload Source #

Memory-managed wrapper type.

Constructors

GraphicsOffload (ManagedPtr GraphicsOffload) |

#### Instances

Instances details

Eq GraphicsOffload Source # |
Instance details Defined in GI.Gtk.Objects.GraphicsOffload Methods (==) :: GraphicsOffload -> GraphicsOffload -> Bool Source # (/=) :: GraphicsOffload -> GraphicsOffload -> Bool Source #
GObject GraphicsOffload Source # |
Instance details Defined in GI.Gtk.Objects.GraphicsOffload
ManagedPtrNewtype GraphicsOffload Source # |
Instance details Defined in GI.Gtk.Objects.GraphicsOffload Methods toManagedPtr :: GraphicsOffload -> ManagedPtr GraphicsOffload Source #
TypedObject GraphicsOffload Source # |
Instance details Defined in GI.Gtk.Objects.GraphicsOffload Methods glibType :: IO GType Source #
HasParentTypes GraphicsOffload Source # |
Instance details Defined in GI.Gtk.Objects.GraphicsOffload
IsGValue (Maybe GraphicsOffload) Source # | Convert `GraphicsOffload` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gtk.Objects.GraphicsOffload Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe GraphicsOffload -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe GraphicsOffload) Source #
type ParentTypes GraphicsOffload Source # |
Instance details Defined in GI.Gtk.Objects.GraphicsOffload type ParentTypes GraphicsOffload = '[Widget, Object, Accessible, Buildable, ConstraintTarget]

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

getAccessibleId, 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 ]