Documentation
[SDK Documentation] [CGapiMaskSurface]

CGapiMaskSurface

Overview

CGapiMaskSurface is a surface specifically suited for collision detection masks.

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.

CGapiMaskSurface::DrawMask

This method fills an area on the surface using a mask ID.

Parameters

x

The left position on the destination surface for the mask. Can be negative if clipping is enabled.

y

The top position on the destination surface for the mask. Can be negative if clipping is enabled.

pRect

Address of a RECT structure that defines the upper-left and lower-right points of the rectangle to draw to on the destination surface. If this parameter is NULL, the entire destination surface will be used.

pSrcSurface

Address of a key sourced CGapiSurface object that is used as source image to define what area to fill with the mask color.

pSrcRect

Address of a RECT structure that defines the upper-left and lower-right points of the rectangle to use from the source surface. If this parameter is NULL, the entire source surface will be used.

dwMaskID

The ID to use for drawing the mask.

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_INVALIDRECT
GDERR_LOCKEDSURFACES
GDERR_NOTINITIALIZED

Remarks

Masks are used in special buffers dedicated for collision detection. You can draw a single pixel, rectangle or a key sourced surface to the mask surface, and then check for collisions using GetMaskID.

DrawMask automatically takes the ID number specified in dwMaskID and converts it to the current color space. Allowed values are between 1 and 32767. The advantage of using mask ID numbers in favor of colors are that colors are "clipped" on 16-bit devices. For example, if you draw a red rectangle using the color RGB(255, 0, 0), what is actually drawn on the surface is a red rectangle with the color value RGB(248, 0, 0). The reason for this is that the lower 3 bits of the color value is clipped, since only 5 bits are available for each color. Using mask ID numbers, this is no longer an issue since the mask ID numbers are mapped to the available color space.

If you draw to a mask surface and do not "see" anything, it may be because the mask is dark in color. For example, calling DrawMask using a dwMaskID of "1" would cause DrawMask to paint using the color RGB(8, 0, 0). The formula used for drawing the mask ID is:

Color = RGB(((dwMaskID & 0x1F) << 3), ((dwMaskID & 0x3E0) >> 2), (dwMaskID & 0x7C00) >> 7)).

CGapiMaskSurface::GetMaskID

This method returns the mask ID number for a specific area on the mask surface.

Parameters

x

The left position on the destination surface. Can be negative if clipping is enabled.

y

The top position on the destination surface. Can be negative if clipping is enabled.

pRect

Address of a RECT structure that defines the upper-left and lower-right points of the rectangle to use for scanning for mask ID numbers on the destination surface. If this parameter is NULL, the entire destination surface will be scanned.

pSrcSurface

Address of a key sourced CGapiSurface object that is used as source image to define what areas to scan on the mask surface.

pSrcRect

Address of a RECT structure that defines the upper-left and lower-right points of the rectangle to use from the source surface. If this parameter is NULL, the entire source surface will be used.

pMaskID

Address of a DWORD that will be filled with the mask ID. If no mask ID was found within the specified area, the contents of pMaskID will be set to 0.

pIntersection

Address of a POINT structure that will be filled with location where the mask ID was found. If no mask ID was found within the specified area, the coordinates in pIntersection will be set to (-1, -1).

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_INVALIDRECT
GDERR_LOCKEDSURFACES
GDERR_NOTINITIALIZED
GDERR_SURFACELOST