cc.Sprite

Classcc.Sprite

 

• Defined in: CCSprite.js
• Extends cc.NodeRGBA

Class Summary

Constructor Attributes	Constructor Name and Description
	cc.Sprite() 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.

Field Summary

Field Attributes	Field Name and Description
	addChild Add child to sprite (override cc.Node )
	ctor Constructor
	draw draw sprite to canvas
	init Initializes an empty sprite with nothing init.
	initWithTexture Initializes a sprite with a texture and a rect in points, optionally rotated.
	isFrameDisplayed Returns whether or not a cc.SpriteFrame is being displayed
	setBatchNode Sets the batch node to sprite
	setBlendFunc conforms to cc.TextureProtocol protocol
	setColor color setter
	setDisplayFrame Sets a new display frame to the cc.Sprite.
	setOpacity opacity setter
	setOpacityModifyRGB opacity: conforms to CCRGBAProtocol protocol
	setTexture Texture of sprite setter
	setTextureRect updates the texture rect of the CCSprite in points.
	updateTransform updates the quad according the the rotation, position, scale values.

Fields borrowed from class cc.Node:

nodeToParentTransform, setNodeDirty, transform, visit

Method Summary

Method Attributes	Method Name and Description
<static>	cc.Sprite.create(fileName, rect) Create a sprite with filename and rect
<static>	cc.Sprite.createWithSpriteFrame(spriteFrame) Creates a sprite with a sprite frame.
<static>	cc.Sprite.createWithSpriteFrameName(spriteFrameName) Creates a sprite with a sprite frame.
<static>	cc.Sprite.createWithTexture(texture, rect) Creates a sprite with an exsiting texture contained in a CCTexture2D object  After creation, the rect will be the size of the texture, and the offset will be (0,0).
	displayFrame() Returns the current displayed frame.
	getAtlasIndex() Returns the index used on the TextureAtlas.
	getBatchNode() Returns the batch node object if this sprite is rendered by cc.SpriteBatchNode
	getBlendFunc() conforms to cc.TextureProtocol protocol
	getOffsetPosition() Gets the offset position of the sprite.
	getQuad() Returns the quad (tex coords, vertex coords and color) information.
	getSpriteBatchNode() return the SpriteBatchNode of the cc.Sprite
	getTextureAtlas() Gets the weak reference of the cc.TextureAtlas when the sprite is rendered using via cc.SpriteBatchNode
	getTextureRect() returns the rect of the cc.Sprite in points
	ignoreAnchorPointForPosition(relative) IsRelativeAnchorPoint setter (override cc.Node )
	initWithFile(filename, rect) Initializes a sprite with an image filename.
	initWithSpriteFrame(spriteFrame) Initializes a sprite with an SpriteFrame.
	initWithSpriteFrameName(spriteFrameName) Initializes a sprite with a sprite frame name.
	isDirty() Whether or not the Sprite needs to be updated in the Atlas
	isFlippedX() Returns the flag which indicates whether the sprite is flipped horizontally or not.
	isFlippedY() Return the flag which indicates whether the sprite is flipped vertically or not.
	isOpacityModifyRGB() return IsOpacityModifyRGB value
	isTextureRectRotated() Returns whether or not the texture rectangle is rotated.
	removeAllChildren(cleanup) Removes all children from the container (override cc.Node )
	removeChild(child, cleanup) Removes a child from the sprite.
	reorderChild(child, zOrder) Reorders a child according to a new z value.
	SET_DIRTY_RECURSIVELY() HACK: optimization
	setAnchorPoint(anchor) AnchorPoint setter (override cc.Node )
	setAtlasIndex(atlasIndex) Set the index used on the TextureAtlas.
	setDirty(bDirty) Makes the Sprite to be updated in the Atlas.
	setDirtyRecursively(value) set Recursively is or isn't Dirty used only when parent is cc.SpriteBatchNode
	setDisplayFrameWithAnimationName(animationName, frameIndex) changes the display frame with animation name and index.
	setFlippedX(flippedX) Sets whether the sprite should be flipped horizontally or not.
	setFlippedY(flippedY) Sets whether the sprite should be flipped vertically or not.
	setPosition(pos) position setter (override cc.Node )
	setRotation(rotation) Rotation setter (override cc.Node )
	setScale(scale, scaleY) The scale factor of the node.
	setScaleX(scaleX) ScaleX setter (override cc.Node )
	setScaleY(scaleY) ScaleY setter (override cc.Node )
	setSkewX(sx) SkewX setter (override cc.Node )
	setSkewY(sy) SkewY setter (override cc.Node )
	setSpriteBatchNode(spriteBatchNode) set the SpriteBatchNode of the cc.Sprite
	setTextureAtlas(textureAtlas) Sets the weak reference of the cc.TextureAtlas when the sprite is rendered using via cc.SpriteBatchNode
	setVertexRect(rect) set the vertex rect.
	setVertexZ(vertexZ) VertexZ setter (override cc.Node )
	setVisible(visible) visible setter (override cc.Node )
	updateColor() Update sprite's color
	useBatchNode(batchNode) tell the sprite to use batch node render.

Methods borrowed from cc.Node:

addComponent    

 

cleanup    

 

convertToNodeSpace    

 

convertToNodeSpaceAR    

 

convertTouchToNodeSpace    

convertTouchToNodeSpaceAR    

 

convertToWorldSpace    

 

convertToWorldSpaceAR    

 

description    

 

getActionByTag    

getActionManager    

 

getAnchorPoint    

 

getAnchorPointInPoints    

 

getBoundingBox    

 

getBoundingBoxToWorld    

getCamera    

 

getChildByTag    

 

getChildren    

 

getChildrenCount    

 

getComponent    

 

getContentSize    

 

getGLServerState    

getGrid    

 

getOrderOfArrival    

 

getParent    

 

getPosition    

 

getPositionX    

 

getPositionY    

 

getRotation    

getRotationX    

 

getRotationY    

 

getScale    

 

getScaleX    

 

getScaleY    

 

getScheduler    

 

getShaderProgram    

 

getSkewX    

getSkewY    

 

getTag    

 

getUserData    

 

getUserObject    

 

getVertexZ    

 

getZOrder    

 

isIgnoreAnchorPointForPosition    

isRunning    

 

isVisible    

 

nodeToWorldTransform    

 

numberOfRunningActions    

 

onEnter    

 

onEnterTransitionDidFinish    

onExit    

 

onExitTransitionDidStart    

 

parentToNodeTransform    

 

pauseSchedulerAndActions    

removeAllChildrenWithCleanup    

 

removeAllComponents    

 

removeChildByTag    

 

removeComponent    

 

removeFromParent    

removeFromParentAndCleanup    

 

resumeSchedulerAndActions    

 

retain    

 

runAction    

 

schedule    

 

scheduleOnce    

scheduleUpdate    

 

scheduleUpdateWithPriority    

 

setActionManager    

 

setAdditionalTransform    

 

setContentSize    

setGLServerState    

 

setGrid    

 

setOrderOfArrival    

 

setParent    

 

setPositionX    

 

setPositionY    

 

setRotationX    

setRotationY    

 

setScheduler    

 

setShaderProgram    

 

setTag    

 

setUserData    

 

setUserObject    

 

setZOrder    

sortAllChildren    

 

stopAction    

 

stopActionByTag    

 

stopAllActions    

 

transformAncestors    

 

unschedule    

unscheduleAllCallbacks    

 

unscheduleUpdate    

 

update    

 

worldToNodeTransform    

Class Detail

cc.Sprite()

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).

var aSprite = new cc.Sprite();
aSprite.initWithFile("HelloHTML5World.png",cc.rect(0,0,480,320));

Field Detail

addChild

Add child to sprite (override cc.Node )

 

ctor

Constructor

 

draw

draw sprite to canvas

 

{Boolean} init

Initializes an empty sprite with nothing init.

 

{Boolean} initWithTexture

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).

var img =cc.TextureCache.getInstance().addImage("HelloHTML5World.png");
var mySprite = new cc.Sprite();
mySprite.initWithTexture(img,cc.rect(0,0,480,320));

 

{Boolean} isFrameDisplayed

Returns whether or not a cc.SpriteFrame is being displayed

 

setBatchNode

Sets the batch node to sprite

 var batch = cc.SpriteBatchNode.create("Images/grossini_dance_atlas.png", 15);
 var sprite = cc.Sprite.createWithTexture(batch.getTexture(), cc.rect(0, 0, 57, 57));
 batch.addChild(sprite);
 layer.addChild(batch);

 

setBlendFunc

conforms to cc.TextureProtocol protocol

 

setColor

color setter

 

setDisplayFrame

Sets a new display frame to the cc.Sprite.

 

setOpacity

opacity setter

 

setOpacityModifyRGB

opacity: conforms to CCRGBAProtocol protocol

 

setTexture

Texture of sprite setter

 

setTextureRect

updates the texture rect of the CCSprite in points.

 

updateTransform

updates the quad according the the rotation, position, scale values.

Method Detail

• <static> {cc.Sprite} cc.Sprite.create(fileName, rect)
  Create a sprite with filename and rect

  //create a sprite with filename
  var sprite1 = cc.Sprite.create("HelloHTML5World.png");
  
  //create a sprite with filename and rect
  var sprite2 = cc.Sprite.create("HelloHTML5World.png",cc.rect(0,0,480,320));

  Parameters:

  {String} 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.

  Returns:

   

  {cc.Sprite} A valid sprite object

   
• <static> {cc.Sprite} cc.Sprite.createWithSpriteFrame(spriteFrame)

  Creates a sprite with a sprite frame. 
  
  A CCSpriteFrame will be fetched from the CCSpriteFrameCache by pszSpriteFrameName param. 
  If the CCSpriteFrame doesn't exist it will raise an exception.

  //get a sprite frame
  var spriteFrame = cc.SpriteFrameCache.getInstance().getSpriteFrame("grossini_dance_01.png");
  
  //create a sprite with a sprite frame
  var sprite = cc.Sprite.createWithSpriteFrame(spriteFrame);

  Parameters:

  {cc.SpriteFrame} spriteFrame

  A sprite frame which involves a texture and a rect

  Returns:

   

  {cc.Sprite} A valid sprite object

   
• <static> {cc.Sprite} cc.Sprite.createWithSpriteFrameName(spriteFrameName)

  Creates a sprite with a sprite frame. 
  
  A CCSpriteFrame will be fetched from the CCSpriteFrameCache by pszSpriteFrameName param. 
  If the CCSpriteFrame doesn't exist it will raise an exception.

  //create a sprite with a sprite frame
  var sprite = cc.Sprite.createWithSpriteFrameName('grossini_dance_01.png');

  Parameters:

  {String} spriteFrameName

  A sprite frame which involves a texture and a rect

  Returns:

   

  {cc.Sprite} A valid sprite object

   
• <static> {cc.Sprite} cc.Sprite.createWithTexture(texture, rect)

  Creates a sprite with an exsiting texture contained in a CCTexture2D object 
  After creation, the rect will be the size of the texture, and the offset will be (0,0).

  //get an image
  var img = cc.TextureCache.getInstance().addImage("HelloHTML5World.png");
  
  //create a sprite with texture
  var sprite1 = cc.Sprite.createWithTexture(img);
  
  //create a sprite with texture and rect
  var sprite2 = cc.Sprite.createWithTexture(img, cc.rect(0,0,480,320));

  Parameters:

  {cc.Texture2D} texture

  A pointer to an existing CCTexture2D object. You can use a CCTexture2D object for many sprites.

  {cc.Rect} rect

  Only the contents inside the rect of this texture will be applied for this sprite.

  Returns:

   

  {cc.Sprite} A valid sprite object

   
• {cc.SpriteFrame} displayFrame()
  Returns the current displayed frame.

  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()
  conforms to cc.TextureProtocol protocol

  Returns:

   

  {cc.BlendFunc}

   
• {cc.Point} getOffsetPosition()
  Gets the offset position of the sprite. Calculated automatically by editors like Zwoptex.

  Returns:

   

  {cc.Point}

   
• {cc.V3F_C4B_T2F_Quad} getQuad()
  Returns the quad (tex coords, vertex coords and color) information.

  Returns:

   

  {cc.V3F_C4B_T2F_Quad}

   
• {cc.SpriteBatchNode} getSpriteBatchNode()
  return the SpriteBatchNode of the cc.Sprite

  Returns:

   

  {cc.SpriteBatchNode}

   
• {cc.TextureAtlas} getTextureAtlas()
  Gets 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)
  IsRelativeAnchorPoint setter (override cc.Node )

  Parameters:

  {Boolean} relative

   
• {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).

  var mySprite = new cc.Sprite();
  mySprite.initWithFile("HelloHTML5World.png",cc.rect(0,0,480,320));

  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 an SpriteFrame. The texture and rect in SpriteFrame will be applied on this sprite

  var spriteFrame = cc.SpriteFrameCache.getInstance().getSpriteFrame("grossini_dance_01.png");
  var sprite = new cc.Sprite();
  sprite.initWithSpriteFrame(spriteFrame);

  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. 

  var sprite = new cc.Sprite();
  sprite.initWithSpriteFrameName("grossini_dance_01.png");

  Parameters:

  {String} spriteFrameName

  A key string that can fected a volid cc.SpriteFrame from cc.SpriteFrameCache

  Returns:

   

  {Boolean} true if the sprite is initialized properly, false otherwise.

   
• {Boolean} isDirty()
  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 horizaontally, 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, flase otherwise.

   
• {Boolean} isOpacityModifyRGB()
  return IsOpacityModifyRGB value

  Returns:

   

  {Boolean}

   
• {Boolean} isTextureRectRotated()
  Returns whether or not the texture rectangle is rotated.

  Returns:

   

  {Boolean}

   
• removeAllChildren(cleanup)
  Removes all children from the container (override cc.Node )

  Parameters:

  cleanup

  whether or not cleanup all running actions

   
• removeChild(child, cleanup)
  Removes a child from the sprite. (override cc.Node )

  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

   
• SET_DIRTY_RECURSIVELY()
  HACK: optimization
   
• setAnchorPoint(anchor)
  AnchorPoint setter (override cc.Node )

  Parameters:

  {cc.Point} anchor

   
• setAtlasIndex(atlasIndex)
  Set the index used on the TextureAtlas.

  Parameters:

  {Number} atlasIndex

   
• setDirty(bDirty)
  Makes the Sprite to be updated in the Atlas.

  Parameters:

  {Boolean} bDirty

   
• setDirtyRecursively(value)
  set Recursively is or isn't Dirty used only when parent is cc.SpriteBatchNode

  Parameters:

  {Boolean} value

   
• setDisplayFrameWithAnimationName(animationName, frameIndex)
  changes the display frame with animation name and index.
  The animation name will be get from the CCAnimationCache

  Parameters:

  animationName

  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.

   
• setPosition(pos)
  position setter (override cc.Node )

  Parameters:

  {cc.Point} pos

   
• setRotation(rotation)
  Rotation setter (override cc.Node )

  Parameters:

  {Number} rotation

   
• setScale(scale, scaleY)

  The scale factor of the node. 1.0 is the default scale factor. 
  It modifies the X and Y scale at the same time. (override cc.Node )

   

  Parameters:

  {Number} scale

  {Number|null} scaleY Optional

   
• setScaleX(scaleX)
  ScaleX setter (override cc.Node )

  Parameters:

  {Number} scaleX

   
• setScaleY(scaleY)
  ScaleY setter (override cc.Node )

  Parameters:

  {Number} scaleY

   
• setSkewX(sx)
  SkewX setter (override cc.Node )

  Parameters:

  {Number} sx

  SkewX value

   
• setSkewY(sy)
  SkewY setter (override cc.Node )

  Parameters:

  {Number} sy

  SkewY value

   
• setSpriteBatchNode(spriteBatchNode)
  set the SpriteBatchNode of the cc.Sprite

  Parameters:

  {cc.SpriteBatchNode} spriteBatchNode

   
• setTextureAtlas(textureAtlas)
  Sets the weak reference of the cc.TextureAtlas when the sprite is rendered using via cc.SpriteBatchNode

  Parameters:

  {cc.TextureAtlas} textureAtlas

   
• 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:

  rect

   
• setVertexZ(vertexZ)
  VertexZ setter (override cc.Node )

  Parameters:

  {Number} vertexZ

   
• setVisible(visible)
  visible setter (override cc.Node )

  Parameters:

  {Boolean} visible

   
• updateColor()
  Update sprite's color
   
• useBatchNode(batchNode)
  tell the sprite to use batch node render.

  Parameters:

  {cc.SpriteBatchNode} batchNode