cocos2d-x节点（CCTextureAtlas.h)API

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

cocos2d-x节点（CCTextureAtlas.h)API

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

一个类实现了Texture Atlas. 对 Quads 进行操作

///cocos2d-x-3.0alpha0/cocos2dx/textures
//一个类实现了Texture Atlas. 对 Quads 进行操作


#ifndef __CCTEXTURE_ATLAS_H__
#define __CCTEXTURE_ATLAS_H__

#include "ccTypes.h"
#include "cocoa/CCObject.h"
#include "ccConfig.h"
#include <string>

NS_CC_BEGIN

class Texture2D;

/**
 * @addtogroup textures
 * @{
 */

/** @brief A class that implements a Texture Atlas.
支持的功能:
* The atlas file can be a PVRTC, PNG or any other format supported by Texture2D
* Quads can be updated in runtime
* Quads can be added in runtime
* Quads can be removed in runtime
* Quads can be re-ordered in runtime
* 运行时可以增加 TextureAtlas 的容量
* OpenGL component: V3F, C4B, T2F.
 quads 使用 OpenGL ES VBO 呈现.
交错的顶点数组列表渲染 quads，您应该修改ccConfig.h的文件
*/
class CC_DLL TextureAtlas : public Object 
{
public:
    /** creates a TextureAtlas with an filename and with an initial capacity for Quads.
     * 运行时可以增加 TextureAtlas 的容量
     */
    static TextureAtlas* create(const char* file , int capacity);

    /** 在 TextureAtlas 对象创建之前，初始化 Texture2D 对象和制定容量的 Quads
     * 运行时可以增加 TextureAtlas 的容量
     */
    static TextureAtlas* createWithTexture(Texture2D *texture, int capacity);
    /**
     * @js ctor
     */
    TextureAtlas();
    /**
     * @js NA
     * @lua NA
     */
    virtual ~TextureAtlas();

    /** initializes a TextureAtlas with a filename and with a certain capacity for Quads.
    * 运行时可以增加 TextureAtlas 的容量
    *
    * WARNING: 不重新初始化 TextureAtlas 因为它会导致内存泄漏(issue #706)
    */
    bool initWithFile(const char* file, int capacity);

    /** 在 TextureAtlas 对象初始化之前，初始化 Texture2D 对象和制定容量的 Quads
    * 运行时可以增加 TextureAtlas 的容量
    *
    * WARNING: 不重新初始化 TextureAtlas 因为它会导致内存泄漏(issue #706)
    */
    bool initWithTexture(Texture2D *texture, int capacity);

    /** updates a Quad (texture, vertex and color) at a certain index
    * index 必须在 0 和 atlas 容量 - 1 之间
    @since v0.8
    */
    void updateQuad(V3F_C4B_T2F_Quad* quad, int index);

    /** Inserts a Quad (texture, vertex and color) at a certain index
    index 必须在 0 和 atlas 容量 - 1 之间
    @since v0.8
    */
    void insertQuad(V3F_C4B_T2F_Quad* quad, int index);

    /** Inserts a c array of quads at a given index
     index 必须在 0 和 atlas 容量 - 1 之间
     当 amount + index > totalQuads 时，这种方法不会放大 array 容量
     @since v1.1
    */
    void insertQuads(V3F_C4B_T2F_Quad* quads, int index, int amount);

    /** Removes the quad that is located at a certain index and inserts it at a new index
    此操作的速度比 removing 、 inserting 一个 quad 两个不同的步骤要快
    @since v0.7.2
    */
    void insertQuadFromIndex(int fromIndex, int newIndex);

    /** removes a quad at a given index number.
    容量保持不变，但要绘制的 quads 减少1
    @since v0.7.2
    */
    void removeQuadAtIndex(int index);

    /** 从 index 开始移除 amount 个 quads
        @since 1.1
     */
    void removeQuadsAtIndex(int index, int amount);
    /** removes all Quads.
     TextureAtlas 容量保持不变。没有内存被释放
     要绘制的 quads 总数将是0
    @since v0.7.2
    */
    void removeAllQuads();

    /** 调整 TextureAtlas 的容量.
    * 新的容量可以 高于/低于 当前容量
    *  returns true 如果调整容量成功.
    * fails 无法调整容量，新的容量是 0.
    */
    bool resizeCapacity(int capacity);

    /**
     ParticleBatchNode 内部使用
   不要使用这个，除非你知道你在做什么
     @since 1.1
    */
    void increaseTotalQuadsWith(int amount);

    /** 从 oldIndex 移动 amount 个 quads 到 newIndex
     @since v1.1
     */
    void moveQuadsFromIndex(int oldIndex, int amount, int newIndex);

    /**
     把 quads 从 index 移动到 newIndex
     ParticleBatchNode 内部使用
   这个方法不增加 array if newIndex + quads to be moved > capacity
     @since 1.1
    */
    void moveQuadsFromIndex(int index, int newIndex);

    /**
     确保 quads realloc 后保持 empty
     ParticleBatchNode 内部使用
     @since 1.1
    */
    void fillWithEmptyQuadsFromIndex(int index, int amount);

    /** draws n quads
    * n 不能大于 the atlas 的容量 
    */
    void drawNumberOfQuads(int n);

    /** 从 index (offset) 开始绘制 quad.
    n + start 不能大于 the atlas 的容量

    @since v1.0
    */
    void drawNumberOfQuads(int numberOfQuads, int start);

    /**绘制所有 Atlas's Quads
    */
    void drawQuads();
    /** 在 android 平台上监听 进入 foreground 事件
     */
    void listenBackToForeground(Object *obj);

    /** VBO数组缓冲区是否需要更新*/
    inline bool isDirty(void) { return _dirty; }
    /** 如果指定的VBO数组缓冲区需要更新 */
    inline void setDirty(bool bDirty) { _dirty = bDirty; }
    /**
     * @js NA
     * @lua NA
     */
    const char* description() const;

    /** Gets 将要绘制的四边形 */
    int getTotalQuads() const;
    
    /** Gets 当前的  texture atlas 可以存储的四边形数量 */
    int getCapacity() const;
    
    /** Gets texture atlas 的 texture  */
    Texture2D* getTexture() const;
    
    /** Sets exture atlas 的 texture */
    void setTexture(Texture2D* texture);
    
    /** Gets 将要呈现的四边形 */
    V3F_C4B_T2F_Quad* getQuads();
    
    /** Sets 将要呈现的四边形 */
    void setQuads(V3F_C4B_T2F_Quad* quads);
    
private:
    void setupIndices();
    void mapBuffers();
#if CC_TEXTURE_ATLAS_USE_VAO
    void setupVBOandVAO();
#else
    void setupVBO();
#endif

protected:
    GLushort*           _indices;
#if CC_TEXTURE_ATLAS_USE_VAO
    GLuint              _VAOname;
#endif
    GLuint              _buffersVBO[2]; //0: vertex  1: indices
    bool                _dirty; //标记 VBO 数组缓冲区是否需要更新
    /** 将要绘制的四边形 */
    int _totalQuads;
    /** 当前的  texture atlas 可以存储的四边形数量 */
    int _capacity;
    /** texture atlas 的 texture */
    Texture2D* _texture;
    /** 将要呈现的四边形*/
    V3F_C4B_T2F_Quad* _quads;
};

// end of textures group
/// @}

NS_CC_END

#endif //__CCTEXTURE_ATLAS_H__