CC3PODResource is a wrapper class around a PVR POD resource structure. More...
#import <CC3PODResource.h>
Detailed Description
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 CC3Node 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:
- Allocate and initialize the CC3PODResource instance and load a POD file into the internal structures. This action also builds all the objects from the resource data structures (depending on the initializer used, loading can be triggered from the initializer, or can be performed separately).
- Access the nodes property to retrieve the fully-built node assembly.
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:
- buildMeshNodeAtIndex:
- buildLightAtIndex:
- buildCameraAtIndex:
- buildStructuralNodeAtIndex:
- buildMaterialAtIndex:
- buildTextureAtIndex:
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.
Member Function Documentation
| - (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:
- textures, by invoking the buildTextures template method
- materials, by invoking the buildMaterials template method
- mesh models, by invoking the buildMeshModels template method
- nodes, by invoking the buildNodes template method
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.
| - (CC3MeshModel*) buildMeshModelAtIndex: | (uint) | meshIndex |
Builds the meshIndex'th mesh model.
Note that meshIndex is an ordinal number indicating the rank of the mesh model.
| - (void) buildMeshModels |
Template method that extracts and builds the mesh models 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.
| - (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:
- buildMeshNodeAtIndex:
- buildLightAtIndex:
- buildCameraAtIndex:
- buildStructuralNodeAtIndex:
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.
| - (id) initFromPODFile: | (NSString *) | aFilepath |
Initializes this instance, populates the internal POD data structures from the file at the specified path, and extracts the 3D objects.
The specified file path must be an absolute path.
| - (id) initFromPODResourceFile: | (NSString *) | aRezPath |
Initializes this instance, populates the internal POD data structures from the file at the specified resource path, and extracts the 3D objects.
The specified file path is a path relative to the resource directory. Typically this means that the specified path can just be the name of the file, with no path information.
| - (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.
| - (void) loadFromPODFile: | (NSString *) | aFilepath |
Loads the file at the specified path, populates the internal POD data structures, and extracts the 3D objects and nodes.
The specified file path must be an absolute path.
| - (void) loadFromPODResourceFile: | (NSString *) | aRezPath |
Loads the file at the specified resource path, populates the internal POD data structures, and extracts the 3D objects and nodes.
The specified file path is a path relative to the resource directory. Typically this means that the specified path can just be the name of the file, with no path information.
| - (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.
| - (CC3MeshModel*) meshModelAtIndex: | (uint) | meshIndex |
Returns the meshIndex'th mesh model.
Note that meshIndex is an ordinal number indicating the rank of the mesh model.
| - (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 model.
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.
| + (id) resource |
Allocates and initializes an autoreleased instance, without loading a POD file.
The file can be loaded later using the loadFromPODFile: method.
Use this method if you want to perform activities such as setting the textureParameters property before loading.
| + (id) resourceFromPODFile: | (NSString *) | aFilepath |
Allocates and initializes an autoreleased instance, populates the internal POD data structures from the file at the specified path, and extracts the 3D objects.
The specified file path must be an absolute path.
| + (id) resourceFromPODResourceFile: | (NSString *) | aRezPath |
Allocates and initializes an autoreleased instance, populates the internal POD data structures from the file at the specified resource path, and extracts the 3D objects.
The specified file path is a path relative to the resource directory. Typically this means that the specified path can just be the name of the file, with no path information.
| - (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.
Property Documentation
- (NSArray*) 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.
- (NSArray*) materials [read, assign] |
A collection of the CC3Materials extracted from the POD file.
- (uint) meshModelCount [read, assign] |
The total number of mesh models in the POD file.
This is different than the meshNodeCount because mesh models may be used by more than one mesh node.
- (NSArray*) meshModels [read, assign] |
A collection of the CC3MeshModels 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.
- (NSArray*) nodes [read, assign] |
A collection of the root nodes of the node assembly extracted from the POD file.
Each of these nodes will usually contain child nodes. This is the primary property used to access the assembled nodes.
- (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:
- Minifying function: GL_LINEAR
- Magnifying function: GL_LINEAR
- Texture wrap S: GL_REPEAT
- Texture wrap T: GL_REPEAT
Any changes to this property should be made before invoking the loadFromPODFile: method.
- (NSArray*) textures [read, assign] |
A collection of the CC3Textures extracted from the POD file.
The documentation for this class was generated from the following file:
