cocos2D-x 3.5 引擎解析之--节点（Node）

#ifndef __CCNODE_H__

#define __CCNODE_H__

 

#include "base/ccMacros.h"

#include "base/CCVector.h"

#include "base/CCProtocols.h"

#include "base/CCScriptSupport.h"

#include "math/CCAffineTransform.h"

#include "math/CCMath.h"

 

NS_CC_BEGIN

 

class GridBase;

class Touch;

class Action;

class LabelProtocol;

class Scheduler;

class ActionManager;

class Component;

class ComponentContainer;

class EventDispatcher;

class Scene;

class Renderer;

class Director;

class GLProgram;

class GLProgramState;

#if CC_USE_PHYSICS

class PhysicsBody;

#endif

 

/**

 * @addtogroup _2d

 * @{

 */

 

enum {

    kNodeOnEnter,

    kNodeOnExit,

    kNodeOnEnterTransitionDidFinish,

    kNodeOnExitTransitionDidStart,

    kNodeOnCleanup

};

 

bool CC_DLL nodeComparisonLess(Node* n1, Node* n2);

 

class EventListener;

 

 

一个简单节点是一个场景图的基本元素，一个场景的元素必须为一个节点对象或者节点的子类的对象。常见的节点对象有：场景，图层，精灵，菜单，标签。

一个节点的主要特征有：

    -可以包含其他节点对象（使用addChild,getChildByTag,removeChild来操作）

    -可以使用计时器来使用回调函数（schedule，unschedule）

    -可以执行动作（runAction,stopAction）

节点的子类意味着：

    重载inti函数来初始化资源和载入何时调用回调函数

    创建回调函数来处理事件

    重载draw来渲染节点

节点的特性：

    位置（默认（0，0）），

    缩放（默认x=0,y=0,也就是在x和y方向没有缩放）

    旋转（角度，旋转方向，默认为0，即没有旋转）

    锚点（默认为（0，0））

    尺寸大小（宽和高）

    是否可见（默认可见）

 局限：

    一个节点是空对象，如果想要在屏幕显示，我们需要使用精灵代替或者设置节点的子类，并重载draw函数。

 

 

class CC_DLL Node : public Ref//公有继承Ref,即每个Node对象都能被引用计数

{

public:  

    static const int INVALID_TAG = -1;

    enum {

        FLAGS_TRANSFORM_DIRTY = (1 << 0),

        FLAGS_CONTENT_SIZE_DIRTY = (1 << 1),

        FLAGS_RENDER_AS_3D = (1 << 3),

 

        FLAGS_DIRTY_MASK = (FLAGS_TRANSFORM_DIRTY | FLAGS_CONTENT_SIZE_DIRTY),

    };

 

static Node * create()//静态构造函数

{

    Node * ret = new (std::nothrow) Node();//初始化一个Node

    if (ret && ret->init())//调用init来初始化Node属性，定义中init是虚函数，可以重载

    {

        ret->autorelease();//加入自动释放池

    }

    else

    {

        CC_SAFE_DELETE(ret);

    }

    return ret;

}

    virtual std::string getDescription() const;

    LocalZOrder是用来对其兄弟节点排序的关键，其父节点对所有它的子节点的排序都是基于LocalZOrder.如果两个节点有同样的LocalZOrder,那么先加入孩子队列中的排在后加入的前面。

    当然，场景图可以用这个LocalZOrder来进行三维转换的算法。所有LocalZOrder值小于零的节点位于左子树，同时LocalZOrder大于零的节点位于右子树。

 

 

    virtual void setLocalZOrder(int localZOrder);//设置LocalZOrder

 

    CC_DEPRECATED_ATTRIBUTE virtual void setZOrder(int localZOrder) { setLocalZOrder(localZOrder); }

   

    CC_DEPRECATED_ATTRIBUTE virtual void _setLocalZOrder(int z);

 

    virtual int getLocalZOrder() const { return _localZOrder; }//得到LocalZOrder

    CC_DEPRECATED_ATTRIBUTE virtual int getZOrder() const { return getLocalZOrder(); }

 

    定义那些需要渲染的节点的顺序：全局Z Order越小，越先渲染。如果有两个或两个以上的节点有相同的Global Z Order,这样渲染顺序就不能保证。

    默认情况下，所有的节点的Global Z Order为零，这意味着，默认情况下，场景图层顺序被用来渲染节点。在我们需要把常见图层顺序和渲染顺序不同时，Global Z Order 是很有用的。

    局限：Global Z Order不能应用到有一个激灵节点集作为祖先的那些节点。

 

 

    

 

 

    virtual void setGlobalZOrder(float globalZOrder);//设置全局Z Order

 

    virtual float getGlobalZOrder() const { return _globalZOrder; }//获取全局Z Order

 

    virtual void setScaleX(float scaleX);//设置X方向的缩放因子，注意物理刚体不支持该函数。

    

    virtual float getScaleX() const;//获取X缩放因子

 

 

    virtual void setScaleY(float scaleY);

     

    virtual float getScaleY() const;

 

     virtual void setScaleZ(float scaleZ);

  

    virtual float getScaleZ() const;

 

 

    virtual void setScale(float scale);//设置XYZ都使用同一个缩放因子

 

    virtual float getScale() const;//当缩放因子一样返回

 

    virtual void setScale(float scaleX, float scaleY);//设置XY缩放因子

 

    设置节点相对应其父节点坐标的位置，我们使用Vec2对象来设置。如果我们需要把节点设置在屏幕中心可以使用下面代码：

     Size size =Director::getInstance()->getWinSize();

     node->setPosition(size.width/2,size.height/2);

 

    virtual void setPosition(const Vec2 &position);//设置节点位置，position是一个OpenGl坐标。

 

    设置位置（x,y）使用0-1之间的值。Pos（其值在0-1之间）在像素可以用下面代码计算：

     void setNormalizedPosition(Vec2 pos) {

       Size s =getParent()->getContentSize();

       _position = pos * s;

     }

     virtual void setNormalizedPosition(const Vec2 &position);//设置归一化位置

 

    

    virtual const Vec2& getPosition() const;//获取节点在其父节点坐标中的位置

 

    virtual const Vec2& getNormalizedPosition() const;

 

 

    virtual void setPosition(float x, float y);//设置节点相对于其父节点坐标的位置，使用这个函数比使用virtual void setPosition(const Vec2 &position)更高效，因为后者需要使用构造函数来构造一个Vec2对象。

    

    virtual void getPosition(float* x, float* y) const;//同上，返回值到x和y，相对返回Vec2更高效。

     

    virtual void  setPositionX(float x);//设置X坐标（相对于其父节点坐标）

    

    virtual float getPositionX(void) const;//得到X坐标（相对于其父节点坐标）

 

    virtual void  setPositionY(float y);

   

    virtual float getPositionY(void) const;

 

    virtual void setPosition3D(const Vec3& position);//设置三维坐标（相对于其父节点坐标）

     

    virtual Vec3 getPosition3D() const;//返回三维坐标（相对于其父节点坐标）

 

 

    virtual void setPositionZ(float positionZ);//设置OpenGL Z值。OpenGL 深度缓冲和深度测试默认是关闭的，我们需要把他们打开才能正确的使用这个特性。

    CC_DEPRECATED_ATTRIBUTE virtual void setVertexZ(float vertexZ) { setPositionZ(vertexZ); }

 

   

    virtual float getPositionZ() const;

    CC_DEPRECATED_ATTRIBUTE virtual float getVertexZ() const { return getPositionZ(); }

 

改变X方向角度（度）。这个函数不同setRotationalSkew() 和setSkew()，第一个用来仿真Flash倾斜功能，第二个用来仿真实际倾斜函数的。物体刚体不支持。

 

    virtual void setSkewX(float skewX);//设置相对应X反向的倾斜角skewX，默认为零，单位为度。

 

    virtual float getSkewX() const;

  

  

    virtual void setSkewY(float skewY);

   

    virtual float getSkewY() const;

 

锚点是所有转换和位置换算的基础。锚点就像是一个相对应父节点用针把子节点别上去，此时针的位置就是该子节点的锚点。锚点是归一化的，（0，0）意味着左下角，（1，1）意味着右上角。默认锚点是（0.5，0.5）,也就是节点中心。如果节点是物理刚体，其锚点只能是节点中心，不能修改。

   

    virtual void setAnchorPoint(const Vec2& anchorPoint);//设置锚点

 

    virtual const Vec2& getAnchorPoint() const;//返回矛盾

 

    virtual const Vec2& getAnchorPointInPoints() const;//返回相对应像素的锚点位置

 

 

 ContentSize 描述一个节点的实际大小，不管节点是否缩放旋转，其大小保持不变，所有结点都有一个size.场景和层都有屏幕大小的ContentSize.

    virtual void setContentSize(const Size& contentSize);//设置ContentSize

 

    virtual const Size& getContentSize() const;//返回ContentSize

 

    virtual void setVisible(bool visible);//设置是否可见

 

    virtual bool isVisible() const;//判断是否可见

 

 

  

    virtual void setRotation(float rotation);//设置旋转角度，正值为顺时针方向，负值为逆时针方向。

   

    virtual float getRotation() const;//返回旋转角度

 

  

    virtual void setRotation3D(const Vec3& rotation);//设置三维选择角度，物理刚体不支持

 

    virtual Vec3 getRotation3D() const;

   

  

    virtual void setRotationQuat(const Quaternion& quat);//设置四元旋转量

rotationusing quaternion, if _rotationZ_X == _rotationZ_Y, _rotationQuat = RotationZ_X* RotationY * RotationX, else _rotationQuat = RotationY * RotationX

 

 

    virtual Quaternion getRotationQuat() const;//返回四元旋转量

 

  

    virtual void setRotationSkewX(float rotationX);

    CC_DEPRECATED_ATTRIBUTE virtual void setRotationX(float rotationX) { return setRotationSkewX(rotationX); }

 

   

    virtual float getRotationSkewX() const;

    CC_DEPRECATED_ATTRIBUTE virtual float getRotationX() const { return getRotationSkewX(); }

 

    

    virtual void setRotationSkewY(float rotationY);

    CC_DEPRECATED_ATTRIBUTE virtual void setRotationY(float rotationY) { return setRotationSkewY(rotationY); }

 

     

    virtual float getRotationSkewY() const;

    CC_DEPRECATED_ATTRIBUTE virtual float getRotationY() const { return getRotationSkewY(); }

 

 

    void setOrderOfArrival(int orderOfArrival);//设置到达顺序，使用addChild依次加入节点，越早加入的达到顺序值越小，就会越先被绘制。如果两个孩子有同样的ZOrder，使用达到顺序值可以判断谁先被绘制。

  

    int getOrderOfArrival() const;//返回节点的到达顺序，可以用来判断哪个节点先加入到其父节点中。

 

  

    virtual void ignoreAnchorPointForPosition(bool ignore);//当把当前节点设置位置时，设置其节点是否为（0，0）。仅层和场景可以使用。函数传入参数默认为false。

 

    virtual bool isIgnoreAnchorPointForPosition() const;

 

    virtual void addChild(Node * child);//child加入节点树中，其默认ZOrder值为0.如果这个孩子加入的是一个正在运行的节点，onEnter函数和onEnterTransitionDidFinish函数将会被调用。

 

    virtual void addChild(Node * child, int localZOrder);设置加入LocalZOrder

    

    virtual void addChild(Node* child, int localZOrder, const std::string &name);

   

     virtual Node * getChildByTag(int tag) const;//使用查询tag来返回子节点

 

    virtual Node* getChildByName(const std::string& name) const; //使用查询name来返回子节点

 

    template <typename T>

    inline T getChildByName(const std::string& name) const { return static_cast<T>(getChildByName(name)); }

 

    virtual void enumerateChildren(const std::string &name, std::function<bool(Node* node)> callback) const;

   

    virtual Vector<Node*>& getChildren() { return _children; }//返回当前节点的孩子队列

    virtual const Vector<Node*>& getChildren() const { return _children; }

   

  

    virtual ssize_t getChildrenCount() const;//返回当前节点的孩子数量

 

 

    virtual void setParent(Node* parent);设置当前节点的父节点

 

    virtual Node* getParent() { return _parent; }//返回父节点

    virtual const Node* getParent() const { return _parent; }

 

 

 

    virtual void removeFromParent();//把当前节点从其父节点移除，并清除

 

    virtual void removeFromParentAndCleanup(bool cleanup);//移除，并判断是否清楚。如果这个节点的所有动作和回调函数都可以移除，就设置为true

 

 

 

    virtual void removeChild(Node* child, bool cleanup = true);//移除子节点

 

    

     virtual void removeChildByTag(int tag, bool cleanup = true);//使用tag来移除子节点

 

     

    virtual void removeChildByName(const std::string &name, bool cleanup = true);

   

    virtual void removeAllChildren();//移除所有子节点

 

    virtual void removeAllChildrenWithCleanup(bool cleanup);//移除所有孩子并清除

 

 

    virtual void reorderChild(Node * child, int localZOrder);//根据child的localZOrder重新排序.

 

 

    virtual void sortAllChildren();//在绘制之前对所有孩子排序

                                         

 

     virtual int getTag() const;//返回节点的tag

 

     virtual void setTag(int tag);//设置tag

   

 

    virtual std::string getName() const;

  

    virtual void setName(const std::string& name);

 

   

    virtual void* getUserData() { return _userData; }//返回用户数据指针，可以是任何类型

  

    virtual const void* getUserData() const { return _userData; }

 

  

    virtual void setUserData(void *userData);//设置用户数据（指针），记得手动是否内存

 

    virtual Ref* getUserObject() { return _userObject; }//返回用户分配的对象（Ref*）

   

    virtual const Ref* getUserObject() const { return _userObject; }

 

 

    virtual void setUserObject(Ref *userObject);//类似于用户数据，只是这个可以自动释放