Graphics.Caramia.Resource

Caramia resources.

Resources in Caramia encapsulate OpenGL resources which have some constraints on their use:

• They are, in the general case, only valid in a specific operating system thread.
• They need an implicit OpenGL context active to be used.

This module helps with the correct finalization of OpenGL resources as according to those constraints.

Most of the time, Caramia keeps Resource objects hidden so you, the user, is unlikely to see these directly.

Documentation

data Resource a

The data type of a Caramia resource.

Instances

Eq (Resource a)

newResource

Arguments

:: (MonadIO m, MonadMask m)

=> m a

Action that returns the raw, unmanaged resource. Good place to create it.

-> (a -> IO ())

OpenGL finalizer. Will only be called in the same thread as this newResource is called, but only if the same OpenGL context is still alive.

-> IO ()

'Ordinary' finalizer. This will be called immediately when garbage collector collects the resource which means before the OpenGL finalizer and in a separate thread. If this finalizer throws an exception then the OpenGL finalizer is cancelled and the resource is marked as finalized. This will be run even if the OpenGL context is gone.

-> m (Resource a)

Creates a new resource.

Must be called in a thread that has an OpenGL context active. Otherwise, an error will be thrown.

If you throw an exception in the OpenGL finalizer, then this will disrupt Caramia context and make it invalid. So try not to throw those exceptions?

withResource

Arguments

:: MonadIO m

=> Resource a

-> (a -> m b)

Use the resource inside this action. Don't return the unmanaged resource from this because behaviour is then undefined.

-> m b

Uses a resource.

Throws an user error if the resource is used in a wrong or dead context.

finalizeNow :: Resource a -> IO ()

Promptly finalize a resource.

This is UNSAFE if you finalize a resource that is being referred to from another resource that you will still use. Consequences will be unpredictable (although you are unlikely to hit a hard crash).

The ordinary finalizer will be run immediately. The OpenGL finalizer will be run if the current thread is the same OpenGL thread where the resource was created.

If ordinary finalizer throws an exception, the OpenGL finalizer is not run and the resource is marked as finalized. The exception propagates out from this call to you.

Does nothing if the resource is already finalized.

newtype WrappedOpenGLResource a

Wrap a Resource to a WrappedOpenGLResource. The wrapped resource has OpenGLResource implementation.

Constructors

WrappedOpenGLResource (Resource a)

Instances

OpenGLResource a (WrappedOpenGLResource a)

Eq (WrappedOpenGLResource a)