summary refs log tree commit diff stats
path: root/libs/cocos2d/CCNode.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/CCNode.h
downloadcartcollect-9cd57b731ab1c666d4a1cb725538fdc137763d12.tar.gz
cartcollect-9cd57b731ab1c666d4a1cb725538fdc137763d12.tar.bz2
cartcollect-9cd57b731ab1c666d4a1cb725538fdc137763d12.zip
Initial commit (version 0.2.1)
Diffstat (limited to 'libs/cocos2d/CCNode.h')
-rwxr-xr-xlibs/cocos2d/CCNode.h529
1 files changed, 529 insertions, 0 deletions
diff --git a/libs/cocos2d/CCNode.h b/libs/cocos2d/CCNode.h new file mode 100755 index 0000000..64acdc5 --- /dev/null +++ b/libs/cocos2d/CCNode.h
@@ -0,0 +1,529 @@
1/*
2 * cocos2d for iPhone: http://www.cocos2d-iphone.org
3 *
4 * Copyright (c) 2009 Valentin Milea
5 *
6 * Copyright (c) 2008-2010 Ricardo Quesada
7 * Copyright (c) 2011 Zynga Inc.
8 *
9 * Permission is hereby granted, free of charge, to any person obtaining a copy
10 * of this software and associated documentation files (the "Software"), to deal
11 * in the Software without restriction, including without limitation the rights
12 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13 * copies of the Software, and to permit persons to whom the Software is
14 * furnished to do so, subject to the following conditions:
15 *
16 * The above copyright notice and this permission notice shall be included in
17 * all copies or substantial portions of the Software.
18 *
19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25 * THE SOFTWARE.
26 */
27
28#import <Availability.h>
29
30#import "Platforms/CCGL.h"
31#import "CCAction.h"
32#import "ccTypes.h"
33#import "CCTexture2D.h"
34#import "CCProtocols.h"
35#import "ccConfig.h"
36#import "Support/CCArray.h"
37
38enum {
39 kCCNodeTagInvalid = -1,
40};
41
42@class CCCamera;
43@class CCGridBase;
44
45/** CCNode is the main element. Anything thats gets drawn or contains things that get drawn is a CCNode.
46 The most popular CCNodes are: CCScene, CCLayer, CCSprite, CCMenu.
47
48 The main features of a CCNode are:
49 - They can contain other CCNode nodes (addChild, getChildByTag, removeChild, etc)
50 - They can schedule periodic callback (schedule, unschedule, etc)
51 - They can execute actions (runAction, stopAction, etc)
52
53 Some CCNode nodes provide extra functionality for them or their children.
54
55 Subclassing a CCNode usually means (one/all) of:
56 - overriding init to initialize resources and schedule callbacks
57 - create callbacks to handle the advancement of time
58 - overriding draw to render the node
59
60 Features of CCNode:
61 - position
62 - scale (x, y)
63 - rotation (in degrees, clockwise)
64 - CCCamera (an interface to gluLookAt )
65 - CCGridBase (to do mesh transformations)
66 - anchor point
67 - size
68 - visible
69 - z-order
70 - openGL z position
71
72 Default values:
73 - rotation: 0
74 - position: (x=0,y=0)
75 - scale: (x=1,y=1)
76 - contentSize: (x=0,y=0)
77 - anchorPoint: (x=0,y=0)
78
79 Limitations:
80 - A CCNode is a "void" object. It doesn't have a texture
81
82 Order in transformations with grid disabled
83 -# The node will be translated (position)
84 -# The node will be rotated (rotation)
85 -# The node will be scaled (scale)
86 -# The node will be moved according to the camera values (camera)
87
88 Order in transformations with grid enabled
89 -# The node will be translated (position)
90 -# The node will be rotated (rotation)
91 -# The node will be scaled (scale)
92 -# The grid will capture the screen
93 -# The node will be moved according to the camera values (camera)
94 -# The grid will render the captured screen
95
96 Camera:
97 - Each node has a camera. By default it points to the center of the CCNode.
98 */
99@interface CCNode : NSObject
100{
101 // rotation angle
102 float rotation_;
103
104 // scaling factors
105 float scaleX_, scaleY_;
106
107 // position of the node
108 CGPoint position_;
109 CGPoint positionInPixels_;
110
111 // skew angles
112 float skewX_, skewY_;
113
114 // is visible
115 BOOL visible_;
116
117 // anchor point in pixels
118 CGPoint anchorPointInPixels_;
119 // anchor point normalized
120 CGPoint anchorPoint_;
121 // If YES the transformtions will be relative to (-transform.x, -transform.y).
122 // Sprites, Labels and any other "small" object uses it.
123 // Scenes, Layers and other "whole screen" object don't use it.
124 BOOL isRelativeAnchorPoint_;
125
126 // untransformed size of the node
127 CGSize contentSize_;
128 CGSize contentSizeInPixels_;
129
130 // transform
131 CGAffineTransform transform_, inverse_;
132#if CC_NODE_TRANSFORM_USING_AFFINE_MATRIX
133 GLfloat transformGL_[16];
134#endif
135
136 // openGL real Z vertex
137 float vertexZ_;
138
139 // a Camera
140 CCCamera *camera_;
141
142 // a Grid
143 CCGridBase *grid_;
144
145 // z-order value
146 NSInteger zOrder_;
147
148 // array of children
149 CCArray *children_;
150
151 // weakref to parent
152 CCNode *parent_;
153
154 // a tag. any number you want to assign to the node
155 NSInteger tag_;
156
157 // user data field
158 void *userData_;
159
160 // Is running
161 BOOL isRunning_;
162
163 // To reduce memory, place BOOLs that are not properties here:
164 BOOL isTransformDirty_:1;
165 BOOL isInverseDirty_:1;
166#if CC_NODE_TRANSFORM_USING_AFFINE_MATRIX
167 BOOL isTransformGLDirty_:1;
168#endif
169}
170
171/** The z order of the node relative to it's "brothers": children of the same parent */
172@property(nonatomic,readonly) NSInteger zOrder;
173/** The real openGL Z vertex.
174 Differences between openGL Z vertex and cocos2d Z order:
175 - OpenGL Z modifies the Z vertex, and not the Z order in the relation between parent-children
176 - OpenGL Z might require to set 2D projection
177 - cocos2d Z order works OK if all the nodes uses the same openGL Z vertex. eg: vertexZ = 0
178 @warning: Use it at your own risk since it might break the cocos2d parent-children z order
179 @since v0.8
180 */
181@property (nonatomic,readwrite) float vertexZ;
182
183/** The X skew angle of the node in degrees.
184 This angle describes the shear distortion in the X direction.
185 Thus, it is the angle between the Y axis and the left edge of the shape
186 The default skewX angle is 0. Positive values distort the node in a CW direction.
187 */
188@property(nonatomic,readwrite,assign) float skewX;
189
190/** The Y skew angle of the node in degrees.
191 This angle describes the shear distortion in the Y direction.
192 Thus, it is the angle between the X axis and the bottom edge of the shape
193 The default skewY angle is 0. Positive values distort the node in a CCW direction.
194 */
195@property(nonatomic,readwrite,assign) float skewY;
196/** The rotation (angle) of the node in degrees. 0 is the default rotation angle. Positive values rotate node CW. */
197@property(nonatomic,readwrite,assign) float rotation;
198/** The scale factor of the node. 1.0 is the default scale factor. It modifies the X and Y scale at the same time. */
199@property(nonatomic,readwrite,assign) float scale;
200/** The scale factor of the node. 1.0 is the default scale factor. It only modifies the X scale factor. */
201@property(nonatomic,readwrite,assign) float scaleX;
202/** The scale factor of the node. 1.0 is the default scale factor. It only modifies the Y scale factor. */
203@property(nonatomic,readwrite,assign) float scaleY;
204/** Position (x,y) of the node in points. (0,0) is the left-bottom corner. */
205@property(nonatomic,readwrite,assign) CGPoint position;
206/** Position (x,y) of the node in points. (0,0) is the left-bottom corner. */
207@property(nonatomic,readwrite,assign) CGPoint positionInPixels;
208/** A CCCamera object that lets you move the node using a gluLookAt
209*/
210@property(nonatomic,readonly) CCCamera* camera;
211/** Array of children */
212@property(nonatomic,readonly) CCArray *children;
213/** A CCGrid object that is used when applying effects */
214@property(nonatomic,readwrite,retain) CCGridBase* grid;
215/** Whether of not the node is visible. Default is YES */
216@property(nonatomic,readwrite,assign) BOOL visible;
217/** anchorPoint is the point around which all transformations and positioning manipulations take place.
218 It's like a pin in the node where it is "attached" to its parent.
219 The anchorPoint is normalized, like a percentage. (0,0) means the bottom-left corner and (1,1) means the top-right corner.
220 But you can use values higher than (1,1) and lower than (0,0) too.
221 The default anchorPoint is (0,0). It starts in the bottom-left corner. CCSprite and other subclasses have a different default anchorPoint.
222 @since v0.8
223 */
224@property(nonatomic,readwrite) CGPoint anchorPoint;
225/** The anchorPoint in absolute pixels.
226 Since v0.8 you can only read it. If you wish to modify it, use anchorPoint instead
227 */
228@property(nonatomic,readonly) CGPoint anchorPointInPixels;
229
230/** The untransformed size of the node in Points
231 The contentSize remains the same no matter the node is scaled or rotated.
232 All nodes has a size. Layer and Scene has the same size of the screen.
233 @since v0.8
234 */
235@property (nonatomic,readwrite) CGSize contentSize;
236
237/** The untransformed size of the node in Pixels
238 The contentSize remains the same no matter the node is scaled or rotated.
239 All nodes has a size. Layer and Scene has the same size of the screen.
240 @since v0.8
241 */
242@property (nonatomic,readwrite) CGSize contentSizeInPixels;
243
244/** whether or not the node is running */
245@property(nonatomic,readonly) BOOL isRunning;
246/** A weak reference to the parent */
247@property(nonatomic,readwrite,assign) CCNode* parent;
248/** If YES the transformtions will be relative to it's anchor point.
249 * Sprites, Labels and any other sizeble object use it have it enabled by default.
250 * Scenes, Layers and other "whole screen" object don't use it, have it disabled by default.
251 */
252@property(nonatomic,readwrite,assign) BOOL isRelativeAnchorPoint;
253/** A tag used to identify the node easily */
254@property(nonatomic,readwrite,assign) NSInteger tag;
255/** A custom user data pointer */
256@property(nonatomic,readwrite,assign) void *userData;
257
258// initializators
259/** allocates and initializes a node.
260 The node will be created as "autorelease".
261 */
262+(id) node;
263/** initializes the node */
264-(id) init;
265
266
267// scene managment
268
269/** callback that is called every time the CCNode enters the 'stage'.
270 If the CCNode enters the 'stage' with a transition, this callback is called when the transition starts.
271 During onEnter you can't a "sister/brother" node.
272 */
273-(void) onEnter;
274/** callback that is called when the CCNode enters in the 'stage'.
275 If the CCNode enters the 'stage' with a transition, this callback is called when the transition finishes.
276 @since v0.8
277 */
278-(void) onEnterTransitionDidFinish;
279/** callback that is called every time the CCNode leaves the 'stage'.
280 If the CCNode leaves the 'stage' with a transition, this callback is called when the transition finishes.
281 During onExit you can't access a sibling node.
282 */
283-(void) onExit;
284
285
286// composition: ADD
287
288/** Adds a child to the container with z-order as 0.
289 If the child is added to a 'running' node, then 'onEnter' and 'onEnterTransitionDidFinish' will be called immediately.
290 @since v0.7.1
291 */
292-(void) addChild: (CCNode*)node;
293
294/** Adds a child to the container with a z-order.
295 If the child is added to a 'running' node, then 'onEnter' and 'onEnterTransitionDidFinish' will be called immediately.
296 @since v0.7.1
297 */
298-(void) addChild: (CCNode*)node z:(NSInteger)z;
299
300/** Adds a child to the container with z order and tag.
301 If the child is added to a 'running' node, then 'onEnter' and 'onEnterTransitionDidFinish' will be called immediately.
302 @since v0.7.1
303 */
304-(void) addChild: (CCNode*)node z:(NSInteger)z tag:(NSInteger)tag;
305
306// composition: REMOVE
307
308/** Remove itself from its parent node. If cleanup is YES, then also remove all actions and callbacks.
309 If the node orphan, then nothing happens.
310 @since v0.99.3
311 */
312-(void) removeFromParentAndCleanup:(BOOL)cleanup;
313
314/** Removes a child from the container. It will also cleanup all running actions depending on the cleanup parameter.
315 @since v0.7.1
316 */
317-(void) removeChild: (CCNode*)node cleanup:(BOOL)cleanup;
318
319/** Removes a child from the container by tag value. It will also cleanup all running actions depending on the cleanup parameter
320 @since v0.7.1
321 */
322-(void) removeChildByTag:(NSInteger) tag cleanup:(BOOL)cleanup;
323
324/** Removes all children from the container and do a cleanup all running actions depending on the cleanup parameter.
325 @since v0.7.1
326 */
327-(void) removeAllChildrenWithCleanup:(BOOL)cleanup;
328
329// composition: GET
330/** Gets a child from the container given its tag
331 @return returns a CCNode object
332 @since v0.7.1
333 */
334-(CCNode*) getChildByTag:(NSInteger) tag;
335
336/** Reorders a child according to a new z value.
337 * The child MUST be already added.
338 */
339-(void) reorderChild:(CCNode*)child z:(NSInteger)zOrder;
340
341/** Stops all running actions and schedulers
342 @since v0.8
343 */
344-(void) cleanup;
345
346// draw
347
348/** Override this method to draw your own node.
349 The following GL states will be enabled by default:
350 - glEnableClientState(GL_VERTEX_ARRAY);
351 - glEnableClientState(GL_COLOR_ARRAY);
352 - glEnableClientState(GL_TEXTURE_COORD_ARRAY);
353 - glEnable(GL_TEXTURE_2D);
354
355 AND YOU SHOULD NOT DISABLE THEM AFTER DRAWING YOUR NODE
356
357 But if you enable any other GL state, you should disable it after drawing your node.
358 */
359-(void) draw;
360/** recursive method that visit its children and draw them */
361-(void) visit;
362
363// transformations
364
365/** performs OpenGL view-matrix transformation based on position, scale, rotation and other attributes. */
366-(void) transform;
367
368/** performs OpenGL view-matrix transformation of it's ancestors.
369 Generally the ancestors are already transformed, but in certain cases (eg: attaching a FBO)
370 it's necessary to transform the ancestors again.
371 @since v0.7.2
372 */
373-(void) transformAncestors;
374
375/** returns a "local" axis aligned bounding box of the node in points.
376 The returned box is relative only to its parent.
377 The returned box is in Points.
378
379 @since v0.8.2
380 */
381- (CGRect) boundingBox;
382
383/** returns a "local" axis aligned bounding box of the node in pixels.
384 The returned box is relative only to its parent.
385 The returned box is in Points.
386
387 @since v0.99.5
388 */
389- (CGRect) boundingBoxInPixels;
390
391
392// actions
393
394/** Executes an action, and returns the action that is executed.
395 The node becomes the action's target.
396 @warning Starting from v0.8 actions don't retain their target anymore.
397 @since v0.7.1
398 @return An Action pointer
399 */
400-(CCAction*) runAction: (CCAction*) action;
401/** Removes all actions from the running action list */
402-(void) stopAllActions;
403/** Removes an action from the running action list */
404-(void) stopAction: (CCAction*) action;
405/** Removes an action from the running action list given its tag
406 @since v0.7.1
407*/
408-(void) stopActionByTag:(NSInteger) tag;
409/** Gets an action from the running action list given its tag
410 @since v0.7.1
411 @return the Action the with the given tag
412 */
413-(CCAction*) getActionByTag:(NSInteger) tag;
414/** Returns the numbers of actions that are running plus the ones that are schedule to run (actions in actionsToAdd and actions arrays).
415 * Composable actions are counted as 1 action. Example:
416 * If you are running 1 Sequence of 7 actions, it will return 1.
417 * If you are running 7 Sequences of 2 actions, it will return 7.
418 */
419-(NSUInteger) numberOfRunningActions;
420
421// timers
422
423/** check whether a selector is scheduled. */
424//-(BOOL) isScheduled: (SEL) selector;
425
426/** schedules the "update" method. It will use the order number 0. This method will be called every frame.
427 Scheduled methods with a lower order value will be called before the ones that have a higher order value.
428 Only one "udpate" method could be scheduled per node.
429
430 @since v0.99.3
431 */
432-(void) scheduleUpdate;
433
434/** schedules the "update" selector with a custom priority. This selector will be called every frame.
435 Scheduled selectors with a lower priority will be called before the ones that have a higher value.
436 Only one "udpate" selector could be scheduled per node (You can't have 2 'update' selectors).
437
438 @since v0.99.3
439 */
440-(void) scheduleUpdateWithPriority:(NSInteger)priority;
441
442/* unschedules the "update" method.
443
444 @since v0.99.3
445 */
446-(void) unscheduleUpdate;
447
448
449/** schedules a selector.
450 The scheduled selector will be ticked every frame
451 */
452-(void) schedule: (SEL) s;
453/** schedules a custom selector with an interval time in seconds.
454 If time is 0 it will be ticked every frame.
455 If time is 0, it is recommended to use 'scheduleUpdate' instead.
456
457 If the selector is already scheduled, then the interval parameter will be updated without scheduling it again.
458 */
459-(void) schedule: (SEL) s interval:(ccTime)seconds;
460/** unschedules a custom selector.*/
461-(void) unschedule: (SEL) s;
462
463/** unschedule all scheduled selectors: custom selectors, and the 'update' selector.
464 Actions are not affected by this method.
465@since v0.99.3
466 */
467-(void) unscheduleAllSelectors;
468
469/** resumes all scheduled selectors and actions.
470 Called internally by onEnter
471 */
472-(void) resumeSchedulerAndActions;
473/** pauses all scheduled selectors and actions.
474 Called internally by onExit
475 */
476-(void) pauseSchedulerAndActions;
477
478
479// transformation methods
480
481/** Returns the matrix that transform the node's (local) space coordinates into the parent's space coordinates.
482 The matrix is in Pixels.
483 @since v0.7.1
484 */
485- (CGAffineTransform)nodeToParentTransform;
486/** Returns the matrix that transform parent's space coordinates to the node's (local) space coordinates.
487 The matrix is in Pixels.
488 @since v0.7.1
489 */
490- (CGAffineTransform)parentToNodeTransform;
491/** Retrusn the world affine transform matrix. The matrix is in Pixels.
492 @since v0.7.1
493 */
494- (CGAffineTransform)nodeToWorldTransform;
495/** Returns the inverse world affine transform matrix. The matrix is in Pixels.
496 @since v0.7.1
497 */
498- (CGAffineTransform)worldToNodeTransform;
499/** Converts a Point to node (local) space coordinates. The result is in Points.
500 @since v0.7.1
501 */
502- (CGPoint)convertToNodeSpace:(CGPoint)worldPoint;
503/** Converts a Point to world space coordinates. The result is in Points.
504 @since v0.7.1
505 */
506- (CGPoint)convertToWorldSpace:(CGPoint)nodePoint;
507/** Converts a Point to node (local) space coordinates. The result is in Points.
508 treating the returned/received node point as anchor relative.
509 @since v0.7.1
510 */
511- (CGPoint)convertToNodeSpaceAR:(CGPoint)worldPoint;
512/** Converts a local Point to world space coordinates.The result is in Points.
513 treating the returned/received node point as anchor relative.
514 @since v0.7.1
515 */
516- (CGPoint)convertToWorldSpaceAR:(CGPoint)nodePoint;
517
518#ifdef __IPHONE_OS_VERSION_MAX_ALLOWED
519/** Converts a UITouch to node (local) space coordinates. The result is in Points.
520 @since v0.7.1
521 */
522- (CGPoint)convertTouchToNodeSpace:(UITouch *)touch;
523/** Converts a UITouch to node (local) space coordinates. The result is in Points.
524 This method is AR (Anchor Relative)..
525 @since v0.7.1
526 */
527- (CGPoint)convertTouchToNodeSpaceAR:(UITouch *)touch;
528#endif // __IPHONE_OS_VERSION_MAX_ALLOWED
529@end