PowerVR Software Development Kit


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

PVRShell

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:

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(); }

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 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; }

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 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; }

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.

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


Generated by DOXYGEN 1.3.6