Class cc.Sprite
- Defined in: CCSprite.js
- Extends cc.NodeRGBA
Constructor Attributes | Constructor Name and Description |
---|---|
cc.Sprite is a 2d image ( http://en.wikipedia.org/wiki/Sprite_(computer_graphics) ) |
Method Summary
Class Detail
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
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));
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);
Method Detail
-
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
-
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
-
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
-
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, y)Sets the anchor point in percent. (override cc.Node )
- Parameters:
- {cc.Point|Number} anchor
- The anchor Sprite of Sprite or The anchor point.x of Sprite.
- {Number} y Optional
- The anchor point.y of Sprite.
-
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, yValue)position setter (override cc.Node )
- Parameters:
- {cc.Point|Number} pos
- position or x value of position
- {Number} yValue Optional
- y value of position
-
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:
- {cc.Rect} 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