G3D::VertexBuffer Class Reference

A block of GPU memory within which G3D::AttributeArrays for vertex, texcoord, normal, etc. More...

Inherits G3D::ReferenceCountedObject.

Public Types
typedef shared_ptr< class VertexBuffer >	Ref
enum	UsageHint {   WRITE_ONCE,   WRITE_EVERY_FEW_FRAMES,   WRITE_EVERY_FRAME }
	These values are hints. More...

Public Member Functions
	~VertexBuffer ()
size_t	allocatedSize () const
uint64	currentGeneration () const
void	finish ()
	Blocks the CPU until all rendering calls referencing this area have completed. More...
size_t	freeSize () const
void *	openGLBasePointer () const
	Provided for breaking the VertexBuffer abstraction; use G3D::AttributeArray and G3D::RenderDevice in general. More...
uint32	openGLVertexBufferObject () const
	Provided for breaking the VertexBuffer abstraction; use G3D::AttributeArray and G3D::RenderDevice in general. More...
size_t	peakAllocatedSize () const
void	reset ()
	Finishes, then frees all AttributeArray memory inside this area. More...
size_t	totalSize () const
UsageHint	usageHint () const

Static Public Member Functions
static void	cleanupAllVertexBuffers ()
	Releases all VertexBuffers. More...
static shared_ptr< VertexBuffer >	create (size_t s, UsageHint h=WRITE_EVERY_FRAME)
	You should always create your VertexBuffers at least 8 bytes larger than needed for each individual AttributeArray because VertexBuffer tries to align AttributeArray starts in memory with dword boundaries. More...
static void	resetCacheMarkers ()
static size_t	sizeOfAllVertexBuffersInMemory ()
	Returns the total m_size of all VertexBuffers allocated. More...

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

Friends
class	AttributeArray
class	RenderDevice

Detailed Description

A block of GPU memory within which G3D::AttributeArrays for vertex, texcoord, normal, etc.

arrays or index lists can be allocated.

Allocate a VertexBuffer, then allocate AttributeArrays and IndexStreams within it. For example:

// Allocate on CPU
Array<Vector3>   cpuVertex;
Array<Vector2>   cpuTexCoord;
Array<int>       cpuIndex;

... initialize ...

// Upload to GPU
shared_ptr<VertexBuffer> vbuffer = VertexBuffer::create((sizeof(Vector3) + sizeof(Vector2)) * cpuVertex.size() + sizeof(int) * cpuIndex.size());
AttributeArray gpuVertex   = AttributeArray(cpuVertex, vbuffer);
AttributeArray gpuTexCoord = AttributeArray(cpuTexCoord, vbuffer);
IndexStream gpuIndex       = IndexStream(cpuIndex, vbuffer);

VertexBuffers are garbage collected: when no pointers remain to AttributeArrays inside it or the VertexBuffer itself, it will automatically be reclaimed by the system.

You cannot mix pointers from different VertexBuffers when rendering. For example, if the vertex AttributeArray is in one VertexBuffer, the normal AttributeArray and color AttributeArray must come from the same area.

This class corresponds closely to the OpenGL Vertex Buffer Object http://oss.sgi.com/projects/ogl-sample/registry/ARB/vertex_buffer_object.txt http://developer.nvidia.com/docs/IO/8230/GDC2003_OGL_BufferObjects.ppt

Member Typedef Documentation

Ref

typedef shared_ptr<class VertexBuffer> G3D::VertexBuffer::Ref

Member Enumeration Documentation

UsageHint

enum G3D::VertexBuffer::UsageHint

These values are hints.

Your program will work correctly regardless of which you use, but using the appropriate value lets the renderer optimize for your useage patterns and can increase performance.

Use WRITE_EVERY_FRAME if you write at least once per frame (e.g. software animation).

Use WRITE_EVERY_FEW_FRAMES if you write to the area as part of the rendering loop, but not every frame (e.g. impostors, deformable data).

Use WRITE_ONCE if you do not write to the area inside the rendering loop (e.g. rigid bodies loaded once at the beginning of a game level).
This does not mean you can't write multiple times to the area, just that writing might be very slow compared to rendering.

Correspond to OpenGL hints: WRITE_ONCE : GL_STATIC_DRAW_ARB WRITE_EVERY_FRAME : GL_STREAM_DRAW_ARB WRITE_EVERY_FEW_FRAMEs : DYNAMIC_DRAW_ARB

Enumerator
WRITE_ONCE
WRITE_EVERY_FEW_FRAMES
WRITE_EVERY_FRAME

Constructor & Destructor Documentation

~VertexBuffer()

G3D::VertexBuffer::~VertexBuffer

(

)

Member Function Documentation

allocatedSize()

size_t G3D::VertexBuffer::allocatedSize ( ) const

inline

cleanupAllVertexBuffers()

static void G3D::VertexBuffer::cleanupAllVertexBuffers ( )

static

Releases all VertexBuffers.

Called before shutdown by RenderDevice.

create()

static shared_ptr<VertexBuffer> G3D::VertexBuffer::create ( size_t  s, UsageHint  h = WRITE_EVERY_FRAME  )

static

You should always create your VertexBuffers at least 8 bytes larger than needed for each individual AttributeArray because VertexBuffer tries to align AttributeArray starts in memory with dword boundaries.

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

currentGeneration()

uint64 G3D::VertexBuffer::currentGeneration ( ) const

inline

finish()

void G3D::VertexBuffer::finish

(

)

Blocks the CPU until all rendering calls referencing this area have completed.

freeSize()

size_t G3D::VertexBuffer::freeSize ( ) const

inline

openGLBasePointer()

void* G3D::VertexBuffer::openGLBasePointer ( ) const

inline

Provided for breaking the VertexBuffer abstraction; use G3D::AttributeArray and G3D::RenderDevice in general.

When using system memory, this is a pointer to the beginning of the system memory block in which data is stored. Null when using VBO.

openGLVertexBufferObject()

uint32 G3D::VertexBuffer::openGLVertexBufferObject ( ) const

inline

Provided for breaking the VertexBuffer abstraction; use G3D::AttributeArray and G3D::RenderDevice in general.

When using the OpenGL vertex buffer API, this is the underlying OpenGL vertex buffer object. It is zero when using system memory. The caller cannot control whether VBO is used or not; G3D selects the best method automatically.

peakAllocatedSize()

size_t G3D::VertexBuffer::peakAllocatedSize ( ) const

inline

reset()

void G3D::VertexBuffer::reset

(

)

Finishes, then frees all AttributeArray memory inside this area.

resetCacheMarkers()

static void G3D::VertexBuffer::resetCacheMarkers ( )

static

sizeOfAllVertexBuffersInMemory()

static size_t G3D::VertexBuffer::sizeOfAllVertexBuffersInMemory ( )

inlinestatic

Returns the total m_size of all VertexBuffers allocated.

Note that not all will be in video memory, and some will be backed by main memory even if nominally stored in video memory, so the total size may exceed the video memory size.

totalSize()

size_t G3D::VertexBuffer::totalSize ( ) const

inline

usageHint()

UsageHint G3D::VertexBuffer::usageHint ( ) const

inline

Friends And Related Function Documentation

AttributeArray

friend class AttributeArray

friend

RenderDevice

friend class RenderDevice

friend