GapiDraw

Documentation
[SDK Documentation] [CGapiDisplay]

GapiDraw Classes

CGapiDisplay

Overview

CGapiDisplay is a representation of the display. It inherits all drawing functionality from CGapiSurface, and adds some extra features such as surface flipping and back buffer support.

Rectangles

All RECT structures are defined so that the right and bottom members are exclusive: right minus left equals the width of the rectangle, not one less than the width. This is to enable full compability with the DirectDraw coordinate system.

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

CGapiDisplay::OpenDisplay

This method initializes the display-device hardware.

HRESULT OpenDisplay(: DWORD dwFlags, HWND hWnd,
DWORD dwWidth, DWORD dwHeight,
DWORD dwZoomWidth, DWORD dwZoomHeight,
DWORD dwBPP, DWORD dwHz)

Parameters

dwFlags

The following table shows the possible flags.

Type	Description
GDDISPLAY_FULLSCREEN	Open the display in full screen mode.
GDDISPLAY_WINDOW	Open the display in windowed mode.
GDDISPLAY_BACKBUFFERSYSMEM	Use a back buffer stored in system memory. Default when application is windowed on stationary PCs or when GDDISPLAY_QUARTERSIZE is used on Windows Mobile devices.
GDDISPLAY_BACKBUFFERVIDMEM	Use a back buffer stored in video memory. Default on Windows Mobile devices or when the application is full screen on stationary PCs.
GDDISPLAY_QUARTERSIZE	(Windows Mobile) Force all surfaces to be stored in system memory. This is for maximum performance when calling PresentQuarterSize.
GDDISPLAY_VSYNC	Try to use VSync when calling Flip().

hWnd

Window handle used for the application. Set to the calling application's top-level window handle (not a handle for any child windows created by the top-level window).

dwWidth

Width of the application window.

dwHeight

Height of the application window.

dwZoomWidth

(Stationary PCs) The window will resize its contents to this width when windowed. Only applicable in windowed mode. Set this value to NULL to disable window zoom.

dwZoomHeight

(Stationary PCs) The window will resize its contents to this height when windowed. Only applicable in windowed mode. Set this value to NULL to disable window zoom.

dwBPP

(Stationary PCs) The bit depth of the display. Valid numbers are NULL (use default 16 bits) or 16.

dwHz

(Stationary PCs) The preferred refresh rate of the display. Only applicable in full screen mode. If set to NULL it will use the adapter default setting.

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:

GDERR_INCOMPATIBLEPRIMARY
GDERR_INVALIDPARAMS
GDERR_NOGAPI
GDERR_OUTOFMEMORY
GDERR_PRIMARYSURFACEALREADYEXISTS
GDERR_SURFACELOST
GDERR_UNSUPPORTEDMODE

Remarks

CGapiDisplay::CloseDisplay is automatically called in the CGapiDisplay destructor. The display can only be opened by one display object. It may be possible to write directly to the display surface (in full screen mode on stationary PCs and some Pocket PCs). You can check if this is possible by calling CGapiSurface::GetSurfaceFlags() and match with the flag GDSURFACE_PRIMARY.

CGapiDisplay uses DirectDraw on Windows Mobile 5.0 and newer devices. On Pocket PC 2003 devices CGapiDisplay will try to use GETRAWFRAMEBUFFER with fallback to GAPI if GETRAWFRAMEBUFFER is unavailable or returns incorrect values.

CGapiDisplay::CreateOffscreenDisplay

This method created a HDC compatible back buffer for blitting to a window.

HRESULT CreateOffscreenDisplay(DWORD dwFlags, DWORD dwWidth, DWORD dwHeight);

Parameters

dwFlags: Reserved for future use. Set to zero.
dwWidth: Width of the back buffer.
dwHeight: Height of the back buffer.

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:

GDERR_INVALIDPARAMS
GDERR_OUTOFMEMORY
GDERR_PRIMARYSURFACEALREADYEXISTS

Remarks

CGapiDisplay::CreateOffscreenDisplay creates a HDC compatible back buffer in that can be used for background applications. Calling CGapiSurface::GetDC() on the backbuffer after calling CreateOffscreenDisplay() is done with zero overhead.

After you have created a HDC compatible back buffer with CGapiDisplay::CreateOffscreenDisplay you can blit it to the display using code such as:

// Copy the back buffer to the main window if active
if (g_bActiveWindow && (hdc = GetDC(g_hWnd)))
{
    if (SUCCEEDED(g_display.GetBackBuffer()->GetDC(&hdcSurf)))
    {
        BitBlt(hdc, 0, 0, g_dwChildWidth, g_dwChildHeight,
        hdcSurf, 0, 0, SRCCOPY);
        g_display.GetBackBuffer()->ReleaseDC(hdcSurf);
        }
    ReleaseDC(g_hWnd, hdc);
}

If you choose to create the back buffer as a HDC compatible bitmap the following restrictions apply:

You should not try to call OpenDisplay() if you have previously called CreateOffscreenDisplay(). Doing so will return GDERR_PRIMARYSURFACEALREADYEXISTS. Full screen exclusive mode is not possible when the backbuffer is created as a HDC bitmap.
You cannot use CGapiApplication. You will have to write your own message handling routines.
You cannot call Flip(), GetMonitorFrequency(), GetAvailableVidMem(), RestoreAllVideoSurfaces() if the backbuffer is created as a HDC bitmap. Doing so will return GDERR_INCOMPATIBLEPRIMARY.

CGapiDisplay::CloseDisplay

This method forces the display to close, preventing all future operations.

HRESULT CloseDisplay();

Parameters

None

Return values

The return value is GD_OK

Remarks

CGapiDisplay::CloseDisplay is automatically called in the CGapiDisplay destructor. The display can only be opened by one object, which automatically will be assigned as the primary surface of the display.

This method must be called by the same thread that created the application window. It is recommended that the display is closed before the window handle passed to CGapiDisplay::OpenDisplay is destroyed.

CGapiDisplay::SetDisplayMode

This method changes the display orientation.

HRESULT SetDisplayMode(DWORD dwMode);

Parameters

dwMode

The following table shows the possible display modes.

Type	Description
GDDISPMODE_NORMAL	Normal display mode (default).
GDDISPMODE_ROTATE90CCW	Rotate display 90 degrees counter clockwise
GDDISPMODE_ROTATE90CW	Rotate display 90 degrees clockwise
GDDISPMODE_ROTATE180	Rotate display 180 degrees

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:

GDERR_INVALIDMODE
GDERR_LOCKEDSURFACES
GDERR_OUTOFMEMORY

Remarks

The display can be rotated without any additional overhead to the GapiDraw blitter operations. This is because all surfaces in GapiDraw are always stored in a cache-optimized format compatible with the display.

The orientation of the display device can be changed at any time. CGapiApplication will automatically call CreateSysMemSurfaces or CreateVidMemSurfaces in your subclass if the display orientation changes.

GDDISPMODE_NORMAL

GDDISPMODE_ROTATE180

GDDISPMODE_ROTATE90CCW

GDDISPMODE_ROTATE90CW

The display orientations used in GapiDraw.

CGapiDisplay::GetDisplayMode

This method returns the current display orientation.

HRESULT GetDisplayMode(DWORD* pMode);

Parameters

pMode: Address of a DWORD that will be filled with the current display mode.

Return values

The return value is GD_OK.

CGapiDisplay::GetBackBuffer

This method returns a pointer to the back buffer surface.

CGapiSurface* CGapiDisplay::GetBackBuffer();

Parameters

None

Return values

If this method succeeds, the return value is a pointer to the back buffer surface.

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

NULL

Remarks

If you plan to use PresentQuarterSize to draw graphics to the display you should use your own surface instead of GetBackBuffer.

CGapiDisplay::RenderSystemFont

This method re-renders the system font in a user-specified color.

HRESULT RenderSystemFont(COLORREF dwColor);

Parameters

dwColor: The color to use to render the system font.

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:

GDERR_INCOMPATIBLEPRIMARY

Remarks

The system font can be of a user-specified color and with an optional black border. If you need another border color, or in other ways need to modify this font, it is delivered in a bitmap format with the GapiDraw distribution.

CGapiDisplay::GetSystemFont

This method returns a temporary pointer to the built-in system font.

CGapiBitmapFont* GetSystemFont();

Parameters

None

Return values

If this method succeeds, the return value is a pointer to the built-in system font.

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

NULL

CGapiDisplay::GetSystemFontBorder

This method returns a temporary pointer to the built-in system font with border.

CGapiBitmapFont* GetSystemFontBorder();

Parameters

None

Return values

If this method succeeds, the return value is a pointer to the built-in system font with border.

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

NULL

CGapiDisplay::DrawDisplayInformation

This method draws display information to a surface that can help developers work around device issues.

HRESULT DrawDisplayInformation(CGapiSurface* pDestinationSurface, CGapiBitmapFont* pBitmapFont);

Parameters

pDestinationSurface: Surface upon which CGapiDisplay will output debug information.
pBitmapFont: The font used to draw the text. If set to NULL, CGapiDisplay will use the default system font stored in system memory.

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:

GDERR_NOTINITIALIZED
GDERR_INVALIDPARAMS;
GDERR_LOCKEDSURFACES

CGapiDisplay::GetDirectDrawInterface

This method returns a pointer to the DirectDraw Interface.

void* GetDirectDrawInterface();

Parameters

None

Return values

If this method succeeds, the return value is a pointer to a DIRECTDRAW object.

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

NULL

CGapiDisplay::GetDirectDrawPrimarySurface

This method returns a pointer to the DirectDraw Primary Surface.

void* GetDirectDrawPrimarySurface();

Parameters

None

Return values

If this method succeeds, the return value is a pointer to a DIRECTDRAWSURFACE object.

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

NULL

CGapiDisplay::GetMonitorFrequency

This method returns the update frequency of the monitor.

HRESULT GetMonitorFrequency(DWORD* pFrequency);

Parameters

pFrequency: Pointer to a DWORD which will receive the update frequency of the monitor.

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:

GDERR_INVALIDPARAMS
GDERR_NOTINITIALIZED
GDERR_NOVIDEOHW

CGapiDisplay::GetAvailableVidMem

This method returns the amount of video memory available.

HRESULT GetAvailableVidMem(DWORD dwFlags, DWORD* pTotal, DWORD* pFree);

Parameters

dwFlags

The following table shows the possible flags.

Type	Description
GDSURFACE_VIDEOMEMORY	Return the total amount of video memory.
GDSURFACE_LOCALVIDMEM	Return the amount of local video memory.
GDSURFACE_NONLOCALVIDMEM	Return the amount of non local video memory.

pTotal: Pointer to a DWORD which will receive the total amount of video memory
pFree: Pointer to a DWORD which will receive the amount of free video memory.

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:

GDERR_INVALIDPARAMS
GDERR_NOTINITIALIZED
GDERR_NOVIDEOHW

Remarks

Surfaces can be stored in video memory on some devices and stationary PCs. Use this function to calculate the video hardware requirements of your application.

CGapiDisplay::GetHWStatus

This method returns the hardware status of the device.

HRESULT GetHWStatus(DWORD* pStatus);

Parameters

pStatus: Pointer to a DWORD which will receive the hardware status.

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:

GDERR_INVALIDPARAMS
GDERR_NOTINITIALIZED
GDERR_NOVIDEOHW

Remarks

The following flags are set in pStatus:

Device type	Back buffer
GDVIDEOHW_VIDMEM	The device is capable of storing surfaces in video memory
GDVIDEOHW_VSYNC	The device can sync updates of the display to the current refresh rate.

CGapiDisplay::SurfacesAreLost

Checks the video hardware if any surfaces have been lost in a previous operation.

HRESULT SurfacesAreLost();

Parameters

None

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:

GDERR_NOTINITIALIZED
GDERR_SURFACELOST
GDERR_NOVIDEOHW

Remarks

Surfaces stored in video memory may be invalidated when a user switches from full screen mode to desktop mode on stationary PCs, or by minimizing an application on a PDA with hardware accelerated graphics. If an operation have failed due to lost surfaces, CGapiDisplay::SurfacesAreLost() will return GDERR_SURFACELOST. Restore the surfaces stored in video memory by calling CGapiDisplay::RestoreAllVideoSurfaces().

CGapiDisplay::RestoreAllVideoSurfaces

This method restores all surfaces stored in video memory, in the order they were created.

HRESULT RestoreAllVideoSurfaces();

Parameters

None

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:

GDERR_NOTINITIALIZED
GDERR_NOVIDEOHW

Remarks

Surfaces stored in video memory may be invalidated when a user switches from full screen mode to desktop mode on stationary PCs, or by minimizing an application on a PDA with hardware accelerated graphics. To restore all surfaces in video memory call this function. Please note that the contents of the surfaces are not restored, requiring you to manually recreate their contents.

CGapiDisplay::Flip

This method transfers the contents of the back buffer associated with the display surface to the display device.

HRESULT Flip();

Parameters

None

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:

GDERR_LOCKEDSURFACES
GDERR_NOTINITIALIZED
GDERR_SURFACELOST

Remarks

Use Flip instead of PresentQuarterSize if you want to use the native resolution of the display.

On stationary PCs with hardware acceleration the back buffer is actually "flipped" with the display - meaning that the contents of the back buffer will be set to the previous frame as shown on the display. Do not assume that the contents of the back buffer is un-altered, and always repaint the full contents of the back buffer on each flip.

On mobile devices page flipping is disabled due to EXCLUSIVE DirectDraw mode is not possible to use since it will block incoming phone call notifications. GapiDraw will instead always use BltFast to copy the backbuffer to the display on Windows Mobile devices.

CGapiDisplay::PresentQuarterSize

This method scales a surface to double width and double height to fit on the display.

HRESULT PresentQuarterSize(CGapiSurface* pQuarterSizeSurface)

Parameters

pQuarterSizeSurface: Pointer CGapiSurface that will be scaled 2 x Width and 2 x Height to fit the display.

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:

GDERR_INVALIDPARAMS
GDERR_NOTINITIALIZED
GDERR_LOCKEDSURFACES
GDERR_INCOMPATIBLEPRIMARY
GDERR_INVALIDPARAMS

Remarks

Use PresentQuarterSize instead of Flip if you want your applications to look the same on QVGA devices as well as high-DPI mobile devices.

The width and height of pQuarterSizeSurface must be exactly half of the display. CGapiDisplay will then use an ARM optimized algorithm to quadruple the pQuarterSizeSurface to fit in the display backbuffer, which is then blitted to the display.

CGapiDisplay::SuspendDisplay

This method suspends all drawing operations to the display and locks the surface.

HRESULT SuspendDisplay();

Parameters

None

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:

GDERR_LOCKEDSURFACES
GDERR_NOTINITIALIZED

CGapiDisplay::ResumeDisplay

This method unlocks the surface and resumes all drawing operations to the display.

HRESULT ResumeDisplay();

Parameters

None

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:

GDERR_NOTINITIALIZED
GDERR_NOTLOCKED

CGapiDisplay::DeviceToLogical

This method transforms a device coordinate to a logical coordinate.

HRESULT DeviceToLogical(RECT* pRect);
HRESULT DeviceToLogical(POINT* pPoint);

Parameters

pRect: Pointer to a RECT structure containing the coordinates to transform.
pPoint: Pointer to a POINT structure containing the coordinates to transform.

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:

GDERR_INVALIDPARAMS
GDERR_NOTINITIALIZED

Remarks

Typical device coordinates are those received from WM_LBUTTONDOWN, and GetWindowRect(). DeviceToLogical transforms these coordinates into coordinates matching the current display orientation.

On Stationary Computers, DevictToLogical takes Window Size into account and scales the coordinates accordingly.