cocos2d-X 节点（CCSprite.h）API

最新推荐文章于 2022-11-29 17:05:51 发布

runaying

最新推荐文章于 2022-11-29 17:05:51 发布

阅读量5k

点赞数

分类专栏： cocos2d-x 文章标签： cocos2d-x cocos2dx

本文链接：https://blog.csdn.net/runaying/article/details/13291047

版权

cocos2d-x 专栏收录该内容

203 篇文章

订阅专栏

这篇博客详细介绍了cocos2d-X中的CCSprite节点，包括创建初始化、批处理节点操作、纹理方法、帧方法、动画方法、属性设置与获取、TextureProtocol和节点及NodeRGBA的内部功能。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

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

cocos2d-X 节点（CCSprite.h）API

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

Sprite 是一个 2d 图片
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__