DDGPE::WrapSurface (Windows Embedded CE 6.0)

1/6/2010

This method creates a DDGPESurf-based object based on a pointer to an existing block of memory. The new object can optionally be associated with a DirectDraw surface.

Syntax

virtual SCODE WrapSurface(
  LPDDRAWI_DDRAWSURFACE_LCL lpDDSurface, 
  int width, 
  int height, 
  EGPEFormat format, 
  EDDGPEPixelFormat pixelFormat, 
  int stride, 
  int surfaceFlags
);
virtual SCODE WrapSurface(
  DDGPESurf** ppSurf, 
  int width, 
  int height, 
  EGPEFormat format, 
  EDDGPEPixelFormat pixelFormat, 
  unsigned char* pBits, 
  int stride
);
virtual SCODE WrapSurface(
  LPDDRAWI_DDRAWSURFACE_LCL lpDDSurface, 
  int width, 
  int height, 
  EGPEFormat format, 
  EDDGPEPixelFormat pixelFormat, 
  unsigned char* pBits, 
  int stride
);
virtual SCODE WrapSurface(
  DDGPESurf** ppSurf, 
  DDGPEAllocSurfaceData* pddgpeAllocSurfaceData
);
virtual SCODE WrapSurface(
  LPDDRAWI_DDRAWSURFACE_LCL lpDDSurface, 
  DDGPEAllocSurfaceData* pddgpeAllocSurfaceData 
);

Parameters

• ppSurf
  Pointer to a new DDGPESurf object.

• lpDDSurface
  A pointer to an existing DirectDraw surface. A new DDGPESurf object will be attached to it. Any existing DDGPESurf object attached to this surface will be replaced. The driver is responsible for managing surfaces replaced in this manner.

• width
  Width of the surface.

• height
  Height of the surface.

• format
  Format of the surface.

• pixelFormat
  Display mode's pixel format.

• pBits
  Pointer to an existing block of video or system memory that stores the surface's data.

• stride
  Stride of the surface.

• surfaceFlags
  GPE surface flags for the surface.

  Flag	Description
  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 method is successful. Otherwise, an error code is returned.

Remarks

Typically, you use this method to wrap a surface around surface memory you have created manually, either in video or system memory. If a pointer to allocated surface memory is not supplied, the WrapSurface method results in a call to AllocSurface, which is implemented by the driver. Your driver is responsible for allocating video memory for these surfaces, if possible, and for requesting that DDGPESurf allocate system memory, if necessary.

Requirements

See Also

Concepts

DDGPE Class
DDGPE Class Definition