buffer< Target, Usage > Class Template Reference

Class encapsulating an OpenGL buffer object. More...

#include <buffer.hpp>

Public Member Functions
GLuint	name () const
	Retrieve the OpenGL name of this buffer. More...
GLsizeiptr	size () const
	Retrieve the size of buffer. More...
void	bind ()
	Bind this buffer to its target. More...
template<typename T >
void	bind_range (GLuint index, GLintptr offset, T range_size)
	Bind a range to an indexed target. More...
template<typename T >
void	data (T data_size, const GLvoid *data_ptr)
	Allocate storage and upload data. More...
template<typename T >
void	sub_data (GLintptr offset, T data_size, const GLvoid *data_ptr)
	Upload a data range. More...
template<GLenum SourceTarget, GLenum SourceUsage, typename V >
void	copy_sub_data (const buffer< SourceTarget, SourceUsage > &source, GLintptr readoffset, GLintptr writeoffset, V data_size)
	Copy a data range from another buffer into this one. More...
template<typename T >
void	get_sub_data (GLintptr offset, T data_size, GLvoid *data_ptr)
	Read back data from the buffer. More...

Static Public Member Functions
static void	unbind ()
	Unbind the current buffer from the target. More...

Detailed Description

template<GLenum Target = GL_ARRAY_BUFFER, GLenum Usage = GL_DYNAMIC_DRAW>
class gls::buffer< Target, Usage >

Class encapsulating an OpenGL buffer object.

A gls::buffer is an object that encapsulates an OpenGL buffer object.

Template Parameters

Target	The target this buffer object will be bound to when calling bind()
Usage	The usage hint passed to OpenGL when the buffer storage is created

Like all objects in GLS, the underlying name is generated at object construction and deleted at destruction. This can be retrieved with name().

Buffer objects store arbitrary data within server (GPU) memory. This buffer can then be used to e.g. provide attribute data to shaders or act as the data storage for uniform blocks.

All the provided methods offer different ways of manipulating the buffer's data content. One must be aware of the performance implications some transfers might have. As a general rule of thumb, try to avoid unnecessary transfers between client and server, and re-use data within the buffers if possible.

To use a gls::buffer, simply call bind(). It will bind the gls::buffer to its target binding and replace any previously bound to that target. To clear the binding to that target, call unbind().

Example usage:

auto buffer1 = gls::buffer<GL_ARRAY_BUFFER, GL_DYNAMIC_DRAW>();

auto write_data = std::vector<float>();
write_data = { 1.f, 2.f, 3.f, 4.f, 5.f, 6.f, 7.f, 8.f, 9.f };
buffer1.data( write_data.size() * sizeof( float ), write_data.data() );

auto buffer2 = gls::buffer<GL_UNIFORM_BUFFER, GL_STREAM_DRAW>();
buffer2.copy_sub_data( buffer1, 0, 0, buffer1.size() );

write_data = { 0.f, 0.f, 0.f };
buffer2.sub_data( 3 * sizeof( float ), write_data.size() * sizeof( float ), write_data.data() );

Member Function Documentation

GLuint name

(

)

const

Retrieve the OpenGL name of this buffer.

Returns

OpenGL name of this buffer

GLsizeiptr size

(

)

const

Retrieve the size of buffer.

After calling data(), storage is allocated for the buffer by the GL. This method returns how much storage was requested during the last allocation that took place.

Returns

OpenGL name of this buffer

void bind

(

)

Bind this buffer to its target.

Bind this buffer to the target specified by the Target template parameter. This replaces any previous binding on that target.

static void unbind ( )

static

Unbind the current buffer from the target.

Unbind the buffer currently bound to the target specified by the Target template parameter.

void bind_range	(	GLuint	index,
		GLintptr	offset,
		T	range_size
	)

Bind a range to an indexed target.

Bind a range given by an offset into this buffer along with the size of the range in bytes to an indexed buffer target. The target is specified by the Target template parameter.

Parameters

index	Index of the binding point within the target
offset	Byte offset into the buffer where the range starts
range_size	Size of the range in bytes

void data	(	T	data_size,
		const GLvoid *	data_ptr
	)

Allocate storage and upload data.

Request the GL to allocate storage for this buffer specifying usage according to the Usage template parameter and optionally upload data to it. If no data should currently be uploaded, pass a nullptr as the second argument.

Even if the new size is equal to the previously allocated size, this method will orphan the buffer. If this is not wanted, use sub_data() instead.

If you only want to partially fill the buffer with data, pass nullptr as the second argument and call sub_data() after this.

Parameters

data_size	Size in bytes of the storage to be allocated
data_ptr	Pointer to a data source to upload from, or nullptr if no upload should take place

void sub_data	(	GLintptr	offset,
		T	data_size,
		const GLvoid *	data_ptr
	)

Upload a data range.

Upload a range of data to the buffer at the given byte offset. If the current buffer is not large enough to hold all the data, a new buffer will be created and will replace the current one. Be aware that if this reallocation takes place, the name of the underlying buffer object will be changed, and updating all references to this buffer may be necessary.

Parameters

offset	Byte offset into the buffer where the data should be uploaded
data_size	Size of the range of data to be uploaded in bytes
data_ptr	Pointer to a data source to upload from

void copy_sub_data	(	const buffer< SourceTarget, SourceUsage > &	source,
		GLintptr	readoffset,
		GLintptr	writeoffset,
		V	data_size
	)

Copy a data range from another buffer into this one.

This copies a range of data of the specified size in bytes from the read offset in bytes from the source buffer to this buffer at the write offset in bytes. If the current buffer is not large enough to hold all the data, a new buffer will be created and will replace the current one. Be aware that if this reallocation takes place, the name of the underlying buffer object will be changed, and updating all references to this buffer may be necessary.

Because this data transfer takes place on the server (GPU), this avoids any expensive read backs that would be incurred if done manually using a combination of the other methods.

Parameters

source	Source buffer to copy data from
readoffset	Offset in bytes of the start of the range to read from the source buffer
writeoffset	Offset in bytes to start writing the range to in this buffer
data_size	Size in bytes of the range to copy

void get_sub_data	(	GLintptr	offset,
		T	data_size,
		GLvoid *	data_ptr
	)

Read back data from the buffer.

This reads a range of data from the buffer back into client memory.

Parameters

offset	Offset in bytes into the buffer to read the range from
data_size	Size in bytes of the range
data_ptr	Pointer to client memory that is large enough to hold the data