| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Graphics.Caramia.Context
Contents
Description
This module manages OpenGL contexts in Caramia.
Caramia does not actually have any functionality about creating OpenGL contexts. You need to tell it about them with this module.
giveContext is the most important function in this module. You also want
to runPendingFinalizers regularly to make sure OpenGL resources are
garbage collected.
- giveContext :: (MonadIO m, MonadMask m) => m a -> m a
- setViewportSize :: MonadIO m => Int -> Int -> m ()
- currentContextID :: MonadIO m => m (Maybe ContextID)
- data ContextID
- runPendingFinalizers :: MonadIO m => m ()
- scheduleFinalizer :: MonadIO m => ContextID -> IO () -> m ()
- storeContextLocalData :: (MonadIO m, Typeable a) => a -> m ()
- retrieveContextLocalData :: forall m a. (MonadIO m, Typeable a) => m a -> m a
- data NoSupport = NoSupport {}
- data TooOldOpenGL = TooOldOpenGL {}
- data OpenGLVersion = OpenGLVersion !Int !Int
Running with an OpenGL context
giveContext :: (MonadIO m, MonadMask m) => m a -> m a Source
Tell Caramia the current thread has an OpenGL context active.
When the given IO action returns, Caramia will think that the OpenGL context is now gone. It is probably best to actually close the context because this also means OpenGL finalizers will not be run (Caramia thinks they were all released when the OpenGL context went away).
The context in the IO action is referred to as 'Caramia context' in this documentation to distinguish it from OpenGL context.
If the environment variable 'CARAMIA_OPENGL_DEBUG' is set, then, if 'GL_KHR_debug' extension is supported, OpenGL debug output is written. Note that you might need a debug OpenGL context for there to be any messages.
If the window size changes while the context is active, you should call
setViewportSize with the new dimensions. There is no mechanism from
OpenGL's side to automatically detect if size has changed.
Throws TooOldOpenGL if the code detects a context that does not provide
at least OpenGL 2.1.
Viewport size
Sets the new viewport size. You should call this if the display size has changed; otherwise your rendering may look twisted and stretched.
Context IDs
currentContextID :: MonadIO m => m (Maybe ContextID) Source
Returns the current Caramia context ID.
The context ID is unique between different calls to giveContext.
Returns Nothing if there is no context active.
The type of a Caramia context ID.
Finalization
runPendingFinalizers :: MonadIO m => m () Source
Run any pending finalizers in the current Caramia context.
Does nothing if current thread does not have a Caramia context or there are no pending finalizers.
If any finalizer throws an exception (asynchronous or synchronous), the
Caramia context dies and that exception is propagated upwards.
runPendingFinalizers itself runs mask_ to run the finalizers with
exceptions masked but you might still receive asynchronous exceptions with,
for example, the MVar functions.
A good place to call this is right after or before swapping buffers.
scheduleFinalizer :: MonadIO m => ContextID -> IO () -> m () Source
Schedules a finalizer to be run in a Caramia context.
Does nothing if given context is not alive anymore.
This is typically called from Haskell garbage collector finalizers because they cannot do finalization there (Haskell finalizers are running in the wrong operating system thread).
Context local data
storeContextLocalData :: (MonadIO m, Typeable a) => a -> m () Source
Stores a context local value.
The type of the given value is used as a key. This means that if a value of the same type was stored before, that value is thrown away and replaced with this new value you just gave.
The value is evaluated to WHNF.
You don't need this function to work with context local data.
retrieveContextLocalData is sufficient as it also lets you set a default
value in case a value was not already set.
Context local data is wiped to oblivion once giveContext ends.
retrieveContextLocalData Source
Arguments
| :: (MonadIO m, Typeable a) | |
| => m a | Default value generating action; not evaluated if there was already a value stored. |
| -> m a |
Retrieves a context local value.
Exceptions
Thrown when there was a detected attempt to use an OpenGL feature that is not supported by the driver, hardware or platform.
Caramia cannot detect all attempts to use non-supported features.
If the platform supports at least OpenGL 3.3, then this exception is guaranteed to never be thrown.
Constructors
| NoSupport | The text contains human-readable string that may tell what exactly is missing and where. |
data TooOldOpenGL Source
An exception that is thrown when the OpenGL version is too old for this library.
Constructors
| TooOldOpenGL | |
Fields
| |
data OpenGLVersion Source
Constructors
| OpenGLVersion !Int !Int |