CC3VertexArray manages the data associated with an aspect of a vertex. More...
#import <CC3VertexArrays.h>
Public Member Functions | |
| (GLvoid *) | - addressOfElement: |
| (GLvoid *) | - allocateElements: |
| (void) | - bindWithVisitor: |
| (void) | - createGLBuffer |
| (void) | - deallocateElements |
| (void) | - deleteGLBuffer |
| (id) | - initFromCPODData:fromSPODMesh: |
| (id) | - initFromSPODMesh: |
| (void) | - releaseRedundantData |
| (void) | - unbind |
| (void) | - updateGLBuffer |
| (void) | - updateGLBufferStartingAt:forLength: |
Static Public Member Functions | |
| (id) | + arrayFromSPODMesh: |
| (void) | + resetAllSwitching |
| (void) | + resetSwitching |
| (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 |
| BOOL | shouldAllowVertexBuffering |
| BOOL | shouldReleaseRedundantData |
Detailed Description
CC3VertexArray manages the data associated with an aspect of a vertex.
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 can be released from the CC3VertexArray instance, thereby freeing memory, by using the releaseRedundantData method.
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.
Vertex arrays support the NSCopying protocol, but in normal operation, the need to create copies of vertex arrays is rare.
By default, when a mesh node is copied, it does not make a separate copy of its model. Both the original and the copy make use of the same mesh instance. Similarly, when a mesh is copied, it does not make separate copies of its vertex arrays. Instead, both the original and the copy make use of the same vertex array instances.
However, in some cases, such as populating a mesh from a template and then manipulating the contents of each resulting mesh individually, creating copies of vertex arrays can be useful.
If you do find need to create a copy of a vertex array, you can do so by invoking the copy method. However, you should take care to understand several points about copying vertex arrays:
- Copying a vertex array creates a full copy of the vertex data. This may consume significant memory.
- The vertex data is copied for each vertex array copy. If several vertex arrays share interleaved data, multiple copies of that data will be created. This is almost never what you intend to do, and results in significant redundant data in memory. Instead, consider creating a copy of one of the vertex arrays, and then manually populating the others so that the interleaved vertex data can be shared.
- If the value of the shouldReleaseRedundantData property of the original vertex array is YES and releaseRedundantData has been invoked, there will be no vertex data to be copied.
- The new vertex array will not have a GL vertex buffer object associated with it. To buffer the vertex data of the new vertex array, invoke the createGLBuffer method on the new vertex array.
Member Function Documentation
| - (GLvoid*) addressOfElement: | (GLsizei) | index |
Returns a pointer to the element in the underlying data at the specified index.
The implementation takes into consideration the elementStride and elementOffset properties to locate the aspect of interest in this instance.
If the releaseRedundantData method has been invoked and the underlying vertex data has been released, or the index is beyond the elementCount, this method will raise an assertion exception.
| - (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 freed 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) bindWithVisitor: | (CC3NodeDrawingVisitor *) | visitor |
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 CC3VertexArrayMesh containing this instance. Usually, the application never needs to invoke this method directly.
| - (void) createGLBuffer |
If the shouldAllowVertexBuffering property is set to YES, 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), and sets the value of the bufferID property to that of the new GL buffer.
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 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 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.
Deallocating the elements array does not change the elementCount property, because that property is still used for other operations, including drawing.
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 releaseRedundantData. 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) releaseRedundantData |
Once the elements data has been buffered into a GL vertex buffer object (VBO) within the GL engine, via the createGLBuffer method, this method can be used to release the data in main memory that is now redundant.
If the shouldReleaseRedundantData property is set to NO, or if the elements data has not been successfully buffered to a VBO in the GL engine. this method does nothing. It is safe to invokde this method even if createGLBuffer has not been invoked, and even if VBO buffering was unsuccessful.
Typically, this method is not invoked directly by the application. Instead, consider using the same method on a node assembly in order to release as much memory as possible in one simply method invocation.
Subclasses may extend this behaviour to remove data loaded, for example, from files, but should ensure that data is only released if bufferId is valid (not zero), and the shouldReleaseRedundantData property is set to YES.
| + (void) resetAllSwitching |
Resets the tracking of the vertex array switching functionality for all vertex array subclasses.
This is invoked automatically by the resetSwitching method in CC3VertexArrayMesh at the beginning of each frame drawing cycle. Usually, the application never needs to invoke this method directly.
| + (void) resetSwitching |
Resets the tracking of the vertex array switching functionality.
This is invoked automatically by the resetAllSwitching method 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 instance.
This implementation simply delegates to the unbind class method. Usually, the application never needs to invoke this method directly.
Implemented in CC3VertexTextureCoordinates.
| + (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 CC3VertexArrayMesh instance. Usually, the application never needs to invoke this method directly.
Implemented in CC3VertexTextureCoordinates.
| - (void) updateGLBuffer |
Updates the GL engine buffer with all of the element data contained in this array.
| - (void) updateGLBufferStartingAt: | (GLuint) | offsetIndex | |
| forLength: | (GLsizei) | vertexCount | |
Updates the GL engine buffer with the element data contained in this array, starting at the vertex at the specified offsetIndex, and extending for the specified number of vertices.
| + (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. If you will be updating the data frequently, you can change this to GL_DYNAMIC_DRAW.
- (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.
- (BOOL) shouldAllowVertexBuffering [read, write, assign] |
Indicates whether this instance should allow the vertex data to be copied to a vertex buffer object within the GL engine when the createGLBuffer method is invoked.
The initial value of this property is YES. In most cases, this is appropriate, but for specific meshes, it might make sense to retain data in main memory and submit it to the GL engine during each frame rendering.
As an alternative to setting this property to NO, consider leaving it as YES, and making use of the updateGLBuffer and updateGLBufferStartingAt:forLength: to dynamically update the data in the GL engine buffer. Doing so permits the data to be copied to the GL engine only when it has changed, and permits copying only the range of data that has changed, both of which offer performance improvements over submitting all of the vertex data on each frame render.
- (BOOL) shouldReleaseRedundantData [read, write, assign] |
Indicates whether this instance should release the data held in the elments array when the releaseRedundantData method is invoked.
The initial value of this property is YES. In most cases, this is appropriate, but in some circumstances it might make sense to retain some data (usually the vertex locations) in main memory for potantial use in collision detection, etc.
The documentation for this class was generated from the following file:
