io-graphics

Start the Photon graphics server

Syntax:

io-graphics [-c config file]
            [-C crtc_settings_file]
            [-d driver [driver_options]] ...
            [-F font_options] [-f]
            [-p plugin [plugin_options]] ...]

Runs on:

Neutrino

Options:

-c
The location of the io-graphics configuration file. You can use this file instead of the command line options to set io-graphics options. You can't use both the command line and the configuration file. See The io-graphics Configuration File below for a description of this file's format.
-C
The location of the crtc-settings file. If unspecified, the default is /etc/system/config/crtc-settings.
-ddriver [driver_options]
Load the specified driver and pass it the optional driver_options. The driver is a shared object named devg-driver.so . For example, -dbanshee loads devg-banshee.so.
For more information on the available graphics drivers, see the devg-* entries:
Driver Shared object
3dfx VooDoo devg-banshee.so
ATI Mach64 devg-mach64.so
ATI RADEON devg-radeon.so
ATI RAGE devg-rage.so
ATI RAGE 128/128 Pro devg-ati_rage128.so
Chips and Technologies devg-chips.so
Flat unaccelerated devg-flat.so
Fujitsu Coral devg-coral.so
Fujitsu MB86292 devg-orchid.so
Generic (SVGA) devg-svga.so
Generic (VESA 2.0) devg-vesabios.so
Generic (VGA) devg-vga.so
Hitachi Q2SD devg-q2sd.so
Intel I810 and I815 devg-i810.so
Intel I830 devg-i830.so
Intel PXA250 devg-pxa250.so
Matrox Millenium G-series devg-matroxg.so
Matrox Millenium, Mystique, and G100 devg-matrox.so
MediaQ MQ-200 devg-mq200.so
National Semiconductor Geode and Media GX devg-geode.so
NEC Ravin devg-ravin.so
NeoMagic devg-neomagic.so
Rotate display 90 degrees devg-rotate90.so
Rotate display 270 degrees devg-rotate270.so
NVIDIA devg-tnt.so
RPX-lite development board devg-rpxlite.so
S3 Savage devg-s3_savage.so
S3 Vision, Virge, and Trio devg-s3.so
SA1100 LCD controller devg-sa1110.so
Silicon Motion Lynx devg-smi7xx.so
Silicon Motion SM501 devg-smi5xx.so
SIS devg-sis630.so
STPC devg-stpc.so
TVIA CyberPro 50xx devg-igs5000.so
TVIA CyberPro devg-tvia.so
The driver_options are:
vid=vendor_id
The PCI Vendor ID of the graphics device.
did=device_id
The PCI Device ID of the graphics device.
index=pci_index
The PCI index of the graphics device. Default is 0.
xres=x_res
The horizontal resolution of the display.
yres=y_res
The vertical resolution of the display.
bitpp=bit_pp
The bits per pixel color depth of the display.
refresh=value
The refresh rate, in Hz. The default value depends on the driver, though it is typically 60.
palette=palette_file
Load the palette_file as the graphics driver's initial palette. The palette data is stored as 4 bytes per pixel arranged as blue, green, red, and a spare.
hook=hook_modules
The driver's hook modules. You can specify multiple modules by using a quoted, space-separated string (e.g. hook="devg-rotate90.so devg-stats.so").

Hook modules are modules that are used to replace driver functions. The hook module calls the driver to accomplish the task it is performing, but allows statistics and transformations to occur prior to the driver being called.

The following hooks are shipped with Neutrino:

noversion
Disable the driver version mismatch validation.
mode_opts=argument_string
mem_opts=argument_string
misc_opts=argument_string
vid_opts=argument_string
vcap_opts=argument_string
Specify an argument_string to pass to the initialization function of a hardware-level driver module. The interpretation of the argument_string is driver dependent. See the device driver documentation for details.
db[=interval]
Enable double buffering. You can optionally set the double buffer interval in ns. The default is calculated from the time it takes the display controller to enter the vertical-retrace period, as returned by wait_vsync().
driver_ws=size
The size of the graphics driver's internal workspace, in bytes. Default is 16K.
receive_len=size
The maximum message length, in bytes. Default is 32K.
reply_len=size
The maximum reply length, in bytes. Default is 16K.
photon[=photon_name]
Enable the Photon interface for this device. Optionally, you can specify the name of the Photon server as photon_name to attach to. photon_name is passed literally as the name parameter to PhAttach().

These options are available only if the photon option is enabled:

expose=Y|y|N|n
If Y|y, emit an expose event on initialization. This requests a redraw from all Photon objects. Default: y.
input_group=input_group
Set the driver region input group. Default: 1.
region_x=xpos
region_y=ypos
Place the driver region at a specific location in the Photon event space. Default: 0, 0.
-f
Don't load the internal font server.
-F font_options
Command-line options for the local font DLL. See phfont for a list of options. Options must be quoted. For example, the phfont command line -d /usr/photon/font -A becomes "-d=/usr/photon/font -A"
-p plugin [plugin_options]
Load a plugin, and optionally pass it the given plugin_options. For example: -p photon. There is one plugin available, gri-photon.so.

Description:

The io-graphics command starts a graphics driver.


Note: The format of the command-line options for this utility changed in Neutrino 6.3. However, io-graphics still accepts and understands the old format. However, there are limitations: you can't mix the legacy and current options, and you can't specify the legacy options in a configuration file. For a list of these options, see Legacy command-line options, below.

The io-graphics configuration file

You can pass a configuration file to io-graphics on startup using the -c option. This file is processed before any other command line options. The same device may not be configured in both the file and the command line.

The configuration file allows you to configure multiple displays on one or more device. These device drivers support multiple displays on a single device:

When multiple displays are supported by a single device, the following functions will only work on one display:

In addition, PdSetTargetDevice() may not work correctly, and video overlays will probably only work on one display.


Note: QNX doesn't guarantee support for arbitrary combinations of multiple video cards.

The configuration file has these rules:

For some sample configuration files, see "Setting up multiple displays" in the Connecting Hardware chapter of the Neutrino User's Guide.

Sections

These sections make up the configuration file:

[GLOBAL]
This section enumerates devices.
[DEVICE.device]
This section is required for each device in the [GLOBAL] section. This section specifies properties for a device loaded for device.
[DEVICE.device.n]
Specifies properties for each display supported by the device. The entries in this section override the entries in [DEVICE.device].
Displays are numbered from n = 0 to displays-1.
[PLUGIN.plugin]
Specifies the default initial properties for each plugin listed in the [GLOBAL] section.
[DEVICE.device.PLUGIN.plugin]
Specifies properties for a plugin to be mounted at /dev/io- graphics/device/plugin. The entries in this section override the entries in [PLUGIN.plugin].

[GLOBAL] section

This is a space-delimited list of devices in the form devices=device [device [device]...] where each device must be a valid pathname component. The default is an empty string. Example:

[GLOBAL]
devices = radeon matroxg

[DEVICE.device] section

This section sets options for each device listed in the GLOBAL section. It has the following entries:

dllpath=[dll [dll...]]
A space-delimited list of driver pathnames, in the form devg- driver.so. (The path to the DLL may be included.) Drivers are loaded in the order specified. The default is an empty string. This entry is required. Example:
[DEVICE.radeon]
dllpath  = devg-radeon.so /dev/shmem/devg-test.so
transform_modules = module [module [ module]...]
Space-delimited list of transform module pathnames. The default is an empty string. Example:
transform_modules = devg-stats.so
mode_options = arguments_string
mem_options= arguments_string
misc_options = arguments_string
vid_options= arguments_string
vcap_options = arguments_string
Driver-specific initialization strings. The default is an empty string.
driver_workspace = value
The size of the graphics driver's internal workspace. Default: 16K.
enable_doublebuffer = value
Enable double-buffering. value can be 0 or 1 . The default is 0.
doublebuffer_interval = value
Optionally specify double-buffer interval in nanoseconds. The default is calculated from wait_vsync().
expose = YES|NO
Emit an expose event at the Photon root region on initialization. This entry can be set to YES (the default) or NO.
allow_version_mismatch = YES|NO
Overrides driver version validation. This entry can be set to YES or NO (the default). Example:
allow_version_mismatch = NO
pci_vendor_id = value
pci_device_id= value
pci_index = value
Specify PCI device information as an integer Defaults: 0. Example:
pci_vendor_id = 0x1002
pci_device_id = 0x5144
pci_index = 0
displays = value
The number of displays to initialize on this device. This value is bounded by the number of displays supported by the driver. Default: 1 Example:
displays = 1
plugins = module [module [module]...]
Space-delimited list of plugins to mount. Default: an empty string. Example:
plugins = photon

Note: module is a logical name that is used to find the corresponding plugin configuration section, PLUGIN.module.

xres = value
yres = value
bitpp= value
refresh = value
Initial display properties. Defaults: 0. Example:
xres = 1024
yres = 768
bitpp = 16
refresh = 60

palette = palette_file
Set the default palette file. The default is an empty string. For example:
palette  =
gamma_factor_r|g|b = value
Gamma color correction as a 16.16 fixed point value. Default: 0.2. Example:
gamma_factor_r = 0x3333
gamma_offset_r|g|b = value
Offset level for gamma color correction as a 16.16 fixed point value. Default: 0.16. Example:
gamma_offset_g = 0x1000
gamma_white_r|g|b = value
White level for gamma color correction as a 16.16 fixed point value. Default: 1.0. Example:
gamma_white_b = 0x10000
receive_buffer_length = value
The maximum message length in bytes. This usually bounds drawstream length. Default: 32K. Example:
receive_buffer_length = 0x8000
reply_buffer_length = value
The maximum reply length in bytes. Default: 16K. Example:
reply_buffer_length = 0x4000
photon = photon_server
Name of photon server. The existence of this entry enables the photon server interface on this device. The empty string is an acceptable value, and indicates that the default value should be used. The default is $PHOTON.
region properties
Graphics driver region properties. These entries are processed only if the photon entry exists. These properties are:

[DEVICE.device.n] section

This section sets the options for the device number n. This allows you to set options for multiple displays. The possible entries are a subset of the DEVICE section (see above):

[PLUGIN.plugin] section

This section configures each plugin listed in the plugins entry in the DEVICE section. Entries are:

dllpath = [path]plugin
Plugin pathname in the form gri-plugin.so. This entry is required for each plugin. Example:
dllpath  = gri-photon.so

or:

dllpath  = /dev/shmem/gri-photon.so
options = option_string
Initialization string for the plugin. See the plugin documentation for its specific options.

Legacy command-line options

The command-line options for io-graphics changed in Neutrino 6.3, but the legacy options are still supported. There are limitations: you can't mix the legacy and current options, and you can't specify the legacy options in a configuration file.

io-graphics [-aargument] [-B] [Ccrtc_settings_file]
            [-ccursor_option]
            [-dl driver [driver_options]] ...
            [-dvendor,device] [-G n] [-g             X,Y,B]
            [-HP...] [-In] [-N] [-n name] [-o X,Y
            ]
            [-P palette_file] [-p n] [-s n]
            [-T] [-w n] [-wc n] [-wr n]
            [-wu n] [-Z none] [-Z val]
            [-ZB val] [-ZW val]

These options are:

-aargument
The argument variable takes the form token=string, where token represents the hardware-level driver module that will receive the string. Strings are passed to a module's entry point as optstring parameters. The meaning of a particular string depends on the driver used.

These are the permitted tokens with their module entry points:

Here's an example:

io-graphics -amode=nopanel,tvout:pal
-amisc=gofast
-B
Perform double buffering if supported by hardware.
-C
The location of the crtc-settings file. For example, /etc/system/config/crtc-settings.
-ccursor_option
Specify cursor options:
-dldriver [driver_options]
Load the specified driver and pass it the given driver_options.

For information on the drivers and their syntax and options, see the table above.

-dvendor,device
Specify the PCI Vendor and Device ID of the graphics device.
-G n
Set the primary Photon input group.
-g X,Y,B
Define the size and color depth of the video mode, such as -g 640,480,4 for the standard VGA mode of 640*480 in 16 colors.
-HP...
Make the graphics driver a child of a region.
-In
Specify the PCI index of the graphics device.
-N
Prevent the screen from clearing at startup. (This is useful for providing splash screen support).
-n name
The name of the Photon server to attach to. If the name starts with a digit, it's a node number. If the name starts with a slash (/) it's a full path. Otherwise, the system looks for the server name in the dev directory.
-o X,Y
Place the graphics driver at a specific location in the Photon event space.
-P palette_file
Load the graphics driver's initial palette. The palette data is stored as 4 bytes per pixel arranged as blue, green, red, and a spare.
-p n
The maximum number of palettes in the palette cache (default: 8).
-R n
The n variable is the refresh rate in Hz. The default rate depends on the driver, typically it is 60Hz.
-s n
The maximum number of screen buffers (default: 32).
-T
The transform module used for switching views.
-w n
The size of the graphics driver's internal workspace (default: 16K).
-wc n
The number of internal clipping rectangles (default: 256).
-wr n
The initial size of the receive buffer, in kilobytes (default: 4K).
-wu n
The number of user clipping rectangles (default: 64).
-Z none
Disable gamma correction.
-Z val
Set the gamma correction factor (0 no correction; default: 0.2).
-ZB val
Set the black level for gamma correction (default: 0.06).
-ZW val
Set the white level for gamma correction (default: 1).

Note: You can also specify gamma correction values as RGB values for monitors with inconsistent colors.

Files:

The devg-* drivers generally require libffb.so.2 and libdisputil.so.2 at runtime.

Environment variables:

PHFONT_USE_EXTERNAL
If this environment variable exists, io-graphics does not run an internal font server. You should set this environment variable for systems that have remote clients accessing font services on the host machine (e.g. phindows, phditto).

See also:

crttrap, phfont, phgrafx

"Graphics drivers (devg-*)" in the Utilities Summary

Connecting Hardware in the Neutrino User's Guide