Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | Related Pages

Buffer Class Reference

#include <buffer.h>

Inheritance diagram for Buffer:

Inheritance graph
[legend]
Collaboration diagram for Buffer:

Collaboration graph
[legend]
List of all members.

Detailed Description

Reference counted buffers.

Buffers can be stored in system RAM or in video RAM. A buffer of type DYNAMIC have a system RAM backing storage and are when used in a render primitive uploaded to video RAM if needed. A buffer of type STATIC have no system RAM storage, it is always stored in video RAM if present.

This allows sharing of video RAM among buffers with a total storage larger than the allocated video RAM segment, and buffers are "swapped out" on a least-recent-used scheme.

When a DYNAMIC buffer is used for rendering, first the dirty flag is checked (a WRITE lock to the buffer will cause the dirty flag to be set) and if set the buffer will update it's video RAM segment. This will also happen if the segment was invalidated (swapped out). If no segment present (or invalid) a new segment will be requested from the backend (which might cause other segments to be invalidated to make enough free space). The data is then uploaded to the video RAM segment.

The buffer upload policy determines when a buffer will be uploaded to the video RAM segment. Possible values are ONUNLOCK for uploading directly after a WRITE lock is released, ONRENDER for uploading when used in a Render() call to the device, or ONFLUSH for uploading during render pipeline flush.

Buffers are by default (the default policy) set to uploaded on render if the buffer is dirty (a WRITE lock was held during the frame). If the policy is to upload on unlock, but the flag NOUPLOAD was given to the lock method for a WRITE lock it will cause the dirty flag to be set and upload-on-render being used. The flag FORCEUPLOAD will force the upload to be made on unlock, regardless of the policy.

A buffer of type STATIC that has a READPRIORITIZED and/or WRITEPRIORITIZED type set might also get a system RAM backing store. The same argument for upload-on-render and upload-on-unlock as above applies, with the exception that the video RAM segment of a STATIC buffer will never be invalidated.

A buffer with type NOREADWRITE set can be optimized by the backend by not allowing the buffer to be locked for read or write access. This means you must pass a data pointer to the buffer creation call.

Finally, a buffer of type NORENDER can be optimized by the backend to never use any video RAM resources. This buffer type must NEVER be sent for rendering.

Author:
Mattias Jansson (mattias@realityrift.com)


Public Types

enum  BUFFERTYPE {
  DYNAMIC = 0x00000000, STATIC = 0x00000001, READPRIORITIZED = 0x00000002, WRITEPRIORITIZED = 0x00000004,
  NOREADWRITE = 0x00000008, NORENDER = 0x00000010, NORMAL = ( DYNAMIC | READPRIORITIZED | WRITEPRIORITIZED )
}
 Buffer type identifiers. Any combination of the flags is valid. More...

enum  BUFFERUPLOADPOLICY { ONUNLOCK, ONRENDER, ONFLUSH }
 Upload policy identifiers. More...

enum  BUFFERLOCK { READ = 1, WRITE = 2, NOUPLOAD = 4, FORCEUPLOAD = 8 }
 Lock type identifiers. More...


Public Member Functions

 Buffer (unsigned int uiType)
virtual ~Buffer ()
bool Lock (unsigned int uiLockType)
void Unlock ()
virtual void Upload ()
bool IsLocked () const
bool IsDirty () const
unsigned int GetType () const
unsigned int GetNumAllocated () const
unsigned int GetNumElements () const
void SetNumElements (unsigned int uiNumElements)
void IncRef ()
void DecRef ()
int GetRefCount () const

Static Public Member Functions

std::string GetTypeAsString (unsigned int uiType)
unsigned int GetTypeFromString (std::string const &strType)

Static Public Attributes

BUFFERUPLOADPOLICY s_eUploadPolicy

Protected Member Functions

virtual bool AcquireLock ()=0
virtual void ReleaseLock ()=0

Protected Attributes

unsigned int m_uiType
unsigned int m_uiLock
bool m_bDirty
unsigned int m_uiNumAllocated
unsigned int m_uiNumCurrent


Member Enumeration Documentation

enum BUFFERTYPE
 

Buffer type identifiers. Any combination of the flags is valid.

Enumeration values:
DYNAMIC  Dynamic buffer with system RAM backing store
STATIC  AGP or VRAM storage if possible
READPRIORITIZED  Prioritize read access
WRITEPRIORITIZED  Prioritize write accesss
NOREADWRITE  Buffer that can never be read from or written to, must pass data pointer to ctor
NORENDER  Buffer that must never be sent for rendering, guaranteed to not use video RAM resources
NORMAL  Default type

enum BUFFERUPLOADPOLICY
 

Upload policy identifiers.

Enumeration values:
ONUNLOCK  Upload after WRITE lock released
ONRENDER  Upload when used in render primitive queued for render
ONFLUSH  Upload when used in render pipeline flush

enum BUFFERLOCK
 

Lock type identifiers.

Enumeration values:
READ  Read access
WRITE  Write access (implies read access)
NOUPLOAD  No upload on unlock, will cause upload-on-render
FORCEUPLOAD  Force upload on unlock


Constructor & Destructor Documentation

Buffer unsigned int  uiType  )  [inline]
 

virtual ~Buffer  )  [inline, virtual]
 


Member Function Documentation

virtual bool AcquireLock  )  [protected, pure virtual]
 

Called by Lock. Lock type member m_uiLock has been set at this point

Returns:
true if lock successful, false if not

Implemented in PolygonStripBuffer, PolygonBuffer, and VertexBuffer.

virtual void ReleaseLock  )  [protected, pure virtual]
 

Called by Unlock when a lock should be released. Lock type member m_uiLock is still holding lock type at this point.

Implemented in PolygonStripBuffer, PolygonBuffer, and VertexBuffer.

bool Lock unsigned int  uiLockType  )  [inline]
 

Lock buffer for read/write operation

Parameters:
uiLockType Lock type
Returns:
true if lock acquired, false if failed (already locked)

void Unlock  )  [inline]
 

Unlock buffer

virtual void Upload  )  [inline, virtual]
 

Upload data to backing store, reset dirty flag

bool IsLocked  )  const [inline]
 

Returns:
true if buffer is locked, false if not

bool IsDirty  )  const [inline]
 

Returns:
true if buffer is dirty, false if not

unsigned int GetType  )  const [inline]
 

Returns:
Buffer type

unsigned int GetNumAllocated  )  const [inline]
 

Returns:
Number of allocated elements

unsigned int GetNumElements  )  const [inline]
 

Returns:
Number of currently used elements

void SetNumElements unsigned int  uiNumElements  )  [inline]
 

Set new count of currently used elements

Parameters:
uiNumElements Number of elements currently used, will be clamped to [0,numallocated] range

std::string GetTypeAsString unsigned int  uiType  )  [static]
 

Get buffer type as string

Parameters:
uiType Type identifier
Returns:
Type as string

unsigned int GetTypeFromString std::string const &  strType  )  [static]
 

Get buffer type from string

Parameters:
strType String type identifier
Returns:
Type id

void IncRef  )  [inline, inherited]
 

Increase reference count

void DecRef  )  [inline, inherited]
 

Decrease reference count and garbage collect if 0

int GetRefCount  )  const [inline, inherited]
 

Returns:
Current reference count


Member Data Documentation

unsigned int m_uiType [protected]
 

Buffer type

unsigned int m_uiLock [protected]
 

Current lock type held

bool m_bDirty [protected]
 

Dirty flag

unsigned int m_uiNumAllocated [protected]
 

Number of allocated elements

unsigned int m_uiNumCurrent [protected]
 

Number of currently used elements

BUFFERUPLOADPOLICY s_eUploadPolicy [static]
 

Buffer upload policy


The documentation for this class was generated from the following file:
Generated on Wed Jan 21 14:21:10 2004 for NeoEngine by doxygen 1.3.5