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

Configuring `io-winmgr`

The Composition Manager ( io-winmgr ) uses a configuration file to set HMI and application settings on startup. The configuration file contains the following sections:

Global settings: Enables you to set global options.
Display settings: Enables you to set display-specific options.
Window settings: Enables you to set options that are specific to the HMI.

Each section must be contained within a set of begin and end tags. The following example shows the begin and end tags for the display section:

begin display
...
end display

It isn't necessary for the sections to be in a particular order.

A configuration file must also define a plane. A plane represents a composition stage, or the area where the composition occurs.

The plane section has a begin and an end tag, just like a section:

begin plane
...
end plane

and must be placed within the display section.

By default, the configuration file is: /etc/system/config/winmgr.conf. You can modify this configuration file, or create a new configuration file and use the -c option to specify the location for the file.

Global settings

This section includes configuration items that have a global scope. In other words, they aren't tied to a particular display, window class, or input device.

id = [0..99]

Specifies the ID of the composition manager. This ID is appended to the device name that will be created.

For example, if set to 0, the composition manager will handle requests sent to /dev/winmgr:0. It is recommended that you omit this directive and use the default ID. This default ID will ensure that EGL connections established with EGL_DEFAULT_DEVICE_ID don't return with an error. The value for id must be a number between 0 and 99.

queue-incr-size = [size]

Indicates how much the event queue will grow when an event needs to be enqueued and the queue is full. The value must be positive and non-zero.

queue-start-size = [size]

The size of an event queue at creation. If you set queue-start-size to 20, a queue with 20 events will be allocated for each new connection that gets established.

window-incr-size = [size]

Determines the amount by which the window pool is grown when it becomes full.

select-up-alpha-test = [on|off]

Indicates whether transparency lookups will occur for every pointer event, or just events which cause a change in button state. The default value is off.

Turning this option on can hinder performance.

input = [all|attach_string|none]

Indicates which devi input devices will be managed by composition manager.

Currently supported devices include touch screens, mice, keyboards, and control devices. When the the all option is specified, composition manager scans the /dev/devi namespace, and attaches to all devices it supports, including multiple devices of the same type. You can specify an attach string to provide more control over which devices will be managed by composition manager. The attach string consists of a space separated list of devi dev entries. For example, input = touch0 mouse0 keyboard0 keyboard1 control0

The none option, indicates that the composition manager will not manage any devi input devices. The default value is none.

autofocus = [on|off]

Sets the focus policy when windows are created or destroyed.

When set to on, focus is assigned to newly created windows when they're on top. When a window that has input focus is destroyed, focus will also be assigned to the window directly above. When top-most windows get destroyed while they have input focus, the focus goes to the window below. Turning autofocus off removes these rules and requires a click or refocus from the window manager.

The default value is on.

pointer-qsize = [auto|1..n]

Sets the size of queues allocated to hold pointer events.

Depending on system load and performance, pointer events may start queueing up in the input driver. When this happens, it is important to rapidly empty events from this queue in order to minimise the latency between events, cursor updates, and actual pointer movements.

The value of this property determines the maximum number of events that can be read at once. The auto value indicates that the composition manager will grow the queue as events start queueing up.

The default value is 1.

Display settings

You must define one display section for every display that will be handled by the composition manager.

Typically, a display entry in this configuration file will correspond to an actual physical display device. When multiple displays are present on a system, you must use the OpenWF display directives so that the Composition Manager can target each display. Otherwise, a single EGL display can be used.

id = [int]

Specifies the ID of this display instance.

This ID corresponds to the KD_QNX_WINDOWPROPERTY_DISPLAY window attribute that must be used to make a window appear on a specific display. For example, if id is set to 10, a window would have to call kdSetWindowPropertyiv() with pname set to KD_QNX_WINDOWPROPERTY_DISPLAY and param pointing to a value of 10 in order to put that window on this display.

By default, windows will be placed on the first display entry in this configuration file, not on display ID 0.

The default ID is an auto-incremented integer that starts with 0.

cursor = [sw-square|sw-arrow|hw-arrow|off]

Indicates the shape of the cursor, if present.

If cursor is set to sw-square, a small square is drawn at the coordinates of the relative pointer device.

The Composition Manager will use a hardware cursor if the value is set to hw-arrow.

The default value is off.

egl-display = [EGLNativeDisplayID|default]

The EGLNativeDisplayID that the Composition Manager should connect to, or default to specify the default EGL display.

wfd-device = [WFDDeviceId|default]

The wfd-device entry associates a display section with a physical display.

You can use the sysres utility to generate a list of WFD devices, ports and pipelines available on a system. It isn't necessary to provide a wfd-device unless the Composition Manager must handle multiple displays.

wfd-port = [WFDPortId|default]

This directive indicates which display port should be used to drive the physical display.

You can use the sysres utility to generate a list of WFD devices, ports, and pipelines that are available on a system. The default value corresponds to the first port ID returned by WFD.

wfd-mode = [width] x [height] @ [refresh]

Use this directive to change the display mode.

This directive is necessary only if the display mode isn't set when the Composition Manager starts up. The width and height arguments indicate the display resolution. The refresh argument is the update rate in frames per second. The default value is the current display mode.

Note that a specific display controller may not support all combinations of resolutions and refresh rates.

# Set the display mode.
wfd-mode = 640x480@60

begin plane

A display must have at least one plane section. A plane represents a composition stage.

egl-config = [EGLConfig|auto]

When the egl-config directive is present, the Composition Manager creates a target surface where composition results can be saved. This allows several windows to share the same plane. The value of egl-config specifies which pixel format is used to create the target buffer. The egl-config argument must refer to an EGL configuration that supports native rendering, for example EGL_NATIVE_RENDERABLE is set to EGL_TRUE.

You can use the sysres utility to generate a list of EGL configuration IDs that can be used.

wfd-pipeline = [WFDPipelineID|default]

This directive associates a plane to a WFD pipeline, or layer.

Planes can be associated to WFD pipelines whether they have target buffers or not (see the egl-config directive). A wfd-pipeline with no egl-config can support one window. When multiple windows are created on such planes, only the top-most window is visible.

Conversely, planes with target buffers that are associated with WFD pipelines can support any number of windows simultaneously.

You can use the sysres utility to generate a list of WFD devices, ports, and pipelines available on a particular system.

source-alpha = [on|off]

When turned on, the values from alpha channels are used to blend the contents of a window with other windows, or with the background beneath it.

Blending can still be performed even if this option is not enabled when a target buffer is available (see egl-config).

The option is ignored if the WFD pipeline does not support source alpha blending. The source-alpha and source-chroma options should not both be turned on. The option is also ignored if the plane was tied to a valid WFD pipeline ID.

source-chroma = [on|off]

When turned on, colors that correspond to the background color will be interpreted as transparent.

The option is ignored if the hardware doesn't support source color transparency. Don't turn on both the source-chroma.

background = rrggbb

Specifies the background color for a plane.

The background color fills regions not occupied by windows of the lower plane. The default background color is black, or 000000. Note that certain optimizations are available only if the background color is black.

Planes without target buffers can't have a background color. For planes where source color transparency is enabled (see source-chroma), the background color directive specifies the source color that will be interpreted as transparent.

end plane

Window class settings

Classes can be used by system integrators to set default values for window properties that can otherwise be configured differently from system to system. This works as long as the application itself sets the class property, or in cases where a delegate does it instead.

Each begin and end class directive defines a new class. Note that all fields are optional. Only the fields specified in the class description will actually be copied into their corresponding window properties.

name = [string]

Indicates the name of the class. The class is used to identify a window. No two classes can share the same name. This string affects the KD_QNX_WINDOWPROPERTY_CLASS window property if a window wishes to inherit the values stored in this class.

caption = [string]

The caption string for any window deriving from this class.

This property isn't used by the Composition Manager to provide a title bar. It affects the KD_WINDOWPROPERTY_CAPTION window property.

delegate = [true|false]

The default value of the delegate flag for windows inheriting from this class. This affects the KD_WINDOWPROPERTY_DELEGATE window property, when it is set with kdSetWindowPropertybv() and read with kdGetWindowPropertybv().

visible = [true|false]

The default value of the visible flag for windows inheriting from this class.

This affects the KD_WINDOWPROPERTY_VISIBILITY window property.

source-alpha = [true|false]

The default value of the source alpha flag for windows inheriting from this class.

This affects the KD_QNX_WINDOWPROPERTY_SOURCE_ALPHA window property.

pointer-focus = [true|false]

Specifies that pointer focus will be assigned to any window that inherits from this class. This affects the KD_QNX_WINDOWPROPERTY_POINTER_FOCUS window property.

When pointer focus is assigned to a window, general focus cannot be re-assigned by mouse click.

focus = [true|false]

Specifies that general focus will be assigned to any window that inherits from this class. This affects the KD_QNX_WINDOWPROPERTY_FOCUS window property.

surface-size = [width] x [height]

Specifies a default buffer size for windows derived from this class.

This affects the KD_QNX_WINDOWPROPERTY_SURFACE_SIZE window property.

source-position = [x], [y]

Specifies a default source position for windows derived from this class.

This affects the KD_QNX_WINDOWPROPERTY_SOURCE_POSITION window property.

source-size = [width] x [height]

Specifies a default source size for windows derived from this class.

This affects the KD_QNX_WINDOWPROPERTY_SOURCE_SIZE window property.

window-position = [x], [y]

Specifies a default screen position for windows derived from this class.

This affects the KD_QNX_WINDOWPROPERTY_POSITION window property.

window-size = [width] x [height]

Specifies a default size for windows derived from this class.

This affects the KD_WINDOWPROPERTY_SIZE window property.

alpha = [0..255]

Global transparency value for windows derived from this class.

This affects the KD_QNX_WINDOWPROPERTY_ALPHA window property.

interval = [0..255]

Default swap interval for all windows inheriting from this class. This affects the KD_QNX_WINDOWPROPERTY_SWAP_INTERVAL window property.

egl-config = [EGLConfig]

Specifies the default pixel-format that should be used by windows derived from this class.

This field doesn't correspond to an OpenKODE window property. It replaces the config argument provided to the kdCreateWindow() function. You can use utilities such as egl-configs or io-winmgr's sysres command to generate a list of EGL configurations available on a given system. The EGL config ID is the value that you should use to set this attribute.

Configuring io-winmgr

Global settings

Display settings

Window class settings

Configuring `io-winmgr`