third_party/PowerVR_SDK/Shell/PVRShell.h

/*!****************************************************************************

 @file       Shell/PVRShell.h
 @copyright  Copyright (c) Imagination Technologies Limited.
 @brief      Makes programming for 3D APIs easier by wrapping surface
             initialization, Texture allocation and other functions for use by a demo.

******************************************************************************/

#ifndef __PVRSHELL_H_
#define __PVRSHELL_H_

/*****************************************************************************/
/*! @mainpage PVRShell
******************************************************************************

 @tableofcontents 
 
 @section overview Overview
 *****************************

 PVRShell is a C++ class used to make programming for PowerVR platforms easier and more portable.
 PVRShell takes care of all API and OS initialisation for the user and handles adapters, devices, screen/windows modes,
 resolution, buffering, depth-buffer, viewport creation & clearing, etc...

 PVRShell consists of 3 files: PVRShell.cpp, PVRShellOS.cpp and PVRShellAPI.cpp.

 PVRShellOS.cpp and PVRShellAPI.cpp are supplied per platform and contain all the code to initialise the specific
 API (OpenGL ES, Direct3D Mobile, etc.) and the OS (Windows, Linux, WinCE, etc.).
 PVRShell.cpp is where the common code resides and it interacts with the user application through an abstraction layer.

 A new application must link to these three files and must create a class that will inherit the PVRShell class.
 This class will provide five virtual functions to interface with the user.

 The user also needs to register his application class through the NewDemo function:

 @code
 class MyApplication: public PVRShell
 {
 public:
     virtual bool InitApplication();
     virtual bool InitView();
     virtual bool ReleaseView();
     virtual bool QuitApplication();
     virtual bool RenderScene();
 };

 PVRShell* NewDemo()
 {
     return new MyApplication();
 }
 @endcode
 

 @section interface Interface
 ******************************

 There are two functions for initialisation, two functions to release allocated resources and a render function:

 InitApplication() will be called by PVRShell once per run, before the graphic context is created.
 It is used to initialise variables that are not dependant on the rendering context (e.g. external modules, loading user data, etc.).
 QuitApplication() will be called by PVRShell once per run, just before exiting the program.
 If the graphic context is lost, QuitApplication() will not be called.

 InitView() will be called by PVRShell upon creation or change in the rendering context.
 It is used to initialise variables that are dependant on the rendering context (e.g. textures, vertex buffers, etc.).
 ReleaseView() will be called by PVRShell before changing to a new rendering context or
 when finalising the application (before calling QuitApplication).

 RenderScene() is the main rendering loop function of the program. This function must return FALSE when the user wants to terminate the application.
 PVRShell will call this function every frame and will manage relevant OS events.

 There are other PVRShell functions which allow the user to set his/her preferences and get data back from the devices:

 PVRShellSet() and PVRShellGet() are used to pass data to and from PVRShell. PVRShellSet() is recommended to be used
 in InitApplication() so the user preferences are applied at the API initialisation.
 There is a definition of these functions per type of data passed or returned. Please check the prefNameBoolEnum, prefNameFloatEnum,
 prefNameIntEnum, prefNamePtrEnum and prefNameConstPtrEnum enumerations for a full list of the data available.

 This is an example:

 @code
 bool MyApplication::InitApplication()
 {
     PVRShellSet (prefFullScreen, true);
 }

 bool MyApplication::RenderScene()
 {
     int dwCurrentWidth = PVRShellGet (prefHeight);
     int dwCurrentHeight = PVRShellGet (prefWidth);

     return true;
 }
 @endcode

 
 @section helper Helper functions
 *************************************

 The user input is abstracted with the PVRShellIsKeyPressed() function. It will not work in all devices, but we have tried to map the most
 relevant keys when possible. See PVRShellKeyName enumeration for the list of keys supported. This function will return true or false depending on
 the specified key being pressed.

 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
 save a screen-shot of the current frame:

 PVRShellGetTime() returns time in milliseconds.

 PVRShellOutputDebug() will write a debug string (same format as printf) to the platform debug output.

 PVRShellScreenCaptureBuffer() and  PVRShellWriteBMPFile() will be used to save the current frame as a BMP file. PVRShellScreenCaptureBuffer()
 receives a pointer to an area of memory containing the screen buffer. The memory should be freed with free() when not needed any longer.

 Example of screenshot:

 @code
 bool MyApplication::RenderScene()
 {
     [...]

     unsigned char *pLines;

     PVRShellScreenCaptureBuffer(PVRShellGet (prefWidth), PVRShellGet (prefHeight), &pLines);

     PVRShellScreenSave("myfile", pLines, NULL);

     free (pLines);

     return true;
 }
 @endcode

 
 @section cmd Command-line
 *************************************

 Across all platforms, PVRShell takes a set of command-line arguments which allow things like the position and size of the demo
 to be controlled. The list below shows these options.

 \b -width=N   Sets the horizontal viewport width to N.

 \b -height=N   Sets the vertical viewport height to N.

 \b -posx=N   Sets the x coordinate of the viewport.

 \b -posy=N   Sets the y coordinate of the viewport.

 \b -aasamples=N   Sets the number of samples to use for full screen anti-aliasing. e.g 0, 2, 4, 8

 \b -fullscreen=N   Enable/Disable fullscreen mode. N can be: 0=Windowed 1=Fullscreen.

 \b -qat=N   Quits after N seconds.

 \b -qaf=N   Quits after N frames.

 \b -powersaving=N Where available enable/disable power saving. N can be: 0=Disable power saving 1=Enable power saving.

 \b -vsync=N Where available modify the apps vsync parameters.

 \b -version Output the SDK version to the debug output.

 \b -info Output setup information (e.g. window width) to the debug output.

 \b -rotatekeys=N Sets the orientation of the keyboard input. N can be: 0-3, 0 is no rotation.

 \b -c=N Save a single screenshot or a range. e.g. -c=1-10, -c=14.

 \b -priority=N EGL only. Sets the priority of the EGL context.

 \b -colourbpp=N EGL only. When choosing an EGL config N will be used as the value for EGL_BUFFER_SIZE.

 \b -depthbpp=N EGL only. When choosing an EGL config N will be used as the value for EGL_DEPTH_SIZE.

 \b -config=N EGL only. Force the shell to use the EGL config with ID N.

 \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.

 Example:
 @code
     Demo -width=160 -height=120 -qaf=300
 @endcode

 @section APIsOSs APIs and Operating Systems
 *****************************
 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.
 
******************************************************************************/
// Uncomment to enable the -fps command-line option
// #define PVRSHELL_FPS_OUTPUT

/*****************************************************************************
** Includes
*****************************************************************************/
#include <stdlib.h>

#define EXIT_NOERR_CODE 0
#define EXIT_ERR_CODE (!EXIT_NOERR_CODE)

// avoid warning about unused parameter
#define PVRSHELL_UNREFERENCED_PARAMETER(x) ((void) x)

// Keyboard mapping. //
 
/*!***********************************************************************
 @enum PVRShellKeyName
 @brief Key name.
 ************************************************************************/ 
enum PVRShellKeyName
{
    PVRShellKeyNameNull,        /*!< Null key value */
    PVRShellKeyNameQUIT,        /*!< QUIT key value */
    PVRShellKeyNameSELECT,      /*!< SELECT key value */
    PVRShellKeyNameACTION1,     /*!< ACTION1 key value */
    PVRShellKeyNameACTION2,     /*!< ACTION2 key value */
    PVRShellKeyNameUP,          /*!< UP key */
    PVRShellKeyNameDOWN,        /*!< DOWN key */
    PVRShellKeyNameLEFT,        /*!< LEFT key */
    PVRShellKeyNameRIGHT,       /*!< RIGHT key */
    PVRShellKeyNameScreenshot   /*!< SCREENSHOT key */
};

/*!***********************************************************************
 @enum PVRShellKeyRotate
 @brief Key rotate.
 ************************************************************************/ 
enum PVRShellKeyRotate
{
    PVRShellKeyRotateNone=0,    /*!< Rotate key none = 0. */ 
    PVRShellKeyRotate90,        /*!< Rotate key 90 */
    PVRShellKeyRotate180,       /*!< Rotate key 180 */
    PVRShellKeyRotate270        /*!< Rotate key 270 */
};

//  Pointer button mapping. //
 
/*!***********************************************************************
 @enum EPVRShellButtonState
 @brief Pointer button mapping.
 ************************************************************************/ 
enum EPVRShellButtonState
{
    ePVRShellButtonLeft = 0x1,  /*!< Left button */
    ePVRShellButtonRight = 0x2, /*!< Right button */
    ePVRShellButtonMiddle = 0x4 /*!< Middle button */
};

/*!***********************************************************************
 @enum prefNameBoolEnum
 @brief Boolean Shell preferences.
 ************************************************************************/
enum prefNameBoolEnum
{
    prefFullScreen,             /*!< Set to: 1 for full-screen rendering; 0 for windowed */
    prefIsRotated,              /*!< Query this to learn whether screen is rotated */
    prefPBufferContext,         /*!< 1 if you need pbuffer support (default is pbuffer not needed) */
    prefPixmapContext,          /*!< 1 to use a pixmap as a render-target (default off) */
    prefPixmapDisableCopy,      /*!< 1 to disable the copy if pixmaps are used */
    prefZbufferContext,         /*!< 1 if you wish to have zbuffer support (default to on) */
    prefLockableBackBuffer,     /*!< DX9 only: true to use D3DPRESENTFLAG_LOCKABLE_BACKBUFFER (default: false) */
    prefSoftwareRendering,      /*!< 1 to select software rendering (default: off, i.e. use hardware) */
    prefStencilBufferContext,   /*!< 1 if you wish to have stencil support (default: off) */
    prefAlphaFormatPre,         /*!< EGL only: 1 to create the EGL surface with EGL_ALPHA_FORMAT_PRE (default: 0) */
    prefPowerSaving,            /*!< If true then the app will go into powersaving mode (if available) when not in use. */
#ifdef PVRSHELL_FPS_OUTPUT
    prefOutputFPS,              /*!< If true then the FPS are output using PVRShellOutputdebug */
#endif
    prefOutputInfo,             /*!< If true then the app will output helpful information such as colour buffer format via PVRShellOutputDebug. */
    prefNoShellSwapBuffer,      /*!< EGL: If true then the shell won't call eglswapbuffers at the end of each frame. */
    prefShowCursor,             /*!< Set to: 1 to show the cursor; 0 to hide it. */
    prefForceFrameTime,         /*!< If true will alter PVRShellGetTime behaviour to be frame based. This is for debugging purposes. */
    prefDiscardColor,           /*!< GLES: Whether or not to discard color data at the end of a render, to save bandwidth. Requires specific functionality. (default: false) */
    prefDiscardDepth,           /*!< GLES: Whether or not to discard depth data at the end of a render, to save bandwidth. Requires specific functionality. (default: true) */
    prefDiscardStencil          /*!< GLES: Whether or not to discard stencil data at the end of a render, to save bandwidth. Requires specific functionality. (default: true) */
};

/*!***********************************************************************
 @enum prefNameFloatEnum
 @brief Float Shell preferences.
 ************************************************************************/
enum prefNameFloatEnum
{
    prefQuitAfterTime           /*!< Shell will quit after this number of seconds (-1 to disable) */
};

/*!***********************************************************************
 @enum prefNameIntEnum
 @brief Integer Shell preferences.
 ************************************************************************/
enum prefNameIntEnum
{
    prefEGLMajorVersion,    /*!< EGL: returns the major version as returned by eglInitialize() */
    prefEGLMinorVersion,    /*!< EGL: returns the minor version as returned by eglInitialize() */
    prefWidth,              /*!< Width of render target */
    prefHeight,             /*!< Height of render target */
    prefPositionX,          /*!< X position of the window */
    prefPositionY,          /*!< Y position of the window */
    prefQuitAfterFrame,     /*!< Shell will quit after this number of frames (-1 to disable) */
    prefSwapInterval,       /*!< 0 to preventing waiting for monitor vertical syncs */
    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. */
    prefAASamples,          /*!< Set to: 0 to disable full-screen anti-aliasing; 2 for 2x; 4 for 4x; 8 for 8x. */
    prefCommandLineOptNum,  /*!< Returns the length of the array returned by prefCommandLineOpts */
    prefColorBPP,           /*!< Allows you to specify a desired color buffer size e.g. 16, 32. */
    prefDepthBPP,           /*!< Allows you to specify a desired depth buffer size e.g. 16, 24. */
    prefRotateKeys,         /*!< Allows you to specify and retrieve how the keyboard input is transformed */
    prefButtonState,        /*!< pointer button state */
    prefCaptureFrameStart,  /*!< The frame to start capturing screenshots from */
    prefCaptureFrameStop,   /*!< The frame to stop capturing screenshots at */
    prefCaptureFrameScale,  /*!< Pixel-replicate saved screenshots this many times; default 1 for no scale */
    prefPriority,           /*!< EGL: If supported will set the egl context priority; 0 for low, 1 for med and 2 for high. */
    prefConfig,             /*!< EGL: Get the chosen EGL config. */
    prefRequestedConfig,    /*!< EGL: Force the shell to use a particular EGL config. */
    prefNativeDisplay,      /*!< EGL: Allows you to specify the native display to use if the device has more that one. */
    prefFrameTimeValue      /*!< An integer value to say how long you wish one frame to last for (in ms) when force frame time is enabled. */
};

/*!***********************************************************************
 @enum prefNamePtrEnum
 @brief Pointers/Handlers Shell preferences.
 ************************************************************************/
enum prefNamePtrEnum
{
    prefD3DDevice,          /*!< D3D: returns the device pointer */
    prefEGLDisplay,         /*!< EGL: returns the EGLDisplay */
    prefEGLSurface,         /*!< EGL: returns the EGLSurface */
    prefHINSTANCE,          /*!< Windows: returns the application instance handle */
    prefNativeWindowType,   /*!< Returns the window handle */
    prefAccelerometer,      /*!< Accelerometer values */
    prefPointerLocation,    /*!< Mouse pointer/touch location values */
    prefPVR2DContext,       /*!< PVR2D: returns the PVR2D context */
    prefLoadFileFunc,       /*!< A pointer to a function that can be used to load external files on platforms that don't allow the use of fopen.
                                 The ptr returned is of the type PFNLoadFileFunc defined below. */
    prefReleaseFileFunc,        /*!< A pointer to a function that is used to release any data allocated by the load file function.
                                 The ptr returned is of the type PFNReleaseFileFunc defined below. */
    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. */
};

/*!***********************************************************************
 @typedef PFNLoadFileFunc
 @brief The LoadFileFunc function pointer template.
 ************************************************************************/
typedef void* (*PFNLoadFileFunc)(const char*, char** pData, size_t &size);

/*!***********************************************************************
 @typedef PFNReleaseFileFunc
 @brief The ReleaseFileFunc function pointer template.
 ************************************************************************/
typedef bool (*PFNReleaseFileFunc)(void* handle);

/*!***********************************************************************
 @enum prefNameConstPtrEnum
 @brief Constant pointers Shell preferences.
 ************************************************************************/
enum prefNameConstPtrEnum
{
    prefAppName,            /*!< ptrValue is char* */
    prefReadPath,           /*!< ptrValue is char*; will include a trailing slash */
    prefWritePath,          /*!< ptrValue is char*; will include a trailing slash */
    prefCommandLine,        /*!< used to retrieve the entire application command line */
    prefCommandLineOpts,    /*!< ptrValue is SCmdLineOpt*; retrieves an array of arg/value pairs (parsed from the command line) */
    prefExitMessage,        /*!< ptrValue is char*; gives the shell a message to show on exit, typically an error */
    prefVersion             /*!< ptrValue is char* */
};

/*!**************************************************************************
 @struct PVRShellData
 @brief  PVRShell implementation Prototypes and definitions
*****************************************************************************/
struct PVRShellData;

/*!***************************************************************************
 @class PVRShellInit
 *****************************************************************************/
class PVRShellInit;

/*!***********************************************************************
 @struct SCmdLineOpt
 @brief  Stores a variable name/value pair for an individual command-line option.
 ************************************************************************/
struct SCmdLineOpt
{
    const char *pArg, *pVal;
};

/*!***************************************************************************
 @class    PVRShell
 @brief    Inherited by the application; responsible for abstracting the OS and API.
 @details  PVRShell is the main Shell class that an application uses. An
           application should supply a class which inherits PVRShell and supplies
           implementations of the virtual functions of PVRShell (InitApplication(),
           QuitApplication(), InitView(), ReleaseView(), RenderScene()). Default stub
           functions are supplied; this means that an application is not
           required to supply a particular function if it does not need to do anything
           in it.
           The other, non-virtual, functions of PVRShell are utility functions that the
           application may call.
 *****************************************************************************/
class PVRShell
{
private:
    friend class PVRShellInitOS;
    friend class PVRShellInit;

    PVRShellData    *m_pShellData;
    PVRShellInit    *m_pShellInit;

public:
    /*!***********************************************************************
    @brief      Constructor
    *************************************************************************/
    PVRShell();

    /*!***********************************************************************
    @brief      Destructor
    *************************************************************************/
    virtual ~PVRShell();

    /*
        PVRShell functions that the application should implement.
    */

    /*!***********************************************************************
    @brief      Initialise the application.
    @details    This function can be overloaded by the application. It
                will be called by PVRShell once, only at the beginning of
                the PVRShell WinMain()/main() function. This function
                enables the user to perform any initialisation before the
                render API is initialised. From this function the user can
                call PVRShellSet() to change default values, e.g.
                requesting a particular resolution or device setting.
    @return     true for success, false to exit the application
    *************************************************************************/
    virtual bool InitApplication() { return true; };

    /*!***********************************************************************
    @brief      Quit the application.
    @details    This function can be overloaded by the application. It
                will be called by PVRShell just before finishing the
                program. It enables the application to release any
                memory/resources acquired in InitApplication().
    @return     true for success, false to exit the application
    *************************************************************************/
    virtual bool QuitApplication() { return true; };

    /*!***********************************************************************
    @brief      Initialise the view.
    @details    This function can be overloaded by the application. It
                will be called by PVRShell after the OS and rendering API
                are initialised, before entering the RenderScene() loop.
                It is called any time the rendering API is initialised,
                i.e. once at the beginning, and possibly again if the
                resolution changes, or a power management even occurs, or
                if the app requests a re-initialisation.
                The application should check here the configuration of
                the rendering API; it is possible that requests made in
                InitApplication() were not successful.
                Since everything is initialised when this function is
                called, you can load textures and perform rendering API functions.
    @return     true for success, false to exit the application
    *************************************************************************/
    virtual bool InitView() { return true; };

    /*!***********************************************************************
     @brief     Release the view.
     @details   This function can be overloaded by the application. It
                will be called after the RenderScene() loop, before
                shutting down the render API. It enables the application
                to release any memory/resources acquired in InitView().
     @return    true for success, false to exit the application
    *************************************************************************/
    virtual bool ReleaseView() {  return true; };

    /*!***********************************************************************
     @brief     Render the scene
     @details   This function can be overloaded by the application.
                It is main application function in which you have to do your own rendering.  Will be
                called repeatedly until the application exits.
     @return    true for success, false to exit the application
    *************************************************************************/
    virtual bool RenderScene() { return true; };

    /*
        PVRShell functions available for the application to use.
    */

    /*!***********************************************************************
     @brief     This function is used to pass preferences to the PVRShell.
                If used, this function must be called from InitApplication().
     @param[in] prefName  Name of preference to set to value
     @param[in] value     Value
     @return    true for success
    *************************************************************************/
    bool PVRShellSet(const prefNameBoolEnum prefName, const bool value);

    /*!***********************************************************************
     @brief     This function is used to pass preferences to the PVRShell.
                If used, this function must be called from InitApplication().
     @param[in] prefName    Name of preference to set to value
     @param[in] value       Value
     @return    true for success
    *************************************************************************/
    bool PVRShellSet(const prefNameFloatEnum prefName, const float value);

    /*!***********************************************************************
     @brief     This function is used to pass preferences to the PVRShell.
                If used, this function must be called from InitApplication().
     @param[in] prefName    Name of preference to set to value
     @param[in] value       Value
     @return    true for success
    *************************************************************************/
    bool PVRShellSet(const prefNameIntEnum prefName, const int value);

    /*!***********************************************************************
     @brief     This function is used to pass preferences to the PVRShell.
                If used, this funciton must be called from InitApplication().
     @param[in] prefName    Name of preference to set to value
     @param[in] ptrValue    Value
     @return    true for success
    *************************************************************************/
    bool PVRShellSet(const prefNamePtrEnum prefName, const void * const ptrValue);

    /*!***********************************************************************
     @brief     This function is used to pass preferences to the PVRShell.
                If used, this function must be called from InitApplication().
     @param[in] prefName    Name of preference to set to value
     @param[in] ptrValue    Value
     @return    true for success
    *************************************************************************/
    bool PVRShellSet(const prefNameConstPtrEnum prefName, const void * const ptrValue);

    /*!***********************************************************************
     @brief     This function is used to get parameters from the PVRShell.
                It can be called from anywhere in the program.
     @param[in] prefName    Name of preference to set to value
     @return    The requested value.
    *************************************************************************/
    bool PVRShellGet(const prefNameBoolEnum prefName) const;

    /*!***********************************************************************
    @brief      This function is used to get parameters from the PVRShell.
                It can be called from anywhere in the program.
    @param[in]  prefName    Name of preference to set to value
    @return     The requested value.
    *************************************************************************/
    float PVRShellGet(const prefNameFloatEnum prefName) const;

    /*!***********************************************************************
    @brief      This function is used to get parameters from the PVRShell.
                It can be called from anywhere in the program.
    @param[in]  prefName    Name of preference to set to value
    @return     The requested value.
    *************************************************************************/
    int PVRShellGet(const prefNameIntEnum prefName) const;

    /*!***********************************************************************
    @brief      This function is used to get parameters from the PVRShell.
                It can be called from anywhere in the program.
    @param[in]  prefName    Name of preference to set to value
    @return     The requested value.
    *************************************************************************/
    void *PVRShellGet(const prefNamePtrEnum prefName) const;

    /*!***********************************************************************
    @brief      This function is used to get parameters from the PVRShell
                It can be called from anywhere in the program.
    @param[in]  prefName    Name of preference to set to value
    @return     The requested value.
    *************************************************************************/
    const void *PVRShellGet(const prefNameConstPtrEnum prefName) const;

    /*!***********************************************************************
     @brief      It will be stored as 24-bit per pixel, 8-bit per chanel RGB. 
                 The memory should be freed using the free() function when no longer needed.
     @param[in]  Width   size of image to capture (relative to 0,0)
     @param[in]  Height  size of image to capture (relative to 0,0)
     @param[out] pLines  receives a pointer to an area of memory containing the screen buffer.
     @return     true for success
    *************************************************************************/
    bool PVRShellScreenCaptureBuffer(const int Width, const int Height, unsigned char **pLines);

    /*!***********************************************************************
    @brief      Writes out the image data to a BMP file with basename fname.
    @details    The file written will be fname suffixed with a
                number to make the file unique.
                For example, if fname is "abc", this function will attempt
                to save to "abc0000.bmp"; if that file already exists, it
                will try "abc0001.bmp", repeating until a new filename is
                found. The final filename used is returned in ofname.
    @param[in]  fname               base of file to save screen to
    @param[in]  Width               size of image
    @param[in]  Height              size of image
    @param[in]  pLines              image data to write out (24bpp, 8-bit per channel RGB)
    @param[in]  ui32PixelReplicate  expand pixels through replication (1 = no scale)
    @param[out] ofname              If non-NULL, receives the filename actually used
    @return     true for success
    *************************************************************************/
    int PVRShellScreenSave(
        const char          * const fname,
        const int           Width,
        const int           Height,
        const unsigned char * const pLines,
        const unsigned int  ui32PixelReplicate = 1,
        char                * const ofname = NULL);

    /*!***********************************************************************
     @brief     Writes out the image data to a BMP file with name fname.
     @param[in] pszFilename     file to save screen to
     @param[in] ui32Width       the width of the data
     @param[in] ui32Height      the height of the data
     @param[in] pImageData      image data to write out (24bpp, 8-bit per channel RGB)
     @param[in] ui32PixelReplicate  expand pixels through replication (1 = no scale)
     @return    0 on success
    *************************************************************************/
    int PVRShellWriteBMPFile(
        const char          * const pszFilename,
        const unsigned int  ui32Width,
        const unsigned int  ui32Height,
        const void          * const pImageData,
        const unsigned int  ui32PixelReplicate = 1);

    /*!***********************************************************************
    @brief     Writes the resultant string to the debug output (e.g. using
               printf(), OutputDebugString(), ...). Check the SDK release notes for
               details on how the string is output.
    @param[in] format       printf style format followed by arguments it requires
    *************************************************************************/
    void PVRShellOutputDebug(char const * const format, ...) const;

    /*!***********************************************************************
    @brief      The number itself should be considered meaningless; an
                application should use this function to determine how much
                time has passed between two points (e.g. between each frame).
    @return     A value which increments once per millisecond.
    *************************************************************************/
    unsigned long PVRShellGetTime();

    /*!***********************************************************************
    @brief      Check if a key was pressed. 
    @details    The keys on various devices
                are mapped to the PVRShell-supported keys (listed in @a PVRShellKeyName) in
                a platform-dependent manner, since most platforms have different input
                devices. Check the <a href="modules.html">Modules page</a> for your OS
                for details on how the enum values map to your device's key code input.
    @param[in]  key     Code of the key to test
    @return     true if key was pressed
    *************************************************************************/
    bool PVRShellIsKeyPressed(const PVRShellKeyName key);
};

/****************************************************************************
** Declarations for functions that the scene file must supply
****************************************************************************/

/*!***************************************************************************
 @brief     This function must be implemented by the user of the shell.
 @details   The user should return its PVRShell object defining the
            behaviour of the application.
 @return    The demo supplied by the user
*****************************************************************************/
PVRShell* NewDemo();

#endif /* __PVRSHELL_H_ */

/*****************************************************************************
 End of file (PVRShell.h)
*****************************************************************************/