gf_layer_attach()

Attach to a layer

Synopsis:

#include <gf/gf.h>

int gf_layer_attach( gf_layer_t * player,
                     gf_display_t display,
                     unsigned layer_index,
                     unsigned flags );

Arguments:

player

A pointer to a gf_layer_t where the function can store the handle for the layer.

display

A handle for the display you want the layer for, returned by gf_display_attach().

layer_index

The index of the layer to attach to. Layers are indexed numerically, starting at 0. A display always has at least one layer.

flags

Flags to control behavior. Can be one of:

GF_LAYER_ATTACH_NODEFAULTS — attach only; do not reset layer parameters to their initial values.
GF_LAYER_ATTACH_PASSIVE — allow the attach to proceed even if another process has already attached to the layer. Attempting to attach to an already attached layer will fail if this flag isn't set. Only one process “owns” a layer, but by attaching with this flag set, other processes may change various settings. For example, the owner may set up a video stream to display to a layer, while another process may adjust the size and position of the layer.
GF_LAYER_ATTACH_NOAUTODISABLE — allow the layer to remain enabled after the owner detaches from it (note that setting GF_LAYER_ATTACH_PASSIVE causes this flag to be ignored). By default, io-display will disable the layer when the application detaches from it, either via an explicit call to gf_layer_detach() or indirectly by terminating (normally or otherwise).

Description:

This function attaches a GF application to a layer within the specified display. This function provides you with a handle, player, which you require to manipulate the layer.

If you pass 0 for flags, some layer settings are set to their defaults:

the layer is enabled
the source viewport is set to entire surface
the destination viewport is set to entire display

If you call gf_layer_attach() for an already attached layer index, set the GF_LAYER_ATTACH_NODEFAULTS flag bit to prevent any layer settings from being reset to their defaults. If you attach to a layer that's disabled with this flag bit set, the layer remains disabled, and you'll need to explicitly enable it with gf_layer_enable().

To get information about an attached layer's capabilities, call gf_layer_query().

Returns:

GF_ERR_OK: Success.
GF_ERR_MEM: Memory-allocation failure.
GF_ERR_PARM: Layer index is out of range for the specified display.
GF_ERR_INUSE: Layer is already in use; try attaching with the GF_LAYER_ATTACH_PASSIVE flag enabled.
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

Safety:
Interrupt handler	No
Signal handler	No
Thread	Yes

Caveats:

When using the GF_LAYER_ATTACH_NOAUTODISABLE flag, none of the surfaces allocated by an application will be released on termination. If you need to release a surface, and you are using the GF_LAYER_ATTACH_NOAUTODISABLE flag, you must explicitly release it via the gf_surface_free() API call.