Documentation
[SDK Documentation] [CGapiApplication]

 

GapiDraw Classes CGapiSurface CGapiRGBASurface CGapiDraw CGapiDisplay CGapiMaskSurface CGapiBitmapFont CGapiCursor CGapiApplication CGapiInput CGapiVFS CGapiTimer CGapiGradient

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:

  1. Create a new GDAPPCONFIG structure and set the parameters you want.
  2. Create a CGapiApplication instance and supply the GDAPPCONFIG structure.
  3. Start the application with CGapiApplication::Run

CGapiApplication will then call the following operations in your subclass:

  1. CGapiApplication::InitInstance
  2. CGapiApplication::CreateSysMemSurfaces
  3. CGapiApplication::CreateVidMemSurfaces
  4. On each frame, CGapiApplication::ProcessNextFrame will be called
  5. 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:

E_FAIL
GDERR_INVALIDMODE
GDERR_INVALIDPARAMS
GDERR_LOCKEDSURFACES
GDERR_NOGAPI
GDERR_OUTOFMEMORY
GDERR_UNSUPPORTEDMODE
GDERR_PRIMARYSURFACEALREADYEXISTS

Remarks

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

  1. CGapiApplication first checks to see another instance is running. If so, that window is restored.
  2. The main window is created based on the options specified in the configuration.
  3. The GapiDraw display is opened and the display mode is set.
  4. CGapiApplication::InitInstance is called in the subclass.
  5. CGapiApplication::CreateSysMemSurfaces is called in the subclass.
  6. CGapiApplication::CreateVidMemSurfaces is called in the subclass.
  7. 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:

  1. CGapiApplication::ExitInstance is called in the subclass.
  2. The GapiDraw display is closed.
  3. Any pending error messages set with CGapiApplication::SetErrorMessage are displayed.
  4. 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::ExitInstance

Override CGapiApplication::ExitInstance to free memory in your application.

virtual HRESULT ExitInstance();
Parameters
None
Return values

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

CGapiApplication::CreateSysMemSurfaces

Override CGapiApplication::CreateSysMemSurfaces to create all your surfaces and coordinates.

virtual HRESULT CreateSysMemSurfaces(CGapiDisplay* pDisplay, HINSTANCE hInstance);
Parameters

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

virtual HRESULT CreateVidMemSurfaces(CGapiDisplay* pDisplay, HINSTANCE hInstance)
Parameters

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

virtual HRESULT ProcessNextFrame(CGapiSurface* pBackBuffer, DWORD dwFlags);
Parameters
pBackBuffer
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.
Return values

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

CGapiApplication::WindowProc

Override CGapiApplication::WindowProc to capture specific window messages.

virtual HRESULT WindowProc(HWND hWnd, UINT msg, WPARAM wParam, LPARAM lParam);
Parameters
hWnd
Handle to the main window.
msg
Specifies the message.
wParam
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.

GDAPPCONFIG
CGapiDraw
CGapiDisplay*
CGapiInput*
CGapiTimer*
CGapiSurface*

m_config;
m_pGapiDraw;
m_pDisplay;
m_pInput;
m_pTimer;
m_pQuarterSizeBackBuffer;
Parameters
m_config
A copy of the GDAPPCONFIG structure passed to the constructor.
m_pGapiDraw
A pointer to the global CGapiDraw object used in all class constructors.
m_pDisplay
The primary surface of the application.
m_pInput
The CGapiInput instance used for all keyboard and stylus input.
m_pTimer
The CGapiTimer object used to sleep between each CGapiApplication::ProcessNextFrame.
m_pQuarterSizeBackBuffer
Used as backbuffer if the display flag GDDISPLAY_QUARTERSIZE was used to open the display.