io-display

The QNX Graphics Framework server

Syntax:

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

Runs on:

Neutrino

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 has the following options and subsections:

• 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:
  • argb1555 — 16 bpp
  • rgb565 — 16 bpp
  • rgb888 — 24 bpp
  • argb8888 — 32 bpp
• photon — a subsection that includes Photon-specific options:
  • enabled — 1 if Photon is enabled for this display, or 0 if it isn't.
  • xoffset, yoffset — the x and y offsets for the display.
  • layer — the layer index for the display.
  • input_group — the input group for the display.
  • cursor — the type of cursor; one of hardware, software, or none.
  • phook — a Photon hook module to load; one of:

    ph-rotate-90.so

    Rotate the display 90 degrees.

    ph-rotate-180.so

    Rotate the display 180 degrees.

    ph-rotate-270.so

    Rotate the display 270 degrees.

    You can also load a hook module by calling PgPHookRegister(). For more information, see the Photon Library Reference.

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=0x201e
            deviceindex=0
            modeopts=/usr/photon/config/coral.conf
            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 start Photon:

1. Start io-display with the appropriate device and vendor IDs.
2. Set the environment variables required by Photon.
3. Start Photon.
4. 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

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

See also:

io-graphics, dispconf