gi-gsk-4.0.9: Gsk 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.Gsk.Objects.Renderer

Contents

- Exported types
- Methods
  - getSurface
  - isRealized
  - newForSurface
  - realize
  - realizeForDisplay
  - render
  - renderTexture
  - unrealize
- Properties
  - realized
  - surface

Description

Renders a scene graph defined via a tree of `RenderNode` instances.

Typically you will use a `GskRenderer` instance to repeatedly call `rendererRender` to update the contents of its associated `Surface`.

It is necessary to realize a `GskRenderer` instance using `rendererRealize` before calling `rendererRender`, in order to create the appropriate windowing system resources needed to render the scene.

Synopsis

- newtype Renderer = Renderer (ManagedPtr Renderer)
- class (GObject o, IsDescendantOf Renderer o) => IsRenderer o
- toRenderer :: (MonadIO m, IsRenderer o) => o -> m Renderer
- rendererGetSurface :: (HasCallStack, MonadIO m, IsRenderer a) => a -> m (Maybe Surface)
- rendererIsRealized :: (HasCallStack, MonadIO m, IsRenderer a) => a -> m Bool
- rendererNewForSurface :: (HasCallStack, MonadIO m, IsSurface a) => a -> m (Maybe Renderer)
- rendererRealize :: (HasCallStack, MonadIO m, IsRenderer a, IsSurface b) => a -> Maybe b -> m ()
- rendererRealizeForDisplay :: (HasCallStack, MonadIO m, IsRenderer a, IsDisplay b) => a -> b -> m ()
- rendererRender :: (HasCallStack, MonadIO m, IsRenderer a, IsRenderNode b) => a -> b -> Maybe Region -> m ()
- rendererRenderTexture :: (HasCallStack, MonadIO m, IsRenderer a, IsRenderNode b) => a -> b -> Maybe Rect -> m Texture
- rendererUnrealize :: (HasCallStack, MonadIO m, IsRenderer a) => a -> m ()
- getRendererRealized :: (MonadIO m, IsRenderer o) => o -> m Bool
- getRendererSurface :: (MonadIO m, IsRenderer o) => o -> m (Maybe Surface)

# Exported types

newtype Renderer Source #

Memory-managed wrapper type.

Constructors

Renderer (ManagedPtr Renderer) |

#### Instances

Instances details

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

class (GObject o, IsDescendantOf Renderer o) => IsRenderer o Source #

Type class for types which can be safely cast to `Renderer`, for instance with `toRenderer`.

#### Instances

Instances details

(GObject o, IsDescendantOf Renderer o) => IsRenderer o Source # |
Instance details Defined in GI.Gsk.Objects.Renderer

toRenderer :: (MonadIO m, IsRenderer o) => o -> m Renderer Source #

Cast to `Renderer`, 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

bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, isFloating, isRealized, notify, notifyByPspec, realize, realizeForDisplay, ref, refSink, render, renderTexture, runDispose, stealData, stealQdata, thawNotify, unrealize, unref, watchClosure.

#### Getters

getData, getProperty, getQdata, getSurface.

#### Setters

setData, setDataFull, setProperty.

## getSurface

rendererGetSurface Source #

Arguments

:: (HasCallStack, MonadIO m, IsRenderer a) |
=> a | `renderer`: a renderer
-> m (Maybe Surface) | Returns: the surface

Retrieves the surface that the renderer is associated with.

If the renderer has not been realized yet, `NULL` will be returned.

## isRealized

rendererIsRealized Source #

Arguments

:: (HasCallStack, MonadIO m, IsRenderer a) |
=> a | `renderer`: a renderer
-> m Bool | Returns: true if the renderer was realized, false otherwise

Checks whether the renderer is realized or not.

## newForSurface

rendererNewForSurface Source #

Arguments

:: (HasCallStack, MonadIO m, IsSurface a) |
=> a | `surface`: a surface
-> m (Maybe Renderer) | Returns: the realized renderer

Creates an appropriate `GskRenderer` instance for the given surface.

If the `GSK_RENDERER` environment variable is set, GSK will try that renderer first, before trying the backend-specific default. The ultimate fallback is the cairo renderer.

The renderer will be realized before it is returned.

## realize

rendererRealize Source #

Arguments

:: (HasCallStack, MonadIO m, IsRenderer a, IsSurface b) |
=> a | `renderer`: a renderer
-> Maybe b | `surface`: the surface that renderer will be used on
-> m () | (Can throw `GError`)

Creates the resources needed by the renderer.

Since GTK 4.6, the surface may be `NULL`, which allows using renderers without having to create a surface. Since GTK 4.14, it is recommended to use `rendererRealizeForDisplay` for this case.

Note that it is mandatory to call `rendererUnrealize` before destroying the renderer.

## realizeForDisplay

rendererRealizeForDisplay Source #

Arguments

:: (HasCallStack, MonadIO m, IsRenderer a, IsDisplay b) |
=> a | `renderer`: a renderer
-> b | `display`: the display that the renderer will be used on
-> m () | (Can throw `GError`)

Creates the resources needed by the renderer.

Note that it is mandatory to call `rendererUnrealize` before destroying the renderer.

Since: 4.14

## render

rendererRender Source #

Arguments

:: (HasCallStack, MonadIO m, IsRenderer a, IsRenderNode b) |
=> a | `renderer`: a realized renderer
-> b | `root`: the render node to render
-> Maybe Region | `region`: the `cairo_region_t` that must be redrawn or `NULL` for the whole surface
-> m () |

Renders the scene graph, described by a tree of `GskRenderNode` instances to the renderer's surface, ensuring that the given region gets redrawn.

If the renderer has no associated surface, this function does nothing.

Renderers must ensure that changes of the contents given by the `root` node as well as the area given by `region` are redrawn. They are however free to not redraw any pixel outside of `region` if they can guarantee that it didn't change.

The renderer will acquire a reference on the `GskRenderNode` tree while the rendering is in progress.

## renderTexture

rendererRenderTexture Source #

Arguments

:: (HasCallStack, MonadIO m, IsRenderer a, IsRenderNode b) |
=> a | `renderer`: a realized renderer
-> b | `root`: the render node to render
-> Maybe Rect | `viewport`: the section to draw or `NULL` to use `root`'s bounds
-> m Texture | Returns: a texture with the rendered contents of `root`

Renders a scene graph, described by a tree of `GskRenderNode` instances, to a texture.

The renderer will acquire a reference on the `GskRenderNode` tree while the rendering is in progress.

If you want to apply any transformations to `root`, you should put it into a transform node and pass that node instead.

## unrealize

rendererUnrealize Source #

Arguments

:: (HasCallStack, MonadIO m, IsRenderer a) |
=> a | `renderer`: a renderer
-> m () |

Releases all the resources created by `rendererRealize`.

# Properties

## realized

Whether the renderer has been associated with a surface or draw context.

getRendererRealized :: (MonadIO m, IsRenderer o) => o -> m Bool Source #

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

    get renderer #realized

## surface

The surface associated with renderer.

getRendererSurface :: (MonadIO m, IsRenderer o) => o -> m (Maybe Surface) Source #

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

    get renderer #surface