gf_surface_create()

Create a new surface

Synopsis:

#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 );

Arguments:

psurface

An address where the function can store a handle to the surface.

gdev

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.

format

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.

palette

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

Flags for the surface's properties. These can be:

• GF_SURFACE_CREATE_2D_ACCESSIBLE — the surface will be used by the 2D API (that is, rendered to and blitted from).
• GF_SURFACE_CREATE_3D_ACCESSIBLE — the surface will be used by the 3D API (OpenGL ES) or OpenVG API.
• GF_SURFACE_CREATE_ALPHA_MAP — the surface must be usable as the alpha map source for 2D rendering.
• GF_SURFACE_CREATE_CPU_FAST_ACCESS — the surface is allocated so that CPU access speed is optimized. Satisfying this request typically precludes accelerated hardware rendering. The default is to allocate a surface optimize for rendering performance; that is, try to allocate such that hardware accelerated rendering is possible.
• GF_SURFACE_CREATE_CPU_LINEAR_ACCESSIBLE — the surface memory is linearly accessible. Note that this request may preclude hardware accelerated rendering if, for example, the hardware uses tiled video memory. In general, though, this is not the case.
• GF_SURFACE_CREATE_PHYS_CONTIG — the surface memory must be physically contiguous. This is not a usual requirement; however it may be needed in some cases. Some video capture hardware, for instance, requires that the memory be physically contiguous.
• GF_SURFACE_CREATE_PAGE_ALIGNED — the allocated surface must be aligned on a page boundary. You may require this if you are doing your own advanced manipulation of allocated memory, or if you have some hardware with alignment restrictions. Otherwise this is not usually a requirement.
• GF_SURFACE_CREATE_SHAREABLE — Allows server side surfaces to be allocated. Creates a shared memory object, which allows gf_surface_create() to return a valid SID.

---

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 (devg-carmine.so) graphics driver.

---

Library:

gf

Description:

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.

---

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

---

Returns:

GF_ERR_OK

Success.

GF_ERR_MEM

Memory allocation failure.

GF_ERR_PARM

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

GF_ERR_NOSUPPORT

Unsupported flag.

Classification:

QNX Graphics Framework

See also:

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