cocos2d-X 节点（CCTexture2D.h）API

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

cocos2d-X 节点（CCTexture2D.h）API

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

贴图类 CCTexture2D是关于
OpenGL
的概念。在
OpenGL中称图片为贴图,在Cocos2D-x中
CCTexture2D
就是图片对象的意思,可以通过它创建精灵等对象 .CCTexture2D类是精灵类和其相关类的基础。以下会看到很多类都可以用CCTexture2D类定义。

//cocos2d-x-3.0alpha0-pre/cocos2dx/textures

#ifndef __CCTEXTURE2D_H__
#define __CCTEXTURE2D_H__

#include <string>
#include <map>

#include "cocoa/CCObject.h"
#include "cocoa/CCGeometry.h"
#include "ccTypes.h"
#ifdef EMSCRIPTEN
#include "base_nodes/CCGLBufferedNode.h"
#endif // EMSCRIPTEN

NS_CC_BEGIN

class Image;
typedef struct _MipmapInfo MipmapInfo;

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

//CONSTANTS:

class GLProgram;

//CLASS INTERFACES:

简要

/** @brief Texture2D class.
* 这个类可以方便的从一个  images, text or raw data. 创建OpenGL的2D textures       // 图像，文本或原始数据
*创建Texture2D对象将永远有  power-of-two dimensions             //两个维度。
*实际的图像的 texture 可能小于 texture 的尺寸;这取决于你是如何创建 tEXURE2D对象的 i.e. "contentSize" != (pixelsWide, pixelsHigh) and (maxS, maxT) != (1.0, 1.0).
* 请注意，所生成的纹理的内容将上下颠倒！
*/
class CC_DLL Texture2D : public Object
#ifdef EMSCRIPTEN
, public GLBufferedNode
#endif // EMSCRIPTEN
{
public:
/** @typedef Texture2D::PixelFormat
texture 可能会被像素格式化
*/
enum class PixelFormat
{
//! 自动检测类型
AUTO,
//! 32-bit texture: BGRA8888    //32位纹理：BGRA8888
BGRA8888,
//! 32-bit texture: RGBA8888
RGBA8888,
//! 24-bit texture: RGBA888
RGB888,
//! 不带Alpha通道的16位纹理
RGB565,
//! 8-bit textures 作为 masks     //模形
A8,
//! 8-bit 强度的 texture
I8,
//! 16-bit textures  作为 masks     //模形
AI88,
//! 16-bit textures: RGBA4444
RGBA4444,
//! 16-bit textures: RGB5A1
RGB5A1,
//! 4-bit PVRTC-compressed texture: PVRTC4A                        // 压缩
PVRTC4,
//! 4-bit PVRTC-compressed texture: PVRTC4 (有 alpha 通道)
PVRTC4A,
//! 2-bit PVRTC-compressed texture: PVRTC2
PVRTC2,
//! 2-bit PVRTC-compressed texture: PVRTC2 (有 alpha 通道)
PVRTC2A,
//! ETC-compressed texture: ETC                       // 压缩
ETC,
//! S3TC-compressed texture: S3TC_Dxt1
S3TC_DXT1,
//! S3TC-compressed texture: S3TC_Dxt3
S3TC_DXT3,
//! S3TC-compressed texture: S3TC_Dxt5
S3TC_DXT5,
//! ATITC-compressed texture: ATC_RGB
ATC_RGB,
//! ATITC-compressed texture: ATC_EXPLICIT_ALPHA
ATC_EXPLICIT_ALPHA,
//! ATITC-compresed texture: ATC_INTERPOLATED_ALPHA
ATC_INTERPOLATED_ALPHA,
//! 默认的 texture 格式: AUTO
DEFAULT = AUTO,

NONE = -1
};

struct PixelFormatInfo {

PixelFormatInfo(GLenum internalFormat, GLenum format, GLenum type, int bpp, bool compressed, bool alpha)
: internalFormat(internalFormat)
, format(format)
, type(type)
, bpp(bpp)
, compressed(compressed)
, alpha(alpha)
{}

GLenum internalFormat;
GLenum format;
GLenum type;
int bpp;
bool compressed;
bool alpha;
};

typedef std::map<Texture2D::PixelFormat, const PixelFormatInfo> PixelFormatInfoMap;

/**
set Min / Mag 扩展的过滤器
*/
typedef struct _TexParams {
GLuint    minFilter;
GLuint    magFilter;
GLuint    wrapS;
GLuint    wrapT;
}TexParams;

public:
/** 为 UIImagescontains alpha 通道设置默认的像素的格式.
该UIImage如果包含Alpha通道，然后有三种选择:
- generate 32-bit textures: Texture2D::PixelFormat::RGBA8888 (default one)     //默认的一种
- generate 24-bit textures: Texture2D::PixelFormat::RGB888                     //生成
- generate 16-bit textures: Texture2D::PixelFormat::RGBA4444
- generate 16-bit textures: Texture2D::PixelFormat::RGB5A1
- generate 16-bit textures: Texture2D::PixelFormat::RGB565
- generate 8-bit textures: Texture2D::PixelFormat::A8 (使用它的时候你只能使用一种颜色)

他是如何工作的 ?
-如果图片是 RGBA（使用了 alpha通道）则默认的像素格式将被使用 (它可以是 a 8-bit, 16-bit or 32-bit texture)
-如果图片是 RGB（没有使用 alpha通道） 如果默认的像素格式是 RGBA8888 那么将使用 RGBA8888 (32-bit) ，其他情况将使用一个 RGB565 (16-bit texture)

这个参数对 PVR / PVR.CCZ 图片是无效的.

@since v0.8
*/
static void setDefaultAlphaPixelFormat(Texture2D::PixelFormat format);

/** returns  alpha 通道像素格式
@since v0.8
*/
static Texture2D::PixelFormat getDefaultAlphaPixelFormat();
CC_DEPRECATED_ATTRIBUTE static Texture2D::PixelFormat defaultAlphaPixelFormat() { return Texture2D::getDefaultAlphaPixelFormat(); };

/**对待（或没有） RVR 文件，把他们当作有 alpha premultiplied。          //预乘
你不可能再运行前知道他们有没有 alpha premultiplied。          //预乘
不论他们有没有 alpha premultiplied。  他们都是可以被加载的        //预乘

默认情况下，它被禁用。

@since v0.99.5
*/
static void PVRImagesHavePremultipliedAlpha(bool haveAlphaPremultiplied);

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

/** 这些功能都需要创建可变的 textures
* @js NA
* @lua NA
*/
void releaseData(void *data);
/**
* @js NA
* @lua NA
*/
void* keepData(void *data, unsigned int length);

/** 使用数据，初始化一个Texture2D
* @js NA
* @lua NA
*/
bool initWithData(const void *data, int dataLen, Texture2D::PixelFormat pixelFormat, unsigned int pixelsWide, unsigned int pixelsHigh, const Size& contentSize);

/** 使用 mipmaps 初始化 */
bool initWithMipmaps(MipmapInfo* mipmaps, int mipmapsNum, Texture2D::PixelFormat pixelFormat, unsigned int pixelsWide, unsigned int pixelsHigh);

/**
扩展 Texture2D 对象使它很容易的绘制一个基本矩形
这个功能需要客户端支持 GL_TEXTURE_2D 、 GL_VERTEX_ARRAY 、 GL_TEXTURE_COORD_ARRAY     */
/** 在一个给定的点绘制一个 texture */
void drawAtPoint(const Point& point);
/** 在一个矩形内绘制一个 texture */
void drawInRect(const Rect& rect);

/**
扩展 Texture2D 对象使它很容易使用一个图片初始化
*/
/**
使用一个 UIImage 对象初始化一个 texure.
调用 setDefaultAlphaPixelFormat 使用你制定的格式，转换图片然后在 texture 里面使用转换后的图片
NOTE: 他不会转换 pvr 图片文件.       //关于 pvr（图片的一种格式，像png、jpg一样） 是什么请参考 http://blog.sina.com.cn/s/blog_6fbe210701015j7z.html */
bool initWithImage(Image * image);

/** 使用一个 UIImage 对象初始化一个 texure.
图片使用我们传递过来的格式化参数格式化，然后被 texture 使用
如果你传递的是 PixelFormat::Automatic, 那么图片将自动检测图片的渲染类型，使用该类型来渲染 texture
**/
bool initWithImage(Image * image, PixelFormat format);

/**使用字符串和字符串的 长度、对齐方式、字体、字体尺寸 初始化一个 texture */
bool initWithString(const char *text,  const char *fontName, float fontSize, const Size& dimensions = Size(0, 0), TextHAlignment hAlignment = TextHAlignment::CENTER, TextVAlignment vAlignment = TextVAlignment::TOP);
/** 使用 text 初始化一个 texture */
bool initWithString(const char *text, const FontDefinition& textDefinition);

/** 为 texture 设置过滤器的最小值和磁力
如果 texture 是 NPOT (密度不是 2),那么它只能在 GL_TEXTURE_WRAP_{S,T} 里面使用 GL_CLAMP_TO_EDGE

@warning 调用此方法，可以为 texture 分配额外的内存。

@since v0.8
* @code
* 这个功能函数在 js 或者 lua 里面使用时,输入参数会改变
* In js: var setBlendFunc(var arg1, var arg2, var arg3, var arg4)
* In lua: local setBlendFunc(local arg1, local arg2, local arg3, local arg4)
* @endcode
*/
void setTexParameters(const TexParams& texParams);
/**
* @js NA
* @lua NA
*/
CC_DEPRECATED_ATTRIBUTE void setTexParameters(const TexParams* texParams) { return setTexParameters(*texParams); };

/** sets texture 的反锯齿参数:
- GL_TEXTURE_MIN_FILTER = GL_LINEAR
- GL_TEXTURE_MAG_FILTER = GL_LINEAR

@warning 调用此方法，可以为 texture 分配额外的内存。

@since v0.8
*/
void setAntiAliasTexParameters();

/** 设置 texture 参数别名：
- GL_TEXTURE_MIN_FILTER = GL_NEAREST
- GL_TEXTURE_MAG_FILTER = GL_NEAREST

@warning 调用此方法，可以分配额外的 texture 内存。

@since v0.8
*/
void setAliasTexParameters();

/** 为 texture 产生 mipmap 图片.
It only works if the texture size is POT (power of 2).      //她只在 texture 密度是2 时工作
@since v0.99.0
*/
void generateMipmap();

/** returns 像素格式.
@since v2.0
*/
const char* getStringForFormat() const;
CC_DEPRECATED_ATTRIBUTE const char* stringForFormat() const { return getStringForFormat(); };

/** return OpenGL texture每像素在内存中所占的 bit
@since v1.0
*/
unsigned int getBitsPerPixelForFormat() const;
CC_DEPRECATED_ATTRIBUTE unsigned int bitsPerPixelForFormat() const { return getBitsPerPixelForFormat(); };

/**辅助功能，对于一个给定的格式返回每像素所占bit。
@since v2.0
*/
unsigned int getBitsPerPixelForFormat(Texture2D::PixelFormat format) const;
CC_DEPRECATED_ATTRIBUTE unsigned int bitsPerPixelForFormat(Texture2D::PixelFormat format) const { return getBitsPerPixelForFormat(format); };

/** 内容尺寸 */
const Size& getContentSizeInPixels();

bool hasPremultipliedAlpha() const;
bool hasMipmaps() const;

/** Gets texture 的像素格式 */
Texture2D::PixelFormat getPixelFormat() const;

/**获取 texture 的宽度（以像素为单位）*/
unsigned int getPixelsWide() const;

/** *获取 texture 的高度（以像素为单位） */
unsigned int getPixelsHigh() const;

/** Gets texture 名字 */
GLuint getName() const;

/** Gets max S */
GLfloat getMaxS() const;
/** Sets max S */
void setMaxS(GLfloat maxS);

/** Gets max T */
GLfloat getMaxT() const;
/** Sets max T */
void setMaxT(GLfloat maxT);

Size getContentSize() const;

void setShaderProgram(GLProgram* program);
GLProgram* getShaderProgram() const;

public:
static const PixelFormatInfoMap& getPixelFormatInfoMap();

private:

转换函数

/**convert functions*/      //转换函数

/**
准换格式到你指定的格式参数,如果这个参数是， PixelFormat::Automatic,他会自动检测转换成最接近，你指定的格式参数。他会返回转换后的格式给你 如果 outData != data（输出数据不等于传入的数据）,你必须手动删除
*/
static PixelFormat convertDataToFormat(const unsigned char* data, int dataLen, PixelFormat originFormat, PixelFormat format, unsigned char** outData, int* outDataLen);

static PixelFormat convertI8ToFormat(const unsigned char* data, int dataLen, PixelFormat format, unsigned char** outData, int* outDataLen);
static PixelFormat convertAI88ToFormat(const unsigned char* data, int dataLen, PixelFormat format, unsigned char** outData, int* outDataLen);
static PixelFormat convertRGB888ToFormat(const unsigned char* data, int dataLen, PixelFormat format, unsigned char** outData, int* outDataLen);
static PixelFormat convertRGBA8888ToFormat(const unsigned char* data, int dataLen, PixelFormat format, unsigned char** outData, int* outDataLen);

//I8 to XXX
static void convertI8ToRGB888(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertI8ToRGBA8888(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertI8ToRGB565(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertI8ToRGBA4444(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertI8ToRGB5A1(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertI8ToAI88(const unsigned char* data, int dataLen, unsigned char* outData);

//AI88 to XXX
static void convertAI88ToRGB888(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertAI88ToRGBA8888(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertAI88ToRGB565(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertAI88ToRGBA4444(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertAI88ToRGB5A1(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertAI88ToA8(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertAI88ToI8(const unsigned char* data, int dataLen, unsigned char* outData);

//RGB888 to XXX
static void convertRGB888ToRGBA8888(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertRGB888ToRGB565(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertRGB888ToI8(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertRGB888ToAI88(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertRGB888ToRGBA4444(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertRGB888ToRGB5A1(const unsigned char* data, int dataLen, unsigned char* outData);

//RGBA8888 to XXX
static void convertRGBA8888ToRGB888(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertRGBA8888ToRGB565(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertRGBA8888ToI8(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertRGBA8888ToA8(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertRGBA8888ToAI88(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertRGBA8888ToRGBA4444(const unsigned char* data, int dataLen, unsigned char* outData);
static void convertRGBA8888ToRGB5A1(const unsigned char* data, int dataLen, unsigned char* outData);

protected:
/**  texture 的像素格式 */
Texture2D::PixelFormat _pixelFormat;

/**宽度（像素）s */
unsigned int _pixelsWide;

/**高度（像素） */
unsigned int _pixelsHigh;

/** texture 名 */
GLuint _name;

/** texture max S */
GLfloat _maxS;

/** texture max T */
GLfloat _maxT;

/** content 尺寸 */
Size _contentSize;

/** texture 是否有他们的 Alpha premultiplied */
bool _hasPremultipliedAlpha;

bool _hasMipmaps;

/** 着色器程序在 drawAtPoint and drawInRect 里面使用*/
GLProgram* _shaderProgram;

static const PixelFormatInfoMap _pixelFormatInfoTables;
};

// end of textures group
/// @}

NS_CC_END

#endif //__CCTEXTURE2D_H__