GPE::AllocSurface (Compact 2013)
3/26/2014
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.
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.
Example
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
Header |
gpe.h |
Library |
Gpe_lib.lib |