cocos2d-X 节点（CCNode.h）API
本文来自http://blog.csdn.net/runaying ，引用必须注明出处！
cocos2d-X 节点（CCNode.h）API
温馨提醒：为了大家能更好学习，强烈推荐大家看看本人的这篇博客 Cocos2d-X权威指南笔记
这个类是一个基础类，最常用的 Node 有: Scene, Layer, Sprite, Menu
1.图形getter、setter 属性 （z 顺序、OpenGL 顶点、位置、缩放、旋转、倾斜角、锚点、尺寸、是否可见......）
2.children 和 parent 之间的关系（添加/删除 children、为children 添加识别码、获取 children 总数、获取 children 的parent......）
3.设置对象效果、为对象设置 schedule、各种坐标的相互转换、添加移除组件
#ifndef __PLATFORM_CCNODE_H__
#define __PLATFORM_CCNODE_H__
#include "ccMacros.h"
#include "cocoa/CCAffineTransform.h"
#include "cocoa/CCArray.h"
#include "CCGL.h"
#include "shaders/ccGLStateCache.h"
#include "shaders/CCGLProgram.h"
#include "kazmath/kazmath.h"
#include "script_support/CCScriptSupport.h"
#include "CCProtocols.h"
NS_CC_BEGIN
class Camera;
class GridBase;
class Point;
class Touch;
class Action;
class RGBAProtocol;
class LabelProtocol;
class Scheduler;
class ActionManager;
class Component;
class Dictionary;
class ComponentContainer;
/**
* @添加到组 base_nodes
* @{
*/
enum {
kNodeTagInvalid = -1,
};
enum {
kNodeOnEnter,
kNodeOnExit,
kNodeOnEnterTransitionDidFinish,
kNodeOnExitTransitionDidStart,
kNodeOnCleanup
};
//简要
/** @简要 Node 是主要元素. 所有被绘制或者包含的东西都是 Node.
最常用的 Node 有: Scene, Layer, Sprite, Menu.
Node 的主要特点是:
- 它可以包含其它的 Node nodes (addChild, getChildByTag, removeChild, etc)
- 他们可以定期回调 (schedule, unschedule, etc)
- 它们可以执行动作(runAction, stopAction, etc)
一些 Node nodes 它们的子节点为他们提供额外的功能.
子节点通常包含下面的 (one/all) :
- 重写 init 来初始化资源和进度回调
- 随着时间的推进创建回调 handle
- 重写 draw 来渲染 node
节点的特点:
- position
- scale (x, y)//尺寸
- rotation (in degrees, clockwise)//旋转（以度为单位，顺时针方向）
- Camera (an interface to gluLookAt ) //（视点转换函数接口）
- GridBase (to do mesh transformations)//（网格转换）
- anchor point //锚点
- size
- visible
- z-order //给定的名称排序
- openGL z position //
默认值:
- rotation: 0 //旋转
- position: (x=0,y=0)
- scale: (x=1,y=1)
- contentSize: (x=0,y=0) //内容大小
- anchorPoint: (x=0,y=0) //锚点
限制:
- 一个节点是一个 "void" 对象. 它没有 texture
转换为不可见的顺序
-# 节点将转换 translated (position) //位置
-# 节点将转换 rotated (rotation) //旋转
-# 节点将转换 scaled (scale) //规模
-# 节点根据中心点的值移动
转换为可见的顺序
-# 节点将转换 translated (position) //位置
-# 节点将转换 rotated (rotation) //旋转
-# 节点将转换 scaled (scale) //规模
-# 将在屏幕中占据位置
-# 节点根据中心点的值移动
-# 将渲染所占据的屏幕
中心点:
- 每个节点都有一个中心点。默认情况下，它指向 Node 的中心节点。
*/
class CC_DLL Node : public Object
{
public:
构造函数名和析构函数的初始化
/// @{
/// @构造函数的名称, 析构函数的初始化
/**
* 分配并初始化一个节点。
* @return 一个被标记为 "autorelease" 的初始化的节点.
*/
static Node * create(void);
/**
* 默认的构造方法
*/
Node(void);
/**
* 默认的析构函数
*/
virtual ~Node(void);
/**
* 初始化一个节点的实例
* @return 返回是否初始化成功.
*/
virtual bool init();
/**
* 获取的描述字符串。这使得调试更加容易。
* @return 一个字符串，当字符串是 '\0' 的时候终止
*/
const char* description(void) const;
/// @} 初始化结束
图形属性的 getter 和 setter 方法名称
/// @{
/// @图形属性的 getter 和 setter 方法名称
/**
* 设置 Z 顺序代表绘制顺序, 并重新排序这个节点在其父节点的孩子数组中的位置
*
* Z 顺序的节点是相对于它的 "brothers": 子节点有相同的 parent.
* OpenGL's z 顶点什么也没有做. 它只是在 cocos2d 中影响节点的绘制顺序.
* 号码越大, 这个节点在这个消息队列中越晚被绘制。
* 请参考到setVertexZ（浮动）的区别。
*
* @param nZOrder 这个节点 Z 顺序。.
*/
virtual void setZOrder(int zOrder);
/**
* 标准的设置 z 的绘制顺序 setter
*
* 这是一个内部的方法。不要把它用在框架之外。
* setZOrder(int) 和 _setOrder(int) 的却别是:
* - _setZOrder(int) 简单的为 _ZOrder 设置成员变量
* - setZOrder(int) 首先改变 _ZOrder, 然后把这个节点写入其 parent's 孩子 array.
*/
virtual void _setZOrder(int z);
/**
* 获取这个节点Z顺序。.
*
* @请参考 setZOrder(int)
*
* @return Z顺序.
*/
virtual int getZOrder() const;
/**
* 设置真实的 OpenGL Z 顶点.
*
* openGL 的 Ž 顶点和 cocos2d 的 Z 顺序之间的差异:
* - OpenGL 的 Ž 修改的 Z 顶点，不是 parent-children 之间的 Z 顺序
* - OpenGL 的 Z 可能需要设置 2D 投影
* - 如果所有的节点使用相同的 OpenGL Ž 顶点，那么 cocos2d 的 Z 顺序工程确定的. eg: vertexZ = 0
*
* @warning 使用它有破坏 cocos2d parent-children z 顺序的风险
*
* @param fVertexZ 这个节点的 OpenGL Z 顶点.
*/
virtual void setVertexZ(float vertexZ);
/**
* 获取这个节点 OpenGL Z 顶点.
*
* @请看 setVertexZ(float)
*
* @return 这个节点的 OpenGL Z 顶点
*/
virtual float getVertexZ() const;
/**
* 改变这个节点 X 轴上的比例因子
*
* 如果你之前没有改变，它的默认值就是 1.0
*
* @param scaleX X轴的比例因子。
*/
virtual void setScaleX(float scaleX);
/**
* Returns 这个节点在 X 轴上的比例因子
*
* @请看 setScaleX(float)
*
* @return X轴的比例因子。
*/
virtual float getScaleX() const;
/**
* 改变这个节点 Y 轴上的比例因子
*
* 如果你之前没有改变，它的默认值就是 1.0
*
* @param scaleY Y 轴的比例因子。
*/
virtual void setScaleY(float scaleY);
/**
* Returns 这个节点在 X 轴上的比例因子
*
* @请看 setScaleY(float)
*
* @return Y 轴的比例因子。
*/
virtual float getScaleY() const;
/**
* 改变这个节点的 X 轴和 Y 轴上的比例因子
*
* 1.0 是默认的比例因子. 在同一时间修改 X 和 Y 轴 上的比例因子
*
* @param scale X 和 Y 轴的比例因子.
*/
virtual void setScale(float scale);
/**
* 获取这个节点的比例因子, X 和 Y 轴拥有相同的比例因子
*
* @warning 这并意味着 _scaleX != _scaleY ，因为你可以单独修改它们其中的一个例如： setScaleY(float scaleY);
* @请看 setScale(float)
*
* @return 这个节点的比例因子.
*/
virtual float getScale() const;
/**
* 改变这个节点的 OpenGL (x,y)坐标位置
*
* 通常，我们使用点（X，Y）组成的Point对象。
* 原始点（0,0）在屏幕左下角。
* For example, 这个代码片段设置它的 node 在 屏幕的中心
* @code
* Size size = Director::getInstance()->getWinSize();
* node->setPosition( Point(size.width/2, size.height/2) )
* @endcode
*
* @param 这个节点的 OpenGL (x,y)坐标位置
*/
virtual void setPosition(const Point &position);
/**
* 获取这个节点的 OpenGL (x,y)坐标位置
*
* @请看 setPosition(const Point&)
*
* @return 这个 node 在 OpenGL 坐标节点的位置（X，Y）
*/
virtual const Point& getPosition() const;
/**
* 更有效的设置位置的方式.
*
* 传递两个数字（X，Y）的效率比经过点对象的效率要高。
* 这个方法在 Lua 和 Javascript 绑定了
* 传递一个数字的速度 lua C++ 对象的十倍
*
* @code
* // Lua中的示例代码
* local pos = node::getPosition() -- returns 从 C++ 返回 Point
* node:setPosition(x, y) -- 在 C++ 中传递 x, y 坐标
* @endcode
*
* @param x X 坐标位置
* @param y Y 坐标位置
*/
virtual void setPosition(float x, float y);
/**
* 更有效的获取位置的方式, returns 两个数字代替 Point 对象
*
* @请看 setPosition(float, float)
*/
virtual void getPosition(float* x, float* y) const;
/**
* Gets/Sets x 或者 y 个别坐标的位置
* 这个方法在 Lua 和 Javascript 绑定了
*/
virtual void setPositionX(float x);
virtual float getPositionX(void) const;
virtual void setPositionY(float y);
virtual float getPositionY(void) const;
/**
* 改变节点在 X 轴方向上的倾斜角度
*
* 这个角度描述了在X方向上的剪切变形。
* 因此，它是 Y 轴和形状的左边缘之间的角度
* skewX 默认角度是 0. 有效的数值改变了 node 在 CW 上的方向
*
* @param fSkewX 节点在 Y 轴方向上的倾斜角度.
*/
virtual void setSkewX(float fSkewX);
/**
* Returns 节点在 X 轴方向上的倾斜角度.
*
* @请看 setSkewX(float)
*
* @return 节点在 X 轴方向上的倾斜角度
*/
virtual float getSkewX() const;
/**
* 改变节点在 Y 轴方向上的倾斜角度.
*
* 这个角度描述了在X方向上的剪切变形。
* 因此，它是 X 轴和形状的左边缘之间的角度
* skewX 默认角度是 0. 有效的数值改变了 node 在 CW 上的方向
*
* @param fSkewY 节点在 Y 轴方向上的倾斜角度
*/
virtual void setSkewY(float fSkewY);
/**
* Returns 改变节点在 Y 轴方向上的倾斜角度
*
* @请看 setSkewY(float)
*
* @return 节点在 Y 轴方向上的倾斜角度.
*/
virtual float getSkewY() const;
/**
* 设定锚点的％.
*
* 锚点是所有的转换和定位操作围绕的点。
* 这就像一根针在 "attached" (附加) 到其父节点.
* 锚点被统一化，像一个百分比。 （0,0）表示的左下角（1,1）表示右上角。
* 但是你可以用值高于（1,1）低于（0,0）以外的值。
* 默认的锚点是（0.5,0.5），所以它开始在中心节点。
*
* @param anchorPoint node 的锚点.
*/
virtual void setAnchorPoint(const Point& anchorPoint);
/**
* Returns 锚点的％.
*
* @请看 setAnchorPoint(const Point&)
*
* @return node 的锚点.
*/
virtual const Point& getAnchorPoint() const;
/**
* Returns 锚点的绝对像素位置
*
* @warning 您只能读取它。如果你想修改它，使用锚点代替.
* @see getAnchorPoint()
*
* @return 锚点的绝对像素位置.
*/
virtual const Point& getAnchorPointInPoints() const;
/**
* 设定的节点未转化时的大小。
*
* 无论该节点缩放或旋转 contentSize 仍然相同
* 所有节点都有大小。层和场景具有相同大小的屏幕。
*
* @param contentSize 节点未转化时的大小。
*/
virtual void setContentSize(const Size& contentSize);
/**
* Returns 节点的未转化的大小。
*
* @see 请看 setContentSize(const Size&)
*
* @return 节点未转化时的大小。
*/
virtual const Size& getContentSize() const;
/**
* 设置节点是否可见
*
* 默认值是true，节点是默认可见
*
* @param visible true 代表 node 可见, false 代表当前 node 不可见.
*/
virtual void setVisible(bool visible);
/**
* 确定节点是否可见
*
* @see setVisible(bool)
*
* @return true 代表 node 可见, false 代表当前 node 不可见.
*/
virtual bool isVisible() const;
/**
* 设置节点度旋转（角度）。
*
* 0 是默认的旋转角度.
* 节点沿顺时针旋转是正值，反时针方向为负值。
*
* @param rotation The rotation of the node in degrees.
*/
virtual void setRotation(float rotation);
/**
* Returns 节点度旋转（角度）。
*
* @see setRotation(float)
*
* @return The rotation of the node in degrees.
*/
virtual float getRotation() const;
/**
* 设置 node x 轴 旋转（角度）水平方向进行旋转偏移
*
* 0 是默认的旋转角度.
* 节点沿顺时针旋转是正值，反时针方向为负值。
*
* @param fRotationX node x 轴 旋转（角度）水平进行旋转偏移
*/
virtual void setRotationX(float rotaionX);
/**
* 获取 node x 轴 旋转（角度）水平方向进行的旋转偏移
*
* @see setRotationX(float)
*
* @return X轴旋转的度数。
*/
virtual float getRotationX() const;
/**
* 设置 node y 轴 旋转（角度）水平方向进行旋转偏移
*
* 0 是默认的旋转角度.
* 节点沿顺时针旋转是正值，反时针方向为负值。
*
* @param fRotationY y轴旋转的度数。
*/
virtual void setRotationY(float rotationY);
/**
* 返回 node y 轴 旋转（角度）水平方向进行旋转偏移
*
* @see setRotationY(float)
*
* @return X轴旋转的度数。.
*/
virtual float getRotationY() const;
/**
* 当这个节点和其它的 children 有相同 Z 顺序时，设置它们的到达顺序
*
* node addChild 越晚，到达顺序就越大
* 如果两个 children 有相同的 Z 顺序到达的顺序较大，children 将被绘制越早
*
* @warning 这个方法是内部 z 排序,不要手动调用
*
* @param orderOfArrival 到达顺序.
*/
virtual void setOrderOfArrival(int orderOfArrival);
/**
* Returns 到达顺序, 表示先前添加的 children
*
* @see setOrderOfArrival(unsigned int)
*
* @return 到达顺序.
*/
virtual int getOrderOfArrival() const;
/** @过时不再需要建议使用新的 API*/
CC_DEPRECATED_ATTRIBUTE void setGLServerState(int serverState) { /* ignore */ };
/** @过时不再需要建议使用新的 API */
CC_DEPRECATED_ATTRIBUTE int getGLServerState() const { return 0; }
/**
* 是否将锚点的位置设置为 (0,0) .
*
* 这是一个内部的方法，只在 Layer 和 Scenne 中使用。不要把它的框架之外。
* 默认值是 false, 在 Layer 和 Scene 里面是 true
*
* @param ignore true 如果你希望锚点的位置是 (0,0)
* @todo 这个方法应该改名为 setIgnoreAnchorPointForPosition(bool)
*/
virtual void ignoreAnchorPointForPosition(bool ignore);
/**
* 返回 是否将锚点的位置设置为 (0,0) .
*
* @see ignoreAnchorPointForPosition(bool)
*
* @return true 如果你希望锚点的位置是 (0,0)
*/
virtual bool isIgnoreAnchorPointForPosition() const;
/// @} end of Setters & Getters 图形属性
Children 和 Parent 名字
/// @{
/// @name Children and Parent
/**
* 往容器里面添加一个 child z-order 顺序是 0. //（z 顺序）
*
* 如果 child 加入到一个 'running' node，'onEnter' 和 'onEnterTransitionDidFinish' 将会立即被调用.
*
* @param child 一个 child 节点
*/
virtual void addChild(Node * child);
/**
* 使用 z-order 往容器里面添加一个 child
*
* 如果 child 加入到一个 'running' node，'onEnter' 和 'onEnterTransitionDidFinish' 将会立即被调用.
*
* @param child 一个 child node
* @param zOrder Z次序绘制优先权。请参阅 setZOrder(int)
*/
virtual void addChild(Node * child, int zOrder);
/**
* 使用 z-order 和标签 往容器里面添加一个 child
*
* 如果 child 加入到一个 'running' node，'onEnter' 和 'onEnterTransitionDidFinish' 将会立即被调用.
*
* @param child 一个 child node
* @param zOrder Z次序绘制优先权。请参阅 setZOrder(int)
* @param tag 一个整数来方便识别节点. 请参阅下面将会提到的 setTag(int)
*/
virtual void addChild(Node* child, int zOrder, int tag);
/**
* 使用 tag 从容器中获取 child
*
* @param tag 一个可以找到 child node 的标记.
*
* @return 一个签等于输入参数的 Node 对象
*/
Node * getChildByTag(int tag);
/**
* Return 一个 children 数组
*
* 节点非常重要的组成结构 "tree"
* 下面是一个示例代码遍历 children 阵列：
* @code
* Node* node = NULL;
* CCARRAY_FOREACH(parent->getChildren(), node)
* {
* node->setPosition(0,0);
* }
* @endcode
* 此示例代码遍历所有子节点，并设置它们位置为（0,0）
*
* @return 一个 children 数组
*/
virtual Array* getChildren() { return _children; }
virtual const Array *getChildren() const { return _children; }
/**
* 获取 children 总数
*
* @return children 总数
*/
unsigned int getChildrenCount() const;
/**
* 设置parent node
*
* @param parent 一个指向 parnet node 的指针
*/
virtual void setParent(Node* parent);
/**
* Returns 一个指向 parnet node 的指针
*
* @see setParent(Node*)
*
* @returns 一个指向 parnet node 的指针
*/
virtual Node* getParent() { return _parent; }
virtual const Node* getParent() const { return _parent; }
////// REMOVES //////
/**
* 从其 praent node 删除此节点本身并清理所有正在运行的行动
* 如果只有一个节点什么也不会发生
* @see removeFromParentAndCleanup(bool)
*/
virtual void removeFromParent();
/**
* 从其 praent node 删除此节点本身
* 如果只有一个节点什么也不会发生.
* @param cleanup true 这个节点所有的 actions 和 callbacks 都将被删除, false 否则返回 false.
*/
virtual void removeFromParentAndCleanup(bool cleanup);
/**
* 从容器中移除一个孩子。也将根据清理参数，清理所有正在运行的行动。
*
* @param child 一个将要移出的 child node.
* @param cleanup true 这个节点所有的 actions 和 callbacks 都将被删除, false 否则返回 false.
*/
virtual void removeChild(Node* child, bool cleanup = true);
/**
* 根据 tag 从容器中中移除一个孩子。也将根据清理参数，清理所有正在运行的行动
*
* tag 一个可以找到 child node 的标记.
* @param cleanup true 这个节点所有的 actions 和 callbacks 都将被删除, false 否则返回 false.
*/
virtual void removeChildByTag(int tag, bool cleanup = true);
/**
* 删除所有节点本身并清理所有正在运行的行动
*
* @see removeAllChildrenWithCleanup(bool)
*/
virtual void removeAllChildren();
/**
* 从容器中移出所有的节点, 也将根据清理参数，清理所有正在运行的行动
*
* @param cleanup true 这个节点所有的 actions 和 callbacks 都将被删除, false 否则返回 false.
*/
virtual void removeAllChildrenWithCleanup(bool cleanup);
/**
* 根据新的Z值重新排序 chlid。
*
* @param child 一个准备添加的 child node. 它必须准备好被添加
* @param zOrder Z次序绘制优先权。请参阅 setZOrder(int)
*/
virtual void reorderChild(Node * child, int zOrder);
/**
* 在绘制前排序一次 children 数组，代替每一次增减 children 时排序一次
* 这是大规模提升性能的途径
* @注意 除非子节点在同一帧内附加后被删除，不然不要手动调用此方法
*/
virtual void sortAllChildren();
/// @} end of Children and Parent
网格对象效果
/// @{
/// @name Grid object for effects //网格对象效果
/**
* Returns 一个网格对象被使用时应用的效果
*
* @return 一个网格对象被使用时应用的效果
*/
virtual GridBase* getGrid() { return _grid; }
virtual const GridBase* getGrid() const { return _grid; }
/**
* 改变一个网格对象被使用时应用效果
*
* @param 一个网格对象被使用时应用的效果
*/
virtual void setGrid(GridBase *grid);
/// @} end of Grid
表签名和用户数据
/// @{
/// @name Tag & User data
/**
* Returns 一个方便识别节点的标记.
*
* 你可以为节点设置身份标签使他们容易找到.
* @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 = NULL;
* CCARRAY_FOREACH(parent->getChildren(), node)
* {
* switch(node->getTag())
* {
* case TAG_PLAYER:
* break;
* case TAG_MONSTER:
* break;
* case TAG_BOSS:
* break;
* }
* }
* @endcode
*
* @return 一个方便识别节点的标记.
*/
virtual int getTag() const;
/**
* 改变标签的标记，可以方便识别节点
*
* 请参阅 上面 getTag 里面的 sample code.
*
* @param 一个识别节点的 interger 数字
*/
virtual void setTag(int tag);
/**
* Returns 一个用户自定义的指针数据
*
* 在用户数据的指针你可以设置所有事情一个数据块的结构或一个对象
*
* @return A custom user data pointer
*/
virtual void* getUserData() { return _userData; }
virtual const void* getUserData() const { return _userData; }
/**
* Sets 一个用户自定义的指针数据
*
* 在用户数据的指针你可以设置所有事情一个数据块的结构或一个对象, etc.
* @warning 不要忘记手动释放内存, 特别是你在这个节点自动释放前你要释放这个数据指针
*
*
* @param 一个自定义的用户数据指针
*/
virtual void setUserData(void *userData);
/**
* Returns 一个用户分配的对象
*
* 类似 UserData, 代替用户拥有的对象.
*
* @return 一个用户分配的对象
*/
virtual Object* getUserObject() { return _userObject; }
virtual const Object* getUserObject() const { return _userObject; }
/**
* Returns 一个用户分配的对象
*
* 类似 UserData, 代替用户拥有的对象.
* UserObject 只能在该方法中保存一个对象,
* 如果以前保存过用户数据 UserObject 新的 UserObject 会覆盖旧的
* UserObject 将会在这个节点的析构函数里面释放
*
* @param 一个用户分配的对象
*/
virtual void setUserObject(Object *userObject);
/// @} end of Tag & User Data
颜色着色器
/// @{
/// @name Shader Program
/**
* Return 此节点目前使用的着色器
*
* @return 此节点目前使用的着色器
*/
virtual GLProgram* getShaderProgram() { return _shaderProgram; }
virtual const GLProgram* getShaderProgram() const { return _shaderProgram; }
/**
* Sets 此节点目前使用的着色器
*
* 从2.0开始，每个渲染节点必须拥有它的着色器程序。.
* 它应该在初始化阶段设置。
* @code
* node->setShaderProgram(ShaderCache::getInstance()->programForKey(GLProgram::SHADER_NAME_POSITION_TEXTURE_COLOR));
* @endcode
*
* @param 着色器程序保存在 ShaderCache
*/
virtual void setShaderProgram(GLProgram *shaderProgram);
/// @} end of Shader Program
/** @{
/// @name Event Callbacks
* Returns 让你使用节点对象的 gluLookAt 移动视角到 camera 位置
*
* @code
* Camera* camera = node->getCamera();
* camera->setEyeXYZ(0, 0, 415/2);
* camera->setCenterXYZ(0, 0, 0);
* @endcode
*
* @return 让你使用节点对象的 gluLookAt 移动视角到 camera 位置
*/
virtual Camera* getCamera();
/**
* Returns 节点是否正在接受事件的回调。
*
* Running 代表这个节点正在接受事件回调例如 onEnter(), onExit(), update()
*
* @return 节点是否正在接受事件的回调。
*/
virtual bool isRunning() const;
/**
* lua 脚本的时间表.
*/
void scheduleUpdateWithPriorityLua(int handler, int priority);
/// @} end Script Bindings /// @{
/// @name Event Callbacks
事件回调名
/**
* 事件被调用的回调函数，每次节点进入'stage'.
* 如果节点过渡到一个 'stage', 这个事件叫做过渡开始.
* 在 onEnter 时你不能进入 "sister/brother" 节点.
* 如果你重写了 onEnter, 你应该告诉它的 parent's, e.g., Node::onEnter().
*/
virtual void onEnter();
/** 事件回调时调用的节点进入'stage'.
* 如果节点已经过渡到一个 'stage', 这个事件叫做过渡开始..
* I如果你重写了 onEnterTransitionDidFinish, 你应该通知他的 parent's, e.g. Node::onEnterTransitionDidFinish()
*/
virtual void onEnterTransitionDidFinish();
/**
* 事件被调用的回调函数，每次节点离开 'stage'.
* 如果节点过渡到离开 'stage' , 这个事件叫做过渡结束
* 在 onExit 时你不能进入 "sister/brother" 节点..
* 如果你重写了 onExit, 你应该通知他的 parent's, e.g., Node::onExit().
*/
virtual void onExit();
/**
* Event 被调用的回调函数，每次节点离开 'stage'.
* 如果节点已经过渡到离开 'stage' , 即将进入下一个场景时调用，有关场景转换的顺序可以参考
* http://blog.csdn.net/nono_love_lilith/article/details/7756361.
*/
virtual void onExitTransitionDidStart();
/// @} end of event callbacks.
/**
* 停止所有的调度和 Action
*/
virtual void cleanup();
/**
* 重写这个方法绘制自己的 node
* GL 状态跟踪默认启用
* - glEnableClientState(GL_VERTEX_ARRAY);
* - glEnableClientState(GL_COLOR_ARRAY);
* - glEnableClientState(GL_TEXTURE_COORD_ARRAY);
* - glEnable(GL_TEXTURE_2D);
* @note 你不应该禁用后绘制节点
* 但是，如果您启用任何其他GL状态，你应该先绘制的节点然后禁用它。
*/
virtual void draw();
/**
* 递归绘制这个节点的 children 节点.
*/
virtual void visit();
/**
* Returns 包围节点的轴对称矩形
* 返回的节点相对于它们的 parent.
*
* @note 这个方法返回一个临时变量所以不能返回 const Rect&
* @todo 重命名为getBoundingBox() 在未来的版本
*
* @return 包围节点的轴对称矩形.
*/
virtual Rect getBoundingBox() const;
/** @弃用的属性建议使用 getBoundingBox 代替 */
CC_DEPRECATED_ATTRIBUTE inline virtual Rect boundingBox() const { return getBoundingBox(); }
Action名
/// @{
/// @name Actions
/**
* 设置 ActionManager 的对象所使用的所用动作.
*
* @warning 如果你设置了一个新的 ActionManager, 那么你以前创建的 action 将会被移除
*
* @param actionManager 一个 ActionManager 的对象所使用的所用动作.
*/
virtual void setActionManager(ActionManager* actionManager);
/**
* 获取ActionManager 的对象所使用的所用动作
* @see setActionManager(ActionManager*)
* @return 一个 ActionManager 对象.
*/
virtual ActionManager* getActionManager() { return _actionManager; }
virtual const ActionManager* getActionManager() const { return _actionManager; }
/**
* 执行相应的动作，并返回执行的动作
*
* 该节点将成为行动的目标。 ，请参阅 Action::getTarget()
* @warning 动作不保留他们的目标。
*
* @return 一个 action 指针
*/
Action* runAction(Action* action);
/**
* 从运行的 action 列表里面停止并移除所有的 action
*/
void stopAllActions();
/**
*从 action 列表里面停止相应的 action.
*
* @param 一个 action 对象将被移除.
*/
void stopAction(Action* action);
/**
* 根据标记从相应的 action 列表里面移除相应的 action.
*
* @param 一个将要移除的action标记
*/
void stopActionByTag(int tag);
/**
* 根据标记从相应的 action 列表里面回去相应的 action
*
* @see setTag(int), getTag().
*
* @return 指定标记所对应的 action 对象.
*/
Action* getActionByTag(int tag);
/**
* 返回正在运行的 action 加上进度表里面的 action 数量 (actions 在 actionsToAdd 和 actions arrays).
*
* 组合的动作都算为1的动作。例如:
* 如果你正在运行 1 包含 7 actions 的序列, 它将会返回 1.
* 如果你正在运行 7 包含 2 actions 的序列, 它将会返回
* @todo 重命名为 getNumberOfRunningActions()
*
* @return 返回正在运行的 action 加上进度表里面的 action 数量
*/
unsigned int getNumberOfRunningActions() const;
/** @弃用的属性建议使用 getNumberOfRunningActions() 代替 */
CC_DEPRECATED_ATTRIBUTE unsigned int numberOfRunningActions() const { return getNumberOfRunningActions(); };
/// @} end of Actions
预定的计时器
/// @{
/// @name Scheduler and Timer
/**
* 设置一个用于安排所有更新和定时器的 Scheduler 对象
*
* @warning 如果你设置了一个新的 Scheduler，那么先前创建的定时器/更新都将被删除。
* @param scheduler 一个用于安排所有更新和定时器的 Scheduler 对象
*/
virtual void setScheduler(Scheduler* scheduler);
/**
* Gets 一个 Scheduler 对象.
*
* @see setScheduler(Scheduler*)
* @return 一个 Scheduler 对象
*/
virtual Scheduler* getScheduler() { return _scheduler; }
virtual const Scheduler* getScheduler() const { return _scheduler; }
/**
* Checks 这个 scheduled 对象是否被选择.
*
* @param selector 包装成 selector 的功能函数
* @return 这个 scheduled 对象是否被选择
*/
bool isScheduled(SEL_SCHEDULE selector);
/**
* 时间表的更新方法
*
* 它使用的顺序号为0。这个方法每一帧都会调用。
* Scheduled 的序列值越低，越先被调用
* 只有一个 "update" 方法可以 scheduled 每一个节点
*/
void scheduleUpdate(void);
/**
* 自定义优先级的时间表更新方法
*
* 这个选择器每一帧都会调用.
* Scheduled 的序列值越低，越先被调用
* 只有一个 "update" 方法可以 scheduled 每一个节点 (你不可以拥有 2 个 'update' 选择器).
*/
void scheduleUpdateWithPriority(int priority);
/*
* 取消更新方法
* @see scheduleUpdate();
*/
void unscheduleUpdate(void);
/**
* 自定义选择时间表
*
* 如果已经选择 scheduled 将根据间隔参数更新，而不是每次都调用 scheduled
* @code
* // 首先实现 schedule 的功能函数
* void MyNode::TickMe(float dt);
* // 然后通过 schedule_selector 把功能函数包装成一个 selector
* this->schedule(schedule_selector(MyNode::TickMe), 0, 0, 0);
* @endcode
*
* @param interval 时间间隔以秒为单位，0 意味着每一帧，如果时间间隔 ＝ 0 ，建议使用 scheduleUpdate（）来代替
* @param repeat 这个 selector 将执行 (repeat + 1) 次,你想使它无限次数重复调用，你可以使用 kRepeatForever
* @param delay 每次调用的延迟时间
*/
void schedule(SEL_SCHEDULE selector, float interval, unsigned int repeat, float delay);
/**
* 时间表每隔一段时间自动选择.
* @see schedule(SEL_SCHEDULE, float, unsigned int, float)
*
* @param selector 包装成 selector 的功能函数
* @param interval 时间间隔以秒为单位，0 意味着每一帧
*/
void schedule(SEL_SCHEDULE selector, float interval);
/**
*只运行一次的时间表延迟是0或者更大
* @see schedule(SEL_SCHEDULE, float, unsigned int, float)
*
* @param selector 包装成 selector 的功能函数
* @param delay 每次调用的延迟时间
*/
void scheduleOnce(SEL_SCHEDULE selector, float delay);
/**
* 时间表每帧都自定义选择
* @see schedule(SEL_SCHEDULE, float, unsigned int, float)
*
* @param selector 包装成 selector 的功能函数
*/
void schedule(SEL_SCHEDULE selector);
/**
*取消自定义选择.
* @see schedule(SEL_SCHEDULE, float, unsigned int, float)
*
* @param selector 包装成 selector 的功能函数
*/
void unschedule(SEL_SCHEDULE selector);
/**
* 取消所有的时间表选择包括自定义选择和更新选择
* 用这种方法 action 不受影响。
*/
void unscheduleAllSelectors(void);
/**
* 恢复所有时间表选择和 action
* 这个方法在 onEnter 内部调用
*/
void resumeSchedulerAndActions(void);
/**
* 暂停所有时间表选择和 action
* 这个方法在 onExit 内部调用
*/
void pauseSchedulerAndActions(void);
/*
*如果就 node 调用了 "scheduleUpdate" 那么每一帧 update 方法都会被调用，这个节点一直存在于后台
*/
virtual void update(float delta);
/// @} end of Scheduler and Timer
转换名
/// @{
/// @name Transformations
/**
* 执行基于 OpenGL的视图矩阵变换，例如位置，缩放，旋转和其他属性
*/
void transform();
/**
* 他的父类执行OpenGL的视图矩阵变换。
* 通常父类首先转换, 但是在某些情况下例外 (eg: 附加一个 FBO)
* 如果必要再次转换父类的视图矩阵.
*/
void transformAncestors();
/**
* 递归调用 children's 的 updateTransform()
*
* 这个方法是从 Sprite 里面移来的, 所以它不再是 Sprite 特有的了.
* As the result, 你可以使用 SpriteBatchNode's 来优化你的自定义 node
* e.g., batchNode->addChild(myCustomNode), 当你只能 addChild(sprite) 之前.
*/
virtual void updateTransform();
/**
* Returns 这个矩阵转换在其父接点里面的空间坐标
* 该矩阵以像素为单位。
*/
virtual AffineTransform getNodeToParentTransform() const;
/** @弃用的属性建议使用 getNodeToParentTransform() 代替 */
CC_DEPRECATED_ATTRIBUTE inline virtual AffineTransform nodeToParentTransform() const { return getNodeToParentTransform(); }
/**
* Returns 矩阵在父试图里面的空间坐标转化为节点的空间坐标
* 该矩阵以像素为单位。
*/
virtual AffineTransform getParentToNodeTransform() const;
/** @弃用的属性建议使用 getParentToNodeTransform() 代替 */
CC_DEPRECATED_ATTRIBUTE inline virtual AffineTransform parentToNodeTransform() const { return getParentToNodeTransform(); }
/**
* Returns 现实世界中的 affine（仿射） 变换矩阵. 该矩阵以像素为单位。
*/
virtual AffineTransform getNodeToWorldTransform() const;
/** @弃用的属性建议使用 getNodeToWorldTransform() 代替 */
CC_DEPRECATED_ATTRIBUTE inline virtual AffineTransform nodeToWorldTransform() const { return getNodeToWorldTransform(); }
/**
* Returns 逆现实世界中的 affine（仿射） 变换矩阵. 该矩阵以像素为单位。
*/
virtual AffineTransform getWorldToNodeTransform() const;
/** @弃用的属性建议使用 worldToNodeTransform() 代替 */
CC_DEPRECATED_ATTRIBUTE inline virtual AffineTransform worldToNodeTransform() const { return getWorldToNodeTransform(); }
/// @} end of Transformations
坐标转换
/// @{
/// @name Coordinate Converters //坐标转换
/** Converts a Point to node (local) space coordinates. The result is in Points.
* 把节点里的一个空间坐标点转换为 真实的坐标点（屏幕坐标点，opengl的坐标系）
*/
Point convertToNodeSpace(const Point& worldPoint) const;
/** Converts a Point to world space coordinates. The result is in Points.
* 从当前坐标点获取相对于某个CCNode的坐标点.
*/
Point convertToWorldSpace(const Point& nodePoint) const;
/**
* 把节点里的一个空间坐标点转换为 真实的坐标点（屏幕坐标点，opengl的坐标系）
* Converts a Point to node (local) space coordinates. The result is in Points.
* 作为返回/接收的 node point 是相对于锚点的
*/
Point convertToNodeSpaceAR(const Point& worldPoint) const;
/** 从当前坐标点获取相对于某个CCNode的坐标点.
* Converts a local Point to world space coordinates.The result is in Points.
* 作为返回/接收的 node point 是相对于锚点的
*/
Point convertToWorldSpaceAR(const Point& nodePoint) const;
/**
* 一个简单的把触摸转化为点的方法convenience methods which take a Touch instead of Point
*/
Point convertTouchToNodeSpace(Touch * touch) const;
/** 把触摸点转化为当前坐标点
* 这个方法是相对于锚点
* converts a Touch (world coordinates) into a local coordinate. This method is AR (Anchor Relative).
*/
Point convertTouchToNodeSpaceAR(Touch * touch) const;
/**
* 设置额外的变换.
*
* @note 额外的变换和 getNodeToParentTransform 连接在一起.
* 它可以用来模拟 `parent-child` 关系 (e.g. 一个是 BatchNode 对象, 一个不是).
* @code
// create a batchNode //创建一个批节点
SpriteBatchNode* batch= SpriteBatchNode::create("Icon-114.png");
this->addChild(batch);
// create two sprites, spriteA will be added to batchNode, they are using different textures. //创建两个使用不同 textures 的精灵，将他们添加到批节点
Sprite* spriteA = Sprite::createWithTexture(batch->getTexture());
Sprite* spriteB = Sprite::create("Icon-72.png");
batch->addChild(spriteA);
// We can't make spriteB as spriteA's child since they use different textures. So just add it to layer. //我们不能让精灵 B 作为精灵 A的 child 因为它们使用不同的纹理，所以我门把它添加到 lalyer 上
// 但是我们希望使用这两个 node 模拟 `parent-child` 关系
this->addChild(spriteB);
//position
spriteA->setPosition(Point(200, 200));
// Gets the spriteA's transform. // 获取 spriteA's 转换.
AffineTransform t = spriteA->getNodeToParentTransform();
// Sets the additional transform to spriteB, spriteB's postion will based on its pseudo parent i.e. spriteA. //设置精灵 B 的额外转换，精灵 B 的位置将基于它的伪父类，也就是精灵 A
spriteB->setAdditionalTransform(t);
//scale //比例
spriteA->setScale(2);
// Gets the spriteA's transform. // 获取 spriteA's 转换.
t = spriteA->getNodeToParentTransform();
// Sets the additional transform to spriteB, spriteB's scale will based on its pseudo parent i.e. spriteA. //设置精灵 B 的额外转换，精灵 B 的位置将基于它的伪父类，也就是精灵 A
spriteB->setAdditionalTransform(t);
//rotation //旋转
spriteA->setRotation(20);
// Gets the spriteA's transform.
t = spriteA->getNodeToParentTransform();
// Sets the additional transform to spriteB, spriteB's rotation will based on its pseudo parent i.e. spriteA.
spriteB->setAdditionalTransform(t);
* @endcode
*/
void setAdditionalTransform(const AffineTransform& additionalTransform);
/// @} end of Coordinate Converters
//组件函数名
/// @{
/// @name component functions
/**
* 根据名字获取一个组件
*/
Component* getComponent(const char *pName);
/**
* 添加一个组件
*/
virtual bool addComponent(Component *pComponent);
/**
* 根据名字移除一个组件
*/
virtual bool removeComponent(const char *pName);
/**
* 移除所有组件
*/
virtual void removeAllComponents();
/// @} end of component functions
private:
/// lazy allocs
void childrenAlloc(void);
/// 帮助你重新排序孩子序列
void insertChild(Node* child, int z);
/// 移除 child, 调用 child->onExit(), 做清理, 从 children array 里面删除它.
void detachChild(Node *child, bool doCleanup);
/// 转换cocos2d的坐标到UI窗口坐标。
Point convertToWindowSpace(const Point& nodePoint) const;
protected:
float _rotationX; ///< x-axis 旋转角度
float _rotationY; ///< y-axis 旋转角度
float _scaleX; ///< x-axis 比例系数
float _scaleY; ///< y-axis 比例系数
float _vertexZ; ///< OpenGL 真实的 Z 顶点
Point _position; ///< 节点位置
float _skewX; ///< x-axis 倾斜角
float _skewY; ///< y-axis 倾斜角
Point _anchorPointInPoints; ///< 锚点所在的点
Point _anchorPoint; ///< 统一化的锚点 (NOT in points)
Size _contentSize; ///< 节点未转化时的大小
// "cache" variables are allowed to be mutable //变量是可变的
mutable AffineTransform _additionalTransform; ///< 变换
mutable AffineTransform _transform; ///< 变换
mutable AffineTransform _inverse; ///< 逆转换
mutable bool _additionalTransformDirty; ///< 检查是否正在转换结束的标记
mutable bool _transformDirty; ///< 是否正在准缓的标记
mutable bool _inverseDirty; ///< inverse transform dirty flag
Camera *_camera; ///< 一个视角
GridBase *_grid; ///< 一个网格
int _ZOrder; ///< 影响绘制顺序的 z-order
Array *_children; ///< children 组成的节点数组
Node *_parent; ///< 弱引用父节点
int _tag; ///< 一个 tag. 你可以随意设置一个数字来标记一个接待呐
void *_userData; ///< 一个用户分配的空指针, 可以指向任意对象
Object *_userObject; ///< 一个用户分配的对象
GLProgram *_shaderProgram; ///< OpenGL 着色器
int _orderOfArrival; ///< 用于保存具有相同 z 顺序的 children 序列的到达顺序
Scheduler *_scheduler; ///< 调用计时器更新的时间表
ActionManager *_actionManager; ///< 指向 ActionManager 的单例指针,用来管理所有动作
bool _running; ///< 是否正在运行
bool _visible; ///< 节点是否可见
bool _ignoreAnchorPointForPosition; ///< true 如果你希望锚点的位置是 (0,0) , false 其它情况.
///< Used by Layer and Scene.
bool _reorderChildDirty; ///< 是否正在重新排序 children的标记
bool _isTransitionFinished; ///< 是否转换结束的标记
int _scriptHandler; ///< 处理脚本的 onEnter() & onExit(), 在 lua 或者 javascript 绑定了这个脚本.
int _updateScriptHandler; ///< 每帧处理 update() 回调的脚本, 在 lua & javascript 里面调用.
ccScriptType _scriptType; ///< 在 lua 或者 javascript 绑定了这个脚本类型,
ComponentContainer *_componentContainer; ///< Dictionary 组件
};
//#pragma mark - NodeRGBA // 里程碑
/** NodeRGBA 是一个子节点，实现了 RGBAProtocol 协议.
节点的所有功能都有效，加上以下新的特点：:
- opacity //不透明度
- RGB colors
如果 cascadeOpacity/cascadeColor 启用，那么 Opacity/Color 在 children 里面传播符合 RGBAProtocol .
@从 v2.1 开始
*/
class CC_DLL NodeRGBA : public Node, public RGBAProtocol
{
public:
NodeRGBA();
virtual ~NodeRGBA();
virtual bool init();
// 覆盖
virtual GLubyte getOpacity() const override;
virtual GLubyte getDisplayedOpacity() const override;
virtual void setOpacity(GLubyte opacity) override;
virtual void updateDisplayedOpacity(GLubyte parentOpacity) override;
virtual bool isCascadeOpacityEnabled() const override;
virtual void setCascadeOpacityEnabled(bool cascadeOpacityEnabled) override;
virtual const Color3B& getColor(void) const override;
virtual const Color3B& getDisplayedColor() const override;
virtual void setColor(const Color3B& color) override;
virtual void updateDisplayedColor(const Color3B& parentColor) override;
virtual bool isCascadeColorEnabled() const override;
virtual void setCascadeColorEnabled(bool cascadeColorEnabled) override;
virtual void setOpacityModifyRGB(bool bValue) override {CC_UNUSED_PARAM(bValue);};
virtual bool isOpacityModifyRGB() const override { return false; };
protected:
GLubyte _displayedOpacity;
GLubyte _realOpacity;
Color3B _displayedColor;
Color3B _realColor;
bool _cascadeColorEnabled;
bool _cascadeOpacityEnabled;
};
// end of base_node group
/// @}
NS_CC_END
#endif // __PLATFORM_CCNODE_H__