gf_layer_query()

Query a layer's capabilities

Synopsis:

#include <gf/gf.h>

int gf_layer_query( gf_layer_t layer,
                    int format_index,
                    gf_layer_info_t *info );

Arguments:

layer

The layer you want to query.

format_index

The index of the format you want to query. Formats are indexed numerically, starting at 0.

info

The address of a gf_layer_info_t structure where the function stores information about the layer (see below). Don't pass NULL for this parameter.

Library:

gf

Description:

This function queries a layer for a given format index, and fills in the info argument with the result. Normally, you'd perform a loop, querying each format index starting at 0 until you either found the format you're looking for, or the function returns something other than GF_ERR_OK.

---

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

---

The info member is a pointer to a gf_layer_info_t structure. It contains at least these members:

gf_format_t format

The layer's pixel format. See gf_format_t for a list of valid formats.

---

If the the format filled in by gf_layer_query() is packed, it will not be endian-specific.

---

unsigned caps

The layer's capabilities. Valid bits include:

GF_LAYER_CAP_FILTER

The layer can apply a filtering technique to the image as it's being displayed in order to produce a smoother image. You can use filtering techniques to reduce artifacts when scaling images.

GF_LAYER_CAP_SCALE_REPLICATE

A simple pixel replication scaling technique is available for a source image that's scaled before it's displayed in the destination viewport.

GF_LAYER_CAP_PAN_SOURCE

You can adjust the source viewport position by calling gf_layer_set_src_viewport().

GF_LAYER_CAP_SIZE_DEST

The size of destination viewport can be different from the size of source viewport.

GF_LAYER_CAP_PAN_DEST

You can adjust the position of destination viewport by calling gf_layer_set_dst_viewport().

GF_LAYER_CAP_EDGE_CLAMP

If the image being displayed isn't large enough to fill the destination viewport, the unfilled right and bottom portions of the viewport can be filled. The last pixel that was displayed can be replicated to the edge of the viewport.

GF_LAYER_CAP_EDGE_WRAP

If the image being displayed isn't large enough to fill the destination viewport, the unfilled right and bottom portions of the viewport can be filled. The right and bottom portions can be wrapped around to the top left portions of the image.

GF_LAYER_CAP_DISABLE

You can disable the layer via gf_layer_disable().

GF_LAYER_CAP_SET_BRIGHTNESS

You can adjust brightness via gf_layer_set_brightness().

GF_LAYER_CAP_SET_CONTRAST

You can adjust contrast via gf_layer_set_contrast().

GF_LAYER_CAP_SET_SATURATION

You can adjust saturation via gf_layer_set_saturation().

GF_LAYER_CAP_ALPHA_WITH_CHROMA

The layer can apply alpha and chroma operations simultaneously.

GF_LAYER_CAP_PAN_DEST_NEGATIVE

The layer destination viewport can be panned to negative coordinates.

GF_LAYER_CAP_MAIN_DISPLAY

This layer is the main display layer.

unsigned alpha_valid_flags

Flags that may be specified in the mode parameter of the gf_alpha_t argument to gf_layer_set_blending().

unsigned alpha_combinations

The capabilities of the alpha-blending hardware for this layer. Valid bits include:

GF_ALPHA_CAP_SPP_WITH_GLOBAL

Source per-pixel blending can be used in conjunction with a global alpha multiplier.

GF_ALPHA_CAP_GLOBAL_WITH_DPP

Destination per-pixel blending can be used in conjunction with a global alpha multiplier.

GF_ALPHA_CAP_SPP_WITH_DPP

Source per-pixel blending can be used in conjunction with destination per-pixel blending.

GF_ALPHA_CAP_GLOBAL_WITH_GLOBAL

Source global alpha multiplier can be used in conjunction with a destination global alpha multiplier.

unsigned chromakey_caps

The capabilites of the chroma-key hardware for this layer. Valid bits include:

GF_LAYER_CHROMAKEY_CAP_SRC_SINGLE

The layer supports chroma-keying based on an exact match between the source pixel value and a single key color.

GF_LAYER_CHROMAKEY_CAP_SRC_RANGE

The layer supports chroma-keying based on a match between the source pixel value and a key color range.

GF_LAYER_CHROMAKEY_CAP_DST_SINGLE

The layer supports chroma-keying based on an exact match between the destination pixel value and a single key color.

GF_LAYER_CHROMAKEY_CAP_DST_RANGE

The layer supports chroma-keying based on a match between the destination pixel value and a key color range.

GF_LAYER_CHROMAKEY_CAP_SHOWTHROUGH

The layer can be configured so that when a chroma-key comparison is made, and the colors match, the pixel displayed comes from the behind the layer. When the colors don't match, the pixel that appears comes from the layer displayed.

GF_LAYER_CHROMAKEY_CAP_BLOCK

The layer can be configured so that when a chroma-key comparison is made, and the colors match, the pixel displayed comes from the layer displayed. When the colors don't match, the pixel that appears comes from behind the layer.

_uint64 order_caps

The z-order slots that this layer can occupy. For each slot, a corresponding bit in order_caps will be either on or off to reflect whether or not this layer can be ordered to that slot. Slot 0 (furthest from the user) is represented by the least significant bit 0, slot 1 by bit 1, and so on.

int src_max_height

The maximum height (in pixels) of the source.

int src_max_width

The maximum width (in pixels) of the source.

int src_max_viewport_height

The maximum height (in pixels) of the source viewport.

int src_max_viewport_width

The maximum width (in pixels) of the source viewport.

int dst_max_height

The maximum height (in pixels) of the destination.

int dst_max_width

The maximum width (in pixels) of the destination.

int dst_min_height

The maximum height (in pixels) of the destination viewport.

int dst_min_width

The maximum width (in pixels) of the destination viewport.

int max_scaleup_x, int max_scaleup_y

The maximum scaling factor for image upscaling in the horizontal and vertical directions. A value of 1 means upscaling can't be performed. A value < 1 is invalid. A value > 1 for max_scaleup_x means that the destination viewport width can be up to max_scaleup_x times the source viewport width. Similarly, a value > 1 for max_scaleup_y means that the destination viewport height can be up to max_scaleup_y times the source viewport height.

int max_scaledown_x, int max_scaledown_y

The maximum scaling factor for image downscaling in the horizontal and vertical directions. A value of 1 means downscaling can't be performed. A value < 1 is invalid. A value > 1 for max_scaledown_x means that the destination viewport width can be up to max_scaledown_x times the source viewport width. Similarly, A value > 1 for max_scaledown_y means that the source viewport height can be up to max_scaledown_y times the destination viewport height.

uint32_t output_mask

On a display with multiple outputs, this bitmask specifies which outputs this layer may be displayed on.

uint32_t vcap_mask

A bitmask indicating which capture units may be bound to this layer.

Returns:

GF_ERR_OK

Success.

GF_ERR_IODISPLAY

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

GF_ERR_PARM

An invalid layer parameter was passed, or an internal consistency error was encountered such as an invalid display number.

GF_ERR_NOSUPPORT

A format index was passed that is out of range for the given layer.

Examples:

See “Using layers” in the Using Layers, Surfaces, and Contexts chapter.

Classification:

QNX Graphics Framework

See also:

gf_format_t, gf_layer_attach(), gf_layer_detach(), gf_layer_disable(), gf_layer_enable()