Base class for transfering arrays of pixels between major classes, generalized over CPU arrays, memory-mapped files, and OpenGL Pixel Buffer Objects. More...

Inherits G3D::ReferenceCountedObject.

Inherited by G3D::CPUPixelTransferBuffer, and G3D::GLPixelTransferBuffer.

Public Member Functions
virtual	~PixelTransferBuffer ()

int	depth () const

const ImageFormat *	format () const

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

int	height () const

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

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

virtual void *	mapWrite ()=0
	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 =0
	If true, mapReadWrite, mapRead, and mapWrite will return immediately. More...

virtual bool	requiresGPUContext () const =0
	If true, then readyToMap(), mapRead(), mapWrite(), mapReadWrite(), and unmap() can only be invoked on a thread that currently has an active OpenGL context. 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...

virtual void	setData (const void *data)=0
	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...

virtual void	unmap () const =0

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

int	width () const

Protected Member Functions
	PixelTransferBuffer (const ImageFormat *format, int width, int height, int depth, int rowAlignment)

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

int	m_height

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

size_t	m_rowAlignment

size_t	m_rowStride

int	m_width

Detailed Description

Base class for transfering arrays of pixels between major classes, generalized over CPU arrays, memory-mapped files, and OpenGL Pixel Buffer Objects.

Beware that because the memory accessed through mapRead mapWrite mapReadWrite may be memory mapped, it may not be cached in the same was as general CPU memory, and thus random access and mixed read-write may have unexpected performance characteristics.

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

Constructor & Destructor Documentation

◆ PixelTransferBuffer()

G3D::PixelTransferBuffer::PixelTransferBuffer	(	const ImageFormat *	format,
		int	width,
		int	height,
		int	depth,
		int	rowAlignment
	)

protected

◆ ~PixelTransferBuffer()

virtual G3D::PixelTransferBuffer::~PixelTransferBuffer ( )

virtual

Member Function Documentation

◆ 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>.

◆ depth()

int G3D::PixelTransferBuffer::depth ( ) const

inline

◆ format()

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

inline

◆ getData()

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

pure virtual

Read back the current contents to data.

Cannot call while mapped.

Implemented in G3D::GLPixelTransferBuffer, and G3D::CPUPixelTransferBuffer.

◆ height()

int G3D::PixelTransferBuffer::height ( ) const

inline

◆ mapRead()

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

pure virtual

Obtain a pointer for read-only access.

See also: mapReadWrite, mapWrite, unmap

Implemented in G3D::GLPixelTransferBuffer, and G3D::CPUPixelTransferBuffer.

◆ mapReadWrite()

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

pure virtual

Obtain a pointer for general access.

See also: mapRead, mapWrite, unmap

Implemented in G3D::GLPixelTransferBuffer, and G3D::CPUPixelTransferBuffer.

◆ mapWrite()

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

pure virtual

Obtain a pointer for write-only access.

See also: mapRead, mapReadWrite, unmap

Implemented in G3D::GLPixelTransferBuffer, and G3D::CPUPixelTransferBuffer.

◆ ownsMemory()

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

inlinevirtual

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

inline

◆ readyToMap()

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

pure virtual

If true, mapReadWrite, mapRead, and mapWrite will return immediately.

This is always true for the base class but subclasses that map Pixel Buffer Objects and files may have a delay between when they are constructed and when they are available for mapping. The standard usage in those cases is to have the GL thread check if data is ready to map, and if not, then wait until the next frame to perform the mapping.

Implemented in G3D::GLPixelTransferBuffer, and G3D::CPUPixelTransferBuffer.

◆ requiresGPUContext()

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

pure virtual

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.

Implemented in G3D::GLPixelTransferBuffer, and G3D::CPUPixelTransferBuffer.

◆ rowAlignment()

size_t G3D::PixelTransferBuffer::rowAlignment ( ) const

inline

Returns alignment of each row of pixel data in bytes.

◆ rowOffset()

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

inline

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().

◆ setData()

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

pure virtual

Overwrite the current contents with data.

Cannot call while mapped.

Implemented in G3D::GLPixelTransferBuffer, and G3D::CPUPixelTransferBuffer.

◆ size()

size_t G3D::PixelTransferBuffer::size ( ) const

inline

Returns entire size of pixel data in bytes.

◆ stride()

size_t G3D::PixelTransferBuffer::stride ( ) const

inline

Returns size of each row of pixel data in bytes.

◆ unmap() [1/2]

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

pure virtual

See also: G3D::BufferUnmapper

Implemented in G3D::GLPixelTransferBuffer, and G3D::CPUPixelTransferBuffer.

Referenced by unmap().

◆ unmap() [2/2]

template<class T >

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

inline

◆ width()

int G3D::PixelTransferBuffer::width ( ) const

inline

Member Data Documentation

◆ m_depth

int G3D::PixelTransferBuffer::m_depth

protected

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

◆ m_format

const ImageFormat* G3D::PixelTransferBuffer::m_format

protected

Referenced by format().

◆ m_height

int G3D::PixelTransferBuffer::m_height

protected

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

◆ m_mappedPointer

void* G3D::PixelTransferBuffer::m_mappedPointer

mutableprotected

nullptr if not currently mapped.

◆ m_rowAlignment

size_t G3D::PixelTransferBuffer::m_rowAlignment

protected

Referenced by rowAlignment().

◆ m_rowStride

size_t G3D::PixelTransferBuffer::m_rowStride

protected

Referenced by rowOffset(), size(), and stride().

◆ m_width

int G3D::PixelTransferBuffer::m_width

protected

Referenced by pixelCount(), and width().

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ PixelTransferBuffer()

◆ ~PixelTransferBuffer()

Member Function Documentation

◆ createShared()

◆ depth()

◆ format()

◆ getData()

◆ height()

◆ mapRead()

◆ mapReadWrite()

◆ mapWrite()

◆ ownsMemory()

◆ pixelCount()

◆ readyToMap()

◆ requiresGPUContext()

◆ rowAlignment()

◆ rowOffset()

◆ setData()

◆ size()

◆ stride()

◆ unmap() [1/2]

◆ unmap() [2/2]

◆ width()

Member Data Documentation

◆ m_depth

◆ m_format

◆ m_height

◆ m_mappedPointer

◆ m_rowAlignment

◆ m_rowStride

◆ m_width