Home | Namespaces | Hierarchy | Alphabetical List | Class list | Files | Namespace Members | Class members | File members
Public Member Functions | Protected Member Functions | Protected Attributes
resource::Buffer Class Reference

#include <Buffer.h>

Inheritance diagram for resource::Buffer:
render::IndexBuffer render::PixelBuffer render::VertexBuffer render::HardwareIndexBuffer render::MemoryIndexBuffer render::HardwarePixelBuffer render::MemoryPixelBuffer render::HardwareVertexBuffer render::MemoryVertexBuffer

List of all members.

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


Member Data Documentation

bool resource::Buffer::mIsLocked [protected]

Referenced by lock(), and updateFromShadow().

Referenced by lock(), and updateFromShadow().

Referenced by Buffer(), lock(), and updateFromShadow().

Referenced by Buffer(), and isSystemMemory().

Referenced by Buffer(), and getUsage().


The documentation for this class was generated from the following files:

The KG Game Engine
The KG Game Engine Documentation © 2006-2011 by Kat'Oun. Generated on Sat Jul 2 2011 00:50:09 by Doxygen (1.7.4)