GPE::AllocSurface (Windows Embedded CE 6.0)

1/6/2010

This method executes when the driver must allocate storage for surface pixels.

Syntax

SCODE GPE::AllocSurface( 
  GPESurf** ppSurf, 
  int width, 
  int height, 
  EGPEFormat format, 
  int surfaceFlags 
);

Parameters

• ppSurf
  [out] Pointer to the memory allocated by the GPE::AllocSurface method.

• width
  [in] Width, in pixels, of the surface to allocate.

• height
  [in] Height, in pixels, of the surface to allocate.

• format
  [in] Format of the surface.

• surfaceFlags
  [in] One of the flags GPE_REQUIRE_VIDEO_MEMORY or GPE_PREFER_VIDEO_MEMORY, which specify where to allocate the memory

Return Value

If GPE_REQUIRE_VIDEO_MEMORY is set in the surfaceFlags parameter, the call returns one of two error values: if the available video memory is insufficient, the call returns E_NOT_ENOUGH_MEMORY, whereas if the allocation is inappropriate for video memory, such as an incorrect pixel format, the call returns E_INVALID_PARAMETER.

Remarks

Display drivers allocate surfaces at initialization time for the video frame buffer, and possibly the cursor, when the graphics device interface (GDI) calls the DrvCreateDeviceBitmap function. GPE::AllocSurface, a required method, implements surface allocation within the driver.

For video memory allocation, the driver should implement a class, derived from GPESurf that contains extra information, such as a pointer to the allocator used when freeing the memory. Refer to the Node2D class for information about a supplied memory allocator that you can use for rectangular allocation requirements.

The following code example shows the system memory allocation for this method.

*ppSurf = new GPESurf( width, height, format );
if(* ppSurf )
  {
  //check that the bitmap bits were allocated
  if (NULL == ((*ppSurf)->Buffer()))
    {
    delete *ppSurf;
    }
    else
    {
    return S_OK;
    }
  }
return E_NOT_ENOUGH_MEMORY;

The surfaceFlags parameter can contain GPE_REQUIRE_VIDEO_MEMORY or GPE_PREFER_VIDEO_MEMORY, although neither is required. For GPE_PREFER_VIDEO_MEMORY, the driver should allocate, if possible, the surface from video memory. Otherwise, the driver should use system memory.

Requirements

See Also

Reference

Display Driver Methods

Concepts

GPESurf
Node2D

Other Resources

Display Drivers