update/refactor 3d docs

en/3d/advanced.md

@@ -0,0 +1,161 @@
+<div class="langs">
+  <a href="#" class="btn" onclick="toggleLanguage()">中文</a>
+</div>
+
+##Advanced Topics
+
+###BillBoard
+You may not have heard of a `BillBoard` before. No, I'm not talking about an
+advertisement on the side of a highway. Rather, `Billboard` is a special `Sprite`
+that always faces the `Camera`. As you rotate the `Camera`, `Billboard` objects
+also rotate. Using a`BillBoard` is a very common rendering technique. Take for
+example a downhill skiing game. Any trees, rocks or other objects that are in
+the way of the skier are `Billboard` objects.
+
+This is how `Camera` and `Billboard` objects relate to each other.
+
+![](3d-img/BillBoard.png)
+
+`Billboard` objects are easy to create. `BillBoard` is derived from `Sprite`, so
+it supports most of the features as a `Sprite` object. We can create one using the
+following create method:
+
+{% codetabs name="C++", type="cpp" -%}
+auto billboard = BillBoard::create("Blue_Front1.png", BillBoard::Mode::VIEW_POINT_ORIENTED);
+{%- endcodetabs %}
+
+You can also create a `Billboard` object for the camera XOY plane (like the plane
+  of a floor) by changing the `BillBoard` objects mode:
+
+{% codetabs name="C++", type="cpp" -%}
+auto billboard = BillBoard::create("Blue_Front1.png", BillBoard::Mode::VIEW_PLANE_ORIENTED);
+{%- endcodetabs %}
+
+These _create_ methods look a little different since an additional parameter of
+__BillBoard::Mode__ is passed in. There are two __BillBoard::Mode__ types,
+__VIEW_POINT_ORIENTED__ and __VIEW_PLANE_ORIENTED__.
+
+__VIEW_POINT_ORIENTED__ is where the `BillBoard` object is oriented to the
+`Camera`. Example:
+
+![](3d-img/9_8_1.png)
+
+ __VIEW_PLANE_ORIENTED__ is where the `BillBoard` is oriented towards the XOY plane
+ of the `Camera`. Example:
+
+![](3d-img/9_8_2.png)
+
+You can also set properties for a `BillBoard` just like with any other `Node`.
+These include, but are not limited to: __scale__, __position__, __rotation__.
+Examples:
+
+{% codetabs name="C++", type="cpp" -%}
+billboard->setScale(0.5f);
+billboard->setPosition3D(Vec3(0.0f, 0.0f, 0.0f));
+billboard->setBlendFunc(BlendFunc::ALPHA_NON_PREMULTIPLIED);
+addChild(billboard);
+{%- endcodetabs %}
+
+###ParticleSystem3D
+In Chapter 7, you learned about 2D particles and how to use them. When you use 3D
+you might also want to use a 3D particle system for rich, advanced effects. Many
+of the same concepts apply for a 3D particle system as they did with a 2D particle
+system. Cocos2d-x currently supports __Particle Universe__ (http://www.fxpression.com/)
+for particle system construction. __Particle Universe__ provides a special particle
+editor that allows you to quickly and easily set up a variety of effects, such as
+explosions, fire, blood and other special effects. This editor uses a __pu__ file
+extension when saving or exporting.
+
+When you are happy with your particle and ready to use it in code, exporting to
+its built-in format of __pu__ is enough! Cocos2d-x supports this format directly.
+Also, as `ParticleSystem3D` is derived from `Node`, it supports most of the
+features that `Node` supports. `PUParticleSystem3D` is an object type specifically
+for dealing with __Particle Universe__ particles. `PUParticleSystem3D` offers two
+ways for creating particles.
+
+The first way is to build a particle by passing in a __Particle Universe__ file
+and its corresponding __material file__. Remember from Chapter 7 that a
+__material file__ is what describes the particle. This is required. Example:
+
+{% codetabs name="C++", type="cpp" -%}
+auto ps = PUParticleSystem3D::create("lineStreak.pu", "pu_mediapack_01.material");
+ps->startParticleSystem();
+this->addChild(ps);
+{%- endcodetabs %}
+
+The second way is to build the particle system only by passing a __particle universe__
+file. When you create a particle this way, besides loading the particle, all
+__material files__ in the same folder as the particle file will automatically be
+loaded. Here is an example:
+
+{% codetabs name="C++", type="cpp" -%}
+auto ps = PUParticleSystem3D::create("electricBeamSystem.pu");
+ps->startParticleSystem();
+
+this->addChild(ps);
+{%- endcodetabs %}
+
+  __Note:__ using this method will result in an increase in loading times and
+consumes more memory since everything will be loaded. If you know what __material__
+you want to use and don't need to load everything, using the first method would
+be preferred.
+
+In these images below, on the left is the particle in __particle universe__, while
+on the right is the effect running in Cocos2d-x:
+
+![](3d-img/particle1.png) ![](3d-img/particle2.png)
+
+Once you have your particle, you can interact with it it fairly obvious ways. You
+can interact with with the __particle system__ as a whole, starting, stopping,
+pausing, resuming and obtaining the total number of particles:
+
+{% codetabs name="C++", type="cpp" -%}
+virtual void startParticleSystem() override;
+virtual void stopParticleSystem() override;
+virtual void pauseParticleSystem() override;
+virtual void resumeParticleSystem() override;
+virtual int getAliveParticleCount() const override;
+{%- endcodetabs %}
+
+As `PUParticleSystem3D` is derived from `Node` you can run `Action` and `Sequence`
+objects on your particles! Example:
+
+{% codetabs name="C++", type="cpp" -%}
+auto ps = PUParticleSystem3D::create("blackHole.pu", "pu_mediapack_01.material");
+ps->setPosition(-25.0f, 0.0f);
+
+auto moveby = MoveBy::create(2.0f, Vec2(50.0f, 0.0f));
+auto moveby1 = MoveBy::create(2.0f, Vec2(-50.0f, 0.0f));
+
+ps->runAction(RepeatForever::create(Sequence::create(moveby, moveby1, nullptr)));
+ps->startParticleSystem();
+{%- endcodetabs %}
+
+Combining `Action` and `Sequence` objects could produce an interesting black hole
+effect:
+
+![](3d-img/particle3.png)
+
+Just like with other 3D objects you can also combine 3D objects using `AttachNode`.
+This allows for creating rich models. Example:
+
+{% codetabs name="C++", type="cpp" -%}
+auto sprite3d = Sprite3D::create("orc.c3b");
+sprite3d->setPosition3D(Vec3(0.0f, 0.0f, 0.0f));
+sprite3d->setRotation3D(Vec3(0.0f, 180.0f, 0.0f));
+
+auto animation = Animation3D::create("orc.c3b");
+if (animation)
+{
+    auto animate = Animate3D::create(animation);
+    sprite3d->runAction(RepeatForever::create(animate));
+}
+
+auto handler = PUParticleSystem3D::create("lightningBolt.pu");
+handler->startParticleSystem();
+sprite3d->getAttachNode("Bip001 L Hand")->addChild(handler);
+
+this->addChild(sprite3d);
+{%- endcodetabs %}
+
+![](3d-img/particle4.png)

en/3d/animation.md

@@ -0,0 +1,65 @@
+<div class="langs">
+  <a href="#" class="btn" onclick="toggleLanguage()">中文</a>
+</div>
+
+##Animation
+`Sprite3D` objects are essential to our game! We have learned how to manipulate them.
+However, we might want a more rich experience. Enter animation! To run a 3d
+animation, you can use the `Animation3D` and `Animate3D` objects. You then create
+an `Animate3D` action using the `Animation3D` object. Example:
+
+{% codetabs name="C++", type="cpp" -%}
+// the animation is contained in the .c3b file
+auto animation = Animation3D::create("orc.c3b");
+
+// creates the Action with Animation object
+auto animate = Animate3D::create(animation);
+
+// runs the animation
+sprite->runAction(RepeatForever::create(animate));
+{%- endcodetabs %}
+
+Run the example __Programmer Guide Sample__ code to see this in action! Please
+keep in mind that 3D animations are exactly the same concepts as 2D. Please refer
+to Chapter 4 in this guide.
+
+###Multiple animations
+What do you do when you want to run multiple __animations__ at the same time?
+Using both the __animation start time__ and __animation length__ parameters you
+can create multiple animations. The unit for both parameters is seconds. Example:
+
+{% codetabs name="C++", type="cpp" -%}
+auto animation = Animation3D::create(fileName);
+
+auto runAnimate = Animate3D::create(animation, 0, 2);
+sprite->runAction(runAnimate);
+
+auto attackAnimate = Animate3D::create(animation, 3, 5);
+sprite->runAction(attackAnimate);
+{%- endcodetabs %}
+
+In the above example there are two animations that get run. The first starts
+immediately and lasts for *2 seconds*. The second starts after *3 seconds* and lasts
+for *5 seconds*.
+
+###Animation speed
+The __speed__ of the animation is a positive integer for forward while
+a negative speed would be reverse. In this case the speed is set to *10*.
+This means that this animation can be considered to be *10* seconds in length.
+
+###Animation blending
+When using multiple animations, __blending__ is automatically applied between each
+animation. The purpose of __blending__ is to create a smooth transition between
+effects. Given two animations, A and B, the last few frames of animation A and
+the first few frames of animation B overlap to make the change in animation look
+natural.
+
+The default transition time is 0.1 seconds. You can set the transition time by
+using __Animate3D::setTransitionTime__.
+
+Cocos2d-x only supports __linear interpolation__ between keyframes. This fills in
+__gaps__ in the curve to ensure a smooth path. If you use other interpolation
+methods in the model production, our built-in tool, __fbx-conv__ will
+generate additional keyframes to compensate. This compensation is completed in
+accordance with the target frame. For more information on __fbx-conv__ please refer
+to the section discussing it at the end of this chapter.

en/3d/camera.md

@@ -0,0 +1,76 @@
+<div class="langs">
+  <a href="#" class="btn" onclick="toggleLanguage()">中文</a>
+</div>
+
+##Camera
+__Camera__ objects are an important aspect of 3D development. Since a 3D world is
+not flat you need to use a `Camera` to look at it and navigate around it. Just
+like when you are watching a movie and the scene pans to the left or right. This
+same concept is applied when using a `Camera` object. The `Camera` object inherits
+from `Node` and therefore supports most of the same `Action` objects. There are two types
+of `Camera` objects: __perspective camera__ and __orthographic camera__.
+
+The __perspective camera__ is used to see objects having a near to far effect. A
+__perspective camera__ view might look like this:
+
+![](3d-img/PerspectiveCamera.png)
+
+As you can see with a __perspective camera__, objects in the _near_ are larger and
+objects in the __far__ are smaller.
+
+The __orthogonal camera__ is used to see objects as large distance. You can think
+about it as converting a 3D world to a 2D representation. An __orthogonal camera__
+view might look like this:
+
+![](3d-img/OrthographicCamera.png)
+
+As you can see with an __orthogonal camera__, objects are the same size regardless
+of how far away from the `Camera` object they are. __Mini Maps__ in games are
+commonly rendered with an __orthogonal camera__. Another example would be a top -
+down view, perhaps in a dungeon style game.
+
+### Camera Use
+Don't worry! `Camera` objects may sound complicated but Cocos2d-x makes them easy.
+When using 3D you don't have to do anything special to create a `Camera` object.
+Each `Scene` automatically creates a default camera, based on the projection
+properties of the `Director` object. If you need more than one camera, you can
+use the following code to create one:
+
+{% codetabs name="C++", type="cpp" -%}
+auto s = Director::getInstance()->getWinSize();
+auto camera = Camera::createPerspective(60, (GLfloat)s.width/s.height, 1, 1000);
+
+// set parameters for camera
+camera->setPosition3D(Vec3(0, 100, 100));
+camera->lookAt(Vec3(0, 0, 0), Vec3(0, 1, 0));
+
+addChild(camera); //add camera to the scene
+{%- endcodetabs %}
+
+### Creating orthogonal camera
+The default `Camera` is a __perspective camera__. If you want to create an
+__orthogonal camera__, it's easy to do by calling:
+
+{% codetabs name="C++", type="cpp" -%}
+Camera::createOrthographic();
+{%- endcodetabs %}
+
+Example:
+
+{% codetabs name="C++", type="cpp" -%}
+auto s = Director::getInstance()->getWinSize();
+auto camera = Camera::createOrthographic(s.width, s.height, 1, 1000);
+{%- endcodetabs %}
+
+### Hiding objects from the camera
+Sometimes you don't want to have all objects visible in a `Camera` view. Hiding
+an object from one camera is very easy. Use __setCameraMask(CameraFlag)__ on the
+`Node` and __setCameraFlag(CameraFlag)__ on the `Camera`. Example:
+
+{% codetabs name="C++", type="cpp" -%}
+//Camera
+camera->setCameraFlag(CameraFlag::USER1);
+
+//Node
+node->setCameraMask(CameraFlag::USER1);
+{%- endcodetabs %}

en/3d/cubemap.md

@@ -0,0 +1,34 @@
+<div class="langs">
+  <a href="#" class="btn" onclick="toggleLanguage()">中文</a>
+</div>
+
+## Cubemap Texture
+A __cube map texture__ is a collection of six separate square textures that are
+put onto the faces of an imaginary cube. Most often they are used to display
+infinitely far away reflections on objects, similar to how __sky box__ displays
+far away scenery in the background. This is what an expanded cube map might look
+like:
+
+![](3d-img/Cubemap.jpg)
+
+In Cocos2d-x, you can create a __cube map texture__ in this way:
+
+{% codetabs name="C++", type="cpp" -%}
+// create a textureCube object with six texture assets
+auto textureCube = TextureCube::create("skybox/left.jpg",  "skybox/right.jpg", "skybox/top.jpg", "skybox/bottom.jpg", "skybox/front.jpg", "skybox/back.jpg");
+
+// set cube map texture parameters
+Texture2D::TexParams tRepeatParams;
+tRepeatParams.magFilter = GL_NEAREST;
+tRepeatParams.minFilter = GL_NEAREST;
+tRepeatParams.wrapS = GL_MIRRORED_REPEAT;
+tRepeatParams.wrapT = GL_MIRRORED_REPEAT;
+textureCube->setTexParameters(tRepeatParams);
+
+// create and set our custom shader
+auto shader = GLProgram::createWithFilenames("cube_map.vert", "cube_map.frag");
+auto _state = GLProgramState::create(shader);
+
+// bind cube map texture to uniform
+state->setUniformTexture("u_cubeTex", textureCube);
+{%- endcodetabs %}