GPipe-2.1.6: Typesafe functional GPU graphics programming

Safe HaskellNone
LanguageHaskell98

Graphics.GPipe.Context

Contents

Description

A Context in GPipe (just as in OpenGl) consist of two things, a window and an object space. The object space consists of Buffers, Textures and Shaders. You may create a context without a window (for example for rendering to textures that are saved as pngs instead of showed), and you can create a context that shares the object space with another context.

Context creation is abstracted away from GPipe, and you need a package that provides a ContextFactory, such as GPipe-GLFW.

Synopsis

The ContextT monad transformer

data ContextT w os f m a Source

The monad transformer that encapsulates a GPipe context (which wraps an OpenGl context).

A value of type ContextT w os f m a is an action on a context with these parameters:

w
The type of the window that is bound to this context. It is defined by the window manager package and is probably an opaque type.
os
An abstract type that is used to denote the object space. This is an forall type defined by the runContextT call which will restrict any objects created inside this context to be returned from it or used by another context (the same trick as the ST monad uses).
f
The format of the context's default frame buffer, always an instance of ContextFormat.
m
The monad this monad transformer wraps. Need to have IO in the bottom for this ContextT to be runnable.
a
The value returned from this monad action.

Instances

MonadTrans (ContextT w os f) Source 
Monad m => Monad (ContextT w os f m) Source 
Functor m => Functor (ContextT w os f m) Source 
Applicative m => Applicative (ContextT w os f m) Source 
MonadIO m => MonadIO (ContextT w os f m) Source 
MonadException m => MonadException (ContextT w os f m) Source 
MonadAsyncException m => MonadAsyncException (ContextT w os f m) Source 

runContextT :: (MonadIO m, MonadAsyncException m) => ContextFactory c ds w -> ContextFormat c ds -> (forall os. ContextT w os (ContextFormat c ds) m a) -> m a Source

Run a ContextT monad transformer, creating a window (unless the ContextFormat is ContextFormatNone) that is later destroyed when the action returns. This function will also create a new object space. You need a ContextFactory, which is provided by an auxillary package, such as GPipe-GLFW.

runSharedContextT :: (MonadIO m, MonadAsyncException m) => ContextFormat c ds -> ContextT w os (ContextFormat c ds) (ContextT w os f m) a -> ContextT w os f m a Source

Run a ContextT monad transformer inside another one, creating a window (unless the ContextFormat is ContextFormatNone) that is later destroyed when the action returns. The inner ContextT monad transformer will share object space with the outer one. The ContextFactory of the outer context will be used in the creation of the inner context.

getContextBuffersSize :: MonadIO m => ContextT w os f m (V2 Int) Source

Return the current size of the context frame buffer. This is needed to set viewport size and to get the aspect ratio to calculate projection matrices.

swapContextBuffers :: MonadIO m => ContextT w os f m () Source

Run this action after a render call to swap out the context windows back buffer with the front buffer, effectively showing the result. This call may block if vsync is enabled in the system and/or too many frames are outstanding. After this call, the context window content is undefined and should be cleared at earliest convenience using clearContextColor and friends.

External interfaces

Users of GPipe shouldn't bother with these functions, instead use a separate window manager package such as GPipe-GLFW that will provide you with a function of type ContextFactory.

To create a window manager package, create a ContextFactory function that provides a ContextHandle with all functionality needed.

data ContextHandle w Source

Constructors

ContextHandle 

Fields

newSharedContext :: forall c ds. ContextFormat c ds -> IO (ContextHandle w)

Like a ContextFactory but creates a context that shares the object space of this handle's context. Called from same thread as created the initial context.

contextDoSync :: forall a. Bool -> IO a -> IO a

Run an OpenGL IO action in this context, returning a value to the caller. The boolean argument will be True if this call references this context's window, and False if it only references shared objects The thread calling this may not be the same creating the context.

contextDoAsync :: Bool -> IO () -> IO ()

Run an OpenGL IO action in this context, that doesn't return any value to the caller. The boolean argument will be True if this call references this context's window, and False if it only references shared objects The thread calling this may not be the same creating the context (for finalizers it is most definetly not).

contextSwap :: IO ()

Swap the front and back buffers in the context's default frame buffer. Called from same thread as created context.

contextFrameBufferSize :: IO (Int, Int)

Get the current size of the context's default framebuffer (which may change if the window is resized). Called from same thread as created context.

contextDelete :: IO ()

Delete this context and close any associated window. Called from same thread as created context.

contextWindow :: w

A value representing the context's window. It is recommended that this is an opaque type that doesn't have any exported functions. Instead, provide ContextT actions that are implemented in terms of withContextWindow to expose any functionality to the user that need a reference the context's window.

withContextWindow :: MonadIO m => (w -> IO a) -> ContextT w os f m a Source

Use the context window handle, which type is specific to the window system used. This handle shouldn't be returned from this function

Hardware exceptions

data GPipeException Source

This kind of exception may be thrown from GPipe when a GPU hardware limit is reached (for instance, too many textures are drawn to from the same FragmentStream)

Constructors

GPipeException String