summary refs log tree commit diff stats
path: root/libs/cocos2d/CCSprite.h
diff options
context:
space:
mode:
authorStarla Insigna <starla4444@gmail.com>2011-07-30 11:19:14 -0400
committerStarla Insigna <starla4444@gmail.com>2011-07-30 11:19:14 -0400
commit9cd57b731ab1c666d4a1cb725538fdc137763d12 (patch)
tree5bac45ae5157a1cb10c6e45500cbf72789917980 /libs/cocos2d/CCSprite.h
downloadcartcollect-9cd57b731ab1c666d4a1cb725538fdc137763d12.tar.gz
cartcollect-9cd57b731ab1c666d4a1cb725538fdc137763d12.tar.bz2
cartcollect-9cd57b731ab1c666d4a1cb725538fdc137763d12.zip
Initial commit (version 0.2.1)
Diffstat (limited to 'libs/cocos2d/CCSprite.h')
-rwxr-xr-xlibs/cocos2d/CCSprite.h351
1 files changed, 351 insertions, 0 deletions
diff --git a/libs/cocos2d/CCSprite.h b/libs/cocos2d/CCSprite.h new file mode 100755 index 0000000..f01688e --- /dev/null +++ b/libs/cocos2d/CCSprite.h
@@ -0,0 +1,351 @@
1/*
2 * cocos2d for iPhone: http://www.cocos2d-iphone.org
3 *
4 * Copyright (c) 2008-2010 Ricardo Quesada
5 * Copyright (c) 2011 Zynga Inc.
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
23 * THE SOFTWARE.
24 *
25 */
26
27
28#import "CCNode.h"
29#import "CCProtocols.h"
30#import "CCTextureAtlas.h"
31
32@class CCSpriteBatchNode;
33@class CCSpriteFrame;
34@class CCAnimation;
35
36#pragma mark CCSprite
37
38#define CCSpriteIndexNotInitialized 0xffffffff /// CCSprite invalid index on the CCSpriteBatchode
39
40/**
41 Whether or not an CCSprite will rotate, scale or translate with it's parent.
42 Useful in health bars, when you want that the health bar translates with it's parent but you don't
43 want it to rotate with its parent.
44 @since v0.99.0
45 */
46typedef enum {
47 //! Translate with it's parent
48 CC_HONOR_PARENT_TRANSFORM_TRANSLATE = 1 << 0,
49 //! Rotate with it's parent
50 CC_HONOR_PARENT_TRANSFORM_ROTATE = 1 << 1,
51 //! Scale with it's parent
52 CC_HONOR_PARENT_TRANSFORM_SCALE = 1 << 2,
53 //! Skew with it's parent
54 CC_HONOR_PARENT_TRANSFORM_SKEW = 1 << 3,
55
56 //! All possible transformation enabled. Default value.
57 CC_HONOR_PARENT_TRANSFORM_ALL = CC_HONOR_PARENT_TRANSFORM_TRANSLATE | CC_HONOR_PARENT_TRANSFORM_ROTATE | CC_HONOR_PARENT_TRANSFORM_SCALE | CC_HONOR_PARENT_TRANSFORM_SKEW,
58
59} ccHonorParentTransform;
60
61/** CCSprite is a 2d image ( http://en.wikipedia.org/wiki/Sprite_(computer_graphics) )
62 *
63 * CCSprite can be created with an image, or with a sub-rectangle of an image.
64 *
65 * If the parent or any of its ancestors is a CCSpriteBatchNode then the following features/limitations are valid
66 * - Features when the parent is a CCBatchNode:
67 * - MUCH faster rendering, specially if the CCSpriteBatchNode has many children. All the children will be drawn in a single batch.
68 *
69 * - Limitations
70 * - Camera is not supported yet (eg: CCOrbitCamera action doesn't work)
71 * - GridBase actions are not supported (eg: CCLens, CCRipple, CCTwirl)
72 * - The Alias/Antialias property belongs to CCSpriteBatchNode, so you can't individually set the aliased property.
73 * - The Blending function property belongs to CCSpriteBatchNode, so you can't individually set the blending function property.
74 * - Parallax scroller is not supported, but can be simulated with a "proxy" sprite.
75 *
76 * If the parent is an standard CCNode, then CCSprite behaves like any other CCNode:
77 * - It supports blending functions
78 * - It supports aliasing / antialiasing
79 * - But the rendering will be slower: 1 draw per children.
80 *
81 * The default anchorPoint in CCSprite is (0.5, 0.5).
82 */
83@interface CCSprite : CCNode <CCRGBAProtocol, CCTextureProtocol>
84{
85
86 //
87 // Data used when the sprite is rendered using a CCSpriteBatchNode
88 //
89 CCTextureAtlas *textureAtlas_; // Sprite Sheet texture atlas (weak reference)
90 NSUInteger atlasIndex_; // Absolute (real) Index on the batch node
91 CCSpriteBatchNode *batchNode_; // Used batch node (weak reference)
92 ccHonorParentTransform honorParentTransform_; // whether or not to transform according to its parent transformations
93 BOOL dirty_; // Sprite needs to be updated
94 BOOL recursiveDirty_; // Subchildren needs to be updated
95 BOOL hasChildren_; // optimization to check if it contain children
96
97 //
98 // Data used when the sprite is self-rendered
99 //
100 ccBlendFunc blendFunc_; // Needed for the texture protocol
101 CCTexture2D *texture_; // Texture used to render the sprite
102
103 //
104 // Shared data
105 //
106
107 // whether or not it's parent is a CCSpriteBatchNode
108 BOOL usesBatchNode_;
109
110 // texture
111 CGRect rect_;
112 CGRect rectInPixels_;
113 BOOL rectRotated_;
114
115 // Offset Position (used by Zwoptex)
116 CGPoint offsetPositionInPixels_;
117 CGPoint unflippedOffsetPositionFromCenter_;
118
119 // vertex coords, texture coords and color info
120 ccV3F_C4B_T2F_Quad quad_;
121
122 // opacity and RGB protocol
123 GLubyte opacity_;
124 ccColor3B color_;
125 ccColor3B colorUnmodified_;
126 BOOL opacityModifyRGB_;
127
128 // image is flipped
129 BOOL flipX_;
130 BOOL flipY_;
131
132
133 // Animations that belong to the sprite
134 NSMutableDictionary *animations_;
135
136@public
137 // used internally.
138 void (*updateMethod)(id, SEL);
139}
140
141/** whether or not the Sprite needs to be updated in the Atlas */
142@property (nonatomic,readwrite) BOOL dirty;
143/** the quad (tex coords, vertex coords and color) information */
144@property (nonatomic,readonly) ccV3F_C4B_T2F_Quad quad;
145/** The index used on the TextureAtlas. Don't modify this value unless you know what you are doing */
146@property (nonatomic,readwrite) NSUInteger atlasIndex;
147/** returns the rect of the CCSprite in points */
148@property (nonatomic,readonly) CGRect textureRect;
149/** returns whether or not the texture rectangle is rotated */
150@property (nonatomic,readonly) BOOL textureRectRotated;
151/** whether or not the sprite is flipped horizontally.
152 It only flips the texture of the sprite, and not the texture of the sprite's children.
153 Also, flipping the texture doesn't alter the anchorPoint.
154 If you want to flip the anchorPoint too, and/or to flip the children too use:
155
156 sprite.scaleX *= -1;
157 */
158@property (nonatomic,readwrite) BOOL flipX;
159/** whether or not the sprite is flipped vertically.
160 It only flips the texture of the sprite, and not the texture of the sprite's children.
161 Also, flipping the texture doesn't alter the anchorPoint.
162 If you want to flip the anchorPoint too, and/or to flip the children too use:
163
164 sprite.scaleY *= -1;
165 */
166@property (nonatomic,readwrite) BOOL flipY;
167/** opacity: conforms to CCRGBAProtocol protocol */
168@property (nonatomic,readwrite) GLubyte opacity;
169/** RGB colors: conforms to CCRGBAProtocol protocol */
170@property (nonatomic,readwrite) ccColor3B color;
171/** whether or not the Sprite is rendered using a CCSpriteBatchNode */
172@property (nonatomic,readwrite) BOOL usesBatchNode;
173/** weak reference of the CCTextureAtlas used when the sprite is rendered using a CCSpriteBatchNode */
174@property (nonatomic,readwrite,assign) CCTextureAtlas *textureAtlas;
175/** weak reference to the CCSpriteBatchNode that renders the CCSprite */
176@property (nonatomic,readwrite,assign) CCSpriteBatchNode *batchNode;
177/** whether or not to transform according to its parent transfomrations.
178 Useful for health bars. eg: Don't rotate the health bar, even if the parent rotates.
179 IMPORTANT: Only valid if it is rendered using an CCSpriteBatchNode.
180 @since v0.99.0
181 */
182@property (nonatomic,readwrite) ccHonorParentTransform honorParentTransform;
183/** offset position in pixels of the sprite in points. Calculated automatically by editors like Zwoptex.
184 @since v0.99.0
185 */
186@property (nonatomic,readonly) CGPoint offsetPositionInPixels;
187/** conforms to CCTextureProtocol protocol */
188@property (nonatomic,readwrite) ccBlendFunc blendFunc;
189
190#pragma mark CCSprite - Initializers
191
192/** Creates an sprite with a texture.
193 The rect used will be the size of the texture.
194 The offset will be (0,0).
195 */
196+(id) spriteWithTexture:(CCTexture2D*)texture;
197
198/** Creates an sprite with a texture and a rect.
199 The offset will be (0,0).
200 */
201+(id) spriteWithTexture:(CCTexture2D*)texture rect:(CGRect)rect;
202
203/** Creates an sprite with an sprite frame.
204 */
205+(id) spriteWithSpriteFrame:(CCSpriteFrame*)spriteFrame;
206
207/** Creates an sprite with an sprite frame name.
208 An CCSpriteFrame will be fetched from the CCSpriteFrameCache by name.
209 If the CCSpriteFrame doesn't exist it will raise an exception.
210 @since v0.9
211 */
212+(id) spriteWithSpriteFrameName:(NSString*)spriteFrameName;
213
214/** Creates an sprite with an image filename.
215 The rect used will be the size of the image.
216 The offset will be (0,0).
217 */
218+(id) spriteWithFile:(NSString*)filename;
219
220/** Creates an sprite with an image filename and a rect.
221 The offset will be (0,0).
222 */
223+(id) spriteWithFile:(NSString*)filename rect:(CGRect)rect;
224
225/** Creates an sprite with a CGImageRef and a key.
226 The key is used by the CCTextureCache to know if a texture was already created with this CGImage.
227 For example, a valid key is: @"sprite_frame_01".
228 If key is nil, then a new texture will be created each time by the CCTextureCache.
229 @since v0.99.0
230 */
231+(id) spriteWithCGImage: (CGImageRef)image key:(NSString*)key;
232
233
234/** Creates an sprite with an CCBatchNode and a rect
235 */
236+(id) spriteWithBatchNode:(CCSpriteBatchNode*)batchNode rect:(CGRect)rect;
237
238
239/** Initializes an sprite with a texture.
240 The rect used will be the size of the texture.
241 The offset will be (0,0).
242 */
243-(id) initWithTexture:(CCTexture2D*)texture;
244
245/** Initializes an sprite with a texture and a rect in points.
246 The offset will be (0,0).
247 */
248-(id) initWithTexture:(CCTexture2D*)texture rect:(CGRect)rect;
249
250/** Initializes an sprite with an sprite frame.
251 */
252-(id) initWithSpriteFrame:(CCSpriteFrame*)spriteFrame;
253
254/** Initializes an sprite with an sprite frame name.
255 An CCSpriteFrame will be fetched from the CCSpriteFrameCache by name.
256 If the CCSpriteFrame doesn't exist it will raise an exception.
257 @since v0.9
258 */
259-(id) initWithSpriteFrameName:(NSString*)spriteFrameName;
260
261/** Initializes an sprite with an image filename.
262 The rect used will be the size of the image.
263 The offset will be (0,0).
264 */
265-(id) initWithFile:(NSString*)filename;
266
267/** Initializes an sprite with an image filename, and a rect.
268 The offset will be (0,0).
269 */
270-(id) initWithFile:(NSString*)filename rect:(CGRect)rect;
271
272/** Initializes an sprite with a CGImageRef and a key
273 The key is used by the CCTextureCache to know if a texture was already created with this CGImage.
274 For example, a valid key is: @"sprite_frame_01".
275 If key is nil, then a new texture will be created each time by the CCTextureCache.
276 @since v0.99.0
277 */
278-(id) initWithCGImage:(CGImageRef)image key:(NSString*)key;
279
280/** Initializes an sprite with an CCSpriteBatchNode and a rect in points
281 */
282-(id) initWithBatchNode:(CCSpriteBatchNode*)batchNode rect:(CGRect)rect;
283
284/** Initializes an sprite with an CCSpriteBatchNode and a rect in pixels
285 @since v0.99.5
286 */
287-(id) initWithBatchNode:(CCSpriteBatchNode*)batchNode rectInPixels:(CGRect)rect;
288
289
290
291#pragma mark CCSprite - BatchNode methods
292
293/** updates the quad according the the rotation, position, scale values.
294 */
295-(void)updateTransform;
296
297/** updates the texture rect of the CCSprite in points.
298 */
299-(void) setTextureRect:(CGRect) rect;
300/** updates the texture rect, rectRotated and untrimmed size of the CCSprite in pixels
301 */
302-(void) setTextureRectInPixels:(CGRect)rect rotated:(BOOL)rotated untrimmedSize:(CGSize)size;
303
304/** tell the sprite to use self-render.
305 @since v0.99.0
306 */
307-(void) useSelfRender;
308
309/** tell the sprite to use sprite batch node
310 @since v0.99.0
311 */
312-(void) useBatchNode:(CCSpriteBatchNode*)batchNode;
313
314
315#pragma mark CCSprite - Frames
316
317/** sets a new display frame to the CCSprite. */
318-(void) setDisplayFrame:(CCSpriteFrame*)newFrame;
319
320/** returns whether or not a CCSpriteFrame is being displayed */
321-(BOOL) isFrameDisplayed:(CCSpriteFrame*)frame;
322
323/** returns the current displayed frame. */
324-(CCSpriteFrame*) displayedFrame;
325
326#pragma mark CCSprite - Animation
327
328/** changes the display frame based on an animation and an index.
329 @deprecated Will be removed in 1.0.1. Use setDisplayFrameWithAnimationName:index instead
330 */
331-(void) setDisplayFrame: (NSString*) animationName index:(int) frameIndex DEPRECATED_ATTRIBUTE;
332
333/** changes the display frame with animation name and index.
334 The animation name will be get from the CCAnimationCache
335 @since v0.99.5
336 */
337-(void) setDisplayFrameWithAnimationName:(NSString*)animationName index:(int) frameIndex;
338
339/** returns an Animation given it's name.
340
341 @deprecated Use CCAnimationCache instead. Will be removed in 1.0.1
342 */
343-(CCAnimation*)animationByName: (NSString*) animationName DEPRECATED_ATTRIBUTE;
344
345/** adds an Animation to the Sprite.
346
347 @deprecated Use CCAnimationCache instead. Will be removed in 1.0.1
348 */
349-(void) addAnimation: (CCAnimation*) animation DEPRECATED_ATTRIBUTE;
350
351@end