DDGPE::AllocSurface (Windows Embedded CE 6.0)

1/6/2010

This method is an extension of its counterpart, the GPE::AllocSurface method. With the addition of the pixelFormat parameter or the pddgpeAllocSurfaceData, your driver can allocate many different types of surfaces, instead of a limited number of GPE surface types.

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
  The desired width of the surface.

• height
  The desired height of the surface.

• format
  The desired format of the surface.

• pixelFormat
  The desired pixel format of the surface.

• surfaceFlags
  GPE surface flags for the 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 should be 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

Your driver should override the first DDGPE AllocSurface function that follows to perform the necessary allocation. Otherwise, the function merely wraps to the standard GPE AllocSurface that you must define in your driver. In this case, the pixelFormat information is ignored. The default implementation of the second DDGPE AllocSurface routine that follows calls the first one, ignoring the information you might have in DDGPEStandardHeader. Your driver must override it if you want to take advantage of DDGPEStandardHeader.

Requirements

See Also

Reference

GPE::AllocSurface
DDGPEAllocSurfaceData

Concepts

DDGPE Class
DDGPE Class Definition