gf_surface_create_layer()

Create a surface that a layer can target

Synopsis:

#include <gf/gf.h>

int gf_surface_create_layer( gf_surface_t *psurface,
                             gf_layer_t *layer,
                             int nlayers,
                             int surface_index,
                             int w,
                             int h,
                             gf_format_t format,
                             const gf_palette_t *palette,
                             uint32_t flags );

Arguments:

psurface

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

layer

An array of handles to the layers that you would like to be able to safely target the surface.

nlayers

The number of handles in the layer array.

surface_index

The surface index, which used only in the case of planar layer formats (for example YUV) that require a surface for each plane. For nonplanar surfaces (the usual case) you should always pass 0 for this parameter.

w, h

The width and height of the surface, in pixels.

format

The gf_format_t display format of the surface. If you're 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. You can pass NULL if the surface format isn't palette-based (GF_LAYER_FORMAT_PAL8).

flags

Flags affecting the surface allocation. See gf_surface_create().

---

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 that can be targetted by the specified layer. You must use this function if you plan on binding the surface directly to one or more layers via gf_layer_set_surfaces(). It provides additional hardware checking to verify that the layer can target the surface. If the surface is going to be used only as a rendering “scratchpad” for offscreen rendering, you can use gf_surface_create() instead.

---

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_IODISPLAY

Error communicating with io-display. Check to ensure io-display is still running. The sloginfo utility may provide more information.

Classification:

QNX Graphics Framework

See also:

gf_palette_t, gf_layer_set_surfaces(), gf_surface_attach(), gf_surface_create(), gf_surface_free()