Materials - cocos3d/cocos3d GitHub Wiki

A material covers a mesh and provides a visual appearance for the surface of the mesh.

In Cocos3D, a material is represented by the CC3Material class, which contains a number of properties and methods to modify the visual aspects of the mesh surface, including:

• Surface colors, including ambient, diffuse, specular and emission colours.
• One or more textures covering the mesh, and how they interact.
• Interaction with lighting.
• Opacity and blending with previously rendered content.

Within your 3D scene, each mesh node holds a single material, and the material covers all vertices within the mesh. For more sophisticated models that require coverage by more than one material, the model must be broken into separate mesh nodes, one per material, with the individual mesh nodes then assembled into a structural node assembly.

In general, each mesh node maintains a unique material instance. However, you can also share a single material across several separate mesh nodes. This can sometimes make it easier to configure and modify the look of a number of nodes simultaneously.

There are two mechanisms for changing the coloring and opacity of a material covering a mesh node.

• To achieve the highest level of detail, accuracy and realism, you can individually set the explicit ambientColor, diffuseColor, specularColor, emissiveColor, shininess, sourceBlend, and destinationBlend properties. This suite of properties gives you the most complete control over the appearance of the material and its interaction with lighting conditions and the colors of the objects behind it, allowing you to generate rich visual effects.

• At a simpler level, CC3Material also supports the Cocos2D properties color and opacity. You can use these properties to set the most commonly used coloring and blending characteristics simply and easily. Setting the color property changes both the ambientColor and diffuseColor properties of the material in tandem (or the emissionColor property if lighting is not enabled on the material). Setting the opacity property also automatically sets the source and destination blend functions to appropriate values for the opacity level. By using the color and opacity properties, you will not be able to achieve the complexity and realism that you can by using the more detailed properties, but you can achieve good effect with much less effort. And by supporting these properties, the coloring and translucency of nodes with materials can be changed using standard Cocos2D CCActionTint... and CCActionFade... actions, making it easier for you to add dynamic coloring and fading effects to your nodes.

---

####Textures

Textures can be added to a material to provide very detailed coloring and surface detail information to the mesh. Textures can be used to provide details about color, or per-pixel lighting and surface normal information.

You add textures to a material using the texture property or the addTexture: method. These textures are then made available to the shaders, where their purpose and visual effect is interpreted and realized.

In Cocos3D, textures are represented by the CC3Texture class. This is actually the parent class of a class-cluster that provide basic 2D textures, cube-map textures, and PVR textures (which may be either 2D or cube-mapped).

Note: The CC3Texture class should not be confused with the CCTexture class from Cocos2D. Both of these classes represent textures, but are not interchangeable. This is because Cocos3D requires more substantial texture behaviour, including cube textures. However, if you have an instance of a CC3Texture, you can extract a compatible instance of a Cocos2D CCTexture from it using the ccTexture property.

Textures can be instantiated from content held in files, or from existing CGImageRef objects. The CC3Texture class defines a number of instance creation methods that provide this functionality, including several convenience methods for simplifying the loading of cube-map textures.

Note: When building for iOS, raw PNG and TGA images are pre-processed by Xcode to pre-multiply the alpha into the color components, and to reorder the pixel component byte order. This is done to optimize the image for the iOS platform. If you want to avoid this pre-processing for PNG or TGA files, for textures such as normal maps or lighting maps, that you don't want to be modified, you can prepend a 'p' to the file extension (ppng or ptga) to cause Xcode to skip this pre-processing and to have Cocos3D use a texture loader that does not pre-multiply the alpha. You can also use this for other file types as well. See the notes for the CC3STBImage useForFileExtensions class-side property for more info.

##### Texture Caching

Textures loaded from files are cached, and repeatedly loading the same texture file will not actually cause the texture file to be loaded over and over. Once the texture file has been loaded once, subsequent calls to load it will retrieve it from the cache.

For convenience, the texture cache is automatically cleared at the end of the each thread loop of any textures that are not being used in the scene, or otherwise retained elsewhere.

If you want to load the same texture file repeatedly, without having to ensure that it is retained somewhere, you can arrange to have that texture permanently cached if you set the class-sideCC3Texture.isPreloading property to YES prior to loading the texture file as described above, to indicate that you are pre-loading the texture and wish it to be cached permanently, until you remove it from the cache manually. You can subsequently set the isPreloading property to NO, to allow future textures to be loaded and cleared from the cache when no longer part of the scene.