[Previous] [Contents] [Index] [Next]

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.

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

Safety:
Interrupt handler No
Signal handler No
Thread Yes

See also:

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

[Previous] [Contents] [Index] [Next]