PowerVR Software Development Kit |
00001 /*!***************************************************************************** 00002 00003 @File PVRShell.h 00004 00005 @Brief Shell to make programming 3D APIs easier. 00006 00007 @Copyright Copyright (C) 2005 - 2006 by Imagination Technologies Limited. 00008 00009 @Platform Independant 00010 00011 @Description Makes programming for 3D APIs easier by wrapping surface 00012 initialization, Texture allocation and other functions for use by a demo. 00013 00014 ******************************************************************************/ 00015 /*****************************************************************************/ 00163 #ifndef __PVRSHELL_H_ 00164 #define __PVRSHELL_H_ 00165 00166 /***************************************************************************** 00167 ** Includes 00168 *****************************************************************************/ 00169 #include <stdlib.h> 00170 00171 /* The following defines are for Windows PC platforms only */ 00172 #if defined(WIN32) && !defined(UNDER_CE) 00173 /* Enable the following 2 lines for memory leak checking - also see WinMain() */ 00174 #define _CRTDBG_MAP_ALLOC 00175 #include <crtdbg.h> 00176 #endif 00177 00178 /* Pocket PC and WinCE 5.0 only */ 00179 #ifdef UNDER_CE 00180 #ifdef DEBUG 00181 #define _ASSERT(X) { (X) ? 0 : DebugBreak(); } 00182 #define _ASSERTE _ASSERT 00183 #else 00184 #define _ASSERT(X) /* */ 00185 #define _ASSERTE(X) /* */ 00186 #endif 00187 #endif 00188 00189 #define EXIT_NOERR_CODE 0 00190 #define EXIT_ERR_CODE (!EXIT_NOERR_CODE) 00191 00192 /*!*********************************************************************** 00193 * Keyboard mapping. 00194 ************************************************************************/ 00195 enum PVRShellKeyName 00196 { 00197 PVRShellKeyNameNull, 00198 PVRShellKeyNameQUIT, 00199 PVRShellKeyNameSELECT, 00200 PVRShellKeyNameACTION1, 00201 PVRShellKeyNameACTION2, 00202 PVRShellKeyNameUP, 00203 PVRShellKeyNameDOWN, 00204 PVRShellKeyNameLEFT, 00205 PVRShellKeyNameRIGHT, 00206 PVRShellKeyNameScreenshot 00207 }; 00208 /*!*********************************************************************** 00209 * @Enum prefNameBoolEnum 00210 * @Brief Boolean Shell preferences. 00211 ************************************************************************/ 00212 enum prefNameBoolEnum 00213 { 00214 prefFullScreen, 00215 prefIsRotated, 00216 prefPBufferContext, 00217 prefPixmapContext, 00218 prefPixmapDisableCopy, 00219 prefZbufferContext, 00220 prefLockableBackBuffer, 00221 prefSoftwareRendering, 00222 prefStencilBufferContext, 00223 prefOpenVGContext 00224 }; 00225 00226 /*!*********************************************************************** 00227 * @Enum prefNameFloatEnum 00228 * @Brief Float Shell preferences. 00229 ************************************************************************/ 00230 enum prefNameFloatEnum 00231 { 00232 prefQuitAfterTime 00233 }; 00234 00235 /*!*********************************************************************** 00236 * @Enum prefNameIntEnum 00237 * @Brief Integer Shell preferences. 00238 ************************************************************************/ 00239 enum prefNameIntEnum 00240 { 00241 prefWidth, 00242 prefHeight, 00243 prefPositionX, 00244 prefPositionY, 00245 prefQuitAfterFrame, 00246 prefSwapInterval, 00247 prefInitRepeats, 00248 prefFSAAMode, 00249 prefCommandLineOptNum 00250 }; 00251 00252 /*!*********************************************************************** 00253 * @Enum prefNamePtrEnum 00254 * @Brief Pointers/Handlers Shell preferences. 00255 ************************************************************************/ 00256 enum prefNamePtrEnum 00257 { 00258 prefD3DDevice, 00259 prefHINSTANCE, 00260 prefNativeWindowType 00261 }; 00262 00263 /*!*********************************************************************** 00264 * @Enum prefNameConstPtrEnum 00265 * @Brief Constant pointers Shell preferences. 00266 ************************************************************************/ 00267 enum prefNameConstPtrEnum 00268 { 00269 prefAppName, 00270 prefDataPath, 00271 prefCommandLine, 00272 prefCommandLineOpts, 00273 prefExitMessage, 00274 prefVersion 00275 }; 00276 00277 /**************************************************************************** 00278 PVRShell implementation Prototypes and definitions 00279 *****************************************************************************/ 00280 00281 struct PVRShellData; 00282 00283 /*!*************************************************************************** 00284 * @Class PVRShellInit 00285 * @Brief main PVRShell class for initialisation 00286 *****************************************************************************/ 00287 class PVRShellInit; 00288 00289 /*!*********************************************************************** 00290 * @Struct SCmdLineOpt 00291 * @Brief Stores a variable name/value pair for an individual command-line option. 00292 ************************************************************************/ 00293 struct SCmdLineOpt 00294 { 00295 const char *pArg, *pVal; 00296 }; 00297 00298 /*!*************************************************************************** 00299 * @Class PVRShell 00300 * @Brief Inherited by the application; responsible for abstracting the OS and API. 00301 * @Description 00302 * PVRShell is the main Shell class that an application uses. An 00303 * application should supply a class which inherits PVRShell and supplies 00304 * implementations of the virtual functions of PVRShell (InitApplication(), 00305 * QuitApplication(), InitView(), ReleaseView(), RenderScene()). Default stub 00306 * functions are supplied; this means that an application is not 00307 * required to supply a particular function if it does not need to do anything 00308 * in it. 00309 * The other, non-virtual, functions of PVRShell are utility functions that the 00310 * application may call. 00311 *****************************************************************************/ 00312 class PVRShell 00313 { 00314 public: 00315 friend class PVRShellInitOS; 00316 friend class PVRShellInit; 00317 00318 private: 00319 PVRShellData *m_pShellData; 00320 PVRShellInit *m_pShellInit; 00321 00322 public: 00323 /*!*********************************************************************** 00324 @Function PVRShell 00325 @Description Constructor 00326 *************************************************************************/ 00327 PVRShell(); 00328 00329 /*!*********************************************************************** 00330 @Function ~PVRShell 00331 @Description Destructor 00332 *************************************************************************/ 00333 virtual ~PVRShell(); 00334 00335 /* 00336 PVRShell functions that the application should implement. 00337 */ 00338 00339 /*!*********************************************************************** 00340 @Function InitApplication 00341 @Return true for success, false to exit the application 00342 @Description This function can be overloaded by the application. It 00343 will be called by PVRShell once only at the beginning of 00344 the PVRShell WinMain()/main() function. This function 00345 enables the user to perform any initialisation before the 00346 render API is initialised. From this function the user can 00347 call PVRShellSet() to change default values, e.g. 00348 requesting a particular resolution or device setting. 00349 *************************************************************************/ 00350 virtual bool InitApplication() { return true; }; 00351 00352 /*!*********************************************************************** 00353 @Function QuitApplication 00354 @Return true for success, false to exit the application 00355 @Description This function can be overloaded by the application. It 00356 will be called by PVRShell just before finishing the 00357 program. It enables the application to release any 00358 memory/resources acquired in InitApplication(). 00359 *************************************************************************/ 00360 virtual bool QuitApplication() { return true; }; 00361 00362 /*!*********************************************************************** 00363 @Function InitView 00364 @Return true for success, false to exit the application 00365 @Description This function can be overloaded by the application. It 00366 will be called by PVRShell after the OS and rendering API 00367 are initialised, before entering the RenderScene() loop. 00368 It is called any time the rendering API is initialised, 00369 i.e. once at the beginning, and possibly again if the 00370 resolution changes, or a power management even occurs, or 00371 if the app requests a reinialisation. 00372 The application should check here the configuration of 00373 the rendering API; it is possible that requests made in 00374 InitApplication() were not successful. 00375 Since everything is initialised when this function is 00376 called, you can load textures and perform rendering API 00377 functions. 00378 *************************************************************************/ 00379 virtual bool InitView() { return true; }; 00380 00381 /*!*********************************************************************** 00382 @Function ReleaseView 00383 @Return true for success, false to exit the application 00384 @Description This function can be overloaded by the application. It 00385 will be called after the RenderScene() loop, before 00386 shutting down the render API. It enables the application 00387 to release any memory/resources acquired in InitView(). 00388 *************************************************************************/ 00389 virtual bool ReleaseView() { return true; }; 00390 00391 /*!*********************************************************************** 00392 @Function RenderScene 00393 @Return true for success, false to exit the application 00394 @Description This function can be overloaded by the application. 00395 It is main application function in which you have to do your own rendering. Will be 00396 called repeatedly until the application exits. 00397 *************************************************************************/ 00398 virtual bool RenderScene() { return true; }; 00399 00400 /* 00401 PVRShell functions available for the application to use. 00402 */ 00403 00404 /*!*********************************************************************** 00405 @Function PVRShellSet 00406 @Input prefName Name of preference to set to value 00407 @Input value Boolean value 00408 @Return true for success 00409 @Description This function is used to pass preferences to the PVRShell 00410 If used, it must be called from InitApplication(). 00411 *************************************************************************/ 00412 bool PVRShellSet(const prefNameBoolEnum prefName, const bool value); 00413 bool PVRShellSet(const prefNameFloatEnum prefName, const float value); 00414 bool PVRShellSet(const prefNameIntEnum prefName, const int value); 00415 bool PVRShellSet(const prefNamePtrEnum prefName, const void * const ptrValue); 00416 bool PVRShellSet(const prefNameConstPtrEnum prefName, const void * const ptrValue); 00417 00418 /*!*********************************************************************** 00419 @Function PVRShellGet 00420 @Input prefName Name of preference to set to value 00421 @Return Value asked for. 00422 @Description This function is used to get parameters from the PVRShell 00423 It can be called from any where in the program. 00424 *************************************************************************/ 00425 bool PVRShellGet(const prefNameBoolEnum prefName) const; 00426 float PVRShellGet(const prefNameFloatEnum prefName) const; 00427 int PVRShellGet(const prefNameIntEnum prefName) const; 00428 void *PVRShellGet(const prefNamePtrEnum prefName) const; 00429 const void *PVRShellGet(const prefNameConstPtrEnum prefName) const; 00430 00431 /*!*********************************************************************** 00432 @Function PVRShellScreenCaptureBuffer 00433 @Input Width size of image to capture (relative to 0,0) 00434 @Input Height size of image to capture (relative to 0,0) 00435 @Modified pLines receives a pointer to an area of memory containing the screen buffer. 00436 @Return true for success 00437 @Description It will be stored as 24-bit per pixel, 8-bit per chanel RGB. The 00438 memory should be freed with free() when no longer needed. 00439 *************************************************************************/ 00440 bool PVRShellScreenCaptureBuffer(const int Width, const int Height, unsigned char **pLines); 00441 00442 /*!*********************************************************************** 00443 @Function PVRShellScreenSave 00444 @Input fname base of file to save screen to 00445 @Output ofname If non-NULL, receives the filename actually used 00446 @Modified pLines image data to write out (24bpp, 8-bit per channel RGB) 00447 @Return true for success 00448 @Description Writes out the image data to a BMP file with basename 00449 fname. The file written will be fname suffixed with a 00450 number to make the file unique. 00451 For example, if fname is "abc", this function will attempt 00452 to save to "abc0000.bmp"; if that file already exists, it 00453 will try "abc0001.bmp", repeating until a new filename is 00454 found. The final filename used is returned in ofname. 00455 *************************************************************************/ 00456 int PVRShellScreenSave( 00457 const char * const fname, 00458 const unsigned char * const pLines, 00459 char * const ofname = NULL); 00460 00461 /*!*********************************************************************** 00462 @Function PVRShellWriteBMPFile 00463 @Input pszFilename file to save screen to 00464 @Input uWidth the width of the data 00465 @Input uHeight the height of the data 00466 @Input pImageData image data to write out (24bpp, 8-bit per channel RGB) 00467 @Return success or failure 00468 @Description Writes out the image data to a BMP file with name fname. 00469 *************************************************************************/ 00470 int PVRShellWriteBMPFile( 00471 const char * const pszFilename, 00472 const unsigned long uWidth, 00473 const unsigned long uHeight, 00474 const void * const pImageData); 00475 00476 /*!*********************************************************************** 00477 @Function PVRShellOutputDebug 00478 @Input format printf style format followed by arguments it requires 00479 @Description Writes the resultant string to the debug output (e.g. using 00480 printf(), OutputDebugString(), ...). Check the SDK release notes for 00481 details on how the string is output. 00482 *************************************************************************/ 00483 void PVRShellOutputDebug(char const * const format, ...) const; 00484 00485 /*!*********************************************************************** 00486 @Function PVRShellGetTime 00487 @Returns A value which increments once per millisecond. 00488 @Description The number itself should be considered meaningless; an 00489 application should use this function to determine how much 00490 time has passed between two points (e.g. between each 00491 frame). 00492 *************************************************************************/ 00493 unsigned long PVRShellGetTime(); 00494 00495 /*!*********************************************************************** 00496 @Function PVRShellIsKeyPressed 00497 @Input key Code of the key to test 00498 @Return true if key was pressed 00499 @Description Check if a key was pressed. The keys on various devices 00500 are mapped to the PVRShell-supported keys (listed in @a PVRShellKeyName) in 00501 a platform-dependent manner, since most platforms have different input 00502 devices. Check the SDK release notes for details on how the enum values 00503 map to your device's input device. 00504 *************************************************************************/ 00505 bool PVRShellIsKeyPressed(const PVRShellKeyName key); 00506 }; 00507 00508 /**************************************************************************** 00509 ** Declarations for functions that the scene file must supply 00510 ****************************************************************************/ 00511 00512 /*!*************************************************************************** 00513 @Function NewDemo 00514 @Return The demo supplied by the user 00515 @Description This function must be implemented by the user of the shell. 00516 The user should return its PVRShell object defining the 00517 behaviour of the application 00518 *****************************************************************************/ 00519 PVRShell* NewDemo(); 00520 00521 #endif /* __PVRSHELL_H_ */ 00522 00523 /***************************************************************************** 00524 End of file (PVRShell.h) 00525 *****************************************************************************/
Copyright © 1999-2006, PowerVR Technologies and partners. PowerVR Technologies is a division of Imagination Technologies Ltd.