cocos2d-X 节点（CCSprite.h）API
本文来自http://blog.csdn.net/runaying ，引用必须注明出处！
cocos2d-X 节点（CCSprite.h）API
温馨提醒：
为了大家能更好学习，强烈推荐大家看看本人的这篇博客 Cocos2d-X权威指南笔记
Sprite 是一个 2d 图片
1.更新 Sprite 的 texture、设置 sprite 的批处理节点、设置 sprite 在 TextureAtlas 里面的索引…
1.更新 Sprite 的 texture、设置 sprite 的批处理节点、设置 sprite 在 TextureAtlas 里面的索引…
///cocos2d-x-3.0alpha0/cocos2dx/sprite_nodes #ifndef __SPITE_NODE_CCSPRITE_H__ #define __SPITE_NODE_CCSPRITE_H__ #include "base_nodes/CCNode.h" #include "CCProtocols.h" #include "textures/CCTextureAtlas.h" #include "ccTypes.h" #include "cocoa/CCDictionary.h" #include <string> #ifdef EMSCRIPTEN #include "base_nodes/CCGLBufferedNode.h" #endif // EMSCRIPTEN #include "physics/CCPhysicsBody.h" NS_CC_BEGIN class SpriteBatchNode; class SpriteFrame; class Animation; class Rect; class Point; class Size; class Texture2D; struct transformValues_;
简要
/**
* @addtogroup sprite_nodes
* @{
*/
/**
* Sprite 是一个 2d 图片 ( http://en.wikipedia.org/wiki/Sprite_(computer_graphics) )
*
* Sprite 可以使用一个图片，或者一个图片的子矩形创建
*
* 如果 Parent 或任何其父类是一个 SpriteBatchNode，那么下面 features/limitations 是有效的 //功能/限制
* - parent 是一个 BatchNode 时有一下特点:
* - 更快的渲染，特别是 SpriteBatchNode 有许多 children 。所有的 children 都将被绘制在一批次里。
*
* - Limitations
* - Camera 不支持 (eg: OrbitCamera 动作不工作)
* - GridBase动作不支持 (eg: Lens, Ripple, Twirl) //镜头，波纹，捻
* - Alias/Antialias 属性属于到SpriteBatchNode，所以你不能单独设置别名属性。 //锯齿/消除锯齿
* - Blending 功能属性属于SpriteBatchNode的，所以你不能单独设置混合功能属性。 //混合
* - 滚动条视差，不支持，但可以使用 sprite 模拟“代替”
*
* 如果 parent 是一个标准 Node, 那么精灵的表现方式和其它的节点一样；
* - 支持混合功能
* - 支持锯齿/抗锯齿
* - 但渲染速度会变慢：每一次只能绘制一个 children。But the rendering will be slower: 1 draw per children.
*
* Sprite 的默认锚点是 (0.5, 0.5).
*/
class CC_DLL Sprite : public NodeRGBA, public TextureProtocol
#ifdef EMSCRIPTEN
, public GLBufferedNode
#endif // EMSCRIPTEN
{
public:
static const int INDEX_NOT_INITIALIZED = -1; /// Sprite 索引在 SpriteBatchNode 上无效
创建初始化
/// @{
/// @name Creators
/**
* 使用 texture 闯将一个空的 sprite , 你可以随后调用 setTexture 方法
*
* @return 一个空的Sprite对象被标记为自动释放。
*/
static Sprite* create();
/**
* 使用一个图片名创建一个 sprite
*
* 创建后，矩形是 sprite 图像的大小，
* 偏移量将是（0,0）。
*
* @param 文件名的字符串表明了图片的路径, e.g., "scene1/monster.png".
* @return 一个有效的精灵被标记为自动释放的对象。
*/
static Sprite* create(const char *filename);
/**
* 使用 image 文件名和矩形创建一个 sprite
*
* @param 文件名的字符串表明了图片的路径, e.g., "scene1/monster.png".
* @param rect 只有正确的文件名路径对应的 texturn 才被应用到 sprite
* @return 一个有效的精灵被标记为自动释放的对象.
*/
static Sprite* create(const char *filename, const Rect& rect);
/**
* 使用一个已经存在 Texture2D 对象的 texture 内容创建一个 Sprite
* 创建后,矩形是 texture 的尺寸，偏移量将是（0,0）。
*
* @param texture 现有的Texture2D对象的指针。.
* @return 一个有效的精灵被标记为自动释放的对象。
*/
static Sprite* createWithTexture(Texture2D *texture);
/**
* 使用一个 texture 和一个 rect 创建一个 sprite.
*
* 创建后，偏移量将是（0,0）。
*
* @param texture 现有的Texture2D对象的指针。.
* 您可以让许多精灵使用一个Texture2D对象
* @param rect 只有正确的文件名路径对应的 texturn 才被应用到 sprite
* @return 一个有效的精灵被标记为自动释放的对象。
*/
static Sprite* createWithTexture(Texture2D *texture, const Rect& rect);
/**
* 使用 SpriteFrame 创建一个 Sprite对象
*
* @param pSpriteFrame 一个 SpriteFrame 对象，他包含一个 texture 一个 rect
* @return 一个有效的精灵被标记为自动释放的对象。
*/
static Sprite* createWithSpriteFrame(SpriteFrame *pSpriteFrame);
/**
* 使用一个精灵名创建一个 sprite
*
* A SpriteFrame will be fetched from the SpriteFrameCache by spriteFrameName param.
* If the SpriteFrame doesn't exist it will raise an exception.
*
* @param spriteFrameName A null terminated string which indicates the sprite frame name.
* @return 一个有效的精灵被标记为自动释放的对象。
*/
static Sprite* createWithSpriteFrameName(const char *spriteFrameName);
/// @} end of creators group
/// @{
/// @name Initializers
/**
* Default constructor
* @js ctor
*/
Sprite(void);
/**
* Default destructor
* @js NA
* @lua NA
*/
virtual ~Sprite(void);
/**
* 什么都不使用初始化一个精灵
*/
virtual bool init(void);
/**
* 使用 texture 初始化一个精灵.
*
* 初始化后, rect 使用 texture 的尺寸，偏移量将是（0,0）。
*
* @param texture 现有的Texture2D对象的指针。.
* 您可以让许多精灵使用一个Texture2D对象
* @return true 如果精灵正确初始化，否则返回false。
*/
virtual bool initWithTexture(Texture2D *texture);
/**
* 使用 texture 、 rect 初始化一个精灵.
*
* 初始化后,偏移量将是（0,0）。
*
* @param texture 现有的Texture2D对象的指针。.
* 您可以让许多精灵使用一个Texture2D对象
* @param rect 只有正确的文件名路径对应的 texturn 才被应用到 sprite
* @return true 如果精灵正确初始化，否则返回false。
*/
virtual bool initWithTexture(Texture2D *texture, const Rect& rect);
/**
* 纹理和一个矩形点，任意旋转，初始化一个精灵，
*
* 初始化后,偏移量将是（0,0）。
* @note This is the designated initializer.
*
* @param texture A Texture2D object whose texture will be applied to this sprite.
* @param rect A rectangle assigned the contents of texture.
* @param rotated Whether or not the texture rectangle is rotated.
* @return true 如果精灵正确初始化，否则返回false。.
*/
virtual bool initWithTexture(Texture2D *texture, const Rect& rect, bool rotated);
/**
* 使用 SpriteFrame 初始化精灵. SpriteFrame 的 texture 、rect 将会应用到这个 sprite
*
* @param pSpriteFrame 一个 SpriteFrame 对象，他包含一个 texture 一个 rect
* @return true 如果精灵正确初始化，否则返回false.
*/
virtual bool initWithSpriteFrame(SpriteFrame *pSpriteFrame);
/**
* 使用 spriteFrameName 初始化一个精灵
*
* 可以从 SpriteFrameCache 找到 spriteFrameName 所关联的 SpriteFrame.
* 如果SpriteFrame不存在，它会触发异常。
*
* @param spriteFrameName 可以从 SpriteFrameCache 找到字符串关联的 SpriteFrame
* @return true 如果精灵正确初始化，否则返回false。
*/
virtual bool initWithSpriteFrameName(const char *spriteFrameName);
/**
* 使用图像文件名初始化一个精灵.
*
* 此方法将从本地文件系统寻找 filename，它的内容装载到 Texture2D,
* 然后使用 Texture2D 创建一个 sprite.
* 初始化后, rect 使用图片尺寸，偏移量将是（0,0）。
*
* @param 本地文件系统中的图像文件的路径.
* @return true 如果精灵正确初始化，否则返回false。
* @js init
* @lua init
*/
virtual bool initWithFile(const char *filename);
/**
* 使用 filename, 和一个 rect 初始化一个精灵.
*
* 此方法将从本地文件系统寻找 filename，它的内容装载到 Texture2D
* 然后使用 Texture2D 创建一个 sprite.
*初始化后,偏移量将是（0,0）。
*
* @param filename 本地文件系统中的图像文件的路径.
* @param rect The rectangle assigned the content area from texture.
* @return true 如果精灵正确初始化，否则返回false。
* @js init
* @lua init
*/
virtual bool initWithFile(const char *filename, const Rect& rect);
/// @} end of initializers
批处理节点
/// @{
/// @name BatchNode methods
/**
* 根据 rotation, position, scale 的值更新. //旋转、位置、尺寸
*/
virtual void updateTransform(void);
/**
* Returns 如果这个 sprite 由 SpriteBatchNode 渲染，那么返回一个批处理节点对象
*
* @return 如果这个 sprite 由 SpriteBatchNode 渲染，那么返回一个批处理节点对象
* NULL 这个 sprite 没有使用批处理节点.
*/
virtual SpriteBatchNode* getBatchNode(void);
/**
* Sets sprite 的批处理节点
* @warning 这种方法不建议在游戏开发中使用. 使用批处理节点的 Sample
* @code
* SpriteBatchNode *batch = SpriteBatchNode::create("Images/grossini_dance_atlas.png", 15);
* Sprite *sprite = Sprite::createWithTexture(batch->getTexture(), Rect(0, 0, 57, 57));
* batch->addChild(sprite);
* layer->addChild(batch);
* @endcode
*/
virtual void setBatchNode(SpriteBatchNode *spriteBatchNode);
/// @} end of BatchNode methods
texture 方法名
/// @{
/// @name Texture methods
/**
* 更新 Sprite的 texture rect
* 他将调用 setTextureRect(const Rect& rect, bool rotated, const Size& untrimmedSize) with \p rotated = false, and \p utrimmedSize = rect.size.
*/
virtual void setTextureRect(const Rect& rect);
/**
* 设置 Sprite的 texture rect, rectRotated 、 untrimmed 尺寸. //旋转、修建
* It will update the texture coordinates and the vertex rectangle.
*/
virtual void setTextureRect(const Rect& rect, bool rotated, const Size& untrimmedSize);
/**
* 设置矩形的顶点
* 它会在 setTextureRect 的内部调用.
* 他是有用的，如果你希望从 sd 卡里面创建一个 2x 图片在 Retina 上显示
* 不要手动调用它。使用 setTextureRect 代替。
*/
virtual void setVertexRect(const Rect& rect);
/// @} end of texture methods
Frame方法名
/// @{
/// @name Frames methods
/**
* Sets 一个新的要显示的 sprite 帧
*/
virtual void setDisplayFrame(SpriteFrame *pNewFrame);
/**
* Returns SpriteFrame 是否正在显示
*/
virtual bool isFrameDisplayed(SpriteFrame *pFrame) const;
/** @ 过时不再需要建议使用新的 API 使用 getDisplayFrame() 代替 */
CC_DEPRECATED_ATTRIBUTE virtual SpriteFrame* displayFrame() { return getDisplayFrame(); };
/**
* Returns 当前显示的帧
*/
virtual SpriteFrame* getDisplayFrame();
/// @} End of frames methods
Animation方法名
/// @{
/// @name Animation methods
/**
* 改变要显示的帧动画的名称和索引。
* 动画的名字将从 AnimationCache 里面获取
*/
virtual void setDisplayFrameWithAnimationName(const char *animationName, int frameIndex);
/// @}
Sprite setter/getter
/// @{
/// @name Sprite Properties' setter/getters
/**
* return Atlas 里面的 Sprite 是否需要更新更新
*
* @return true Atlas里面的精灵需要更新, false 其它情况.
*/
virtual bool isDirty(void) const { return _dirty; }
/**
* 设置 Atlas 里面的 Sprite 更新 // 地图集
*/
virtual void setDirty(bool bDirty) { _dirty = bDirty; }
/**
* Returns quad (顶点的坐标位置，纹理的坐标位置和颜色信息) 信息.
* @js NA
* @lua NA
*/
inline V3F_C4B_T2F_Quad getQuad(void) const { return _quad; }
/**
* Returns 纹理矩形是否旋转。
*/
inline bool isTextureRectRotated(void) const { return _rectRotated; }
/**
* Returns 用于 TextureAtlas 的索引.
*/
inline int getAtlasIndex(void) const { return _atlasIndex; }
/**
* Sets 用于 TextureAtlas 的索引.
* @warning 不要修改此值，除非你知道你在做什么
*/
inline void setAtlasIndex(int atlasIndex) { _atlasIndex = atlasIndex; }
/**
* Returns 包围 Sprite 的外围矩形 (点组成的)
*/
inline const Rect& getTextureRect(void) { return _rect; }
/**
* Gets 精灵通过 CCSpriteBatchNode 渲染使用的 TextureAtlas 弱引用
*/
inline TextureAtlas* getTextureAtlas(void) { return _textureAtlas; }
/**
* Sets 精灵通过 CCSpriteBatchNode 渲染使用的 TextureAtlas 弱引用
*/
inline void setTextureAtlas(TextureAtlas *pobTextureAtlas) { _textureAtlas = pobTextureAtlas; }
/**
* Gets 精灵的偏移位置。自动计算Zwoptex等。
*/
inline const Point& getOffsetPosition(void) const { return _offsetPosition; }
/**
* Return Sprite 是否水平翻转的标记
*
* 他只翻转精灵的 texture ,不翻转 Sprite's children 的 texture
* 此外，翻转纹理不改变锚点。
* 如果你也想翻转锚点 和/或 孩子们也翻转，请使用：
* sprite->setScaleX(sprite->getScaleX() * -1);
*
* @return true 精灵应该垂直翻转, flase 其它情况.
*/
bool isFlippedX(void) const;
/**
* Sets 精灵是否应该水平翻转
*
* @param bFlipX true 精灵应该水平翻转, flase 其它情况.
*/
void setFlippedX(bool flippedX);
/** @ 过时不再需要建议使用新的 API 请使用 isFlippedX() 代替
* @js NA
* @lua NA
*/
CC_DEPRECATED_ATTRIBUTE bool isFlipX() { return isFlippedX(); };
/** @ 过时不再需要建议使用新的 API 请使用 setFlippedX() 代替 */
CC_DEPRECATED_ATTRIBUTE void setFlipX(bool flippedX) { setFlippedX(flippedX); };
/**
* Return Sprite 是否垂直翻转的标记
*
* 他只翻转精灵的 texture ,不翻转 Sprite's children 的 texture
* 此外，翻转纹理不改变锚点。
* 如果你也想翻转锚点 和/或 孩子们也翻转，请使用：
* sprite->setScaleY(sprite->getScaleY() * -1);
*
* @return true 精灵应该垂直翻转, flase 其它情况.
*/
bool isFlippedY(void) const;
/**
* Sets 精灵是否应该垂直翻转
*
* @param bFlipY true 精灵应该垂直翻转, flase 其它情况.
*/
void setFlippedY(bool flippedY);
#ifdef CC_USE_PHYSICS
/**
* set PhysicsBody 使 sprite 效果更真实
*/
virtual void setPhysicsBody(PhysicsBody* body);
/**
* get Sprite 的 PhysicsBody
*/
PhysicsBody* getPhysicsBody() const;
virtual void visit() override;
#endif
/// @} End of Sprite properties getter/setters
/** @过时不再需要建议使用新的 API deprecated Use isFlippedY() instead */
CC_DEPRECATED_ATTRIBUTE bool isFlipY() { return isFlippedY(); };
/** @ 过时不再需要建议使用新的 API deprecated Use setFlippedY() instead */
CC_DEPRECATED_ATTRIBUTE void setFlipY(bool flippedY) { setFlippedY(flippedY); };
TextureProtocol 内部功能
//
// Overrides
//
/// @{
/// @name Functions inherited from TextureProtocol //继承自 TextureProtocol 的功能
virtual void setTexture(Texture2D *texture) override;
virtual Texture2D* getTexture() const override;
/**
*@code
*当此功能绑定到 js 或 lua,参数将被改变
*In js: var setBlendFunc(var src, var dst)
*In lua: local setBlendFunc(local src, local dst)
*@endcode
*/
inline void setBlendFunc(const BlendFunc &blendFunc) override { _blendFunc = blendFunc; }
/**
* @js NA
* @lua NA
*/
inline const BlendFunc& getBlendFunc() const override { return _blendFunc; }
/// @}
节点的内部功能名
/// @{
/// @name Functions inherited from Node //从 Node 继承的功能名称
virtual void setScaleX(float scaleX) override;
virtual void setScaleY(float scaleY) override;
/**
* @js NA
* @lua NA
*/
virtual void setPosition(const Point& pos) override;
virtual void setRotation(float rotation) override;
virtual void setRotationX(float rotationX) override;
virtual void setRotationY(float rotationY) override;
virtual void setSkewX(float sx) override;
virtual void setSkewY(float sy) override;
virtual void removeChild(Node* child, bool cleanup) override;
virtual void removeAllChildrenWithCleanup(bool cleanup) override;
virtual void reorderChild(Node *child, int zOrder) override;
virtual void addChild(Node *child) override;
virtual void addChild(Node *child, int zOrder) override;
virtual void addChild(Node *child, int zOrder, int tag) override;
virtual void sortAllChildren() override;
virtual void setScale(float scale) override;
virtual void setVertexZ(float vertexZ) override;
virtual void setAnchorPoint(const Point& anchor) override;
virtual void ignoreAnchorPointForPosition(bool value) override;
virtual void setVisible(bool bVisible) override;
virtual void draw(void) override;
/// @}
NodeRGBA内部功能
/// @{
/// @name Functions inherited from NodeRGBA //继承自 NodeRGBA 的功能名称
virtual void setColor(const Color3B& color3) override;
virtual void updateDisplayedColor(const Color3B& parentColor) override;
virtual void setOpacity(GLubyte opacity) override;
virtual void setOpacityModifyRGB(bool modify) override;
virtual bool isOpacityModifyRGB(void) const override;
virtual void updateDisplayedOpacity(GLubyte parentOpacity) override;
/// @}
protected:
void updateColor(void);
virtual void setTextureCoords(Rect rect);
virtual void updateBlendFunc(void);
virtual void setReorderChildDirtyRecursively(void);
virtual void setDirtyRecursively(bool bValue);
//
// 当 Sprite 使用 SpriteSheet 渲染的时候使用的数据
//
TextureAtlas* _textureAtlas; /// SpriteBatchNode 纹理集 (弱引用)
int _atlasIndex; /// 在 SpriteSheet 里面的绝对（真实）索引
SpriteBatchNode* _batchNode; /// Used batch node (weak reference)
bool _dirty; /// sprite 是否需要更新
bool _recursiveDirty; /// 是否所有的 sprite's children 需要更新
bool _hasChildren; /// sprite 是否包含 children
bool _shouldBeHidden; /// 因为它的一个 ancestors 是不可见的，所以不应该被绘制
AffineTransform _transformToBatch;
//
// sprite self-rendered 的时候使用的数据 //渲染自己
//
BlendFunc _blendFunc; /// 它必须继承 TextureProtocol 协议
Texture2D* _texture; /// Sprit 渲染的时候使用到的 Texture2D 对象
//
// Shared data
//
// texture
Rect _rect; /// Texture2D 的 Retangle //矩形框
bool _rectRotated; /// 是否旋转 texture
// 偏移位置（在 Zwoptex 里使用）
Point _offsetPosition;
Point _unflippedOffsetPositionFromCenter;
// 顶点的坐标位置，纹理的坐标位置和颜色信息
V3F_C4B_T2F_Quad _quad;
// 不透明度和RGB协议
bool _opacityModifyRGB;
// 图片被翻转
bool _flippedX; /// sprite是否水平翻转
bool _flippedY; /// sprite是否垂直翻转。
#ifdef CC_USE_PHYSICS
PhysicsBody* _physicsBody; ///< 节点的 physicsBody
#endif
};
// end of sprite_nodes group
/// @}
NS_CC_END
#endif // __SPITE_NODE_CCSPRITE_H__