PowerVR Software Development Kit


Main Page | Class Hierarchy | Class List | File List | Class Members | File Members

PVRShell.h

Go to the documentation of this file.
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.


Generated by DOXYGEN 1.3.6