Inherits from CC3NodesResource : CC3Resource : CC3Identifiable : NSObject
Declared in CC3PODResource.h
CC3PODResource.mm

Overview

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: –# 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.

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.

Tasks

Other Methods

Other Methods

Properties

__deprecated

@deprecated Use the CC3Texture class-side property defaultTextureParameters instead.

@property (nonatomic, assign) ccTexParams textureParameters __deprecated

Declared In

CC3PODResource.h

allNodes

A collection of all of the nodes extracted from the POD file. This is the equivalent of flattening the nodes array.

@property (nonatomic, retain, readonly) NSArray *allNodes

Declared In

CC3PODResource.h

ambientLight

The color of the ambient light in the scene.

@property (nonatomic, readonly) ccColor4F ambientLight

Declared In

CC3PODResource.h

animationFrameCount

The number of frames of animation in the POD file.

@property (nonatomic, readonly) GLuint animationFrameCount

Declared In

CC3PODResource.h

animationFrameRate

The frame rate of animation in the POD file, in frames per second.

@property (nonatomic, readonly) GLfloat animationFrameRate

Declared In

CC3PODResource.h

backgroundColor

The background color of the scene.

@property (nonatomic, readonly) ccColor4F backgroundColor

Declared In

CC3PODResource.h

boneNodeClass

The class used to instantiate a bone in a vertex-skinned character.

@property (nonatomic, retain, readonly) Class boneNodeClass

Discussion

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.

Declared In

CC3PODResource.h

cameraClass

The class used to instantiate a camera.

@property (nonatomic, retain, readonly) Class cameraClass

Discussion

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.

Declared In

CC3PODResource.h

cameraCount

The number of cameras in the POD file.

@property (nonatomic, readonly) uint cameraCount

Discussion

This is a transient property that returns a valid value only during node building. Once node building is complete, this property will return zero.

Declared In

CC3PODResource.h

lightClass

The class used to instantiate a light.

@property (nonatomic, retain, readonly) Class lightClass

Discussion

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.

Declared In

CC3PODResource.h

lightCount

The number of lights in the POD file.

@property (nonatomic, readonly) uint lightCount

Discussion

This is a transient property that returns a valid value only during node building. Once node building is complete, this property will return zero.

Declared In

CC3PODResource.h

materialClass

The class used to instantiate a material.

@property (nonatomic, retain, readonly) Class materialClass

Discussion

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.

Declared In

CC3PODResource.h

materialCount

The number of materials in the POD file.

@property (nonatomic, readonly) uint materialCount

Discussion

This is a transient property that returns a valid value only during node building. Once node building is complete, this property will return zero.

Declared In

CC3PODResource.h

materials

A collection of the CC3Materials extracted from the POD file.

@property (nonatomic, retain, readonly) NSArray *materials

Declared In

CC3PODResource.h

meshClass

The class used to instantiate a mesh.

@property (nonatomic, retain, readonly) Class meshClass

Discussion

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.

Declared In

CC3PODResource.h

meshCount

The number of meshes in the POD file.

@property (nonatomic, readonly) uint meshCount

Discussion

This is a transient property that returns a valid value only during node building. Once node building is complete, this property will return zero.

Declared In

CC3PODResource.h

meshNodeClass

The class used to instantiate a mesh node.

@property (nonatomic, retain, readonly) Class meshNodeClass

Discussion

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.

Declared In

CC3PODResource.h

meshNodeCount

The number of mesh nodes in the POD file.

@property (nonatomic, readonly) uint meshNodeCount

Discussion

This is a transient property that returns a valid value only during node building. Once node building is complete, this property will return zero.

Declared In

CC3PODResource.h

meshes

A collection of the CC3Meshs extracted from the POD file.

@property (nonatomic, retain, readonly) NSArray *meshes

Declared In

CC3PODResource.h

nodeCount

The total number of nodes of all types in the POD file.

@property (nonatomic, readonly) uint nodeCount

Discussion

This is a transient property that returns a valid value only during node building. Once node building is complete, this property will return zero.

Declared In

CC3PODResource.h

pfxResourceClass

The class used to create CC3PFXResource instances to read PFX files.

@property (nonatomic, retain, readonly) Class pfxResourceClass

Discussion

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.

Declared In

CC3PODResource.h

pvrtModel

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.

@property (nonatomic, readonly) PODClassPtr pvrtModel

Declared In

CC3PODResource.h

shouldAutoBuild

Indicates whether the build method should be invoked automatically when the file is loaded.

@property (nonatomic, assign) BOOL shouldAutoBuild

Discussion

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.

Declared In

CC3PODResource.h

skinMeshNodeClass

The class used to instantiate a mesh node in a vertex-skinned character.

@property (nonatomic, retain, readonly) Class skinMeshNodeClass

Discussion

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.

Declared In

CC3PODResource.h

softBodyNodeClass

The class used to instantiate a wrapper node around a vertex-skinned character.

@property (nonatomic, retain, readonly) Class softBodyNodeClass

Discussion

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.

Declared In

CC3PODResource.h

structuralNodeClass

The class used to instantiate a structural node.

@property (nonatomic, retain, readonly) Class structuralNodeClass

Discussion

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.

Declared In

CC3PODResource.h

textureCount

The number of textures in the POD file.

@property (nonatomic, readonly) uint textureCount

Discussion

This is a transient property that returns a valid value only during node building. Once node building is complete, this property will return zero.

Declared In

CC3PODResource.h

textures

A collection of the CC3Textures extracted from the POD file.

@property (nonatomic, retain, readonly) NSArray *textures

Declared In

CC3PODResource.h

Instance Methods

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.

- (void)build

Discussion

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 buildMeshes template method – nodes, by invoking the buildNodes template method – a soft body node if needed

This template method can be overridden in a subclass if specialized processing is required.

Declared In

CC3PODResource.h

buildCameraAtIndex:

Builds the cameraIndex'th camera node. Note that cameraIndex is an ordinal number indicating the rank of the camera node.

- (CC3Camera *)buildCameraAtIndex:(uint)cameraIndex

Discussion

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.

Declared In

CC3PODResource.h

buildLightAtIndex:

Builds the lightIndex'th light node. Note that lightIndex is an ordinal number indicating the rank of the light node.

- (CC3Light *)buildLightAtIndex:(uint)lightIndex

Discussion

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.

Declared In

CC3PODResource.h

buildMaterialAtIndex:

Builds the materialIndex'th material. Note that materialIndex is an ordinal number indicating the rank of the material.

- (CC3Material *)buildMaterialAtIndex:(uint)materialIndex

Discussion

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.

Declared In

CC3PODResource.h

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.

- (void)buildMaterials

Discussion

This template method can be overridden in a subclass if specialized processing is required.

Declared In

CC3PODResource.h

buildMeshAtIndex:

Builds the meshIndex'th mesh. Note that meshIndex is an ordinal number indicating the rank of the mesh.

- (CC3Mesh *)buildMeshAtIndex:(uint)meshIndex

Declared In

CC3PODResource.h

buildMeshNodeAtIndex:

Builds the meshIndex'th mesh node. Note that meshIndex is an ordinal number indicating the rank of the mesh node.

- (CC3MeshNode *)buildMeshNodeAtIndex:(uint)meshIndex

Discussion

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.

Declared In

CC3PODResource.h

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.

- (void)buildMeshes

Discussion

This template method can be overridden in a subclass if specialized processing is required.

Declared In

CC3PODResource.h

buildNodeAtIndex:

Builds the node at the specified index. Checks the type of node, and invokes one of the following template methods: – buildMeshNodeAtIndex: – buildLightAtIndex: – buildCameraAtIndex: – buildStructuralNodeAtIndex:

- (CC3Node *)buildNodeAtIndex:(uint)nodeIndex

Discussion

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.

Declared In

CC3PODResource.h

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.

- (void)buildNodes

Discussion

This template method can be overridden in a subclass if specialized processing is required.

Declared In

CC3PODResource.h

buildSceneInfo

Template method that extracts and sets the scene info, including the following properties: – animationFrameCount – animationFrameRate – ambientLight – backgroundColor

- (void)buildSceneInfo

Discussion

This template method can be overridden in a subclass if specialized processing is required.

Declared In

CC3PODResource.h

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.

- (void)buildSoftBodyNode

Declared In

CC3PODResource.h

buildStructuralNodeAtIndex:

Builds the structural node at the specified index.

- (CC3Node *)buildStructuralNodeAtIndex:(uint)nodeIndex

Discussion

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.

Declared In

CC3PODResource.h

buildTextureAtIndex:

Builds the textureIndex'th texture. Note that textureIndex is an ordinal number indicating the rank of the texture.

- (CC3Texture *)buildTextureAtIndex:(uint)textureIndex

Discussion

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.

Declared In

CC3PODResource.h

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.

- (void)buildTextures

Discussion

This template method can be overridden in a subclass if specialized processing is required.

Declared In

CC3PODResource.h

cameraAtIndex:

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.

- (CC3Camera *)cameraAtIndex:(uint)cameraIndex

Declared In

CC3PODResource.h

cameraNodePODStructAtIndex:

Returns the SPODNode structure of the cameraIndex'th light node. Note that cameraIndex is an ordinal number indicating the rank of the camera node.

- (PODStructPtr)cameraNodePODStructAtIndex:(uint)cameraIndex

Discussion

The returned pointer must be cast to SPODNode before accessing any internals of the data structure.

Declared In

CC3PODResource.h

cameraPODStructAtIndex:

Returns cameraIndex'th SPODCamera structure from the data structures.

- (PODStructPtr)cameraPODStructAtIndex:(uint)cameraIndex

Discussion

The returned pointer must be cast to SPODCamera before accessing any internals of the data structure.

Declared In

CC3PODResource.h

createCPVRTModelPOD

- (void)createCPVRTModelPOD

dealloc

- (void)dealloc

deleteCPVRTModelPOD

- (void)deleteCPVRTModelPOD

fullDescription

Returns a string containing a more complete description of this object.

- (NSString *)fullDescription

Discussion

This implementation simply invokes the description method. Subclasses with more substantial content can override to provide much more information.

Declared In

CC3Identifiable.h

init

Initializes this unnamed instance with an automatically generated unique tag value. The tag value will be generated automatically via the method nextTag.

- (id)init

Declared In

CC3Identifiable.h

isBoneNode:

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)isBoneNode:(uint)nodeIndex

Declared In

CC3PODResource.h

isNodeIndex:ancestorOfNodeIndex:

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.

- (BOOL)isNodeIndex:(int)aNodeIndex ancestorOfNodeIndex:(int)childIndex

Declared In

CC3PODResource.h

lightAtIndex:

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.

- (CC3Light *)lightAtIndex:(uint)lightIndex

Declared In

CC3PODResource.h

lightNodePODStructAtIndex:

Returns the SPODNode structure of the lightIndex'th light node. Note that lightIndex is an ordinal number indicating the rank of the light node.

- (PODStructPtr)lightNodePODStructAtIndex:(uint)lightIndex

Discussion

The returned pointer must be cast to SPODNode before accessing any internals of the data structure.

Declared In

CC3PODResource.h

lightPODStructAtIndex:

Returns lightIndex'th SPODLight structure from the data structures.

- (PODStructPtr)lightPODStructAtIndex:(uint)lightIndex

Discussion

The returned pointer must be cast to SPODLight before accessing any internals of the data structure.

Declared In

CC3PODResource.h

materialAtIndex:

Returns the materialIndex'th material. Note that materialIndex is an ordinal number indicating the rank of the material.

- (CC3Material *)materialAtIndex:(uint)materialIndex

Declared In

CC3PODResource.h

materialNamed:

Returns the material with the specified name from the materials array.

- (CC3Material *)materialNamed:(NSString *)aName

Declared In

CC3PODResource.h

materialPODStructAtIndex:

Returns materialIndex'th SPODMaterial structure from the data structures. Note that materialIndex is an ordinal number indicating the rank of the material.

- (PODStructPtr)materialPODStructAtIndex:(uint)materialIndex

Discussion

The returned pointer must be cast to SPODMaterial before accessing any internals of the data structure.

Declared In

CC3PODResource.h

meshAtIndex:

Returns the meshIndex'th mesh. Note that meshIndex is an ordinal number indicating the rank of the mesh.

- (CC3Mesh *)meshAtIndex:(uint)meshIndex

Declared In

CC3PODResource.h

meshModelAtIndex:

@deprecated Renamed to meshAtIndex:.

- (CC3Mesh *)meshModelAtIndex:(uint)meshIndex

Declared In

CC3PODResource.h

meshNodeAtIndex:

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.

- (CC3MeshNode *)meshNodeAtIndex:(uint)meshIndex

Declared In

CC3PODResource.h

meshNodePODStructAtIndex:

Returns the SPODNode structure of the meshIndex'th mesh node. Note that meshIndex is an ordinal number indicating the rank of the mesh node.

- (PODStructPtr)meshNodePODStructAtIndex:(uint)meshIndex

Discussion

The returned pointer must be cast to SPODNode before accessing any internals of the data structure.

Declared In

CC3PODResource.h

meshPODStructAtIndex:

Returns meshIndex'th SPODMesh structure from the data structures. Note that meshIndex is an ordinal number indicating the rank of the mesh.

- (PODStructPtr)meshPODStructAtIndex:(uint)meshIndex

Discussion

The returned pointer must be cast to SPODMesh before accessing any internals of the data structure.

Declared In

CC3PODResource.h

nodeAtIndex:

Returns the node at the specified index in the allNodes array.

- (CC3Node *)nodeAtIndex:(uint)nodeIndex

Declared In

CC3PODResource.h

nodeNamed:

Returns the node with the specified name from the allNodes array.

- (CC3Node *)nodeNamed:(NSString *)aName

Declared In

CC3PODResource.h

nodePODStructAtIndex:

Returns the underlying SPODNode data structure from the POD file, for the SPODNode at the specified index.

- (PODStructPtr)nodePODStructAtIndex:(uint)nodeIndex

Discussion

The returned pointer must be cast to SPODNode before accessing any internals of the data structure.

Declared In

CC3PODResource.h

processFile:

Template method that processes the contents of the file at the specified file path, which must be an absolute file path, and returns whether the file was successfully loaded.

- (BOOL)processFile:(NSString *)anAbsoluteFilePath

Discussion

The application should not invoke this method directly. Use the loadFromFile: method instead.

This implementation does nothing, and returns NO. Concrete subclasses must override this method, and should ensure that the file content is available upon successful completion of this method.

Declared In

CC3Resource.h

pvrtModelImpl

- (CPVRTModelPOD *)pvrtModelImpl

saveAnimationToFile:

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.

- (BOOL)saveAnimationToFile:(NSString *)filePath

Discussion

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.

Declared In

CC3PODResource.h

saveToFile:

Saves the content of this resource to the file at the specified file path and returns whether the saving was successful.

- (BOOL)saveToFile:(NSString *)filePath

Discussion

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.

Declared In

CC3PODResource.h

textureAtIndex:

Returns the textureIndex'th texture. Note that textureIndex is an ordinal number indicating the rank of the texture.

- (CC3Texture *)textureAtIndex:(uint)textureIndex

Declared In

CC3PODResource.h

texturePODStructAtIndex:

Returns textureIndex'th SPODTexture structure from the data structures. Note that textureIndex is an ordinal number indicating the rank of the texture.

- (PODStructPtr)texturePODStructAtIndex:(uint)textureIndex

Discussion

The returned pointer must be cast to SPODTexture before accessing any internals of the data structure.

Declared In

CC3PODResource.h