gi-gdk4-4.0.10: Gdk 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.Gdk.Objects.GLContext

Contents

- Exported types
- Methods
  - clearCurrent
  - getAllowedApis
  - getApi
  - getCurrent
  - getDebugEnabled
  - getDisplay
  - getForwardCompatible
  - getRequiredVersion
  - getSharedContext
  - getSurface
  - getUseEs
  - getVersion
  - isLegacy
  - isShared
  - makeCurrent
  - realize
  - setAllowedApis
  - setDebugEnabled
  - setForwardCompatible
  - setRequiredVersion
  - setUseEs
- Properties
  - allowedApis
  - api
  - sharedContext

Description

Represents a platform-specific OpenGL draw context.

`GdkGLContext`s are created for a surface using `surfaceCreateGlContext`, and the context will match the characteristics of the surface.

A `GdkGLContext` is not tied to any particular normal framebuffer. For instance, it cannot draw to the surface back buffer. The GDK repaint system is in full control of the painting to that. Instead, you can create render buffers or textures and use [func`cairoDrawFromGl`] in the draw function of your widget to draw them. Then GDK will handle the integration of your rendering with that of other widgets.

Support for `GdkGLContext` is platform-specific and context creation can fail, returning `Nothing` context.

A `GdkGLContext` has to be made "current" in order to start using it, otherwise any OpenGL call will be ignored.

## Creating a new OpenGL context

In order to create a new `GdkGLContext` instance you need a `GdkSurface`, which you typically get during the realize call of a widget.

A `GdkGLContext` is not realized until either `gLContextMakeCurrent` or `gLContextRealize` is called. It is possible to specify details of the GL context like the OpenGL version to be used, or whether the GL context should have extra state validation enabled after calling `surfaceCreateGlContext` by calling `gLContextRealize`. If the realization fails you have the option to change the settings of the `GdkGLContext` and try again.

## Using a GdkGLContext

You will need to make the `GdkGLContext` the current context before issuing OpenGL calls; the system sends OpenGL commands to whichever context is current. It is possible to have multiple contexts, so you always need to ensure that the one which you want to draw with is the current one before issuing commands:

### c code

    gdk_gl_context_make_current (context);

You can now perform your drawing using OpenGL commands.

You can check which `GdkGLContext` is the current one by using `gLContextGetCurrent`; you can also unset any `GdkGLContext` that is currently set by calling `gLContextClearCurrent`.

Synopsis

- newtype GLContext = GLContext (ManagedPtr GLContext)
- class (GObject o, IsDescendantOf GLContext o) => IsGLContext o
- toGLContext :: (MonadIO m, IsGLContext o) => o -> m GLContext
- gLContextClearCurrent :: (HasCallStack, MonadIO m) => m ()
- gLContextGetAllowedApis :: (HasCallStack, MonadIO m, IsGLContext a) => a -> m [GLAPI]
- gLContextGetApi :: (HasCallStack, MonadIO m, IsGLContext a) => a -> m [GLAPI]
- gLContextGetCurrent :: (HasCallStack, MonadIO m) => m (Maybe GLContext)
- gLContextGetDebugEnabled :: (HasCallStack, MonadIO m, IsGLContext a) => a -> m Bool
- gLContextGetDisplay :: (HasCallStack, MonadIO m, IsGLContext a) => a -> m (Maybe Display)
- gLContextGetForwardCompatible :: (HasCallStack, MonadIO m, IsGLContext a) => a -> m Bool
- gLContextGetRequiredVersion :: (HasCallStack, MonadIO m, IsGLContext a) => a -> m (Int32, Int32)
- gLContextGetSharedContext :: (HasCallStack, MonadIO m, IsGLContext a) => a -> m (Maybe GLContext)
- gLContextGetSurface :: (HasCallStack, MonadIO m, IsGLContext a) => a -> m (Maybe Surface)
- gLContextGetUseEs :: (HasCallStack, MonadIO m, IsGLContext a) => a -> m Bool
- gLContextGetVersion :: (HasCallStack, MonadIO m, IsGLContext a) => a -> m (Int32, Int32)
- gLContextIsLegacy :: (HasCallStack, MonadIO m, IsGLContext a) => a -> m Bool
- gLContextIsShared :: (HasCallStack, MonadIO m, IsGLContext a, IsGLContext b) => a -> b -> m Bool
- gLContextMakeCurrent :: (HasCallStack, MonadIO m, IsGLContext a) => a -> m ()
- gLContextRealize :: (HasCallStack, MonadIO m, IsGLContext a) => a -> m ()
- gLContextSetAllowedApis :: (HasCallStack, MonadIO m, IsGLContext a) => a -> [GLAPI] -> m ()
- gLContextSetDebugEnabled :: (HasCallStack, MonadIO m, IsGLContext a) => a -> Bool -> m ()
- gLContextSetForwardCompatible :: (HasCallStack, MonadIO m, IsGLContext a) => a -> Bool -> m ()
- gLContextSetRequiredVersion :: (HasCallStack, MonadIO m, IsGLContext a) => a -> Int32 -> Int32 -> m ()
- gLContextSetUseEs :: (HasCallStack, MonadIO m, IsGLContext a) => a -> Int32 -> m ()
- constructGLContextAllowedApis :: (IsGLContext o, MonadIO m) => [GLAPI] -> m (GValueConstruct o)
- getGLContextAllowedApis :: (MonadIO m, IsGLContext o) => o -> m [GLAPI]
- setGLContextAllowedApis :: (MonadIO m, IsGLContext o) => o -> [GLAPI] -> m ()
- getGLContextApi :: (MonadIO m, IsGLContext o) => o -> m [GLAPI]
- constructGLContextSharedContext :: (IsGLContext o, MonadIO m, IsGLContext a) => a -> m (GValueConstruct o)
- getGLContextSharedContext :: (MonadIO m, IsGLContext o) => o -> m (Maybe GLContext)

# Exported types

newtype GLContext Source #

Memory-managed wrapper type.

Constructors

GLContext (ManagedPtr GLContext) |

#### Instances

Instances details

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

class (GObject o, IsDescendantOf GLContext o) => IsGLContext o Source #

Type class for types which can be safely cast to `GLContext`, for instance with `toGLContext`.

#### Instances

Instances details

(GObject o, IsDescendantOf GLContext o) => IsGLContext o Source # |
Instance details Defined in GI.Gdk.Objects.GLContext

toGLContext :: (MonadIO m, IsGLContext o) => o -> m GLContext Source #

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

beginFrame, bindProperty, bindPropertyFull, endFrame, forceFloating, freezeNotify, getv, isFloating, isInFrame, isLegacy, isShared, makeCurrent, notify, notifyByPspec, realize, ref, refSink, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.

#### Getters

getAllowedApis, getApi, getData, getDebugEnabled, getDisplay, getForwardCompatible, getFrameRegion, getProperty, getQdata, getRequiredVersion, getSharedContext, getSurface, getUseEs, getVersion.

#### Setters

setAllowedApis, setData, setDataFull, setDebugEnabled, setForwardCompatible, setProperty, setRequiredVersion, setUseEs.

## clearCurrent

gLContextClearCurrent :: (HasCallStack, MonadIO m) => m () Source #

Clears the current `GdkGLContext`.

Any OpenGL call after this function returns will be ignored until `gLContextMakeCurrent` is called.

## getAllowedApis

gLContextGetAllowedApis Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `self`: a GL context
-> m [GLAPI] | Returns: the allowed APIs

Gets the allowed APIs set via `gLContextSetAllowedApis`.

Since: 4.6

## getApi

gLContextGetApi Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `self`: a GL context
-> m [GLAPI] | Returns: the currently used API

Gets the API currently in use.

If the renderer has not been realized yet, 0 is returned.

Since: 4.6

## getCurrent

gLContextGetCurrent Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m (Maybe GLContext) | Returns: the current `GdkGLContext`

Retrieves the current `GdkGLContext`.

## getDebugEnabled

gLContextGetDebugEnabled Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `context`: a `GdkGLContext`
-> m Bool | Returns: `True` if debugging is enabled

Retrieves whether the context is doing extra validations and runtime checking.

See `gLContextSetDebugEnabled`.

## getDisplay

gLContextGetDisplay Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `context`: a `GdkGLContext`
-> m (Maybe Display) | Returns: a `GdkDisplay`

Retrieves the display the `context` is created for

## getForwardCompatible

gLContextGetForwardCompatible Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `context`: a `GdkGLContext`
-> m Bool | Returns: `True` if the context should be forward-compatible

Retrieves whether the context is forward-compatible.

See `gLContextSetForwardCompatible`.

## getRequiredVersion

gLContextGetRequiredVersion Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `context`: a `GdkGLContext`
-> m (Int32, Int32) |

Retrieves required OpenGL version set as a requirement for the `context` realization. It will not change even if a greater OpenGL version is supported and used after the `context` is realized. See `gLContextGetVersion` for the real version in use.

See `gLContextSetRequiredVersion`.

## getSharedContext

gLContextGetSharedContext Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `context`: a `GdkGLContext`
-> m (Maybe GLContext) | Returns: `Nothing`

Deprecated: (Since version 4.4)Use `gLContextIsShared` to check if contextscan be shared.

Used to retrieves the `GdkGLContext` that this `context` share data with.

As many contexts can share data now and no single shared context exists anymore, this function has been deprecated and now always returns `Nothing`.

## getSurface

gLContextGetSurface Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `context`: a `GdkGLContext`
-> m (Maybe Surface) | Returns: a `GdkSurface`

Retrieves the surface used by the `context`.

## getUseEs

gLContextGetUseEs Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `context`: a `GdkGLContext`
-> m Bool | Returns: `True` if the `GdkGLContext` is using an OpenGL ES profile; `False` if other profile is in use of if the `context` has not yet been realized.

Checks whether the `context` is using an OpenGL or OpenGL ES profile.

## getVersion

gLContextGetVersion Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `context`: a `GdkGLContext`
-> m (Int32, Int32) |

Retrieves the OpenGL version of the `context`.

The `context` must be realized prior to calling this function.

## isLegacy

gLContextIsLegacy Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `context`: a `GdkGLContext`
-> m Bool | Returns: `True` if the GL context is in legacy mode

Whether the `GdkGLContext` is in legacy mode or not.

The `GdkGLContext` must be realized before calling this function.

When realizing a GL context, GDK will try to use the OpenGL 3.2 core profile; this profile removes all the OpenGL API that was deprecated prior to the 3.2 version of the specification. If the realization is successful, this function will return `False`.

If the underlying OpenGL implementation does not support core profiles, GDK will fall back to a pre-3.2 compatibility profile, and this function will return `True`.

You can use the value returned by this function to decide which kind of OpenGL API to use, or whether to do extension discovery, or what kind of shader programs to load.

## isShared

gLContextIsShared Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a, IsGLContext b) |
=> a | `self`: a `GdkGLContext`
-> b | `other`: the `GdkGLContext` that should be compatible with `self`
-> m Bool | Returns: `True` if the two GL contexts are compatible.

Checks if the two GL contexts can share resources.

When they can, the texture IDs from `other` can be used in `self`. This is particularly useful when passing `GdkGLTexture` objects between different contexts.

Contexts created for the same display with the same properties will always be compatible, even if they are created for different surfaces. For other contexts it depends on the GL backend.

Both contexts must be realized for this check to succeed. If either one is not, this function will return `False`.

Since: 4.4

## makeCurrent

gLContextMakeCurrent Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `context`: a `GdkGLContext`
-> m () |

Makes the `context` the current one.

## realize

gLContextRealize Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `context`: a `GdkGLContext`
-> m () | (Can throw `GError`)

Realizes the given `GdkGLContext`.

It is safe to call this function on a realized `GdkGLContext`.

## setAllowedApis

gLContextSetAllowedApis Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `self`: a GL context
-> [GLAPI] | `apis`: the allowed APIs
-> m () |

Sets the allowed APIs. When `gLContextRealize` is called, only the allowed APIs will be tried. If you set this to 0, realizing will always fail.

If you set it on a realized context, the property will not have any effect. It is only relevant during `gLContextRealize`.

By default, all APIs are allowed.

Since: 4.6

## setDebugEnabled

gLContextSetDebugEnabled Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `context`: a `GdkGLContext`
-> Bool | `enabled`: whether to enable debugging in the context
-> m () |

Sets whether the `GdkGLContext` should perform extra validations and runtime checking.

This is useful during development, but has additional overhead.

The `GdkGLContext` must not be realized or made current prior to calling this function.

## setForwardCompatible

gLContextSetForwardCompatible Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `context`: a `GdkGLContext`
-> Bool | `compatible`: whether the context should be forward-compatible
-> m () |

Sets whether the `GdkGLContext` should be forward-compatible.

Forward-compatible contexts must not support OpenGL functionality that has been marked as deprecated in the requested version; non-forward compatible contexts, on the other hand, must support both deprecated and non deprecated functionality.

The `GdkGLContext` must not be realized or made current prior to calling this function.

## setRequiredVersion

gLContextSetRequiredVersion Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `context`: a `GdkGLContext`
-> Int32 | `major`: the major version to request
-> Int32 | `minor`: the minor version to request
-> m () |

Sets the major and minor version of OpenGL to request.

Setting `major` and `minor` to zero will use the default values.

Setting `major` and `minor` lower than the minimum versions required by GTK will result in the context choosing the minimum version.

The `context` must not be realized or made current prior to calling this function.

## setUseEs

gLContextSetUseEs Source #

Arguments

:: (HasCallStack, MonadIO m, IsGLContext a) |
=> a | `context`: a `GdkGLContext`
-> Int32 | `useEs`: whether the context should use OpenGL ES instead of OpenGL, or -1 to allow auto-detection
-> m () |

Deprecated: (Since version 4.6)

Requests that GDK create an OpenGL ES context instead of an OpenGL one.

Not all platforms support OpenGL ES.

The `context` must not have been realized.

By default, GDK will attempt to automatically detect whether the underlying GL implementation is OpenGL or OpenGL ES once the `context` is realized.

You should check the return value of `gLContextGetUseEs` after calling `gLContextRealize` to decide whether to use the OpenGL or OpenGL ES API, extensions, or shaders.

# Properties

## allowedApis

The allowed APIs.

Since: 4.6

constructGLContextAllowedApis :: (IsGLContext o, MonadIO m) => [GLAPI] -> m (GValueConstruct o) Source #

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

getGLContextAllowedApis :: (MonadIO m, IsGLContext o) => o -> m [GLAPI] Source #

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

    get gLContext #allowedApis

setGLContextAllowedApis :: (MonadIO m, IsGLContext o) => o -> [GLAPI] -> m () Source #

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

    set gLContext [ #allowedApis := value ]

## api

The API currently in use.

Since: 4.6

getGLContextApi :: (MonadIO m, IsGLContext o) => o -> m [GLAPI] Source #

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

    get gLContext #api

## sharedContext

Always `Nothing`

As many contexts can share data now and no single shared context exists anymore, this function has been deprecated and now always returns `Nothing`.

constructGLContextSharedContext :: (IsGLContext o, MonadIO m, IsGLContext a) => a -> m (GValueConstruct o) Source #

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

getGLContextSharedContext :: (MonadIO m, IsGLContext o) => o -> m (Maybe GLContext) Source #

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

    get gLContext #sharedContext