Microsoft Windows CE 3.0  

GPE::AllocSurface

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

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

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

Parameters

ppSurf
[OUT] Pointer to the memory allocated by the AllocSurfacefunction.
width
[IN] Width, in pixels, of the surface to allocate.
height
[IN] Height, in pixels, of the surface to allocate.
format
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 Values

If GPE_REQUIRE_VIDEO_MEMORY is set in the surfaceFlagsparameter, 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

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 Node2Dclass for information on a supplied memory allocator that can be used for rectangular allocation requirements.

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

*ppSurf = new GPESurf( width, height, format );
if( *ppSurf ) return S_OK; return E_NOT_ENOUGH_MEMORY;

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

Requirements

Runs on Versions Defined in Include Link to
Windows CE OS 1.0 and later      
Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.


 Last updated on Tuesday, July 13, 2004

© 2004 Microsoft Corporation. All rights reserved.