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

GapiDraw 4.0 Win32 Readme.txt

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

Contents

1. Getting Your GapiDraw 3.8 Application to Compile With GapiDraw 4.0
2. Developing for High-Resolution Mobile Devices
3. Enabling Mouse Capture on Stationary PCs
4. Loading Images Relative to the Executable File Location
5. Known Issues

Getting Your GapiDraw 3.8 Application to Compile With GapiDraw 4.0

GapiDraw 4.0 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.0 in five simple steps:

1. Add a menu

All applications developed for GapiDraw 4.0 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.0 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.0 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.0 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