Graphics.Caramia.Buffer

Buffer objects.

These are chunks of memory (typically) kept on the GPU.

https://www.opengl.org/wiki/Buffer_Object

Creation

newBuffer :: MonadIO m => BufferCreation -> m Buffer

Creates a new buffer according to BufferCreation specification.

newBufferFromBS :: MonadIO m => ByteString -> (BufferCreation -> BufferCreation) -> m Buffer

Creates a buffer from a strict bytestring.

The principle is the same as in newBufferFromVector.

newBufferFromList :: (Storable a, MonadIO m) => [a] -> (BufferCreation -> BufferCreation) -> m Buffer

Creates a buffer from a list.

The principle is the same as in newBufferFromVector.

newBufferFromVector

Arguments

:: (Storable a, MonadIO m)

=> Vector a

-> (BufferCreation -> BufferCreation)

A hook to modify BufferCreation. You can use id. By default all access is forbidden and buffer usage is static, draw. Don't shrink buffer size or this may crash.

-> m Buffer

Creates a buffer from a storable vector.

This is a convenience function.

Types

data Buffer

Buffer data type.

Instances

Eq Buffer

Ord Buffer

Show Buffer

OpenGLResource GLuint Buffer

data AccessFrequency

The frequency of access to a buffer.

These correspond to the OpenGL access frequency hints. You can look for them in the OpenGL specification or check this link:

https://www.opengl.org/wiki/GLAPI/glBufferData

Constructors

Stream

Static

Dynamic

Instances

Enum AccessFrequency

Eq AccessFrequency

Data AccessFrequency

Ord AccessFrequency

Read AccessFrequency

Show AccessFrequency

Generic AccessFrequency

type Rep AccessFrequency

data AccessNature

The nature of access to a buffer.

These correspond to the OpenGL access nature hints. You can look for them in the OpenGL specification or check this link:

https://www.opengl.org/wiki/GLAPI/glBufferData

Constructors

Draw

Read

Copy

Instances

Enum AccessNature

Eq AccessNature

Data AccessNature

Ord AccessNature

Read AccessNature

Show AccessNature

Generic AccessNature

type Rep AccessNature

data AccessFlags

Describes a style of mapping.

Constructors

ReadAccess

The mapping can be read from.

WriteAccess

The mapping can be written to.

ReadWriteAccess

Both reading and writing can be done.

NoAccess

No access; you cannot map the buffer at all after creation.

Instances

Enum AccessFlags

Eq AccessFlags

Data AccessFlags

Ord AccessFlags

Read AccessFlags

Show AccessFlags

Generic AccessFlags

type Rep AccessFlags

data MapFlag

Additional mapping flags.

Constructors

UnSynchronized

Map the buffer without synchronization. You will have to use synchronization primitives to make sure you and OpenGL won't be using the buffer at the same time.

ExplicitFlush

If set, you need to explicitly flush ranges of the mapping after you have modified them, with explicitFlush. The mapping must allow writes. Requires OpenGL 3.0 or greater or "GL_ARB_map_buffer_range", but if neither of these are available, then this flag is no-op and so is explicitFlush.

Explicit flushing can be useful when you map a large buffer but don't know beforehand how much of that buffer you are going to modify.

Instances

Enum MapFlag

Eq MapFlag

Data MapFlag

Ord MapFlag

Read MapFlag

Show MapFlag

Generic MapFlag

type Rep MapFlag

data BufferCreation

This data describes how a buffer should behave and what operations can be done with it.

Accurate description can improve performance.

For forwards compatibility, it is recommended to use defaultBufferCreation and then set the fields you want to change.

Constructors

BufferCreation

Fields

accessHints :: !(AccessFrequency, AccessNature)

Hints on how the buffer will be used.

size :: !Int

How large the buffer should be, in bytes.

initialData :: !(Maybe (Ptr ()))

The initial data to be copied to the buffer. Can be Nothing in which case the initial contents are undefined.

accessFlags :: !AccessFlags

What kind of mapping access is allowed. See map.

Instances

Eq BufferCreation

Data BufferCreation

Ord BufferCreation

Show BufferCreation

Generic BufferCreation

type Rep BufferCreation

defaultBufferCreation :: BufferCreation

The default buffer creation flags.

The default attempts to give you the most general (and possibly slowest) buffer. Both read and write access are allowed.

Default size is 0 which will make newBuffer fail if you don't set it.

Invalidation

invalidateBuffer :: MonadIO m => Buffer -> m ()

Invalidates the contents of a buffer.

This is you saying: "I don't care what's in this buffer anymore. You can do whatever you want with it.".

The data may be gone or it may not be gone. Use this as a hint to the implementation that you will not use the _current_ contents of the buffer anymore.

This requires the OpenGL extension "GL_ARB_invalidate_subdata" but if this extension is not present, then this simply does nothing.

See https://www.opengl.org/wiki/Buffer_Object#Invalidation.

Explicit flushing

explicitFlush

Arguments

:: MonadIO m

=> Buffer

-> Int

Offset, in bytes, from start of the mapped region.

-> Int

How many bytes to flush.

-> m ()

Explicitly flushes part of a buffer mapping.

The buffer must have been mapped with ExplicitFlush set. Furthermore, either OpenGL 3.0 or "GL_ARB_map_buffer_range" is required; however this function does nothing is neither of those are available.

Manipulation

bufferMap

Arguments

:: MonadIO m

=> Int

Offset, in bytes, from start of the buffer from where to map.

-> Int

How many bytes to map.

-> AccessFlags

What access is allowed in the mapping.

-> Buffer

-> m (Ptr a)

Maps (part) of a buffer to system memory space.

The mapping is valid until the buffer is garbage collected (in which case the mapping is automatically unmapped) or when bufferUnmap is called on the buffer.

You can not have two mappings going on at the same time.

bufferMap2 :: MonadIO m => Set MapFlag -> Int -> Int -> AccessFlags -> Buffer -> m (Ptr a)

Same as bufferMap but allows more control over mapping.

 bufferMap = bufferMap2 mempty

bufferUnmap :: MonadIO m => Buffer -> m ()

Unmaps a buffer.

Does nothing if the buffer was not mapped.

It is possible that the mapping become corrupt during the time it was mapped. If there was corruption, BufferCorruption is thrown in this call.

Corruption means that the contents of the buffer are now undefined.

copy

Arguments

:: MonadIO m

=> Buffer

Destination buffer.

-> Int

Offset in destination buffer.

-> Buffer

Source buffer.

-> Int

Offset in source buffer.

-> Int

How many bytes to copy.

-> m ()

Copies bytes from one buffer to another.

This will use GL_ARB_copy_buffer extension if it is available (this became available in OpenGL 3.1).

The buffers must not be mapped; however this call can bypass the access flags set in newBuffer, if the above extension is available. That is, you can copy data even to a buffer that was set as not writable or copy from a buffer that was set as not readable.

When GL_ARB_copy_buffer is not available, this is implemented in terms of withMapping and is subject to mapping restrictions.

This is faster (when the required extensions are available) than mapping both buffers and then doing a memcpy() style copying in system memory because this call usually does not require a round-trip to the driver.

You can use the same buffer for both destination and source but the copying area may not overlap.

withMapping

Arguments

:: (MonadIO m, MonadMask m)

=> Int

-> Int

-> AccessFlags

-> Buffer

-> (Ptr b -> m a)

The pointer is valid during this action.

-> m a

A convenience function over map/unmap that automatically unmaps the buffer when done (even in the case of exceptions).

The arguments to this function are the same as for bufferMap, except for extra action argument.

This calls bufferUnmap which means it can throw BufferCorruption when the action is done.

There is a rare case that can happen if your action throws an exception AND the unmapping throws an exception. Which exception is propagated upwards? If this happens, this call silences BufferCorruption exception and re-throws the user exception. This unfortunately means there is no way to know if the buffer was corrupted if you threw an exception inside the action.

withMapping2 :: (MonadIO m, MonadMask m) => Set MapFlag -> Int -> Int -> AccessFlags -> Buffer -> (Ptr b -> m a) -> m a

Same as withMapping but with map flags.

See bufferMap2.

uploadVector

Arguments

:: (MonadIO m, MonadMask m, Storable a)

=> Vector a

The vector from which to pull data.

-> Int

Offset, in bytes, to which point in the buffer to copy the data.

-> Buffer

-> m ()

A convenience function to upload a storable vector to a buffer.

The buffer must be in an unmapped state and must be write-mappable.

Views

viewSize :: Buffer -> Int

Returns the size of the buffer, in bytes.

viewAllowedMappings :: Buffer -> AccessFlags

Returns the allowed mappings.

Exceptions

data BufferCorruption

Exception that is thrown from bufferUnmap when buffer corruption is detected.

Corruption can happen due to external factors and is system-specific.

Constructors

BufferCorruption Buffer

Instances

Eq BufferCorruption

Show BufferCorruption

Exception BufferCorruption