CGapiApplication

Overview

CGapiApplication is a helper class you can use to quickly create new games
and applications.

This document has been updated for use with GapiDraw 4.0 or later.
Last updated on October 5, 2008.

CGapiApplication::CGapiApplication

Creates a CGapiApplication instance based on the configuration specified.

CGapiApplication(const GDAPPCONFIG& config);

Parameters

config

Supply a valid GDAPPCONFIG
structure to create the CGapiApplication instance.

Return values

None

Remarks

Creating a new CGapiApplication usually consists of the following steps:

Create a new GDAPPCONFIG structure and set the parameters you want.

Create a CGapiApplication instance and supply the GDAPPCONFIG
structure.

Start the application with CGapiApplication::Run

CGapiApplication will then call the following operations in your subclass:

CGapiApplication::InitInstance

CGapiApplication::CreateSysMemSurfaces

CGapiApplication::CreateVidMemSurfaces

On each frame, CGapiApplication::ProcessNextFrame will be called

When CGapiApplication::Shutdown is received, CGapiApplication::ExitInstance
will be called.

CGapiApplication::ExitInstance will always be called after CGapiApplication::InitInstance,
even if InitInstance returned an error code. It is thus safe to allocate
memory in CGapiApplication::InitInstance as long as you free the memory
in CGapiApplication::ExitInstance.

Note Regarding Display Modes

If you want to force the display in a landscape or portrait mode you should check the display width and height in the first ProcessNextFrame, and if necessary change the orientation with CGapiDisplay::SetDisplayMode.

CGapiApplication::Run

Starts the CGapiApplication main thread.

virtual HRESULT Run();

Parameters

None

Return values

If this method succeeds, the return value is S_OK.

If the method fails, the return value may be one of the following return
values:

Remarks

Use CGapiApplication::Run to start a CGapiApplication. When CGapiApplication::Run
is called, the following steps are performed:

CGapiApplication first checks to see another instance is running.
If so, that window is restored.

The main window is created based on the options specified in the configuration.

The GapiDraw display is opened and the display mode is set.

CGapiApplication::InitInstance is called in the subclass.

CGapiApplication::CreateSysMemSurfaces is called in the subclass.

CGapiApplication::CreateVidMemSurfaces is called in the subclass.

The main message loop is started and CGapiApplication::ProcessNextFrame
will be called in the subclass on each frame.

CGapiApplication::Run does not return until CGapiApplication::Shutdown
is called. When it is called, the following steps are performed by CGapiApplication::Run:

CGapiApplication::ExitInstance is called in the subclass.

The GapiDraw display is closed.

Any pending error messages set with CGapiApplication::SetErrorMessage
are displayed.

The main window is destroyed.

CGapiApplication::Shutdown

Shuts down the CGapiApplication and exits the CGapiApplication::Run operation.

virtual HRESULT Shutdown();

Parameters

None

Return values

The return value is S_OK.

CGapiApplication::Minimize

Minimize CGapiApplication and suspend the update thread. On mobile devices the application can be restored by the user by clicking on the application icon on the today screen.

virtual HRESULT Minimize();

Parameters

None

Return values

The return value is S_OK.

CGapiApplication::ToggleFullscreen

Toggle between windowed mode and fullscreen display on Windows Mobile 5.0 and later devices.

virtual HRESULT ToggleFullscreen();

Parameters

None

Return values

The return value is S_OK.

CGapiApplication::Pause

Pauses the application and skips the call to CGapiApplication::ProcessNextFrame
in the subclass.

virtual HRESULT Pause(DWORD dwNumFrames);

Parameters

dwNumFrames

The number of frames to skip the call to CGapiApplication::ProcessNextFrame
in the subclass.

Return values

The return value is S_OK.

CGapiApplication::ChangeFPS

Changes the number of calls to CGapiApplication::ProcessNextFrame during
each second.

virtual HRESULT ChangeFPS(DWORD dwFPS);

Parameters

dwFPS

The number of times each second CGapiApplication::ProcessNextFrame
should be called.

Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return
values:

E_FAIL

CGapiApplication::SetDisplayMode

Changes the display orientation.

virtual HRESULT SetDisplayMode(DWORD dwDisplayMode);

Parameters

dwDisplayMode

A display mode to be passed to CGapiDisplay::SetDisplayMode.

Return values

The return value is S_OK.

Remarks

The display orientation can be changed at any time ("normal"
and two landscape modes are supported). The orientation will change before
the next frame is processed.

After the display mode has changed, CGapiApplication will call CGapiApplication::CreateSysMemSurfaces
and CGapiApplication::CreateVidMemSurfaces in the subclass to re-create
all surfaces so they match the new display orientation. Please make sure
that you set both the display coordinates and surfaces dynamically in
CGapiApplication::CreateSysMemSurfaces and CGapiApplication::CreateVidMemSurfaces
if you want to support dynamic change of the display orientation.

CGapiApplication::SetError

Sets an error description and error code to be displayed before CGapiApplication
exits.

virtual HRESULT SetError(const TCHAR* pErrorDesc, HRESULT
hr = 0);

Parameters

pErrorDesc

A pointer to a string containing the error description.

hr

A numeric value containing the error code. If (HR == 0) no error code
will be shown.

Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return
values:

E_FAIL

CGapiApplication::IsFullscreen

Returns TRUE if the application is running full screen.

BOOL IsFullscreen();

Parameters

None

Return values

Returns TRUE if the application is running full screen, or FALSE if the application is running in windowed mode.

CGapiApplication::GetGlobal

Returns a pointer to the global CGapiDraw object used in all class constructors.

CGapiDraw* GetGlobal()

Parameters

None

Return values

Returns a pointer to the global CGapiDraw object.

CGapiApplication::GetDisplay

Returns a pointer to the display object.

CGapiDisplay* GetDisplay();

Parameters

None

Return values

Returns a pointer to the display object.

CGapiApplication::GetBackBuffer

Returns a pointer to the backbuffer object.

CGapiSurface* GetBackBuffer();

Parameters

None

Return values

Returns a pointer to the backbuffer object.

It is recommended that you use this operation instead of GetDisplay()->GetBackBuffer() since the backbuffer might be of a different size than the display back buffer.

CGapiApplication::GetInput

Returns a pointer to the input object.

CGapiInput* GetInput();

Parameters

None

Return values

Returns a pointer to the input object.

CGapiApplication::GetTimer

Returns a pointer to the timer object.

CGapiTimer* GetTimer();

Parameters

None

Return values

Returns a pointer to the timer object.

CGapiApplication::InitInstance

Override CGapiApplication::InitInstance to perform memory allocations
before the application is started.

virtual HRESULT InitInstance();

Parameters

None

Return values

If this method succeeds, the return value should be S_OK or GD_OK.

Remarks

If the return value is not S_OK or GD_OK the application will call CGapiApplication::ExitInstance
and exit.

CGapiApplication::CreateSysMemSurfaces

Parameters

The primary CGapiDisplay instance. You can use this to get information
on the display such as width, height, and pixel format.

hInstance

The application instance. Use this if you want to create images from
a resource.

Return values

If this method succeeds, the return value should be S_OK or GD_OK.

Remarks

CGapiApplication::CreateSysMemSurfaces is called when the application
starts or when the display mode changes. Please see CGapiApplication::SetDisplayMode
for more details. It is recommended that you add the code to create all
your surfaces in this function.

If the return value is not S_OK or GD_OK the application will call CGapiApplication::ExitInstance
and exit.

CGapiApplication::CreateVidMemSurfaces

Override CGapiApplication::CreateVidMemSurfaces to create all your video
surfaces and coordinates.

Parameters

The primary CGapiDisplay instance. You can use this to get information
on the display such as width, height, and pixel format.

hInstance

The application instance. Use this if you want to create images from
a resource.

Return values

If this method succeeds, the return value should be S_OK or GD_OK.

Remarks

CGapiApplication::CreateVidMemSurfaces is called when the application
starts, the display mode changes, or if surfaces stored in video memory
are lost. Please keep the initialization code and surfaces to be stored
in video memory as small as possible. It is recommended that you add the
code to create all your video surfaces in this function.

If the return value is not S_OK or GD_OK the application will call CGapiApplication::ExitInstance
and exit.

CGapiApplication::ProcessNextFrame

Override CGapiApplication::ProcessNextFrame to draw the next frame to
be displayed on screen.

Parameters

The main back buffer surface. Draw all graphics to the back buffer
and it's contents will automatically be copied to the display when CGapiApplication::ProcessNextFrame
returns.

dwFlags

The following table shows the possible flags.

Type

Description

GDAPP_FRAMETIMEOVERFLOW

Indicates that the last frame took longer to draw than what
is allowed to reach the target number of frame updates each
second.

GDAPP_LOSTSURFACES

Indicates that one or more surfaces stored in video memory
were lost, and that CGapiApplication has called CGapiDisplay::RestoreAllVideoSurfaces(),
and CGapiApplication::CreateVidMemSurfaces() to restore them.

GDAPP_RESTOREWINDOW

Indicates that the window has recently been restored after
being minimized.

GDAPP_DISPLAYCHANGED

Indicates that the display size or orientation was changed.

Return values

If this method succeeds, the return value should be S_OK or GD_OK.

Remarks

If the return value is not S_OK or GD_OK the application will call CGapiApplication::ExitInstance
and exit.

CGapiApplication::OnMinimize

Override CGapiApplication::OnMinimize to run code when the application
window is minimized.

virtual HRESULT OnMinimize();

Parameters

None

Return values

If this method succeeds, the return value should be S_OK or GD_OK.

Remarks

Override this method to run application code when the window is minimized.
Example usage is disabling sound output and sending network notifications.

CGapiApplication::OnRestore

Override CGapiApplication::OnRestore to run code when the application
window is restored.

virtual HRESULT OnRestore();

Parameters

None

Return values

If this method succeeds, the return value should be S_OK or GD_OK.

Remarks

Override this method to run application code when the window is restored
from being minimized. Example usage is enabling sound output and sending
network notifications.

CGapiApplication::OnDisplayChanged

Override CGapiApplication::OnDisplayChanged to run code when the display size or orientation has changed.

virtual HRESULT OnDisplayChanged(CGapiSurface* pBackBuffer);

Parameters

None

Return values

If this method succeeds, the return value should be S_OK or GD_OK.

Remarks

Override this method to run application code when the display size or orientation was changed.

CGapiApplication::KeyDown

Override CGapiApplication::KeyDown to receive information when a key
is pressed down.

virtual HRESULT KeyDown(DWORD dwKey, GDKEYLIST& keylist);

Parameters

dwKey

The code for the key being pressed down.

keylist

A GDKEYLIST structure
containing key codes mapped to the current display orientation.

Return values

If this method succeeds, the return value should be S_OK or GD_OK.

Remarks

To check if a specific key was pressed simply compare dwKey with
any value in keylist. For example, to check if "key left"
has been pressed simply enter "if (dwKey == keylist.vkLeft)".

CGapiApplication::KeyDown is only called once when a key is pressed down.
CGapiApplication::KeyDown is not called when the "keyboard repeat"
event is received.

CGapiApplication::KeyUp

Override CGapiApplication::KeyUp to receive information when a key is
released.

virtual HRESULT KeyUp(DWORD dwKey, GDKEYLIST& keylist);

Parameters

dwKey

The code for the key being released.

keylist

A GDKEYLIST structure
containing key codes mapped to the current display orientation.

Return values

If this method succeeds, the return value should be S_OK or GD_OK.

Remarks

To check if a specific key was pressed simply compare dwKey with
any value in keylist. For example, to check if "key left"
has been released simply enter "if (dwKey == keylist.vkLeft)".

CGapiApplication::StylusDown

Override CGapiApplication::StylusDown to receive information when the
stylus is pressed down.

virtual HRESULT StylusDown(POINT p);

Parameters

p

The coordinate where the stylus was pressed down. The coordinate is
in a format compatible with the current display orientation.

Return values

If this method succeeds, the return value should be S_OK or GD_OK.

CGapiApplication::StylusUp

Override CGapiApplication::StylusUp to receive information when the stylus
is lifted from screen.

virtual HRESULT StylusUp(POINT p);

Parameters

p

The coordinate where the stylus was lifted from screen. The coordinate
is in a format compatible with the current display orientation.

Return values

If this method succeeds, the return value should be S_OK or GD_OK.

CGapiApplication::StylusDblClk

Override CGapiApplication::StylusDblClk to receive information when the
stylus is double tapped. The flag bEnableDoubleClick must be set in m_config
for this function to be called.

virtual HRESULT StylusDblClk(POINT p);

Parameters

p

The coordinate where the stylus was double tapped. The coordinate
is in a format compatible with the current display orientation.

Return values

If this method succeeds, the return value should be S_OK or GD_OK.

CGapiApplication::StylusMove

Override CGapiApplication::StylusMove to receive information when the
stylus is moved across the display.

virtual HRESULT StylusMove(POINT p);

Parameters

p

The coordinate where the stylus was moved. The coordinate is in a
format compatible with the current display orientation.

Parameters

Specifies additional message information. The contents of this parameter
depend on the value of the msg parameter.

lParam

Specifies additional message information. The contents of this parameter
depend on the value of the msg parameter.

Return values

The return code depend on the value of the msg parameter.

Remarks

You may want to override the default CGapiApplication::WindowProc if
you want other actions to happen when a window message is received that
is already captured by CGapiApplication. You may also want to capture
additional window messages not already captured by CGapiApplication.

If you capture a message you are assumed to return the correct return
code for that message. The return codes vary depending on the msg parameter.
Always call the base class CGapiApplication::WindowProc for all messages
you do not capture in your subclass.

CGapiApplication - Member Variables

The member variables provide additional support for advanced customization
of CGapiApplication.