#include <Buffer.h>

Inheritance diagram for resource::Buffer:

Public Member Functions
	Buffer (BufferUsage usage, bool systemMemory, bool useShadowBuffer)
virtual void	copyData (Buffer &srcBuffer, u32 srcOffset, u32 dstOffset, u32 length, bool discardWholeBuffer=false)
u32	getSizeInBytes () const
	Returns the size of this buffer in bytes.
BufferUsage	getUsage () const
	Returns the Usage flags with which this buffer was created.
bool	isLocked () const
	Returns whether or not this buffer is currently locked.
bool	isSystemMemory () const
	Returns whether this buffer is held in system memory.
void *	lock (BufferLocking options)
virtual void *	lock (u32 offset, u32 length, BufferLocking options)
virtual void	readData (u32 offset, u32 length, void *pDest)=0
virtual void	unlock ()
virtual void	updateFromShadow ()
	Updates the real buffer from the shadow buffer, if required.
virtual void	writeData (u32 offset, u32 length, const void *pSource, bool discardWholeBuffer=false)=0
virtual	~Buffer ()
Protected Member Functions
virtual void *	lockImpl (u32 offset, u32 length, BufferLocking options)=0
	Internal implementation of lock().
virtual void	unlockImpl ()=0
	Internal implementation of unlock().
Protected Attributes
bool	mIsLocked
u32	mLockSize
u32	mLockStart
Buffer *	mShadowBuffer
bool	mShadowUpdated
u32	mSizeInBytes
bool	mSystemMemory
BufferUsage	mUsage
bool	mUseShadowBuffer

Detailed Description

Abstract class defining common features of buffers. A 'buffer' is any area of memory held inside or outside of core system ram. Can refer to video ram or other memory areas such as sound card memory, custom co-processor memory etc, called 'hardware buffers'.

Buffers have the ability to be 'shadowed' in system memory, this is because the kinds of access allowed on hardware buffers is not always as flexible as that allowed for areas of system memory - for example it is often either impossible, or extremely undesirable from a performance standpoint to read from a hardware buffer; when writing to hardware buffers, you should also write every byte and do it sequentially. In situations where this is too restrictive, it is possible to create a hardware, write-only buffer (the most efficient kind) and to back it with a system memory 'shadow' copy which can be read and updated arbitrarily.

Constructor & Destructor Documentation

resource::Buffer::Buffer	(	BufferUsage	usage,
		bool	systemMemory,
		bool	useShadowBuffer
	)

References resource::BU_DYNAMIC, resource::BU_DYNAMIC_WRITE_ONLY, resource::BU_STATIC, resource::BU_STATIC_WRITE_ONLY, mIsLocked, mShadowBuffer, mShadowUpdated, mSystemMemory, mUsage, and mUseShadowBuffer.

resource::Buffer::~Buffer ( ) [virtual]

Member Function Documentation

void resource::Buffer::copyData	(	Buffer &	srcBuffer,
		u32	srcOffset,
		u32	dstOffset,
		u32	length,
		bool	discardWholeBuffer = `false`
	)		`[virtual]`

Copy data from another buffer into this one.

Note that the source buffer must not be created with the usage BU_WRITE_ONLY otherwise this will fail.

Parameters:

srcBuffer,:	The buffer from which to read the copied data
srcOffset,:	Offset in the source buffer at which to start reading
dstOffset,:	Offset in the destination buffer to start writing
length,:	Length of the data to copy, in bytes.
discardWholeBuffer,:	If true, will discard the entire contents of this buffer before copying

References resource::BL_READ_ONLY, lock(), unlock(), and writeData().

u32 resource::Buffer::getSizeInBytes ( ) const

Returns the size of this buffer in bytes.

References mSizeInBytes.

BufferUsage resource::Buffer::getUsage ( ) const

Returns the Usage flags with which this buffer was created.

References mUsage.

bool resource::Buffer::isLocked ( ) const

Returns whether or not this buffer is currently locked.

References isLocked(), mIsLocked, mShadowBuffer, and mUseShadowBuffer.

Referenced by isLocked(), lock(), and unlock().

bool resource::Buffer::isSystemMemory ( ) const

Returns whether this buffer is held in system memory.

References mSystemMemory.

void * resource::Buffer::lock ( BufferLocking options )

Lock the entire buffer for (potentially) reading / writing.

Parameters:

options,: Locking options

Returns:: Pointer to the locked memory

References lock(), and mSizeInBytes.

void * resource::Buffer::lock	(	u32	offset,
		u32	length,
		BufferLocking	options
	)		`[virtual]`

Lock the buffer for (potentially) reading / writing.

Parameters:

offset,:	The byte offset from the start of the buffer to lock
length,:	The size of the area to lock, in bytes
options,:	Locking options

Returns:: Pointer to the locked memory

Reimplemented in render::MemoryIndexBuffer, render::MemoryPixelBuffer, and render::MemoryVertexBuffer.

References resource::BL_READ_ONLY, isLocked(), lock(), lockImpl(), mIsLocked, mLockSize, mLockStart, mShadowBuffer, mShadowUpdated, and mUseShadowBuffer.

Referenced by render::TextOverlay::allocateMemory(), copyData(), render::DebugRenderable::initializeGeometry(), render::PanelOverlay::initializeImpl(), lock(), render::TextOverlay::updatePositionBinding(), render::PanelOverlay::updatePositionBinding(), and render::PanelOverlay::updateTextureBinding().

virtual void* resource::Buffer::lockImpl	(	u32	offset,
		u32	length,
		BufferLocking	options
	)		`[protected, pure virtual]`

Internal implementation of lock().

Implemented in render::MemoryIndexBuffer, render::MemoryPixelBuffer, and render::MemoryVertexBuffer.

Referenced by lock(), and updateFromShadow().

virtual void resource::Buffer::readData	(	u32	offset,
		u32	length,
		void *	pDest
	)		`[pure virtual]`

Reads data from the buffer and places it in the memory pointed to by pDest.

Parameters:

offset,:	The byte offset from the start of the buffer to read
length,:	The size of the area to read, in bytes
pDest,:	The area of memory in which to place the data, must be large enough to accommodate the data!

Implemented in render::MemoryIndexBuffer, render::MemoryPixelBuffer, and render::MemoryVertexBuffer.

void resource::Buffer::unlock ( ) [virtual]

Releases the lock on this buffer.

Locking and unlocking a buffer can, in some rare circumstances such as switching video modes whilst the buffer is locked, corrupt the contents of a buffer. This is pretty rare, but if it occurs, this method will throw an exception, meaning you must re-upload the data. Note that using the 'read' and 'write' forms of updating the buffer does not suffer from this problem, so if you want to be 100% sure your data will not be lost, use the 'read' and 'write' forms instead.

Reimplemented in render::MemoryIndexBuffer, render::MemoryPixelBuffer, and render::MemoryVertexBuffer.

References isLocked(), mIsLocked, mShadowBuffer, mUseShadowBuffer, unlock(), unlockImpl(), and updateFromShadow().

Referenced by render::TextOverlay::allocateMemory(), copyData(), render::DebugRenderable::initializeGeometry(), render::PanelOverlay::initializeImpl(), unlock(), render::TextOverlay::updatePositionBinding(), render::PanelOverlay::updatePositionBinding(), and render::PanelOverlay::updateTextureBinding().

virtual void resource::Buffer::unlockImpl ( ) [protected, pure virtual]

Internal implementation of unlock().

Implemented in render::MemoryIndexBuffer, render::MemoryPixelBuffer, and render::MemoryVertexBuffer.

Referenced by unlock(), and updateFromShadow().

void resource::Buffer::updateFromShadow ( ) [virtual]

Updates the real buffer from the shadow buffer, if required.

References resource::BL_DISCARD, resource::BL_NORMAL, resource::BL_READ_ONLY, lockImpl(), mLockSize, mLockStart, mShadowBuffer, mShadowUpdated, mSizeInBytes, mUseShadowBuffer, and unlockImpl().

Referenced by unlock().

virtual void resource::Buffer::writeData	(	u32	offset,
		u32	length,
		const void *	pSource,
		bool	discardWholeBuffer = `false`
	)		`[pure virtual]`

Writes data to the buffer from an area of system memory; note that you must ensure that your buffer is big enough.

Parameters:

offset,:	The byte offset from the start of the buffer to start writing
length,:	The size of the data to write to, in bytes
pSource,:	The source of the data to be written
discardWholeBuffer,:	If true, this allows the driver to discard the entire buffer when writing, such that DMA stalls can be avoided; use if you can.

Implemented in render::MemoryIndexBuffer, render::MemoryPixelBuffer, and render::MemoryVertexBuffer.

Referenced by copyData().