gf_display_attach()

Attach to a display on a graphics device

Synopsis:

#include <gf/gf.h>

int gf_display_attach( gf_display_t * pdisplay,
                       gf_dev_t gfx,
                       unsigned display_index,
                       gf_display_info_t *info );

Arguments:

pdisplay: A pointer to a gf_display_t where the function stores a handle for a graphics display.
gfx: A handle for the graphics device, acquired by gf_dev_attach().
display_index: The index of the desired display. A graphics device can have one or more displays, with the index starting at 0.
info: A pointer to a gf_display_info_t structure that the function fills in with information about the display (see below). Set this to NULL if you don't need to obtain this information.

This function attaches to a display on a graphics device. This function provides you with a handle that lets you use the display while maintaining thread safety. Actual parameters for the individual display (or displays) on a graphics device are configured via a separate configuration file and maintained by a separate server, io-display.

A device typically drives one display, although some hardware is fitted with multiple displays, each of which you can attach to via this function. With a separate handle for each display, you can address and manipulate each on an individual basis.

`gf_display_info_t`

The info argument contains information about the attached display:

typedef struct
{
    unsigned nlayers;
    unsigned main_layer_index;
    uint16_t xres;
    uint16_t yres;
    gf_format_t format;
    int refresh;
} gf_display_info_t;

It contains at least the following members:

nlayers

The number of layers the display supports. There's always at least one layer present (the main display layer), although some hardware has support for multiple layers per display.

main_layer_index

The index of the main display layer. Every display has the concept of a main display layer, which encapsulates the frame buffer for that display. Generally, control of the main display layer is limited in comparison to other layers. This zero-based index lets you identify the main display layer.

xres, yres

The horizontal and vertical resolution, in pixels.

format

The format of the display. See gf_format_t for a list of valid formats.

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

refresh

The current refresh rate of the display (in Hz).

Returns:

GF_ERR_OK: Success.
GF_ERR_MEM: Memory allocation failure.
GF_ERR_IODISPLAY: Could not access the /dev/io-display directory. Check to ensure that io-display is running. The sloginfo utility may provide more information.
GF_ERR_PARM: The display index is out of bounds.
GF_ERR_CFG: Badly configured display; check the io-display configuration file.

Examples:

Attach to a device, and then use the device information structure gf_dev_info_t to attach to the device's displays:



    gf_dev_t            gdev;
    gf_dev_info_t       gdev_info;
    gf_display_t        display;
    gf_display_info_t   display_info;

    int i;

    if (gf_dev_attach(&gdev,GF_DEVICE_INDEX(0),&gdev_info) != GF_ERR_OK) {
        printf("gf_dev_attach() failed\n");
        return (-1);
    }

    printf("Number of displays: %d\n",gdev_info.ndisplays);

    for (i = gdev_info.ndisplays;i;) {
        printf("Display %d: ",i--);
        if (gf_display_attach(&display,gdev,i,&display_info) == GF_ERR_OK) {
            printf("%dX%d, refresh = %dHz\n",display_info.xres,display_info.yres,display_info.refresh);
            printf("Number of layers: %d\n",display_info.nlayers);
        } else {
            printf("gf_display_attach() failed\n");
        }
    }

Classification:

QNX Graphics Framework

Safety:
Interrupt handler	No
Signal handler	No
Thread	Yes