Abstraction of OpenGL Pixel Buffer Object, an efficient way of transferring data to or from a GPU. More...

Inherits G3D::PixelTransferBuffer.

Public Member Functions
virtual	~GLPixelTransferBuffer ()

void	bindAsShaderStorageBuffer (int bindpoint)
	Bind this as an OpenGL GL_SHADER_STORAGE_BUFFER so that it can be read from and written to in a shader. More...

void	bindRead ()
	Bind this as the current OpenGL GL_PIXEL_UNPACK_BUFFER so that OpenGL can read from it. More...

void	bindWrite ()
	Bind this as the current OpenGL GL_PIXEL_PACK_BUFFER so that OpenGL can write to it. More...

int	depth () const

const ImageFormat *	format () const

virtual void	getData (void *data) const override
	Read back the current contents to data. More...

uint64	getGPUAddress (GLenum access=GL_READ_WRITE) const
	CC: NVIDIA-only bindless GPU pointers. More...

unsigned int	glBufferID () const
	The underlying OpenGL buffer ID. More...

int	height () const

virtual const void *	mapRead () const override
	Obtain a pointer for read-only access. More...

virtual void *	mapReadWrite () override
	Obtain a pointer for general access. More...

virtual void *	mapWrite () override
	Obtain a pointer for write-only access. More...

virtual bool	ownsMemory () const
	If true, the data lifetime is independent of the PixelTransferBuffer lifetime. More...

int	pixelCount () const

virtual bool	readyToMap () const override
	Returns true if calls to mapX() will not block the CPU on the GPU. More...

void	registerMapHook (std::function< void(GLint)> mapHook) const

void	registerReallocationHook (std::function< void(GLint)> reallocateHook) const

virtual bool	requiresGPUContext () const override
	If true, then readyToMap(), mapRead(), mapWrite(), mapReadWrite(), and unmap() can only be invoked on a thread that currently has an active OpenGL context. More...

void	resize (int newWidth, int newHeight, int newDepth=1)
	Invokes the reallocation hook is one is registered. More...

size_t	rowAlignment () const
	Returns alignment of each row of pixel data in bytes. More...

size_t	rowOffset (int y, int d=0) const
	Return the byte offset from the mapped pointer for the row to raw pixel data at start of row y of depth d. More...

void	runMapHooks () const
	Executes the callback function previously set by registerMapHook(). More...

void	runReallocateHooks () const
	Executes the callback function previously set by registerReallocationHook(). More...

virtual void	setData (const void *data) override
	Overwrite the current contents with data. More...

size_t	size () const
	Returns entire size of pixel data in bytes. More...

size_t	stride () const
	Returns size of each row of pixel data in bytes. More...

void	unbindRead ()
	Unbind the current OpenGL GL_PIXEL_UNPACK_BUFFER. More...

void	unbindWrite ()
	Unbind the current OpenGL GL_PIXEL_PACK_BUFFER. More...

template<class T >
void	unmap (const T *&setToNull) const

virtual void	unmap () const override

int	width () const

Static Public Member Functions
static void	copy (const shared_ptr< GLPixelTransferBuffer > &src, const shared_ptr< GLPixelTransferBuffer > &dst, int srcSizePixels=-1, int srcUpperLeftPixelIndex=0, int dstUpperLeftPixelIndex=0)

static shared_ptr< GLPixelTransferBuffer >	create (int width, int height, const ImageFormat format, const void data=nullptr, int depth=1, uint32 glUsageHint=GL_STREAM_COPY)
	Creates a buffer backed by an OpenGL PBO of uninitialized values. More...

static void	deleteAllBuffers ()
	Calls glDeleteBuffers on the free list. More...

Protected Member Functions
	GLPixelTransferBuffer (const ImageFormat format, int width, int height, int depth, const void data, uint32 glUsageHint)

void	map (unsigned int access) const

Static Protected Member Functions
template<class T , class ... ArgTypes>
static shared_ptr< T >	createShared (ArgTypes &&... args)
	Like std::make_shared, but works for protected constructors. More...

Protected Attributes
int	m_depth

const ImageFormat *	m_format

unsigned int	m_glBufferID

uint32	m_glUsageHint

int	m_height

shared_ptr< std::function< void(GLint)> >	m_mapHook

void *	m_mappedPointer
	nullptr if not currently mapped. More...

shared_ptr< Milestone >	m_milestone
	If this was created from data on the GPU, then m_milestone is the milestone that must be reached before the data can be memory mapped on the CPU. More...

shared_ptr< std::function< void(GLint)> >	m_reallocateHook

size_t	m_rowAlignment

size_t	m_rowStride

int	m_width

Detailed Description

Abstraction of OpenGL Pixel Buffer Object, an efficient way of transferring data to or from a GPU.

See also: PixelTransferBuffer, CPUPixelTransferBuffer, Image, Texture, VideoInput, VideoOutput, ImageFormat, VertexBuffer, Material, UniversalMaterial, Texture::toPixelTransferBuffer

Constructor & Destructor Documentation

◆ GLPixelTransferBuffer()

G3D::GLPixelTransferBuffer::GLPixelTransferBuffer	(	const ImageFormat *	format,
		int	width,
		int	height,
		int	depth,
		const void *	data,
		uint32	glUsageHint
	)

protected

◆ ~GLPixelTransferBuffer()

virtual G3D::GLPixelTransferBuffer::~GLPixelTransferBuffer ( )

virtual

Member Function Documentation

◆ bindAsShaderStorageBuffer()

void G3D::GLPixelTransferBuffer::bindAsShaderStorageBuffer ( int bindpoint )

Bind this as an OpenGL GL_SHADER_STORAGE_BUFFER so that it can be read from and written to in a shader.

Subsequent calls to the same bindpoint will replace the previously bound buffer with the new one.

◆ bindRead()

void G3D::GLPixelTransferBuffer::bindRead ( )

Bind this as the current OpenGL GL_PIXEL_UNPACK_BUFFER so that OpenGL can read from it.

◆ bindWrite()

void G3D::GLPixelTransferBuffer::bindWrite ( )

Bind this as the current OpenGL GL_PIXEL_PACK_BUFFER so that OpenGL can write to it.

◆ copy()

static void G3D::GLPixelTransferBuffer::copy	(	const shared_ptr< GLPixelTransferBuffer > &	src,
		const shared_ptr< GLPixelTransferBuffer > &	dst,
		int	srcSizePixels = `-1`,
		int	srcUpperLeftPixelIndex = `0`,
		int	dstUpperLeftPixelIndex = `0`
	)

static

Parameters

srcUpperLeftPixelIndex	Starting pixel index, in row-major order
srcSizePixels	-1 means size of src

◆ create()

static shared_ptr<GLPixelTransferBuffer> G3D::GLPixelTransferBuffer::create	(	int	width,
		int	height,
		const ImageFormat *	format,
		const void *	data = `nullptr`,
		int	depth = `1`,
		uint32	glUsageHint = `GL_STREAM_COPY`
	)

static

Creates a buffer backed by an OpenGL PBO of uninitialized values.

Parameters

data	If non-nullptr, copy this data to the GPU as the initial value of the buffer. The pointer is not returned and the data may be deallocated as soon as the method returns.

◆ createShared()

template<class T , class ... ArgTypes>

static shared_ptr<T> G3D::ReferenceCountedObject::createShared ( ArgTypes &&... args )

inlinestaticprotectedinherited

Like std::make_shared, but works for protected constructors.

Call as createShared<myclass>.

◆ deleteAllBuffers()

static void G3D::GLPixelTransferBuffer::deleteAllBuffers ( )

static

Calls glDeleteBuffers on the free list.

◆ depth()

int G3D::PixelTransferBuffer::depth ( ) const

inlineinherited

◆ format()

const ImageFormat* G3D::PixelTransferBuffer::format ( ) const

inlineinherited

◆ getData()

virtual void G3D::GLPixelTransferBuffer::getData ( void * data ) const

overridevirtual

Read back the current contents to data.

Cannot call while mapped.

Implements G3D::PixelTransferBuffer.

◆ getGPUAddress()

uint64 G3D::GLPixelTransferBuffer::getGPUAddress ( GLenum access = GL_READ_WRITE ) const

CC: NVIDIA-only bindless GPU pointers.

◆ glBufferID()

unsigned int G3D::GLPixelTransferBuffer::glBufferID ( ) const

inline

The underlying OpenGL buffer ID.

◆ height()

int G3D::PixelTransferBuffer::height ( ) const

inlineinherited

◆ map()

void G3D::GLPixelTransferBuffer::map ( unsigned int access ) const

protected

◆ mapRead()

virtual const void* G3D::GLPixelTransferBuffer::mapRead ( ) const

overridevirtual

Obtain a pointer for read-only access.

See also: mapReadWrite, mapWrite, unmap

Implements G3D::PixelTransferBuffer.

◆ mapReadWrite()

virtual void* G3D::GLPixelTransferBuffer::mapReadWrite ( )

overridevirtual

Obtain a pointer for general access.

See also: mapRead, mapWrite, unmap

Implements G3D::PixelTransferBuffer.

◆ mapWrite()

virtual void* G3D::GLPixelTransferBuffer::mapWrite ( )

overridevirtual

Obtain a pointer for write-only access.

See also: mapRead, mapReadWrite, unmap

Implements G3D::PixelTransferBuffer.

◆ ownsMemory()

virtual bool G3D::PixelTransferBuffer::ownsMemory ( ) const

inlinevirtualinherited

If true, the data lifetime is independent of the PixelTransferBuffer lifetime.

For example, holding the PixelTransferBuffer may not keep the data valid if ownsMemory() = false.

Reimplemented in G3D::CPUPixelTransferBuffer.

◆ pixelCount()

int G3D::PixelTransferBuffer::pixelCount ( ) const

inlineinherited

◆ readyToMap()

virtual bool G3D::GLPixelTransferBuffer::readyToMap ( ) const

overridevirtual

Returns true if calls to mapX() will not block the CPU on the GPU.

Implements G3D::PixelTransferBuffer.

◆ registerMapHook()

void G3D::GLPixelTransferBuffer::registerMapHook ( std::function< void(GLint)> mapHook ) const

inline

◆ registerReallocationHook()

void G3D::GLPixelTransferBuffer::registerReallocationHook ( std::function< void(GLint)> reallocateHook ) const

inline

◆ requiresGPUContext()

virtual bool G3D::GLPixelTransferBuffer::requiresGPUContext ( ) const

inlineoverridevirtual

If true, then readyToMap(), mapRead(), mapWrite(), mapReadWrite(), and unmap() can only be invoked on a thread that currently has an active OpenGL context.

Always returns false for the base class.

Implements G3D::PixelTransferBuffer.

◆ resize()

void G3D::GLPixelTransferBuffer::resize	(	int	newWidth,
		int	newHeight,
		int	newDepth = `1`
	)

Invokes the reallocation hook is one is registered.

The contents are undefined after resize.

◆ rowAlignment()

size_t G3D::PixelTransferBuffer::rowAlignment ( ) const

inlineinherited

Returns alignment of each row of pixel data in bytes.

◆ rowOffset()

size_t G3D::PixelTransferBuffer::rowOffset	(	int	y,
		int	d = `0`
	)		const

inlineinherited

Return the byte offset from the mapped pointer for the row to raw pixel data at start of row y of depth d.

Referenced by G3D::CPUPixelTransferBuffer::row().

◆ runMapHooks()

void G3D::GLPixelTransferBuffer::runMapHooks ( ) const

inline

Executes the callback function previously set by registerMapHook().

This is called for you when you call map(). You must explicitly call this if you call glBindBuffer (for example, as is done in Texture::update()).

◆ runReallocateHooks()

void G3D::GLPixelTransferBuffer::runReallocateHooks ( ) const

inline

Executes the callback function previously set by registerReallocationHook().

You should call this whenever you resize or reallocate this buffer in GL.

◆ setData()

virtual void G3D::GLPixelTransferBuffer::setData ( const void * data )

overridevirtual

Overwrite the current contents with data.

Cannot call while mapped.

Implements G3D::PixelTransferBuffer.

◆ size()

size_t G3D::PixelTransferBuffer::size ( ) const

inlineinherited

Returns entire size of pixel data in bytes.

◆ stride()

size_t G3D::PixelTransferBuffer::stride ( ) const

inlineinherited

Returns size of each row of pixel data in bytes.

◆ unbindRead()

void G3D::GLPixelTransferBuffer::unbindRead ( )

Unbind the current OpenGL GL_PIXEL_UNPACK_BUFFER.

Sets the G3D::Milestone on this buffer; it will not be readyToMap() until all GPU commands issued prior to unbind() have completed execution.

◆ unbindWrite()

void G3D::GLPixelTransferBuffer::unbindWrite ( )

Unbind the current OpenGL GL_PIXEL_PACK_BUFFER.

Sets the G3D::Milestone on this buffer; it will not be readyToMap() until all GPU commands issued prior to unbind() have completed execution.

◆ unmap() [1/2]

template<class T >

void G3D::PixelTransferBuffer::unmap ( const T *& setToNull ) const

inlineinherited

◆ unmap() [2/2]

virtual void G3D::GLPixelTransferBuffer::unmap ( ) const

overridevirtual

See also: G3D::BufferUnmapper

Implements G3D::PixelTransferBuffer.

◆ width()

int G3D::PixelTransferBuffer::width ( ) const

inlineinherited

Member Data Documentation

◆ m_depth

int G3D::PixelTransferBuffer::m_depth

protectedinherited

Referenced by G3D::PixelTransferBuffer::depth(), G3D::PixelTransferBuffer::pixelCount(), G3D::CPUPixelTransferBuffer::row(), G3D::PixelTransferBuffer::rowOffset(), and G3D::PixelTransferBuffer::size().

◆ m_format

const ImageFormat* G3D::PixelTransferBuffer::m_format

protectedinherited

Referenced by G3D::PixelTransferBuffer::format().

◆ m_glBufferID

unsigned int G3D::GLPixelTransferBuffer::m_glBufferID

protected

Referenced by glBufferID(), runMapHooks(), and runReallocateHooks().

◆ m_glUsageHint

uint32 G3D::GLPixelTransferBuffer::m_glUsageHint

protected

◆ m_height

int G3D::PixelTransferBuffer::m_height

protectedinherited

Referenced by G3D::PixelTransferBuffer::height(), G3D::PixelTransferBuffer::pixelCount(), G3D::CPUPixelTransferBuffer::row(), G3D::PixelTransferBuffer::rowOffset(), and G3D::PixelTransferBuffer::size().

◆ m_mapHook

shared_ptr<std::function<void(GLint)> > G3D::GLPixelTransferBuffer::m_mapHook

mutableprotected

Referenced by registerMapHook(), and runMapHooks().

◆ m_mappedPointer

void* G3D::PixelTransferBuffer::m_mappedPointer

mutableprotectedinherited

nullptr if not currently mapped.

◆ m_milestone

shared_ptr<Milestone> G3D::GLPixelTransferBuffer::m_milestone

protected

If this was created from data on the GPU, then m_milestone is the milestone that must be reached before the data can be memory mapped on the CPU.

◆ m_reallocateHook

shared_ptr<std::function<void(GLint)> > G3D::GLPixelTransferBuffer::m_reallocateHook

mutableprotected

Referenced by registerReallocationHook(), and runReallocateHooks().

◆ m_rowAlignment

size_t G3D::PixelTransferBuffer::m_rowAlignment

protectedinherited

Referenced by G3D::PixelTransferBuffer::rowAlignment().

◆ m_rowStride

size_t G3D::PixelTransferBuffer::m_rowStride

protectedinherited

Referenced by G3D::PixelTransferBuffer::rowOffset(), G3D::PixelTransferBuffer::size(), and G3D::PixelTransferBuffer::stride().

◆ m_width

int G3D::PixelTransferBuffer::m_width

protectedinherited

Referenced by G3D::PixelTransferBuffer::pixelCount(), and G3D::PixelTransferBuffer::width().

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ GLPixelTransferBuffer()

◆ ~GLPixelTransferBuffer()

Member Function Documentation

◆ bindAsShaderStorageBuffer()

◆ bindRead()

◆ bindWrite()

◆ copy()

◆ create()

◆ createShared()

◆ deleteAllBuffers()

◆ depth()

◆ format()

◆ getData()

◆ getGPUAddress()

◆ glBufferID()

◆ height()

◆ map()

◆ mapRead()

◆ mapReadWrite()

◆ mapWrite()

◆ ownsMemory()

◆ pixelCount()

◆ readyToMap()

◆ registerMapHook()

◆ registerReallocationHook()

◆ requiresGPUContext()

◆ resize()

◆ rowAlignment()

◆ rowOffset()

◆ runMapHooks()

◆ runReallocateHooks()

◆ setData()

◆ size()

◆ stride()

◆ unbindRead()

◆ unbindWrite()

◆ unmap() [1/2]

◆ unmap() [2/2]

◆ width()

Member Data Documentation

◆ m_depth

◆ m_format

◆ m_glBufferID

◆ m_glUsageHint

◆ m_height

◆ m_mapHook

◆ m_mappedPointer

◆ m_milestone

◆ m_reallocateHook

◆ m_rowAlignment

◆ m_rowStride

◆ m_width