v2.0.2
|
|
v2.0.2
|
#import <CC3PODResource.h>
Additional Inherited Members | |
 Class Methods inherited from CC3NodesResource | |
| (BOOL) | + defaultExpectsVerticallyFlippedTextures |
| (BOOL) | + defaultShouldFreezeInanimateNodes |
| (id) | + resourceFromFile:expectsVerticallyFlippedTextures: |
| (void) | + setDefaultExpectsVerticallyFlippedTextures: |
| (void) | + setDefaultShouldFreezeInanimateNodes: |
CC3PODResource is a CC3NodesResource 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.
If this resource contains soft-body components such as skinned meshes, the corresponding skinned mesh nodes and skeleton bone nodes are collected together and wrapped in a single soft body node that appears in the nodes array.
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 ...Class properties or build...AtIndex: 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 loadFromFile: method if the POD file was successfully loaded, and the shouldAutoBuild property is set to YES. Autobuilding is the default behaviour, and usually, the application should not need to 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.
| - (CC3Mesh*) buildMeshAtIndex: | (uint) | meshIndex |
Builds the meshIndex'th mesh.
Note that meshIndex is an ordinal number indicating the rank of the mesh.
| - (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.
| - (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.
| - (void) buildSceneInfo |
Template method that extracts and sets the scene info, including the following properties:
This template method can be overridden in a subclass if specialized processing is required.
| - (void) buildSoftBodyNode |
If this resource contains soft-body components such as skinned meshes, the corresponding skinned mesh nodes and skeleton bone nodes are collected together and wrapped in a single soft body node.
| - (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.
| - (BOOL) isBoneNode: | (uint) | nodeIndex |
Returns whether the specified node index represents a bone node that is part of a skeleton node assembly that will be used to control vertex skinning.
| - (BOOL) isNodeIndex: | (int) | aNodeIndex | |
| ancestorOfNodeIndex: | (int) | childIndex | |
Returns whether the specified node index is an ancestor of the specified child node index.
If it is, once the nodes are assembled into their structural hierarchy, the node with the specified child index will be a descendant of the specified node index.
| - (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*) meshAtIndex: | (uint) | meshIndex |
Returns the meshIndex'th mesh.
Note that meshIndex is an ordinal number indicating the rank of the mesh.
| - (CC3Mesh*) meshModelAtIndex: | (uint) | __deprecated |
| - (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.
| - (BOOL) saveAnimationToFile: | (NSString *) | filePath |
Saves the animation content of this resource to the file at the specified file path and returns whether the saving was successful.
Animation content includes the nodes that have animation defined. All other content, including meshes, materials and textures are stripped from the POD resource that is saved. The POD content in this instance is not affected.
The specified file path may be either an absolute path, or a path relative to the application resource directory. If the file is located directly in the application resources directory, the specified file path can simply be the name of the file.
The build method releases loaded POD content from memory once the file content has been extracted and into component objects. As a result, content may not be saved back to file after the build method has been invoked, and this method will raise an assertion error if this method is invoked after content has been released.
The build method is invoked automatically from the loadFromFile: method and several initializer methods that invoke the loadFromFile: method if the shouldAutoBuild property is set to its default YES value. To use this method, initialize this instance with an initializer method that does not invoke the loadFromFile: method, set the shouldAutoBuild property to NO. Then, invoke the loadFromFile: method, make any changes, and invoke this method to save the content back to a file. Once saved, the build method can then be invoked to extract the content into component objects.
| - (BOOL) saveToFile: | (NSString *) | filePath |
Saves the content of this resource to the file at the specified file path and returns whether the saving was successful.
The specified file path may be either an absolute path, or a path relative to the application resource directory. If the file is located directly in the application resources directory, the specified file path can simply be the name of the file.
The build method releases loaded POD content from memory once the file content has been extracted and into component objects. As a result, content may not be saved back to file after the build method has been invoked, and this method will raise an assertion error if this method is invoked after content has been released.
The build method is invoked automatically from the loadFromFile: method and several initializer methods that invoke the loadFromFile: method if the shouldAutoBuild property is set to its default YES value. To use this method, initialize this instance with an initializer method that does not invoke the loadFromFile: method, set the shouldAutoBuild property to NO. Then, invoke the loadFromFile: method, make any changes, and invoke this method to save the content back to a file. Once saved, the build method can then be invoked to extract the content into component objects.
Implements CC3Resource.
| - (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.
|
readwritenonatomicassign |
|
readnonatomicretain |
A collection of all of the nodes extracted from the POD file.
This is the equivalent of flattening the nodes array.
|
readnonatomicassign |
The color of the ambient light in the scene.
|
readnonatomicassign |
The number of frames of animation in the POD file.
|
readnonatomicassign |
The frame rate of animation in the POD file, in frames per second.
|
readnonatomicassign |
The background color of the scene.
|
readnonatomicretain |
The class used to instantiate a bone in a vertex-skinned character.
This implementation returns CC3PODBone. To return a different class, create a subclass and override this method. The returned class must be a subclass of CC3PODBone.
|
readnonatomicretain |
The class used to instantiate a camera.
This implementation returns CC3PODCamera. To return a different class, create a subclass and override this method. The returned class must be a subclass of CC3PODCamera.
|
readnonatomicassign |
The number of cameras in the POD file.
This is a transient property that returns a valid value only during node building. Once node building is complete, this property will return zero.
|
readnonatomicretain |
The class used to instantiate a light.
This implementation returns CC3PODLight. To return a different class, create a subclass and override this method. The returned class must be a subclass of CC3PODLight.
|
readnonatomicassign |
The number of lights in the POD file.
This is a transient property that returns a valid value only during node building. Once node building is complete, this property will return zero.
|
readnonatomicretain |
The class used to instantiate a material.
This implementation returns CC3PODMaterial. To return a different class, create a subclass and override this method. The returned class must be a subclass of CC3PODMaterial.
|
readnonatomicassign |
The number of materials in the POD file.
This is a transient property that returns a valid value only during node building. Once node building is complete, this property will return zero.
|
readnonatomicretain |
A collection of the CC3Materials extracted from the POD file.
|
readnonatomicretain |
The class used to instantiate a mesh.
This implementation returns CC3PODMesh. To return a different class, create a subclass and override this method. The returned class must be a subclass of CC3PODMesh.
|
readnonatomicassign |
The number of meshes in the POD file.
This is a transient property that returns a valid value only during node building. Once node building is complete, this property will return zero.
|
readnonatomicretain |
A collection of the CC3Meshs extracted from the POD file.
|
readnonatomicretain |
The class used to instantiate a mesh node.
This implementation returns CC3PODMeshNode. To return a different class, create a subclass and override this method. The returned class must be a subclass of CC3PODMeshNode.
|
readnonatomicassign |
The number of mesh nodes in the POD file.
This is a transient property that returns a valid value only during node building. Once node building is complete, this property will return zero.
|
readnonatomicassign |
The total number of nodes of all types in the POD file.
This is a transient property that returns a valid value only during node building. Once node building is complete, this property will return zero.
|
readnonatomicretain |
The class used to create CC3PFXResource instances to read PFX files.
PFX effects found in PFX resource files can be used to define the GLSL shaders and textures that are to be applied to a POD model under OpenGL ES 2.0. Each material in the POD file can optionally specify a PFX effect and the PFX file in which it is to be found.
This implementation returns CC3PFXResource. To return a different class, create a subclass and override this method. The returned class must be a subclass of CC3PFXResource.
|
readnonatomicassign |
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.
|
readwritenonatomicassign |
Indicates whether the build method should be invoked automatically when the file is loaded.
The initial value of this property is YES. This property must be set before the loadFromFile: method is invoked. Be aware that the loadFromFile: method is automatically invoked automatically by several instance initializers. To use this property, initialize this instance with an initializer method that does not invoke the loadFromFile: method.
|
readnonatomicretain |
The class used to instantiate a mesh node in a vertex-skinned character.
This implementation returns CC3PODSkinMeshNode. To return a different class, create a subclass and override this method. The returned class must be a subclass of CC3PODSkinMeshNode.
|
readnonatomicretain |
The class used to instantiate a wrapper node around a vertex-skinned character.
This implementation returns CC3SoftBodyNode. To return a different class, create a subclass and override this method. The returned class must be a subclass of CC3SoftBodyNode.
|
readnonatomicretain |
The class used to instantiate a structural node.
Structural nodes are used to group mesh nodes together.
This implementation returns CC3PODNode. To return a different class, create a subclass and override this method. The returned class must be a subclass of CC3PODNode.
|
readnonatomicassign |
The number of textures in the POD file.
This is a transient property that returns a valid value only during node building. Once node building is complete, this property will return zero.
|
readnonatomicretain |
A collection of the CC3Textures extracted from the POD file.