CCSprite Class Reference

#import <CCSprite.h>

Inheritance diagram for CCSprite:

Collaboration diagram for CCSprite:

Instance Methods
(id)	- initWithTexture:
(id)	- initWithTexture:rect:
(id)	- initWithTexture:rect:rotated:
(id)	- initWithSpriteFrame:
(id)	- initWithSpriteFrameName:
(id)	- initWithFile:
(id)	- initWithFile:rect:
(id)	- initWithCGImage:key:
(void)	- updateTransform
(void)	- setTextureRect:
(void)	- setTextureRect:rotated:untrimmedSize:
(void)	- setVertexRect:
(void)	- setDisplayFrame:
(BOOL)	- isFrameDisplayed:
(CCSpriteFrame *)	- displayFrame
(void)	- setDisplayFrameWithAnimationName:index:
(id)	- initWithBatchNode:rect:
(CCSpriteFrame *)	- DEPRECATED_ATTRIBUTE
Instance Methods inherited from CCNodeRGBA
(GLubyte)	- opacity
Instance Methods inherited from CCNode
(id)	- init
(void)	- onEnter
(void)	- onEnterTransitionDidFinish
(void)	- onExit
(void)	- onExitTransitionDidStart
(void)	- addChild:
(void)	- addChild:z:
(void)	- addChild:z:tag:
(void)	- removeFromParent
(void)	- removeFromParentAndCleanup:
(void)	- removeChild:
(void)	- removeChild:cleanup:
(void)	- removeChildByTag:
(void)	- removeChildByTag:cleanup:
(void)	- removeAllChildren
(void)	- removeAllChildrenWithCleanup:
(CCNode *)	- getChildByTag:
(void)	- reorderChild:z:
(void)	- sortAllChildren
(void)	- cleanup
(void)	- draw
(void)	- visit
(void)	- transform
(void)	- transformAncestors
(CGRect)	- boundingBox
(CCAction *)	- runAction:
(void)	- stopAllActions
(void)	- stopAction:
(void)	- stopActionByTag:
(CCAction *)	- getActionByTag:
(NSUInteger)	- numberOfRunningActions
(void)	- scheduleUpdate
(void)	- scheduleUpdateWithPriority:
(void)	- unscheduleUpdate
(void)	- schedule:
(void)	- schedule:interval:
(void)	- schedule:interval:repeat:delay:
(void)	- scheduleOnce:delay:
(void)	- unschedule:
(void)	- unscheduleAllSelectors
(void)	- resumeSchedulerAndActions
(void)	- pauseSchedulerAndActions
(void)	- update:
(CGAffineTransform)	- nodeToParentTransform
(CGAffineTransform)	- parentToNodeTransform
(CGAffineTransform)	- nodeToWorldTransform
(CGAffineTransform)	- worldToNodeTransform
(CGPoint)	- convertToNodeSpace:
(CGPoint)	- convertToWorldSpace:
(CGPoint)	- convertToNodeSpaceAR:
(CGPoint)	- convertToWorldSpaceAR:
(CGPoint)	- convertTouchToNodeSpace:
(CGPoint)	- convertTouchToNodeSpaceAR:
(void)	- setIsRelativeAnchorPoint:
(void)	- setZOrder:
Instance Methods inherited from <CCRGBAProtocol>
(void)	- updateDisplayedColor:
(void)	- updateDisplayedOpacity:
(void)	- setOpacityModifyRGB:
(BOOL)	- doesOpacityModifyRGB
Instance Methods inherited from <CCTextureProtocol>
(CCTexture2D *)	- texture
(void)	- setTexture:
Instance Methods inherited from <CCBlendProtocol>
(void)	- setBlendFunc:
(ccBlendFunc)	- blendFunc

Class Methods
(id)	+ spriteWithTexture:
(id)	+ spriteWithTexture:rect:
(id)	+ spriteWithSpriteFrame:
(id)	+ spriteWithSpriteFrameName:
(id)	+ spriteWithFile:
(id)	+ spriteWithFile:rect:
(id)	+ spriteWithCGImage:key:
(id)	+ spriteWithBatchNode:rect:

Protected Attributes
CCTextureAtlas *	_textureAtlas
NSUInteger	_atlasIndex
CCSpriteBatchNode *	_batchNode
CGAffineTransform	_transformToBatch
BOOL	_dirty
BOOL	_recursiveDirty
BOOL	_hasChildren
BOOL	_shouldBeHidden
ccBlendFunc	_blendFunc
CCTexture2D *	_texture
CGRect	_rect
BOOL	_rectRotated
CGPoint	_offsetPosition
CGPoint	_unflippedOffsetPositionFromCenter
ccV3F_C4B_T2F_Quad	_quad
BOOL	_opacityModifyRGB
BOOL	_flipX
BOOL	_flipY
Protected Attributes inherited from CCNodeRGBA
GLubyte	_displayedOpacity
GLubyte	_realOpacity
ccColor3B	_displayedColor
ccColor3B	_realColor
BOOL	_cascadeColorEnabled
BOOL	_cascadeOpacityEnabled
Protected Attributes inherited from CCNode
float	_rotationX
float	_rotationY
float	_scaleX
float	_scaleY
float	_vertexZ
CGPoint	_position
float	_skewX
float	_skewY
CGPoint	_anchorPointInPoints
CGPoint	_anchorPoint
CGSize	_contentSize
CGAffineTransform	_transform
CGAffineTransform	_inverse
BOOL	_isTransformDirty
BOOL	_isInverseDirty
CCCamera *	_camera
CCGridBase *	_grid
NSInteger	_zOrder
CCArray *	_children
CCNode *	_parent
NSInteger	_tag
void *	_userData
id	_userObject
CCGLProgram *	_shaderProgram
ccGLServerState	_glServerState
NSUInteger	_orderOfArrival
CCScheduler *	_scheduler
CCActionManager *	_actionManager
BOOL	_isRunning
BOOL	_visible
BOOL	_ignoreAnchorPointForPosition
BOOL	_isReorderChildDirty

Properties
BOOL	dirty
ccV3F_C4B_T2F_Quad	quad
NSUInteger	atlasIndex
CGRect	textureRect
BOOL	textureRectRotated
BOOL	flipX
BOOL	flipY
CCTextureAtlas *	textureAtlas
CCSpriteBatchNode *	batchNode
CGPoint	offsetPosition
ccBlendFunc	blendFunc

Detailed Description

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

Method Documentation

- (CCSpriteFrame*) displayFrame

returns the current displayed frame.

- (id) initWithCGImage:		(CGImageRef)	image
key:		(NSString *)	key

Initializes an sprite with a CGImageRef and a key The key is used by the CCTextureCache to know if a texture was already created with this CGImage. For example, a valid key is: "_spriteframe_01". If key is nil, then a new texture will be created each time by the CCTextureCache.

Since

v0.99.0

- (id) initWithFile:

(NSString *)

filename

Initializes an sprite with an image filename. The rect used will be the size of the image. The offset will be (0,0).

- (id) initWithFile:		(NSString *)	filename
rect:		(CGRect)	rect

Initializes an sprite with an image filename, and a rect. The offset will be (0,0).

- (id) initWithSpriteFrame:

(CCSpriteFrame *)

spriteFrame

Initializes an sprite with an sprite frame.

- (id) initWithSpriteFrameName:

(NSString *)

spriteFrameName

Initializes an sprite with an sprite frame name. An CCSpriteFrame will be fetched from the CCSpriteFrameCache by name. If the CCSpriteFrame doesn't exist it will raise an exception.

Since

v0.9

- (id) initWithTexture:

(CCTexture2D *)

texture

Initializes an sprite with a texture. The rect used will be the size of the texture. The offset will be (0,0).

- (id) initWithTexture:		(CCTexture2D *)	texture
rect:		(CGRect)	rect

Initializes an sprite with a texture and a rect in points (unrotated) The offset will be (0,0).

- (id) initWithTexture:		(CCTexture2D *)	texture
rect:		(CGRect)	rect
rotated:		(BOOL)	rotated

Initializes an sprite with a texture and a rect in points, optionally rotated. The offset will be (0,0). IMPORTANT: This is the designated initializer.

- (BOOL) isFrameDisplayed:

(CCSpriteFrame *)

frame

returns whether or not a CCSpriteFrame is being displayed

- (void) setDisplayFrame:

(CCSpriteFrame *)

newFrame

sets a new display frame to the CCSprite.

- (void) setDisplayFrameWithAnimationName:		(NSString *)	animationName
index:		(int)	frameIndex

changes the display frame with animation name and index. The animation name will be get from the CCAnimationCache

Since

v0.99.5

- (void) setTextureRect:

(CGRect)

rect

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

- (void) setTextureRect:		(CGRect)	rect
rotated:		(BOOL)	rotated
untrimmedSize:		(CGSize)	size

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

- (void) setVertexRect:

(CGRect)

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.

+ (id) spriteWithCGImage:		(CGImageRef)	image
key:		(NSString *)	key

Creates an sprite with a CGImageRef and a key. The key is used by the CCTextureCache to know if a texture was already created with this CGImage. For example, a valid key is: "_spriteframe_01". If key is nil, then a new texture will be created each time by the CCTextureCache.

Since

v0.99.0

+ (id) spriteWithFile:

(NSString *)

filename

Creates an sprite with an image filename. The rect used will be the size of the image. The offset will be (0,0).

+ (id) spriteWithFile:		(NSString *)	filename
rect:		(CGRect)	rect

Creates an sprite with an image filename and a rect. The offset will be (0,0).

+ (id) spriteWithSpriteFrame:

(CCSpriteFrame *)

spriteFrame

Creates an sprite with an sprite frame.

+ (id) spriteWithSpriteFrameName:

(NSString *)

spriteFrameName

Creates an sprite with an sprite frame name. An CCSpriteFrame will be fetched from the CCSpriteFrameCache by name. If the CCSpriteFrame doesn't exist it will raise an exception.

Since

v0.9

+ (id) spriteWithTexture:

(CCTexture2D *)

texture

Creates an sprite with a texture. The rect used will be the size of the texture. The offset will be (0,0).

+ (id) spriteWithTexture:		(CCTexture2D *)	texture
rect:		(CGRect)	rect

Creates an sprite with a texture and a rect. The offset will be (0,0).

- (void) updateTransform

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

Property Documentation

- (NSUInteger) atlasIndex

readwritenonatomicassign

The index used on the TextureAtlas. Don't modify this value unless you know what you are doing

- (CCSpriteBatchNode*) batchNode

readwritenonatomicassign

weak reference to the CCSpriteBatchNode that renders the CCSprite

- (ccBlendFunc) blendFunc

readwritenonatomicassign

conforms to CCTextureProtocol protocol

- (BOOL) dirty

readwritenonatomicassign

whether or not the Sprite needs to be updated in the Atlas

- (BOOL) flipX

readwritenonatomicassign

whether or not the sprite is flipped horizontally. 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.scaleX *= -1;

- (BOOL) flipY

readwritenonatomicassign

whether or not the sprite is flipped vertically. 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.scaleY *= -1;

- (CGPoint) offsetPosition

readnonatomicassign

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

Since

v0.99.0

- (ccV3F_C4B_T2F_Quad) quad

readnonatomicassign

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

- (CCTextureAtlas*) textureAtlas

readwritenonatomicassign

weak reference of the CCTextureAtlas used when the sprite is rendered using a CCSpriteBatchNode

- (CGRect) textureRect

readnonatomicassign

returns the texture rect of the CCSprite in points

- (BOOL) textureRectRotated

readnonatomicassign

returns whether or not the texture rectangle is rotated

---

The documentation for this class was generated from the following file:

• CCSprite.h