gf_dev_attach()

Connect to a graphics device

Synopsis:

#include <gf/gf.h>

int gf_dev_attach( gf_dev_t* pdev,
                   const char* name,
                   gf_dev_info_t* info );

Arguments:

pdev

Address of a gf_dev_t where the function stores a handle for the graphics device.

name

The name of the device to attach. This could be a string matching an entry in /dev/io-display, or it could be the manifest GF_DEVICE_INDEX(n) to specify the nth device in the /dev/io-display directory, where n can be from 0 to 63. Normally you would simply specify GF_DEVICE_INDEX(0) to connect to the first device found.

info

A gf_dev_info_t structure filled in by the function with information about the graphics device you want to attach to (see below). If you don't require this information, you can pass this argument as NULL.

Library:

gf

Description:

This function initializes and connects to a graphics device. It provides you with a handle to facilitate subsequent communication with the display hardware in a manner that promotes thread safety. Hardware parameters are configured by a separate configuration file and maintained by a separate server, io-display.

---

The display server, io-display, must be running before you call this function. You can connect to all available graphics devices on the display hardware by calling this function for device GF_DEVICE_INDEX(n), starting at n=0, and incrementing n until the call returns GF_ERR_DEVICE.

---

The info argument contains information about the attached device:

typedef struct {
    unsigned ndisplays;
    unsigned flags;
    const char *description;
    unsigned vendor_id;
    unsigned device_id;
    unsigned index;    
} gf_dev_info_t;

It contains at least the following members:

ndisplays

The number of displays the device supports, which is never less than 1.

flags

Device capability flags. Valid flags are:

• GF_DEV_FLUSHRECT_DRVR — If the bit is set high, the device driver uses a flushrect callout for modifying the framebuffer before presenting it to the display.

description

A pointer to a string that describes the graphics driver, in the format of “ driver_name - driver_description”.

vendor_id

Vendor ID.

device_id

Device ID.

index

The index of the device.

Returns:

GF_ERR_OK

Success.

GF_ERR_MEM

Failure to allocate memory for data structures.

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_DEVICE

Could not find the requested device. Check the /dev/io-display directory to ensure the requested device is mounted.

GF_ERR_SHMEM

Could not open or map in the required shared memory; check errno.

GF_ERR_DLL

Error accessing the driver DLL or entrypoints. Check errno and/or try restarting the application with the DL_DEBUG environment variable set to 1.

GF_ERR_THREAD

Error registering thread. Check errno.

Examples:

    gf_dev_t gdev;
    gf_dev_info_t gdev_info;

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

Classification:

QNX Graphics Framework

See also:

gf_dev_detach()