cocos2d-x节点（CCTextureCache.h)API

cocos2d-x节点（CCTextureCache.h)API

///cocos2d-x-3.0alpha0/cocos2dx/textures
//在 cache 里面存取 texture

#ifndef __CCTEXTURE_CACHE_H__
#define __CCTEXTURE_CACHE_H__

#include <string>
#include <mutex>
#include <thread>
#include <condition_variable>
#include <queue>
#include <string>
#include <unordered_map>

#include "cocoa/CCObject.h"
#include "textures/CCTexture2D.h"
#include "platform/CCImage.h"

#if CC_ENABLE_CACHE_TEXTURE_DATA
#include "platform/CCImage.h"
#include <list>
#endif

NS_CC_BEGIN

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

/** @brief Singleton that handles the loading of textures
* 一旦 texture 加载完成, 下个时间它就会被返回
* 会参考上一次加载的 texture 以减少 GPU & CPU 内存
*/
class CC_DLL TextureCache : public Object
{
public:
/** Returns the shared instance of the cache */
static TextureCache * getInstance();

/** @过时不再需要建议使用新的 API ，可以使用 getInstance() 代替 */
CC_DEPRECATED_ATTRIBUTE static TextureCache * sharedTextureCache() { return TextureCache::getInstance(); }

/** 清除缓存。释放retained（留存）实例
@since v0.99.0
*/
static void destroyInstance();

/** @过时不再需要建议使用新的 API ，可以使用 destroyInstance() 代替 */
CC_DEPRECATED_ATTRIBUTE static void purgeSharedTextureCache() { return TextureCache::destroyInstance(); }

/** Reload all textures
只有 CC_ENABLE_CACHE_TEXTURE_DATA 的值是 1 时，它才有效
*/
static void reloadAllTextures();

public:
/**
* @js ctor
*/
TextureCache();
/**
* @js NA
* @lua NA
*/
virtual ~TextureCache();
/**
* @js NA
* @lua NA
*/
const char* description(void) const;

//    Dictionary* snapshotTextures();

/** Returns 给定文件名对应的 Texture2D
*如果文件名以前没有被加载时，它会创建一个新的Texture2D 对象，它会返回它。它将使用文件名作为 key
* 否则，它会返回一个引用先前加载的图像
* Supported image extensions(扩展): .png, .bmp, .tiff, .jpeg, .pvr, .gif
*/
Texture2D* addImage(const std::string &filepath);

/* Returns a Texture2D object given a file image
* 如果以前没有加载的文件图像，它会创建一个新的Texture2D对象，并返回
* 否则，它会在一个新的线程加载，载入图像时，会吧 Texture2D 作为参数调用回调函数
*回调函数会从主线程上调用所以它可以安全的在回调函数内创建一个 cocos2d 对象
* Supported image extensions: .png, .jpg
* @since v0.8
*/
virtual void addImageAsync(const std::string &filepath, Object *target, SEL_CallFuncO selector);

/** Returns a Texture2D object given an Image.
*  如果以前没有加载的文件图像，它会创建一个新的Texture2D对象，并返回
* 否则，它会返回先前加载的图像引用
* 参数的“key”将被用作缓存的“key”
* If "key" is nil, 每次都会创建一个新的 texture
*/
Texture2D* addImage(Image *image, const std::string &key);
CC_DEPRECATED_ATTRIBUTE Texture2D* addUIImage(Image *image, const char *key) { return addImage(image,key); }

/** Returns an already created texture. Returns nil if the texture doesn't exist.
@since v0.99.5
*/
Texture2D* getTextureForKey(const std::string& key) const;
CC_DEPRECATED_ATTRIBUTE Texture2D* textureForKey(const char* key) const { return getTextureForKey(key); }

/** 清楚加载的 textures 字典.
* 如果你收到了 "Memory Warning" 可以调用这个方法.
* 在短期内: 它还将释放一些资源，防止您的应用程序被杀害。
* 中期: 它将分配更多的资源
* 从长远来看：它会是相同的
*/
void removeAllTextures();

/** Removes unused textures
*  retain count (保留计数)为 为 1 的 Textures 会删除
*  调用此方法后可以很方便的开始一个新的 Scene.
* @since v0.8
*/
void removeUnusedTextures();

/** 从 cache 里面删除 给定的 texture
*/
void removeTexture(Texture2D* texture);

/** 从 cache 里面删除 给定的 key 对应的texture
@since v0.99.4
*/
void removeTextureForKey(const std::string &key);

/** 使用 CCLOG 输出TextureCache的当前内容
* 这个方法会尝试计算每一个texture 的尺寸, texture总共使用了多少内存
*
* @since v1.0
*/
void dumpCachedTextureInfo() const;

private:
void addImageAsyncCallBack(float dt);
void loadImage();

public:
struct AsyncStruct
{
public:
AsyncStruct(const std::string& fn, Object *t, SEL_CallFuncO s) : filename(fn), target(t), selector(s) {}

std::string filename;
Object *target;
SEL_CallFuncO selector;
};

protected:
typedef struct _ImageInfo
{
AsyncStruct *asyncStruct;
Image        *image;
} ImageInfo;

std::thread* _loadingThread;

std::queue<AsyncStruct*>* _asyncStructQueue;
std::queue<ImageInfo*>* _imageInfoQueue;

std::mutex _asyncStructQueueMutex;
std::mutex _imageInfoMutex;

std::mutex _sleepMutex;
std::condition_variable _sleepCondition;

bool _needQuit;

int _asyncRefCount;

std::unordered_map<std::string, Texture2D*> _textures;

static TextureCache *_sharedTextureCache;
};

#if CC_ENABLE_CACHE_TEXTURE_DATA

class VolatileTexture
{
typedef enum {
kInvalid = 0,
kImageFile,
kImageData,
kString,
kImage,
}ccCachedImageType;

public:
VolatileTexture(Texture2D *t);
/**
* @js NA
* @lua NA
*/
~VolatileTexture();

static void addImageTexture(Texture2D *tt, const char* imageFileName);
static void addStringTexture(Texture2D *tt, const char* text, const FontDefinition& fontDefinition);
static void addDataTexture(Texture2D *tt, void* data, int dataLen, Texture2D::PixelFormat pixelFormat, const Size& contentSize);
static void addImage(Texture2D *tt, Image *image);

static void setTexParameters(Texture2D *t, const Texture2D::TexParams &texParams);
static void removeTexture(Texture2D *t);
static void reloadAllTextures();

public:
static std::list<VolatileTexture*> _textures;
static bool _isReloading;

private:
// 使用 Texture2D* 寻找 VolatileTexture
// if not found, create a new one
static VolatileTexture* findVolotileTexture(Texture2D *tt);

protected:
Texture2D *_texture;

Image *_uiImage;

ccCachedImageType _cashedImageType;

void *_textureData;
int  _dataLen;
Size _textureSize;
Texture2D::PixelFormat _pixelFormat;

std::string _fileName;

Texture2D::TexParams      _texParams;
std::string               _text;
FontDefinition            _fontDefinition;
};

#endif

// end of textures group
/// @}

NS_CC_END

#endif //__CCTEXTURE_CACHE_H__