/libs/cocos2d/CCDirector.h
C Header | 539 lines | 150 code | 86 blank | 303 comment | 0 complexity | 9ee22cbcb7d31992138d242ec51366ab MD5 | raw file
Possible License(s): Apache-2.0
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