CC3VertexArray manages the data associated with an aspect of a vertex. More...
#import <CC3VertexArrays.h>
Public Member Functions | |
| (GLvoid *) | - allocateElements: |
| (void) | - bind |
| (void) | - createGLBuffer |
| (void) | - deallocateElements |
| (void) | - deleteGLBuffer |
| (id) | - initFromSPODMesh: |
| (void) | - unbind |
Static Public Member Functions | |
| (id) | + arrayFromSPODMesh: |
| (void) | + initializeSwitching |
| (void) | + unbind |
| (id) | + vertexArray |
| (id) | + vertexArrayWithName: |
| (id) | + vertexArrayWithTag: |
| (id) | + vertexArrayWithTag:withName: |
Properties | |
| GLuint | bufferID |
| GLenum | bufferTarget |
| GLenum | bufferUsage |
| GLsizei | elementCount |
| GLuint | elementOffset |
| GLvoid * | elements |
| GLint | elementSize |
| GLsizei | elementStride |
| GLenum | elementType |
Detailed Description
CC3VertexArray is an abstract implementation, and there are several sublcasses, each specialized to manage the vertex data for a different vertex aspect (locations, normals, colors, texture mapping, indices...).
Each instance of a subclass of CC3VertexArray maintains a reference to the underlying vertex data in memory, along with various parameters describing the underlying data, such as its type, element size, stride, etc.
The underlying data can be interleaved and shared by several CC3VertexArray subclasses, each looking at a different aspect of the data for each vertex. In this case, the elements property of each of those vertex array instances will reference the same underlying data memory, and the elementOffset property of each CC3VertexArray instance will indicate at which offset in each vertex data the datum of interest to that instance is located.
The CC3VertexArray instance also manages buffering the data to the GL engine, including loading it into a server-side GL vertex buffer object (VBO) if desired. Once loaded into the GL engine buffers, the underlying data is released from the CC3VertexArray instance, thereby freeing memory.
The CC3DrawableVertexArray abstract subclass adds the functionality to draw the vertex data to the display through the GL engine.
When drawing the vertices to the GL engine, each subclass remembers which vertices were last drawn, and only binds the vertices to the GL engine when a different set of vertices of the same type are drawn. This allows the application to organize the CC3MeshNodes within the CC3World so that nodes using the same mesh vertices are drawn together, before moving on to other meshes. This strategy can minimize the number of vertex pointer switches in the GL engine, which improves performance.
Member Function Documentation
| - (GLvoid*) allocateElements: | (GLsizei) | elemCount |
Allocates underlying memory for the specified number of elements, taking into consideration the elementStride, assigns the elements property to point to the allocated memory, and returns a pointer to the allocated memory.
Specifically, the amount of memory allocated will be (elemCount * self.elementStride) bytes.
If the underlying data is to be interleaved, set the value of the elementStride property to the appropriate value before invoking this method. If the underlying data will not be interleaved, the elementStride property is determined by the elementType and elementSize properties. Therefore, set the correct values of these two properties before invoking this method.
When interleaving data, this method should be invoked on only one of the CC3VertexArray instances that are sharing the underlying data. After allocating on one CC3VertexArray instances, set the elements property of the other instances to be equal to the elements property of the CC3VertexArray instance on which this method was invoked (or just simply to the pointer returned by this method).
It is safe to invoke this method more than once, but understand that any previously allocated memory will be safely free'd prior to the allocation of the new memory. The memory allocated earlier will therefore be lost and should not be referenced.
| + (id) arrayFromSPODMesh: | (PODStructPtr) | aSPODMesh |
Allocates and initializes an autoreleased instance from the specified SPODMesh structure.
| - (void) bind |
Binds the GL engine to the underlying vertex data, if needed, in preparation for drawing.
This implementation first invokes the switchingArray method on this instance to determine if this vertex array is different than the vertex array that was last bound to the GL engine. If this vertex array is indeed different, this method invokes the bindGL method, otherwise it does nothing.
This is invoked automatically from the draw method of the CC3VertexArrayMeshModel containing this instance. Usually, the application never needs to invoke this method directly.
| - (void) createGLBuffer |
Creates a vertex buffer object within the GL engine, copies the data referenced by the elements into the GL engine (which may make use of VRAM), sets the value of the bufferID property to that of the new GL buffer, and releases the elements data from main memory (since it is now redundant).
Calling this method is optional. Using GL engine buffers is more efficient than passing arrays on each GL draw call, but is optional. If you choose not to call this method, this instance will pass the mesh data properties to the GL engine on each draw call.
If the GL engine cannot allocate space for any of the buffers, this instance will revert to passing the array data for any unallocated buffer on each draw call.
When using interleaved data, this method should be invoked on only one of the CC3VertexArray that share the data. The bufferID property of that instance should then be copied to the other instances.
It is safe to invoke this method more than once, but subsequent invocations will do nothing.
This method is invoked automatically by the createGLBuffers method of the mesh model class, which also coordinates the invocations across multiple CC3VertexArray instances when interleaved data is shared between them, along with the subsequent copying of the bufferID's. Consider using the createGLBuffers of the mesh model class instead of this method.
| - (void) deallocateElements |
Deallocates the underlying vertex data memory that was previously allocated with the allocateElements: method.
It is safe to invoke this method more than once, or even if allocateElements: was not previously invoked.
When using interleaved memory, deallocateElements must be invoked on the same CC3VertexArray instance on which the original allocateElements: was invoked.
This method is invoked automatically when this instance is deallocated.
| - (void) deleteGLBuffer |
Deletes the GL engine buffers created with createGLBuffer.
After calling this method, if they have not been released by createGLBuffer, the vertex data will be passed to the GL engine on each subsequent draw operation. It is safe to call this method even if GL buffers have not been created.
This method may be invoked at any time to free up GL memory, but only if this vertex array will not be used again, or if the data was not released by createGLBuffer. This would be the case if allocateElements: was not invoked.
This method is invoked automatically when this instance is deallocated.
| - (id) initFromCPODData: | (PODClassPtr) | aCPODData | |
| fromSPODMesh: | (PODStructPtr) | aSPODMesh | |
Initializes this instance from the specified CPODData structure and the specified SPODMesh structure.
| - (id) initFromSPODMesh: | (PODStructPtr) | aSPODMesh |
Initializes this instance from the specified SPODMesh structure.
This abstract implementation does nothing. Category extensions to the concrete subclasses of CC3VertexArray must override to extract the suitable CPODData structure for the type of array from the specifed SPODMesh structure and then invoke the initFromCPODData:fromSPODMesh: initializer.
| + (void) initializeSwitching |
Initializes the tracking of the vertex array switching functionality.
This is invoked automatically by the similar method in CC3VertexArrayMeshModel at the beginning of each frame drawing cycle. Usually, the application never needs to invoke this method directly.
| + (void) unbind |
Unbinds the GL engine from the vertex aspect managed by this class.
This abstract implementation does nothing. Subclasses will override to handle their particular type of vetex aspect.
This method is invoked automatically from the CC3VertexArrayMeshModel instance. Usually, the application never needs to invoke this method directly.
| - (void) unbind |
Unbinds the GL engine from the vertex aspect managed by this instance.
This implementation simply delegates to the unbind class method. Usually, the application never needs to invoke this method directly.
| + (id) vertexArray |
Allocates and initializes an autoreleased unnamed instance with an automatically generated unique tag value.
The tag value is generated using a call to nextTag.
| + (id) vertexArrayWithName: | (NSString *) | aName |
Allocates and initializes an autoreleased instance with the specified name and an automatically generated unique tag value.
The tag value is generated using a call to nextTag.
| + (id) vertexArrayWithTag: | (GLuint) | aTag |
Allocates and initializes an unnamed autoreleased instance with the specified tag.
| + (id) vertexArrayWithTag: | (GLuint) | aTag | |
| withName: | (NSString *) | aName | |
Allocates and initializes an autoreleased instance with the specified tag and name.
Property Documentation
- (GLuint) bufferID [read, write, assign] |
If the underlying data has been loaded into a GL engine vertex buffer object, this property holds the ID of that GL buffer as provided by the GL engine when the createGLBuffer method was invoked.
If the createGLBuffer method was not invoked, and the underlying vertex was not loaded into a GL VBO, this property will be zero.
- (GLenum) bufferTarget [read, assign] |
The GL engine buffer target.
Must be one of GL_ARRAY_BUFFER or GL_ELEMENT_ARRAY_BUFFER.
The default value is GL_ARRAY_BUFFER. Subclasses that manage index data will override.
- (GLenum) bufferUsage [read, write, assign] |
The GL engine buffer usage hint, used by the GL engine to arrange data for access when loading data into a server-side vertex buffer object.
The default value is GL_STATIC_DRAW, indicating to the GL engine that the data will generally not be re-accessed after loading.
- (GLsizei) elementCount [read, write, assign] |
The number of elements in the underlying data referenced by the elements property.
The elements property must point to an underlying memory space that is large enough to hold the amount of data specified by this elementCount property.
The initial value is zero.
- (GLuint) elementOffset [read, write, assign] |
When using interleaved data, this property indicates the offset, within the data for a single vertex, at which the datum managed by this instance is located.
When data is not interleaved, and the elements data is dedicated to this instance, this property will be zero.
The initial value is zero.
- (GLvoid *) elements [read, write, assign] |
A pointer to the underlying vertex data.
If the underlying data memory is assigned to this instance using this property directly, the underlying data memory is neither retained nor deallocated by this instance. It is up to the application to manage the allocation and deallocation of the underlying data memory.
Alternately, the method allocateElements: can be used to have this instance allocate and manage the underlying data. When this is done, the underlying data memory will be retained and deallocated by this instance.
The underlying data can be interleaved and shared by several CC3VertexArray subclasses, each looking at a different aspect of the data for each vertex. In this case, the elements property of each of those vertex array instances will reference the same underlying data memory, and the elementOffset property will indicate at which offset in each vertex data the datum of interest to that instance is located.
- (GLint) elementSize [read, write, assign] |
The number of components associated with each vertex in the underlying data.
As an example, the location of each vertex in 3D space is specified by three components (X,Y & Z), so the value of this property in an instance tracking vertex locations would be three.
The initial value is three. Subclass may override this default.
- (GLsizei) elementStride [read, write, assign] |
The number of bytes between consecutive vertices for the vertex aspect being managed by this instance.
If the underlying data is not interleaved, and contains only the data managed by this instance, the value of this property will be the size of a single element of the type of data indicated by the elementType property multiplied by the value of the elementSize property. For example, with the default elementType of GL_FLOAT and elementSize of three, the value of the elementStride property will be (4 * 3) = 12.
If the underlying data is interleaved and contains data for several vertex aspects (location, normals, colors...) interleaved in one memory space, this value should be set by the application to indicate the distance, in bytes, from one element of this aspect to the next.
The initial value of this property is the size of a single element of the type of data indicated by the elementType property multiplied by the value of the elementSize property.
- (GLenum) elementType [read, write, assign] |
The type of data associated with each component of a vertex.
This must be a valid enumerated GL data type suitable for the type of element.
The initial value is GL_FLOAT.
The documentation for this class was generated from the following file:
