A CC3Node that draws a 3D mesh model. More...
#import <CC3MeshNode.h>
Public Member Functions | |
| (void) | - drawLocalContentWithVisitor: |
| (void) | - populateAsCenteredRectangleWithSize: |
| (void) | - populateAsCenteredRectangleWithSize:withTexture:invertTexture: |
| (void) | - populateAsLineStripWith:vertices:andRetain: |
| (void) | - populateAsRectangleWithSize:andPivot: |
| (void) | - populateAsRectangleWithSize:andPivot:withTexture:invertTexture: |
| (void) | - populateAsSolidBox: |
| (void) | - populateAsWireBox: |
Properties | |
| ccColor4F | ambientColor |
| ccColor3B | color |
| ccColor4F | diffuseColor |
| ccColor4F | emissionColor |
| BOOL | isOpaque |
| CC3Material * | material |
| CC3MeshModel * | meshModel |
| GLubyte | opacity |
| ccColor4F | pureColor |
| BOOL | shouldCullBackFaces |
| BOOL | shouldCullFrontFaces |
| ccColor4F | specularColor |
Detailed Description
A CC3Node that draws a 3D mesh model.
This class forms the base of all visible 3D mesh models in the 3D world.
CC3MeshNode is a type of CC3Node, and will often participate in a structural node assembly. An instance can be the child of another node, and the mesh node itself can have child nodes.
CC3MeshNodes encapsulate a CC3MeshModel instance, and can also encapsulate either a CC3Material instance, or a pure color. The CC3MeshModel instance contains the mesh vertex data. The CC3Material instance describes the material and texture properties covering the mesh, which are affected by lighting conditions. Alternately, instead of a material, the mesh may be colored by a single pure color via the pureColor property.
When this node is drawn, it delegates to the mesh model instance to render the mesh vertices. If a material is defined, before drawing the mesh, it delegates to the material to configure the covering of the mesh. If no material is defined, the node establishes its pure color before rendering the mesh. The pure color is only used if the node has no material attached. And the pure color may in turn be overridden by the mesh data if vertex coloring is in use.
Each CC3MeshNode can have only one material or pure color. For large, complicated meshes that are covered by more than one material, or colored with more than one color, the mesh must be broken into smaller meshes, each of which are covered by a single material or color. These smaller sub-meshes are sometimes referred to as "vertex groups". Each such sub-mesh is then wrapped in its own CC3MeshNode instance, along with the material that covers that sub-mesh.
These CC3MeshNode instances can then be added as child nodes to a single parent CC3Node instance. This parent CC3Node can then be moved, rotated and scaled, and all of its child nodes will transform in sync. The assembly will behave and be seen as a single object.
When the mesh model is set in the meshModel property, the CC3MeshNode instance creates and builds a CC3NodeBoundingVolume instance from the mesh data, and sets it into its boundingVolume property.
When a copy is made of a CC3MeshNode instance using the copy method, a copy is made of the material, but the mesh model is simply assigned by reference, and is not copied. The result is that the the new and original nodes will have different materials, but will share the same mesh model. This design avoids creating multiple copies of volumnious and static mesh data when creating copies of nodes.
Normally, the front faces of a mesh are displayed, and the back faces are culled and not displayed. You can change this behaviour if you need to be changing the values of the shouldCullFrontFaces and shouldCullBackFaces properties. An example might be if you wanted to show the back-side of a planar sign, or if you wanted to show the inside faces of a skybox.
However, be aware that culling is a significant performance-improving technique. You should avoid disabling backface culling except where specifically needed for visual effect. And when you do, if you only need the back faces, turn on front face culling for that mesh by setting the shouldCullFrontFaces property to YES.
Member Function Documentation
| - (void) drawLocalContentWithVisitor: | (CC3NodeDrawingVisitor *) | visitor |
Draws the local content of this mesh node by following these steps:
- If the shouldDecorateNode property of the visitor is YES, and this node has a material, invokes the draw method of the material.
Otherwise, invokes the CC3Material class-side unbind method.
- Invokes the drawWithVisitor: method of the encapsulated mesh model.
This method is called automatically from the transformAndDrawWithVisitor: method of this node. Usually, the application never needs to invoke this method directly.
| - (void) populateAsCenteredRectangleWithSize: | (CGSize) | rectSize |
Populates this instance as a simple rectangular mesh of the specified size, centered at the origin, and laid out on the X-Y plane.
You can add a material or pureColor as desired to establish how the look of the rectangle.
As this node is translated, rotate and scaled, the rectangle will be re-oriented in 3D space.
This is a convenience method for creating a simple, but useful shape, which can be used to create walls, floors, signs, etc.
| - (void) populateAsCenteredRectangleWithSize: | (CGSize) | rectSize | |
| withTexture: | (CC3Texture *) | texture | |
| invertTexture: | (BOOL) | shouldInvert | |
Populates this instance as a simple textured rectangular mesh of the specified size, centered at the origin, and laid out on the X-Y plane.
The shouldInvert flag indicates whether the texture should be inverted when laid out on the mesh. Some textures appear inverted after loading under iOS. This flag can be used to compensate for that by reinverting the texture to the correct orientation.
As this node is translated, rotate and scaled, the textured rectangle will be re-oriented in 3D space.
This is a convenience method for creating a simple, but useful shape, which can be used to create walls, floors, etc.
| - (void) populateAsLineStripWith: | (GLshort) | vertexCount | |
| vertices: | (CC3Vector *) | vertices | |
| andRetain: | (BOOL) | shouldRetainVertices | |
Populates this instance as a line strip with the specified number of vertex points.
The data for the points that define the end-points of the lines are contained within the specified vertices array. The vertices array must contain at least vertexCount elements.
The lines are specified and rendered as a strip, where each line is connected to the previous and following lines. Each line starts at the point where the previous line ended, and that point is defined only once in the vertices array. Therefore, the number of lines drawn is equal to one less than the specified vertexCount.
The shouldRetainVertices flag indicates whether the data in the vertices array should be retained by this instance. If this flag is set to YES, the data in the vertices array will be copied to an internal array that is managed by this instance. If this flag is set to NO, the data is not copied internally and, instead, a reference to the vertices data is established. In this case, it is up to you to manage the lifespan of the data contained in the vertices array.
If you are defining the vertices data dynamically in another method, you may want to set this flag to YES to have this instance copy and manage the data. If the vertices array is a static array, you can set this flag to NO.
You can add a material or pureColor as desired to establish the color of the lines. If a material is used, the appearance of the lines will be affected by the lighting conditions. If a pureColor is used, the appearance of the lines will not be affected by the lighting conditions, and the wire-frame box will always appear in the same pure, solid color, regardless of the lighting sources.
As this node is translated, rotate and scaled, the line strip will be re-oriented in 3D space.
This is a convenience method for creating a simple, but useful, shape.
| - (void) populateAsRectangleWithSize: | (CGSize) | rectSize | |
| andPivot: | (CGPoint) | pivot | |
Populates this instance as a simple rectangular mesh of the specified size, with the specified pivot point at the origin, and laid out on the X-Y plane.
You can add a material or pureColor as desired to establish how the look of the rectangle.
The pivot point can be any point within the rectangle's size. For example, if the pivot point is {0, 0}, the rectangle will be laid out so that the bottom-left corner is at the origin. Or, if the pivot point is in the center of the rectangle's size, the rectangle will be laid out centered on the origin, as in the populateAsCenteredRectangleWithSize method.
As this node is translated, rotate and scaled, the rectangle will be re-oriented in 3D space.
This is a convenience method for creating a simple, but useful shape, which can be used to create walls, floors, signs, etc.
| - (void) populateAsRectangleWithSize: | (CGSize) | rectSize | |
| andPivot: | (CGPoint) | pivot | |
| withTexture: | (CC3Texture *) | texture | |
| invertTexture: | (BOOL) | shouldInvert | |
Populates this instance as a simple textured rectangular mesh of the specified size, with the specified pivot point at the origin, and laid out on the X-Y plane.
The pivot point can be any point within the rectangle's size. For example, if the pivot point is {0, 0}, the rectangle will be laid out so that the bottom-left corner is at the origin. Or, if the pivot point is in the center of the rectangle's size, the rectangle will be laid out centered on the origin, as in the populateAsCenteredRectangleWithSize:withTexture: method.
The shouldInvert flag indicates whether the texture should be inverted when laid out on the mesh. Some textures appear inverted after loading under iOS. This flag can be used to compensate for that by reinverting the texture to the correct orientation.
As this node is translated, rotate and scaled, the textured rectangle will be re-oriented in 3D space.
This is a convenience method for creating a simple, but useful shape, which can be used to create walls, floors, etc.
| - (void) populateAsSolidBox: | (CC3BoundingBox) | box |
Populates this instance as a simple rectangular box mesh from the specified bounding box, which contains two of the diagonal corners.
You can add a material or pureColor as desired to establish how the look of the box.
To add a texture, add a material to this node, then add a CC3Texture instance to that material. You must also add an instance of CC3VertexTextureCoordinates to the mesh model of this node, and populate it with the texture coordinate mapping data.
The mesh model uses interleaved data, so when populating the texture coordinate data, set the elements property of the CC3VertexTextureCoordinates instance to the same as the elements property of the CC3VertexLocations instance from the vertexLocations property of the mesh model. Then insert the texture coordinate data into that interleaved vertex data. Each element of that interleaved elements array is a CCTexturedVertex structure, which contains the combined location, normal, and texture coordinate data for a single vertex. For more on how to do this, see the implementation of this method and take note of how this is done with the normal data.
As this node is translated, rotate and scaled, the rectangle will be re-oriented in 3D space.
This is a convenience method for creating a simple, but useful shape, which can be used to create simple structures in your 3D world.
| - (void) populateAsWireBox: | (CC3BoundingBox) | box |
Populates this instance as a wire-frame box with the specified dimensions.
You can add a material or pureColor as desired to establish the color of the lines of the wire-frame. If a material is used, the appearance of the lines will be affected by the lighting conditions. If a pureColor is used, the appearance of the lines will not be affected by the lighting conditions, and the wire-frame box will always appear in the same pure, solid color, regardless of the lighting sources.
As this node is translated, rotate and scaled, the wire-frame box will be re-oriented in 3D space.
This is a convenience method for creating a simple, but useful, shape.
Property Documentation
- (ccColor4F) ambientColor [read, write, assign] |
The ambient color of the material of this mesh node.
Material color is initially set to kCC3DefaultMaterialColorAmbient. If this instance has no material, this property will return kCCC4FBlackTransparent.
The value of this property is also affected by changes to the color and opacity properties. See the notes for those properties for more information.
Implements CC3Node.
- (ccColor3B) color [read, write, assign] |
Implementation of the CCRGBAProtocol color property.
Querying this property returns the RGB components of the material's diffuseColor property, or of this node's pureColor property if this node has no material. In either case, the RGB values are converted from the floating point range (0 to 1), to the byte range (0 to 255).
When setting this property, the RGB values are each converted to a floating point number between 0 and 1, and are set into both the ambientColor and diffuseColor properties of this node's material, and the pureColor property of this node. The alpha of each of those properties remains unchanged.
Setting this property also sets the same property on all descendant nodes.
Implements CC3Node.
- (ccColor4F) diffuseColor [read, write, assign] |
The diffuse color of the material of this mesh node.
Material color is initially set to kCC3DefaultMaterialColorDiffuse. If this instance has no material, this property will return kCCC4FBlackTransparent.
The value of this property is also affected by changes to the color and opacity properties. See the notes for those properties for more information.
Implements CC3Node.
- (ccColor4F) emissionColor [read, write, assign] |
The emission color of the material of this mesh node.
Material color is initially set to kCC3DefaultMaterialColorEmission. If this instance has no material, this property will return kCCC4FBlackTransparent.
The value of this property is also affected by changes to the opacity property. See the notes for the opacity property for more information.
Implements CC3Node.
- (BOOL) isOpaque [read, write, assign] |
Indicates whether the material of this mesh node is opaque.
If this node has a material, returns the value of the same property on the material. If this node has no material, return YES if the alpha component of the pureColor property is 1.0, otherwise returns NO.
Setting this property sets the same property in the material and in all descendants, and sets the alpha component of the pureColor property to 1.0.
See the notes for this property on CC3Material for more information on how this property interacts with the other material properties.
Setting this property should be thought of as a convenient way to switch between the two most common types of blending combinations. For finer control of blending, set specific blending properties on the CC3Material instance directly, and avoid making changes to this property.
Implements CC3Node.
- (CC3Material *) material [read, write, retain] |
The material covering this mesh node.
- (CC3MeshModel *) meshModel [read, write, retain] |
The mesh model that holds the vertex data for this mesh node.
When this property is set, if this node has a boundingVolume, it is forced to rebuild itself, otherwise, if this node does not have a boundingVolume, a default bounding volume is created from the mesh model.
- (GLubyte) opacity [read, write, assign] |
Implementation of the CCRGBAProtocol opacity property.
Querying this property returns the alpha component of the material's diffuseColor property, or of this node's pureColor property if this node has no material. In either case, the RGB values are converted from the floating point range (0 to 1), to the byte range (0 to 255).
When setting this property, the value is converted to a floating point number between 0 and 1, and is set into all of the ambientColor, diffuseColor, specularColor, and emissionColor properties of this node's material, and the pureColor property of this node The RGB components of each of those properties remains unchanged.
Setting this property also sets the same property on all descendant nodes.
See the notes for this property on CC3Material for more information on how this property interacts with the other material properties.
Setting this property should be thought of as a convenient way to switch between the two most common types of blending combinations. For finer control of blending, set specific blending properties on the CC3Material instance directly, and avoid making changes to this property.
Implements CC3Node.
- (ccColor4F) pureColor [read, write, assign] |
The pure, solid color used to paint the mesh if no material is established for this node.
This color is not not be affected by the lighting conditions. The mesh will always appear in the same pure, solid color, regardless of the lighting sources.
- (BOOL) shouldCullBackFaces [read, write, assign] |
Indicates whether the back faces of the mesh should be culled.
The initial value is YES, indicating that back faces will not be displayed. You can set this property to NO if you have reason to display the back faces of the mesh (for instance, if you have a rectangular plane and you want to show both sides of it).
Since the normal of the face points out the front face, back faces interact with light the same way the front faces do, and will appear luminated by light that falls on the front face, much like a stained-glass window. This may not be the affect that you are after, and for some lighting conditions, instead of disabling back face culling, you might consider creating a second textured front face, placed back-to-back with the original front face.
Be aware that culling improves performance, so this property should be set to NO only when specifically needed for visual effect, and only on the meshes that need it.
Implements CC3Node.
- (BOOL) shouldCullFrontFaces [read, write, assign] |
Indicates whether the front faces of the mesh should be culled.
The initial value is NO. Normally, you should leave this property with the initial value, unless you have a specific need not to display the front faces.
Implements CC3Node.
- (ccColor4F) specularColor [read, write, assign] |
The specular color of the material of this mesh node.
Material color is initially set to kCC3DefaultMaterialColorSpecular. If this instance has no material, this property will return kCCC4FBlackTransparent.
The value of this property is also affected by changes to the opacity property. See the notes for the opacity property for more information.
Implements CC3Node.
The documentation for this class was generated from the following file:
