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

GI.Gdk.Objects.GLContext

Contents

Exported types
Methods
Properties

Description

GdkGLContext is an object representing a platform-specific OpenGL draw context.

GdkGLContexts 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 [funccairoDrawFromGl] 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 [funcgdk.GLContext.get_current]; you can also unset any GdkGLContext that is currently set by calling [funcgdk.GLContext.clear_current].

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 # (/=) :: GLContext -> GLContext -> Bool #
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
TypedObject GLContext Source #
Instance details Defined in GI.Gdk.Objects.GLContext Methods glibType :: IO GType
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 gvalueSet_ :: Ptr GValue -> Maybe GLContext -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe GLContext)
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

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 contexts can 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.

If the context has never been made current, the version cannot be known and it will return 0 for both major and minor.

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 ()

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.