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.


Note:
  • 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:
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

Safety:
Interrupt handler No
Signal handler No
Thread Yes

See also:

gf_dev_detach()