Class cc.Sprite

Class Summary
Constructor Attributes Constructor Name and Description
 
cc.Sprite(fileName, rect, rotated)

cc.Sprite is a 2d image ( http://en.wikipedia.org/wiki/Sprite_(computer_graphics) )
cc.Sprite can be created with an image, or with a sub-rectangle of an image.

Method Summary

Class Detail

cc.Sprite(fileName, rect, rotated)

cc.Sprite is a 2d image ( http://en.wikipedia.org/wiki/Sprite_(computer_graphics) )
cc.Sprite can be created with an image, or with a sub-rectangle of an image.
If the parent or any of its ancestors is a cc.SpriteBatchNode then the following features/limitations are valid
- Features when the parent is a cc.BatchNode:
- MUCH faster rendering, specially if the cc.SpriteBatchNode has many children. All the children will be drawn in a single batch.
- Limitations
- Camera is not supported yet (eg: CCOrbitCamera action doesn't work)
- GridBase actions are not supported (eg: CCLens, CCRipple, CCTwirl)
- The Alias/Antialias property belongs to CCSpriteBatchNode, so you can't individually set the aliased property.
- The Blending function property belongs to CCSpriteBatchNode, so you can't individually set the blending function property.
- Parallax scroller is not supported, but can be simulated with a "proxy" sprite.
If the parent is an standard cc.Node, then cc.Sprite behaves like any other cc.Node:
- It supports blending functions
- It supports aliasing / antialiasing
- But the rendering will be slower: 1 draw per children.
The default anchorPoint in cc.Sprite is (0.5, 0.5).

1.Create a sprite with image path and rect
var sprite1 = new cc.Sprite("res/HelloHTML5World.png");
var sprite2 = new cc.Sprite("res/HelloHTML5World.png",cc.rect(0,0,480,320));

2.Create a sprite with a sprite frame name. Must add "#" before frame name.
var sprite = new cc.Sprite('#grossini_dance_01.png');

3.Create a sprite with a sprite frame
var spriteFrame = cc.spriteFrameCache.getSpriteFrame("grossini_dance_01.png");
var sprite = new cc.Sprite(spriteFrame);

4.Create a sprite with an existing texture contained in a CCTexture2D object
     After creation, the rect will be the size of the texture, and the offset will be (0,0).
var texture = cc.textureCache.addImage("HelloHTML5World.png");
var sprite1 = new cc.Sprite(texture);
var sprite2 = new cc.Sprite(texture, cc.rect(0,0,480,320));
Parameters:
{String|cc.SpriteFrame|HTMLImageElement|cc.Texture2D} fileName
The string which indicates a path to image file, e.g., "scene1/monster.png".
{cc.Rect} rect Optional
Only the contents inside rect of pszFileName's texture will be applied for this sprite.
{Boolean} rotated Optional
Whether or not the texture rectangle is rotated.

Field Detail

{Number} atlasIndex
- The index used on the TextureAtlas.
{cc.SpriteBatchNode} batchNode
- The batch node object if this sprite is rendered by cc.SpriteBatchNode.
{Boolean} dirty
- Indicates whether the sprite needs to be updated.
{Boolean} flippedX
- Indicates whether or not the sprite is flipped on x axis.
{Boolean} flippedY
- Indicates whether or not the sprite is flipped on y axis.
<static> <constant> cc.Sprite.INDEX_NOT_INITIALIZED
cc.Sprite invalid index on the cc.SpriteBatchNode
{Number} offsetX
- <@readonly> The offset position on x axis of the sprite in texture. Calculated automatically by editors like Zwoptex.
{Number} offsetY
- <@readonly> The offset position on x axis of the sprite in texture. Calculated automatically by editors like Zwoptex.
- <@readonly> The quad (tex coords, vertex coords and color) information.
{cc.Texture2D} texture
- Texture used to render the sprite.
{cc.TextureAtlas} textureAtlas
- The weak reference of the cc.TextureAtlas when the sprite is rendered using via cc.SpriteBatchNode.
{Boolean} textureRectRotated
- <@readonly> Indicate whether the texture rectangle is rotated.

Method Detail

  • addChild(child, localZOrder, tag)
    Add child to sprite (override cc.Node)
    Parameters:
    {cc.Sprite} child
    {Number} localZOrder
    child's zOrder
    {number|String} tag Optional
    child's tag
  • addLoadedEventListener(callback, target)
    Add a event listener for texture loaded event.
    Parameters:
    {Function} callback
    {Object} target
    Deprecated:
    since 3.1, please use addEventListener instead
  • <static> {cc.Sprite} cc.Sprite.create(fileName, rect, rotated)
    Create a sprite with image path or frame name or texture or spriteFrame.
    Parameters:
    {String|cc.SpriteFrame|HTMLImageElement|cc.Texture2D} fileName
    The string which indicates a path to image file, e.g., "scene1/monster.png".
    {cc.Rect} rect
    Only the contents inside rect of pszFileName's texture will be applied for this sprite.
    {Boolean} rotated Optional
    Whether or not the texture rectangle is rotated.
    Deprecated:
    since v3.0, please use new construction instead
    Returns:
    {cc.Sprite} A valid sprite object
    See:
    cc.Sprite
  • <static> cc.Sprite.createWithSpriteFrame()
    Deprecated:
    since v3.0, please use new construction instead
    See:
    cc.Sprite
  • <static> cc.Sprite.createWithSpriteFrameName()
    Deprecated:
    since v3.0, please use new construction instead
    See:
    cc.Sprite
  • <static> cc.Sprite.createWithTexture()
    Deprecated:
    since v3.0, please use new construction instead
    See:
    cc.Sprite
  • {cc.SpriteFrame} displayFrame()
    Returns the current displayed frame.
    Deprecated:
    since 3.4, please use getSpriteFrame instead
    Returns:
    {cc.SpriteFrame}
  • {Number} getAtlasIndex()
    Returns the index used on the TextureAtlas.
    Returns:
    {Number}
  • {cc.SpriteBatchNode|null} getBatchNode()
    Returns the batch node object if this sprite is rendered by cc.SpriteBatchNode
    Returns:
    {cc.SpriteBatchNode|null} The cc.SpriteBatchNode object if this sprite is rendered by cc.SpriteBatchNode, null if the sprite isn't used batch node.
  • {cc.BlendFunc} getBlendFunc()
    Returns the blend function
    Returns:
    {cc.BlendFunc}
  • {cc.Point} getOffsetPosition()
    Returns the offset position of the sprite. Calculated automatically by editors like Zwoptex.
    Returns:
    {cc.Point}
  • {cc.V3F_C4B_T2F_Quad|null} getQuad()
    Returns the quad (tex coords, vertex coords and color) information.
    Returns:
    {cc.V3F_C4B_T2F_Quad|null} Returns a cc.V3F_C4B_T2F_Quad object when render mode is WebGL, returns null when render mode is Canvas.
  • {cc.SpriteFrame} getSpriteFrame()
    Returns the current displayed frame.
    Returns:
    {cc.SpriteFrame}
  • {cc.Texture2D} getTexture()
    Returns the texture of the sprite node
    Returns:
    {cc.Texture2D}
  • {cc.TextureAtlas} getTextureAtlas()
    Returns the weak reference of the cc.TextureAtlas when the sprite is rendered using via cc.SpriteBatchNode
    Returns:
    {cc.TextureAtlas}
  • {cc.Rect} getTextureRect()
    Returns the rect of the cc.Sprite in points
    Returns:
    {cc.Rect}
  • ignoreAnchorPointForPosition(relative)
    Sets whether ignore anchor point for positioning
    Parameters:
    {Boolean} relative
  • {Boolean} init()
    Initializes an empty sprite with nothing init.
    Please pass parameters to the constructor to initialize the sprite, do not call this function yourself.
    Returns:
    {Boolean}
  • {Boolean} initWithFile(filename, rect)

    Initializes a sprite with an image filename.
    This method will find pszFilename from local file system, load its content to CCTexture2D,
    then use CCTexture2D to create a sprite.
    After initialization, the rect used will be the size of the image. The offset will be (0,0).
    Please pass parameters to the constructor to initialize the sprite, do not call this function yourself.

    Parameters:
    {String} filename
    The path to an image file in local file system
    {cc.Rect} rect
    The rectangle assigned the content area from texture.
    Returns:
    {Boolean} true if the sprite is initialized properly, false otherwise.
  • {Boolean} initWithSpriteFrame(spriteFrame)
    Initializes a sprite with a SpriteFrame. The texture and rect in SpriteFrame will be applied on this sprite.
    Please pass parameters to the constructor to initialize the sprite, do not call this function yourself,
    Parameters:
    {cc.SpriteFrame} spriteFrame
    A CCSpriteFrame object. It should includes a valid texture and a rect
    Returns:
    {Boolean} true if the sprite is initialized properly, false otherwise.
  • {Boolean} initWithSpriteFrameName(spriteFrameName)
    Initializes a sprite with a sprite frame name.
    A cc.SpriteFrame will be fetched from the cc.SpriteFrameCache by name.
    If the cc.SpriteFrame doesn't exist it will raise an exception.
    Please pass parameters to the constructor to initialize the sprite, do not call this function yourself.
    var sprite = new cc.Sprite();
    sprite.initWithSpriteFrameName("grossini_dance_01.png");
    Parameters:
    {String} spriteFrameName
    A key string that can fected a valid cc.SpriteFrame from cc.SpriteFrameCache
    Returns:
    {Boolean} true if the sprite is initialized properly, false otherwise.
  • {Boolean} initWithTexture(texture, rect, rotated, counterclockwise)
    Initializes a sprite with a texture and a rect in points, optionally rotated.
    After initialization, the rect used will be the size of the texture, and the offset will be (0,0).
    Please pass parameters to the constructor to initialize the sprite, do not call this function yourself.
    Parameters:
    {cc.Texture2D|HTMLImageElement|HTMLCanvasElement} texture
    A pointer to an existing CCTexture2D object. You can use a CCTexture2D object for many sprites.
    {cc.Rect} rect Optional
    Only the contents inside rect of this texture will be applied for this sprite.
    {Boolean} rotated Optional
    Whether or not the texture rectangle is rotated.
    {Boolean} counterclockwise Optional, Default: true
    Whether or not the texture rectangle rotation is counterclockwise (texture package is counterclockwise, spine is clockwise).
    Returns:
    {Boolean} true if the sprite is initialized properly, false otherwise.
  • {Boolean} isDirty()
    Returns whether or not the Sprite needs to be updated in the Atlas
    Returns:
    {Boolean} True if the sprite needs to be updated in the Atlas, false otherwise.
  • {Boolean} isFlippedX()

    Returns the flag which indicates whether the sprite is flipped horizontally or not.

    It only flips the texture of the sprite, and not the texture of the sprite's children.
    Also, flipping the texture doesn't alter the anchorPoint.
    If you want to flip the anchorPoint too, and/or to flip the children too use:
    sprite.setScaleX(sprite.getScaleX() * -1);

    Returns:
    {Boolean} true if the sprite is flipped horizontally, false otherwise.
  • {Boolean} isFlippedY()

    Return the flag which indicates whether the sprite is flipped vertically or not.

    It only flips the texture of the sprite, and not the texture of the sprite's children.
    Also, flipping the texture doesn't alter the anchorPoint.
    If you want to flip the anchorPoint too, and/or to flip the children too use:
    sprite.setScaleY(sprite.getScaleY() * -1);

    Returns:
    {Boolean} true if the sprite is flipped vertically, false otherwise.
  • {Boolean} isFrameDisplayed(frame)
    Returns whether or not a cc.SpriteFrame is being displayed
    Parameters:
    {cc.SpriteFrame} frame
    Returns:
    {Boolean}
  • {Boolean} isOpacityModifyRGB()
    Returns whether opacity modify color or not.
    Returns:
    {Boolean}
  • {Boolean} isTextureRectRotated()
    Returns whether or not the texture rectangle is rotated.
    Returns:
    {Boolean}
  • removeAllChildren(cleanup)
    Removes all children from the container.
    Parameters:
    cleanup
    whether or not cleanup all running actions
  • removeChild(child, cleanup)
    Removes a child from the sprite.
    Parameters:
    child
    cleanup
    whether or not cleanup all running actions
  • reorderChild(child, zOrder)
    Reorders a child according to a new z value. (override cc.Node )
    Parameters:
    {cc.Node} child
    {Number} zOrder
  • setAtlasIndex(atlasIndex)
    Sets the index used on the TextureAtlas.
    Parameters:
    {Number} atlasIndex
  • setBatchNode(spriteBatchNode)
    Sets the batch node to sprite
     var batch = new cc.SpriteBatchNode("Images/grossini_dance_atlas.png", 15);
     var sprite = new cc.Sprite(batch.texture, cc.rect(0, 0, 57, 57));
     batch.addChild(sprite);
     layer.addChild(batch);
    Parameters:
    {cc.SpriteBatchNode|null} spriteBatchNode
  • setBlendFunc(src, dst)
    conforms to cc.TextureProtocol protocol
    Parameters:
    {Number|cc.BlendFunc} src
    {Number} dst
  • setDirty(bDirty)
    Makes the sprite to be updated in the Atlas.
    Parameters:
    {Boolean} bDirty
  • setDisplayFrame(newFrame)
    Sets a new display frame to the sprite.
    Parameters:
    {cc.SpriteFrame|String} newFrame
  • setDisplayFrameWithAnimationName(animationName, frameIndex)
    Changes the display frame with animation name and index.
    The animation name will be get from the CCAnimationCache
    Parameters:
    {String} animationName
    {Number} frameIndex
  • setFlippedX(flippedX)
    Sets whether the sprite should be flipped horizontally or not.
    Parameters:
    {Boolean} flippedX
    true if the sprite should be flipped horizontally, false otherwise.
  • setFlippedY(flippedY)
    Sets whether the sprite should be flipped vertically or not.
    Parameters:
    {Boolean} flippedY
    true if the sprite should be flipped vertically, false otherwise.
  • setOpacityModifyRGB(modify)
    Sets whether opacity modify color or not.
    Parameters:
    {Boolean} modify
  • setSpriteFrame(newFrame)
    Sets a new sprite frame to the sprite.
    Parameters:
    {cc.SpriteFrame|String} newFrame
  • setTexture(texture)
    Sets the texture of sprite
    Parameters:
    {cc.Texture2D|String} texture
  • setTextureAtlas(textureAtlas)
    Sets the weak reference of the cc.TextureAtlas when the sprite is rendered using via cc.SpriteBatchNode
    Parameters:
    {cc.TextureAtlas} textureAtlas
  • setTextureRect(rect, rotated, untrimmedSize, needConvert)
    Updates the texture rect of the CCSprite in points.
    Parameters:
    {cc.Rect} rect
    a rect of texture
    {Boolean} rotated Optional
    Whether or not the texture is rotated
    {cc.Size} untrimmedSize Optional
    The original pixels size of the texture
    {Boolean} needConvert Optional
    contentScaleFactor switch
  • setVertexRect(rect)

    set the vertex rect.
    It will be called internally by setTextureRect.
    Useful if you want to create 2x images from SD images in Retina Display.
    Do not call it manually. Use setTextureRect instead.
    (override this method to generate "double scale" sprites)

    Parameters:
    {cc.Rect} rect
  • setVisible(visible)
    Sets whether the sprite is visible or not.
    Parameters:
    {Boolean} visible
  • sortAllChildren()
    Sort all children of this sprite node.
  • {boolean} textureLoaded()
    Returns whether the texture have been loaded
    Returns:
    {boolean}
  • useBatchNode(batchNode)
    Tell the sprite to use batch node render.
    Parameters:
    {cc.SpriteBatchNode} batchNode