Create a new surface


#include <gf/gf.h>

int gf_surface_create( gf_surface_t* psurface,
                       gf_dev_t gdev,
                       int w,
                       int h,
                       gf_format_t format,
                       const gf_palette_t* palette,
                       unsigned flags );


An address where the function can store a handle to the surface.
The handle to the graphical device (acquired by gf_dev_attach()) that will manage the surface.
w, h
The width and height of the surface, in pixels.
The gf_format_t display format of the surface. If you are using a packed type, you should pass the non-endian-specific variant to make your application more portable.
A pointer to a gf_palette_t structure, which represents the surface palette. Pass NULL if the surface format isn't palette-based (GF_FORMAT_PAL8).
Flags for the surface's properties. These can be:

Caution: Formats and flags are supported on a per-graphics card basis. If a specified format or flag is not supported, it will return an error.

The GF_SURFACE_CREATE_CPU_LINEAR_ACCESSIBLE and GF_SURFACE_CREATE_CPU_FAST_ACCESS flags are not compatible with the Carmine ( graphics driver.




This function creates a new surface. A surface provides an area of memory that can be rendered to via draw contexts. Use this function for “offscreen” buffers that will not be targeted by any layers (that is, you will only render to the surface, then blit the results somewhere else). If you plan to directly target the surface with any layers, you must use gf_surface_create_layer() instead.

When the graphics driver (specified by gdev) returns NULL, the behavior of the function depends on the value of the flags that are returned by the driver's get_alloc_info/get_alloc_layer_info methods, and whether or not the GF_SURFACE_CREATE_SHAREABLE is set.

If the GF_SURFACE_CREATE_SHAREABLE flag is not set, the surface will be allocated by Advanced Graphics, but will return an invalid surface id (SID). If you need a valid SID you must pass GF_SURFACE_CREATE_SHAREABLE, which will cause a shared memory object to be created. Other processes can then open this shared memory object.

WARNING: Threads should not call this function between calls to gf_draw_begin() and gf_draw_end(), or a deadlock will occur.


Memory allocation failure.
Unable to satisfy the criteria; verify that the pixel format meets the requirements set out by the flags for the given hardware.
Unsupported flag.


QNX Graphics Framework

Interrupt handler No
Signal handler No
Thread Yes

See also:

gf_format_t, gf_palette_t, gf_surface_attach(), gf_surface_create_layer(), gf_surface_free()