1 /*!**************************************************************************** 2 3 @file Shell/PVRShellImpl.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 __PVRSHELLIMPL_H_ 11 #define __PVRSHELLIMPL_H_ 12 13 /***************************************************************************** 14 ** Build options 15 *****************************************************************************/ 16 17 18 /***************************************************************************** 19 ** Macros 20 *****************************************************************************/ 21 #define FREE(X) { if(X) { free(X); (X)=0; } } 22 23 #ifndef _ASSERT 24 #define _ASSERT(X) /**/ 25 #endif 26 27 /***************************************************************************** 28 ** Defines 29 *****************************************************************************/ 30 #define STR_WNDTITLE (" - Build ") 31 32 /*!*************************************************************************** 33 @struct PVRShellData 34 @brief Holds PVRShell internal data. 35 *****************************************************************************/ 36 struct PVRShellData 37 { 38 // Shell Interface Data 39 char *pszAppName; /*!< Application name string. */ 40 char *pszExitMessage; /*!< Exit message string. */ 41 int nShellDimX; /*!< Width in pixels. */ 42 int nShellDimY; /*!< Height in pixels. */ 43 int nShellPosX; /*!< X position of the window. */ 44 int nShellPosY; /*!< Y position of the window. */ 45 bool bFullScreen; /*!< Fullscreen boolean. */ 46 bool bLandscape; /*!< Landscape orientation boolean. false = portrait orientation. */ 47 bool bNeedPbuffer; /*!< True if pixel buffer is needed. */ 48 bool bNeedZbuffer; /*!< True if Z buffer is needed. */ 49 bool bNeedStencilBuffer; /*!< True if stencil buffer is needed. */ 50 bool bNeedPixmap; /*!< True if pixmap is needed. */ 51 bool bNeedPixmapDisableCopy; /*!< Disables copy if true, because pixmaps are used. */ 52 bool bLockableBackBuffer; /*!< DX9 only. Enable the use of D3DPRESENTFLAG_LOCKABLE_BACKBUFFER. */ 53 bool bSoftwareRender; /*!< Enable the use of software rendering. */ 54 bool bNeedAlphaFormatPre; /*!< EGL only: If true, creates the EGL surface with EGL_ALPHA_FORMAT_PRE. */ 55 bool bUsingPowerSaving; /*!< Use power saving mode when device is not in use. */ 56 bool bOutputInfo; /*!< Enable information to be output via PVRShellOutputDebug. For example, 57 the depth of the colour surface created, extenstions supported and 58 dimensions of the surface created. */ 59 bool bNoShellSwapBuffer; /*!< Disable eglswapbuffers at the end of each frame. */ 60 int nSwapInterval; /*!< Interval to wait for monitor vertical sync. */ 61 int nInitRepeats; /*!< Number of times to reinitialise. */ 62 int nDieAfterFrames; /*!< Set shell to quit after this number of frames (-1 to disable) */ 63 float fDieAfterTime; /*!< Set shell to quit after this number of seconds (-1 to disable). */ 64 int nAASamples; /*!< Number of anti-aliasing samples to have. 0 disables anti-aliasing. */ 65 int nColorBPP; /*!< Color buffer size. */ 66 int nDepthBPP; /*!< Depth buffer size. */ 67 int nCaptureFrameStart; /*!< The frame to start capturing screenshots from. */ 68 int nCaptureFrameStop; /*!< The frame to stop capturing screenshots from. */ 69 int nCaptureFrameScale; /*!< Save screenshots scale factor. 1 for no scaling. */ 70 int nPriority; /*!< EGL: If supported sets the egl context priority; 71 0 for low, 1 for med and 2 for high. */ 72 bool bForceFrameTime; /*!< Overrides PVRShellGetTime to force specified frame time. May cause 73 problems if PVRShellGetTime is called multiple times in a frame. */ 74 int nFrameTime; /*!< How long for each frame time to last (in ms). */ 75 bool bDiscardFrameColor; /*!< Discard color data at the end of a render. */ 76 bool bDiscardFrameDepth; /*!< Discard depth data at the end of a render. */ 77 bool bDiscardFrameStencil; /*!< Discard stencil data at the end of a render. */ 78 79 // Internal Data 80 bool bShellPosWasDefault; /*!< Internal. Default position for the shell was used. */ 81 int nShellCurFrameNum; /*!< Internal. Current frame number. */ 82 #ifdef PVRSHELL_FPS_OUTPUT 83 bool bOutputFPS; /*!< Output frames per second. */ 84 #endif 85 }; 86 87 /*!*************************************************************************** 88 @class PVRShellCommandLine 89 @brief Command-line interpreter 90 *****************************************************************************/ 91 class PVRShellCommandLine 92 { 93 public: 94 char *m_psOrig, *m_psSplit; 95 SCmdLineOpt *m_pOpt; 96 int m_nOptLen, m_nOptMax; 97 98 public: 99 /*!*********************************************************************** 100 @brief Constructor 101 *************************************************************************/ 102 PVRShellCommandLine(); 103 104 /*!*********************************************************************** 105 @brief Destructor 106 *************************************************************************/ 107 ~PVRShellCommandLine(); 108 109 /*!*********************************************************************** 110 @brief Set command-line options to pStr 111 @param[in] pStr Input string 112 *************************************************************************/ 113 void Set(const char *pStr); 114 115 /*!*********************************************************************** 116 @brief Prepend command-line options to m_psOrig 117 @param[in] pStr Input string 118 *************************************************************************/ 119 void Prefix(const char *pStr); 120 121 /*!*********************************************************************** 122 @brief Prepend command-line options to m_psOrig from a file 123 @param[in] pFileName Input string 124 *************************************************************************/ 125 bool PrefixFromFile(const char *pFileName); 126 127 /*!*********************************************************************** 128 @brief Parse m_psOrig for command-line options and store them in m_pOpt 129 *************************************************************************/ 130 void Parse(); 131 132 /*!*********************************************************************** 133 @brief Apply the command-line options to shell 134 @param[in] shell 135 *************************************************************************/ 136 void Apply(PVRShell &shell); 137 }; 138 139 /*!**************************************************************************** 140 @enum EPVRShellState 141 @brief Current Shell state 142 *****************************************************************************/ 143 enum EPVRShellState { 144 ePVRShellInitApp, /*!< Initialise app */ 145 ePVRShellInitInstance, /*!< Initialise instance */ 146 ePVRShellRender, /*!< Render */ 147 ePVRShellReleaseView, /*!< Release View */ 148 ePVRShellReleaseAPI, /*!< Release API */ 149 ePVRShellReleaseOS, /*!< Release Operating System */ 150 ePVRShellQuitApp, /*!< Quit App */ 151 ePVRShellExit /*!< Exit */ 152 }; 153 154 /*!*************************************************************************** 155 @class PVRShellInit 156 @brief The PVRShell initialisation class 157 ****************************************************************************/ 158 class PVRShellInit : public PVRShellInitAPI, public PVRShellInitOS 159 { 160 public: 161 friend class PVRShell; 162 friend class PVRShellInitOS; 163 friend class PVRShellInitAPI; 164 165 PVRShell *m_pShell; /*!< Our PVRShell class */ 166 PVRShellCommandLine m_CommandLine; /*!< Our Command-line class */ 167 168 bool gShellDone; /*!< Indicates that the application has finished */ 169 EPVRShellState m_eState; /*!< Current PVRShell state */ 170 171 // Key handling 172 PVRShellKeyName nLastKeyPressed; /*!< Holds the last key pressed */ 173 PVRShellKeyName m_eKeyMapLEFT; /*!< Holds the value to be returned when PVRShellKeyNameLEFT is requested */ 174 PVRShellKeyName m_eKeyMapUP; /*!< Holds the value to be returned when PVRShellKeyNameUP is requested */ 175 PVRShellKeyName m_eKeyMapRIGHT; /*!< Holds the value to be returned when PVRShellKeyNameRIGHT is requested */ 176 PVRShellKeyName m_eKeyMapDOWN; /*!< Holds the value to be returned when PVRShellKeyNameDOWN is requested */ 177 178 // Read and Write path 179 char *m_pReadPath; /*!<Holds the path where the application will read the data from */ 180 char *m_pWritePath; /*!<Holds the path where the application will write the data to */ 181 182 #ifdef PVRSHELL_FPS_OUTPUT 183 // Frames per second (FPS) 184 int m_i32FpsFrameCnt, m_i32FpsTimePrev; 185 #endif 186 187 public: 188 189 protected: 190 float m_vec2PointerLocation[2]; 191 float m_vec2PointerLocationStart[2]; 192 float m_vec2PointerLocationEnd[2]; 193 194 // Touch handling 195 bool m_bTouching; 196 197 public: 198 /*!*********************************************************************** 199 @brief Constructor 200 *************************************************************************/ 201 PVRShellInit(); 202 203 /*!*********************************************************************** 204 @brief Destructor 205 *************************************************************************/ 206 ~PVRShellInit(); 207 208 /*!*********************************************************************** 209 @brief PVRShell Initialisation. 210 @return True on success and false on failure 211 *************************************************************************/ 212 bool Init(); 213 214 /*!*********************************************************************** 215 @brief PVRShell Deinitialisation. 216 *************************************************************************/ 217 void Deinit(); 218 219 /*!*********************************************************************** 220 @param[in] str A string containing the command-line 221 @brief Receives the command-line from the application. 222 *************************************************************************/ 223 void CommandLine(const char *str); 224 225 /*!*********************************************************************** 226 @brief Receives the command-line from the application. 227 @param[in] argc Number of strings in argv 228 @param[in] argv An array of strings 229 *************************************************************************/ 230 void CommandLine(int argc, char **argv); 231 232 /*!*********************************************************************** 233 @brief Return 'true' if the specific key has been pressed. 234 @param[in] key The key we're querying for 235 *************************************************************************/ 236 bool DoIsKeyPressed(const PVRShellKeyName key); 237 238 /*!*********************************************************************** 239 @param[in] key The key that has been pressed 240 @brief Used by the OS-specific code to tell the Shell that a key has been pressed. 241 *************************************************************************/ 242 void KeyPressed(PVRShellKeyName key); 243 244 /*!*********************************************************************** 245 @brief Used by the OS-specific code to tell the Shell that a touch has began at a location. 246 @param[in] vec2Location The position of a click/touch on the screen when it first touches. 247 *************************************************************************/ 248 void TouchBegan(const float vec2Location[2]); 249 250 /*!*********************************************************************** 251 @brief Used by the OS-specific code to tell the Shell that a touch has began at a location. 252 @param[in] vec2Location The position of the pointer/touch pressed on the screen. 253 *************************************************************************/ 254 void TouchMoved(const float vec2Location[2]); 255 256 /*!*********************************************************************** 257 @brief Used by the OS-specific code to tell the Shell that the current touch has ended at a location. 258 @param[in] vec2Location The position of the pointer/touch on the screen when it is released. 259 *************************************************************************/ 260 void TouchEnded(const float vec2Location[2]); 261 262 /*!*********************************************************************** 263 @brief Used by the OS-specific code to tell the Shell where to read external files from. 264 @return A path the application is capable of reading from. 265 *************************************************************************/ 266 const char *GetReadPath() const; 267 268 /*!*********************************************************************** 269 @brief Used by the OS-specific code to tell the Shell where to write to. 270 @return A path the applications is capable of writing to 271 *************************************************************************/ 272 const char *GetWritePath() const; 273 274 /*!****************************************************************************** 275 @brief Sets the default app name (to be displayed by the OS) 276 @param[in] str The application name 277 *******************************************************************************/ 278 void SetAppName(const char * const str); 279 280 /*!*********************************************************************** 281 @brief Set the path to where the application expects to read from. 282 @param[in] str The read path 283 *************************************************************************/ 284 void SetReadPath(const char * const str); 285 286 /*!*********************************************************************** 287 @brief Set the path to where the application expects to write to. 288 @param[in] str The write path 289 *************************************************************************/ 290 void SetWritePath(const char * const str); 291 292 /*!*********************************************************************** 293 @brief Called from the OS-specific code to perform the render. 294 When this function fails the application will quit. 295 *************************************************************************/ 296 bool Run(); 297 298 /*!*********************************************************************** 299 @brief When prefOutputInfo is set to true this function outputs 300 various pieces of non-API dependent information via 301 PVRShellOutputDebug. 302 *************************************************************************/ 303 void OutputInfo(); 304 305 /*!*********************************************************************** 306 @brief When prefOutputInfo is set to true this function outputs 307 various pieces of API dependent information via 308 PVRShellOutputDebug. 309 *************************************************************************/ 310 void OutputAPIInfo(); 311 312 #ifdef PVRSHELL_FPS_OUTPUT 313 /*!**************************************************************************** 314 @brief Calculates a value for frames-per-second (FPS). 315 *****************************************************************************/ 316 void FpsUpdate(); 317 #endif 318 319 /* 320 OS functionality 321 */ 322 323 /*!*********************************************************************** 324 @brief Initialisation for OS-specific code. 325 *************************************************************************/ 326 void OsInit(); 327 328 /*!*********************************************************************** 329 @brief Saves instance handle and creates main window 330 In this function, we save the instance handle in a global variable and 331 create and display the main program window. 332 *************************************************************************/ 333 bool OsInitOS(); 334 335 /*!*********************************************************************** 336 @brief Destroys main window 337 *************************************************************************/ 338 void OsReleaseOS(); 339 340 /*!*********************************************************************** 341 @brief Destroys main window 342 *************************************************************************/ 343 void OsExit(); 344 345 /*!*********************************************************************** 346 @brief Perform API initialization and bring up window / fullscreen 347 *************************************************************************/ 348 bool OsDoInitAPI(); 349 350 /*!*********************************************************************** 351 @brief Clean up after we're done 352 *************************************************************************/ 353 void OsDoReleaseAPI(); 354 355 /*!*********************************************************************** 356 @brief Main message loop / render loop 357 *************************************************************************/ 358 void OsRenderComplete(); 359 360 /*!*********************************************************************** 361 @brief When using pixmaps, copy the render to the display 362 *************************************************************************/ 363 bool OsPixmapCopy(); 364 365 /*!*********************************************************************** 366 @brief Called from InitAPI() to get the NativeDisplayType 367 *************************************************************************/ 368 void *OsGetNativeDisplayType(); 369 370 /*!*********************************************************************** 371 @brief Called from InitAPI() to get the NativePixmapType 372 *************************************************************************/ 373 void *OsGetNativePixmapType(); 374 375 /*!*********************************************************************** 376 @brief Called from InitAPI() to get the NativeWindowType 377 *************************************************************************/ 378 void *OsGetNativeWindowType(); 379 380 /*!*********************************************************************** 381 @brief Retrieves OS-specific data 382 @param[in] prefName Name of preference to get 383 @param[out] pn A pointer set to the preference. 384 @return true on success 385 *************************************************************************/ 386 bool OsGet(const prefNameIntEnum prefName, int *pn); 387 388 /*!*********************************************************************** 389 @brief Retrieves OS-specific data 390 @param[in] prefName Name of value to get 391 @param[out] pp A pointer set to the value asked for 392 @return true on success 393 *************************************************************************/ 394 bool OsGet(const prefNamePtrEnum prefName, void **pp); 395 396 /*!*********************************************************************** 397 @brief Sets OS-specific data 398 @param[in] prefName Name of preference to set to value 399 @param[in] value Value 400 @return true for success 401 *************************************************************************/ 402 bool OsSet(const prefNameBoolEnum prefName, const bool value); 403 404 /*!*********************************************************************** 405 @brief Sets OS-specific data 406 @param[in] prefName Name of value to set 407 @param[in] i32Value The value to set our named value to 408 @return true on success 409 *************************************************************************/ 410 bool OsSet(const prefNameIntEnum prefName, const int i32Value); 411 412 /*!*********************************************************************** 413 @brief Prints a debug string 414 @param[in] str The debug string to display 415 *************************************************************************/ 416 void OsDisplayDebugString(char const * const str); 417 418 /*!*********************************************************************** 419 @brief Gets the time in milliseconds 420 *************************************************************************/ 421 unsigned long OsGetTime(); 422 423 /* 424 API functionality 425 */ 426 /*!*********************************************************************** 427 @brief Initialisation for API-specific code. 428 *************************************************************************/ 429 bool ApiInitAPI(); 430 431 /*!*********************************************************************** 432 @brief Releases all resources allocated by the API. 433 *************************************************************************/ 434 void ApiReleaseAPI(); 435 436 /*!*********************************************************************** 437 @brief API-specific function to store the current content of the 438 FrameBuffer into the memory allocated by the user. 439 @param[in] Width Width of the region to capture 440 @param[in] Height Height of the region to capture 441 @param[out] pBuf A buffer to put the screen capture into 442 @return true on success 443 *************************************************************************/ 444 bool ApiScreenCaptureBuffer(int Width,int Height,unsigned char *pBuf); 445 446 /*!*********************************************************************** 447 @brief Perform API operations required after a frame has finished (e.g., flipping). 448 *************************************************************************/ 449 void ApiRenderComplete(); 450 451 /*!*********************************************************************** 452 @brief Set preferences which are specific to the API. 453 @param[in] prefName Name of preference to set 454 @param[out] i32Value Value to set it to 455 *************************************************************************/ 456 bool ApiSet(const prefNameIntEnum prefName, const int i32Value); 457 458 /*!*********************************************************************** 459 @brief Get parameters which are specific to the API. 460 @param[in] prefName Name of value to get 461 @param[out] pn A pointer set to the value asked for 462 *************************************************************************/ 463 bool ApiGet(const prefNameIntEnum prefName, int *pn); 464 465 /*!*********************************************************************** 466 @brief Get parameters which are specific to the API. 467 @param[in] prefName Name of value to get 468 @param[out] pp A pointer set to the value asked for 469 *************************************************************************/ 470 bool ApiGet(const prefNamePtrEnum prefName, void **pp); 471 472 473 /*!*********************************************************************** 474 @brief Run specific API code to perform the operations requested in preferences. 475 *************************************************************************/ 476 void ApiActivatePreferences(); 477 }; 478 479 #endif /* __PVRSHELLIMPL_H_ */ 480 481 /***************************************************************************** 482 End of file (PVRShellImpl.h) 483 *****************************************************************************/ 484 485