本文来自http://blog.csdn.net/runaying ,引用必须注明出处!
cocos2d-X 节点(SpriteBatchNode.h.)API
///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__