本文来自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__