1 /*!**************************************************************************** 2 3 @file Shell/PVRShell.h 4 @copyright Copyright (c) Imagination Technologies Limited. 5 @brief Makes programming for 3D APIs easier by wrapping surface 6 initialization, Texture allocation and other functions for use by a demo. 7 8 ******************************************************************************/ 9 10 #ifndef __PVRSHELL_H_ 11 #define __PVRSHELL_H_ 12 13 /*****************************************************************************/ 14 /*! @mainpage PVRShell 15 ****************************************************************************** 16 17 @tableofcontents 18 19 @section overview Overview 20 ***************************** 21 22 PVRShell is a C++ class used to make programming for PowerVR platforms easier and more portable. 23 PVRShell takes care of all API and OS initialisation for the user and handles adapters, devices, screen/windows modes, 24 resolution, buffering, depth-buffer, viewport creation & clearing, etc... 25 26 PVRShell consists of 3 files: PVRShell.cpp, PVRShellOS.cpp and PVRShellAPI.cpp. 27 28 PVRShellOS.cpp and PVRShellAPI.cpp are supplied per platform and contain all the code to initialise the specific 29 API (OpenGL ES, Direct3D Mobile, etc.) and the OS (Windows, Linux, WinCE, etc.). 30 PVRShell.cpp is where the common code resides and it interacts with the user application through an abstraction layer. 31 32 A new application must link to these three files and must create a class that will inherit the PVRShell class. 33 This class will provide five virtual functions to interface with the user. 34 35 The user also needs to register his application class through the NewDemo function: 36 37 @code 38 class MyApplication: public PVRShell 39 { 40 public: 41 virtual bool InitApplication(); 42 virtual bool InitView(); 43 virtual bool ReleaseView(); 44 virtual bool QuitApplication(); 45 virtual bool RenderScene(); 46 }; 47 48 PVRShell* NewDemo() 49 { 50 return new MyApplication(); 51 } 52 @endcode 53 54 55 @section interface Interface 56 ****************************** 57 58 There are two functions for initialisation, two functions to release allocated resources and a render function: 59 60 InitApplication() will be called by PVRShell once per run, before the graphic context is created. 61 It is used to initialise variables that are not dependant on the rendering context (e.g. external modules, loading user data, etc.). 62 QuitApplication() will be called by PVRShell once per run, just before exiting the program. 63 If the graphic context is lost, QuitApplication() will not be called. 64 65 InitView() will be called by PVRShell upon creation or change in the rendering context. 66 It is used to initialise variables that are dependant on the rendering context (e.g. textures, vertex buffers, etc.). 67 ReleaseView() will be called by PVRShell before changing to a new rendering context or 68 when finalising the application (before calling QuitApplication). 69 70 RenderScene() is the main rendering loop function of the program. This function must return FALSE when the user wants to terminate the application. 71 PVRShell will call this function every frame and will manage relevant OS events. 72 73 There are other PVRShell functions which allow the user to set his/her preferences and get data back from the devices: 74 75 PVRShellSet() and PVRShellGet() are used to pass data to and from PVRShell. PVRShellSet() is recommended to be used 76 in InitApplication() so the user preferences are applied at the API initialisation. 77 There is a definition of these functions per type of data passed or returned. Please check the prefNameBoolEnum, prefNameFloatEnum, 78 prefNameIntEnum, prefNamePtrEnum and prefNameConstPtrEnum enumerations for a full list of the data available. 79 80 This is an example: 81 82 @code 83 bool MyApplication::InitApplication() 84 { 85 PVRShellSet (prefFullScreen, true); 86 } 87 88 bool MyApplication::RenderScene() 89 { 90 int dwCurrentWidth = PVRShellGet (prefHeight); 91 int dwCurrentHeight = PVRShellGet (prefWidth); 92 93 return true; 94 } 95 @endcode 96 97 98 @section helper Helper functions 99 ************************************* 100 101 The user input is abstracted with the PVRShellIsKeyPressed() function. It will not work in all devices, but we have tried to map the most 102 relevant keys when possible. See PVRShellKeyName enumeration for the list of keys supported. This function will return true or false depending on 103 the specified key being pressed. 104 105 There are a few other helper functions supplied by PVRShell as well. These functions allow you to read the timer, to output debug information and to 106 save a screen-shot of the current frame: 107 108 PVRShellGetTime() returns time in milliseconds. 109 110 PVRShellOutputDebug() will write a debug string (same format as printf) to the platform debug output. 111 112 PVRShellScreenCaptureBuffer() and PVRShellWriteBMPFile() will be used to save the current frame as a BMP file. PVRShellScreenCaptureBuffer() 113 receives a pointer to an area of memory containing the screen buffer. The memory should be freed with free() when not needed any longer. 114 115 Example of screenshot: 116 117 @code 118 bool MyApplication::RenderScene() 119 { 120 [...] 121 122 unsigned char *pLines; 123 124 PVRShellScreenCaptureBuffer(PVRShellGet (prefWidth), PVRShellGet (prefHeight), &pLines); 125 126 PVRShellScreenSave("myfile", pLines, NULL); 127 128 free (pLines); 129 130 return true; 131 } 132 @endcode 133 134 135 @section cmd Command-line 136 ************************************* 137 138 Across all platforms, PVRShell takes a set of command-line arguments which allow things like the position and size of the demo 139 to be controlled. The list below shows these options. 140 141 \b -width=N Sets the horizontal viewport width to N. 142 143 \b -height=N Sets the vertical viewport height to N. 144 145 \b -posx=N Sets the x coordinate of the viewport. 146 147 \b -posy=N Sets the y coordinate of the viewport. 148 149 \b -aasamples=N Sets the number of samples to use for full screen anti-aliasing. e.g 0, 2, 4, 8 150 151 \b -fullscreen=N Enable/Disable fullscreen mode. N can be: 0=Windowed 1=Fullscreen. 152 153 \b -qat=N Quits after N seconds. 154 155 \b -qaf=N Quits after N frames. 156 157 \b -powersaving=N Where available enable/disable power saving. N can be: 0=Disable power saving 1=Enable power saving. 158 159 \b -vsync=N Where available modify the apps vsync parameters. 160 161 \b -version Output the SDK version to the debug output. 162 163 \b -info Output setup information (e.g. window width) to the debug output. 164 165 \b -rotatekeys=N Sets the orientation of the keyboard input. N can be: 0-3, 0 is no rotation. 166 167 \b -c=N Save a single screenshot or a range. e.g. -c=1-10, -c=14. 168 169 \b -priority=N EGL only. Sets the priority of the EGL context. 170 171 \b -colourbpp=N EGL only. When choosing an EGL config N will be used as the value for EGL_BUFFER_SIZE. 172 173 \b -depthbpp=N EGL only. When choosing an EGL config N will be used as the value for EGL_DEPTH_SIZE. 174 175 \b -config=N EGL only. Force the shell to use the EGL config with ID N. 176 177 \b -forceframetime=N Alter the behaviour of PVRShellGetTime so its returned value is frame based (N denotes how many ms a frame should pretend to last). You can also use the shortened version of -fft and the command can be used without N being defined, e.g. just -forceframetime. This option is provided to aid in debugging time-based applications. 178 179 Example: 180 @code 181 Demo -width=160 -height=120 -qaf=300 182 @endcode 183 184 @section APIsOSs APIs and Operating Systems 185 ***************************** 186 For information specific to each 3D API and Operating System, see the list of supported APIs and OSs on the <a href="modules.html">Modules</a> page. 187 188 ******************************************************************************/ 189 // Uncomment to enable the -fps command-line option 190 // #define PVRSHELL_FPS_OUTPUT 191 192 /***************************************************************************** 193 ** Includes 194 *****************************************************************************/ 195 #include <stdlib.h> 196 197 #define EXIT_NOERR_CODE 0 198 #define EXIT_ERR_CODE (!EXIT_NOERR_CODE) 199 200 // avoid warning about unused parameter 201 #define PVRSHELL_UNREFERENCED_PARAMETER(x) ((void) x) 202 203 // Keyboard mapping. // 204 205 /*!*********************************************************************** 206 @enum PVRShellKeyName 207 @brief Key name. 208 ************************************************************************/ 209 enum PVRShellKeyName 210 { 211 PVRShellKeyNameNull, /*!< Null key value */ 212 PVRShellKeyNameQUIT, /*!< QUIT key value */ 213 PVRShellKeyNameSELECT, /*!< SELECT key value */ 214 PVRShellKeyNameACTION1, /*!< ACTION1 key value */ 215 PVRShellKeyNameACTION2, /*!< ACTION2 key value */ 216 PVRShellKeyNameUP, /*!< UP key */ 217 PVRShellKeyNameDOWN, /*!< DOWN key */ 218 PVRShellKeyNameLEFT, /*!< LEFT key */ 219 PVRShellKeyNameRIGHT, /*!< RIGHT key */ 220 PVRShellKeyNameScreenshot /*!< SCREENSHOT key */ 221 }; 222 223 /*!*********************************************************************** 224 @enum PVRShellKeyRotate 225 @brief Key rotate. 226 ************************************************************************/ 227 enum PVRShellKeyRotate 228 { 229 PVRShellKeyRotateNone=0, /*!< Rotate key none = 0. */ 230 PVRShellKeyRotate90, /*!< Rotate key 90 */ 231 PVRShellKeyRotate180, /*!< Rotate key 180 */ 232 PVRShellKeyRotate270 /*!< Rotate key 270 */ 233 }; 234 235 // Pointer button mapping. // 236 237 /*!*********************************************************************** 238 @enum EPVRShellButtonState 239 @brief Pointer button mapping. 240 ************************************************************************/ 241 enum EPVRShellButtonState 242 { 243 ePVRShellButtonLeft = 0x1, /*!< Left button */ 244 ePVRShellButtonRight = 0x2, /*!< Right button */ 245 ePVRShellButtonMiddle = 0x4 /*!< Middle button */ 246 }; 247 248 /*!*********************************************************************** 249 @enum prefNameBoolEnum 250 @brief Boolean Shell preferences. 251 ************************************************************************/ 252 enum prefNameBoolEnum 253 { 254 prefFullScreen, /*!< Set to: 1 for full-screen rendering; 0 for windowed */ 255 prefIsRotated, /*!< Query this to learn whether screen is rotated */ 256 prefPBufferContext, /*!< 1 if you need pbuffer support (default is pbuffer not needed) */ 257 prefPixmapContext, /*!< 1 to use a pixmap as a render-target (default off) */ 258 prefPixmapDisableCopy, /*!< 1 to disable the copy if pixmaps are used */ 259 prefZbufferContext, /*!< 1 if you wish to have zbuffer support (default to on) */ 260 prefLockableBackBuffer, /*!< DX9 only: true to use D3DPRESENTFLAG_LOCKABLE_BACKBUFFER (default: false) */ 261 prefSoftwareRendering, /*!< 1 to select software rendering (default: off, i.e. use hardware) */ 262 prefStencilBufferContext, /*!< 1 if you wish to have stencil support (default: off) */ 263 prefAlphaFormatPre, /*!< EGL only: 1 to create the EGL surface with EGL_ALPHA_FORMAT_PRE (default: 0) */ 264 prefPowerSaving, /*!< If true then the app will go into powersaving mode (if available) when not in use. */ 265 #ifdef PVRSHELL_FPS_OUTPUT 266 prefOutputFPS, /*!< If true then the FPS are output using PVRShellOutputdebug */ 267 #endif 268 prefOutputInfo, /*!< If true then the app will output helpful information such as colour buffer format via PVRShellOutputDebug. */ 269 prefNoShellSwapBuffer, /*!< EGL: If true then the shell won't call eglswapbuffers at the end of each frame. */ 270 prefShowCursor, /*!< Set to: 1 to show the cursor; 0 to hide it. */ 271 prefForceFrameTime, /*!< If true will alter PVRShellGetTime behaviour to be frame based. This is for debugging purposes. */ 272 prefDiscardColor, /*!< GLES: Whether or not to discard color data at the end of a render, to save bandwidth. Requires specific functionality. (default: false) */ 273 prefDiscardDepth, /*!< GLES: Whether or not to discard depth data at the end of a render, to save bandwidth. Requires specific functionality. (default: true) */ 274 prefDiscardStencil /*!< GLES: Whether or not to discard stencil data at the end of a render, to save bandwidth. Requires specific functionality. (default: true) */ 275 }; 276 277 /*!*********************************************************************** 278 @enum prefNameFloatEnum 279 @brief Float Shell preferences. 280 ************************************************************************/ 281 enum prefNameFloatEnum 282 { 283 prefQuitAfterTime /*!< Shell will quit after this number of seconds (-1 to disable) */ 284 }; 285 286 /*!*********************************************************************** 287 @enum prefNameIntEnum 288 @brief Integer Shell preferences. 289 ************************************************************************/ 290 enum prefNameIntEnum 291 { 292 prefEGLMajorVersion, /*!< EGL: returns the major version as returned by eglInitialize() */ 293 prefEGLMinorVersion, /*!< EGL: returns the minor version as returned by eglInitialize() */ 294 prefWidth, /*!< Width of render target */ 295 prefHeight, /*!< Height of render target */ 296 prefPositionX, /*!< X position of the window */ 297 prefPositionY, /*!< Y position of the window */ 298 prefQuitAfterFrame, /*!< Shell will quit after this number of frames (-1 to disable) */ 299 prefSwapInterval, /*!< 0 to preventing waiting for monitor vertical syncs */ 300 prefInitRepeats, /*!< Number of times to reinitialise (if >0 when app returns false from RenderScene(), shell will ReleaseView(), InitView() then re-enter RenderScene() loop). Decrements on each initialisation. */ 301 prefAASamples, /*!< Set to: 0 to disable full-screen anti-aliasing; 2 for 2x; 4 for 4x; 8 for 8x. */ 302 prefCommandLineOptNum, /*!< Returns the length of the array returned by prefCommandLineOpts */ 303 prefColorBPP, /*!< Allows you to specify a desired color buffer size e.g. 16, 32. */ 304 prefDepthBPP, /*!< Allows you to specify a desired depth buffer size e.g. 16, 24. */ 305 prefRotateKeys, /*!< Allows you to specify and retrieve how the keyboard input is transformed */ 306 prefButtonState, /*!< pointer button state */ 307 prefCaptureFrameStart, /*!< The frame to start capturing screenshots from */ 308 prefCaptureFrameStop, /*!< The frame to stop capturing screenshots at */ 309 prefCaptureFrameScale, /*!< Pixel-replicate saved screenshots this many times; default 1 for no scale */ 310 prefPriority, /*!< EGL: If supported will set the egl context priority; 0 for low, 1 for med and 2 for high. */ 311 prefConfig, /*!< EGL: Get the chosen EGL config. */ 312 prefRequestedConfig, /*!< EGL: Force the shell to use a particular EGL config. */ 313 prefNativeDisplay, /*!< EGL: Allows you to specify the native display to use if the device has more that one. */ 314 prefFrameTimeValue /*!< An integer value to say how long you wish one frame to last for (in ms) when force frame time is enabled. */ 315 }; 316 317 /*!*********************************************************************** 318 @enum prefNamePtrEnum 319 @brief Pointers/Handlers Shell preferences. 320 ************************************************************************/ 321 enum prefNamePtrEnum 322 { 323 prefD3DDevice, /*!< D3D: returns the device pointer */ 324 prefEGLDisplay, /*!< EGL: returns the EGLDisplay */ 325 prefEGLSurface, /*!< EGL: returns the EGLSurface */ 326 prefHINSTANCE, /*!< Windows: returns the application instance handle */ 327 prefNativeWindowType, /*!< Returns the window handle */ 328 prefAccelerometer, /*!< Accelerometer values */ 329 prefPointerLocation, /*!< Mouse pointer/touch location values */ 330 prefPVR2DContext, /*!< PVR2D: returns the PVR2D context */ 331 prefLoadFileFunc, /*!< A pointer to a function that can be used to load external files on platforms that don't allow the use of fopen. 332 The ptr returned is of the type PFNLoadFileFunc defined below. */ 333 prefReleaseFileFunc, /*!< A pointer to a function that is used to release any data allocated by the load file function. 334 The ptr returned is of the type PFNReleaseFileFunc defined below. */ 335 prefAndroidNativeActivity /*!< Android: A pointer to the ANativeActivity struct for the application. Your application will need to include android_native_app_glue.h to cast the pointer to ANativeActivity. */ 336 }; 337 338 /*!*********************************************************************** 339 @typedef PFNLoadFileFunc 340 @brief The LoadFileFunc function pointer template. 341 ************************************************************************/ 342 typedef void* (*PFNLoadFileFunc)(const char*, char** pData, size_t &size); 343 344 /*!*********************************************************************** 345 @typedef PFNReleaseFileFunc 346 @brief The ReleaseFileFunc function pointer template. 347 ************************************************************************/ 348 typedef bool (*PFNReleaseFileFunc)(void* handle); 349 350 /*!*********************************************************************** 351 @enum prefNameConstPtrEnum 352 @brief Constant pointers Shell preferences. 353 ************************************************************************/ 354 enum prefNameConstPtrEnum 355 { 356 prefAppName, /*!< ptrValue is char* */ 357 prefReadPath, /*!< ptrValue is char*; will include a trailing slash */ 358 prefWritePath, /*!< ptrValue is char*; will include a trailing slash */ 359 prefCommandLine, /*!< used to retrieve the entire application command line */ 360 prefCommandLineOpts, /*!< ptrValue is SCmdLineOpt*; retrieves an array of arg/value pairs (parsed from the command line) */ 361 prefExitMessage, /*!< ptrValue is char*; gives the shell a message to show on exit, typically an error */ 362 prefVersion /*!< ptrValue is char* */ 363 }; 364 365 /*!************************************************************************** 366 @struct PVRShellData 367 @brief PVRShell implementation Prototypes and definitions 368 *****************************************************************************/ 369 struct PVRShellData; 370 371 /*!*************************************************************************** 372 @class PVRShellInit 373 *****************************************************************************/ 374 class PVRShellInit; 375 376 /*!*********************************************************************** 377 @struct SCmdLineOpt 378 @brief Stores a variable name/value pair for an individual command-line option. 379 ************************************************************************/ 380 struct SCmdLineOpt 381 { 382 const char *pArg, *pVal; 383 }; 384 385 /*!*************************************************************************** 386 @class PVRShell 387 @brief Inherited by the application; responsible for abstracting the OS and API. 388 @details PVRShell is the main Shell class that an application uses. An 389 application should supply a class which inherits PVRShell and supplies 390 implementations of the virtual functions of PVRShell (InitApplication(), 391 QuitApplication(), InitView(), ReleaseView(), RenderScene()). Default stub 392 functions are supplied; this means that an application is not 393 required to supply a particular function if it does not need to do anything 394 in it. 395 The other, non-virtual, functions of PVRShell are utility functions that the 396 application may call. 397 *****************************************************************************/ 398 class PVRShell 399 { 400 private: 401 friend class PVRShellInitOS; 402 friend class PVRShellInit; 403 404 PVRShellData *m_pShellData; 405 PVRShellInit *m_pShellInit; 406 407 public: 408 /*!*********************************************************************** 409 @brief Constructor 410 *************************************************************************/ 411 PVRShell(); 412 413 /*!*********************************************************************** 414 @brief Destructor 415 *************************************************************************/ 416 virtual ~PVRShell(); 417 418 /* 419 PVRShell functions that the application should implement. 420 */ 421 422 /*!*********************************************************************** 423 @brief Initialise the application. 424 @details This function can be overloaded by the application. It 425 will be called by PVRShell once, only at the beginning of 426 the PVRShell WinMain()/main() function. This function 427 enables the user to perform any initialisation before the 428 render API is initialised. From this function the user can 429 call PVRShellSet() to change default values, e.g. 430 requesting a particular resolution or device setting. 431 @return true for success, false to exit the application 432 *************************************************************************/ InitApplication()433 virtual bool InitApplication() { return true; }; 434 435 /*!*********************************************************************** 436 @brief Quit the application. 437 @details This function can be overloaded by the application. It 438 will be called by PVRShell just before finishing the 439 program. It enables the application to release any 440 memory/resources acquired in InitApplication(). 441 @return true for success, false to exit the application 442 *************************************************************************/ QuitApplication()443 virtual bool QuitApplication() { return true; }; 444 445 /*!*********************************************************************** 446 @brief Initialise the view. 447 @details This function can be overloaded by the application. It 448 will be called by PVRShell after the OS and rendering API 449 are initialised, before entering the RenderScene() loop. 450 It is called any time the rendering API is initialised, 451 i.e. once at the beginning, and possibly again if the 452 resolution changes, or a power management even occurs, or 453 if the app requests a re-initialisation. 454 The application should check here the configuration of 455 the rendering API; it is possible that requests made in 456 InitApplication() were not successful. 457 Since everything is initialised when this function is 458 called, you can load textures and perform rendering API functions. 459 @return true for success, false to exit the application 460 *************************************************************************/ InitView()461 virtual bool InitView() { return true; }; 462 463 /*!*********************************************************************** 464 @brief Release the view. 465 @details This function can be overloaded by the application. It 466 will be called after the RenderScene() loop, before 467 shutting down the render API. It enables the application 468 to release any memory/resources acquired in InitView(). 469 @return true for success, false to exit the application 470 *************************************************************************/ ReleaseView()471 virtual bool ReleaseView() { return true; }; 472 473 /*!*********************************************************************** 474 @brief Render the scene 475 @details This function can be overloaded by the application. 476 It is main application function in which you have to do your own rendering. Will be 477 called repeatedly until the application exits. 478 @return true for success, false to exit the application 479 *************************************************************************/ RenderScene()480 virtual bool RenderScene() { return true; }; 481 482 /* 483 PVRShell functions available for the application to use. 484 */ 485 486 /*!*********************************************************************** 487 @brief This function is used to pass preferences to the PVRShell. 488 If used, this function must be called from InitApplication(). 489 @param[in] prefName Name of preference to set to value 490 @param[in] value Value 491 @return true for success 492 *************************************************************************/ 493 bool PVRShellSet(const prefNameBoolEnum prefName, const bool value); 494 495 /*!*********************************************************************** 496 @brief This function is used to pass preferences to the PVRShell. 497 If used, this function must be called from InitApplication(). 498 @param[in] prefName Name of preference to set to value 499 @param[in] value Value 500 @return true for success 501 *************************************************************************/ 502 bool PVRShellSet(const prefNameFloatEnum prefName, const float value); 503 504 /*!*********************************************************************** 505 @brief This function is used to pass preferences to the PVRShell. 506 If used, this function must be called from InitApplication(). 507 @param[in] prefName Name of preference to set to value 508 @param[in] value Value 509 @return true for success 510 *************************************************************************/ 511 bool PVRShellSet(const prefNameIntEnum prefName, const int value); 512 513 /*!*********************************************************************** 514 @brief This function is used to pass preferences to the PVRShell. 515 If used, this funciton must be called from InitApplication(). 516 @param[in] prefName Name of preference to set to value 517 @param[in] ptrValue Value 518 @return true for success 519 *************************************************************************/ 520 bool PVRShellSet(const prefNamePtrEnum prefName, const void * const ptrValue); 521 522 /*!*********************************************************************** 523 @brief This function is used to pass preferences to the PVRShell. 524 If used, this function must be called from InitApplication(). 525 @param[in] prefName Name of preference to set to value 526 @param[in] ptrValue Value 527 @return true for success 528 *************************************************************************/ 529 bool PVRShellSet(const prefNameConstPtrEnum prefName, const void * const ptrValue); 530 531 /*!*********************************************************************** 532 @brief This function is used to get parameters from the PVRShell. 533 It can be called from anywhere in the program. 534 @param[in] prefName Name of preference to set to value 535 @return The requested value. 536 *************************************************************************/ 537 bool PVRShellGet(const prefNameBoolEnum prefName) const; 538 539 /*!*********************************************************************** 540 @brief This function is used to get parameters from the PVRShell. 541 It can be called from anywhere in the program. 542 @param[in] prefName Name of preference to set to value 543 @return The requested value. 544 *************************************************************************/ 545 float PVRShellGet(const prefNameFloatEnum prefName) const; 546 547 /*!*********************************************************************** 548 @brief This function is used to get parameters from the PVRShell. 549 It can be called from anywhere in the program. 550 @param[in] prefName Name of preference to set to value 551 @return The requested value. 552 *************************************************************************/ 553 int PVRShellGet(const prefNameIntEnum prefName) const; 554 555 /*!*********************************************************************** 556 @brief This function is used to get parameters from the PVRShell. 557 It can be called from anywhere in the program. 558 @param[in] prefName Name of preference to set to value 559 @return The requested value. 560 *************************************************************************/ 561 void *PVRShellGet(const prefNamePtrEnum prefName) const; 562 563 /*!*********************************************************************** 564 @brief This function is used to get parameters from the PVRShell 565 It can be called from anywhere in the program. 566 @param[in] prefName Name of preference to set to value 567 @return The requested value. 568 *************************************************************************/ 569 const void *PVRShellGet(const prefNameConstPtrEnum prefName) const; 570 571 /*!*********************************************************************** 572 @brief It will be stored as 24-bit per pixel, 8-bit per chanel RGB. 573 The memory should be freed using the free() function when no longer needed. 574 @param[in] Width size of image to capture (relative to 0,0) 575 @param[in] Height size of image to capture (relative to 0,0) 576 @param[out] pLines receives a pointer to an area of memory containing the screen buffer. 577 @return true for success 578 *************************************************************************/ 579 bool PVRShellScreenCaptureBuffer(const int Width, const int Height, unsigned char **pLines); 580 581 /*!*********************************************************************** 582 @brief Writes out the image data to a BMP file with basename fname. 583 @details The file written will be fname suffixed with a 584 number to make the file unique. 585 For example, if fname is "abc", this function will attempt 586 to save to "abc0000.bmp"; if that file already exists, it 587 will try "abc0001.bmp", repeating until a new filename is 588 found. The final filename used is returned in ofname. 589 @param[in] fname base of file to save screen to 590 @param[in] Width size of image 591 @param[in] Height size of image 592 @param[in] pLines image data to write out (24bpp, 8-bit per channel RGB) 593 @param[in] ui32PixelReplicate expand pixels through replication (1 = no scale) 594 @param[out] ofname If non-NULL, receives the filename actually used 595 @return true for success 596 *************************************************************************/ 597 int PVRShellScreenSave( 598 const char * const fname, 599 const int Width, 600 const int Height, 601 const unsigned char * const pLines, 602 const unsigned int ui32PixelReplicate = 1, 603 char * const ofname = NULL); 604 605 /*!*********************************************************************** 606 @brief Writes out the image data to a BMP file with name fname. 607 @param[in] pszFilename file to save screen to 608 @param[in] ui32Width the width of the data 609 @param[in] ui32Height the height of the data 610 @param[in] pImageData image data to write out (24bpp, 8-bit per channel RGB) 611 @param[in] ui32PixelReplicate expand pixels through replication (1 = no scale) 612 @return 0 on success 613 *************************************************************************/ 614 int PVRShellWriteBMPFile( 615 const char * const pszFilename, 616 const unsigned int ui32Width, 617 const unsigned int ui32Height, 618 const void * const pImageData, 619 const unsigned int ui32PixelReplicate = 1); 620 621 /*!*********************************************************************** 622 @brief Writes the resultant string to the debug output (e.g. using 623 printf(), OutputDebugString(), ...). Check the SDK release notes for 624 details on how the string is output. 625 @param[in] format printf style format followed by arguments it requires 626 *************************************************************************/ 627 void PVRShellOutputDebug(char const * const format, ...) const; 628 629 /*!*********************************************************************** 630 @brief The number itself should be considered meaningless; an 631 application should use this function to determine how much 632 time has passed between two points (e.g. between each frame). 633 @return A value which increments once per millisecond. 634 *************************************************************************/ 635 unsigned long PVRShellGetTime(); 636 637 /*!*********************************************************************** 638 @brief Check if a key was pressed. 639 @details The keys on various devices 640 are mapped to the PVRShell-supported keys (listed in @a PVRShellKeyName) in 641 a platform-dependent manner, since most platforms have different input 642 devices. Check the <a href="modules.html">Modules page</a> for your OS 643 for details on how the enum values map to your device's key code input. 644 @param[in] key Code of the key to test 645 @return true if key was pressed 646 *************************************************************************/ 647 bool PVRShellIsKeyPressed(const PVRShellKeyName key); 648 }; 649 650 /**************************************************************************** 651 ** Declarations for functions that the scene file must supply 652 ****************************************************************************/ 653 654 /*!*************************************************************************** 655 @brief This function must be implemented by the user of the shell. 656 @details The user should return its PVRShell object defining the 657 behaviour of the application. 658 @return The demo supplied by the user 659 *****************************************************************************/ 660 PVRShell* NewDemo(); 661 662 #endif /* __PVRSHELL_H_ */ 663 664 /***************************************************************************** 665 End of file (PVRShell.h) 666 *****************************************************************************/ 667 668