Base class for OpenGL buffer objects, which are the building blocks of Vertex Buffer Objects. More...

#include </home/werner/origo/vish/ocean/GLvish/BufferArray.hpp>

Classes

class Activator
Helper class for exception-safe enabling of buffer arrays. More...
struct Error
Exception class that might happen during loading of buffer arrays. More...
struct Inconsistency
Exception class thrown when an array of incompatible number of elements is going to be added to a given VBO object. More...
class MapMemory
API For glMapBuffer. More...

Public Types

enum usage {
  STREAM_DRAW = GL_STREAM_DRAW, STREAM_READ = GL_STREAM_READ, STREAM_COPY = GL_STREAM_COPY, STATIC_DRAW = GL_STATIC_DRAW,
  STATIC_READ = GL_STATIC_READ, STATIC_COPY = GL_STATIC_COPY, DYNAMIC_DRAW = GL_DYNAMIC_DRAW, DYNAMIC_READ = GL_DYNAMIC_READ,
  DYNAMIC_COPY = GL_DYNAMIC_COPY
}
Specifies the expected usage pattern of the data store. More...

Public Member Functions

override bool activate (const Anemone &)
bool bindBuffer () const
bool bindBufferWithPossibleCreation ()
Bind a buffer, possibly creating one if not yet there.
BufferArray (type buffer_target)
Construct an OpenGL buffer object (this call does NOT require an OpenGL Context)
override bool deactivate (const Anemone &)
virtual bool disable () const =0
virtual bool enable () const =0
type getArrayTarget () const
bool isbound () const
Verification function: buffer is bound?
bool isIndexBuffer () const
Check whether this is an index buffer.
bool isVertexArray () const
Check whether this is a vertex array.
size_t memsize () const
Return the memory occupied by this buffer.
size_t NumberOfElements () const
Returns the number of elements referenced via this BufferArray.
void unbindBuffer () const
~BufferArray ()
Destructor - MUST be called within an OpenGL Context.

Protected Member Functions

bool load_subset (int offset, const void *ptr, memsize_t sz) const
Load a subset of the data on the graphics card, updating an existing buffer.
bool load_untyped (const void *ptr, memsize_t MemorySize, size_t nElements, usage usage_hint=STATIC_DRAW)
Loads the given data on the graphix card.

Detailed Description

Base class for OpenGL buffer objects, which are the building blocks of Vertex Buffer Objects.

A possible exception-save usage scenario is via the activateVB() macro:

BufferArray&B;

        activateVB(B)
        {
                ... render code ..
        }

See also:: http://www.songho.ca/opengl/gl_vbo.html

Member Enumeration Documentation

enum Wizt::BufferArray::usage

Specifies the expected usage pattern of the data store.

STREAM The data store contents will be modified once and used at most a few times.
STATIC The data store contents will be modified once and used many times.
DYNAMIC The data store contents will be modified repeatedly and used many times.

The nature of access may be one of these:

DRAW The data store contents are modified by the application, and used as the source for GL drawing and image specification commands.
READ The data store contents are modified by reading data from the GL, and used to return that data when queried by the application.
COPY The data store contents are modified by reading data from the GL, and used as the source for GL drawing and image specification commands.

See also:: http://www.opengl.org/sdk/docs/man/xhtml/glBufferData.xml

Constructor & Destructor Documentation

Wizt::BufferArray::~BufferArray ( )

Destructor - MUST be called within an OpenGL Context.

If called in an non-OpenGL context, segmentation faults in the OpenGL driver/library will most likely occur. The preferred way is to store BufferArray objects in a GLCache, but NOT in an user-defined structure. The GLCache is supposed to be destroyed by the application when the OpenGL Context is destroyed, which is NOT when the containing objects are destroyed. Rather it is when a windows is closed, but not yet the application.

This mechanism does require special care and is non-trivial.

Member Function Documentation

bool Wizt::BufferArray::activate ( const Anemone & )

Note:: This function issues the glGenBuffer() creation call on request.

bool Wizt::BufferArray::load_subset	(	int	offset,
		const void *	ptr,
		memsize_t	sz
	)		const `[protected]`

Load a subset of the data on the graphics card, updating an existing buffer.

Calls glBufferSubData() . http://www.opengl.org/sdk/docs/man/xhtml/glBufferSubData.xml

When replacing the entire data store, consider using glBufferSubData rather than completely recreating the data store with glBufferData. This avoids the cost of reallocating the data store.

Consider using multiple buffer objects to avoid stalling the rendering pipeline during data store updates. If any rendering in the pipeline makes reference to data in the buffer object being updated by glBufferSubData, especially from the specific region being updated, that rendering must drain from the pipeline before the data store can be updated.

Clients must align data elements consistent with the requirements of the client platform, with an additional base-level requirement that an offset within a buffer to a datum comprising N bytes be a multiple of N.

bool Wizt::BufferArray::load_untyped	(	const void *	ptr,
		memsize_t	MemorySize,
		size_t	nElements,
		usage	usage_hint = `STATIC_DRAW`
	)		`[protected]`

Loads the given data on the graphix card.

Binds the current target and calls glBufferData().

Parameters:

MemorySize	How much memory will this call occupy on the GPU? This value will be used in conjunction with the GLCache.
nElements	How much elements will be used in this array? This value will be used to check the consistency of Vertex Buffer Arrays, if an array with different number of elements is added, then an Inconsistency exception will be thrown.

Note:: Clients must align data elements consistent with the requirements of the client platform, with an additional base-level requirement that an offset within a buffer to a datum comprising N bytes be a multiple of N.

See also:: http://www.opengl.org/sdk/docs/man/xhtml/glBufferData.xml

Todo:: Call does unbind() internally. Think if that is a problem and/or should be optimized.

size_t Wizt::BufferArray::NumberOfElements ( ) const [inline]

Returns the number of elements referenced via this BufferArray.

It will be zero at construction and only be set using a typed load() call.

The documentation for this class was generated from the following files:

ocean/GLvish/BufferArray.hpp
ocean/GLvish/BufferArray.cpp