This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

gf_display_set_layer_order()

Set the ordering of the layers for a display

Synopsis:

#include <gf/gf.h>

int gf_display_set_layer_order( gf_display_t display,
                                const unsigned order[],
                                unsigned flags );

Arguments:

display

The handle for the display to set the layer order for. This handle is returned by gf_display_attach().

order

An array of type unsigned specifying the new order of the layers, with the first element in the array specifying the layer furthest to the back. Therefore, there must be the correct number of elements in the array, which is the number of available layers for that display. If there aren't enough elements in the array, the results aren't defined.

flags

Flags controlling additional options. Valid flags are:

• GF_LAYER_UPDATE_NO_WAIT_VSYNC -- Perform the operation asynchronously; the default behaviour is to block until the next vertical synchronization before changing the layer order.
• GF_LAYER_UPDATE_NO_WAIT_IDLE -- Perform the operation immediately; the default behaviour is to wait for the draw hardware to finish before changing the layer order.

Library:

gf

Description:

This function sets the ordering of the layers for a display. Each display is always equipped with at least one layer (known as the main display layer), but some hardware is equipped with additional layers that can provide advanced visual effects without incurring additional CPU overhead.

---

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

---

Layers are stacked and therefore have an implicit z-order. Some hardware allows the reordering of these layers. The default ordering is numerical by layer index, with layer 0 being the furthest away from the user.

For example, to reverse the default order of the layers on a 2-layer display, you would specify an order array of { 1, 0 }. If there were six layers, and you wanted to move layer 2 to the back, you'd specify an order array of { 2, 0, 1, 3, 4, 5 }.

Returns:

GF_ERR_OK

Success.

GF_ERR_NOSUPPORT

Layer ordering is not supported on the specified display.

GF_ERR_PARM

Invalid layer order. Check to ensure there are no duplicate entries in your order array. Check the order_caps member of gf_layer_info_t (see gf_layer_query()) to ensure that all layers are being ordered to a supported slot.

GF_ERR_IODISPLAY

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

Classification:

QNX Graphics Framework

See also:

gf_display_attach(), gf_display_detach()