cocos2d-x节点（CCImage.h)API

cocos2d-x节点（CCImage.h)API

///cocos2d-x-3.0alpha0/cocos2dx/platform
//加载图片，储存图片，例如，从 stream buffer 里面加载图片，从指定路径加载图片，把文本初始化为图片

#ifndef __CC_IMAGE_H__
#define __CC_IMAGE_H__

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

//当我们尝试在 Texture2D 上使用其他像素格式时， premultiply（预乘）alpha 或者效果就会出现错误
#define CC_RGB_PREMULTIPLY_ALPHA(vr, vg, vb, va) \
(unsigned)(((unsigned)((unsigned char)(vr) * ((unsigned char)(va) + 1)) >> 8) | \
((unsigned)((unsigned char)(vg) * ((unsigned char)(va) + 1) >> 8) << 8) | \
((unsigned)((unsigned char)(vb) * ((unsigned char)(va) + 1) >> 8) << 16) | \
((unsigned)(unsigned char)(va) << 24))

NS_CC_BEGIN

/**
* @addtogroup platform
* @{
*/

/**
@brief 我们可以告诉 mipmap 什么时候开始，持续多久的结构
*/
typedef struct _MipmapInfo
{
unsigned char* address;
int len;
}MipmapInfo;

class CC_DLL Image : public Object
{
public:
friend class TextureCache;
/**
* @js ctor
*/
Image();
/**
* @js NA
* @lua NA
*/
virtual ~Image();

/** 支持的图片格式 */
enum class Format
{
//! JPEG
JPG,
//! PNG
PNG,
//! TIFF
TIFF,
//! WebP
WEBP,
//! PVR
PVR,
//! ETC
ETC,
//! S3TC
S3TC,
//! ATITC
ATITC,
//! Raw Data
RAW_DATA,
//! Unknown format
UNKOWN
};

enum class TextAlign
{
CENTER        = 0x33, ///< Horizontal center and vertical center.       //水平居中、垂直居中
TOP           = 0x13, ///< Horizontal center and vertical top.          //水平居中、垂直向上
TOP_RIGHT     = 0x12, ///< Horizontal right and vertical top.           //水平向右、垂直向上
RIGHT         = 0x32, ///< Horizontal right and vertical center.        //水平向右、垂直居中
BOTTOM_RIGHT = 0x22, ///< Horizontal right and vertical bottom.         //水平向右、垂直向下
BOTTOM        = 0x23, ///< Horizontal center and vertical bottom.       //水平向左、垂直向下
BOTTOM_LEFT  = 0x21, ///< Horizontal left and vertical bottom.          //水平向左、垂直向下
LEFT          = 0x31, ///< Horizontal left and vertical center.         //水平向左、垂直居中
TOP_LEFT      = 0x11, ///< Horizontal left and vertical top.            //水平向左、垂直向上
};

/**
@brief 从指定的路径加载图片.
@param path  文件的绝对路径.
@return true 如果正确加载.
*/
bool initWithImageFile(const char *path);

/**
@brief 从 stream buffer 加载图像.
@param data  保存图像数据的 stream buffer.
@param dataLen  data 表示数据的长度 (number of bytes）.
@return true 如果正确加载.
* @js NA
* @lua NA
*/
bool initWithImageData(const unsigned char * data, int dataLen);

// @warning kFmtRawData only support RGBA8888
bool initWithRawData(const unsigned char * data, int dataLen, int width, int height, int bitsPerComponent, bool preMulti = false);

/**
@brief 使用指定的字符串，创建一个图片
@param text       文字图像显示 (cannot be nil).
@param width      图像的宽度，如果为0，宽度将匹配文本的宽度。
@param height     图像的高度，如果为0，高度匹配文本的高度。
@param alignMask  the test Alignment                                                                    //对齐方式
@param fontName  用于绘制文本的字体名称. 如果为 nil, 使用系统默认的字体
@param size      字体大小，如果为0，则使用系统默认的大小。
* @js NA
* @lua NA
*/
bool initWithString(
const char *    text,
int             width = 0,
int             height = 0,
TextAlign       alignMask = TextAlign::CENTER,
const char *    fontName = 0,
int             size = 0);

#if (CC_TARGET_PLATFORM == CC_PLATFORM_ANDROID) || (CC_TARGET_PLATFORM == CC_PLATFORM_IOS)

bool initWithStringShadowStroke(
const char *    pText,
int             nWidth      = 0,
int             nHeight     = 0,
TextAlign       eAlignMask  = TextAlign::CENTER,
const char *    pFontName   = 0,
int             nSize       = 0,
float           textTintR   = 1,
float           textTintG   = 1,
float           textTintB   = 1,
bool shadow                 = false,
float shadowOffsetX         = 0.0,
float shadowOffsetY         = 0.0,
float shadowOpacity         = 0.0,
float shadowBlur            = 0.0,
bool  stroke                =  false,
float strokeR               = 1,
float strokeG               = 1,
float strokeB               = 1,
float strokeSize            = 1

);

#endif

// Getters
inline unsigned char *   getData()               { return _data; }
inline int               getDataLen()            { return _dataLen; }
inline Format            getFileType()           {return _fileType; }
inline Texture2D::PixelFormat getRenderFormat()    { return _renderFormat; }
inline int               getWidth()              { return _width; }
inline int               getHeight()             { return _height; }
inline bool              isPremultipliedAlpha()  { return _preMulti;   }
inline int               getNumberOfMipmaps()    { return _numberOfMipmaps; }
inline MipmapInfo*       getMipmaps()            { return _mipmaps; }
inline bool              hasPremultipliedAlpha() { return _hasPremultipliedAlpha; }

int                      getBitPerPixel();
bool                     hasAlpha();
bool                     isCompressed();

/**
@brief   以指定的格式，将图像数据保存到指定的文件
@param    filePath       文件的绝对路径，包括文件后缀
@param    isToRGB       是否将图片保存为RGB格式
*/
bool saveToFile(const char *filePath, bool isToRGB = true);

protected:
bool initWithJpgData(const unsigned char *  data, int dataLen);
bool initWithPngData(const unsigned char * data, int dataLen);
bool initWithTiffData(const unsigned char * data, int dataLen);
bool initWithWebpData(const unsigned char * data, int dataLen);
bool initWithPVRData(const unsigned char * data, int dataLen);
bool initWithPVRv2Data(const unsigned char * data, int dataLen);
bool initWithPVRv3Data(const unsigned char * data, int dataLen);
bool initWithETCData(const unsigned char * data, int dataLen);
bool initWithS3TCData(const unsigned char * data, int dataLen);
bool initWithATITCData(const unsigned char *data, int dataLen);

bool saveImageToPNG(const char *filePath, bool isToRGB = true);
bool saveImageToJPG(const char *filePath);

private:
/**
@brief     确定我们可以有多少 mipmaps。相同的定义，但它尊重命名空间
*/
static const int MIPMAP_MAX = 16;
unsigned char *_data;
int _dataLen;
int _width;
int _height;
Format _fileType;
Texture2D::PixelFormat _renderFormat;
bool _preMulti;
MipmapInfo _mipmaps[MIPMAP_MAX];   // 指向 mipmap 图片
int _numberOfMipmaps;
// false 如果我们不能自动检测图像是经过预乘.
bool _hasPremultipliedAlpha;

private:
// noncopyable              //不可拷贝
Image(const Image&    rImg);
Image & operator=(const Image&);

/*
@brief 与 initWithImageFile 有同样的结果, 但是线程是安全的，它是受 TextureCache.cpp 的 loadImage()影响 .
@param fullpath  这个文件的完整路径.
@param imageType 图像的类型，目前仅支持两种类型
@return  true if loaded correctly.
*/
bool initWithImageFileThreadSafe(const char *fullpath);

Format detectFormat(const unsigned char * data, int dataLen);
bool isPng(const unsigned char * data, int dataLen);
bool isJpg(const unsigned char * data, int dataLen);
bool isTiff(const unsigned char * data, int dataLen);
bool isWebp(const unsigned char * data, int dataLen);
bool isPvr(const unsigned char * data, int dataLen);
bool isEtc(const unsigned char * data, int dataLen);
bool isS3TC(const unsigned char * data,int dataLen);
bool isATITC(const unsigned char *data, int dataLen);
};

// end of platform group
/// @}

NS_CC_END

#endif    // __CC_IMAGE_H__