English
资源说明：cocos3d for iPhone
README - cocos3d 0.6.4
----------------------
cocos3d 0.6.4
Copyright (c) 2010-2011 The Brenwill Workshop Ltd. All rights reserved.
http://www.brenwill.com
+++++++++++++++++++++++++++++++++++
Table of Contents
-----------------
- Installation
- cocos2d Version Compatibility
- Creating Your First cocos3d Project
- Documentation
- Demo Applications
- Demo Models
- Creating POD 3D Model Files
- PowerVR Library
Installation
------------
The cocos3d framework is built on cocos2d. Before installing cocos3d,
you must download and install the cocos2d SDK from
http://www.cocos2d-iphone.org/download
Unzip the cocos3d distribution file (which you've probably already done,
otherwise you wouldn't be reading this document).
Open a Terminal session, navigate to the unzipped cocos3d distribution
directory and run the install-cocos3d script as follows:
./install-cocos3d.sh -u -f -2 "relative-path-to-cocos2d-sources"
For example:
./install-cocos3d.sh -u -f -2 "../../cocos2d/cocos2d-iphone-1.0.0"
The cocos2d source code must be available and identified using the -2 switch
so that the installer can copy the cocos2d libraries to the cocos3d templates
and demo projects.
That's it!
cocos2d Version Compatibility
-----------------------------
cocos3d 0.6.4 is compatible with cocos2d versions 0.99.5 through 1.1.
At the time of this release, the current version of cocos2d is 1.0.1, and by default, cocos3d is
configured to use that version. This section includes notes on compatibility with other versions.
cocos2d 1.1
-----------
Version 1.1 of cocos2d introduced a change to the structure used for 2D particles.
When running cocos2d 1.1 set the following build setting in your Xcode build configuration:
CC_USES_2D_PARTICLES=0
You can set this in your Xcode project build settings in the Preprocessor Macros entry.
This applies to any cocos3d project, including the demo projects that are included in the
cocos3d distribution and the cocos3d project templates.
cocos2d 0.9.5
-------------
Version 0.99.5 of cocos2d contains several files that were removed in cocos2d 1.0,
These files are not included in the cocos3d Xcode demo apps and project templates.
When using cocos2d 0.9.5, drag the following files to the cocos2d group within the Xcode project:
cocos2d/CCCompatibility.h
cocos2d/CCCompatibility.m
cocos2d/CCSpriteSheet.h
cocos2d/CCSpriteSheet.m
TouchJSON/Extensions/NSCharacterSet_Extensions.h
TouchJSON/Extensions/NSCharacterSet_Extensions.m
TouchJSON/Extensions/NSScanner_Extensions.h
TouchJSON/Extensions/NSScanner_Extensions.m
Because of the modular nature of Xcode 4 project templates, the cocos3d Xcode 4 template
project uses whichever cocos2d Xcode 4 project templates were installed. Typically this
will be the cocos2d 1.0.0 project templates, unless you have created cocos2d 0.99.5
Xcode 4 project templates.
Creating Your First cocos3d Project
-----------------------------------
To get started with your first cocos3d project, open Xcode 4, click on the
File->New->NewProject... menu selection, and select the 'cocos3d Application'
project template from the cocos3d template group.
The template project starts with a working 3D variation on the familiar
'hello, world' application, and you can use it as a starting point for
your own application.
Documentation
-------------
The cocos3d Programming Guide is online at:
http://brenwill.com/2011/cocos3d-programming-guide/.
The API documentation is online at:
http://brenwill.com/docs/cocos3d/0.6.4/api/
You can create a local copy of the API documentation using Doxygen to extract the
documentation from the source files. There is a Doxygen configuration file to output
the API documents in the same format as appears online in the folder Docs/API within
the cocos3d distribution.
Demo Applications
-----------------
To help get you learn how to work with cocos3d, several demo apps are included in
the cocos3d distribution. These demos will help you understand how to use cocos3d,
and demonstrate many of the key features and capabilities of cocos3d.
For convenience, to access all of the demos together, open the 'cocos3d.xcworkspace'
Xcode workspace. You can also open each demo project individually in the Demos folder.
If you are using cocos2d 0.99.5, read the cocos2d Version Compatibility selection
below regarding running the demo apps with that version.
The following demo apps are included in the cocos3d distribution:
CC3DemoMashUp
-------------
Your camera hovers over a virtual world that includes animated robots, bouncing beach-balls,
spinning globes, and a selection of animated teapots. This is a sophisticated demo that
showcases many interesting features of cocos3d, including:
- loading mesh models, cameras and lights from 3D model files stored in the PowerVR POD format
- creating mesh models from static header file data
- sharing mesh data across several nodes with different materials
- loading 3D models from a POD file converted from a Collada file created in a 3D editor (Blender)
- assembling nodes into a hierarchical parent-child structual assembly.
- texturing a 3D mesh from a CCTexture2D image
- texturing a mesh using UV coordinates exported from a 3D editor
- transparency and alpha-blending
- coloring a mesh with a per-vertex color blend
- multi-texturing an object using texture units by combining several individual textures into overlays
- DOT3 bump-map texturing of an object to provide high-resolution surface detail on a model
with few actual vertices
- Vertex skinning with a soft-body mesh bending and flexing based on the movement of skeleton bone nodes.
- Copying soft-body nodes to create a completely separate character, with its own skeleton, that can be
manipulated independently of the skeleton of the original.
- animating 3D models using a variety of standard cocos2d CCActionIntervals
- overlaying the 3D world with 2D cocos2d controls such as joysticks and buttons
- embedding 2D cocos2d text labels into the 3D world
- incorporating 2D cocos2d CCParticleEmitters into the 3D world (as a sun and explosion fire)
- emitting 3D point particles from a moving nozzle, with realistic distance attenuation
- creating a tightly focused spotlight whose intensity attenuates with distance
- directing the 3D camera to track a particular target object
- directing an object to track the camera, always facing (looking at) the camera (aka halo objects)
- directing an object to track another object, always facing (looking at) that object
- selecting a 3D object by touching the object on the screen with a finger
- placing a 3D object on another at a point that was touched with a finger
- adding a small CC3Layer/CC3World pair as a child window to a larger CC3Layer/CC3World pair.
- moving, scaling and fading a CC3Layer and its CC3World
- creating parametric boxes and texturing all six sides of the box with a single texture.
- adding an object as a child of another, but keeping the original orientation of the child
(addAndLocalizeChild:)
- handling touch-move events to create swipe gestures to spin a 3D object using rotation
around an arbitrary axis
- toggling between opacity and translucency using the isOpaque property
- choosing to cull or display backfaces (shouldCullBackFaces)
- creating and deploying many independent copies of a node, while sharing the underlying mesh data
- drawing a descriptive text label on a node using CC3Node shouldDrawDescriptor property.
- drawing a wireframe bounding box around a node using CC3Node shouldDrawWireframeBox property.
- automatically zooming the camera out to view all objects in the world
- constructing and drawing a highly tessellated rectangular plane mesh using CC3PlaneNode
- caching mesh data into GL vertex buffer objects and releasing vertex data from application memory
- retaining vertex location data in application memory (retainVertexLocations) for subsequent calculations
- moving the pivot location (origin) of a mesh to the center of geometry of the mesh.
- attaching application-specific userData to any node
- applying a texture to all six sides of a parametric box
- displaying direction marker lines on a node to clarify its orientation during development.
In addition, there are a number of interesting options for you to play with by uncommenting
certain lines of code in the methods of this class that build objects in the 3D world,
including experimenting with:
- simple particle generator with multi-colored, light-interactive, particles
- different options for ordering nodes when drawing, including ordering by mesh or texture
- translucent and transparent textures (addFloatingRing)
- configuring the camera for parallel/isometric/orthographic projection instead of the default
perpective projection
- mounting the camera on a moving object, in this case a bouncing ball
- mounting the camera on a moving object, in this case a bouncing ball, and having the
camera stay focused on the rainbow teapot as both beach ball and teapot move and rotate
- directing an object to track another object, always facing that object, but only
rotating in one direction (eg- side-to-side, but not up and down).
- displaying 2D labels (eg- health-bars) overlayed on top of the 3D world at locations projected from the position of 3D objects
- disabling animation for a particular node, in this case the camera and light
- invading with an army of teapots instead of robots
- ignore lighting conditions when drawing a node to draw in pure colors and textures
- initializing and disposing of users data by adding initUserData and releaseUserData method extension categories.
- displaying descriptive text and wireframe bounding boxes on every node
- displaying a dynamic bounding box on a 3D particle emitter.
- making use of a fixed bounding volume for the 3D particle emitter to improve performance.
- displaying a repeating texture pattern across a mesh
CC3Performance
--------------
This is a simple demo of the performance characteristics of cocos3d. It demonstrates
how to collect statistics about your application's performance. In doing so, it
presents a number of model scenarios, and through the user interface, you can control
the type of model loaded and how many copies to render.
You can dynamically experiment with how different model types, sizes and quantities
affects the performance of cocos3d. You can also use this performance demo app to
compare performance across different device types.
CC3Demo3DTiles
--------------
A simple demo that lays out multiple small cocos3d worlds as layers in a larger cocos2d
layer. The effect is a grid of tiles, with each tile displaying a separate 3D world,
each containing its own camera and lighting. The main node in each 3D tile can be rotated
under touch control.
This demonstrates the ability to simply include 3D objects in an otherwise 2D game,
and techniques for optimizing under those conditions. It also demonstrates touch control
when many 3D world are visible concurrently, and the ability to add app data to nodes
using the userData property.
The CC3Demo3DTiles demo app also demonstrates the use of the cocos2d RootController with cocos3d.
If you are using cocos2d 1.1 or 0.99.5, read the cocos2d Version Compatibility selection below
regarding running the demo apps with that version.
Demo Models
-----------
Some of the POD models that appear in the demo and template apps were designed in Blender,
exported to DAE, and converted to POD files using the PowerVR Collada2POD converter.
As a reference for the creation of your own 3D models for use in cocos3d, you can find
the original Blender files and DAE files for these POD models in the Models folder in
the cocos3d distribution.
Creating POD 3D Model Files
---------------------------
The PowerVR SDK contains tools for converting from a limited number of 3D editor export
files. The PVR SDK is available free from Imagination Technologies, the supplier of the
GPU's used in iOS devices. You can download the PowerVR SDK from:
http://www.imgtec.com/powervr/insider/sdk/KhronosOpenGLES1xMBX.asp
If you are using Blender (or any 3D editor), you can export your 3D model to a file in
Collada 1.4 format, and used the Collada2POD converter tool (GUI or command line) in the
PVR SDK to convert the Collada file to POD format.
For convenience, when using the Collada2POD tool, you can use the settings in the
Tools/Collada2PODSettings.txt file in the cocos3d distribution. When using the
Collada2POD GUI converter, please be aware that the tool does not store the setting
for the Invert Transparency flag. This flag must be turned on each time you use the
GUI tool to avoid having all your models disappear.
Please also note that the Collada2POD tool rotates data so that the Z-axis is 'up'.
Since the OpenGL ES default is to have the Y-axis as up, and the camera looking down
the -Z-axis, it is usually more convenient to use the OpenGL orientation in cocos3d
(although there's nothing to stop you from rotating everything by 90 degrees in cocos3d).
With this in mind, when using Blender, and exporting to POD via Collada, orient your
model world so that 'up' is along the Z-axis (which is the Blender default anyway).
The Collada2POD tool will then rotate the axes so that 'up' is along the Y-axis when
the model is imported into cocos3d.
PowerVR Library
---------------
In order to reduce the size of the cocos3d distribution, several large and
unused files have been removed from the PVR library. More info can be found
in the document: 'cocos3d/cc3PVR/PVRT 2.08/PVRT_Removed_Files.txt'.
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
