A class that represents a buffer of shader attributes stored in GPU memory. More...

#include <omGraphicsBuffer.h>

Inheritance diagram for om::graphics::buffers::Buffer:

Public Member Functions
	Buffer ()
	Create an empty vertex buffer with undefined data type and zero capacity. More...

	Buffer (const AttributeType &newType)
	Create an empty vertex buffer with the specified data type and zero capacity. More...

	Buffer (const AttributeType &newType, Size capacity)
	Create an empty vertex buffer containing the specified data type and with the specified capacity. More...

	Buffer (const BufferType &bufferType)
	Create an empty buffer of the given type with undefined data type and zero capacity. More...

	Buffer (const BufferType &bufferType, const AttributeType &newType)
	Create an empty buffer of the given type with the specified data type and zero capacity. More...

	Buffer (const BufferType &bufferType, const AttributeType &newType, Size capacity)
	Create an empty buffer of the given type containing the specified data type and with the specified capacity. More...

	Buffer (devices::GraphicsContext *context, const BufferType &bufferType, const BufferUsage &usage=BufferUsage::STATIC)
	Create an empty GPU-only buffer with the specified context and buffer type. More...

	Buffer (devices::GraphicsContext *context, const BufferType &bufferType, const AttributeType &newType, const BufferUsage &usage=BufferUsage::STATIC)
	Create an empty GPU-only buffer with the specified context, buffer type, and attribute type. More...

	Buffer (devices::GraphicsContext *context, const BufferType &bufferType, const AttributeType &newType, Size capacity, const BufferUsage &usage=BufferUsage::STATIC)
	Create a GPU-only buffer with the specified context, buffer type, attribute type, and capacity. More...

	Buffer (const Buffer &other)
	Create a copy of another buffer. More...

	~Buffer ()
	Destroy a buffer and release its internal resources. More...

Buffer &	operator= (const Buffer &other)
	Copy the contents and state of one buffer to this one. More...

const BufferUsage &	getUsage () const
	Return the current expected usage pattern for this hardware buffer. More...

void	setUsage (const BufferUsage &newUsage)
	Set the current expected usage pattern for this hardware buffer. More...

Size	getSizeInBytes () const
	Return the size in bytes of the attributes stored in the buffer. More...

Size	getSize () const
	Return the number of valid attributes stored in the buffer. More...

Bool	setSize (Size newSize)
	Set the number of valid attributes there are in this buffer. More...

Size	getCapacity () const
	Return the total number of elements of this buffer's current attribute type that it can hold. More...

Bool	setCapacity (Size newCapacity)
	Set the number of elements of this buffer's current attribute type that this buffer is able to hold. More...

Size	getCapacityInBytes () const
	Return the capacity of the buffer in bytes. More...

Bool	setCapacityInBytes (Size newCapacityInBytes)
	Set the number of bytes that this buffer is able to hold. More...

const AttributeType &	getAttributeType () const
	Return the type of elements that this buffer can hold. More...

virtual Bool	setAttributeType (const AttributeType &newAttributeType)
	Set the type of elements that this buffer can hold. More...

void *	getPointer ()
	Return a pointer to the start of the internal buffer of attributes, or NULL if it is not allocated. More...

const void *	getPointer () const
	Return a const pointer to the start of the internal buffer of attributes, or NULL if it is not allocated. More...

Size	getStride () const
	Return the number of bytes between successive elements in the buffer. More...

Bool	hasData () const
	Return whether or not this buffer has data. More...

Bool	getAttributes (void *attributes, Size &numAttributes) const
	Read the specified number of attributes from the buffer into the specified output pointer. More...

Bool	setAttributes (const void *attributes, const AttributeType &attributeType, Size numAttributes)
	Replace the contents of this hardware buffer with the specified attributes. More...

Bool	updateAttributes (const void *attributes, const AttributeType &attributeType, Size numAttributes, Index startIndex=0)
	Update a region of this hardware buffer with the specified attributes. More...

template<typename T >
T	get (Index index) const
	Return the attribute stored at the specified index in this buffer. More...

Bool	getAttribute (Index index, AttributeValue &value) const
	Get the attribute stored at the specified index in this buffer. More...

template<typename T >
void	set (Index index, const T &element)
	Set the attribute stored at the specified index in this buffer. More...

Bool	setAttribute (Index index, const AttributeValue &value) const
	Set the attribute stored at the specified index in this buffer. More...

Bool	addAttribute (const AttributeValue &newAttribute)
	Add the specified attribute to the end of the buffer. More...

template<typename T >
Bool	add (const T &newAttribute)
	Add the specified attribute to the end of the buffer. More...

template<typename T >
Bool	add (const T *newAttributes, Size number)
	Add the specified number of attributes from the given array to the buffer's end. More...

Bool	remove (Index index)
	Remove the element at the specified index in this buffer. More...

Bool	removeUnordered (Index index)
	Remove the element at the specified index in this buffer. More...

void	clear ()
	Clear all entries and the associated attribute type type from the buffer. More...

Bool	reallocate ()
	Reallocate this buffer's data store using its current capacity. More...

Bool	reallocate (BufferUsage newUsage)
	Reallocate this buffer's data store using its current capacity, changing its usage type. More...

void *	map (BufferAccessType accessType)
	Map this buffer's data store to the main memory address space and return a pointer to it. More...

void *	mapRange (BufferAccessType accessType, Index attributeOffset, Size numAttributes)
	Map this buffer's data store to the main memory address space and return a pointer to it. More...

void	unmap () const
	Unmap this buffer's data store to the main memory address space. More...

Bool	isMapped () const
	Return whether or not this buffer is currently mapped to main memory. More...

virtual void	setContext (devices::GraphicsContext *newContext)
	Set a pointer to the graphics context this buffer should use to do rendering. More...

virtual void	upload (UploadRequest &request)
	Upload this buffer's CPU representation to the GPU device. More...

virtual void	download (DownloadRequest &request)
	Download the buffer's GPU representation to CPU memory. More...

virtual Bool	isUploaded () const
	Return whether or not this buffer has been successfully created and uploaded to the device. More...

virtual Bool	isDownloaded () const
	Return whether or not this buffer has a copy of its data stored in CPU-side memory. More...

virtual Bool	isValid () const
	Return whether or not the state of this buffer is valid (either on CPU or GPU) and able to be used for rendering. More...

const DeviceBuffer *	getRenderable () const
	Return a pointer to the context-renderable buffer for this buffer, or NULL if there is none. More...

Public Member Functions inherited from om::graphics::devices::GraphicsContextObject
virtual	~GraphicsContextObject ()
	Destory this graphics context object. More...

GraphicsContext *	getContext () const
	Return a pointer to the graphics context this context object is using to do rendering. More...

void	clearContext ()
	Clear the previous context from this object. More...

void	upload ()
	Upload this resource's CPU representation to the GPU device. More...

void	download ()
	Upload this resource's CPU representation to the GPU device. More...

Additional Inherited Members
Protected Member Functions inherited from om::graphics::devices::GraphicsContextObject
	GraphicsContextObject ()
	Create a new graphics context object that doesn't have an associated graphics context. More...

	GraphicsContextObject (GraphicsContext *newContext)
	Create a new graphics context object that uses the specified context for rendering. More...

Protected Attributes inherited from om::graphics::devices::GraphicsContextObject
GraphicsContext *	context
	A pointer to the graphics context this object is using. More...

Detailed Description

A class that represents a buffer of shader attributes stored in GPU memory.

This class allows attribute data to be stored in the graphics card's RAM for faster access. It is analogous to the Texture class that performs the same function but for pixel data.

Constructor & Destructor Documentation

om::graphics::buffers::Buffer::Buffer ( )

Create an empty vertex buffer with undefined data type and zero capacity.

om::graphics::buffers::Buffer::Buffer ( const AttributeType & newType )

Create an empty vertex buffer with the specified data type and zero capacity.

om::graphics::buffers::Buffer::Buffer	(	const AttributeType &	newType,
		Size	capacity
	)

Create an empty vertex buffer containing the specified data type and with the specified capacity.

om::graphics::buffers::Buffer::Buffer ( const BufferType & bufferType )

Create an empty buffer of the given type with undefined data type and zero capacity.

om::graphics::buffers::Buffer::Buffer	(	const BufferType &	bufferType,
		const AttributeType &	newType
	)

Create an empty buffer of the given type with the specified data type and zero capacity.

om::graphics::buffers::Buffer::Buffer	(	const BufferType &	bufferType,
		const AttributeType &	newType,
		Size	capacity
	)

Create an empty buffer of the given type containing the specified data type and with the specified capacity.

om::graphics::buffers::Buffer::Buffer	(	devices::GraphicsContext *	context,
		const BufferType &	bufferType,
		const BufferUsage &	usage = `BufferUsage::STATIC`
	)

Create an empty GPU-only buffer with the specified context and buffer type.

om::graphics::buffers::Buffer::Buffer	(	devices::GraphicsContext *	context,
		const BufferType &	bufferType,
		const AttributeType &	newType,
		const BufferUsage &	usage = `BufferUsage::STATIC`
	)

Create an empty GPU-only buffer with the specified context, buffer type, and attribute type.

om::graphics::buffers::Buffer::Buffer	(	devices::GraphicsContext *	context,
		const BufferType &	bufferType,
		const AttributeType &	newType,
		Size	capacity,
		const BufferUsage &	usage = `BufferUsage::STATIC`
	)

Create a GPU-only buffer with the specified context, buffer type, attribute type, and capacity.

om::graphics::buffers::Buffer::Buffer ( const Buffer & other )

Create a copy of another buffer.

om::graphics::buffers::Buffer::~Buffer ( )

Destroy a buffer and release its internal resources.

Member Function Documentation

Buffer& om::graphics::buffers::Buffer::operator= ( const Buffer & other )

Copy the contents and state of one buffer to this one.

const BufferUsage& om::graphics::buffers::Buffer::getUsage ( ) const

inline

Return the current expected usage pattern for this hardware buffer.

The usage type can be changed any time the buffer's contents are reallocated.

void om::graphics::buffers::Buffer::setUsage ( const BufferUsage & newUsage )

inline

Set the current expected usage pattern for this hardware buffer.

The usage type can be changed any time the buffer's contents are reallocated.

Size om::graphics::buffers::Buffer::getSizeInBytes ( ) const

inline

Return the size in bytes of the attributes stored in the buffer.

Size om::graphics::buffers::Buffer::getSize ( ) const

inline

Return the number of valid attributes stored in the buffer.

Bool om::graphics::buffers::Buffer::setSize ( Size newSize )

Set the number of valid attributes there are in this buffer.

If the new size is greater than the previous size, the new attribute values at the end of the buffer are undefined. This method otherwise keeps the buffer data intact and only changes the valid data size.

Size om::graphics::buffers::Buffer::getCapacity ( ) const

Return the total number of elements of this buffer's current attribute type that it can hold.

Bool om::graphics::buffers::Buffer::setCapacity ( Size newCapacity )

Set the number of elements of this buffer's current attribute type that this buffer is able to hold.

This method invalidates any contents of the buffer and reallocates the buffer's data store to have the specified capacity.

If the method fails (i.e. capacity too big), the method returns FALSE. Otherwise, the method returns TRUE indicating that the buffer was successfully resized.

Size om::graphics::buffers::Buffer::getCapacityInBytes ( ) const

Return the capacity of the buffer in bytes.

Bool om::graphics::buffers::Buffer::setCapacityInBytes ( Size newCapacityInBytes )

Set the number of bytes that this buffer is able to hold.

This method invalidates any contents of the buffer and reallocates the buffer's data store to have the specified capacity.

If the method fails (i.e. capacity too big), the method returns FALSE. Otherwise, the method returns TRUE indicating that the buffer was successfully resized.

const AttributeType& om::graphics::buffers::Buffer::getAttributeType ( ) const

inline

Return the type of elements that this buffer can hold.

virtual Bool om::graphics::buffers::Buffer::setAttributeType ( const AttributeType & newAttributeType )

virtual

Set the type of elements that this buffer can hold.

This method will not alter the contents of the buffer but it changes how they will be interpreted. The old attribute type is replaced but the capacity and contents are unchanged.

The method returns whether or not the attribute type was able to be changed. A return value of FALSE means that the specified attribute type was incompatible with this buffer.

void* om::graphics::buffers::Buffer::getPointer ( )

inline

Return a pointer to the start of the internal buffer of attributes, or NULL if it is not allocated.

const void* om::graphics::buffers::Buffer::getPointer ( ) const

inline

Return a const pointer to the start of the internal buffer of attributes, or NULL if it is not allocated.

Size om::graphics::buffers::Buffer::getStride ( ) const

inline

Return the number of bytes between successive elements in the buffer.

Bool om::graphics::buffers::Buffer::hasData ( ) const

inline

Return whether or not this buffer has data.

Bool om::graphics::buffers::Buffer::getAttributes	(	void *	attributes,
		Size &	numAttributes
	)		const

Read the specified number of attributes from the buffer into the specified output pointer.

If the method succeeds, it reads the specified number of attributes from the buffer and writes them to the specified attribute pointer and returns TRUE. The number of attributes read from the buffer is written to the output numAttributes reference. If the method fails, FALSE is returned.

The attribute pointer should be allocated with enough room to hold that many attributes of the buffer's type.

Bool om::graphics::buffers::Buffer::setAttributes	(	const void *	attributes,
		const AttributeType &	attributeType,
		Size	numAttributes
	)

Replace the contents of this hardware buffer with the specified attributes.

This method replaces the current contents of the buffer (reallocating the buffer if necessary), and sets this buffer to have the same attribute type as the given buffer.

This variant allows the user to modify the usage type of the buffer's data store.

If the method fails (i.e. if the buffer's attribute type is incompatible with this buffer), FALSE is returned the buffer is unchanged. If the method succeeds, TRUE is returned.

Bool om::graphics::buffers::Buffer::updateAttributes	(	const void *	attributes,
		const AttributeType &	attributeType,
		Size	numAttributes,
		Index	startIndex = `0`
	)

Update a region of this hardware buffer with the specified attributes.

This method updates the current contents of the buffer, starting at the specified attribute start index within the buffer.

If the method fails (i.e. if the buffer's attribute type is incompatible with this buffer), FALSE is returned the buffer is unchanged. If the method succeeds, TRUE is returned.

template<typename T >

T om::graphics::buffers::Buffer::get ( Index index ) const

inline

Return the attribute stored at the specified index in this buffer.

The method will not compile if an invalid output type is specified. A debug assertion is raised if the output type is incompatible with the buffer attribute type or if the specified index is invalid.

Bool om::graphics::buffers::Buffer::getAttribute	(	Index	index,
		AttributeValue &	value
	)		const

Get the attribute stored at the specified index in this buffer.

The value is stored in the output value parameter. The method returns whether or not the value was able to be accessed.

template<typename T >

void om::graphics::buffers::Buffer::set	(	Index	index,
		const T &	element
	)

inline

Set the attribute stored at the specified index in this buffer.

The method will not compile if an invalid output type is specified. A debug assertion is raised if the input type is incompatible with the buffer attribute type or if the specified index is invalid.

Bool om::graphics::buffers::Buffer::setAttribute	(	Index	index,
		const AttributeValue &	value
	)		const

Set the attribute stored at the specified index in this buffer.

The value is copied from the value parameter. The method returns whether or not the value was able to be set. The method can fail if the index is invalid or the value's type does not match the buffer's type.

Bool om::graphics::buffers::Buffer::addAttribute ( const AttributeValue & newAttribute )

Add the specified attribute to the end of the buffer.

If the type of the argument is incompatable with the current type of the buffer then FALSE is returned. Otherwise TRUE is returned.

template<typename T >

Bool om::graphics::buffers::Buffer::add ( const T & newAttribute )

inline

Add the specified attribute to the end of the buffer.

If the type of the argument is incompatable with the current type of the buffer then FALSE is returned. Otherwise TRUE is returned.

template<typename T >

Bool om::graphics::buffers::Buffer::add	(	const T *	newAttributes,
		Size	number
	)

inline

Add the specified number of attributes from the given array to the buffer's end.

If the type of the argument elements is incompatable with the current type of the buffer then FALSE is returned. Otherwise TRUE is returned.

Bool om::graphics::buffers::Buffer::remove ( Index index )

Remove the element at the specified index in this buffer.

This method maintains the order of the buffer elements and copies them to fill the space left by the removed element.

Bool om::graphics::buffers::Buffer::removeUnordered ( Index index )

Remove the element at the specified index in this buffer.

This method moves the last element in the buffer to fill the space left by the removed element.

void om::graphics::buffers::Buffer::clear ( )

Clear all entries and the associated attribute type type from the buffer.

This method doesn't release any of the buffer's data, allowing the buffer's data to be reused again. The resulting buffer has AttributeType::UNDEFINED as its attribute type.

Bool om::graphics::buffers::Buffer::reallocate ( )

Reallocate this buffer's data store using its current capacity.

This method allows the user to get a new data store for the buffer, releasing the previous data store. This is useful if you are using a memory-mapped buffer to transfer vertices to the GPU. By releasing the buffer before mapping it, you signal that you don't need the old buffer anymore, avoiding synchronization stalls.

The resulting contents of the buffer are undefined.

Bool om::graphics::buffers::Buffer::reallocate ( BufferUsage newUsage )

Reallocate this buffer's data store using its current capacity, changing its usage type.

This method allows the user to get a new data store for the buffer, releasing the previous data store. This is useful if you are using a memory-mapped buffer to transfer vertices to the GPU. By releasing the buffer before mapping it, you signal that you don't need the old buffer anymore, avoiding synchronization stalls.

The resulting contents of the buffer are undefined.

This variant allows the user to change the usage of the buffer when it is reallocated.

void* om::graphics::buffers::Buffer::map ( BufferAccessType accessType )

Map this buffer's data store to the main memory address space and return a pointer to it.

The method returns NULL if the buffer is unable to be mapped with the given access type. The method allows the user to specify an offset within the buffer that is applied to the returned pointer, in units of the attribute type width.

void* om::graphics::buffers::Buffer::mapRange	(	BufferAccessType	accessType,
		Index	attributeOffset,
		Size	numAttributes
	)

Map this buffer's data store to the main memory address space and return a pointer to it.

The method returns NULL if the buffer is unable to be mapped with the given access type. The method allows the user to specify an offset within the buffer that is applied to the returned pointer, in units of the attribute type width.

void om::graphics::buffers::Buffer::unmap ( ) const

Unmap this buffer's data store to the main memory address space.

Bool om::graphics::buffers::Buffer::isMapped ( ) const

Return whether or not this buffer is currently mapped to main memory.

If this method returns TRUE, it means that a BufferIterator is probably iterating over the buffer. The buffer cannot be used for any drawing until the iterator object is destroyed, causing the buffer's data to be unmapped from main memory.

virtual void om::graphics::buffers::Buffer::setContext ( devices::GraphicsContext * newContext )

virtual

Set a pointer to the graphics context this buffer should use to do rendering.

Reimplemented from om::graphics::devices::GraphicsContextObject.

virtual void om::graphics::buffers::Buffer::upload ( UploadRequest & request )

virtual

Upload this buffer's CPU representation to the GPU device.

Reimplemented from om::graphics::devices::GraphicsContextObject.

virtual void om::graphics::buffers::Buffer::download ( DownloadRequest & request )

virtual

Download the buffer's GPU representation to CPU memory.

Reimplemented from om::graphics::devices::GraphicsContextObject.

virtual Bool om::graphics::buffers::Buffer::isUploaded ( ) const

virtual

Return whether or not this buffer has been successfully created and uploaded to the device.

Reimplemented from om::graphics::devices::GraphicsContextObject.

virtual Bool om::graphics::buffers::Buffer::isDownloaded ( ) const

virtual

Return whether or not this buffer has a copy of its data stored in CPU-side memory.

Reimplemented from om::graphics::devices::GraphicsContextObject.

virtual Bool om::graphics::buffers::Buffer::isValid ( ) const

virtual

Return whether or not the state of this buffer is valid (either on CPU or GPU) and able to be used for rendering.

Reimplemented from om::graphics::devices::GraphicsContextObject.

const DeviceBuffer* om::graphics::buffers::Buffer::getRenderable ( ) const

inline

Return a pointer to the context-renderable buffer for this buffer, or NULL if there is none.

If the buffer has a valid context and the the data for this buffer has been uploaded to the GPU successfully after a call to upload(), the method returns a pointer to the GPU buffer instance for this buffer object.

Otherwise, the buffer is not renderable and NULL is returned.

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

omGraphicsBuffer.h

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation