Documentation
[SDK Documentation] [GapiDraw 4.2 Win32 Readme.txt]

 

GapiDraw 4.2 Win32 Readme.txt

This document has been updated for use with GapiDraw 4.2 or later.
Last updated on July 11, 2009.

 

Contents

  1. GapiDraw and GAPI
  2. GapiDraw Versions (WM 5.0 and PPC 2003)
  3. Xperia Panel Development
  4. Compiling for Pocket PC 2003 in Visual Studio 2008
  5. Getting Your GapiDraw 3.8 Application to Compile With GapiDraw 4
  6. Developing for High-Resolution Mobile Devices
  7. Enabling Mouse Capture on Stationary PCs
  8. Loading Images Relative to the Executable File Location
  9. Known Issues

 

GapiDraw and GAPI

The Microsoft Game API (GAPI) was for almost a decade the most popular way to achieve fast access to the display on Windows Mobile devices. As of Windows Mobile 6.5, the GAPI library has now been discontinued and many devices are expected to ship without working GAPI libraries. Microsoft therefore requires that mobile applications shipping on the Windows Marketplace for Mobile no longer uses the GAPI library.

GapiDraw was from the beginning designed to be as similar to DirectDraw as possible. When first launched in 2002, one of the key selling points of GapiDraw was that developers could easily move existing DirectDraw code to mobile devices, since the GapiDraw API was so similar to DirectDraw. In 2002 GapiDraw used DirectDraw on stationary PCs and the GAPI library on mobile devices, but for the past years GapiDraw has shipped in two mobile versions - one that uses GAPI (built for PPC 2003) and one that only uses DirectDraw (built for WM 5.0 and later).

Up to and including GapiDraw 4.1, GapiDraw still used the Microsoft GAPI library to lock all the keys on the device. As of GapiDraw 4.2 we have now finally moved to an alternative API - AllKeys, which means that there is not a single dependency left to the GAPI library in GapiDraw. For maximum device compatibility we still maintain and support the Pocket PC 2003 "GAPI based" version of GapiDraw, even if we recommend all developers to use the DirectDraw build for Windows Mobile 5.0 and later devices as their primary development platform.

GapiDraw 4.2 for WM 5.0 and later can be used to create applications for the Windows Marketplace.

 

GapiDraw Versions (WM 5.0 and PPC 2003)

There are two main types of GapiDraw builds included in the distribution: One for Pocket PC 2003 devices (PPC 2003), and one for Windows Mobile 5.0 (WM 5.0) and later devices. The compatibility list is as follows:

GapiDraw build for PPC 2003

  • Uses GETRAWFRAMEBUFFER and GAPI (gx.dll) to draw graphics to the display
  • Uses GAPI (gx.dll) to lock all buttons on the device
  • Compatible with all PPC 2003, WM 5.0, WM 6.0 and WM 6.1 devices

GapiDraw build for Windows Mobile 5.0

  • Uses DirectDraw to draw graphics to the display
  • Uses AllKeys to lock all buttons on the device
  • Compatible with all WM 5.0, WM 6.0, WM 6.1 and WM 6.5 devices and Windows Marketplace

Our recommendation is that you create two builds of your application as follows:

  1. One build for legacy PPC 2003 devices (using the GapiDraw build for PPC 2003 devices)
  2. One build for Windows Mobile 5.0 and later devices (using the GapiDraw build for WM 5.0 devices)

 

Xperia Panel Development

GapiDraw 4.1 introduced a new framework for developing panel applications: CGapiPanelApplication. This framework is fully compatible with CGapiApplication, but it is multithreaded which means that there are some issues you might have to consider when using this framework.

1. Memory allocations. Do not allocate memory as a response to a Window Message. This means that the Windows process will be allocating the memory, and you would then later have a crash if you try to free this memory in your own process. Do all memory allocation within the functions called by the worker thread such as InitApplication, CreateSurfaces or ProcessNextFrame. Do not allocate memory in OnKeyDown etc that are triggered by window messages.

2. Mutex locks. It might happen that you will get a call to OnKeyDown or OnStylusDown while you are performing a ProcessNextFrame, since ProcessNextFrame runs in its own worker thread. Be aware of these possible pitfalls, and avoid them by using thread synchronization objects such as mutex.

Other than the above two concerns you should have few issues when creating your panels using the GapiDraw framework. You will find the sample panel application in the "Xperia" folder in the "Samples" directory.

 

Compiling for Pocket PC 2003 in Visual Studio 2008

If you try to compile any of the sample applications for the Pocket PC 2003 SDK within Visual Studio 2008 you might experience the following issue:

unresolved external symbol __security_cookie

To resolve this issue you have to go into the C++ Generation Settings and disable Buffer Security Check as can be seen in the picture below.

BufferSecurityCheck
If you build for Pocket PC 2003 within Visual Studio 2008 you should disable the Buffer Security Check.

 

Getting Your GapiDraw 3.8 Application to Compile With GapiDraw 4

GapiDraw 4 introduces a few minor SDK changes that require you to change a parts of your application. In this section we will describe how to get your GapiDraw 3.8 application to compile with GapiDraw 4 in five simple steps:

1. Add a menu

All applications developed for GapiDraw 4 should define a menu bar with two options. The menu bar will be shown if the application is run in windowed mode. Add a menu bar to your project using the Resource View in Visual Studio, name it IDM_GAPIAPPLICATION and add two menu options to it. Name the two menu options ID_VKA and ID_VKB and set them to be of type Popup: FALSE.

2. Change flags

If your application is built for high resolution displays, remove the display flag GDDISPLAY_HI_RES_AWARE from your project. This flag is no longer used since GapiDraw 4 by default will use high resolution displays. Similarly, if your application did not use the GDDISPLAY_HI_RES_AWARE flag, you should add the new flag GDDISPLAY_QUARTERSIZE to have the backbuffer created with half width and half height of the display if either the width or height of the display exceeds 320 pixels.

3. Backbuffer access

It is a good idea to search for all occurrences of m_pDisplay, GetDisplay() and GetBackBuffer() in your code. As of GapiDraw 4 the GapiApplication backbuffer can be different from the CGapiDisplay backbuffer if the display flag GDDISPLAY_QUARTERSIZE is used. You should therefore always use CGapiApplication::GetBackbuffer() when calculating width, height or scaling factors. And you should never copy graphics directly to the CGapiDisplay backbuffer, but instead use CGapiApplication::GetBackbuffer() to retrieve a pointer to the current backbuffer.

4. Change methods

CGapiApplication::CreateSysMemSurfaces and CGapiApplication::CreateVidMemSurfaces now take a CGapiSurface* parameter instead of a CGapiDisplay* parameter, so you need to change your implementation of these two virtual functions. This is because the backbuffer can now be in a different size than the display (if you use the GDDISPLAY_QUARTERSIZE flag).

5. Build two versions

Pocket PC and Smartphone 2003 devices: GapiDraw uses GETRAWFRAMEBUFFER with fallback to GAPI. GapiDraw can only use the display in full screen mode. Hardware accelerated graphics not available.

Windows Mobile 5.0 devices and later: GapiDraw uses DirectDraw for all graphics. GapiDraw can use the display in either windowed or full screen mode. Hardware accelerated graphics will be used if available.

Starting with GapiDraw 4 it is recommended that you distribute two versions of your application: One for Pocket PC 2003 devices and one for Windows Mobile 5.0 and newer devices. This is because GAPI and GETRAWFRAMEBUFFER are not implemented on many newer devices and can lead to unpredictable behaviour. You will also gain the advantages such as windowed mode and hardware accelerated graphics on some devices using the DirectDraw library.

 

Developing for High-Resolution Mobile Devices

GapiDraw fully supports high-resolution displays on Windows Mobile 2003 SE and later devices, and GapiDraw will always open the display in it's native screen resolution. If your application was designed for low-resolution units, you can set the display flag GDDISPLAY_QUARTERSIZE which means that the back buffer of the application will be half width and half height if the application is run on a device where the width or height of the display is more than 320 pixels (e.g. if device runs at 800x480 pixels, the back buffer will be 400x240 pixels).

Please remember to also add a resource called HI_RES_AWARE to your application project, otherwise your application will be running at an extremely low performance emulation mode. Also, if you do not add this resource, Windows Mobile 2003 SE will scale all stylus coordinates down to QVGA resolution! The resource HI_RES_AWARE must be of type CEUX.

This is how your .rc file should look:

/////////////////////////////////////////////////////////////////////////////
//
// CEUX
//
HI_RES_AWARE CEUX DISCARDABLE
BEGIN
0x0001
END

All sample applications shipped with GapiDraw support high-resolution displays and already have the HI_RES_AWARE flag set.

 

Enabling Mouse Capture on Stationary PCs

Question

On a build for stationary PCs, it is possible to press down a mouse button in the window and then move the mouse outside the window and release the mouse. So, the application does not receive a StylusUp event, and it's state is incorrect. How should I deal with this issue? Should I handle events for window exit and enter? Where should I be doing this in a GapiDraw application (that also runs in windowed mode on PC)?

Answer

Add the following code to your subclass of CGapiApplication:

//----------------------------------------------------------------------
HRESULT CMyApplication::StylusDown(POINT p)
//----------------------------------------------------------------------
{
#ifndef _WIN32_WCE
    ::SetCapture( m_hwnd );
#endif

    // Rest of code here //
}

//----------------------------------------------------------------------
HRESULT CMyApplication::StylusUp(POINT p)
//----------------------------------------------------------------------
{
#ifndef _WIN32_WCE
    if( ::GetCapture() == m_hwnd )
    ::ReleaseCapture();
#endif

    // Rest of code here //
}

 

Loading Images Relative to the Executable File Location

Question

I have images stored in a folder "\mygame\data". When I start my application as "\mygame\myapplication.exe" and try to call CreateSurface(GDSURFACE_SYSTEMMEMORY, _T("data\\image.png")) the call fails and returns GDERR_BITMAPNOTFOUND!

Answer

GapiDraw always uses the current folder location to search for images. If you start your application from Visual Studio, the current location can be something different from the folder where your application resides. To get the searchpath to your application you can use the following code and that way use absolute file paths with CreateSurface.

DWORD getModuleDirectory(HMODULE hModule, TCHAR* szPath, DWORD dwLength)
{
    DWORD dwLen;
    TCHAR* p;
    if (0 == (dwLen = GetModuleFileName(hModule, szPath, dwLength)))
    {
        return(0);
    }
    p = szPath + dwLen;
    while (p != szPath)
    {
        if (TEXT('\\') == *--p)
        {
            *(++p) = 0;
            break;
        }
    }
    return(p - szPath);
}

Call the above function using:

    TCHAR gameEXEPath[_MAX_PATH];
    getModuleDirectory(GetModuleHandle(NULL), gameEXEPath, sizeof(gameEXEPath) / sizeof(TCHAR));

Append the filename of your bitmap to the application path using _tcscat(gameEXEPath, TEXT("imagefile"))).

 

Known Issues

None