cocos2d-iphone  2.1
Improved Cocos2D API Reference (iOS version) for www.kobold2d.com developers
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Properties Macros Pages
Instance Methods | Class Methods | Protected Attributes | Properties | List of all members
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 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) - setColor:
 
(ccColor3B) - color
 
(GLubyte) - opacity
 returns the opacity
 
(void) - setOpacity:
 
(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:
 
 Class Methods inherited from CCNode
(id) + node
 

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_
 
GLubyte opacity_
 
ccColor3B color_
 
ccColor3B colorUnmodified_
 
BOOL opacityModifyRGB_
 
BOOL flipX_
 
BOOL flipY_
 
 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_
 
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 isTransformDirty_
 
BOOL isInverseDirty_
 
BOOL visible_
 
BOOL ignoreAnchorPointForPosition_
 
BOOL isReorderChildDirty_
 

Properties

BOOL dirty
 
ccV3F_C4B_T2F_Quad quad
 
NSUInteger atlasIndex
 
CGRect textureRect
 
BOOL textureRectRotated
 
BOOL flipX
 
BOOL flipY
 
GLubyte opacity
 
ccColor3B color
 
CCTextureAtlas * textureAtlas
 
CCSpriteBatchNode * batchNode
 
CGPoint offsetPosition
 
ccBlendFunc blendFunc
 
 Properties inherited from CCNode
NSInteger zOrder
 
float vertexZ
 
float skewX
 
float skewY
 
float rotation
 
float rotationX
 
float rotationY
 
float scale
 
float scaleX
 
float scaleY
 
CGPoint position
 
CCCamera * camera
 
CCArray * children
 
CCGridBase * grid
 
BOOL visible
 
CGPoint anchorPoint
 
CGPoint anchorPointInPoints
 
CGSize contentSize
 
BOOL isRunning
 
CCNode * parent
 
BOOL ignoreAnchorPointForPosition
 
NSInteger tag
 
void * userData
 
id userObject
 
CCGLProgram * shaderProgram
 
NSUInteger orderOfArrival
 
ccGLServerState glServerState
 
CCActionManager * actionManager
 
CCScheduler * scheduler
 

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: "sprite_frame_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: "sprite_frame_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

- (ccColor3B) color
readwritenonatomicassign

RGB colors: conforms to CCRGBAProtocol 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
- (GLubyte) opacity
readwritenonatomicassign

opacity: conforms to CCRGBAProtocol protocol

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