cocos2d-X 节点（SpriteBatchNode.h.）API

本文来自http://blog.csdn.net/runaying ，引用必须注明出处！

cocos2d-X 节点（SpriteBatchNode.h.）API

温馨提醒： 为了大家能更好学习，强烈推荐大家看看本人的这篇博客  Cocos2d-X权威指南笔记

///cocos2d-x-3.0alpha0/cocos2dx/sprite_nodes


#ifndef __CC_SPRITE_BATCH_NODE_H__
#define __CC_SPRITE_BATCH_NODE_H__

#include <vector>

#include "base_nodes/CCNode.h"
#include "CCProtocols.h"
#include "textures/CCTextureAtlas.h"
#include "ccMacros.h"

NS_CC_BEGIN

/**
 * @addtogroup sprite_nodes
 * @{
 */


class Sprite;

/** SpriteBatchNode就像是一个批节点：如果它包含孩子，他会一次性绘制所有孩子
* (通常叫做"批绘制").
*
* SpriteBatchNode可以引用一个且只有一个 texture（纹理）（一个图像文件，一个 texture atlas （纹理图集））。
* 只有 Sprites 所包含的 texture 才会被添加到 the SpriteBatchNode.
* 所有添加到 SpriteBatchNode  的 Sprites 都会一次性绘制
* 如果 Sprites 没有被添加到 SpriteBatchNode 那么它们会一个一个的绘制 ，这样做效率低
*
*
* 限制:
*  - 只接受 Sprite 或者他的子类 eg: particles（颗粒）, labels and layer 不能添加到 SpriteBatchNode.       
*  - 所有 children 的 Aliased/Antialiased 都不能相互混合.因为 "alias" 是 texture（纹理）的一个属性所有的 sprites共享同样的 texture, and all the sprites share the same texture.
* 
* @since v0.7.1
*/
class CC_DLL SpriteBatchNode : public Node, public TextureProtocol
{
    static const int DEFAULT_CAPACITY = 29;

public:
    /** 使用 Texture2D 和 capacity 创建一个 SpriteBatchNode
     如果 capacity 的 runtime 空间不够用，那么 runtime 空间会增加 33%
     */
    static SpriteBatchNode* createWithTexture(Texture2D* tex, int capacity = DEFAULT_CAPACITY);

    /** 使用 fileImage (.png, .jpeg, .pvr, etc) 、capacity 创建一个 SpriteBatchNode 
     如果 capacity 的 runtime 空间不够用，那么 runtime 空间会增加 33%
     该文件将使用 TextureMgr 加载.
     */
    static SpriteBatchNode* create(const char* fileImage, int capacity = DEFAULT_CAPACITY);
    /**
     * @js ctor
     */
    SpriteBatchNode();
    /**
     * @js NA
     * @lua NA
     */
    virtual ~SpriteBatchNode();

    /**使用 texture2d 、 capacity  初始化一个 SpriteBatchNode 
     如果 capacity 的 runtime 空间不够用，那么 runtime 空间会增加 33%
     */
    bool initWithTexture(Texture2D *tex, int capacity);
    /** 使用 fileImage (.png, .jpeg, .pvr, etc) 、capacity 初始化一个 SpriteBatchNode
     如果 capacity 的 runtime 空间不够用，那么 runtime 空间会增加 33%
     该文件将使用 TextureMgr 加载.
     * @js init
     * @lua init
     */
    bool initWithFile(const char* fileImage, int capacity);
    bool init();

    /** returns TextureAtlas 对象 */
    inline TextureAtlas* getTextureAtlas(void) { return _textureAtlas; }

    /** sets  TextureAtlas 对象 */
    inline void setTextureAtlas(TextureAtlas* textureAtlas)
    { 
        if (textureAtlas != _textureAtlas)
        {
            CC_SAFE_RETAIN(textureAtlas);
            CC_SAFE_RELEASE(_textureAtlas);
            _textureAtlas = textureAtlas;
        }
    }

    /** returns 一个 descendants（任何子类） 数组
     这是 BatchNode 特有的.其它情况为了使用 children, 可以使用 getChildren() 代替 */
    inline const std::vector<Sprite*>& getDescendants() const { return _descendants; }

    void increaseAtlasCapacity();

    /** 根据 index 移除一个孩子. 然后根据 doCleanup 参数判断是否需要清理 actions
    @warning 从 SpriteBatchNode 移除一个 children 非常慢
    */
    void removeChildAtIndex(int index, bool doCleanup);

    void appendChild(Sprite* sprite);
    void removeSpriteFromAtlas(Sprite *sprite);

    int rebuildIndexInOrder(Sprite *parent, int index);
    int highestAtlasIndexInChild(Sprite *sprite);
    int lowestAtlasIndexInChild(Sprite *sprite);
    int atlasIndexForChild(Sprite *sprite, int z);
    /* 使用这个方法排序 Sprites，但是不要手动调用这个方法 */
    void reorderBatch(bool reorder);

    //
    // Overrides
    //
    // TextureProtocol
    virtual Texture2D* getTexture(void) const override;
    virtual void setTexture(Texture2D *texture) override;
    /**
    *@code
    *当这个功能在 js or lua 里面使用时,参数会发生改变
    *In js: var setBlendFunc(var src, var dst)
    *@endcode
    * @lua NA 
    */
    virtual void setBlendFunc(const BlendFunc &blendFunc) override;
    /**
    * @js NA
    * @lua NA
    */
    virtual const BlendFunc& getBlendFunc(void) const override;

    virtual void visit(void) override;
    virtual void addChild(Node* child) override{ Node::addChild(child);}
    virtual void addChild(Node * child, int zOrder) override { Node::addChild(child, zOrder);}
    virtual void addChild(Node * child, int zOrder, int tag) override;
    virtual void reorderChild(Node *child, int zOrder) override;
        
    virtual void removeChild(Node *child, bool cleanup) override;
    virtual void removeAllChildrenWithCleanup(bool cleanup) override;
    virtual void sortAllChildren() override;
    virtual void draw(void) override;

protected:
    /** 在索引位置的 texture atlas 插入一个 quad(顶点的坐标位置，纹理的坐标位置和颜色信息). Sprite 不会被加入到孩子们的数组。
     这个方法会在你使用一个很大的 AtlasSrite 时或者大多数 Sprite 都不会更新时调用
     例如: 一块地图 (TMXMap) or 一个标签有很多的字符(LabelBMFont)
     */
    void insertQuadFromSprite(Sprite *sprite, int index);
    /** 在索引位置的 texture atlas 更新一个 quad(顶点的坐标位置，纹理的坐标位置和颜色信息). Sprite 不会被加入到孩子们的数组。
     这个方法会在你使用一个很大的 AtlasSrite 时或者大多数 Sprite 都不会更新时调用
     例如: 一块地图 (TMXMap) or 一个标签有很多的字符(LabelBMFont)
     */
    void updateQuadFromSprite(Sprite *sprite, int index);
    /* 这个方法和 "addQuadFromSprite 相反.
    它添加 sprite children/descendanta（子类） 到批处理数组，但是它不把更新添加到 texture atlas
    */
    SpriteBatchNode * addSpriteWithoutQuad(Sprite *child, int z, int aTag);

    void updateAtlasIndex(Sprite* sprite, int* curIndex);
    void swap(int oldIndex, int newIndex);
    void updateBlendFunc();

    TextureAtlas *_textureAtlas;
    BlendFunc _blendFunc;

    // 所有的子类: children, grand children, etc...
    // 不需要 retain/release 这些对象，因为它们已经在 _children 里面保留了
    // 所以这种情况下使用 std::vector<Sprite*> 略快与使用 cocos2d::Array
    std::vector<Sprite*> _descendants;
};

// end of sprite_nodes group
/// @}

NS_CC_END

#endif // __CC_SPRITE_BATCH_NODE_H__