CC3PODResource is a CC3Resource that wraps a PVR POD data structure loaded from a file. More...
#import <CC3PODResource.h>
CC3PODResource is a CC3Resource that wraps a PVR POD data structure loaded from a file.
It handles loading object data from POD files, and creating CC3Nodes from that data. This class is the cornerstone of POD file management, and is typically one of only two POD-based classes that your application needs to be aware of, the other being CC3PODResourceNode, which is a CC3ResourceNode that, in turn, wraps an instance of this class.
CC3PODResource includes many properties and methods geared towards extracing object data from the underlying complex POD resource structure. However, most of the properties and methods exist as template methods to support internal behaviour and for overriding in subclasses that might customize object creation from the POD data.
Basic use of this class is straightforward:
The array of nodes accessible via the nodes property are the root nodes of a hierarchical structure of nodes. The loading step takes care of assembling this structural assembly.
In addition to this core functionality, this class includes many methods for accessing data structures within the resource, and extracting object content from those data structures, should the application have the need to do so. However, in almost all cases, the basic two-step process of loading and retrieving the node assembly is all that is needed.
Much of the building of the node assembly from the underlying data strucutres is handled in template methods that are identified here in the interface for ease of overriding in a customized subclass. Although not necessary, some applications may find it necessary or convenient to override one or more of these template methods to modify the objects that are extracted from the underlying file data, perhaps customizing them for the application, or correcting idiosyncracies that might have been exported into the POD file from a 3D editor. This capability can be useful if you are using a POD file of a 3D model that you did not create yourself, and cannot edit.
When customizing a subclass to change the properties of the objects returned, you will most likely override one or more of the following methods:
In most cases, the overridden method can simply invoke the superclass implementation on this class, and then change the properties of the extracted object. In other cases you may want to extract and return a customized subclass of the object of interest.
- (void) build |
Template method that extracts and builds all components.
This is automatically invoked from the loadFromPODFile: method if the POD file was successfully loaded. The application should not invoke this method directly.
The order of component extraction and building is:
This template method can be overridden in a subclass if specialized processing is required.
- (CC3Camera*) buildCameraAtIndex: | (uint) | cameraIndex |
Builds the cameraIndex'th camera node.
Note that cameraIndex is an ordinal number indicating the rank of the camera node.
This is automatically invoked from the buildNodeAtIndex: method. The application should not invoke this method directly.
This template method can be overridden in a subclass to adjust the properties of the new node. The subclass can invoke this superclass method, and then change properties as required.
- (CC3Light*) buildLightAtIndex: | (uint) | lightIndex |
Builds the lightIndex'th light node.
Note that lightIndex is an ordinal number indicating the rank of the light node.
This is automatically invoked from the buildNodeAtIndex: method. The application should not invoke this method directly.
This template method can be overridden in a subclass to adjust the properties of the new node. The subclass can invoke this superclass method, and then change properties as required.
- (CC3Material*) buildMaterialAtIndex: | (uint) | materialIndex |
Builds the materialIndex'th material.
Note that materialIndex is an ordinal number indicating the rank of the material.
This is automatically invoked from the buildMaterials method. The application should not invoke this method directly.
This template method can be overridden in a subclass to adjust the properties of the new node. The subclass can invoke this superclass method, and then change properties as required.
- (void) buildMaterials |
Template method that extracts and builds the materials from the underlying data.
This is automatically invoked from the build method. The application should not invoke this method directly.
This template method can be overridden in a subclass if specialized processing is required.
- (void) buildMeshes |
Template method that extracts and builds the meshes from the underlying data.
This is automatically invoked from the build method. The application should not invoke this method directly.
This template method can be overridden in a subclass if specialized processing is required.
- (CC3Mesh*) buildMeshModelAtIndex: | (uint) | meshIndex |
Builds the meshIndex'th mesh.
Note that meshIndex is an ordinal number indicating the rank of the mesh.
- (CC3MeshNode*) buildMeshNodeAtIndex: | (uint) | meshIndex |
Builds the meshIndex'th mesh node.
Note that meshIndex is an ordinal number indicating the rank of the mesh node.
This is automatically invoked from the buildNodeAtIndex: method. The application should not invoke this method directly.
This template method can be overridden in a subclass to adjust the properties of the new node. The subclass can invoke this superclass method, and then change properties as required.
- (CC3Node*) buildNodeAtIndex: | (uint) | nodeIndex |
Builds the node at the specified index.
Checks the type of node, and invokes one of the following template methods:
This is automatically invoked from the buildNodes method. The application should not invoke this method directly.
This template method can be overridden in a subclass if specialized processing is required.
- (void) buildNodes |
Template method that extracts and builds the nodes from the underlying data.
This is automatically invoked from the build method. The application should not invoke this method directly.
This template method can be overridden in a subclass if specialized processing is required.
- (CC3Node*) buildStructuralNodeAtIndex: | (uint) | nodeIndex |
Builds the structural node at the specified index.
This is automatically invoked from the buildNodeAtIndex: method. The application should not invoke this method directly.
This template method can be overridden in a subclass to adjust the properties of the new node. The subclass can invoke this superclass method, and then change properties as required.
- (CC3Texture*) buildTextureAtIndex: | (uint) | textureIndex |
Builds the textureIndex'th texture.
Note that textureIndex is an ordinal number indicating the rank of the texture.
This is automatically invoked from the buildTextures method. The application should not invoke this method directly.
This template method can be overridden in a subclass to adjust the properties of the new node. The subclass can invoke this superclass method, and then change properties as required.
- (void) buildTextures |
Template method that extracts and builds the textures from the underlying data.
This is automatically invoked from the build method. The application should not invoke this method directly.
This template method can be overridden in a subclass if specialized processing is required.
- (CC3Camera*) cameraAtIndex: | (uint) | cameraIndex |
Returns the cameraIndex'th camera node.
Note that cameraIndex is an ordinal number indicating the rank of the camera node, and is not a direct index into the allNodes array.
- (PODStructPtr) cameraNodePODStructAtIndex: | (uint) | cameraIndex |
Returns the SPODNode structure of the cameraIndex'th light node.
Note that cameraIndex is an ordinal number indicating the rank of the camera node.
The returned pointer must be cast to SPODNode before accessing any internals of the data structure.
- (PODStructPtr) cameraPODStructAtIndex: | (uint) | cameraIndex |
Returns cameraIndex'th SPODCamera structure from the data structures.
The returned pointer must be cast to SPODCamera before accessing any internals of the data structure.
- (CC3Light*) lightAtIndex: | (uint) | lightIndex |
Returns the lightIndex'th light node.
Note that lightIndex is an ordinal number indicating the rank of the light node, and is not a direct index into the allNodes array.
- (PODStructPtr) lightNodePODStructAtIndex: | (uint) | lightIndex |
Returns the SPODNode structure of the lightIndex'th light node.
Note that lightIndex is an ordinal number indicating the rank of the light node.
The returned pointer must be cast to SPODNode before accessing any internals of the data structure.
- (PODStructPtr) lightPODStructAtIndex: | (uint) | lightIndex |
Returns lightIndex'th SPODLight structure from the data structures.
The returned pointer must be cast to SPODLight before accessing any internals of the data structure.
- (CC3Material*) materialAtIndex: | (uint) | materialIndex |
Returns the materialIndex'th material.
Note that materialIndex is an ordinal number indicating the rank of the material.
- (CC3Material*) materialNamed: | (NSString *) | aName |
Returns the material with the specified name from the materials array.
- (PODStructPtr) materialPODStructAtIndex: | (uint) | materialIndex |
Returns materialIndex'th SPODMaterial structure from the data structures.
Note that materialIndex is an ordinal number indicating the rank of the material.
The returned pointer must be cast to SPODMaterial before accessing any internals of the data structure.
- (CC3Mesh*) meshModelAtIndex: | (uint) | meshIndex |
Returns the meshIndex'th mesh.
Note that meshIndex is an ordinal number indicating the rank of the mesh.
- (CC3MeshNode*) meshNodeAtIndex: | (uint) | meshIndex |
Returns the meshIndex'th mesh node.
Note that meshIndex is an ordinal number indicating the rank of the mesh node, and is not a direct index into the allNodes array.
- (PODStructPtr) meshNodePODStructAtIndex: | (uint) | meshIndex |
Returns the SPODNode structure of the meshIndex'th mesh node.
Note that meshIndex is an ordinal number indicating the rank of the mesh node.
The returned pointer must be cast to SPODNode before accessing any internals of the data structure.
- (PODStructPtr) meshPODStructAtIndex: | (uint) | meshIndex |
Returns meshIndex'th SPODMesh structure from the data structures.
Note that meshIndex is an ordinal number indicating the rank of the mesh.
The returned pointer must be cast to SPODMesh before accessing any internals of the data structure.
- (CC3Node*) nodeAtIndex: | (uint) | nodeIndex |
Returns the node at the specified index in the allNodes array.
- (CC3Node*) nodeNamed: | (NSString *) | aName |
Returns the node with the specified name from the allNodes array.
- (PODStructPtr) nodePODStructAtIndex: | (uint) | nodeIndex |
Returns the underlying SPODNode data structure from the POD file, for the SPODNode at the specified index.
The returned pointer must be cast to SPODNode before accessing any internals of the data structure.
- (CC3Texture*) textureAtIndex: | (uint) | textureIndex |
Returns the textureIndex'th texture.
Note that textureIndex is an ordinal number indicating the rank of the texture.
- (PODStructPtr) texturePODStructAtIndex: | (uint) | textureIndex |
Returns textureIndex'th SPODTexture structure from the data structures.
Note that textureIndex is an ordinal number indicating the rank of the texture.
The returned pointer must be cast to SPODTexture before accessing any internals of the data structure.
- (CCArray *) allNodes [read, assign] |
A collection of all of the nodes extracted from the POD file.
This is the equivalent of flattening the nodes array.
- (ccColor4F) ambientLight [read, assign] |
The global ambient light of the scene in the POD file.
- (uint) animationFrameCount [read, assign] |
The number of frames of animation in the POD file.
- (ccColor4F) backgroundColor [read, assign] |
The background color of the scene in the POD file.
- (uint) cameraCount [read, assign] |
The total number of cameras in the POD file.
- (uint) lightCount [read, assign] |
The total number of lights in the POD file.
- (uint) materialCount [read, assign] |
The number of materials in the POD file.
- (CCArray *) materials [read, assign] |
A collection of the CC3Materials extracted from the POD file.
- (uint) meshCount [read, assign] |
The total number of meshes in the POD file.
This is different than the meshNodeCount because mesh models may be used by more than one mesh node.
- (CCArray *) meshes [read, assign] |
A collection of the CC3Meshs extracted from the POD file.
- (uint) meshNodeCount [read, assign] |
The total number of mesh nodes in the POD file.
- (uint) nodeCount [read, assign] |
The total number of nodes in the POD file.
This is also the count of the allNodes array.
- (PODClassPtr) pvrtModel [read, assign] |
The underlying C++ CPVRTModelPOD class.
It is defined here as a generic pointer so that it can be imported into header files without the need for the including file to support C++ This must be cast to a pointer to CPVRTModelPOD before accessing any elements within the class.
- (uint) textureCount [read, assign] |
The number of different textures in the POD file.
- (ccTexParams) textureParameters [read, write, assign] |
An set of texture parameters used to optimize the display of textures in the GL engine.
These parameters will be set in any texture that is extracted from this resource.
The initial value of these parameters are:
Any changes to this property should be made before invoking the loadFromPODFile: method.
- (CCArray *) textures [read, assign] |
A collection of the CC3Textures extracted from the POD file.