buffertexture< InternalFormat > Class Template Reference

Class encapsulating an OpenGL buffer object. More...

#include <buffertexture.hpp>

Inheritance diagram for buffertexture< InternalFormat >:

Public Member Functions
GLuint	buffer_name () const
	Retrieve the OpenGL name of the buffer. More...
GLuint	texture_name () const
	Retrieve the OpenGL name of the texture. More...
void	bind ()
	Bind this buffer texture. More...
GLuint	name () const
	Retrieve the OpenGL name of this buffer. More...
GLsizeiptr	size () const
	Retrieve the size of buffer. More...
void	bind_range (GLuint index, GLintptr offset, T range_size)
	Bind a range to an indexed target. More...
void	data (T data_size, const GLvoid *data_ptr)
	Allocate storage and upload data. More...
void	sub_data (GLintptr offset, T data_size, const GLvoid *data_ptr)
	Upload a data range. More...
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...
void	get_sub_data (GLintptr offset, T data_size, GLvoid *data_ptr)
	Read back data from the buffer. More...
GLuint	name () const
	Retrieve the OpenGL name of this texture. More...
GLsizei	width () const
	Retrieve the width of the level 0 image of the allocated texture storage. More...
GLsizei	height () const
	Retrieve the height of the level 0 image of the allocated texture storage. More...
GLsizei	depth () const
	Retrieve the depth of the level 0 image of the allocated texture storage. More...
void	parameter (GLenum pname, GLfloat param)
	Set a texture parameter. More...
void	parameter (GLenum pname, GLint param)
	Set a texture parameter. More...
void	parameter (GLenum pname, const GLfloat *param)
	Set a texture parameter. More...
void	parameter (GLenum pname, const GLint *param)
	Set a texture parameter. More...
void	image_1d (GLint level, GLint internal_format, T the_width, GLenum format, GLenum type, const GLvoid *data)
	Allocate storage for a 1D image and upload texture data. More...
void	image_2d (GLint level, GLint internal_format, T the_width, U the_height, GLenum format, GLenum type, const GLvoid *data)
	Allocate storage for a 2D image and upload texture data. More...
void	image_3d (GLint level, GLint internal_format, T the_width, U the_height, V the_depth, GLenum format, GLenum type, const GLvoid *data)
	Allocate storage for a 3D image and upload texture data. More...
void	sub_image_1d (GLint level, T xoffset, U the_width, GLenum format, GLenum type, const GLvoid *data)
	Update a section of a 1D image within the texture. More...
void	sub_image_2d (GLint level, T xoffset, U yoffset, V the_width, W the_height, GLenum format, GLenum type, const GLvoid *data)
	Update a section of a 2D image within the texture. More...
void	sub_image_3d (GLint level, T xoffset, U yoffset, V zoffset, W the_width, X the_height, Y the_depth, GLenum format, GLenum type, const GLvoid *data)
	Update a section of a 3D image within the texture. More...
void	get_image (GLint level, GLint format, GLenum type, GLvoid *img)
	Get image data from this texture. More...
void	generate_mipmap ()
	Generate mipmaps for this texture. More...

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

Detailed Description

template<GLenum InternalFormat>
class gls::buffertexture< InternalFormat >

Class encapsulating an OpenGL buffer object.

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

Template Parameters

InternalFormat

The internal format used by this buffer texture

Unlike other objects in GLS, this simply acts as an interface to a texture object and a buffer object that is used as its storage. As such, any gls::buffertexture object can be used like a normal gls::buffer object created with GL_TEXTURE_BUFFER and GL_STREAM_DRAW template parameters and a normal gls::texture object created with the GL_TEXTURE_BUFFER target.

The names of the underlying objects can be retrieved with buffer_name() and texture_name().

Buffer textures provide a way for samplers to source their data directly from a buffer instead of conventional texture storage. This typically allows for much more data to be available to a shader than if one were to rely solely on uniform storage, whose capacity is an order of magnitude smaller than buffer capacity. However, this also means that the shader will have to fetch more data using a possibly slower path than if it were to use uniforms instead.

Example usage:

auto buffertexture = gls::buffertexture<GL_R32F>();
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 };
buffertexture.data( write_data.size() * sizeof( float ), write_data.data() );

buffertexture.bind();

... do stuff that makes use of samplers that sample from the buffer texture ...

buffertexture.unbind();

Member Function Documentation

GLuint buffer_name

(

)

const

Retrieve the OpenGL name of the buffer.

Returns

OpenGL name of the buffer

GLuint texture_name

(

)

const

Retrieve the OpenGL name of the texture.

Returns

OpenGL name of the texture

void bind

(

)

Bind this buffer texture.

This replaces any buffer texture previously bound to the GL_TEXTURE_BUFFER binding point.

static void unbind ( )

static

Unbind the current buffer texture.

GLuint name ( ) const

inherited

Retrieve the OpenGL name of this buffer.

Returns

OpenGL name of this buffer

GLsizeiptr size ( ) const

inherited

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_range ( GLuint  index, GLintptr  offset, T  range_size  )

inherited

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  )

inherited

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  )

inherited

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  )

inherited

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  )

inherited

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

GLuint name ( ) const

inherited

Retrieve the OpenGL name of this texture.

Returns

OpenGL name of this texture

GLsizei width ( ) const

inherited

Retrieve the width of the level 0 image of the allocated texture storage.

Returns

Width of the level 0 image of the allocated texture storage

GLsizei height ( ) const

inherited

Retrieve the height of the level 0 image of the allocated texture storage.

Returns

Height of the level 0 image of the allocated texture storage

GLsizei depth ( ) const

inherited

Retrieve the depth of the level 0 image of the allocated texture storage.

Returns

Depth of the level 0 image of the allocated texture storage

void parameter ( GLenum  pname, GLfloat  param  )

inherited

Set a texture parameter.

Set the given parameter to the given value

Parameters

pname	Name of the parameter to set
param	Value to set the parameter to

void parameter ( GLenum  pname, GLint  param  )

inherited

Set a texture parameter.

Set the given parameter to the given value

Parameters

pname	Name of the parameter to set
param	Value to set the parameter to

void parameter ( GLenum  pname, const GLfloat *  param  )

inherited

Set a texture parameter.

Set the given parameter to the given value

Parameters

pname	Name of the parameter to set
param	Pointer to the value to set the parameter to

void parameter ( GLenum  pname, const GLint *  param  )

inherited

Set a texture parameter.

Set the given parameter to the given value

Parameters

pname	Name of the parameter to set
param	Pointer to the value to set the parameter to

void image_1d ( GLint  level, GLint  internal_format, T  the_width, GLenum  format, GLenum  type, const GLvoid *  data  )

inherited

Allocate storage for a 1D image and upload texture data.

This marks any previously allocated image storage for deletion by the GL.

Parameters

level	The level of detail number, 0 is the base image, level n is the n-th mipmap
internal_format	Internal format of the texture
the_width	Width of the texture image
format	Format of the data passed to this method
type	Type of the data passed to this method
data	Pointer to memory containing the data to upload

void image_2d ( GLint  level, GLint  internal_format, T  the_width, U  the_height, GLenum  format, GLenum  type, const GLvoid *  data  )

inherited

Allocate storage for a 2D image and upload texture data.

This marks any previously allocated image storage for deletion by the GL.

Parameters

level	The level of detail number, 0 is the base image, level n is the n-th mipmap
internal_format	Internal format of the texture
the_width	Width of the texture image
the_height	Height of the texture image
format	Format of the data passed to this method
type	Type of the data passed to this method
data	Pointer to memory containing the data to upload

void image_3d ( GLint  level, GLint  internal_format, T  the_width, U  the_height, V  the_depth, GLenum  format, GLenum  type, const GLvoid *  data  )

inherited

Allocate storage for a 3D image and upload texture data.

This marks any previously allocated image storage for deletion by the GL.

Parameters

level	The level of detail number, 0 is the base image, level n is the n-th mipmap
internal_format	Internal format of the texture
the_width	Width of the texture image
the_height	Height of the texture image
the_depth	Depth of the texture image
format	Format of the data passed to this method
type	Type of the data passed to this method
data	Pointer to memory containing the data to upload

void sub_image_1d ( GLint  level, T  xoffset, U  the_width, GLenum  format, GLenum  type, const GLvoid *  data  )

inherited

Update a section of a 1D image within the texture.

Parameters

level	The level of detail number, 0 is the base image, level n is the n-th mipmap
xoffset	x-offset of the region to update
the_width	Width of the region to update
format	Format of the data passed to this method
type	Type of the data passed to this method
data	Pointer to memory containing the data to upload

void sub_image_2d ( GLint  level, T  xoffset, U  yoffset, V  the_width, W  the_height, GLenum  format, GLenum  type, const GLvoid *  data  )

inherited

Update a section of a 2D image within the texture.

Parameters

level	The level of detail number, 0 is the base image, level n is the n-th mipmap
xoffset	x-offset of the region to update
yoffset	y-offset of the region to update
the_width	Width of the region to update
the_height	Height of the region to update
format	Format of the data passed to this method
type	Type of the data passed to this method
data	Pointer to memory containing the data to upload

void sub_image_3d ( GLint  level, T  xoffset, U  yoffset, V  zoffset, W  the_width, X  the_height, Y  the_depth, GLenum  format, GLenum  type, const GLvoid *  data  )

inherited

Update a section of a 3D image within the texture.

Parameters

level	The level of detail number, 0 is the base image, level n is the n-th mipmap
xoffset	x-offset of the region to update
yoffset	y-offset of the region to update
zoffset	z-offset of the region to update
the_width	Width of the region to update
the_height	Height of the region to update
the_depth	Depth of the region to update
format	Format of the data passed to this method
type	Type of the data passed to this method
data	Pointer to memory containing the data to upload

void get_image ( GLint  level, GLint  format, GLenum  type, GLvoid *  img  )

inherited

Get image data from this texture.

Parameters

level	The level of detail number, 0 is the base image, level n is the n-th mipmap
format	Format of the returned data
type	Type of the returned data
img	Pointer to memory to write the image data to

void generate_mipmap ( )

inherited

Generate mipmaps for this texture.