PowerVR Software Development Kit |
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:
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(); }
InitApplication() will be called by PVRShell once per run, before the graphic context is created. It is used to initialize variables that are not dependant on the rendering context (e.g. external modules, loading user data, etc.). QuitApplication() will 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. PVShell will call this function every frame and will manage relevant OS events.
There are other PVRShell functions which allow the user to set his 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:
bool MyApplication::InitApplication() { PVRShellSet (prefFullScreen, true); } bool MyApplication::RenderScene() { int dwCurrentWidth = PVRShellGet (prefHeight); int dwCurrentHeight = PVRShellGet (prefWidth); return true; }
There are a few other helper functions supplied by PVRShell as well. These functions allows to read the timer, to output debug information and to save a screen-shot of the current frame:
PVRShellGetTime() returns time in milliseconds since the last call.
PVRShellOutputDebug() will write a debug string (same format than 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:
bool MyApplication::RenderScene() { [...] unsigned char *pLines; PVRShellScreenCaptureBuffer(PVRShellGet (prefWidth), PVRShellGet (prefHeight), &pLines); PVRShellScreenSave("myfile", pLines, NULL); free (pLines); return true; }
-width=N Sets the horizontal viewport width to N.
-height=N Sets the vertical viewport height to N.
-posx=N Sets the x coordinate of the viewport.
-posy=N Sets the y coordinate of the viewport
-FSAAMode=N Sets full screen antialiasing. N can be: 0=no AA , 1=2x AA , 2=4x AA
-fullscreen Runs in fullscreen mode
-windowed Runs in window mode
-qat=N Quits after N seconds
-qaf=N Quits after N frames
Example:
Demo -width=160 -height=120 -windowed -qaf=300
Copyright © 1999-2006, PowerVR Technologies and partners. PowerVR Technologies is a division of Imagination Technologies Ltd.