Class CCSprite

#include <Geode/cocos/sprite_nodes/CCSprite.h>
classCCSprite:publiccocos2d::CCNodeRGBA,publiccocos2d::CCTextureProtocol{ ... }

CCSprite is a 2d image ( http://en.wikipedia.org/wiki/Sprite_(computer_graphics) )

CCSprite can be created with an image, or with a sub-rectangle of an image.

If the parent or any of its ancestors is a CCSpriteBatchNode then the following features/limitations are valid

  • Features when the parent is a CCBatchNode:

    • MUCH faster rendering, specially if the CCSpriteBatchNode 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 CCNode, then CCSprite behaves like any other CCNode:

  • It supports blending functions
  • It supports aliasing / antialiasing
  • But the rendering will be slower: 1 draw per children.

The default anchorPoint in CCSprite is (0.5, 0.5).

Examples0
Public static methods7
staticcocos2d::CCSprite*create()

Creates an empty sprite without texture. You can call setTexture method subsequently.

Return value
An empty sprite object that is marked as autoreleased.
staticcocos2d::CCSprite*create(
charconst*pszFileName
)

Creates a sprite with an image filename.

After creation, the rect of sprite will be the size of the image, and the offset will be (0,0).

Parameters

pszFileName

The string which indicates a path to image file, e.g., "scene1/monster.png".
Return value
A valid sprite object that is marked as autoreleased.
staticcocos2d::CCSprite*create(
charconst*pszFileName
,
cocos2d::CCRectconst&rect
)

Creates a sprite with an image filename and a rect.

Parameters

pszFileName

The string wich indicates a path to image file, e.g., "scene1/monster.png"

rect

Only the contents inside rect of pszFileName's texture will be applied for this sprite.
Return value
A valid sprite object that is marked as autoreleased.
staticcocos2d::CCSprite*createWithTexture(
cocos2d::CCTexture2D*pTexture
)

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

Parameters

pTexture

A pointer to a CCTexture2D object.
Return value
A valid sprite object that is marked as autoreleased.
staticcocos2d::CCSprite*createWithTexture(
cocos2d::CCTexture2D*pTexture
,
cocos2d::CCRectconst&rect
)

Creates a sprite with a texture and a rect.

After creation, the offset will be (0,0).

Parameters

pTexture

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

rect

Only the contents inside the rect of this texture will be applied for this sprite.
Return value
A valid sprite object that is marked as autoreleased.
staticcocos2d::CCSprite*createWithSpriteFrame(
cocos2d::CCSpriteFrame*pSpriteFrame
)

Creates a sprite with an sprite frame.

Parameters

pSpriteFrame

A sprite frame which involves a texture and a rect
Return value
A valid sprite object that is marked as autoreleased.
staticcocos2d::CCSprite*createWithSpriteFrameName(
charconst*pszSpriteFrameName
)

Creates a sprite with an sprite frame name.

A CCSpriteFrame will be fetched from the CCSpriteFrameCache by pszSpriteFrameName param. If the CCSpriteFrame doesn’t exist it will raise an exception.

Parameters

pszSpriteFrameName

A null terminated string which indicates the sprite frame name.
Return value
A valid sprite object that is marked as autoreleased.
Public member functions79
virtualboolinit()

Initializes an empty sprite with nothing init.

virtualboolinitWithTexture(
cocos2d::CCTexture2D*pTexture
)

Initializes a sprite with a texture.

After initialization, the rect used will be the size of the texture, and the offset will be (0,0).

Parameters

pTexture

A pointer to an existing CCTexture2D object. You can use a CCTexture2D object for many sprites.
Return value
true if the sprite is initialized properly, false otherwise.
virtualboolinitWithTexture(
cocos2d::CCTexture2D*pTexture
,
cocos2d::CCRectconst&rect
)

Initializes a sprite with a texture and a rect.

After initialization, the offset will be (0,0).

Parameters

pTexture

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

rect

Only the contents inside rect of this texture will be applied for this sprite.
Return value
true if the sprite is initialized properly, false otherwise.
virtualboolinitWithTexture(
cocos2d::CCTexture2D*pTexture
,
cocos2d::CCRectconst&rect
,
boolrotated
)

Initializes a sprite with a texture and a rect in points, optionally rotated.

After initialization, the offset will be (0,0).

Parameters

pTexture

A CCTexture2D object whose texture will be applied to this sprite.

rect

A rectangle assigned the contents of texture.

rotated

Whether or not the texture rectangle is rotated.
Return value
true if the sprite is initialized properly, false otherwise.

ℹ This is the designated initializer.

virtualboolinitWithSpriteFrame(
cocos2d::CCSpriteFrame*pSpriteFrame
)

Initializes a sprite with an SpriteFrame. The texture and rect in SpriteFrame will be applied on this sprite

Parameters

pSpriteFrame

A CCSpriteFrame object. It should includes a valid texture and a rect
Return value
true if the sprite is initialized properly, false otherwise.
virtualboolinitWithSpriteFrameName(
charconst*pszSpriteFrameName
)

Initializes a sprite with an sprite frame name.

A CCSpriteFrame will be fetched from the CCSpriteFrameCache by name. If the CCSpriteFrame doesn’t exist it will raise an exception.

Parameters

pszSpriteFrameName

A key string that can fected a volid CCSpriteFrame from CCSpriteFrameCache
Return value
true if the sprite is initialized properly, false otherwise.
virtualboolinitWithFile(
charconst*pszFilename
)

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

Parameters

pszFilename

The path to an image file in local file system
Return value
true if the sprite is initialized properly, false otherwise.
virtualboolinitWithFile(
charconst*pszFilename
,
cocos2d::CCRectconst&rect
)

Initializes a sprite with an image filename, and a rect.

This method will find pszFilename from local file system, load its content to CCTexture2D, then use CCTexture2D to create a sprite. After initialization, the offset will be (0,0).

Parameters

pszFilename

The path to an image file in local file system.

rect

The rectangle assigned the content area from texture.
Return value
true if the sprite is initialized properly, false otherwise.
virtualvoidsetTexture(
cocos2d::CCTexture2D*texture
)

///

virtualcocos2d::CCTexture2D*getTexture()
No description provided
virtualvoidsetBlendFunc(
cocos2d::ccBlendFuncblendFunc
)
No description provided
virtualcocos2d::ccBlendFuncgetBlendFunc()
No description provided
virtualvoidsetChildColor(
cocos2d::ccColor3Bconst&
)
No description provided
virtualvoidsetChildOpacity(
_::GLubyte
)
No description provided
virtualvoidsetScaleX(
floatfScaleX
)

///

virtualvoidsetScaleY(
floatfScaleY
)
No description provided
virtualvoidsetPosition(
cocos2d::CCPointconst&pos
)
No description provided
virtualvoidsetRotation(
floatfRotation
)
No description provided
virtualvoidsetRotationX(
floatfRotationX
)
No description provided
virtualvoidsetRotationY(
floatfRotationY
)
No description provided
virtualvoidsetSkewX(
floatsx
)
No description provided
virtualvoidsetSkewY(
floatsy
)
No description provided
virtualvoidremoveChild(
cocos2d::CCNode*pChild
,
boolbCleanup
)
No description provided
virtualvoidremoveAllChildrenWithCleanup(
boolbCleanup
)
No description provided
virtualvoidreorderChild(
cocos2d::CCNode*pChild
,
intzOrder
)
No description provided
virtualvoidaddChild(
cocos2d::CCNode*pChild
)
No description provided
virtualvoidaddChild(
cocos2d::CCNode*pChild
,
intzOrder
)
No description provided
virtualvoidaddChild(
cocos2d::CCNode*pChild
,
intzOrder
,
inttag
)
No description provided
virtualvoidsortAllChildren()
No description provided
virtualvoidsetScale(
floatfScale
)
No description provided
virtualvoidsetVertexZ(
floatfVertexZ
)
No description provided
virtualvoidsetAnchorPoint(
cocos2d::CCPointconst&anchor
)
No description provided
virtualvoidignoreAnchorPointForPosition(
boolvalue
)
No description provided
virtualvoidsetVisible(
boolbVisible
)
No description provided
virtualvoiddraw()
No description provided
virtualvoidsetColor(
cocos2d::ccColor3Bconst&color3
)

///

virtualvoidupdateDisplayedColor(
cocos2d::ccColor3Bconst&parentColor
)
No description provided
virtualvoidsetOpacity(
_::GLubyteopacity
)
No description provided
virtualvoidsetOpacityModifyRGB(
boolmodify
)
No description provided
virtualboolisOpacityModifyRGB()
No description provided
virtualvoidupdateDisplayedOpacity(
_::GLubyteparentOpacity
)
No description provided
virtualvoidupdateTransform()

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

virtualcocos2d::CCSpriteBatchNode*getBatchNode()

Returns the batch node object if this sprite is rendered by CCSpriteBatchNode

Return value
The CCSpriteBatchNode object if this sprite is rendered by CCSpriteBatchNode, NULL if the sprite isn't used batch node.
virtualvoidsetBatchNode(
cocos2d::CCSpriteBatchNode*pobSpriteBatchNode
)

Sets the batch node to sprite

⚠️ This method is not recommended for game developers. Sample code for using batch node

CCSpriteBatchNode *batch = CCSpriteBatchNode::create("Images/grossini_dance_atlas.png", 15);
CCSprite *sprite = CCSprite::createWithTexture(batch->getTexture(), CCRectMake(0, 0, 57, 57));
batch->addChild(sprite);
layer->addChild(batch);
virtualvoidrefreshTextureRect()
No description provided
virtualvoidsetTextureRect(
cocos2d::CCRectconst&rect
)

Updates the texture rect of the CCSprite in points. It will call setTextureRect:rotated:untrimmedSize with rotated = NO, and utrimmedSize = rect.size.

virtualvoidsetTextureRect(
cocos2d::CCRectconst&rect
,
boolrotated
,
cocos2d::CCSizeconst&untrimmedSize
)

Sets the texture rect, rectRotated and untrimmed size of the CCSprite in points. It will update the texture coordinates and the vertex rectangle.

virtualvoidsetVertexRect(
cocos2d::CCRectconst&rect
)

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

virtualvoidsetDisplayFrame(
cocos2d::CCSpriteFrame*pNewFrame
)

Sets a new display frame to the CCSprite.

virtualboolisFrameDisplayed(
cocos2d::CCSpriteFrame*pFrame
)

Returns whether or not a CCSpriteFrame is being displayed

virtualcocos2d::CCSpriteFrame*displayFrame()

Returns the current displayed frame.

virtualvoidsetDisplayFrameWithAnimationName(
charconst*animationName
,
intframeIndex
)

///

virtualboolisDirty()

Whether or not the Sprite needs to be updated in the Atlas.

Return value
true if the sprite needs to be updated in the Atlas, false otherwise.
virtualvoidsetDirty(
boolbDirty
)

Makes the Sprite to be updated in the Atlas.

cocos2d::ccV3F_C4B_T2F_QuadgetQuad()

Returns the quad (tex coords, vertex coords and color) information.

boolisTextureRectRotated()

Returns whether or not the texture rectangle is rotated.

uintgetAtlasIndex()

Returns the index used on the TextureAtlas.

voidsetAtlasIndex(
uintuAtlasIndex
)

Sets the index used on the TextureAtlas.

⚠️ Don't modify this value unless you know what you are doing

cocos2d::CCRectconst&getTextureRect()

Returns the rect of the CCSprite in points

cocos2d::CCTextureAtlas*getTextureAtlas()

Gets the weak reference of the CCTextureAtlas when the sprite is rendered using via CCSpriteBatchNode

voidsetTextureAtlas(
cocos2d::CCTextureAtlas*pobTextureAtlas
)

Sets the weak reference of the CCTextureAtlas when the sprite is rendered using via CCSpriteBatchNode

cocos2d::CCPointconst&getOffsetPosition()

Gets the offset position of the sprite. Calculated automatically by editors like Zwoptex.

boolisFlipX()

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

Return value
true if the sprite is flipped horizaontally, false otherwise.
voidsetFlipX(
boolbFlipX
)

Sets whether the sprite should be flipped horizontally or not.

Parameters

bFlipX

true if the sprite should be flipped horizaontally, false otherwise.
boolisFlipY()

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

Return value
true if the sprite is flipped vertically, flase otherwise.
voidsetFlipY(
boolbFlipY
)

Sets whether the sprite should be flipped vertically or not.

Parameters

bFlipY

true if the sprite should be flipped vertically, flase otherwise.
cocos2d::CCPointconst&getUnflippedOffsetPosition()

///

boolgetUseVertexMod()const
No description provided
voidsetUseVertexMod(
bool
)
No description provided
boolgetDontDraw()const
No description provided
voidsetDontDraw(
boolvar
)
No description provided
floatgetTlVertexMod()const
No description provided
voidsetTlVertexMod(
floatvar
)
No description provided
floatgetTrVertexMod()const
No description provided
voidsetTrVertexMod(
floatvar
)
No description provided
floatgetBlVertexMod()const
No description provided
voidsetBlVertexMod(
floatvar
)
No description provided
floatgetBrVertexMod()const
No description provided
voidsetBrVertexMod(
floatvar
)
No description provided
Fields2
char[16]pad579
;
No description provided
boolm_bUnknown
;
No description provided
Protected member functions5
voidupdateColor()
No description provided
virtualvoidsetTextureCoords(
cocos2d::CCRectconst&rect
)
No description provided
virtualvoidupdateBlendFunc()
No description provided
virtualvoidsetReorderChildDirtyRecursively()
No description provided
virtualvoidsetDirtyRecursively(
boolbValue
)
No description provided
Protected fields23
cocos2d::CCTextureAtlas*m_pobTextureAtlas
;
No description provided
uintm_uAtlasIndex
;

/// CCSpriteBatchNode texture atlas (weak reference)

cocos2d::CCSpriteBatchNode*m_pobBatchNode
;

/// Absolute (real) Index on the SpriteSheet

boolm_bDirty
;

/// Used batch node (weak reference)

boolm_bRecursiveDirty
;

/// Whether the sprite needs to be updated

boolm_bHasChildren
;

/// Whether all of the sprite’s children needs to be updated

boolm_bShouldBeHidden
;

/// Whether the sprite contains children

cocos2d::CCAffineTransformm_transformToBatch
;

/// should not be drawn because one of the ancestors is not visible

cocos2d::ccBlendFuncm_sBlendFunc
;
No description provided
cocos2d::CCTexture2D*m_pobTexture
;

/// It’s required for CCTextureProtocol inheritance

cocos2d::CCRectm_obRect
;

/// CCTexture2D object that is used to render the sprite

boolm_bRectRotated
;

/// Retangle of CCTexture2D

cocos2d::CCPointm_obOffsetPosition
;

/// Whether the texture is rotated

cocos2d::CCPointm_obUnflippedOffsetPositionFromCenter
;
No description provided
cocos2d::ccV3F_C4B_T2F_Quadm_sQuad
;
No description provided
boolm_bOpacityModifyRGB
;
No description provided
boolm_bFlipX
;
No description provided
boolm_bFlipY
;

/// Whether the sprite is flipped horizaontally or not.

boolm_bDontDraw
;
No description provided
floatm_fTlVertexMod
;
No description provided
floatm_fTrVertexMod
;
No description provided
floatm_fBlVertexMod
;
No description provided
floatm_fBrVertexMod
;
No description provided