Documentation
[SDK Documentation] [CGapiDisplay]

 

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

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:

  1. 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.
  2. You cannot use CGapiApplication. You will have to write your own message handling routines.
  3. 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.