Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | None |
Language | Haskell2010 |
GdkGLContext
is an object representing 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 [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
Memory-managed wrapper type.
Instances
Eq GLContext Source # | |
GObject GLContext Source # | |
Defined in GI.Gdk.Objects.GLContext | |
ManagedPtrNewtype GLContext Source # | |
Defined in GI.Gdk.Objects.GLContext | |
TypedObject GLContext Source # | |
Defined in GI.Gdk.Objects.GLContext | |
HasParentTypes GLContext Source # | |
Defined in GI.Gdk.Objects.GLContext | |
IsGValue (Maybe GLContext) Source # | Convert |
Defined in GI.Gdk.Objects.GLContext | |
type ParentTypes GLContext Source # | |
Defined in GI.Gdk.Objects.GLContext |
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
(GObject o, IsDescendantOf GLContext o) => IsGLContext o Source # | |
Defined in GI.Gdk.Objects.GLContext |
toGLContext :: (MonadIO m, IsGLContext o) => o -> m GLContext Source #
Methods
Click to display all available methods, including inherited ones
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 #
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> m [GLAPI] | Returns: the allowed APIs |
Gets the allowed APIs set via gLContextSetAllowedApis
.
Since: 4.6
getApi
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m) | |
=> m (Maybe GLContext) | Returns: the current |
Retrieves the current GdkGLContext
.
getDebugEnabled
gLContextGetDebugEnabled Source #
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> m Bool | Returns: |
Retrieves whether the context is doing extra validations and runtime checking.
getDisplay
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> m (Maybe Display) | Returns: a |
Retrieves the display the context
is created for
getForwardCompatible
gLContextGetForwardCompatible Source #
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> m Bool | Returns: |
Retrieves whether the context is forward-compatible.
getRequiredVersion
gLContextGetRequiredVersion Source #
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> 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.
getSharedContext
gLContextGetSharedContext Source #
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> m (Maybe GLContext) | Returns: |
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
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> m (Maybe Surface) | Returns: a |
Retrieves the surface used by the context
.
getUseEs
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> m Bool | Returns: |
Checks whether the context
is using an OpenGL or OpenGL ES profile.
getVersion
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> m (Int32, Int32) |
Retrieves the OpenGL version of the context
.
The context
must be realized prior to calling this function.
isLegacy
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> m Bool | Returns: |
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
:: (HasCallStack, MonadIO m, IsGLContext a, IsGLContext b) | |
=> a |
|
-> b |
|
-> m Bool | Returns: |
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
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> m () |
Makes the context
the current one.
realize
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> m () | (Can throw |
Realizes the given GdkGLContext
.
It is safe to call this function on a realized GdkGLContext
.
setAllowedApis
gLContextSetAllowedApis Source #
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> [GLAPI] |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> Bool |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> Bool |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> Int32 |
|
-> Int32 |
|
-> 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
:: (HasCallStack, MonadIO m, IsGLContext a) | |
=> a |
|
-> Int32 |
|
-> 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.
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