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:

Library:

gf

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:


Note: 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.

See also:

gf_display_attach(), gf_layer_detach(), gf_layer_disable(), gf_layer_enable(), gf_layer_query()