Documentation
[SDK Documentation] [CGapiRGBASurface]

 

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

CGapiRGBASurface

Overview

CGapiRGBASurface is a memory area with embedded alpha information. You can use CGapiRGBASurface in operations such as CGapiSurface::AlphaBlt for easy to use alpha blends.

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

 

CGapiRGBASurface::CreateSurface

This method allocates memory for the surface and prepares it for graphic operations.

HRESULT CreateSurface(DWORD dwFlags, DWORD dwWidth, DWORD dwHeight);
HRESULT CreateSurface(DWORD dwFlags, const TCHAR* pImageFile);
HRESULT CreateSurface(DWORD dwFlags, BYTE* pImageFileMem, DWORD dwImageFileSize);
HRESULT CreateSurface(DWORD dwFlags, HINSTANCE hInstance, DWORD dwResourceID,
const TCHAR* pResourceType = NULL);
HRESULT CreateSurface(CGapiRGBASurface* pSrcSurface);
HRESULT CreateSurface(DWORD dwFlags, CGapiVFS* pVFS, const TCHAR* pImageFile);
HRESULT CreateSurface(DWORD dwFlags, CGapiFileStream* pGapiFileStream);
Parameters
dwFlags
Creation options. The following table shows the possible types.

Type

Description

GDRGBASURFACE_CLEAR

Clears the surface memory area after creation.

GDRGBASURFACE_12BIT

Store the surface as 444A WORD aligned.

GDRGBASURFACE_32BIT

Store the surface as 555A or 565A DWORD aligned.

GDRGBASURFACE_SYSTEMMEMORY

Store the surface in system memory - default.
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.
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. If you use MFC, you can use AfxGetInstanceHandle() to get a valid HINSTANCE.
dwResourceID
The ID of a bitmap resource to be loaded into the surface.
pResourceType
The name of the resource category where your image is located. If your image is BMP you can omit this parameter.
pSrcSurface
Surface to be used as a source image when creating a copy. The size and contents of the current surface will be erased and adjusted to fit the source image.
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

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))).

Remarks

Previous data stored in the surface will be deleted, even if the call to CGapiRGBASurface::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 CGapiRGBASurface::CreateSurface((DWORD)0, (DWORD)0, (DWORD)0).

The width and height of the surface will be adjusted to fit the entire image. Supported image file types are PNG images with an embedded variable alpha map. PNG images are loaded with zero-memory-overhead.

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 application path of your executable file and append the image file name (e.g. if your executable is "\Program Files\Games\MyGame\MyGame.exe" and you call CreateSurface with pImageFile set to "MyPicture.png", GapiDraw will try to load the image as "\Program Files\Games\MyGame\MyPicture.png").

CGapiRGBASurface::GetWidth

This method returns the width of the surface in pixels.

DWORD GetWidth();
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.

CGapiRGBASurface::GetHeight

This method returns the height of the surface in pixels.

DWORD GetHeight();
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.

CGapiRGBASurface::GetBuffer

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

HRESULT GetBuffer(GDBUFFERDESC* pGDBufferDesc);
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

Remarks

CGapiRGBASurface::GetBuffer is used to directly access the internal memory buffer of a surface. You can use CGapiRGBASurface::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.

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

RGBA Surfaces in GapiDraw can be of 444A, 555A or 565A 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.

CGapiRGBASurface::ReleaseBuffer

Releases the previously locked internal memory buffer used by CGapiRGBASurface.

HRESULT ReleaseBuffer();
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