PVRShell Classes#

InternalOS#

Defined in InternalOS.h

Class Documentation#

class InternalOS#

Public Functions

InternalOS(ShellOS *shellOS)#

virtual ~InternalOS()#

inline void setIsInitialized(bool isInitialized)#

inline ShellOS *getShellOS()#

inline const ShellOS *getShellOS() const#

inline bool isInitialized()#

virtual bool handleOSEvents(std::unique_ptr<Shell> &shell)#

Keys getKeyFromAscii(unsigned char initialKey)#

Keys getKeyFromEVCode(uint32_t keycode)#

Shell#

Defined in Shell.h

Nested Relationships#

Nested Types#

Inheritance Relationships#

Base Type#

public IAssetProvider

Class Documentation#

class Shell : public IAssetProvider #

The PowerVR Shell (pvr::Shell) is the main class that the user will inherit his application from.

This class abstracts the platform for the user and provides a unified interface to it. The user will normally write his application as a class inheriting from the Shell. This way the user can have specific and easy to use places to write his code - Application start, window initialisation, per frame, cleanup. All platform queries and settings can be done on the shell (set the required Graphics API required, window size etc.). Specific callbacks and queries are provided for system events (keyboard, mouse, touch) as well as a unified simplified input interface provided such abstracted input events as “Left”, “Right”, “Action1”, “Quit” across different platforms.

Public Functions

inline void onKeyDown(Keys key)#

Used externally to signify events to the Shell. Do not use.

Parameters:: key – The key for this event.

inline void onKeyUp(Keys key)#

Used externally to signify events to the Shell. Do not use.

Parameters:: key – The key for this event.

inline void onPointingDeviceDown(uint8_t buttonIdx)#

Used externally to signify events to the Shell. Do not use.

Parameters:: buttonIdx – The button ID for this event.

inline void onPointingDeviceUp(uint8_t buttonIdx)#

Used externally to signify events to the Shell. Do not use.

Parameters:: buttonIdx – The button ID for this event.

inline void onSystemEvent(SystemEvent systemEvent)#

Used externally to signify events to the Shell. Do not use.

Parameters:: systemEvent – The type of the system event.

inline void onConfigureEvent(const ConfigureEvent &configureEvent)#

Called by some OS (X11) to record the movement of the mouse.

Parameters:: configureEvent – Mouse data.

virtual ~Shell()#: Destructor.

DisplayAttributes &getDisplayAttributes()#

Get the display attributes (width, height, bpp, AA, etc) of this pvr::Shell.

OSManager interface implementation.

Returns:: The display attributes (width, height, bpp, AA, etc) of this pvr::Shell

const DisplayAttributes &getDisplayAttributes() const#

Get the display attributes (width, height, bpp, AA, etc) of this pvr::Shell.

OSManager interface implementation.

Returns:: The display attributes (width, height, bpp, AA, etc) of this pvr::Shell

OSConnection getConnection() const#

Get the underlying connection object of this shell.

OSManager interface implementation.

Returns:: The underlying connection object of this shell

OSDisplay getDisplay() const#

Get the underlying Display object of this shell.

OSManager interface implementation.

Returns:: The underlying Display object of this shell

OSWindow getWindow() const#

Get the underlying Window object of this shell.

OSManager interface implementation.

Returns:: The underlying Window object of this shell

inline bool isKeyPressed(Keys key) const#

Query if a key is pressed.

Parameters:: key – The key to check
Returns:: True if a keyboard exists and the key is pressed

inline bool isButtonPressed(int8_t buttonIndex) const#

Query if a key is pressed.

Parameters:: buttonIndex – The number of the button to check (LMB:0, RMB:1, MMB:2)
Returns:: True if a mouse/touchscreen exists and the button with this is index pressed. Simple touch is 0.

inline PointerLocation getPointerAbsolutePosition() const#

Query the pointer location in pixels.

Returns:: The location of the pointer in pixels.

inline PointerLocation getPointerRelativePosition() const#

Query the pointer relative position.

Returns:: The relative pointer location in pixels.

inline PointerNormalisedLocation getPointerNormalisedPosition() const#

Query the pointer location in normalised coordinates (0..1).

Returns:: The location of the pointer in normalised coordinates (0..1).

inline const PointingDeviceState &getPointingDeviceState() const#

Query the state of the pointing device (Mouse, Touchscreend).

Returns:: A PointingDeviceState struct containing the state of the pointing device.

uint64_t getTime() const#

Get the total time (from the same arbitrary starting point as getTimeAtInitApplication ), in milliseconds.

Returns:: The total time in milliseconds.

uint64_t getFrameTime() const#

The duration of the last frame to pass, in milliseconds. This is the time to use to advance app logic.

Returns:: The duration of the last frame, in milliseconds.

uint64_t getTimeAtInitApplication() const#

Get the total time (from the same arbitrary starting point as getTime ), in milliseconds.

Returns:: The time at init application, in milliseconds.

const platform::CommandLineParser::ParsedCommandLine &getCommandLine() const#

Get the command line options that were passed at application launch.

Returns:: A pvr::platform::CommandLineParser::ParsedCommandLine object containing all options passed at app launch.

void setFullscreen(const bool fullscreen)#

ONLY EFFECTIVE AT INIT APPLICATION. Set the application to run at full screen mode. Not all platforms support this option.

Parameters:: fullscreen – Set to true for fullscreen, false for windowed

bool isFullScreen() const#

Get if the application is running in full screen.

Returns:: True if the application is running in full screen. False otherwise.

uint32_t getWidth() const#

Get the width of the application area (window width for windowed, or screen width for full screen).

Returns:: The width of the application area.

uint32_t getHeight() const#

Get the height of the application area (window height for windowed, or screen height for full screen).

Returns:: The height of the application area.

uint32_t getCaptureFrameScale() const#

Get the screenshot capture scale to be applied to any saved screenshot.

Returns:: The screenshot capture scaling factor.

Api getMaxApi() const#

Get the maximum api type requested.

Returns:: The maximum api type requested.

Api getMinApi() const#

Get the minimum api type requested.

Returns:: The minimum api type requested.

Result setDimensions(uint32_t w, uint32_t h)#

ONLY EFFECTIVE IF CALLED AT INIT APPLICATION. Set the window size, or resolution for fullscreen.

Parameters:

w – The width of the window / horizontal resolution
h – The height of the window / vertical resolution

Returns:

pvr::Result::Success if successful. pvr::Result::UnsupportedRequest if unsuccessful.

uint32_t getPositionX() const#

Get the window position X coordinate.

Returns:: The window position X coordinate. (0 for fullscreen)

uint32_t getPositionY() const#

Get the window position Y coordinate.

Returns:: The window position Y coordinate. (0 for fullscreen)

Result setPosition(uint32_t x, uint32_t y)#

ONLY EFFECTIVE IF CALLED AT INIT APPLICATION. Set the window position. Not supported in all platforms.

Parameters:

x – x-coordinate (Distance of the left of the window to the left of the screen)
y – y-coordinate (Distance of the top of the window to the top of the screen)

Returns:

pvr::Result::Success if successful. pvr::Result::UnsupportedRequest if unsuccessful.

int32_t getQuitAfterFrame() const#

Return the frame after which the application is set to automatically quit. If QuitAfterFrame was not set, returns -1.

Returns:: The frame after which the application is set to quit. If not set, returns -1

bool getSafetyCritical() const#

Get whether the application should be ran as Safety Critical (only Vulkan API currently).

Returns:: True if the application should be ran as Safety Critical.

bool getJsonGeneration() const#

Get whether the application should be ran in .json pipeline file generation mode (only Vulkan API currently).

Returns:: True if the application should be ran in .json pipeline file generation mode.

void setQuitAfterFrame(uint32_t value)#

ONLY EFFECTIVE IF CALLED AT INIT APPLICATION. Set a frame after which the application will quit.

Parameters:: value – The frame after which the application is set to quit. Set to -1 to disable.

void setSafetyCritical(bool value) const#

Setter of ShellData::safetyCritical.

Parameters:: value – Value to set.

void setJsonGeneration(bool value) const#

Setter of ShellData::jsonGeneration.

Parameters:: value – Value to set.

float getQuitAfterTime() const#

Get the time after which the application is set to automatically quit.If QuitAfterTime was not set, returns -1.

Returns:: The time after which the application will quit. If not set, returns -1

void setQuitAfterTime(float value)#

ONLY EFFECTIVE IF CALLED AT INIT APPLICATION. Set a time after which the application will quit.

Parameters:: value – The time (seconds) after which the application will quit. Set to -1 to disable.

VsyncMode getVsyncMode() const#

Get the vertical synchronization mode.

Returns:: The vertical synchronisation mode.

void setVsyncMode(VsyncMode mode)#

ONLY EFFECTIVE IF CALLED AT INIT APPLICATION. Set the Vertical Syncchronization mode(vertical sync). Default is On(Fifo).

On : VerticalSync (no tearing, some possible input lag

Off : no synchronization. Little lag, bad tearing.

Mailbox: If supported, what was commonly known as triple-buffering - the app uses the latest full image. Little lag, no tearing.

Relaxed: If supported, the presentation engine will only synchronize if framerate is greater than refresh. Some lag, minimal tearing.

Half The application will present once per two refresh intervals (usually to preserve power). Much lag, no tearing.

Parameters:: mode – The Vertical Synchronization mode.

void setPreferredSwapChainLength(uint32_t swapChainLength)#

ONLY EFFECTIVE IF CALLED AT INIT APPLICATION. Set a desired number of swap images (number of framebuffers). This number will be clamped between the minimum and the maximum number supported by the platform, so that if a small (0-1) or large (8+) number is requested, the minimum/maximum of the platform will always be providedd.

Parameters:: swapChainLength – The desired number of swap images. Default is 3 for Mailbox, 2 for On.

void forceReleaseInitView()#: EFFECTIVE IF CALLED DURING RenderFrame. Force the shell to ReleaseView and then InitView again after this frame.

void forceReleaseInitWindow()#: EFFECTIVE IF CALLED DURING RenderFrame. Force the shell to ReleaseView and then InitView again after this frame.

uint32_t getAASamples() const#

Get the number of anti-aliasing samples.

Returns:: The number of anti-aliasing samples.

void setAASamples(uint32_t value)#

ONLY EFFECTIVE IF CALLED AT INIT APPLICATION. Set the Anti-Aliasing samples.

Parameters:: value – The anti-aliasing samples.

uint32_t getColorBitsPerPixel() const#

Returns:

Get the total number of color bits per pixel (sum of all channels’ bits per pixel)

The number of total color bits per pixel.

uint32_t getDepthBitsPerPixel() const#

Get the number of framebuffer depth bits per pixel.

Returns:: The number of depth bits per pixel.

uint32_t getStencilBitsPerPixel() const#

Get the number of framebuffer stencil bits per pixel.

Returns:: The number of stencil bits per pixel.

ColorSpace getBackBufferColorspace() const#

Get the Colorspace of the main window framebuffer (linear RGB or sRGB).

Returns:: The Colorspace of the main window framebuffer (linear RGB or sRGB).

void setBackBufferColorspace(ColorSpace colorSpace)#

ONLY EFFECTIVE IF CALLED AT INIT APPLICATION. Specify the colorspace of the backbuffer. Default is a (linear) RGB BackBuffer. Use this to specifically request an sRGB backbuffer. Since the support of backbuffer colorspace is an extension in many implementations, if you use this function, you must call getBackBufferColorspace after initApplication (in initView) to determine the actual backBuffer colorspace that was obtained.

Parameters:: colorSpace – the desired framebuffer colorspace (either lRgb or sRgb)

void setColorBitsPerPixel(uint32_t r, uint32_t g, uint32_t b, uint32_t a)#

ONLY EFFECTIVE IF CALLED AT INIT APPLICATION. Set the number of framebuffer color bits per pixel.

Actual number obtained may vary per implementation. Query with getColorBitsPerPixel after initView to check the actual number obtained

Parameters:

r – The Red framebuffer channel color bits
g – The Green framebuffer channel color bits
b – The Blue framebuffer channel color bits
a – The Alpha framebuffer channel color bits

void setDepthBitsPerPixel(uint32_t value)#

ONLY EFFECTIVE IF CALLED AT INIT APPLICATION. Set the number of framebuffer Depth bits per pixel.

Actual number obtained may vary per implementation. Query with getDepthBitsPerPixel after initView to check the actual number obtained

Parameters:: value – The desired framebuffer Depth channel bits.

void setStencilBitsPerPixel(uint32_t value)#

ONLY EFFECTIVE IF CALLED AT INIT APPLICATION. Set the number of Stencil bits per pixel.

Actual number obtained may vary per implementation. Query with getStencilBitsPerPixel after initView to check the actual number obtained

Parameters:: value – The Stencil channel bits.

void setForceFrameTime(const bool value)#

ONLY EFFECTIVE IF CALLED AT INIT APPLICATION. Forces frame time to always be reported as 1/60th of a second.

Parameters:: value – True to force frame time, false to use real frame time.

bool isForcingFrameTime() const#

Check if frame time is forced (forceFrameTime(true) has been called)

Returns:: True if forcing frame time.

bool isScreenRotated() const#

Check if screen is rotated. By convention, we consider “landscape” to be the default, non-rotated and “portrait” to be rotated.

Returns:: True if screen is Portrait (height > width) on a full-screen device, false otherwise

bool isScreenPortrait() const#

Check if screen is Portrait (Height > Width) .

Returns:: True if screen height > width, false otherwise

bool isScreenLandscape() const#

Check if screen is Landscape (Height > Width) .

Returns:: True if screen height > width, false otherwise

void showOutputInfo() const#: Print out general information about this Shell (application name, sdk version, cmd line etc.

void setCaptureFrames(uint32_t start, uint32_t stop)#

ONLY EFFECTIVE IF CALLED AT INIT APPLICATION. Captures the frames between start and stop and saves them as TGA screenshots.

Parameters:

start – First frame to be captured
stop – Last frame to be captured

void setCaptureFrameScale(uint32_t value)#

ONLY EFFECTIVE IF CALLED AT INIT APPLICATION. Sets the upscale factor of the screenshots. Upscaling only.

Parameters:: value – Upscaling of the screenshots

uint32_t getCaptureFrameStart() const#

If capturing frames, get the first frame to be captured.

Returns:: If capturing frames, the first frame to be captured.

uint32_t getCaptureFrameStop() const#

If capturing frames, get the last frame to be captured.

Returns:: If capturing frames, the last frame to be captured.

uint32_t getFrameNumber() const#

Returns the current frame number. Incremented each time renderFrame is called.

Returns:: The current frame number maintained by the Shell.

uint32_t getContextPriority() const#

Get the requested context priority.0=Low,1=Medium, 2+ = High. Initial value: High.

Returns:: If supported, the priority of the main Graphics Context used by the application.

void setContextPriority(uint32_t value)#

ONLY EFFECTIVE IF CALLED AT INIT APPLICATION. If supported, sets a ContextPriority that the shell will attempt to use when creating the main Graphics Context used for the window. Initial value:High.

Parameters:: value – The context priority requested. 0=Low, 1=Medium, 2+=High.

uint32_t getDesiredConfig() const#

If setDesiredConfig was called, get the desired ConfigID.

Returns:: If setDesiredConfig was called, the desired ConfigID.

void setDesiredConfig(uint32_t value)#

ONLY EFFECTIVE IF CALLED AT INIT APPLICATION. If supported by the platform/API, sets a specific Context Configuration ID to be used.

Parameters:: value – The ConfigID that will be requested.

uint32_t getFakeFrameTime() const#

Get the artificial frame time that has been set. 0 means unset.

Returns:: The artificial frame time that has been set. 0 means unset.

void setFakeFrameTime(uint32_t value)#

Sets a time delta that will be used as frame time to increment the application clock instead of real time. This number will be returned as the frame time.

Parameters:: value – The number of milliseconds of the frame.

bool isShowingFPS() const#

Check if FPS are being printed out.

Returns:: True if FPS are being printed out.

void setShowFPS(bool showFPS)#

Sets if the Frames Per Second are to be output periodically.

Parameters:: showFPS – Set to true to output fps, false otherwise.

float getFPS() const#

Get an FPS calculation of the last frame.

Returns:: An Frames-Per-Second value calculated periodically by the application.

template<typename ...Args> inline void setExitMessage(const char *const format, Args... args)#

Set a message to be displayed on application exit. Normally used to display critical error messages that might be missed if displayed as just logs.

Parameters:

format – A printf-style format std::string
args – Printf-style variable arguments

template<typename ...Args> void setApplicationName(const char *const format, Args... args)#

Sets the application name.

Parameters:

format – A printf-style format std::string
args – Printf-style variable parameters

template<typename ...Args> inline void setTitle(const char *const format, Args... args)#

Sets the window title. Will only be actually displayed If used on or before initApplication.

Parameters:

format – A printf-style format std::string
args – Printf-style variable parameters

const std::string &getExitMessage() const#

Get the exit message set by the user.

Returns:: The exit message set by the user.

const std::string &getApplicationName() const#

Get application name.

Returns:: The application name.

const std::string &getDefaultReadPath() const#

Get the default read path.

Returns:: The first (default) read path. Normally, current directory.

const std::vector<std::string> &getReadPaths() const#

Get a list of all paths that will be tried when looking for loading files.

Returns:: The a list of all the read paths that will successively be tried when looking to read a file.

const std::string &getWritePath() const#

Get the path where any files will be saved.

Returns:: The path where any files saved (screenshots, logs) will be output to.

void exitShell()#: Signifies the application to clean up and exit. Will go through the normal StateMachine cycle and exit cleanly, exactly like returning ExitRenderFrame from RenderFrame. Will skip the next RenderFrame execution.

std::unique_ptr<Stream> getAssetStream(const std::string &filename, bool errorIfFileNotFound = true) const#

Create and return a Stream object for a specific filename. Uses platform dependent lookup rules to create the stream from the filesystem or a platform-specific store (Windows resources, Android .apk assets) etc. Will first try the filesystem (if available) and then the built-in stores, in order to allow the user to easily override built-in assets.

Parameters:

filename – The name of the file to load. Is usually a raw filename, but may contain a path.
errorIfFileNotFound – Set this to false if file-not-found are expected and should not be logged as errors.

Returns:

A unique pointer to the Stream returned if successful, an Empty unique pointer if failed.

std::unique_ptr<Stream> getWriteAssetStream(const std::string &filename, bool allowRead = false, bool truncateIfExists = false) const#

Create and return a Stream object for a specific filename. Uses platform dependent write path rules to create the stream.

Parameters:

filename – The name of the file to load. Should be a raw filename.
allowRead – Whether to allow read & write or Write only access.
truncateIfExists – Whether it’s a write operation (false) or and append operation (true)

Returns:

A unique pointer to the Stream returned if successful, an Empty unique pointer if failed.

ShellOS &getOS() const#

Gets the ShellOS object owned by this shell.

Returns:: The ShellOS object owned by this shell.

inline bool shouldTakeScreenshot() const#

Returns whether a screenshot should be taken for the current frame making use of command line arguments.

Returns:: True if a screenshot was requested for this frame, otherwise returns false

std::string getScreenshotFileName() const#

Generates and returns a potential screenshot name based on the shell write path, frame number and appication name.

Returns:: Returns a potential screenshot name based on the shell write path, frame number and application name.

void addReadPath(const std::string &readPath)#

Adds a new path to the set of read paths.

Parameters:: readPath – A new read path to add to the set of read paths.

Public Static Functions

static inline const char *getSDKVersion()#

Get the current version of the PowerVR SDK.

Returns:: The current version of the PowerVR SDK.

Protected Functions

inline virtual Result preInitApplication()#

IMPLEMENT THIS FUNCTION IN YOUR APPLICATION CLASS. This event is called before application start.

Returns:: When implementing, return a suitable error code to signify failure. If pvr::Result::Success is not returned , the Shell will detect that, clean up, and exit.

virtual Result initApplication() = 0#

IMPLEMENT THIS FUNCTION IN YOUR APPLICATION CLASS. This event represents application start.

This function must be implemented in the user’s application class. It will be fired once, on start, before any other callback and before Graphics Context aquisition. It is suitable to do per-run initialisation, load assets files and similar tasks. A context does not exist yet, hence if the user tries to create API objects, they will fail and the behaviour is undefined.

Returns:: When implementing, return a suitable error code to signify failure. If pvr::Result::Success is not returned , the Shell will detect that, clean up, and exit.

virtual Result initView() = 0#

IMPLEMENT THIS FUNCTION IN YOUR APPLICATION CLASS. This event is called after successful window/context aquisition.

This function must be implemented in the user’s application class. It will be fired once after every time the main Graphics Context (the one the Application Window is using) is initialized. This is usually once per application run, but in some cases (context lost) it may be called more than once. If the context is lost, the releaseView() callback will be fired, and if it is reaquired this function will be called again. This callback is suitable to do all do-once tasks that require a graphics context, such as creating an On-Screen Framebuffer, and for simple applications creating the graphics objects.

Returns:: When implementing, return a suitable error code to signify failure. If pvr::Result::Success is not returned , the Shell will detect that, clean up, and exit.

virtual Result renderFrame() = 0#

IMPLEMENT THIS FUNCTION IN YOUR APPLICATION CLASS. This event is called every frame.

This function must be implemented in the user’s application class. It will be fired once every frame. The user should use this callback as his main callback to start rendering and per-frame code. This callback is suitable to do all per-frame task. In multithreaded environments, it should be used to mark the start and signal the end of frames.

Returns:: When implementing, return a suitable error code to signify failure. Return pvr::Success to signify success and allow the Shell to do all actions necessary to render the frame (swap buffers etc.). If pvr::Result::Success is not returned, the Shell will detect that, clean up, and exit. Return pvr::Result::ExitRenderFrame to signify a clean, non-error exit for the application. Any other error code will be logged.

virtual Result releaseView() = 0#

IMPLEMENT THIS FUNCTION IN YOUR APPLICATION CLASS. This event represents graphics context released.

This function must be implemented in the user’s application class. It will be fired once before the main Graphics Context is lost. The user should use this callback as his main callback to release all API objects as they will be invalid afterwards. In simple applications where all objects are created in initView, it should release all objects acquired in initView. This callback will be called when the application is exiting, but not only then - losing (and later re-acquiring) the Graphics Context will lead to this callback being fired, followed by an initView callback, renderFrame etc.

Returns:: When implementing, return a suitable error code to signify failure. If pvr::Result::Success is not returned, the Shell will detect that, clean up, and exit. If the shell was exiting, this will happen anyway.

virtual Result quitApplication() = 0#

IMPLEMENT THIS FUNCTION IN YOUR APPLICATION CLASS. This event represents application exit.

This function must be implemented in the user’s application class. It will be fired once before the application exits, after the Graphics Context is torn down. The user should use this callback as his main callback to release all objects that need to. The application will exit shortly after this callback is fired. In effect, the user should release all objects that were acquired during initApplication. Do NOT use this to release API objects - these should already have been released during releaseView.

Returns:: When implementing, return a suitable error code to signify a failure that will be logged.

inline virtual void eventClick(int buttonIdx, PointerLocation location)#

Override in your class to handle the “Click” or “Touch” event of the main input device (mouse or touchscreen).

This event will be fired on releasing the button, when the mouse pointer has not moved more than a few pixels since the button was pressed (otherwise a drag will register instead of a click).

Parameters:

buttonIdx – The index of the button (LMB:0, RMB:1, MMB:2, Touch:0)
location – The location of the click.

inline virtual void eventDragFinished(PointerLocation location)#

Override in your class to handle the finish of a “Drag” event of the main input device (mouse, touchscreen).

This event will be fired on releasing the button, and the mouse pointer has not moved more than a few pixels since the button was pressed.

Parameters:: location – The location of the click.

inline virtual void eventDragStart(int buttonIdx, PointerLocation location)#

Override in your class to handle the start of a “Drag” event of the main input device (mouse, touchscreen).

This event will be fired after a movement of more than a few pixels is detected with a button down.

Parameters:

buttonIdx – The index of the button (LMB:0, RMB:1, MMB:2, Touch:0).
location – The location of the click.

inline virtual void eventButtonDown(int buttonIdx)#

Override in your class to handle the initial press (down) of the main input device (mouse, touchscreen).

This event will be fired on pressing any button.

Parameters:: buttonIdx – The index of the button (LMB:0, RMB:1, MMB:2, Touch:0)

inline virtual void eventButtonUp(int buttonIdx)#

Override in your class to handle the release (up) of the main input device (mouse, touchscreen).

This event will be fired on releasing any button.

Parameters:: buttonIdx – The index of the button (LMB:0, RMB:1, MMB:2, Touch:0)

inline virtual void eventKeyDown(Keys key)#

Override in your class to handle the press of a key of the keyboard.

This event will be fired on pressing any key.

Parameters:: key – The key pressed

inline virtual void eventKeyStroke(Keys key)#

Override in your class to handle a keystroke of the keyboard.

This event will normally be fired multiple times during a key press, as controlled by the key repeat of the operating system.

Parameters:: key – The key pressed

inline virtual void eventKeyUp(Keys key)#

Override in your class to handle the release (up) of a key of of the keyboard.

This event will be fired once, when releasing a key.

Parameters:: key – The key released

inline virtual void eventMappedInput(SimplifiedInput key)#

Override in your class to handle a unified interface for input across different platforms and devices.

This event abstracts, maps and unifies several input devices, in a way with a mind to unify several platforms and input devices. The Left/Right/Up/Down keyboard key, Swipe Left/Right/Up/Down both cause Left/Right/Up/Down events. Left Click at Center, Space key, Enter key, Touch at Center cause Action1. Left Click at Left, Right Click, One Key, Touch at the Left cause Action2. Left Click at Right, Middle Click, Two Key, Touch at the Right cause Action3. Escape, Q key, Back button cause Quit. Default behaviour is Quit action calls exitShell. In order to retain Quit button functionality, this behaviour should be mirrored (exitShell called on ActionClose).

Parameters:: key – The Simplified Unified Event

Shell()#: Default constructor. Do not instantiate a Shell class directly - extend as your application and then provide the newDemo() function returning your application instance. See bottom of this file.

struct PointerNormalisedLocation#

Contains a pointer location in unsigned normalised coordinates (0..1).

Public Functions

inline PointerNormalisedLocation()#: Constructor. Undefined values.

Public Members

float x#: The x location of the cursor, where 0=left and 1=right.

float y#: The y location of the cursor, where 0=top and 1=bottom.

struct PointingDeviceState#

Contains the state of a pointing device (mouse, touch screen).

Public Functions

inline PointingDeviceState()#: Constructor.

inline PointerLocation position() const#

Get the current (i.e. last known) location of the mouse/pointing device pointer.

Returns:: The location of the pointer.

inline PointerLocation dragStartPosition() const#

Get the location of the mouse/pointing device pointer when the last drag started.

Returns:: The location of a drag action’s starting point.

inline bool isPressed(int8_t buttonIndex) const#

Query if a specific button is pressed.

Parameters:: buttonIndex – The index of the button (0 up to 6).
Returns:: True if the button exists and is pressed. False otherwise.

inline bool isDragging() const#

Check if a drag action has started.

Returns:: True if during a dragging action.

Protected Attributes

PointerLocation _pointerLocation#: Location of the pointer.

PointerLocation _dragStartLocation#: Location of a drag starting point.

int8_t _buttons#: Buttons pressed.

ShellOS#

Defined in ShellOS.h

Nested Relationships#

Nested Types#

ShellOS::Capabilities

Inheritance Relationships#

Derived Type#

public pvr::platform::StateMachine (StateMachine)

Class Documentation#

class ShellOS#

Internal class Implements a lot of the functionality and forwards to the platform from PVRShell. Don’t use directly, instead use the pvr::Shell class.

Subclassed by pvr::platform::StateMachine

Public Functions

ShellOS(OSApplication instance, OSDATA osdata)#

Constructor.

Parameters:

instance – An OS Specific instance.
osdata – OS Specific data.

virtual ~ShellOS()#: Destructor.

bool init(DisplayAttributes &data)#

Initializes the platform specific shell. Accepts a data struct so it can overide default values.

Parameters:: data – A set of display attributes which will be set within this function.
Returns:: True on success

bool initializeWindow(DisplayAttributes &data)#

Initializes the platform specific window.

Parameters:: data – A set of display attributes which will be set within this function.
Returns:: True on success

bool isInitialized()#

Indicates whether the platform specific shell has been initiailised.

Returns:: True on success

void releaseWindow()#: Releases the platform specific window.

OSApplication getApplication() const#

Retrieves the platform specific application.

Returns:: The OS specific application

OSConnection getConnection() const#

Retrieves the window specific connection.

Returns:: The window system specific connection

OSDisplay getDisplay() const#

Retrieves the platform specific display.

Returns:: The OS specific display

OSWindow getWindow() const#

Retrieves the platform specific window.

Returns:: The OS specific window

inline const std::string &getDefaultReadPath() const#

Retrieves the default read path.

Returns:: The default read path

inline const std::vector<std::string> &getReadPaths() const#

Retrieves the read paths.

Returns:: The read paths

inline void addReadPath(const std::string &readPath)#

Retrieves the read paths.

Parameters:: readPath – A new read path to add to the list of read paths.

inline void clearReadPaths()#: Clears the read paths.

inline const std::string &getWritePath() const#

Retrieves the current write path.

Returns:: The write path

inline void setWritePath(const std::string &writePath)#

Sets the current write path.

Parameters:: writePath – A new write path to use as the current write path.

inline const std::string &getApplicationName() const#

Retrieves the application name.

Returns:: The application name

inline void setApplicationName(const std::string &applicationName)#

Sets the application name.

Parameters:: applicationName – An application name.

bool handleOSEvents()#

Handles os specific events.

Returns:: True on success

bool popUpMessage(const char *const title, const char *const message, ...) const#

Pops up a message.

Parameters:

title – Specifies the title.
message – Specifies the message.
... – Variable arguments for the format std::string. Printf-style rules

Returns:

True on success

inline Shell *getShell()#

Retrieves the shell.

Returns:: A pointer to the shell

void updatePointingDeviceLocation()#: Updates the location of the pointing device.

Public Members

ShellData _shellData#: Platform specific shell data.

Public Static Functions

static inline const Capabilities &getCapabilities()#

Retrieves OS specific capabilities.

Returns:: OS Specific capabilities

Protected Attributes

std::unique_ptr<Shell> _shell#: A unique pointer to the shell.

std::string _appName#: The application name.

std::vector<std::string> _readPaths#: A list of read paths.

std::string _writePath#: The current write path.

struct Capabilities#

Capabilities that may be different between platforms.

Public Members

Capability resizable#: A window with this capability can be resized while the program is running (e.g windows, X11, but not Android)

Capability movable#: A window with this capability can be moved while the program is running (e.g windows and X11, but not Android)

StateMachine#

Defined in StateMachine.h

Inheritance Relationships#

Base Type#

public pvr::platform::ShellOS (ShellOS)

Class Documentation#

class StateMachine : public pvr::platform::ShellOS #

The StateMachine controlling the PowerVR Shell. Provides the application main loop and callbacks.

Public Types

enum NewState#

Values:

enumerator StateUninitialised#

enumerator StateInitialised#

enumerator StateAppInitialised#

enumerator StateWindowInitialised#

enumerator StateReady#

Public Functions

StateMachine(OSApplication instance, platform::CommandLineParser &commandLine, OSDATA osdata)#

Constructor. Called by the application’s entry point (main).

Parameters:

instance – Platform-specific object containing pointer/s to the application instance.
commandLine – The command line arguments passed by the user.
osdata – Platform specific data passed in by the system

~StateMachine()#

Result init()#

Called by the application’s entry point (main).

Returns:: pvr::Result::Success if successful, otherwise error code.

Result execute()#

Called by the application’s entry point (main).

Returns:: pvr::Result::Success if successful, otherwise error code.

Result executeNext()#

Called internally by the state machine.

Returns:: pvr::Result::Success if successful, otherwise error code.

Result executeTo(NewState state)#

Called internally by the state machine. Executes all code paths between current state and the state requested (naturally reaching that state). For example, executeTo(QuitApplication) when current state is RenderFrame, will execute ReleaseView, ReleaseWindow, QuitApplication.

Parameters:: state – The state to execute
Returns:: pvr::Result::Success if successful, otherwise error code.

Result executeUpTo(NewState state)#

If the state machine is before (less initialised) than the parameter state, execute initialisation steps until that state is reached. Does nothing if it is after (more initialised) than the parameter state.

Parameters:: state – The state to execute
Returns:: pvr::Result::Success if successful, otherwise error code.

Result executeDownTo(NewState state)#

If the state machine is after (more initialised) than the parameter state, execute teardown steps until that state is reached. Does nothing if it is before (less initialised) than the parameter state.

Parameters:: state – The state to execute
Returns:: pvr::Result::Success if successful, otherwise error code.

inline NewState getState() const#

Get the current state of the StateMachine.

Returns:: The current state of the StateMachine.

inline bool isPaused() const#

Check if the StateMachine is paused.

Returns:: True if the StateMachine is paused.

inline void pause()#: Pauses the state machine.

inline void resume()#: Resumes (exits pause state for) the state machine.

PointerLocation#

Defined in Shell.h

Inheritance Relationships#

Base Type#

public pvr::PointerLocationStore (PointerLocationStore)

Class Documentation#

class PointerLocation : public pvr::PointerLocationStore #

Mouse pointer coordinates.

Public Functions

inline PointerLocation()#: Constructor.

inline explicit PointerLocation(const PointerLocationStore &st)#

Copy Constructor.

Parameters:: st – Copy source

inline PointerLocation(int16_t x, int16_t y)#

Constructor.

Parameters:

x – X coordinate
y – Y coordinate

AppController#

Defined in AppController.h

Inheritance Relationships#

Base Types#

public NSObject
public <NSApplicationDelegate>
public <UIApplicationDelegate>

Class Documentation#

AppController : public NSObject , public <NSApplicationDelegate> , public <UIApplicationDelegate>

iOS entry point implementation

Public Functions

virtual void terminateApp()#: Terminates the application.

Protected Attributes

NSTimer *mainLoopTimer#: timer for the main loop

pvr::platform::StateMachine *stateMachine#

The State Machine powering the pvr::Shell.

The StateMachine powering the pvr::Shell.

pvr::platform::CommandLineParser commandLine#

Command line options passed on app launch.

The command line options passed on app launch.

ViewMTL#

Defined in ViewMTL.h

Inheritance Relationships#

Base Type#

public NSView

Class Documentation#

class ViewMTL : public NSView#

Public Functions

virtual ViewMTL * initWithFrame: (NSRect frame)

Protected Attributes

id<MTLDevice> m_device#