DDGPE::AllocSurface (Compact 2013)

3/26/2014

This method is an extension of its counterpart, the GPE::AllocSurface method.

Syntax

// Surface memory allocation
virtual SCODE AllocSurface(
  DDGPESurf** ppSurf,
  int width,
  int height,
  EGPEFormat format,
  int surfaceFlags
)=0;
virtual SCODE AllocSurface(
  DDGPESurf** ppSurf,
  int width,
  int height,
  EGPEFormat format,
  EDDGPEPixelFormat pixelFormat,
  int surfaceFlags
);
virtual SCODE AllocSurface(
  DDGPESurf** ppSurf,
  DDGPEAllocSurfaceData* pddgpeAllocSurfaceData 
);

Parameters

• ppSurf
  Pointer to a new DDGPESurf object.

• width
  Width of the surface (desired).

• height
  Height of the surface (desired).

• format
  Format of the surface (desired).

• pixelFormat
  Format of pixels on the surface (desired).

• surfaceFlags
  Flags for the GPE surface.

  Flag	Description
  GPE_BACK_BUFFER	Indicates a surface will be used as a back buffer.
  GPE_REQUIRE_VIDEO_MEMORY	Surface memory must be allocated in video memory.
  GPE_PREFER_VIDEO_MEMORY	Surface memory is allocated in video memory, if possible, but can be allocated in system memory, if necessary.

  If no flags are set, for example, if surfaceFlags is set to zero (0), the surface is allocated in system memory.

• pddgpeAllocSurfaceData
  See DDGPEAllocSurfaceData.

Return Value

The return value is S_OK, if the function is successful. Otherwise, an error code is returned.

Remarks

By using pixelFormat or pddgpeAllocSurfaceData, your driver can allocate many different types of surfaces, instead of a limited number of GPE surface types.

Your driver should override the first DDGPE::AllocSurface method that follows to perform the necessary allocation. Otherwise, the method only wraps to the standard GPE::AllocSurface that you must define in your driver. In this case, the pixelFormat information is not used. The default implementation of the second DDGPE::AllocSurface routine that follows calls the first one, and doesn't use the information you might have in DDGPEStandardHeader. Your driver must override it if you want to use DDGPEStandardHeader.

To use this method, your display driver code must enforce the data alignment requirements of the microprocessor for your device. Additionally, the allocated surface must be DWORD (32 bit) aligned, even for a source or destination surface with a pixel depth of 8 or 16 bits per pixel (bpp). Otherwise, the method may throw an exception or cause a downstream exception.

Requirements

Header	ddgpe.h
Library	Ddgpe.lib

See Also

Reference

DDGPE Class
GPE::AllocSurface
DDGPEAllocSurfaceData
DDGPE Class Definition