Documentation
[SDK Documentation] [CGapiSurface]

CGapiSurface

Overview

CGapiSurface is a memory area to which you can draw images and primitives.

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.

Hardware Acceleration

Operations that are hardware accelerated have a [HW Accelerated] label placed in their description. Hardware acceleration is available on stationary PCs in full screen mode and some Windows Mobile devices.

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

CGapiSurface::CreateSurface

This method allocates memory for the surface and prepares it for graphic operations. It can also be used to load an image to the surface from a file, resource, or from a virtual file system.

Parameters

dwFlags

Creation options. The following table shows the possible types.

Type	Description
GDSURFACE_CLEAR	Clears the surface memory area after creation.
GDSURFACE_ALPHA	Use only alpha information when loading a transparent PNG image.
GDSURFACE_NOCOORDCHECK	Disable coordinate verifications.
GDSURFACE_SYSTEMMEMORY	Store the surface in system memory. Default when application is windowed on stationary PCs or when the display was initialized using the flag GDDISPLAY_QUARTERSIZE on Windows Mobile devices.
GDSURFACE_VIDEOMEMORY	Store the surface in video memory (try to use local video memory if available, otherwise fall back to non local video memory). Default on Windows Mobile devices when GDDISPLAY_QUARTERSIZE is not used or when the application is full screen on stationary PCs.
GDSURFACE_LOCALVIDMEM	(Stationary PCs) The surface is stored in local video memory and will return an error if local video memory is not available. Default when application is full screen on stationary PCs.
GDSURFACE_NONLOCALVIDMEM	(Stationary PCs) The surface is stored in non local video memory and will return an error if non local video memory is not available.

pSrcSurface

Surface to be used as a source image when creating a copy. The size and contents of the local surface will be erased and adjusted to fit the source image. The pSrcSurface surface will not be modified.

dwWidth

The width of the surface in pixels.

dwHeight

The height of the surface in pixels.

pImageFile

The name of an image file name to be loaded into the surface.

 

dwResourceID

The ID of a bitmap resource to be loaded into the surface.

pImageFileMem

The address of an image file in memory to be loaded into the surface.

dwImageFileSize

The size of the memory area containing the image.

hInstance

The instance handle containing the requested bitmap resource.

pResourceType

The name of the resource category where your image is located. If your image is BMP you can omit this parameter.

pVFS

A pointer to a GapiVFS virtual file system.

pGapiFileStream

A pointer to a file that will be streamed from a GapiVFS virtual file system.

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_BITMAPNOTFOUND
GDERR_INCOMPATIBLEPRIMARY
GDERR_INVALIDBITMAP
GDERR_INVALIDPARAMS
GDERR_INVALIDSURFACETYPE
GDERR_LOCKEDSURFACES
GDERR_OUTOFMEMORY
GDERR_SURFACELOST

Performance

If CreateSurface is called multiple times on the same instance, memory will not be re-allocated if:
(((newwidth == oldwidth) && (newheight == oldheight)) || ((newwidth == oldheight) && (newheight == oldwidth))). If the surface is stored in video memory, memory will not be re-allocated if: ((newwidth == oldwidth) && (newheight == oldheight)).

Remarks

If no flags are specified, CGapiSurface::CreateSurface will try to create the surface in local video memory. If that fails, it will try non local video memory. If that also fails GapiDraw will fall back to system memory. You can use the flags GDSURFACE_VIDEOMEMORY, GDSURFACE_LOCALVIDMEM, and GDSURFACE_NONLOCALVIDMEM to force GapiDraw to try video memory and return an error if failed.

Previous data stored in the surface will be deleted, even if the call to CGapiSurface::CreateSurface failed. All data allocated by a surface object will automatically be freed when the surface object is deleted. If you manually want to free all data allocated by a surface you can call CGapiSurface::FreeSurface.

The width and height of the surface will be adjusted to fit the entire image. Supported image file types are BMP, GIF, JPG and PNG. BMP images can be RLE-encoded (1, 4, 8, and 24-bit BMPs are supported). BMP and PNG images will be loaded with zero-memory-overhead, and it is strongly recommended that you only use these bitmap formats in your application. PNG images may not be grayscale or progressive since that format is not compatible with the zero-memory-overhead image loader.

Transparent GIF images are fully supported on Stationary PCs only. Note that you must set the color that should replace the transparent parts of your image before you create your surface, using CGapiSurface::SetColorKey(). Some Pocket PCs and Smartphones have an incorrect GIF decoder built in (IMGDECMP.DLL) that always draws all transparent parts of an image in white color, regardless of the input parameters. If this is corrected in a future update, GapiDraw will work correctly with transparent GIF images on these updated devices. Currently it is recommended to use an image format other than transparent GIF, or to set the color key of your surface to RGB(255, 255, 255) to filter the background if you really need transparent GIF images on the Pocket PC or Smartphone.

When images are loaded from file, GapiDraw will use an absolute file path if pImageFile begins with "\" or "x:\". If pImageFile does not begin with "\" or "x:\", GapiDraw will use the current path and append the image file name (e.g. if your executable is run in the folder "\Program Files\Games\MyGame\" and you call CreateSurface with pImageFile set to "MyPicture.png", GapiDraw will try to load the image as "\Program Files\Games\MyGame\MyPicture.png").

CGapiSurface::FreeSurface

This method frees all resources associated with the surface.

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_INVALIDSURFACETYPE
GDERR_LOCKEDSURFACES
GDERR_SURFACELOST

Remarks

All resources allocated by a surface is automatically freed when the surface is deleted. Call CGapiSurface::FreeSurface if you manually want to free all resources before the surface is deleted.

CGapiSurface::GetWidth

This method returns the width of the surface in pixels.

Parameters

None

Return values

The width of the surface in pixels. If the surface has not yet been created, the returned width will be 0.

CGapiSurface::GetHeight

This method returns the height of the surface in pixels.

Parameters

None

Return values

The height of the surface in pixels. If the surface has not yet been created, the returned height will be 0.

CGapiSurface::GetColorKey

This method retrieves the color key value for the surface.

Parameters

pColorKey

Address of a COLORREF that will be filled with the current color key.

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

CGapiSurface::SetColorKey

This method sets the color key value for the surface.

Parameters

pColorKey

The color key that will be used as source color key.

Return values

The return value is GD_OK.

Remarks

The color key will not be removed if you call CGapiSurface::CreateSurface.

CGapiSurface::GetClipper

This method retrieves the clipping viewport for the surface.

Parameters

pRect

Address of a RECT that will be filled with the current clipping viewport.

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_LOCKEDSURFACES
GDERR_NOTINITIALIZED

CGapiSurface::SetClipper

This method sets the clipping viewport for the surface.

Parameters

pRect

The rectangle that will be used as viewport. Can be NULL to set the entire surface as viewport. Please see remarks below.

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_LOCKEDSURFACES
GDERR_NOTINITIALIZED
GDERR_OUTOFMEMORY
GDERR_SURFACEBUSY

Remarks

Call SetClipper(NULL) to enable clipping on the entire surface. Call SetClipper with an empty rectangle to remove the viewport (pRect = {0, 0, 0, 0}). Call SetClipper with a valid rectangle to enable a viewport smaller than the surface. The rectangle pRect is automatically clipped to the surface border. If you call CGapiSurface::CreateSurface on a valid surface that has a clipper, the clipper will be removed even if the surface dimensions have not changed.

The built-in software clipper in GapiDraw is pixel perfect in all operations (meaning that no fixed point errors are visible in any operations). Please note that if the surface is stored in video memory the standard DirectDraw clipper is used. The DirectDraw clipper is however not pixel perfect, so if you need high quality clipping of stretched blits it is recommended that you store the surface in system memory and use the GapiDraw software clipper instead.

CGapiSurface::LockVideoSurface

This method locks the surface if it is stored in video memory.

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_INCOMPATIBLEPRIMARY
GDERR_NOTINITIALIZED
GDERR_NOVIDEOSURFACE
GDERR_LOCKEDSURFACES
GDERR_SURFACELOST

Remarks

If a surface is stored in video memory it has to be locked exclusively on each operation that is not hardware accelerated. Locking a surface involves much overhead, and should be avoided if possible. Call CGapiSurface::LockVideoSurface if you intend to use several consecutive non-accelerated operations on surfaces stored in video memory.

If a surface is video locked, and an operation is performed to the surface that can be hardware accelerated (such as BltFast), the surface is temporarily unlocked, the operation is performed using video hardware, and then re-locked again.

Important! Do not lock video surfaces for a long time. Only keep them locked for as short amount of time as possible.

CGapiSurface::UnlockVideoSurface

This method unlocks the surface if it is stored in video memory.

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_INVALIDPARAMS
GDERR_BITMAPWRITEERROR
GDERR_NOTINITIALIZED
GDERR_LOCKEDSURFACES

CGapiSurface::GetBuffer

This method obtains a pointer to the internal memory buffer used by CGapiSurface.

Parameters

pGDBufferDesc

Address of a GDBUFFERDESC structure that will be filled with the relevant details about the 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_INCOMPATIBLEPRIMARY
GDERR_INVALIDPARAMS
GDERR_LOCKEDSURFACES
GDERR_NOTINITIALIZED
GDERR_SURFACELOST

Remarks

CGapiSurface::GetBuffer is used to directly access the internal memory buffer of a surface. You can use CGapiSurface::GetBuffer if you want to draw full screen video, 3D, plasma effects or if you in any other way need to set multiple pixels and cannot afford the overhead of a function call.

CGapiSurface::GetBuffer will place a lock on the surface that is not be released until CGapiSurface::ReleaseBuffer is called. The lock prevents other operations to use the surface until CGapiSurface::ReleaseBuffer is called.

Surfaces in GapiDraw can be of 555 or 565 pixel formats (see the GapiDraw overview for details). To convert standard RGB color values to a native surface color value you can use the routines available in the file GapiDrawExtension.h.

CGapiSurface::ReleaseBuffer

Releases the previously locked internal memory buffer used by CGapiSurface.

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
GDERR_DCLOCKED

CGapiSurface::GetDC

This method creates a GDI-compatible handle of a device context for the surface.

Parameters

pDC

Address for the returned handle to a device context.

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_CANTCREATEDC
GDERR_INCOMPATIBLEPRIMARY
GDERR_INVALIDPARAMS
GDERR_LOCKEDSURFACES
GDERR_NOTINITIALIZED
GDERR_OUTOFMEMORY
GDERR_SURFACELOST

Remarks

Do not delete the DC handle returned in pDC. This handle will automatically be deleted by CGapiSurface, even if a corresponding call to ReleaseDC is not issued.

This method uses an internal version of the CGapiSurface::Lock method to lock the surface. The surface remains locked until the CGapiSurface::ReleaseDC method is called.

If the surface flag GDSURFACE_GDI is set, CGapiSurface::GetDC requires a minimum amount of overhead. The flag GDSURFACE_GDI is set on the backbuffer if the display was opened using CGapiDisplay::CreateOffscreenDisplay.

CGapiSurface::ReleaseDC

This method releases the handle of a device context previously obtained by using the CGapiSurface::GetDC method.

Parameters

hDC

Handle to a device context previously obtained by CGapiSurface::GetDC.

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_NODC
GDERR_NOTINITIALIZED
GDERR_NOTLOCKED
GDERR_SURFACELOST

Remarks

This method unlocks the surface previously locked when the CGapiDraw::GetDC method was called.

CGapiSurface::SaveSurface

This method saves the contents of the surface as a bitmap file.

Parameters

pBitmapFile

The name of the bitmap file to which surface data will be written.

dwFlags

The following table shows the possible flags.

Type	Description
GDSAVESURFACE_BMP	The surface is saved as a 24-bit BMP image - default.
GDSAVESURFACE_PNG	The surface is saved as a true color PNG image.

 

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

Remarks

Surfaces are saved with zero memory overhead, requiring no additional memory than the current surface.

CGapiSurface::GetSurfaceFlags

This method retrieves current flags for the surface.

Parameters

pOptions

Address of a DWORD that will be filled with the current surface flags.

Return values

The return value is GD_OK.

Remarks

The following flags can be set:

CGapiSurface::ColorrefToNative

This method converts an RGB color value to the native format used by the surface.

Parameters

dwColor

The RGB color value to be converted.

pNative

Address of a DWORD that will be filled with the native color value.

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_NOTINITIALIZED

CGapiSurface::NativeToColorref

This method converts a native color value used by the surface to a generic RGB value.

Parameters

dwNative

The native color value to be converted.

pColorKey

Address of a COLORREF that will be filled with the RGB color value.

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_NOTINITIALIZED

CGapiSurface::AlphaBlt

This method blits a rectangular source image to a destination rectangle using an alpha blend surface.

Parameters

pDestRect

Pointer to destination rectangle for blit operation. This parameter specifies a rectangular region of the destination surface. If a null pointer is specified, the effective destination rectangle is the entire destination surface.

pSrcSurface

Pointer to source surface for blit operation.

pSrcRect

Pointer to source rectangle for blit operation. This parameter specifies a rectangular region of the source surface. If a null pointer is specified, the effective source rectangle is the entire source surface.

pAlphaSurface

Pointer to alpha surface for blit operation.

pAlphaRect

Pointer to alpha rectangle for blit operation. This parameter specifies a rectangular region of the alpha surface. If a null pointer is specified, the effective alpha rectangle is the entire alpha surface.

dwFlags

The following table shows the possible flags.

Type	Description
GDALPHABLT_OPACITY	Uses the opacity value in pGDAlphaBltFx->dwOpacity to adjust the overall weight of the alpha blend. Allowed range is from 0 (transparent) to 255 (opaque). If the opacity is set to 128, an optimized blending mode will be used.
GDALPHABLT_MIRRORLEFTRIGHT	Mirrors the source image left-to-right in the destination rectangle.
GDALPHABLT_MIRRORUPDOWN	Mirrors the source image vertically in the destination rectangle.

pGDAlphaBltFx

Pointer to a GDALPHABLTFX structure.

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_LOCKEDSURFACES
GDERR_INVALIDPARAMS
GDERR_INVALIDRECT
GDERR_NOTINITIALIZED
GDERR_OUTOFMEMORY
GDERR_SURFACELOST

Performance

CGapiSurface::AlphaBltFast is much faster than CGapiSurface::AlphaBlt. If you need to stretch or mirror the source surface during the blit, use CGapiSurface::AlphaBlt. Otherwise you should always use CGapiSurface::AlphaBltFast.

AlphaBlt will always check if the alpha value is black (transparent - no pixels are copied), or white (opaque - pixels are copied but not alpha blended) before performing the actual alpha blend with the destination. For best performance, try to use as large blocks of black and white in your alpha surface as possible.

AlphaBlt performs best when RGBA surfaces are used.

Remarks

Alpha surfaces must be gray scale for the internal optimizations to work. You can create a surface to use as alpha surface by using the flag GDSURFACE_ALPHA when creating a surface from a transparent PNG image with variable alpha.

For those unfamiliar with alpha blending, it involves the process of blending two surfaces together based on a variable weight of influence for each pixel. The weight of influence for each pixel is specified using a separate surface, called alpha surface. The effect can best be described as in the following figure:

Note: For best results with AlphaBlt, always use a black background color of RGB(0, 0, 0) in your source image.

CGapiSurface::AlphaBltFast

This method blits a rectangular source image to a destination rectangle using an alpha blend surface.

Parameters

destX

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

destY

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

pSrcSurface

Pointer to source surface for blit operation.

pSrcRect

Pointer to source rectangle for blit operation. This parameter specifies a rectangular region of the source surface. If a null pointer is specified, the effective source rectangle is the entire source surface.

pAlphaSurface

Pointer to alpha surface for blit operation.

pAlphaRect

Pointer to alpha rectangle for blit operation. This parameter specifies a rectangular region of the alpha surface. If a null pointer is specified, the effective alpha rectangle is the entire alpha surface.

dwFlags

The following table shows the possible flags.

Type	Description
GDALPHABLTFAST_OPACITY	Uses the opacity value in pGDABltFastFx->dwOpacity to adjust the overall weight of the alpha blend. Allowed range is from 0 (transparent) to 255 (opaque). If the opacity is set to 128, an optimized blending mode will be used.

pGDABltFastFx

Pointer to a GDALPHABLTFASTFX structure.

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

Performance

CGapiSurface::AlphaBltFast is much faster than CGapiSurface::AlphaBlt. If you need to stretch or mirror the source surface during the blit, use CGapiSurface::AlphaBlt. Otherwise you should always use CGapiSurface::AlphaBltFast.

AlphaBltFast will always check if the alpha value is black (transparent - no pixels are copied), or white (opaque - pixels are copied but not alpha blended) before performing the actual alpha blend with the destination. For best performance, try to use as large blocks of black and white in your alpha surface as possible.

Depending on how the rectangles to be copied are aligned, AlphaBltFast will:

1. Read, write and operate on two pixels simultaneously
   (source and destination [left, top] are both on even or odd coordinates)
2. Read two pixels simultaneously, operate and write pixels separately to destination
   (source [left, top] is on even coordinates, destination [left, top] is on odd coordinates)
3. Read, write and operate on one pixel at a time
   (source [left, top] is on odd coordinates, destination [left, top] is on even coordinates)

AlphaBltFast performs best when separate surfaces for image and alpha are used. If separate surfaces for image and alpha + option (1) above is used, GapiDraw will use a fast 32-bit alpha blend routine.

Remarks

Alpha surfaces must be gray scale for the internal optimizations to work. You can create a surface to use as alpha surface by using the flag GDSURFACE_ALPHA when creating a surface from a transparent PNG image with variable alpha.

Please see the documentation on CGapiSurface::AlphaBlt for additional remarks.

CGapiSurface::Blt

This method performs a bit block transfer with optional rotation and scaling. [HW Accelerated]

Parameters

pDestRect

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

pSrcSurface

Address of a CGapiSurface object that is the source of the blit. This value can be null only if the flag GDBLT_COLORFILL is set.

pSrcRect

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

dwFlags

A combination of flags that determine the valid members of the associated GDBLTFX structure, specify color key information, or that request special behavior from the method.

Type	Description
<No Flags>	A fast stretched blit. [HW Accelerated]
GDBLT_KEYSRC	Uses the color key associated with the source surface. Source pixels matching the color key are transparent when blitted to the destination. The source color-key value has to be specified in an earlier call to CGapiSurface::SetColorKey. [HW Accelerated]
GDBLT_COLORFILL	Uses the pixel value in pGDBltFx->dwFillColor instead of source image to perform a color fill.
GDBLT_OPACITY	Uses the opacity value in pGDBltFx->dwOpacity to perform an alpha blend. Allowed range is from 0 (transparent) to 255 (opaque). If the opacity is set to 128, an optimized blending mode will be used.
GDBLT_MIRRORLEFTRIGHT	Mirrors the source image left-to-right (before rotation). [HW Accelerated on Stationary PCs]
GDBLT_MIRRORUPDOWN	Mirrors the source image vertically (before rotation). [HW Accelerated on Stationary PCs]
GDBLT_ROTATIONANGLE	Uses the rotation angle in pGDBltFx->nRotationAngle as the rotation angle (specified in 1/100th of a degree) for the surface.
GDBLT_ROTATIONSCALE	Uses the rotation scale in pGDBltFx->dwRotationScale as the rotation scale factor (specified in percent) for the surface. Please note that in GapiDraw 2.04 you must specify the GDBLT_ROTATIONANGLE flag to use the GDBLT_ROTATIONSCALE parameter.
GDBLT_ROTATIONCENTER	Uses the specified point in pGDBltFx->rotationCenter as center of rotation in the destination rectangle. This value can be negative. Please note that in GapiDraw 2.04 you must specify the GDBLT_ROTATIONANGLE flag to use the GDBLT_ROTATIONSCALE parameter.

pGDBltFx

Pointer to a GDBLTFX structure.

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_OUTOFMEMORY
GDERR_SURFACELOST

Performance

CGapiSurface::BltFast is always much faster than CGapiSurface::Blt. If you need to stretch or mirror the source surface during the blit, use CGapiSurface::Blt. Otherwise you should always use CGapiSurface::BltFast.

CGapiSurface::Blt will always calculate a minimum rectangle for the destination if rotation is used. This means that you do not have to specify the destination rectangle unless you want CGapiSurface::Blt to clip the drawing to a specific portion of the destination surface.

If both source and destination surface are stored in video memory, and only HW accelerated flags are used, Blt will use video hardware for the copy.

It is recommended to use as small destination rectangle as possible.

Remarks

Many DirectDraw drivers are known to have issues with hardware-accelerated Blt. Especially stretched surfaces in combination with color keys will not work on most NVidia cards. Only use hardware-accelerated stretch (where source rect and dest rect are of different sizes) + color key if you know in advance what hardware you will run your application on (e.g. ATI chips do not suffer from this issue). Otherwise create your source surface in system memory and use the software based routine in GapiDraw.

COLOR KEYS

Partially transparent blits, or "Masked Blits" are supported in GapiDraw by the use of color keys. A color key is a color value that is attached to a surface. If the color key option is used in a blit, all pixels matching the color of the color key in the source surface will not be copied to the destination area. For an example of a color key blit operation, please see the figure below.

OPACITY, COLOR FILL, ROTATE and ZOOM

The Opacity Value indicates that an alpha blend should be use to blit the source image into the background. Allowed range is from 0 (transparent) to 255 (opaque). Using a value of 128 will cause Blt to use an optimized color blend version ((a + b) >> 1). Please see Result (a) below for a blit using opacity.

Color Fills are useful to create shadows and highlighted areas - see Result (b) below. If pSrcSurface is NULL, the entire destination rectangle will be filled with the specified color fill value. If pSrcSurface is NULL and color fill is being used, the operation CGapiSurface::FillRect will automatically be used internally.

Rotation is used to rotate a source image clockwise during the blit. Degrees are specified in 1/100 degrees. The spaceship in Result (c) below was rotated using a rotation value of 3000 (30 degrees). Images can also be scaled during the blit, using the rotation scale value. The image in Result (d) shows a source image that was both rotated 30 degrees and scaled by 300 percent.

CGapiSurface::BltFast

This method performs a fast bit block transfer with optional effects. [HW Accelerated]

Parameters

destX

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

destY

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

pSrcSurface

Pointer to source surface for blit operation. This value can be null only if the flag GDBLTFAST_COLORFILL is set.

pSrcRect

Pointer to source rectangle for blit operation. This parameter specifies a rectangular region of the source surface. If a null pointer is specified, the effective source rectangle is the entire source surface.

dwFlags

A combination of flags that determine the valid members of the associated GDBLTFASTFX structure, specify color key information, or that request special behavior from the method.

Type	Description
<No Flags>	A fast 1:1 blit. [HW Accelerated]
GDBLTFAST_KEYSRC	Uses the color key associated with the source surface. Source pixels matching the color key are transparent when blitted to the destination. The source color-key value was specified in an earlier call to CGapiSurface::SetColorKey. [HW Accelerated]
GDBLTFAST_COLORFILL	Uses the pixel value in pGDBltFastFx->dwFillColor instead of source image to perform a color fill.
GDBLTFAST_OPACITY	Uses the opacity value in pGDBltFastFx->dwOpacity to perform an alpha blend. Allowed range is from 0 (transparent) to 255 (opaque). If the opacity is set to 128, an optimized blending mode will be used.
GDBLTFAST_FXOPACITY	FX Opacity: Uses the value in GDBLTFASTFX.dwFXopacity to control amount of effect (0-255)
GDBLTFASTFX_MULTIPLY	FX Color multiply: Uses the color in GDBLTFASTFX.dwFXcolor1 to multiply source.
GDBLTFASTFX_SCREEN	FX Color screen: Uses the color in GDBLTFASTFX.dwFXcolor1 to screen source.
GDBLTFASTFX_OVERLAY	FX Color overlay: Uses the color in GDBLTFASTFX.dwFXcolor1 to overlay source.
GDBLTFASTFX_TINT	FX Color tint: Uses the angle in GDBLTFASTFX.dwFXparam1 to adjust source hue ((-180)-(180) degrees).
GDBLTFASTFX_COLORIZE	FX Colorize: Uses the color in GDBLTFASTFX.dwFXcolor1 to colorize source.

pGDBltFastFx

Pointer to a GDBLTFASTFX structure.

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

Performance

CGapiSurface::BltFast is always much faster than CGapiSurface::Blt. If you need to stretch or mirror the source surface during the blit, use CGapiSurface::Blt. Otherwise you should always use CGapiSurface::BltFast.

Depending on the surfaces, and how the rectangles to be copied are aligned, BltFast will:

1. Use hardware-acceleration
   (source and destination are placed in video memory, and only HW accelerated flags are used)
2. memcpy the entire surface
   (source and destination are of same size and have the same pitch values, no flags are used)
3. memcpy each surface row
   (source and destination are of same size but have different pitch values, no flags are used)
4. Read, write and operate on two pixels simultaneously
   (source and destination [left, top] are both on even or odd coordinates)
5. Read two pixels simultaneously, operate and write pixels separately to destination
   (source [left, top] is on even coordinates, destination [left, top] is on odd coordinates)
6. Read, write and operate on one pixel at a time
   (source [left, top] is on odd coordinates, destination [left, top] is on even coordinates

Using the blit effects TINT, COLORIZE or MULTIPLY will significantly affect real-time performance. If possible, always pre-render your surfaces with the blit effect of choice before using the surface.

Remarks

COLOR KEYS, OPACITY, and COLOR FILL

Please refer to the documentation on CGapiSurface::Blt for more information.

BLIT EFFECTS

The blit effects in GapiDraw have been designed to be 100% compatible with the corresponding Photoshop effects. This way you can set up tint and colorization values in Photoshop, and then just copy the tint angle, colorization color and opacity values directly to your code. To set Tint in PhotoShop, load an image and press CTRL+U, or use the menu "Image", "Adjust", "Hue/Saturation". The Tint angle is listed as "Hue". In the example below a Tint angle of (-90) was used.

GapiDraw effect [Multiply] : Photoshop layer effect [Multiply]
GapiDraw effect [Screen] : Photoshop layer effect [Screen]
GapiDraw effect [Colorize] : Photoshop layer effect [Color]
GapiDraw effect [Overlay] : Photoshop layer effect [Overlay]
GapiDraw effect [Tint] : Photoshop effect [Hue/Saturation]

To adjust colorization in Photoshop, create a new layer in your image (SHIFT+CTRL+N), Select All (CTRL+A). Change the layer type to "Color Overlay" (menu "Layer", "Layer Style"), and pick a foreground color. Choose the menu "Edit", "Fill" to fill the layer with your foreground color. Try different color combinations, and then use this RGB value as a colorization color for GapiDraw. In the example below a colorization value of RGB(39, 93, 0) was used.

SOURCE	TINT	MULTIPLY	SCREEN	COLORIZE	OVERLAY

CGapiSurface::GetPixel

This method returns the color value of a single pixel on the surface.

Parameters

x

x-coordinate for the pixel on the surface.

y

y-coordinate for the pixel on the surface.

pColor

Address of a COLORREF that will be filled with the pixel color.

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

CGapiSurface::SetPixel

This method sets the color value of a single pixel on the surface.

Parameters

x

x-coordinate for the pixel on the surface.

y

y-coordinate for the pixel on the surface.

dwColor

The color value that will be used to set the color of the pixel.

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

CGapiSurface::SetPixels

This method sets the color value of several pixels on the surface, using an ARRAY or LIST of pixels.

Parameters

pHead

Pointer to the first element in a linked list of GDPIXELNODE elements. Link the elements together using the pointer in pHead->pNext. Set pHead->pNext to NULL for the last element in the list.

pFirst

Pointer to the first GDPIXEL element in an array of pixels. You may subclass GDPIXEL to add custom data, just pass the correct size of your structure as dwElementSize.

dwElementSize

The size of each element in the array. Set this to "sizeof(GDPIXEL)" if you use pixels, or the size of your own data element if you are subclassing GDPIXEL.

dwElementCount

The number of elements in your array (the number of pixels to be drawn on the surface).

dwFlags

The following table shows the possible flags.

Type	Description
GDSETPIXELS_FIXEDPOINT	Use GDSETPIXELS_FIXEDPOINT if your pixels are stored using 16:16 fixed point coordinates.

 

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

Remarks

For performance reasons, you might want to consider disabling coordinate verification for the surface using the flag GDSURFACE_NOCOORDCHECK when creating the surface. Internally two separate paths are used, where the slowest one verifies the coordinate of each pixel before drawing it to the surface.

Please note that SetPixels is the only function that does not work with clipping rectangles due to performance aspects. If you need clipping on pixels it is recommended that you use SetPixel() instead.

CGapiSurface::DrawLine

This method draws a line on the surface.

Parameters

x1

x-coordinate for the start point on the surface. Can be negative if clipping is enabled.

y1

y-coordinate for the start point on the surface. Can be negative if clipping is enabled.

x2

x-coordinate for the end point on the surface. Can be negative if clipping is enabled.

y2

y-coordinate for the end point on the surface. Can be negative if clipping is enabled.

dwColor

The color value that will be used to draw the line.

dwFlags

The following table shows the possible flags.

Type	Description
GDDRAWLINE_OPACITY	Uses the opacity value in pGDLineFx->dwOpacity to perform an alpha blend. Allowed range is from 0 (transparent) to 255 (opaque). If the opacity is set to 128, an optimized blending mode will be used.
GDDRAWLINE_ANTIALIAS	Uses a fast fixed point WU algorithm to draw the line with antialias.

pGDLineFx

Pointer to a GDLINEFX structure.

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

Performance

If (x1 == x2) or (y1 == y2) an optimized internal line drawing method will be used.

CGapiSurface::DrawRect

This method draws a hollow rectangle on the surface.

Parameters

pRect

Pointer to source rectangle. This parameter specifies a rectangular region that will be used to draw the rectangle on the surface. If a null pointer is specified, the effective rectangle area is the entire surface.

dwColor

The color value that will be used to draw the rectangle.

dwFlags

The following table shows the possible flags.

Type	Description
GDDRAWLINE_OPACITY	Uses the opacity value in pGDLineFx->dwOpacity to perform an alpha blend. Allowed range is from 0 (transparent) to 255 (opaque). If the opacity is set to 128, an optimized blending mode will be used.

pGDLineFx

Pointer to a GDLINEFX structure.

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

CGapiSurface::FillRect

This method draws a solid rectangle on the surface. [HW Accelerated]

Parameters

pRect

Pointer to source rectangle. This parameter specifies a rectangular region that will be used to fill the rectangle on the surface. If a null pointer is specified, the effective rectangle area is the entire surface.

dwColor

The color value that will be used to fill the rectangle.

dwFlags

The following table shows the possible flags.

Type	Description
<No Flags>	A fast color fill. [HW Accelerated]
GDFILLRECT_OPACITY	Uses the opacity value in pGDFillRectFx->dwOpacity to perform an alpha blend. Allowed range is from 0 (transparent) to 255 (opaque). If the opacity is set to 128, an optimized blending mode will be used.

pGDFillRectFx

Pointer to a GDFILLRECTFX structure.

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

Performance

CGapiSurface::FillRect always operates on two pixels simultaneously using 32-bit data writes. Loop unrolling is done in steps of 2, 4, 8, and 16 depending on row width and alignment. For best performance, try to keep the width of the rectangle as a power of two (2, 4, 8, 16, 32, ...).

CGapiSurface::GradientRect

This method draws a filled gradient rectangle on the surface.

Parameters

pRect

Pointer to source rectangle. This parameter specifies a rectangular region that will be used to draw the rectangle on the surface. If a null pointer is specified, the effective rectangle area is the entire surface. The height or width of the final clipped pRect must be exactly the same as the number of pixels in pGradient, depending on if the gradient is horizontal or vertical.

pGradient

Pointer to an initialized CGapiGradient object. The gradient is precalculated for performance reasons.

dwFlags

The following table shows the possible flags.

Type	Description
<No Flags>	GDGRADIENTRECT_TOP_TO_BOTTOM will be used.
GDGRADIENTRECT_OPACITY	Uses the opacity value in pGDGradientRectFx->dwOpacity to perform an alpha blend. Allowed range is from 0 (transparent) to 255 (opaque). If the opacity is set to 128, an optimized blending mode will be used.
GDGRADIENTRECT_TOP_TO_BOTTOM	First color = top, last color = bottom. Default mode.
GDGRADIENTRECT_BOTTOM_TO_TOP	First color = bottom, last color = top
GDGRADIENTRECT_LEFT_TO_RIGHT	First color = left, last color = right
GDGRADIENTRECT_RIGHT_TO_LEFT	First color = right, last color = left

pGDGradientRectFx

Pointer to a GDGRADIENTRECTFX structure.

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

Performance

GradientRect will always do a 1:1 gradient for performance reasons. It is therefore a requirement that the number of pixels specified in pGradient is exactly the same as the width or height of the clipped pRect, depending on if the gradient is drawn horizontal or vertical.

CGapiSurface::DrawText

This method draws text on the surface. [HW Accelerated]

Parameters

x

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

y

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

pString

Pointer to a text string that should be drawn on the surface.

pFont

Pointer to a bitmap font object that should be used as font.

dwTextFlags

The following table shows the possible flags.

Type	Description
<No Flags>	Draw left aligned text, x = text left. [HW Accelerated]
GDDRAWTEXT_LEFT	Draw left aligned text, x = text left. [HW Accelerated]
GDDRAWTEXT_CENTER	Draw centered text, x = text center. [HW Accelerated]
GDDRAWTEXT_RIGHT	Draw right-aligned text, x = text right. [HW Accelerated]

pGDDrawTextFx

Pointer to a GDDRAWTEXTFX structure. Can be NULL.

dwBltFastFlags

Flags sent to CGapiSurface::BltFast() when drawing the font. Please see the documentation for CGapiSurface::BltFast() for details. Can be NULL.

pGDBltFastFx

Pointer to a GDBLTFASTFX structure sent to CGapiSurface::BltFast() when drawing the font. Can be NULL.

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

Remarks

The flags sent to BltFast() when drawing the font characters are (dwBltFastFlags | GDBLTFAST_KEYSRC), so there is no need to explicitly specify the color key flag.

SYSTEM FONT

If you do not want to create your own font, GapiDraw has a default font built-in that is stored in system memory. You can access it using the functions CGapiDisplay::GetSystemFont and CGapiDisplay::GetSystemFontBorder. The built in system font is very suitable for prototypes and status messages. The system font is of variable width (1-6 pixels + 1 pixel white space), and fixed height (7 pixels with border, 5 pixels without). The system font is pre-rendered with a white color, and can be re-rendered with a different color using CGapiDisplay::RenderSystemFont.

BITMAP FONT

Bitmapped fonts provides the most flexible way to do text output in GapiDraw. Create a new CGapiBitmapFont object, load a font image to the CGapiBitmapFont object using CGapiBitmapFont::CreateSurface, initialize the font with CGapiBitmapFont::CreateFont, and finally pass a pointer of your font to CGapiSurface::DrawText.

For a detailed description on how bitmap fonts are created and used, please see the documentation for CGapiBitmapFont.

CGapiSurface::Intersect

This method performs a pixel-by-pixel scan of two color keyed surfaces to see if they intersect.

Parameters

x1, y1

The top left starting position for the local surface. The value does not have to be a valid surface coordinate and can be negative (signed).

pSrcRect

Pointer to a rectangle defining the size of the area to check. This parameter specifies a rectangular region of the first surface. If a null pointer is specified, the effective rectangle is the entire surface.

pDestSurface

Pointer to the second surface for intersection test.

x2, y2

The top left starting position for the second surface. The value does not have to be a valid surface coordinate and can be negative (signed).

pDestRect

Pointer to a rectangle defining the size of the area to check. This parameter specifies a rectangular region of the second surface. If a null pointer is specified, the effective rectangle is the entire surface.

pIntersection

Pointer to a POINT structure that will receive the coordinate where the intersection occured. If the surfaces did not intersect, the x and y coordinates of pIntersection will both be set to -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

Performance

CGapiSurface::Intersect will always performs a quick bounding box collision test before performing the delta area pixel-by-pixel scan. If the surfaces do not overlap the function will return immediately. The delta area pixel-by-pixel scan will only check for collision in those areas of the surfaces that overlap. The scanning of pixels is done in a cache-optimized way, meaning that the delta area will be searched in the native alignment of the display.

Remarks

Please note that Intersect only works with key sourced surfaces. If you call CGapiSurface::Intersect with a surface to which you have not set a color key value, the default color key of RGB(0, 0, 0) will be used. For an example of how to use Intersect, please see the sample project Collision Mask.