/libs/cocos2d/CCDirector.h

  1/*
  2 * cocos2d for iPhone: http://www.cocos2d-iphone.org
  3 *
  4 * Copyright (c) 2008-2010 Ricardo Quesada
  5 * 
  6 * Permission is hereby granted, free of charge, to any person obtaining a copy
  7 * of this software and associated documentation files (the "Software"), to deal
  8 * in the Software without restriction, including without limitation the rights
  9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 10 * copies of the Software, and to permit persons to whom the Software is
 11 * furnished to do so, subject to the following conditions:
 12 * 
 13 * The above copyright notice and this permission notice shall be included in
 14 * all copies or substantial portions of the Software.
 15 * 
 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 22 * THE SOFTWARE.
 23 */
 24
 25
 26
 27//
 28#import "ccConfig.h"
 29#import "ccTypes.h"
 30
 31// OpenGL related
 32#import "Support/EAGLView.h"
 33
 34/** @typedef tPixelFormat
 35 Possible Pixel Formats for the EAGLView.
 36 
 37 @deprecated Will be removed in v1.0
 38 */
 39typedef enum {
 40	/** RGB565 pixel format. No alpha. 16-bit. (Default) */
 41	kCCPixelFormatRGB565,
 42	/** RGBA format. 32-bit. Needed for some 3D effects. It is not as fast as the RGB565 format. */
 43	kCCPixelFormatRGBA8888,
 44	/** default pixel format */
 45	kCCPixelFormatDefault = kCCPixelFormatRGB565,
 46
 47	// backward compatibility stuff
 48	kPixelFormatRGB565 = kCCPixelFormatRGB565,
 49	kRGB565 = kCCPixelFormatRGB565,
 50	kPixelFormatRGBA8888 = kCCPixelFormatRGBA8888,
 51	kRGBA8 = kCCPixelFormatRGBA8888,
 52} tPixelFormat;
 53
 54/** @typedef tDepthBufferFormat
 55 Possible DepthBuffer Formats for the EAGLView.
 56 Use 16 or 24 bit depth buffers if you are going to use real 3D objects.
 57 
 58 @deprecated Will be removed in v1.0
 59 */
 60typedef enum {
 61	/// A Depth Buffer of 0 bits will be used (default)
 62	kCCDepthBufferNone,
 63	/// A depth buffer of 16 bits will be used
 64	kCCDepthBuffer16,
 65	/// A depth buffer of 24 bits will be used
 66	kCCDepthBuffer24,
 67	
 68	// backward compatibility stuff
 69	kDepthBuffer16 = kCCDepthBuffer16,
 70	kDepthBuffer24 = kCCDepthBuffer24,
 71} tDepthBufferFormat;
 72
 73/** @typedef ccDirectorProjection
 74 Possible OpenGL projections used by director
 75 */
 76typedef enum {
 77	/// sets a 2D projection (orthogonal projection)
 78	kCCDirectorProjection2D,
 79	
 80	/// sets a 3D projection with a fovy=60, znear=0.5f and zfar=1500.
 81	kCCDirectorProjection3D,
 82	
 83	/// it does nothing. But if you are using a custom projection set it this value.
 84	kCCDirectorProjectionCustom,
 85	
 86	/// Detault projection is 3D projection
 87	kCCDirectorProjectionDefault = kCCDirectorProjection3D,
 88	
 89	// backward compatibility stuff
 90	CCDirectorProjection2D = kCCDirectorProjection2D,
 91	CCDirectorProjection3D = kCCDirectorProjection3D,
 92	CCDirectorProjectionCustom = kCCDirectorProjectionCustom,
 93
 94} ccDirectorProjection;
 95
 96/** @typedef ccDirectorType
 97 Possible Director Types.
 98 @since v0.8.2
 99 */
100typedef enum {
101	/** Will use a Director that triggers the main loop from an NSTimer object
102	 *
103	 * Features and Limitations:
104	 * - Integrates OK with UIKit objects
105	 * - It the slowest director
106	 * - The invertal update is customizable from 1 to 60
107	 */
108	kCCDirectorTypeNSTimer,
109	
110	/** will use a Director that triggers the main loop from a custom main loop.
111	 *
112	 * Features and Limitations:
113	 * - Faster than NSTimer Director
114	 * - It doesn't integrate well with UIKit objecgts
115	 * - The interval update can't be customizable
116	 */
117	kCCDirectorTypeMainLoop,
118	
119	/** Will use a Director that triggers the main loop from a thread, but the main loop will be executed on the main thread.
120	 *
121	 * Features and Limitations:
122	 * - Faster than NSTimer Director
123	 * - It doesn't integrate well with UIKit objecgts
124	 * - The interval update can't be customizable
125	 */
126	kCCDirectorTypeThreadMainLoop,
127	
128	/** Will use a Director that synchronizes timers with the refresh rate of the display.
129	 *
130	 * Features and Limitations:
131	 * - Faster than NSTimer Director
132	 * - Only available on 3.1+
133	 * - Scheduled timers & drawing are synchronizes with the refresh rate of the display
134	 * - Integrates OK with UIKit objects
135	 * - The interval update can be 1/60, 1/30, 1/15
136	 */	
137	kCCDirectorTypeDisplayLink,
138	
139	/** Default director is the NSTimer directory */
140	kCCDirectorTypeDefault = kCCDirectorTypeNSTimer,
141	
142	// backward compatibility stuff
143	CCDirectorTypeNSTimer = kCCDirectorTypeNSTimer,
144	CCDirectorTypeMainLoop = kCCDirectorTypeMainLoop,
145	CCDirectorTypeThreadMainLoop = kCCDirectorTypeThreadMainLoop,
146	CCDirectorTypeDisplayLink = kCCDirectorTypeDisplayLink,
147	CCDirectorTypeDefault = kCCDirectorTypeDefault,
148
149
150} ccDirectorType;
151
152/** @typedef ccDeviceOrientation
153 Possible device orientations
154 */
155typedef enum {
156	/// Device oriented vertically, home button on the bottom
157	kCCDeviceOrientationPortrait = UIDeviceOrientationPortrait,	
158	/// Device oriented vertically, home button on the top
159    kCCDeviceOrientationPortraitUpsideDown = UIDeviceOrientationPortraitUpsideDown,
160	/// Device oriented horizontally, home button on the right
161    kCCDeviceOrientationLandscapeLeft = UIDeviceOrientationLandscapeLeft,
162	/// Device oriented horizontally, home button on the left
163    kCCDeviceOrientationLandscapeRight = UIDeviceOrientationLandscapeRight,
164	
165	// Backward compatibility stuff
166	CCDeviceOrientationPortrait = kCCDeviceOrientationPortrait,
167	CCDeviceOrientationPortraitUpsideDown = kCCDeviceOrientationPortraitUpsideDown,
168	CCDeviceOrientationLandscapeLeft = kCCDeviceOrientationLandscapeLeft,
169	CCDeviceOrientationLandscapeRight = kCCDeviceOrientationLandscapeRight,
170} ccDeviceOrientation;
171
172@class CCLabelAtlas;
173@class CCScene;
174
175/**Class that creates and handle the main Window and manages how
176and when to execute the Scenes.
177 
178 The CCDirector is also resposible for:
179  - initializing the OpenGL ES context
180  - setting the OpenGL ES pixel format (default on is RGB565)
181  - setting the OpenGL ES buffer depth (default one is 0-bit)
182  - setting the projection (default one is 2D)
183  - setting the orientation (default one is Protrait)
184 
185 Since the CCDirector is a singleton, the standard way to use it is by calling:
186  - [[CCDirector sharedDirector] xxxx];
187 
188 The CCDirector also sets the default OpenGL ES context:
189  - GL_TEXTURE_2D is enabled
190  - GL_VERTEX_ARRAY is enabled
191  - GL_COLOR_ARRAY is enabled
192  - GL_TEXTURE_COORD_ARRAY is enabled
193*/
194@interface CCDirector : NSObject
195{
196	EAGLView	*openGLView_;
197
198	// internal timer
199	NSTimeInterval animationInterval_;
200	NSTimeInterval oldAnimationInterval_;
201
202	tPixelFormat pixelFormat_;
203	tDepthBufferFormat depthBufferFormat_;
204	
205	/* orientation */
206	ccDeviceOrientation	deviceOrientation_;
207	
208	/* display FPS ? */
209	BOOL displayFPS_;
210
211	int frames_;
212	ccTime accumDt_;
213	ccTime frameRate_;
214#if	CC_DIRECTOR_FAST_FPS
215	CCLabelAtlas *FPSLabel_;
216#endif
217	
218	/* is the running scene paused */
219	BOOL isPaused_;
220	
221	/* The running scene */
222	CCScene *runningScene_;
223	
224	/* will be the next 'runningScene' in the next frame
225	 nextScene is a weak reference. */
226	CCScene *nextScene_;
227	
228	/* If YES, then "old" scene will receive the cleanup message */
229	BOOL	sendCleanupToScene_;
230
231	/* scheduled scenes */
232	NSMutableArray *scenesStack_;
233	
234	/* last time the main loop was updated */
235	struct timeval lastUpdate_;
236	/* delta time since last tick to main loop */
237	ccTime dt;
238	/* whether or not the next delta time will be zero */
239	BOOL nextDeltaTimeZero_;
240	
241	/* projection used */
242	ccDirectorProjection projection_;
243	
244	/* screen, different than surface size */
245	CGSize	screenSize_;
246
247	/* screen, different than surface size */
248	CGSize	surfaceSize_;
249	
250	/* content scale factor */
251	CGFloat	contentScaleFactor_;
252	
253	/* contentScaleFactor could be simulated */
254	BOOL	isContentScaleSupported_;
255
256#if CC_ENABLE_PROFILERS
257	ccTime accumDtForProfiler_;
258#endif
259}
260
261/** The current running Scene. Director can only run one Scene at the time */
262@property (nonatomic,readonly) CCScene* runningScene;
263/** The FPS value */
264@property (nonatomic,readwrite, assign) NSTimeInterval animationInterval;
265/** Whether or not to display the FPS on the bottom-left corner */
266@property (nonatomic,readwrite, assign) BOOL displayFPS;
267/** The EAGLView, where everything is rendered */
268@property (nonatomic,readwrite,retain) EAGLView *openGLView;
269/** Pixel format used to create the context */
270@property (nonatomic,readonly) tPixelFormat pixelFormat DEPRECATED_ATTRIBUTE;
271/** whether or not the next delta time will be zero */
272@property (nonatomic,readwrite,assign) BOOL nextDeltaTimeZero;
273/** The device orientation.
274 If the EAGLView is going to be controlled by an UIViewController, then set the CCDirector orientation to portrait.
275 */
276@property (nonatomic,readwrite) ccDeviceOrientation deviceOrientation;
277/** Whether or not the Director is paused */
278@property (nonatomic,readonly) BOOL isPaused;
279/** Sets an OpenGL projection
280 @since v0.8.2
281 */
282@property (nonatomic,readwrite) ccDirectorProjection projection;
283
284/** Whether or not the replaced scene will receive the cleanup message.
285 If the new scene is pushed, then the old scene won't receive the "cleanup" message.
286 If the new scene replaces the old one, the it will receive the "cleanup" message.
287 @since v0.99.0
288 */
289@property (nonatomic, readonly) BOOL sendCleanupToScene;
290
291/** The size in pixels of the surface. It could be different than the screen size.
292 High-res devices might have a higher surface size than the screen size.
293 In non High-res device the contentScale will be emulated.
294
295 Warning: Emulation of High-Res on iOS < 4 is an EXPERIMENTAL feature.
296 
297 @since v0.99.4
298 */
299@property (nonatomic, readwrite) CGFloat contentScaleFactor;
300
301/** returns a shared instance of the director */
302+(CCDirector *)sharedDirector;
303
304+ (void) purgeSharedDirector;
305
306/** There are 4 types of Director.
307 - kCCDirectorTypeNSTimer (default)
308 - kCCDirectorTypeMainLoop
309 - kCCDirectorTypeThreadMainLoop
310 - kCCDirectorTypeDisplayLink
311 
312 Each Director has it's own benefits, limitations.
313 If you are using SDK 3.1 or newer it is recommed to use the DisplayLink director
314 
315 This method should be called before any other call to the director.
316
317 It will return NO if the director type is kCCDirectorTypeDisplayLink and the running SDK is < 3.1. Otherwise it will return YES.
318 
319 @since v0.8.2
320 */
321+(BOOL) setDirectorType:(ccDirectorType) directorType;
322
323
324// iPhone Specific
325
326/** Uses a new pixel format for the EAGLView.
327 Call this class method before attaching it to a UIView
328 Default pixel format: kRGB565. Supported pixel formats: kRGBA8 and kRGB565
329 
330 @deprecated Set the pixel format when creating the EAGLView. This method will be removed in v1.0
331 */
332-(void) setPixelFormat: (tPixelFormat)p DEPRECATED_ATTRIBUTE;
333
334/** Change depth buffer format of the render buffer.
335 Call this class method before attaching it to a UIWindow/UIView
336 Default depth buffer: 0 (none).  Supported: kCCDepthBufferNone, kCCDepthBuffer16, and kCCDepthBuffer24
337 
338 @deprecated Set the depth buffer format when creating the EAGLView. This method will be removed in v1.0
339 */
340-(void) setDepthBufferFormat: (tDepthBufferFormat)db DEPRECATED_ATTRIBUTE;
341
342// Integration with UIKit
343/** detach the cocos2d view from the view/window */
344-(BOOL)detach DEPRECATED_ATTRIBUTE;
345
346/** attach in UIWindow using the full frame.
347 It will create a EAGLView.
348 
349 @deprecated set setOpenGLView instead. Will be removed in v1.0
350 */
351-(BOOL)attachInWindow:(UIWindow *)window DEPRECATED_ATTRIBUTE;
352
353/** attach in UIView using the full frame.
354 It will create a EAGLView.
355 
356 @deprecated set setOpenGLView instead. Will be removed in v1.0
357 */
358-(BOOL)attachInView:(UIView *)view DEPRECATED_ATTRIBUTE;
359
360/** attach in UIView using the given frame.
361 It will create a EAGLView and use it.
362 
363 @deprecated set setOpenGLView instead. Will be removed in v1.0
364 */
365-(BOOL)attachInView:(UIView *)view withFrame:(CGRect)frame DEPRECATED_ATTRIBUTE;
366
367// Landscape
368
369/** returns the size of the OpenGL view in pixels, according to the landspace */
370- (CGSize) winSize;
371/** returns the display size of the OpenGL view in pixels */
372-(CGSize) displaySize;
373
374/** converts a UIKit coordinate to an OpenGL coordinate
375 Useful to convert (multi) touchs coordinates to the current layout (portrait or landscape)
376 */
377-(CGPoint) convertToGL: (CGPoint) p;
378/** converts an OpenGL coordinate to a UIKit coordinate
379 Useful to convert node points to window points for calls such as glScissor
380 */
381-(CGPoint) convertToUI:(CGPoint)p;
382
383// rotates the screen if an orientation differnent than Portrait is used
384-(void) applyOrientation;
385
386/// XXX: missing description
387-(float) getZEye;
388
389// Scene Management
390
391/**Enters the Director's main loop with the given Scene. 
392 * Call it to run only your FIRST scene.
393 * Don't call it if there is already a running scene.
394 */
395- (void) runWithScene:(CCScene*) scene;
396
397/**Suspends the execution of the running scene, pushing it on the stack of suspended scenes.
398 * The new scene will be executed.
399 * Try to avoid big stacks of pushed scenes to reduce memory allocation. 
400 * ONLY call it if there is a running scene.
401 */
402- (void) pushScene:(CCScene*) scene;
403
404/**Pops out a scene from the queue.
405 * This scene will replace the running one.
406 * The running scene will be deleted. If there are no more scenes in the stack the execution is terminated.
407 * ONLY call it if there is a running scene.
408 */
409- (void) popScene;
410
411/** Replaces the running scene with a new one. The running scene is terminated.
412 * ONLY call it if there is a running scene.
413 */
414-(void) replaceScene: (CCScene*) scene;
415
416/** Ends the execution, releases the running scene.
417 It doesn't remove the OpenGL view from its parent. You have to do it manually.
418 */
419-(void) end;
420
421/** Pauses the running scene.
422 The running scene will be _drawed_ but all scheduled timers will be paused
423 While paused, the draw rate will be 4 FPS to reduce CPU consuption
424 */
425-(void) pause;
426
427/** Resumes the paused scene
428 The scheduled timers will be activated again.
429 The "delta time" will be 0 (as if the game wasn't paused)
430 */
431-(void) resume;
432
433/** Stops the animation. Nothing will be drawn. The main loop won't be triggered anymore.
434 If you wan't to pause your animation call [pause] instead.
435 */
436-(void) stopAnimation;
437
438/** The main loop is triggered again.
439 Call this function only if [stopAnimation] was called earlier
440 @warning Dont' call this function to start the main loop. To run the main loop call runWithScene
441 */
442-(void) startAnimation;
443
444/** Draw the scene.
445 This method is called every frame. Don't call it manually.
446 */
447-(void) drawScene;
448
449// Memory Helper
450
451/** Removes all the cocos2d data that was cached automatically.
452 It will purge the CCTextureCache, CCBitmapFont cache.
453 IMPORTANT: The CCSpriteFrameCache won't be purged. If you want to purge it, you have to purge it manually.
454 @since v0.99.3
455 */
456-(void) purgeCachedData;
457 
458
459// OpenGL Helper
460
461/** sets the OpenGL default values */
462-(void) setGLDefaultValues;
463
464/** enables/disables OpenGL alpha blending */
465- (void) setAlphaBlending: (BOOL) on;
466/** enables/disables OpenGL depth test */
467- (void) setDepthTest: (BOOL) on;
468/** recalculate the projection view and projection size based on the EAGLVIEW
469 @since v0.99.4
470 */
471- (void) recalculateProjectionAndEAGLViewSize;
472
473@end
474
475/** FastDirector is a Director that triggers the main loop as fast as possible.
476 *
477 * Features and Limitations:
478 *  - Faster than "normal" director
479 *  - Consumes more battery than the "normal" director
480 *  - It has some issues while using UIKit objects
481 */
482@interface CCFastDirector : CCDirector
483{
484	BOOL isRunning;
485	
486	NSAutoreleasePool	*autoreleasePool;
487}
488-(void) preMainLoop;
489@end
490
491/** ThreadedFastDirector is a Director that triggers the main loop from a thread.
492 *
493 * Features and Limitations:
494 *  - Faster than "normal" director
495 *  - Consumes more battery than the "normal" director
496 *  - It can be used with UIKit objects
497 *
498 * @since v0.8.2
499 */
500@interface CCThreadedFastDirector : CCDirector
501{
502	BOOL isRunning;	
503}
504-(void) preMainLoop;
505@end
506
507/** DisplayLinkDirector is a Director that synchronizes timers with the refresh rate of the display.
508 *
509 * Features and Limitations:
510 * - Only available on 3.1+
511 * - Scheduled timers & drawing are synchronizes with the refresh rate of the display
512 * - Only supports animation intervals of 1/60 1/30 & 1/15
513 *
514 * It is the recommended Director if the SDK is 3.1 or newer
515 *
516 * @since v0.8.2
517 */
518@interface CCDisplayLinkDirector : CCDirector
519{
520	id displayLink;
521}
522-(void) preMainLoop:(id)sender;
523@end
524
525/** TimerDirector is a Director that calls the main loop from an NSTimer object
526 *
527 * Features and Limitations:
528 * - Integrates OK with UIKit objects
529 * - It the slowest director
530 * - The invertal update is customizable from 1 to 60
531 *
532 * It is the default Director.
533 */
534@interface CCTimerDirector : CCDirector
535{
536	NSTimer *animationTimer;
537}
538@end
539