Lothario
/
axmol
mirror of https://github.com/axmolengine/axmol.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #5602 from ricardoquesada/node_fixes 

Fixes docstrings
This commit is contained in:
Ricardo Quesada 2014-03-06 16:15:06 -08:00
parent 640482e38c 57b6478de7
commit 808a874fac
8 changed files with 116 additions and 172 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.REMOVED.git-id
View File

@ -1 +1 @@
8d7fb651cdd88dc91ed4fa6164452635e681d143
c0fd8e6a4cb224b1ca5d5b41b9b508d284423daa

186
cocos/2d/CCNode.h
View File

@ -76,53 +76,29 @@ bool nodeComparisonLess(Node* n1, Node* n2);
class EventListener;
/** @brief Node is the base element of the Scene Graph. Element of the Scene Graph must be Node objects or subclasses of it.
The most common Node objects are: Scene, Layer, Sprite, Menu.
/** @brief Node is the base element of the Scene Graph. Elements of the Scene Graph must be Node objects or subclasses of it.
The most common Node objects are: Scene, Layer, Sprite, Menu, Label.
The main features of a Node are:
- They can contain other Node objects (`addChild`, `getChildByTag`, `removeChild`, etc)
- They can schedule periodic callback (`schedule`, `unschedule`, etc)
- They can execute actions (`runAction`, `stopAction`, etc)
Some Node objects provide extra functionality for them or their children.
Subclassing a Node usually means (one/all) of:
- overriding init to initialize resources and schedule callbacks
- create callbacks to handle the advancement of time
- overriding draw to render the node
- overriding `draw` to render the node
Properties of Node:
- position
- scale (x, y)
- rotation (in degrees, clockwise)
- GridBase (to do mesh transformations)
- anchor point
- size
- visible
- z-order
- openGL z position
Default values:
- rotation: 0
- position: (x=0,y=0)
- scale: (x=1,y=1)
- contentSize: (x=0,y=0)
- anchorPoint: (x=0,y=0)
- position (default: x=0, y=0)
- scale (default: x=1, y=1)
- rotation (in degrees, clockwise) (default: 0)
- anchor point (default: x=0, y=0)
- contentSize (default: width=0, height=0)
- visible (default: true)
Limitations:
- A Node is a "invisible" object. If you want to draw something on the screen, you should use a Sprite instead. Or subclass Node and override `draw`.
Order in transformations with grid disabled
-# The node will be translated (position)
-# The node will be rotated (rotation)
-# The node will be scaled (scale)
Order in transformations with grid enabled
-# The node will be translated (position)
-# The node will be rotated (rotation)
-# The node will be scaled (scale)
-# The grid will capture the screen
-# The grid will render the captured screen
- A Node is a "void" object. If you want to draw something on the screen, you should use a Sprite instead. Or subclass Node and override `draw`.
*/
@ -215,9 +191,9 @@ public:
virtual float getGlobalZOrder() const { return _globalZOrder; }
/**
* Changes the scale factor on X axis of this node
* Sets the scale (x) of the node.
*
* The deafult value is 1.0 if you haven't changed it before
* It is a scaling factor that multiplies the width of the node and its children.
*
* @param scaleX The scale factor on X axis.
*/
@ -233,9 +209,9 @@ public:
/**
* Changes the scale factor on Y axis of this node
* Sets the scale (y) of the node.
*
* The Default value is 1.0 if you haven't changed it before.
* It is a scaling factor that multiplies the height of the node and its children.
*
* @param scaleY The scale factor on Y axis.
*/
@ -268,9 +244,9 @@ public:
/**
* Changes both X and Y scale factor of the node.
* Sets the scale (x,y,z) of the node.
*
* 1.0 is the default scale factor. It modifies the X and Y scale at the same time.
* It is a scaling factor that multiplies the width, height and depth of the node and its children.
*
* @param scale The scale factor for both X and Y axis.
*/
@ -286,21 +262,20 @@ public:
virtual float getScale() const;
/**
* Changes both X and Y scale factor of the node.
* Sets the scale (x,y) of the node.
*
* 1.0 is the default scale factor. It modifies the X and Y scale at the same time.
* It is a scaling factor that multiplies the width and height of the node and its children.
*
* @param scaleX The scale factor on X axis.
* @param scaleY The scale factor on Y axis.
*/
virtual void setScale(float scaleX,float scaleY);
virtual void setScale(float scaleX, float scaleY);
/**
* Changes the position (x,y) of the node in OpenGL coordinates
* Sets the position (x,y) of the node in its parent's coordinate system.
*
* Usually we use `Point(x,y)` to compose Point object.
* The original point (0,0) is at the left-bottom corner of screen.
* For example, this codesnip sets the node in the center of screen.
* This code snippet sets the node in the center of screen.
@code
Size size = Director::getInstance()->getWinSize();
node->setPosition( Point(size.width/2, size.height/2) )
@ -310,7 +285,7 @@ public:
*/
virtual void setPosition(const Point &position);
/**
* Gets the position (x,y) of the node in OpenGL coordinates
* Gets the position (x,y) of the node in its parent's coordinate system.
*
* @see setPosition(const Point&)
*
@ -321,14 +296,14 @@ public:
*/
virtual const Point& getPosition() const;
/**
* Sets position in a more efficient way.
* Sets the position (x,y) of the node in its parent's coordinate system.
*
* Passing two numbers (x,y) is much efficient than passing Point object.
* This method is binded to lua and javascript.
* Passing a number is 10 times faster than passing a object from lua to c++
* This method is bound to Lua and JavaScript.
* Passing a number is 10 times faster than passing a object from Lua to c++
*
@code
// sample code in lua
// sample code in Lua
local pos = node::getPosition() -- returns Point object from C++
node:setPosition(x, y) -- pass x, y coordinate to C++
@endcode
@ -354,16 +329,16 @@ public:
virtual float getPositionY(void) const;
/**
* Sets the X, Y, and Z axis position
* Sets the position (X, Y, and Z) in its parent's coordinate system
*/
virtual void setPosition3D(const Vertex3F& position);
/**
* returns the X, Y and Z axis position
* returns the position (X,Y,Z) in its parent's coordinate system
*/
virtual Vertex3F getPosition3D() const;
/**
* Sets the 'z' axis in the position. It is the OpenGL Z vertex value.
* Sets the 'z' coordinate in the position. It is the OpenGL Z vertex value.
*
* The OpenGL depth buffer and depth testing are disabled by default. You need to turn them on
* in order to use this property correctly.
@ -378,11 +353,11 @@ public:
CC_DEPRECATED_ATTRIBUTE virtual void setVertexZ(float vertexZ) { setPositionZ(vertexZ); }
/**
* Gets position Z axis of this node.
* Gets position Z coordinate of this node.
*
* @see setPositionZ(float)
*
* @return the position Z axis of this node.
* @return the position Z coordinate of this node.
*/
virtual float getPositionZ() const;
CC_DEPRECATED_ATTRIBUTE virtual float getVertexZ() const { return getPositionZ(); }
@ -391,10 +366,10 @@ public:
* Changes the X skew angle of the node in degrees.
*
* The difference between `setRotationalSkew()` and `setSkew()` is that the first one simulate Flash's skew functionality
* while the second one uses the real skew funciton.
* while the second one uses the real skew function.
*
* This angle describes the shear distortion in the X direction.
* Thus, it is the angle between the Y axis and the left edge of the shape
* Thus, it is the angle between the Y coordinate and the left edge of the shape
* The default skewX angle is 0. Positive values distort the node in a CW direction.
*
* @param skewX The X skew angle of the node in degrees.
@ -414,10 +389,10 @@ public:
* Changes the Y skew angle of the node in degrees.
*
* The difference between `setRotationalSkew()` and `setSkew()` is that the first one simulate Flash's skew functionality
* while the second one uses the real skew funciton.
* while the second one uses the real skew function.
*
* This angle describes the shear distortion in the Y direction.
* Thus, it is the angle between the X axis and the bottom edge of the shape
* Thus, it is the angle between the X coordinate and the bottom edge of the shape
* The default skewY angle is 0. Positive values distort the node in a CCW direction.
*
* @param skewY The Y skew angle of the node in degrees.
@ -521,20 +496,20 @@ public:
virtual float getRotation() const;
/**
* Sets the X, Y and Z axis rotation
* Sets the rotation (X,Y,Z) in degrees.
* Useful for 3d rotations
*/
virtual void setRotation3D(const Vertex3F& rotation);
/**
* returns the X, Y and Z axis rotation
* returns the rotation (X,Y,Z) in degrees.
*/
virtual Vertex3F getRotation3D() const;
/**
* Sets the X rotation (angle) of the node in degrees which performs a horizontal rotational skew.
*
* The difference between setRotationalSkew() and setSkew() is that the first one simulate Flash's skew functionality
* while the second one uses the real skew funciton.
* The difference between `setRotationalSkew()` and `setSkew()` is that the first one simulate Flash's skew functionality
* while the second one uses the real skew function.
*
* 0 is the default rotation angle.
* Positive values rotate node clockwise, and negative values for anti-clockwise.
@ -557,8 +532,8 @@ public:
/**
* Sets the Y rotation (angle) of the node in degrees which performs a vertical rotational skew.
*
* The difference between setRotationalSkew() and setSkew() is that the first one simulate Flash's skew functionality
* while the second one uses the real skew funciton.
* The difference between `setRotationalSkew()` and `setSkew()` is that the first one simulate Flash's skew functionality
* while the second one uses the real skew function.
*
* 0 is the default rotation angle.
* Positive values rotate node clockwise, and negative values for anti-clockwise.
@ -590,7 +565,7 @@ public:
*/
void setOrderOfArrival(int orderOfArrival);
/**
* Returns the arrival order, indecates which children is added previously.
* Returns the arrival order, indicates which children is added previously.
*
* @see `setOrderOfArrival(unsigned int)`
*
@ -617,7 +592,7 @@ public:
* The default value is false, while in Layer and Scene are true
*
* @param ignore true if anchor point will be (0,0) when you position this node
* @todo This method shoud be renamed as setIgnoreAnchorPointForPosition(bool) or something with "set"
* @todo This method should be renamed as setIgnoreAnchorPointForPosition(bool) or something with "set"
*/
virtual void ignoreAnchorPointForPosition(bool ignore);
/**
@ -629,7 +604,7 @@ public:
*/
virtual bool isIgnoreAnchorPointForPosition() const;
/// @} end of Setters & Getters for Graphic Peroperties
/// @} end of Setters & Getters for Graphic Properties
/// @{
@ -658,8 +633,8 @@ public:
* If the child is added to a 'running' node, then 'onEnter' and 'onEnterTransitionDidFinish' will be called immediately.
*
* @param child A child node
* @param zOrder Z order for drawing priority. Please refer to setLocalZOrder(int)
* @param tag A interger to identify the node easily. Please refer to setTag(int)
* @param zOrder Z order for drawing priority. Please refer to `setLocalZOrder(int)`
* @param tag An integer to identify the node easily. Please refer to `setTag(int)`
*/
virtual void addChild(Node* child, int localZOrder, int tag);
/**
@ -671,26 +646,15 @@ public:
*/
virtual Node * getChildByTag(int tag);
/**
* Return an array of children
* Returns the array of the node's children
*
* Composing a "tree" structure is a very important feature of Node
* Here's a sample code of traversing children array:
@code
Node* node = nullptr;
CCARRAY_FOREACH(parent->getChildren(), node)
{
node->setPosition(0,0);
}
@endcode
* This sample code traverses all children nodes, and set their position to (0,0)
*
* @return An array of children
* @return the array the node's children
*/
virtual Vector<Node*>& getChildren() { return _children; }
virtual const Vector<Node*>& getChildren() const { return _children; }
/**
* Get the amount of children.
* Returns the amount of children
*
* @return The amount of children.
*/
@ -783,35 +747,7 @@ public:
/**
* Returns a tag that is used to identify the node easily.
*
* You can set tags to node then identify them easily.
@code
#define TAG_PLAYER 1
#define TAG_MONSTER 2
#define TAG_BOSS 3
// set tags
node1->setTag(TAG_PLAYER);
node2->setTag(TAG_MONSTER);
node3->setTag(TAG_BOSS);
parent->addChild(node1);
parent->addChild(node2);
parent->addChild(node3);
// identify by tags
Node* node = nullptr;
CCARRAY_FOREACH(parent->getChildren(), node)
{
switch(node->getTag())
{
case TAG_PLAYER:
break;
case TAG_MONSTER:
break;
case TAG_BOSS:
break;
}
}
@endcode
*
* @return A interger that identifies the node.
* @return An integer that identifies the node.
*/
virtual int getTag() const;
/**
@ -819,7 +755,7 @@ public:
*
* Please refer to getTag for the sample code.
*
* @param tag A interger that indentifies the node.
* @param tag A integer that identifies the node.
*/
virtual void setTag(int tag);
@ -873,8 +809,8 @@ public:
*
* Similar to UserData, but instead of holding a void* it holds an object.
* The UserObject will be retained once in this method,
* and the previous UserObject (if existed) will be relese.
* The UserObject will be released in Node's destructure.
* and the previous UserObject (if existed) will be released.
* The UserObject will be released in Node's destructor.
*
* @param userObject A user assigned Object
*/
@ -888,7 +824,7 @@ public:
/**
* Return the shader program currently used for this node
*
* @return The shader program currelty used for this node
* @return The shader program currently used for this node
*/
virtual GLProgram* getShaderProgram() { return _shaderProgram; }
virtual const GLProgram* getShaderProgram() const { return _shaderProgram; }
@ -902,16 +838,16 @@ public:
node->setShaderProgram(ShaderCache::getInstance()->getProgram(GLProgram::SHADER_NAME_POSITION_TEXTURE_COLOR));
@endcode
*
* @param shaderProgram The shader program which fetchs from ShaderCache.
* @param shaderProgram The shader program
*/
virtual void setShaderProgram(GLProgram *shaderProgram);
/// @} end of Shader Program
/**
* Returns whether or not the node accepts event callbacks.
* Returns whether or not the node is "running".
*
* Running means the node accept event callbacks like onEnter(), onExit(), update()
* If the node is running it will accept event callbacks like onEnter(), onExit(), update()
*
* @return Whether or not the node is running.
*/
@ -1000,13 +936,9 @@ public:
virtual Scene* getScene();
/**
* Returns a "local" axis aligned bounding box of the node.
* The returned box is relative only to its parent.
* Returns an AABB (axis-aligned bounding-box) in its parent's coordinate system.
*
* @note This method returns a temporaty variable, so it can't returns const Rect&
* @todo Rename to `getBoundingBox()` in the future versions.
*
* @return A "local" axis aligned boudning box of the node.
* @return An AABB (axis-aligned bounding-box) in its parent's coordinate system
*/
virtual Rect getBoundingBox() const;

51
cocos/2d/CCSprite.h
View File

@ -63,21 +63,19 @@ struct transformValues_;
*
* Sprite can be created with an image, or with a sub-rectangle of an image.
*
* If the parent or any of its ancestors is a SpriteBatchNode then the following features/limitations are valid
* - Features when the parent is a BatchNode:
* - MUCH faster rendering, specially if the SpriteBatchNode has many children. All the children will be drawn in a single batch.
* To optimize the Sprite rendering, please follow the following best practices:
*
* - Limitations
* - Camera is not supported yet (eg: OrbitCamera action doesn't work)
* - GridBase actions are not supported (eg: Lens, Ripple, Twirl)
* - The Alias/Antialias property belongs to SpriteBatchNode, so you can't individually set the aliased property.
* - The Blending function property belongs to SpriteBatchNode, so you can't individually set the blending function property.
* - Parallax scroller is not supported, but can be simulated with a "proxy" sprite.
* - Put all your sprites in the same spritesheet (http://www.codeandweb.com/what-is-a-sprite-sheet)
* - Use the same blending function for all your sprites
* - ...and the Renderer will automatically "batch" your sprites (will draw all of them in one OpenGL call).
*
* If the parent is an standard Node, then Sprite behaves like any other Node:
* - It supports blending functions
* - It supports aliasing / antialiasing
* - But the rendering will be slower: 1 draw per children.
* To gain an additional 5% ~ 10% more in the rendering, you can parent your sprites into a `SpriteBatchNode`.
* But doing so carries the following limitations:
*
* - The Alias/Antialias property belongs to `SpriteBatchNode`, so you can't individually set the aliased property.
* - The Blending function property belongs to `SpriteBatchNode`, so you can't individually set the blending function property.
* - `ParallaxNode` is not supported, but can be simulated with a "proxy" sprite.
* - Sprites can only have other Sprites (or subclasses of Sprite) as children.
*
* The default anchorPoint in Sprite is (0.5, 0.5).
*/
@ -93,7 +91,7 @@ public:
/**
* Creates an empty sprite without texture. You can call setTexture method subsequently.
*
* @return An empty sprite object that is marked as autoreleased.
* @return An autoreleased sprite object.
*/
static Sprite* create();
@ -103,26 +101,27 @@ public:
* After creation, the rect of sprite will be the size of the image,
* and the offset will be (0,0).
*
* @param filename The string which indicates a path to image file, e.g., "scene1/monster.png".
* @return A valid sprite object that is marked as autoreleased.
* @param filename A path to image file, e.g., "scene1/monster.png"
* @return An autoreleased sprite object.
*/
static Sprite* create(const std::string& filename);
/**
* Creates a sprite with an image filename and a rect.
*
* @param filename The string wich indicates a path to image file, e.g., "scene1/monster.png"
* @param rect Only the contents inside rect of filename's texture will be applied for this sprite.
* @return A valid sprite object that is marked as autoreleased.
* @param filename A path to image file, e.g., "scene1/monster.png"
* @param rect A subrect of the image file
* @return An autoreleased sprite object
*/
static Sprite* create(const std::string& filename, const Rect& rect);
/**
* Creates a sprite with an exsiting texture contained in a Texture2D object
* Creates a sprite with a Texture2D object.
*
* After creation, the rect will be the size of the texture, and the offset will be (0,0).
*
* @param texture A pointer to a Texture2D object.
* @return A valid sprite object that is marked as autoreleased.
* @return An autoreleased sprite object
*/
static Sprite* createWithTexture(Texture2D *texture);
@ -135,17 +134,17 @@ public:
* You can use a Texture2D object for many sprites.
* @param rect Only the contents inside the rect of this texture will be applied for this sprite.
* @param rotated Whether or not the rect is rotated
* @return A valid sprite object that is marked as autoreleased.
* @return An autoreleased sprite object
*/
static Sprite* createWithTexture(Texture2D *texture, const Rect& rect, bool rotated=false);
/**
* Creates a sprite with an sprite frame.
*
* @param pSpriteFrame A sprite frame which involves a texture and a rect
* @return A valid sprite object that is marked as autoreleased.
* @param spriteFrame A sprite frame which involves a texture and a rect
* @return An autoreleased sprite object
*/
static Sprite* createWithSpriteFrame(SpriteFrame *pSpriteFrame);
static Sprite* createWithSpriteFrame(SpriteFrame *spriteFrame);
/**
* Creates a sprite with an sprite frame name.
@ -154,7 +153,7 @@ public:
* If the SpriteFrame doesn't exist it will raise an exception.
*
* @param spriteFrameName A null terminated string which indicates the sprite frame name.
* @return A valid sprite object that is marked as autoreleased.
* @return An autoreleased sprite object
*/
static Sprite* createWithSpriteFrameName(const std::string& spriteFrameName);

2
cocos/2d/cocos2d.cpp
View File

@ -31,7 +31,7 @@ NS_CC_BEGIN
const char* cocos2dVersion()
{
return "3.0-beta2";
return "3.0-rc0";
}
NS_CC_END

6
cocos/2d/renderer/CCQuadCommand.h
View File

@ -34,6 +34,7 @@ NS_CC_BEGIN
#define CC_NO_TEXTURE 0
/** Command used to render one or more Quads */
class QuadCommand : public RenderCommand
{
public:
@ -41,7 +42,9 @@ public:
QuadCommand();
~QuadCommand();
void init(float depth, GLuint texutreID, GLProgram* shader, BlendFunc blendType, V3F_C4B_T2F_Quad* quads, ssize_t quadCount,
/** Initializes the command with a globalZOrder, a texture ID, a `GLProgram`, a blending function, a pointer to quads,
* quantity of quads, and the Model View transform to be used for the quads */
void init(float globalOrder, GLuint texutreID, GLProgram* shader, BlendFunc blendType, V3F_C4B_T2F_Quad* quads, ssize_t quadCount,
const kmMat4& mv);
void useMaterial() const;
@ -71,7 +74,6 @@ protected:
GLuint _textureID;
GLProgram* _shader;
// GLuint _shaderID;
BlendFunc _blendType;

5
cocos/2d/renderer/CCRenderCommand.h
View File

@ -33,8 +33,9 @@
NS_CC_BEGIN
/** Base class of the RenderCommand hierarchy.
The Renderer knows how to render RenderCommands.
/** Base class of the `RenderCommand` hierarchy.
*
The `Renderer` knows how to render `RenderCommands` objects.
*/
class RenderCommand
{

26
cocos/2d/renderer/CCRenderer.h
View File

@ -38,11 +38,10 @@ NS_CC_BEGIN
class EventListenerCustom;
class QuadCommand;
/** Class that knows how to sort the Commands.
Since the commands that have z==0 are "pushed back" in
the correct order, the only Commands that need to be sorted,
are the ones that have z <0 and z >0.
And that is what this class does.
/** Class that knows how to sort `RenderCommand` objects.
Since the commands that have `z == 0` are "pushed back" in
the correct order, the only `RenderCommand` objects that need to be sorted,
are the ones that have `z < 0` and `z > 0`.
*/
class RenderQueue {
@ -65,7 +64,9 @@ struct RenderStackElement
ssize_t currentIndex;
};
/* Class reponsible for the rendering in cocos2d
/* Class responsible for the rendering in.
Whenever possible prefer to use `QuadCommand` objects since the renderer will automatically batch them.
*/
class Renderer
{
@ -79,13 +80,22 @@ public:
//TODO manage GLView inside Render itself
void initGLView();
//TODO support multiple viewport
/** Adds a `RenderComamnd` into the renderer */
void addCommand(RenderCommand* command);
/** Adds a `RenderComamnd` into the renderer specifying a particular render queue ID */
void addCommand(RenderCommand* command, int renderQueue);
/** Pushes a group into the render queue */
void pushGroup(int renderQueueID);
/** Pops a group from the render queue */
void popGroup();
/** Creates a render queue and returns its Id */
int createRenderQueue();
/** Renders into the GLView all the queued `RenderCommand` objects */
void render();
/* returns the number of drawn batches in the last frame */

10
docs/MainPage.h
View File

@ -5,8 +5,8 @@
@section sec1 About cocos2d-x
cocos2d-x open source project is designed to be a cross-platform 2D game engine for building 2D games, demos and other graphical/interactive mobile applications.
It runs on OpenGL ES 1.1, and is written in C++ language, provides C++ API.\n
This project is based on the famous <A HREF="http://www.cocos2d-iphone.org">"cocos2d-iphone"</A> project, and will keep pace with it. \n
It runs on top of OpenGL 2.0 and OpenGL ES 2.0 and is written in C++.\n
This project is based on the famous <A HREF="http://www.cocos2d-iphone.org">"cocos2d-iphone"</A> project.\n
- website: http://www.cocos2d-x.org/
- forum: http://forum.cocos2d-x.org/
@ -17,7 +17,7 @@ This project is based on the famous <A HREF="http://www.cocos2d-iphone.org">"coc
- <A HREF="http://www.cocos2d-x.org/projects/cocos2d-x/wiki/Tutorials">Tutorials of Cocos2dxSimpleGame</A>
- <A HREF="http://www.cocos2d-x.org/projects/cocos2d-x/wiki/Installation_and_First_run">Installation and First run</A>
- <A HREF="http://www.cocos2d-x.org/boards/6/topics/567">DEVELOP FAQ</A>
- <A HREF="http://www.cocos2d-x.org/boards/6/topics/567">FAQ</A>
\n
@ -46,11 +46,11 @@ THE SOFTWARE. \n
@section sec3 Get the source code
- Stable version: \n
- publish at http://download.cocos2d-x.org/
- Last code: \n
- Latest code: \n
- http://github.com/cocos2d/cocos2d-x/
@section sec4 How to contribute
- Fork our repository on github, commit your changes, and send a "pull request" to us. We will merge your contribution to master
- Any suggestion, bug fix, improvment will be appreciated.
- Suggestion, bug fixes, and improvements are highly appreciated.
*/