GPE::AllocSurface

This method is called 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 AllocSurface function.

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 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

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 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 surfaceFlags member 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.