A block of GPU memory storing a stream of vector data (e.g., vertices, normals, texture coordinates) More...

Public Member Functions
	VertexRange ()
	Creates an invalid VertexRange.

	VertexRange (size_t numBytes, VertexBufferRef _area)
	Creates a VertexRange that acts as a pointer to a block of memory.

template<class T >
	VertexRange (const T *sourcePtr, int _numElements, VertexBufferRef _area)
	Uploads memory from the CPU to the GPU.

template<class T >
	VertexRange (const Array< T > &source, VertexBufferRef _area)

template<class T >
	VertexRange (const T *srcPtr, size_t _numElements, size_t srcStride, VertexRange dstPtr, size_t dstOffset, size_t dstStride)
	Create an interleaved array within an existing VertexRange and upload data to it.

template<class T >
	VertexRange (const T &ignored, int _numElements, VertexRange dstPtr, size_t dstOffset, size_t dstStride)
	Create an interleaved array within an existing VertexRange, but do not upload data to it.

template<class T >
	VertexRange (const T &ignored, int _numElements, VertexBuffer::Ref dstPtr)
	Allocate a vertex range within a vertex buffer with no offset, but do not upload data to it.

template<class T >
	VertexRange (const Array< T > &source, VertexRange dstPtr, size_t dstOffset, size_t dstStride)

VertexBuffer::Ref	area ()

VertexBuffer::Ref G3D_DEPRECATED	area () const

VertexBuffer::Ref	buffer ()
	The G3D::VertexBuffer containing this VertexRange.

VertexBuffer::Ref	buffer () const
	The G3D::VertexBuffer containing this VertexRange.

size_t	elementSize () const


uint64	generation () const

void *	mapBuffer (GLenum permissions)
	Return a pointer to CPU-addressable memory for this VertexRange.

size_t	maxSize () const
	Maximum size that can be loaded via update into this VertexRange.

bool	normalizedFixedPoint ()
	True if this vertex is storing numbers in normalized fixed point format.

bool	operator== (const VertexRange &other) const

template<class T >
void	set (int index, const T &value)
	Overwrites a single element of an existing array without changing the number of elements.

void	setNormalizedFixedPoint (bool b)

int	size () const
	Number of elements in this array (not byte size!)

void *	startAddress ()
	For VBO_MEMORY, this is the offset.

size_t	stride () const


VertexBuffer::Type	type () const

GLenum	underlyingRepresentation () const

void	unmapBuffer ()
	Release CPU addressable memory previously returned by mapBuffer.

template<class T >
void	update (const T *sourcePtr, int _numElements)

template<class T >
void	update (const Array< T > &source)
	Overwrites existing data with data of the same size or smaller.

bool	valid () const
	Returns true if this VertexRange can be used for rendering (i.e., contains data and the parent VertexBuffer has not been reset).

Static Public Member Functions
template<class T1 , class T2 , class T3 , class T4 , class T5 >
static void	createInterleaved (const Array< T1 > &src1, VertexRange &var1, const Array< T2 > &src2, VertexRange &var2, const Array< T3 > &src3, VertexRange &var3, const Array< T4 > &src4, VertexRange &var4, const Array< T5 > &src5, VertexRange &var5, VertexBufferRef area)
	Creates five interleaved VertexRange arrays simultaneously.

template<class T1 , class T2 , class T3 , class T4 >
static void	createInterleaved (const Array< T1 > &src1, VertexRange &var1, const Array< T2 > &src2, VertexRange &var2, const Array< T3 > &src3, VertexRange &var3, const Array< T4 > &src4, VertexRange &var4, VertexBufferRef area)

template<class T1 , class T2 , class T3 , class T4 , class T5 >
static void	updateInterleaved (const Array< T1 > &src1, VertexRange &var1, const Array< T2 > &src2, VertexRange &var2, const Array< T3 > &src3, VertexRange &var3, const Array< T4 > &src4, VertexRange &var4, const Array< T5 > &src5, VertexRange &var5)
	Update a set of interleaved arrays.

template<class T1 , class T2 , class T3 , class T4 >
static void	updateInterleaved (const Array< T1 > &src1, VertexRange &var1, const Array< T2 > &src2, VertexRange &var2, const Array< T3 > &src3, VertexRange &var3, const Array< T4 > &src4, VertexRange &var4)

Friends
class	RenderDevice

class	Shader

Detailed Description

A block of GPU memory storing a stream of vector data (e.g., vertices, normals, texture coordinates)

A pointer to a "Vertex Arrray" of data (e.g., vertices, colors, or normals) in video memory.

A VertexRange is just a pointer, so it is safe to copy these (the pointer will be copied, not the video memory).

There is no destructor because the referenced memory is freed when the parent VertexBuffer is reset or freed.

A VertexRange is normally a statically typed fixed-length array of a Vector or Color class, however it is possible to make a "void" array with the constructor that does not take an array, and then fill it with data to create interleaved or structure arrays. Interleaved arrays are 2x - 3x as fast as non-interleaved ones for vertex-limited programs.

Constructor & Destructor Documentation

G3D::VertexRange::VertexRange ( )

Creates an invalid VertexRange.

G3D::VertexRange::VertexRange	(	size_t	numBytes,
		VertexBufferRef	_area
	)

Creates a VertexRange that acts as a pointer to a block of memory.

This block of memory can then be used with VertexRange::VertexRange() to upload interleaved data.

template<class T >

G3D::VertexRange::VertexRange	(	const T *	sourcePtr,
		int	_numElements,
		VertexBufferRef	_area
	)

inline

Uploads memory from the CPU to the GPU.

The element type is inferred from the pointer type by the preprocessor. Sample usage:

// Once at the beginning of the program
VertexBufferRef dataArea  = VertexBuffer::create(5 * 1024 * 1024);
VertexBufferRef indexArea = VertexBuffer::create(1024 * 1024, VertexBuffer::WRITE_EVERY_FRAME, VertexBuffer::INDEX);
//----------
// Store data in main memory
Array<Vector3> vertexArrayCPU;
Array<int>     indexArrayCPU;
//... fill out vertex & index arrays
//------------
// Upload to graphics card whenever CPU data changes
area.reset();
VertexRange vertexVARGPU(vertexArrayCPU, dataArea);
VertexRange indexVARGPU(indexArrayCPU, indexArea);
//------------
// Render 
renderDevice->beginIndexedPrimitives();
{
    renderDevice->setVertexArray(varray);
    renderDevice->sendIndices(PrimitiveType::TRIANGLES, indexVARGPU);
}
renderDevice->endIndexedPrimitives();

Parameters

sourcePtr The type of the data is determined from this. If NULL, no data is actually uploaded...but you must provide a properly typed pointer, e.g., (uint16*)(NULL).

template<class T >

G3D::VertexRange::VertexRange	(	const Array< T > &	source,
		VertexBufferRef	_area
	)

inline

template<class T >

G3D::VertexRange::VertexRange	(	const T *	srcPtr,
		size_t	_numElements,
		size_t	srcStride,
		VertexRange	dstPtr,
		size_t	dstOffset,
		size_t	dstStride
	)

inline

Create an interleaved array within an existing VertexRange and upload data to it.

Upload _numElements values from sourcePtr on the CPU to dstPtr on the GPU.

Parameters

srcStride	If non-zero, this is the spacing between sequential elements in bytes. It may be negative.
dstOffset	Offset in bytes from the head of dstPtr. e.g., to upload starting after the 2nd byte, set `dstOffset = 2`.
dstStride	If non-zero, this is the spacing between sequential elements of T in dstPtr. e.g., to upload every other Vector3, use `dstStride = sizeof(Vector3) * 2`. May not be negative.

template<class T >

G3D::VertexRange::VertexRange	(	const T &	ignored,
		int	_numElements,
		VertexRange	dstPtr,
		size_t	dstOffset,
		size_t	dstStride
	)

inline

Create an interleaved array within an existing VertexRange, but do not upload data to it.

    Data can later be uploaded by update() or mapBuffer().

    Example:
    <PRE>
       G3D_BEGIN_PACKED_CLASS
       struct Packed {
           Vector3   vertex;
           Vector2   texcoord;
       }
       G3D_END_PACKED_CLASS

       ...

       int stride = sizeof(Vector3) + sizeof(Vector2);
       int totalSize = stride * N;

       VertexRange interleavedBlock(totalSize, area);

       VertexRange vertex(Vector3() N, interleavedBlock, 0, stride);
       VertexRange texcoord(Vector2(), N, interleavedBlock, sizeof(Vector3), stride);

       Packed* ptr = (Packed*)interleavedBlock.mapBuffer(GL_WRITE_ONLY);

... write to elements of ptr ... interleavedBlock.unmapBuffer();

Parameters

dstStride If non-zero, this is the spacing between sequential elements of T in dstPtr. e.g., to upload every other Vector3, use dstStride = sizeof(Vector3) * 2. May not be negative.

template<class T >

G3D::VertexRange::VertexRange	(	const T &	ignored,
		int	_numElements,
		VertexBuffer::Ref	dstPtr
	)

inline

Allocate a vertex range within a vertex buffer with no offset, but do not upload data to it.

See Also: mapBuffer

template<class T >

G3D::VertexRange::VertexRange	(	const Array< T > &	source,
		VertexRange	dstPtr,
		size_t	dstOffset,
		size_t	dstStride
	)

inline

Member Function Documentation

VertexBuffer::Ref G3D::VertexRange::area ( )

inline

See Also: buffer()

Deprecated:

VertexBuffer::Ref G3D_DEPRECATED G3D::VertexRange::area ( ) const

inline

See Also: buffer()

Deprecated:

VertexBuffer::Ref G3D::VertexRange::buffer ( )

inline

The G3D::VertexBuffer containing this VertexRange.

VertexBuffer::Ref G3D::VertexRange::buffer ( ) const

inline

The G3D::VertexBuffer containing this VertexRange.

template<class T1 , class T2 , class T3 , class T4 , class T5 >

static void G3D::VertexRange::createInterleaved	(	const Array< T1 > &	src1,
		VertexRange &	var1,
		const Array< T2 > &	src2,
		VertexRange &	var2,
		const Array< T3 > &	src3,
		VertexRange &	var3,
		const Array< T4 > &	src4,
		VertexRange &	var4,
		const Array< T5 > &	src5,
		VertexRange &	var5,
		VertexBufferRef	area
	)

inlinestatic

Creates five interleaved VertexRange arrays simultaneously.

Creates five interleaved VertexRange arrays simultaneously. This is convenient for uploading vertex, normal, texcoords, and tangent arrays although it can be used for any five arrays. This is substantially faster than creating a single "void VertexRange" and uploading arrays within it using a stride.

The varn arguments are outputs only; they should not be initialized values.

All src arrays must have the same length or be empty. Empty arrays will return an uninitialized var.

See Also: updateInterleaved

Referenced by createInterleaved().

template<class T1 , class T2 , class T3 , class T4 >

static void G3D::VertexRange::createInterleaved	(	const Array< T1 > &	src1,
		VertexRange &	var1,
		const Array< T2 > &	src2,
		VertexRange &	var2,
		const Array< T3 > &	src3,
		VertexRange &	var3,
		const Array< T4 > &	src4,
		VertexRange &	var4,
		VertexBufferRef	area
	)

inlinestatic

size_t G3D::VertexRange::elementSize ( ) const

inline

uint64 G3D::VertexRange::generation ( ) const

inline

void* G3D::VertexRange::mapBuffer ( GLenum permissions )

Return a pointer to CPU-addressable memory for this VertexRange.

The buffer must be unmapped later before any rendering calls are made. This contains a glPushClientAttrib call that must be matched by unmapBuffer.

Works for both CPU memory and VBO memory VertexRange.

This method of moving data is not typesafe and is not recommended.

Parameters

permissions Same as the argument to glMapBufferARB: GL_READ_ONLY, GL_WRITE_ONLY, or GL_READ_WRITE.

Referenced by updateInterleaved().

size_t G3D::VertexRange::maxSize ( ) const

inline

Maximum size that can be loaded via update into this VertexRange.

bool G3D::VertexRange::normalizedFixedPoint ( )

inline

True if this vertex is storing numbers in normalized fixed point format.

bool G3D::VertexRange::operator== ( const VertexRange & other ) const

inline

template<class T >

void G3D::VertexRange::set	(	int	index,
		const T &	value
	)

inline

Overwrites a single element of an existing array without changing the number of elements.

This is faster than calling update for large arrays, but slow if many set calls are made. Typically used to change a few key vertices, e.g., the single dark cap point of a directional light's shadow volume.

void G3D::VertexRange::setNormalizedFixedPoint ( bool b )

inline

int G3D::VertexRange::size ( ) const

inline

Number of elements in this array (not byte size!)

void* G3D::VertexRange::startAddress ( )

inline

For VBO_MEMORY, this is the offset.

For MAIN_MEMORY, this is a pointer to the block of uploaded memory.

When there was a dstOffset as a constructor argument, it has already been applied here.

size_t G3D::VertexRange::stride ( ) const

inline

Referenced by createInterleaved().

VertexBuffer::Type G3D::VertexRange::type ( ) const

inline

GLenum G3D::VertexRange::underlyingRepresentation ( ) const

inline

void G3D::VertexRange::unmapBuffer ( )

Release CPU addressable memory previously returned by mapBuffer.

This method of moving data is not typesafe and is not recommended.

Referenced by updateInterleaved().

template<class T >

void G3D::VertexRange::update	(	const T *	sourcePtr,
		int	_numElements
	)

inline

template<class T >

void G3D::VertexRange::update ( const Array< T > & source )

inline

Overwrites existing data with data of the same size or smaller.

Convenient for changing part of a G3D::VertexBuffer without reseting the area (and thereby deallocating the other G3D::VertexRange arrays in it).

template<class T1 , class T2 , class T3 , class T4 , class T5 >

static void G3D::VertexRange::updateInterleaved	(	const Array< T1 > &	src1,
		VertexRange &	var1,
		const Array< T2 > &	src2,
		VertexRange &	var2,
		const Array< T3 > &	src3,
		VertexRange &	var3,
		const Array< T4 > &	src4,
		VertexRange &	var4,
		const Array< T5 > &	src5,
		VertexRange &	var5
	)

inlinestatic

Update a set of interleaved arrays.

Update a set of interleaved arrays. None may change size from the original.

Referenced by createInterleaved(), and updateInterleaved().

template<class T1 , class T2 , class T3 , class T4 >

static void G3D::VertexRange::updateInterleaved	(	const Array< T1 > &	src1,
		VertexRange &	var1,
		const Array< T2 > &	src2,
		VertexRange &	var2,
		const Array< T3 > &	src3,
		VertexRange &	var3,
		const Array< T4 > &	src4,
		VertexRange &	var4
	)

inlinestatic

bool G3D::VertexRange::valid ( ) const

Returns true if this VertexRange can be used for rendering (i.e., contains data and the parent VertexBuffer has not been reset).

Referenced by maxSize(), and G3D::Args::usesStandardMode().

Friends And Related Function Documentation

friend class RenderDevice

friend

friend class Shader

friend

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation