This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

`io-display`

The QNX Graphics Framework server

Syntax:

io-display [-fv] [-d device] [-c config_file]
           [-p priority]

Options:

-c

Specify a path to the configuration file. The default is /etc/system/config/display.conf. See below for the configuration file's format.

-d device

Load the graphics driver specified by the device. These options must match an entry in the io-display configuration file (see below).

The format of the device string is:

      vid=[0x]vendor_id,did=[0x]device_id[,deviceindex=index]

Where:

vendor_id: The vendor ID of the graphics device.
device_id: The device ID of the graphics device.
index: The index of the graphics device. If not specified, the default is 0.

For PCI devices, you can use the pci utility to display PCI information about installed graphics devices on a machine running Neutrino.

-f

Ignore requests to wait for vertical synchronization coming from the application. This is useful when measuring frame rates for benchmarking purposes.

-p priority

Set the priority of pulses to be used by device drivers, e.g. when delivering interrupt events; io-display inherits the priority of received pulses, which can cause priority inversion problems for client applications that block on io-display. The default value is 21.

-v

Be verbose.

Description:

The io-display manager provides support for direct rendering to graphics devices using the QNX Graphics Framework and OpenGL ES by loading the driver specified by the -d option.

Once io-display has started, applications can use the QNX Graphics Framework library (libgf) and OpenGL ES libraries to acquire a graphics context and render to the device.

QNX Graphics Framework applications must be privileged in order to run, since they directly access the graphics hardware when rendering. This means they either have to be run by root, or by a member of the display group. Applications that are a member of the display group can directly access the graphics hardware, without having supervisor (root) privileges.

There is one restriction however, which currently only applies to x86 systems. Some drivers for older video devices may need to perform accesses to I/O mapped registers when rendering. In this case, the thread performing the rendering will need to have I/O privilege. In order to obtain I/O privilege, the process must run as root. A process with I/O privilege on an x86 system does not have full superuser privileges, however, so the extra requirement to run as root with some graphics devices introduces minimal risk.

The `io-display` configuration file

By default, the io-display configuration file is located in /etc/system/config/display.conf, but you can put it in a different location and use the -c option.

This file specifies global options, device-specific options, and display-specific options. The file follows these conventions:

Only one option is permitted on a line.
Options are specified as name=value pairs.
The file layout is hierarchical, with each section containing zero or more options, and zero or more subsections.
Subsections are contained within curly braces ({}).

The top-level section is device, which describes a graphics device. It has these options and subsections:

noautoshutdown -- set to 1 to prevent the display from being turned off when all applications exit. If not specified, the default 0 is used.
drivername -- a string describing the devg-* driver that io-display loads for this device. The string must match the name of the driver. For example, coral matches devg-coral.so.
vid -- the vendor ID, in hexadecimal. In the case of a PCI device, this is the PCI vendor ID.
did -- the device ID, in hexadecimal. In the case of a PCI device, this is the PCI device ID.
deviceindex -- the device index.
modeopts -- a string passed directly to the driver. For example, in the case of the Coral driver, it can specify a configuration file with additional hardware-specific settings.
display -- a subsection that describes one or more displays supported by the device. This subsection as the following options:
- xres -- the horizontal resolution of the display.
- yres -- the vertical resolution of the display.
- refresh -- the refresh rate of the display, in Hz.
- pixel_format -- The pixel format of the display. Possible pixel formats are:
  - pal8 -- 8 bpp
  - argb1555 -- 15 bpp
  - rgb565 -- 16 bpp
  - rgb888 -- 24 bpp
  - argb8888 -- 32 bpp

Here is a sample file:

device {
    drivername=coral
    vid=0x10cf
    did=0x201e
    deviceindex=0
    display {
        xres=640
        yres=480
        refresh=60
        pixel_format=argb1555
    }
}
device {
    noautoshutdown=1
    drivername=coral
    vid=0x10cf
    did=0x2019
    deviceindex=0
    display {
        xres=640
        yres=480
        refresh=60
        pixel_format=argb1555
    }
}

The `io-display` server and Photon

When you want to run both GF/OpenGL ES and Photon applications, you must start io-display before starting the Photon graphics server, io-graphics. In this situation, io-graphics queries io-display for the display's settings rather than its own command-line settings. You can start Photon using the ph script on x86 targets; on other targets you need to start Photon manually.

To run both GF/OpenGL ES and Photon applications, you require the patched version of io-graphics, which cannot be run stand-alone. If you've installed the io-graphics, you always need to start io-display first, even if you aren't going to run any GF/OpenGL ES applications.

To start Photon:

Start io-display with the appropriate device and vendor IDs.
Set the environment variables required by Photon.
Start Photon.
Start phfont.
Start io-graphics, without any command-line arguments.

By default, Photon runs on the display's main layer. Therefore you should run GF and OpenGL ES applications on a different layer.

Examples:

Start io-display, and load and initialize the driver for the Fujitsu Coral PA chipset:

io-display -dvid=0x10cf,did=0x201e

This example assumes the contents of the configuration file are as follows:

device {
        drivername=coral
        vid=0x10cf
        did=0x201e
        deviceindex=0
        modeopts=/etc/system/config/coral.conf
        display {
                xres=640
                yres=480
                refresh=60
                pixel_format=argb1555
        }
}

The driver, devg-coral.so, is loaded by io-display, and the initial display resolution is 640*480*15 at 60Hz.