Support Forum       G3D Web Page     
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
G3D::AttributeArray Class Reference


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

Inherited by G3D::IndexStream.

Public Member Functions

 AttributeArray ()
 Creates an invalid AttributeArray. More...
 
 AttributeArray (size_t numBytes, const shared_ptr< VertexBuffer > &_area)
 Creates a AttributeArray that acts as a pointer to a block of memory. More...
 
template<class T >
 AttributeArray (const T *sourcePtr, int _numElements, const shared_ptr< VertexBuffer > &_area)
 Uploads memory from the CPU to the GPU. More...
 
template<class T >
 AttributeArray (const Array< T > &source, const shared_ptr< VertexBuffer > &_area)
 
template<class T >
 AttributeArray (const T *srcPtr, size_t _numElements, size_t srcStride, AttributeArray dstPtr, size_t dstOffset, size_t dstStride)
 Create an interleaved array within an existing AttributeArray and upload data to it. More...
 
template<class T >
 AttributeArray (const T &ignored, int _numElements, AttributeArray dstPtr, size_t dstOffset, size_t dstStride)
 Create an interleaved array within an existing AttributeArray, but do not upload data to it. More...
 
template<class T >
 AttributeArray (const T &ignored, int _numElements, shared_ptr< VertexBuffer > dstPtr)
 Allocate a vertex range within a vertex buffer with no offset, but do not upload data to it. More...
 
template<class T >
 AttributeArray (const Array< T > &source, AttributeArray dstPtr, size_t dstOffset, size_t dstStride)
 
virtual ~AttributeArray ()
 
shared_ptr< VertexBufferarea ()
 
shared_ptr< VertexBufferarea () const
 
shared_ptr< VertexBufferbuffer ()
 The G3D::VertexBuffer containing this AttributeArray. More...
 
shared_ptr< VertexBufferbuffer () const
 The G3D::VertexBuffer containing this AttributeArray. More...
 
size_t elementSize () const
 Size of one element in bytes.
More...
 
uint64 generation () const
 
void * mapBuffer (GLenum permissions)
 Return a pointer to CPU-addressable memory for this AttributeArray. More...
 
size_t maxSize () const
 Maximum size that can be loaded via update into this AttributeArray. More...
 
bool normalizedFixedPoint ()
 True if this vertex is storing numbers in normalized fixed point format. More...
 
virtual GLenum openGLTarget () const
 Target argument for glBufferData and other raw OpenGL routines. More...
 
bool operator== (const AttributeArray &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. More...
 
void setNormalizedFixedPoint (bool b)
 
int size () const
 Number of elements in this array (not byte size!) More...
 
void * startAddress () const
 For VBO_MEMORY, this is the offset. More...
 
size_t stride () const
 Space between subsequent elements in bytes, must be either zero or >= m_elementSize.
More...
 
GLenum underlyingRepresentation () const
 
void unmapBuffer ()
 Release CPU addressable memory previously returned by mapBuffer. More...
 
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. More...
 
bool valid () const
 Returns true if this AttributeArray can be used for rendering (i.e., contains data and the parent VertexBuffer has not been reset). More...
 

Static Public Member Functions

template<class T1 , class T2 , class T3 , class T4 , class T5 >
static void createInterleaved (const Array< T1 > &src1, AttributeArray &var1, const Array< T2 > &src2, AttributeArray &var2, const Array< T3 > &src3, AttributeArray &var3, const Array< T4 > &src4, AttributeArray &var4, const Array< T5 > &src5, AttributeArray &var5, const shared_ptr< VertexBuffer > &area)
 Creates five interleaved AttributeArray arrays simultaneously. More...
 
template<class T1 , class T2 , class T3 , class T4 >
static void createInterleaved (const Array< T1 > &src1, AttributeArray &var1, const Array< T2 > &src2, AttributeArray &var2, const Array< T3 > &src3, AttributeArray &var3, const Array< T4 > &src4, AttributeArray &var4, const shared_ptr< VertexBuffer > &area)
 
template<class T1 , class T2 , class T3 , class T4 , class T5 >
static void updateInterleaved (const Array< T1 > &src1, AttributeArray &var1, const Array< T2 > &src2, AttributeArray &var2, const Array< T3 > &src3, AttributeArray &var3, const Array< T4 > &src4, AttributeArray &var4, const Array< T5 > &src5, AttributeArray &var5)
 Update a set of interleaved arrays. More...
 
template<class T1 , class T2 , class T3 , class T4 >
static void updateInterleaved (const Array< T1 > &src1, AttributeArray &var1, const Array< T2 > &src2, AttributeArray &var2, const Array< T3 > &src3, AttributeArray &var3, const Array< T4 > &src4, AttributeArray &var4)
 

Protected Member Functions

void init (AttributeArray &dstPtr, size_t dstOffset, GLenum glformat, size_t eltSize, int numElements, size_t stride, bool normalizedFixedPoint)
 For uploading interleaved arrays. More...
 
void init (const void *sourcePtr, int numElements, shared_ptr< VertexBuffer > area, GLenum glformat, size_t eltSize, bool normalizedFixedPoint)
 
void init (const void *srcPtr, int numElements, size_t srcStride, GLenum glformat, size_t eltSize, AttributeArray dstPtr, size_t dstOffset, size_t dstStride, bool normalizedFixedPoint)
 
const void * pointer () const
 May be an OpenGL video memory offset or a real memory pointer. More...
 
void set (int index, const void *value, GLenum glformat, size_t eltSize)
 
void update (const void *sourcePtr, int _numElements, GLenum glformat, size_t eltSize, bool normalizedFixedPoint)
 
void uploadToCard (const void *sourcePtr, size_t dstPtrOffsetElements, size_t size)
 Performs the actual memory transfer (like memcpy). More...
 
void uploadToCardStride (const void *sourcePtr, size_t srcElements, size_t srcSizeBytes, size_t srcStrideBytes, size_t dstPtrOffsetBytes, size_t dstStrideBytes)
 Used for creating interleaved arrays. More...
 
void vertexAttribPointer (unsigned int attribNum) const
 

Protected Attributes

shared_ptr< VertexBufferm_area
 
size_t m_elementSize
 Size of one element in bytes. More...
 
uint64 m_generation
 
size_t m_maxSize
 The initial size this AttributeArray was allocated with, in bytes. More...
 
bool m_normalizedFixedPoint
 
int m_numElements
 For a void array, this is m_maxSize. More...
 
void * m_pointer
 For VBO_MEMORY, this is the offset. More...
 
size_t m_stride
 Space between subsequent elements in bytes, must be either zero or >= m_elementSize. More...
 
GLenum m_underlyingRepresentation
 GL_NONE for a "void" array. More...
 

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

◆ ~AttributeArray()

virtual G3D::AttributeArray::~AttributeArray ( )
inlinevirtual

◆ AttributeArray() [1/8]

G3D::AttributeArray::AttributeArray ( )

Creates an invalid AttributeArray.

◆ AttributeArray() [2/8]

G3D::AttributeArray::AttributeArray ( size_t  numBytes,
const shared_ptr< VertexBuffer > &  _area 
)

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

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

◆ AttributeArray() [3/8]

template<class T >
G3D::AttributeArray::AttributeArray ( const T *  sourcePtr,
int  _numElements,
const shared_ptr< VertexBuffer > &  _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
shared_ptr<VertexBuffer> dataArea = VertexBuffer::create(5 * 1024 * 1024);
shared_ptr<VertexBuffer> 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();
AttributeArray vertexVARGPU(vertexArrayCPU, dataArea);
AttributeArray indexVARGPU(indexArrayCPU, indexArea);
//------------
// Render
Args args;
args.setAttributeArray("g3d_Vertex", varray);
args.setIndexStream(indexVARGPU);
LAUNCH_SHADER("myShader.*", args);
Parameters
sourcePtrThe type of the data is determined from this. If nullptr, no data is actually uploaded...but you must provide a properly typed pointer, e.g., (uint16*)(nullptr).

◆ AttributeArray() [4/8]

template<class T >
G3D::AttributeArray::AttributeArray ( const Array< T > &  source,
const shared_ptr< VertexBuffer > &  _area 
)
inline

◆ AttributeArray() [5/8]

template<class T >
G3D::AttributeArray::AttributeArray ( const T *  srcPtr,
size_t  _numElements,
size_t  srcStride,
AttributeArray  dstPtr,
size_t  dstOffset,
size_t  dstStride 
)
inline

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

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

Parameters
srcStrideIf non-zero, this is the spacing between sequential elements in bytes. It may be negative.
dstOffsetOffset in bytes from the head of dstPtr. e.g., to upload starting after the 2nd byte, set dstOffset = 2.
dstStrideIf 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.

◆ AttributeArray() [6/8]

template<class T >
G3D::AttributeArray::AttributeArray ( const T &  ignored,
int  _numElements,
AttributeArray  dstPtr,
size_t  dstOffset,
size_t  dstStride 
)
inline

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

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

Example:

    G3D_BEGIN_PACKED_CLASS
    struct Packed {
        Vector3   vertex;
        Vector2   texcoord;
    }
    G3D_END_PACKED_CLASS

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

    AttributeArray interleavedBlock(totalSize, area);

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

    Packed* ptr = (Packed*)interleavedBlock.mapBuffer(GL_WRITE_ONLY);
     // ... write to elements of ptr ...
    interleavedBlock.unmapBuffer();
 

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

◆ AttributeArray() [7/8]

template<class T >
G3D::AttributeArray::AttributeArray ( const T &  ignored,
int  _numElements,
shared_ptr< VertexBuffer dstPtr 
)
inline

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

See also
mapBuffer

◆ AttributeArray() [8/8]

template<class T >
G3D::AttributeArray::AttributeArray ( const Array< T > &  source,
AttributeArray  dstPtr,
size_t  dstOffset,
size_t  dstStride 
)
inline

Member Function Documentation

◆ area() [1/2]

shared_ptr<VertexBuffer> G3D::AttributeArray::area ( )
inline
See also
buffer()
Deprecated:

Referenced by createInterleaved().

◆ area() [2/2]

shared_ptr<VertexBuffer> G3D::AttributeArray::area ( ) const
inline

◆ buffer() [1/2]

shared_ptr<VertexBuffer> G3D::AttributeArray::buffer ( )
inline

The G3D::VertexBuffer containing this AttributeArray.

◆ buffer() [2/2]

shared_ptr<VertexBuffer> G3D::AttributeArray::buffer ( ) const
inline

The G3D::VertexBuffer containing this AttributeArray.

◆ createInterleaved() [1/2]

template<class T1 , class T2 , class T3 , class T4 , class T5 >
static void G3D::AttributeArray::createInterleaved ( const Array< T1 > &  src1,
AttributeArray var1,
const Array< T2 > &  src2,
AttributeArray var2,
const Array< T3 > &  src3,
AttributeArray var3,
const Array< T4 > &  src4,
AttributeArray var4,
const Array< T5 > &  src5,
AttributeArray var5,
const shared_ptr< VertexBuffer > &  area 
)
inlinestatic

Creates five interleaved AttributeArray arrays simultaneously.

Creates five interleaved AttributeArray 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 AttributeArray" 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().

◆ createInterleaved() [2/2]

template<class T1 , class T2 , class T3 , class T4 >
static void G3D::AttributeArray::createInterleaved ( const Array< T1 > &  src1,
AttributeArray var1,
const Array< T2 > &  src2,
AttributeArray var2,
const Array< T3 > &  src3,
AttributeArray var3,
const Array< T4 > &  src4,
AttributeArray var4,
const shared_ptr< VertexBuffer > &  area 
)
inlinestatic

◆ elementSize()

size_t G3D::AttributeArray::elementSize ( ) const
inline

Size of one element in bytes.

For a void array, this is 1.

◆ generation()

uint64 G3D::AttributeArray::generation ( ) const
inline

◆ init() [1/3]

void G3D::AttributeArray::init ( AttributeArray dstPtr,
size_t  dstOffset,
GLenum  glformat,
size_t  eltSize,
int  numElements,
size_t  stride,
bool  normalizedFixedPoint 
)
protected

For uploading interleaved arrays.

Referenced by AttributeArray(), and createInterleaved().

◆ init() [2/3]

void G3D::AttributeArray::init ( const void *  sourcePtr,
int  numElements,
shared_ptr< VertexBuffer area,
GLenum  glformat,
size_t  eltSize,
bool  normalizedFixedPoint 
)
protected

◆ init() [3/3]

void G3D::AttributeArray::init ( const void *  srcPtr,
int  numElements,
size_t  srcStride,
GLenum  glformat,
size_t  eltSize,
AttributeArray  dstPtr,
size_t  dstOffset,
size_t  dstStride,
bool  normalizedFixedPoint 
)
protected

◆ mapBuffer()

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

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

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

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

Parameters
permissionsSame as the argument to glMapBufferARB: GL_READ_ONLY, GL_WRITE_ONLY, or GL_READ_WRITE.

Referenced by updateInterleaved().

◆ maxSize()

size_t G3D::AttributeArray::maxSize ( ) const
inline

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

◆ normalizedFixedPoint()

bool G3D::AttributeArray::normalizedFixedPoint ( )
inline

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

◆ openGLTarget()

virtual GLenum G3D::AttributeArray::openGLTarget ( ) const
inlinevirtual

Target argument for glBufferData and other raw OpenGL routines.

Reimplemented in G3D::IndexStream.

◆ operator==()

bool G3D::AttributeArray::operator== ( const AttributeArray other) const
inline

◆ pointer()

const void* G3D::AttributeArray::pointer ( ) const
inlineprotected

May be an OpenGL video memory offset or a real memory pointer.

For use by RenderDevice only.

◆ set() [1/2]

void G3D::AttributeArray::set ( int  index,
const void *  value,
GLenum  glformat,
size_t  eltSize 
)
protected

◆ set() [2/2]

template<class T >
void G3D::AttributeArray::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.

◆ setNormalizedFixedPoint()

void G3D::AttributeArray::setNormalizedFixedPoint ( bool  b)
inline

◆ size()

int G3D::AttributeArray::size ( ) const
inline

◆ startAddress()

void* G3D::AttributeArray::startAddress ( ) const
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.

◆ stride()

size_t G3D::AttributeArray::stride ( ) const
inline

Space between subsequent elements in bytes, must be either zero or >= m_elementSize.

Referenced by createInterleaved().

◆ underlyingRepresentation()

GLenum G3D::AttributeArray::underlyingRepresentation ( ) const
inline

◆ unmapBuffer()

void G3D::AttributeArray::unmapBuffer ( )

Release CPU addressable memory previously returned by mapBuffer.

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

Referenced by updateInterleaved().

◆ update() [1/3]

void G3D::AttributeArray::update ( const void *  sourcePtr,
int  _numElements,
GLenum  glformat,
size_t  eltSize,
bool  normalizedFixedPoint 
)
protected

Referenced by update().

◆ update() [2/3]

template<class T >
void G3D::AttributeArray::update ( const T *  sourcePtr,
int  _numElements 
)
inline

◆ update() [3/3]

template<class T >
void G3D::AttributeArray::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::AttributeArray arrays in it).

◆ updateInterleaved() [1/2]

template<class T1 , class T2 , class T3 , class T4 , class T5 >
static void G3D::AttributeArray::updateInterleaved ( const Array< T1 > &  src1,
AttributeArray var1,
const Array< T2 > &  src2,
AttributeArray var2,
const Array< T3 > &  src3,
AttributeArray var3,
const Array< T4 > &  src4,
AttributeArray var4,
const Array< T5 > &  src5,
AttributeArray 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().

◆ updateInterleaved() [2/2]

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

◆ uploadToCard()

void G3D::AttributeArray::uploadToCard ( const void *  sourcePtr,
size_t  dstPtrOffsetElements,
size_t  size 
)
protected

Performs the actual memory transfer (like memcpy).

The dstPtrOffset is the number of bytes to add to m_pointer when performing the transfer.

◆ uploadToCardStride()

void G3D::AttributeArray::uploadToCardStride ( const void *  sourcePtr,
size_t  srcElements,
size_t  srcSizeBytes,
size_t  srcStrideBytes,
size_t  dstPtrOffsetBytes,
size_t  dstStrideBytes 
)
protected

Used for creating interleaved arrays.

◆ valid()

bool G3D::AttributeArray::valid ( ) const

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

Referenced by G3D::UniversalSurface::GPUGeom::hasBones(), G3D::Args::hasGPUIndexStream(), and maxSize().

◆ vertexAttribPointer()

void G3D::AttributeArray::vertexAttribPointer ( unsigned int  attribNum) const
protected

Friends And Related Function Documentation

◆ RenderDevice

friend class RenderDevice
friend

◆ Shader

friend class Shader
friend

Member Data Documentation

◆ m_area

shared_ptr<VertexBuffer> G3D::AttributeArray::m_area
protected

Referenced by area(), buffer(), and operator==().

◆ m_elementSize

size_t G3D::AttributeArray::m_elementSize
protected

Size of one element in bytes.

For a void array, this is 1.

Referenced by elementSize(), and operator==().

◆ m_generation

uint64 G3D::AttributeArray::m_generation
protected

Referenced by generation(), and operator==().

◆ m_maxSize

size_t G3D::AttributeArray::m_maxSize
protected

The initial size this AttributeArray was allocated with, in bytes.

Referenced by maxSize(), and operator==().

◆ m_normalizedFixedPoint

bool G3D::AttributeArray::m_normalizedFixedPoint
protected

◆ m_numElements

int G3D::AttributeArray::m_numElements
protected

For a void array, this is m_maxSize.

Referenced by operator==(), size(), and updateInterleaved().

◆ m_pointer

void* G3D::AttributeArray::m_pointer
protected

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 an init() argument, it has already been applied here.

Referenced by operator==(), pointer(), startAddress(), and updateInterleaved().

◆ m_stride

size_t G3D::AttributeArray::m_stride
protected

Space between subsequent elements in bytes, must be either zero or >= m_elementSize.

Referenced by operator==(), and stride().

◆ m_underlyingRepresentation

GLenum G3D::AttributeArray::m_underlyingRepresentation
protected

GL_NONE for a "void" array.

Referenced by operator==(), and underlyingRepresentation().


documentation generated on Wed Nov 24 2021 08:01:53 using doxygen 1.8.15