cugl::graphics::VertexBuffer Class Reference

#include <CUVertexBuffer.h>

Public Member Functions
	VertexBuffer ()
	~VertexBuffer ()
void	dispose ()
bool	init (size_t size, BufferAccess access=BufferAccess::DYNAMIC)
bool	init (size_t size, size_t stride, BufferAccess access=BufferAccess::DYNAMIC)
void	setName (std::string name)
const std::string	getName () const
BufferData *	getImplementation ()
BufferAccess	getAccess () const
size_t	getCapacity () const
size_t	getStride () const
size_t	getSize () const
size_t	getCount () const
bool	loadData (const std::byte *data, size_t size)
template<typename T >
bool	loadData (const T *data, size_t size)
template<typename T >
bool	loadData (const std::vector< T > &data)
size_t	readData (std::byte *data, size_t size)
template<typename T >
size_t	readData (T *data, size_t size)
template<typename T >
size_t	readData (std::vector< T > &data)

Static Public Member Functions
static std::shared_ptr< VertexBuffer >	alloc (size_t size, BufferAccess access=BufferAccess::DYNAMIC)
static std::shared_ptr< VertexBuffer >	alloc (size_t size, size_t stride, BufferAccess access=BufferAccess::DYNAMIC)

Protected Attributes
std::string	_name
BufferData *	_data
size_t	_capacity
size_t	_stride
BufferAccess	_access
size_t	_size

Detailed Description

This class defines a vertex buffer for drawing with a shader.

A vertex buffer is a collection of data meant to be passed to an attribute binding in a GraphicsShader. Vertex buffers are only intended to attribute data. To ensure maximum flexibility, index buffers are stored separately in an IndexBuffer object.

Vertex buffers with the COMPUTE type may also be used as the output of a ComputeShader. However, this functionality is only supported in Vulkan. The OpenGL limitations of CUGL do not support compute shaders.

Vertex buffer object do not store any information about their contents other than their stride (which can be used for minimal validation checking with a shader). They are simply containers.

Constructor & Destructor Documentation

VertexBuffer()

cugl::graphics::VertexBuffer::VertexBuffer

(

)

Creates an uninitialized vertex buffer.

You must initialize the vertex buffer to allocate buffer memory.

~VertexBuffer()

cugl::graphics::VertexBuffer::~VertexBuffer ( )

inline

Deletes this vertex buffer, disposing all resources.

Member Function Documentation

alloc() [1/2]

static std::shared_ptr< VertexBuffer > cugl::graphics::VertexBuffer::alloc ( size_t  size, BufferAccess  access = BufferAccess::DYNAMIC  )

inlinestatic

Returns a new vertex buffer for the given size and access.

The size is measured in bytes, not number of vertex elements.

Note that some access types such as BufferAccess#STATIC or BufferAccess#COMPUTE_ONLY can only be updated once. Any attempts to load data after the first time will fail.

This method will assume a stride of 0, meaning that no validation with the shader will be attempted.

Parameters

size	The maximum number of bytes in this buffer
access	The buffer access

Returns

a new vertex buffer for the given size and type.

alloc() [2/2]

static std::shared_ptr< VertexBuffer > cugl::graphics::VertexBuffer::alloc ( size_t  size, size_t  stride, BufferAccess  access = BufferAccess::DYNAMIC  )

inlinestatic

Returns a new vertex buffer for the given size, stride, and type.

The size in this method measured in number of elements. The value stride is used to indicate the size of a single element/vertex.

Note that some access types such as BufferAccess#STATIC or BufferAccess#COMPUTE_ONLY can only be updated once. Any attempts to load data after the first time will fail.

Parameters

size	The maximum number of elements in this buffer
stride	The vertex element stride
access	The buffer access

Returns

a new vertex buffer for the given size, stride, and type.

dispose()

void cugl::graphics::VertexBuffer::dispose

(

)

Deletes the vertex buffer, freeing all resources.

You must reinitialize the vertex buffer to use it.

getAccess()

BufferAccess cugl::graphics::VertexBuffer::getAccess ( ) const

inline

Returns the access policy of this vertex buffer

Returns

the access policy of this vertex buffer

getCapacity()

size_t cugl::graphics::VertexBuffer::getCapacity ( ) const

inline

Returns the maximum capacity of this buffer.

The size determines the number of elements that can be loaded with the method loadData.

Returns

the maximum capacity of this buffer.

getCount()

size_t cugl::graphics::VertexBuffer::getCount ( ) const

inline

Returns the number of elements currently stored in this buffer

The value returned is getSize divided by the stride. If the stride is 0, this just returns the number of bytes.

Returns

the number of elements currently stored in this buffer

getImplementation()

BufferData * cugl::graphics::VertexBuffer::getImplementation ( )

inline

Returns the platform-specific implementation for this buffer

The value returned is an opaque type encapsulating the information for either OpenGL or Vulkan.

Returns

the platform-specific implementation for this buffer

getName()

const std::string cugl::graphics::VertexBuffer::getName ( ) const

inline

Returns the name of this vertex buffer.

A name is a user-defined way of identifying a buffer. It is used for debugging purposes only, and has no affect on the graphics pipeline.

Returns

the name of this vertex buffer.

getSize()

size_t cugl::graphics::VertexBuffer::getSize ( ) const

inline

Returns the amount of data currently stored in this buffer

The value returned is the total number of bytes stored in this buffer so far. If 0, that means that no data has been loaded.

Returns

the amount of data currently stored in this buffer

getStride()

size_t cugl::graphics::VertexBuffer::getStride ( ) const

inline

Returns the stride of this vertex buffer

If this value is 0, shaders will not attempt to do any validation. Otherwise, the shader will make sure that its stride matches that of the the vertex buffer.

Returns

the stride of this vertex buffer

init() [1/2]

bool cugl::graphics::VertexBuffer::init ( size_t  size, BufferAccess  access = BufferAccess::DYNAMIC  )

inline

Initializes this vertex buffer for the given size and access.

The size is measured in bytes, not number of vertex elements.

Note that some access types such as BufferAccess#STATIC or BufferAccess#COMPUTE_ONLY can only be updated once. Any attempts to load data after the first time will fail.

This method will assume a stride of 0, meaning that no validation with the shader will be attempted.

Parameters

size	The maximum number of bytes in this buffer
access	The buffer access

Returns

true if initialization was successful.

init() [2/2]

bool cugl::graphics::VertexBuffer::init	(	size_t	size,
		size_t	stride,
		BufferAccess	access = BufferAccess::DYNAMIC
	)

Initializes this vertex buffer for the given size, stride, and access.

The size in this method measured in number of elements. The value stride is used to indicate the size of a single element/vertex.

Note that some access types such as BufferAccess#STATIC or BufferAccess#COMPUTE_ONLY can only be updated once. Any attempts to load data after the first time will fail.

Parameters

size	The maximum number of elements in this buffer
stride	The vertex element stride
access	The buffer access

Returns

true if initialization was successful.

loadData() [1/3]

bool cugl::graphics::VertexBuffer::loadData	(	const std::byte *	data,
		size_t	size
	)

Loads the given vertex buffer with the given data.

Data that is loaded into this buffer can now be read by either a GraphicsShader or a ComputeShader.

Note that this method may only be called once for buffers with access BufferAccess#STATIC, BufferAccess#COMPUTE_ONLY or BufferAccess#COMPUTE_READ. Additional attempts to load into such buffers will fail.

In this version of the method, size is the number of bytes in the data.

Parameters

data	The data to load
size	The number of bytes to load

Returns

true if the data was successfully loaded

loadData() [2/3]

template<typename T >

bool cugl::graphics::VertexBuffer::loadData ( const std::vector< T > &  data )

inline

Loads the given vertex buffer with the given elements.

Data that is loaded into this buffer can now be read by either a GraphicsShader or a ComputeShader.

Note that this method may only be called once for buffers with access BufferAccess#STATIC, BufferAccess#COMPUTE_ONLY or BufferAccess#COMPUTE_READ. Additional attempts to load into such buffers will fail.

Parameters

data	The vertices to load

Returns

true if the data was successfully loaded

loadData() [3/3]

template<typename T >

bool cugl::graphics::VertexBuffer::loadData ( const T *  data, size_t  size  )

inline

Loads the given vertex buffer with the given elements.

Data that is loaded into this buffer can now be read by either a GraphicsShader or a ComputeShader.

Note that this method may only be called once for buffers with access BufferAccess#STATIC, BufferAccess#COMPUTE_ONLY or BufferAccess#COMPUTE_READ. Additional attempts to load into such buffers will fail.

In this version of the method, size is the number of elements of type T in the data array.

Parameters

data	The vertices to load
size	The number of vertices to load

Returns

true if the data was successfully loaded

readData() [1/3]

size_t cugl::graphics::VertexBuffer::readData	(	std::byte *	data,
		size_t	size
	)

Reads from the buffer into the given data array.

VULKAN ONLY: This method allows us to extract the elements of a vertex buffer into any array on the CPU side. It is generally only useful for buffers of type BufferAccess#COMPUTE_READ or BufferAccess#COMPUTE_ALL so that we can inspect the results of a compute shader.

In this version of the method, size is the number of bytes to read.

Parameters

data	The array to receive the data
size	The number of bytes to read

Returns

the number of bytes read

readData() [2/3]

template<typename T >

size_t cugl::graphics::VertexBuffer::readData ( std::vector< T > &  data )

inline

Reads from the buffer into the given vector.

VULKAN ONLY: This method allows us to extract the elements of a vertex buffer into any array on the CPU side. It is generally only useful for buffers of type BufferAccess#COMPUTE_READ or BufferAccess#COMPUTE_ALL so that we can inspect the results of a compute shader.

Data read by this method is appended to the end of the vector. Elements already in the vector are preserved.

Parameters

data	The vector to receive the data

Returns

the number of elements read

readData() [3/3]

template<typename T >

size_t cugl::graphics::VertexBuffer::readData ( T *  data, size_t  size  )

inline

Reads from the buffer into the given data array.

VULKAN ONLY: This method allows us to extract the elements of a vertex buffer into any array on the CPU side. It is generally only useful for buffers of type BufferAccess#COMPUTE_READ or BufferAccess#COMPUTE_ALL so that we can inspect the results of a compute shader.

In this version of the method, size is the number of elements to read.

Parameters

data	The array to receive the data
size	The number of elements to read

Returns

the number of elements read

setName()

void cugl::graphics::VertexBuffer::setName ( std::string  name )

inline

Sets the name of this vertex buffer.

A name is a user-defined way of identifying a buffer. It is used for debugging purposes only, and has no affect on the graphics pipeline.

Parameters

name	The name of this vertex buffer.

Member Data Documentation

_access

BufferAccess cugl::graphics::VertexBuffer::_access

protected

The buffer access

_capacity

size_t cugl::graphics::VertexBuffer::_capacity

protected

The maximum number of bytes supported

_data

BufferData* cugl::graphics::VertexBuffer::_data

protected

The graphics API implementation of this buffer

_name

std::string cugl::graphics::VertexBuffer::_name

protected

The name of this vertex buffer

_size

size_t cugl::graphics::VertexBuffer::_size

protected

The number of bytes loaded into the vertex buffer

_stride

size_t cugl::graphics::VertexBuffer::_stride

protected

The data stride of this buffer (0 if there is only one attribute)

---

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

• /Users/wmwhite/Developer/CUGL/include/cugl/graphics/CUVertexBuffer.h