Merge remote-tracking branch 'remotes/mike3d/master'

Docs/Reference.dox

@@ -1682,26 +1682,88 @@ A typical 2D game setup would consist of the following:
 	- Create some sprites
 	- Use physics and constraints to interact with the scene
 
-To create a textured sprite with physics you must create a node that has:
-	- a drawable component + a resource (texture)
-	- a rigid body component + a collision shape component (for physics simulation)
-	- a constraint (optional)
+\section Urho2D_Orthographic Orthographic camera
+In order to use Urho2D we need to set camera to orthographic mode first; it can be done with following code:
+
+C++:
+\code
+    // Create camera node
+    Node* cameraNode = scene_->CreateChild("Camera");
+
+    // Create camera
+    Camera* camera = cameraNode->CreateComponent<Camera>();
+    // Set camera orthographic
+    camera->SetOrthographic(true);
+    // Set camera ortho size (the value of PIXEL_SIZE is 0.01)
+    camera->SetOrthoSize((float)graphics->GetHeight() * PIXEL_SIZE);
+\endcode 
+
+AngelScript:
+\code
+    // Create camera node
+    Node@ cameraNode = scene_.CreateChild("Camera");
+
+    // Create camera
+    Camera@ camera = cameraNode.CreateComponent("Camera");
+    // Set camera orthographic
+    camera.orthographic = true;
+    // Set camera ortho size (the value of PIXEL_SIZE is 0.01)
+    camera.orthoSize = graphics.height * PIXEL_SIZE;
+\endcode 
 
-Provided classes are:
+Lua:
+\code
+    -- Create camera node
+    cameraNode = scene_:CreateChild("Camera")
 
-\section Drawable_Components Drawable components
-Your choice depends on the kind of sprite you want to create:
-- AnimatedSprite2D : used to display an Animation2D. Equivalent to a 3D AnimatedModel.
+    -- Create camera
+    local camera = cameraNode:CreateComponent("Camera")
+    -- Set camera orthographic
+    camera.orthographic = true
+    -- Set camera ortho size (the value of PIXEL_SIZE is 0.01)
+    camera.orthoSize = graphics.height * PIXEL_SIZE
+\endcode 
+
+To zoom in/out, use \ref Camera::SetZoom "SetZoom()".
+
+\section Urho2D_Sprites Sprites
+Urho2D provides a handful of classes for loading/drawing the kind of sprite required by your game.
+You can chose from animated sprites, 2D particle emitters and static sprites.
+
+\section Urho2D_Animated Animated sprites
+
+Workflow for creating animated sprites in Urho2D relies on Spriter (c). 
+Spriter is a crossplatform tool for creating 2D animations. It comes both as an almost fully featured free version and a more advanced 'pro' version. Free version is available at http://www.brashmonkey.com/spriter.htm. To get started, scml files from Bin/Data/Urho2D folder can be loaded in Spriter. Note that although currently Spriter doesn't support spritesheets/texture atlases, Urho2D does: you just have to use the same name for your scml file and your spritesheet's xml file (see details below on how to generate this file). Keep your individual image files as they are still required if you want to later edit your scml project in Spriter.
+A *.scml file is loaded using AnimationSet2D class (Resource) and rendered using AnimatedSprite2D class (Drawable component):
+
+- AnimationSet2D: a Spriter *.scml file including one or more animations.
+Each Spriter animation (Animation2D) contained in an AnimationSet2D can be accessed by its index and by its name (\ref AnimationSet2D::GetAnimation "GetAnimation()").
+
+- AnimatedSprite2D: used to display a Spriter animation (Animation2D from an AnimationSet2D). Equivalent to a 3D AnimatedModel. Animation2D animations inside the AnimationSet2D are accessed by their name (String) using \ref AnimatedSprite2D::SetAnimation "SetAnimation()". Playback animation speed can be controlled using \ref AnimatedSprite2D::SetSpeed "SetSpeed()". Loop mode can be controlled using \ref AnimatedSprite2D::SetLoopMode "SetLoopMode()" (you can use the default value set in Spriter or make the animation repeat or clamp).
+One interesting feature is the ability to flip/mirror animations on both axes, using \ref AnimatedSprite2D::SetFlip "SetFlip()", \ref AnimatedSprite2D::SetFlipX "SetFlipX()" or \ref AnimatedSprite2D::SetFlipY "SetFlipY()". Once flipped, the animation remains in that state until boolean state is restored to false. It is recommended to build your sprites centered in Spriter if you want to easily flip their animations (otherwise sprite position will seem to diverge).
+
+- Animation2D (RefCounted): a Spriter animation from an AnimationSet2D.
+
+For a demonstration, check examples 33_Urho2DSpriterAnimation and 24_Urho2DSprite.
+
+\section Urho2D_Particle Particle Emitters
+A 2D particle emitter is built from a *.pex file (a format used by many 2D engines).
+A *.pex file is loaded using ParticleEffect2D class (Resource) and rendered using AnimatedSprite2D class (Drawable component):
+
+- ParticleEffect2D: a *.pex file defining the behavior and texture of a 2D particle (ParticleEmitter2D). For an example, see Bin/Data/Urho2D/greenspiral.pex
 - ParticleEmitter2D: used to display a ParticleEffect2D. Equivalent to a 3D ParticleEmitter.
-- StaticSprite2D: used to display a Sprite2D. Equivalent to a 3D StaticModel.
-You can use different layers in order to simulate perspective. In this case you can use \ref Drawable2D::SetLayer "SetLayer()" and \ref Drawable2D::SetOrderInLayer "SetOrderInLayer()" to organise your sprites and arrange thir display order.
 
-\section Resources Resources
-A 2D resource is the texture file applied to the drawable component:
-- Animation2D: a *.anm file defining a sequence of Sprite2D frames (retrieved from one or more Sprite2Ds/SpriteSheet2Ds) to play. For an example using a SpriteSheet2D, see Bin/Data/Urho2D/GoldIcon.anm
-- ParticleEffect2D: a *.xml file defining the behavior and texture of a 2D particle (ParticleEmitter2D). For an example, see Bin/Data/Urho2D/greenspiral.pex
+For a demonstration, check example 25_Urho2DParticle.
+
+\section Urho2D_Static_Sprites Static Sprites
+Static sprites are built from single image files or from spritesheets/texture atlases.
+Single image files are loaded using Sprite2D class (Resource) and spritesheets/texture atlases are loaded using SpriteSheet2D class (Resource).
+Both are rendered using StaticSprite2D class (Drawable component):
+- StaticSprite2D: used to display a Sprite2D. Equivalent to a 3D StaticModel.
 - Sprite2D: an image defined with texture, texture rectangle and hot spot.
 - SpriteSheet2D: a texture atlas image (that packs multiple Sprite2D images).
+Spritesheets can be created using tools like ShoeBox (http://renderhjs.net/shoebox/), darkFunction Editor (http://darkfunction.com/editor/), SpriteHelper (http://www.gamedevhelper.com/spritehelper/), TexturePacker (http://www.codeandweb.com/texturepacker), ...
+These tools will generate an image file and a xml file mapping coordinates and size for each individual image. Note that Urho2D uses same xml file format as Sparrow/Starling engines.
 
 You can assign a material to an image by creating a xml parameter file named as the image and located in the same folder.
 For example, to make the box sprite (Bin/Data/Urho2D/Box.png) nearest filtered, create a file Box.xml next to it, with the following content:
@@ -1714,12 +1776,6 @@ For example, to make the box sprite (Bin/Data/Urho2D/Box.png) nearest filtered,
 
 The full list of texture parameters is documented \ref Materials "here".
 
-To create an Animation2D from multiple images:
-- Pack all your individual images into a texture atlas using tools like ShoeBox (http://renderhjs.net/shoebox/), darkFunction Editor (http://darkfunction.com/editor/), SpriteHelper (http://www.gamedevhelper.com/spritehelper/), TexturePacker (http://www.codeandweb.com/texturepacker), ...
-This will generate an image file and a xml file mapping coordinates and size for each individual image. Note that Urho2D uses same xml file format as Sparrow/Starling engines.
-- Create an Animation2D xml file from scratch or using ShoeBox.
-For an example, see rotating coin in example 24_Urho2DSprite and resources located in Bin/Data/Urho2D : GoldIcon.png is the texture atlas image, GoldIcon.xml is the external file storing sprites' coordinates and size and GoldIcon.anm is the Animation2D file.
-
 \section Urho2D_Physics Physics
 Physics in Urho2D uses Box2D. You can refer to Box2D manual at http://box2d.org/manual.pdf for full reference (just substitute "joints" for "constraints").
 - PhysicsWorld2D: implements 2D physics simulation. Mandatory for 2D physics components such as RigidBody2D, CollisionShape2D or Constraint2D.
@@ -1728,7 +1784,7 @@ Physics in Urho2D uses Box2D. You can refer to Box2D manual at http://box2d.org/
 - RigidBody2D: a 2D physics object instance.
 Available BodyType2Ds are:
 - BT_STATIC: A static body does not move under simulation and behaves as if it has infinite mass. Internally, Box2D stores zero for the mass and the inverse mass. Static bodies can be moved manually by the user. A static body has zero velocity. Static bodies do not collide with other static or kinematic bodies.
-- BT_DYNAMIC: A dynamic body is fully simulated. They can be moved manually by the user, but normally they move according to forces. A dynamic body can collide with all body types. A dynamic body always has finite, non-zero mass. If you try to set the mass of a dynamic body to zero, it will automatically acquire a mass of one kilogram.
+- BT_DYNAMIC: A dynamic body is fully simulated. It can be moved manually by the user, but normally they move according to forces. A dynamic body can collide with all body types. A dynamic body always has finite, non-zero mass. If you try to set the mass of a dynamic body to zero, it will automatically acquire a mass of one kilogram.
 - BT_KINEMATIC: A kinematic body moves under simulation according to its velocity. Kinematic bodies do not respond to forces. They can be moved manually by the user, but normally a kinematic body is moved by setting its velocity. A kinematic body behaves as if it has infinite mass, however, Box2D stores zero for the mass and the inverse mass. Kinematic bodies do not collide with other static or kinematic bodies.
 
 You should establish the body type at creation, using \ref RigidBody2D::SetBodyType "SetBodyType()", because changing the body type later is expensive.
@@ -1749,7 +1805,7 @@ Other interesting tool is BisonKick (https://bisonkick.com/app/518195d06927101d3
 Apply a constraint to a node (called 'ownerBody') and use \ref Constraint::SetOtherBody "SetOtherBody()" to set the other node's body to be constrained to the ownerBody.
 Use \ref Constraint2D::SetCollideConnected "SetCollideConnected()" to switch collision on/off between the bodies.
 Use \ref PhysicsWorld2D::SetDrawJoint "SetDrawJoint()" in combination with \ref PhysicsWorld2D::DrawDebugGeometry "DrawDebugGeometry()" to display the joints.
-See 32_Urho2DConstraints sample (not released yet) for detailed examples and to help selecting the appropriate constraint.
+See 32_Urho2DConstraints sample for detailed examples and to help selecting the appropriate constraint.
 - Constraint2D: base class for 2D physics constraints.
 - ConstraintDistance2D: defines 2D physics distance constraint. The distance between two anchor points (\ref ConstraintDistance2D::SetOwnerBodyAnchor "SetOwnerBodyAnchor()" and \ref ConstraintDistance2D::SetOtherBodyAnchor "SetOtherBodyAnchor()") on two bodies is kept constant. The constraint can also be made soft, like a spring-damper connection. Softness is achieved by tuning frequency (\ref ConstraintDistance2D::SetFrequencyHz "SetFrequencyHz()" is below half of the timestep) and damping ratio (\ref ConstraintDistance2D::SetDampingRatio "SetDampingRatio()").
 - ConstraintFriction2D: defines 2D physics friction constraint. This constraint is used for top-down friction. It provides 2D translational friction (\ref ConstraintFriction2D::SetMaxForce "SetMaxForce()") and angular friction (\ref ConstraintFriction2D::SetMaxTorque "SetMaxTorque()").
@@ -1763,51 +1819,12 @@ See 32_Urho2DConstraints sample (not released yet) for detailed examples and to
 - ConstraintWeld2D: defines 2D physics weld constraint. This constraint attempts to constrain all relative motion between two bodies.
 - ConstraintWheel2D: defines 2D physics wheel constraint. This constraint restricts a point on bodyB (\ref ConstraintWheel2D::SetAnchor() "SetAnchor()") to a line on bodyA (\ref ConstraintWheel2D::SetAxis "SetAxis()"). It also provides a suspension spring.
 
-In order to use Urho2D we need to set camera to orthographic mode first; it can be done with following code:
-
-C++:
-\code
-    // Create camera node
-    Node* cameraNode = scene_->CreateChild("Camera");
-    
-    // Create camera
-    Camera* camera = cameraNode->CreateComponent<Camera>();
-    // Set camera orthographic
-    camera->SetOrthographic(true);
-    // Set camera ortho size (the value of PIXEL_SIZE is 0.01)
-    camera->SetOrthoSize((float)graphics->GetHeight() * PIXEL_SIZE);
-\endcode 
-
-AngelScript:
-\code
-    // Create camera node
-    Node@ cameraNode = scene_.CreateChild("Camera");
-    
-    // Create camera
-    Camera@ camera = cameraNode.CreateComponent("Camera");
-    // Set camera orthographic
-    camera.orthographic = true;
-    // Set camera ortho size (the value of PIXEL_SIZE is 0.01)
-    camera.orthoSize = graphics.height * PIXEL_SIZE;
-\endcode 
-
-Lua:
-\code
-    -- Create camera node
-    cameraNode = scene_:CreateChild("Camera")
-    
-    -- Create camera
-    local camera = cameraNode:CreateComponent("Camera")
-    -- Set camera orthographic
-    camera.orthographic = true
-    -- Set camera ortho size (the value of PIXEL_SIZE is 0.01)
-    camera.orthoSize = graphics.height * PIXEL_SIZE
-\endcode 
-
-To zoom in/out, use \ref Camera::SetZoom "SetZoom()".
-
+\section Urho2D_Background_and_Layers Background and Layers
 To set the background color for the scene, use \ref Renderer::GetDefaultZone "GetDefaultZone()".fogColor
 
+You can use different layers in order to simulate perspective. In this case you can use \ref Drawable2D::SetLayer "SetLayer()" and \ref Drawable2D::SetOrderInLayer "SetOrderInLayer()" to organise your sprites and arrange thir display order.
+
+Finally, note that you can easily mix both 2D and 3D resources. 3D assets' position need to be slightly offset on the Z axis (z=1 is enough), Camera's position needs to be slightly offset (on the Z axis) from 3D assets' max girth and a Light is required.
 
 \page Serialization Serialization