Configuring Screen

Graphics and Screen4.0 (8.x)Screen Graphics Subsystem Developer's GuideAPIProgrammingUtilities

You configure libraries, drivers, and Screen parameters using the configuration file, graphics.conf.

Configuration file

The graphics.conf file is located in the following directory:

on your host: $QNX_TARGET/processor/usr/lib/graphics/platform
on your target: /usr/lib/graphics/platform

where processor is the CPU architecture of your target hardware, and platform is the name of your platform (e.g., imx6x).

Unless your target system allows for it, you modify the graphics.conf file on your host, and then build it into your OS image filesystem. When you start the Screen services in your target system, Screen will process the configuration file that you specified in the -c option. See screen in the "Utilities and binaries" chapter of this guide.

The graphics.conf file is a free-form ASCII text file. Screen or clients parse this file. The file can contain extra tabs and blank lines for formatting purposes. Keywords in the file are case-sensitive. You can place comments anywhere within the file (except within quotes). Comments begin with the # character and end at the end of the line.

The graphics.conf file includes the following main sections:

khronos

Specifies the libraries and parameters related to Khronos (GPU and WFD libraries). The libraries and parameters in this section apply to your EGL display and WFD driver. This section is denoted by the begin khronos and end khronos statements.

The khronos section can have the following subsections:

egl display
wfd device

winmgr

Specifies the parameters related to Screen. This section is denoted by the begin winmgr and end winmgr statements. The parameters in this section include those that apply to:

Screen globally
displays
classes (e.g., framebuffers)

The winmgr section can have the following subsections:

globals
display
virtual display
class

Configuration parameters

Within each of the sections and subsections of your graphics.conf file, you can specify the configuration of several parameters. Some parameters are platform-specific. Use the following format to configure parameters:

parameter = value

Each configuration parameter must be on its own separate line. If the parameter allows for multiple values as its configuration, then the values follow the = after the parameter and are separated by either a space or a comma. For example:

parameter = value1,value2,value3

parameter = value1 value2 value3

For reference purposes, the complete list of parameters by section in the configuration file is as follows:

khronos section:

egl display subsection:

wfd device subsection:

Parameters in this section are platform-specific. Refer to Configure wfd device subsection.

winmgr section:

globals subsection:

display subsection:

virtual display subsection:

class subsection:

Configuration example

A typical graphics.conf file will look something like this:

begin khronos
  begin egl display 1
    egl-dlls = [IMG%s] libusc.so libsrv_um.so libpvr2d.so libIMGegl.so
    glesv1-dlls = libusc.so libsrv_um.so  libIMGegl.so libImgGLESv1_CM.so
    glesv2-dlls = libusc.so libsrv_um.so libusc.so libIMGegl.so libImgGLESv2.so
    gpu-dlls = libsrv_um.so libpvr2d.so pvrsrv.so
    gpu-string = SGX540rev120
    aperture = 200
  end egl display

  begin wfd device 1
    wfd-dlls = libomap4modes-panda.so libWFDomap4430.so
  end wfd device
end khronos

begin winmgr
  begin globals
    blit-config = pvr2d
    blits-logsize = 4096
    input-logsize = 8192
    requests-logsize = 65536
  end globals

  begin display 1
    formats = rgba8888 rgbx8888 nv12
    video-mode = 1280 x 720 @ 60
  end display
  
  begin virtual display
    id_string = virtual-1
    video-mode = 1280 x 768 @ 60
    format = rgba8888
    usage = vmwgfxdrm
  end virtual display

  begin class framebuffer
    pipeline = 3 
    display = hdmi 
    surface-size = 1280 x 720
    format = rgba8888
    usage = pvr2d 
  end class
end winmgr

Configure khronos section

Graphics and Screen4.0 (8.x)Screen Graphics Subsystem Developer's GuideAPIProgrammingUtilities

The khronos section specifies the libraries and parameters related to Khronos (e.g., EGL and WFD libraries).

In your graphics.conf configuration file, the khronos section specifies your GPU and display drivers. Include this section in your configuration file only if your system requires one or both of these types of drivers. The khronos section is enclosed with begin khronos and end khronos. For example:

begin khronos
  begin egl display 1
    ...
  end egl display

  begin wfd device 1
    ...
  end wfd device
end khronos
...

Subsections

The subsections of the khronos section are:

egl display: Libraries and parameters that are related to the EGL display are specified in this section that starts with begin egl display display_id and ends with end egl display.
wfd device: Libraries and parameters that are related to the WFD driver are specified in this section that starts with begin wfd device device_id and ends with end wfd device.

Note:

On your target, all libraries that you specify in the khronos section of your configuration file should reside in the same directory as the configuration file itself.

Configure egl display subsection

Graphics and Screen4.0 (8.x)Screen Graphics Subsystem Developer's GuideAPIProgrammingUtilities

The egl display subsection specifies the GPU libraries and parameters.

This section must begin with begin egl display display_id and end with end egl display. Include this section in your configuration file only if your system requires graphics drivers.

Typically, there's only one egl display section. Therefore, conventionally, you set the display ID to 1.

Here's an example of an egl display section:

begin egl display 1
  egl-dlls = [IMG%s] libusc.so libsrv_um.so libpvr2d.so libIMGegl.soD
  glesv1-dlls = libusc.so libsrv_um.so  libIMGegl.so libImgGLESv1_CM.so
  glesv2-dlls = libusc.so libsrv_um.so libusc.so libIMGegl.so libImgGLESv2.so
  gpu-dlls = libsrv_um.so libpvr2d.so pvrsrv.so
  gpu-string = SGX540rev120
  aperture = 200
end egl display

Most of these libraries and parameters are provided in the default graphics.conf configuration file delivered with your platform.

Note:

This egl display section is not related, in any respect, to physical displays, or to the display subsection of the winmgr section.

On your target, all libraries that you specify in this egl display subsection of your configuration file should reside in the same directory as the configuration file itself.

Parameters

The following are valid parameters that can be configured under the egl display subsection:


Parameter	Description	Type	Possible value(s)
aperture	The number of MB of GPU memory to allocate at startup	Integer	Range varies
cl-dlls	The OpenCL client libraries for your platform	String	`libOpenCL.so`
egl-dlls	The EGL libraries	String	`libusc.so` `libsrv_um.so` `libpvr2d.so` `libIMGegl.so`
glesv1-dlls	The OpenGL ES 1.X libraries	String	`libusc.so` `libsrv_um.so` `libIMGegl.so` `libImgGLESv1_CM.so`
glesv2-dlls	The OpenGL ES 2.X libraries	String	`libusc.so` `libsrv_um.so` `libIMGegl.so` `libImgGLESv2.so`
gpu-dlls	The GPU libraries	String	`libsrv_um.so` `libpvr2d.so` `pvrsrv.so`
gpu-string	The SGX core. The gpu-string will determine core-specific behavior.	String	`SGX535rev121` `SGX530rev125` `SGX540rev120`
vg-dlls	The OpenVG libraries	String	`libsrv_um.so` `libIMGegl.so` `libImgOpenVG.so`
vk-exps	List of Vulkan JSON file names or paths. The path could be full or relative to the graphics.conf file. Any non JSON files are treated as prerequisite libraries and are loaded before any attempts at loading explicit layers at runtime. Layers specified as explicit can be activated by applications at runtime. You can also activate these layers by setting the VK_INSTANCE_LAYERS environment variable. This variable can be set with a colon separated list of layer names that need activation. The first layer in the list is the topmost, the layer closest to the application. The last layer in the list is at the bottom, the layer closest to the driver.	String	`VkLayer_khronos_validation.json` `/usr/lib/graphics/vulkan/VkLayer_khronos_validation.json`
vk-icds	List of Vulkan JSON file names or paths. The path could be full or relative to the graphics.conf file. Any non JSON files are treated as prerequisite libraries and are loaded before any attempts at loading the ICD driver.	String	`intel_icds.json` `/usr/lib/graphics/vulkan/intel_icds.json`
vk-imps	List of Vulkan JSON file names or paths. The path could be full or relative to the graphics.conf file. Any non JSON files are treated as prerequisite libraries and are loaded before any attempts at loading implicit layers. Any layer specified as implicit is automatically loaded by the ICD loader.	String	`VkLayer_MESA_overlay.json` `/usr/lib/graphics/vulkan/VkLayer_MESA_overlay.json`

Configure wfd device subsection

Graphics and Screen4.0 (8.x)Screen Graphics Subsystem Developer's GuideAPIProgrammingUtilities

The wfd device subsection specifies the OpenWF Display libraries and parameters.

This section must begin with begin wfd device device_id and end with end wfd device. Include this section in your configuration file only if your system requires display drivers.

Typically, there's only one wfd device section. Therefore, conventionally, you set the device ID to 1.

Below is an example of a wfd device section of a graphics.conf file:

begin wfd device 1
  wfd-dlls = libj5modes-evm.so libWFDjacinto5.so
  grpx0 = lcd
  grpx1 = hdmi
  grpx2 = hdmi
  video-layer0 = lcd
  video-layer1 = hdmi
end wfd device

The parameters that can be configured under the wfd device section are platform-specific. You must obtain the valid parameters for your platform by running the use command on the libraries for your platform:
use libWFDplatform.so

The use command will display a message describing the specific parameters and libraries to configure for your particular platform. These libraries are usually located on your host in the following directory:
$QNX_TARGET/PROCESSOR/usr/lib/graphics/platform/
where PROCESSOR is the name of the CPU and platform is the name of your target's platform.

Note:

On your target, all libraries that you specify in this wfd device subsection of your configuration file should reside in the same directory as the configuration file itself.

Configure winmgr section

Graphics and Screen4.0 (8.x)Screen Graphics Subsystem Developer's GuideAPIProgrammingUtilities

The winmgr section specifies the parameters related to Screen.

Your graphics.conf configuration file must include a winmgr section where your global, display, virtual display, and class parameters are specified.

The winmgr section is identified as the section of the configuration file that's enclosed by begin winmgr and end winmgr.

...
begin winmgr
  begin globals
  ...
  end globals

  begin display hdmi
  ...
  end display
  
  begin virtual display 
  ...
  end virtual display

  begin class framebuffer
  ...
  end class
  

end winmgr

Subsections

The subsections of the winmgr section are:

globals: Parameters that apply globally to Screen are specified in this subsection starting with begin globals and ending with end globals. There can be only one globals section in your configuration file.
display: Parameters that are related to the display are specified in this subsection starting with begin display display_id and ending with end display. There can be multiple display subsections, each corresponding to a physical display that's available and supported by the platform.
virtual display: Parameters that are related to virtual displays are specified in this subsection starting with begin virtual display and ending with end virtual display. There can be multiple virtual display subsections. Virtual displays allow rendering without the use of a physical display. Virtual displays contain framebuffers that you can use for off-screen rendering.
class: Parameters that are related to the class are specified in this subsection starting with begin class class_name and ending with end class. There can be multiple class subsections to correspond to each class defined.

Configure globals subsection

Graphics and Screen4.0 (8.x)Screen Graphics Subsystem Developer's GuideAPIProgrammingUtilities

The globals subsection specifies the configuration to apply globally to Screen.

This section must begin with begin globals and end with end globals.

There can only be one globals section. Parameters that are set in this section are applied to all pipelines.

Below is an example of a globals section of a graphics.conf file.

begin globals
  blit-config = pvr2d
  blits-logsize = 4096
end globals

You can view the globals configuration at anytime. The configuration parameters and their associated values are stored in the /dev/screen/0/globals file. See the At runtime subsection of the Debugging section for more information.

Parameters

The following are valid parameters that can be configured under the globals subsection:


Parameter	Description	Type	Possible value(s)
alloc-config	The name of the module used for buffer allocation. Screen uses the following algorithm to determine the allocation module to load: `"screen-" + <value of alloc-config> + ".so"` This configuration is platform-specific, and it's already set in the graphics.conf provided to you for your platform. We don't recommend changing this configuration from its original value.	String	`imx6xbuf`
autofocus	Indicate whether windows and sessions automatically acquire input focus when created or when they become focusable. You can turn this option on (default) or off. This setting applies only to inputs that are focusable. Such inputs are joystick, gesture, and keyboard based. Inputs such as pointer inputs are controlled by the display's focus and configuration and are not affected by this setting. When on, windows and sessions will acquire input focus when created. If they cannot focus immediately after creation, they acquire input focus when they are able to focus for the first time. When off, input focus does not change between windows or sessions when a new window or session is created. In this case, use SCREEN_PROPERTY_FOCUS to explicitly set the input focus.	String	`on (default)` `off`
blit-config	The blitter used when your application explicitly calls the native blit API functions (screen_blit() and screen_fill()). Screen uses the following algorithm to determine the blitter module to load: `"screen-" + <value of blit-config> + ".so"` Specify `none` to disable the use of a blitter module. If you specify `none`, screen_blit() and screen_fill() will fail to execute. Note: Only one blitter can be configured. The selection of valid blitters depends on your platform; there can be multiple blitter values available for your particular platform. This parameter differs from the blitter specified in the usage parameter under your `class` section in graphics.conf. The blitter specified in the usage parameter is the blitter that Screen uses for composition.	String	`sw` (default) `pvr2d` `bv-j5` `gles2blt` `none`
blit-defer	Specify whether Screen loads the blitter module on startup or only when a blit operation is called.	String	`false` Screen loads the associated (or configured) blitter module at startup. `true` (default) Screen loads the blitter module on the execution of a blit operation (e.g., screen_blit() or screen_fill()).
blits-logsize	The size (in bytes) of an internal working ring buffer. You can specify the size followed by "K" or "M" to represent multiples of 1024 or 1048576 bytes respectively.	Integer or String	Examples: `4K` (default) `2M` `2048K` `2097152`
default-display	The primary display. Identify the primary display by using the `display_id` that's used to define your displays in the `display` section of graphics.conf. This is typically an integer that identifies the display. This parameter is valid only if your system supports displays.	Integer	Example: `1`
gesture-logsize	The size (in bytes) of an internal working ring buffer. You can specify the size followed by "K" or "M" to represent multiples of 1024 or 1048576 bytes respectively.	Integer or String	Examples: `0` (default) `2M` `2048K` `2097152`
idle-timeout	The maximum time (in nanoseconds) between two input events that the system receives before Screen deems it to be in an idle state. By default, the SCREEN_PROPERTY_IDLE_STATE property is set to 0, and the idle-timeout check isn't active. The SCREEN_PROPERTY_DISPLAY property returns the handle of the display when a window enters an idle state. The SCREEN_PROPERTY_GROUP property returns the group when one of the windows has entered the idle state (if applicable).	Integer	`0` (default) Screen ignores idle states.
input	Human interface device (HID). This parameter can be configured with multiple values. If you don't specfiy input at all in your configuration file, Screen defaults to include all input (i.e., the same as if you had specified `input = gamepad joystick keyboard mouse`). Specify `none` (with no other valid input string) to explicitly disable all input. Note: If you specify any valid input string other than `none`, you must ensure that you have io-hid running before starting screen; you must also have libhiddi.so in your LD_LIBRARY_PATH.	String	`gamepad` `joystick` `keyboard` `mouse` `none`
input-logsize	The size (in bytes) of an internal working ring buffer. You can specify the size followed by "K" or "M" to represent multiples of 1024 or 1048576 bytes respectively.	Integer or String	Examples: `8K` (default) `2M` `2048K` `2097152`
joystick-logsize	The size (in bytes) of an internal working ring buffer. You can specify the size followed by "K" or "M" to represent multiples of 1024 or 1048576 bytes respectively.	Integer or String	Examples: `0` (default) `2M` `2048K` `2097152`
keyboard-logsize	The size (in bytes) of an internal working ring buffer. You can specify the size followed by "K" or "M" to represent multiples of 1024 or 1048576 bytes respectively.	Integer or String	Examples: `0` (default) `2M` `2048K` `2097152`
keymap	The location and/or the name of the default keymap file. This parameter is optional and applicable only to HID keyboards. To change the default keymap file name and location, provide the folder path and file name without the .kbd extension. For example: `keymap=/my/share/folder/ru_RU_102` To specify a different keymap file, provide the file name without the .kbd extension. The file has to be located in the default folder. If it is in a different location, use the method above. For example: `keymap=ru_RU_102` To specify a different keymap file location, provide the folder path ending with a slash (/). For example: `keymap=/my/share/folder/`	String	Examples: `/usr/share/keyboard/en_US_101` (default file name and location) `en_US_101` (default file name) `/usr/share/keyboard/` (default folder)
pointer-logsize	The size (in bytes) of an internal working ring buffer. You can specify the size followed by "K" or "M" to represent multiples of 1024 or 1048576 bytes respectively.	Integer or String	Examples: `0` (default) `2M` `2048K` `2097152`
queue-start-size	The size of the event queue per context. Events for the context, such as input events, are put into this queue. This queue size doesn't grow if there are more events than the queue size specified. This means that applications may lose events if they aren't handled before more events are queued to beyond the queue's capacity.	Integer	`20 (default)`
requests-logsize	The size (in bytes) of an internal ring buffer. You can specify the size followed by "K" or "M" to represent multiples of 1024 or 1048576 bytes respectively.	Integer or String	Examples: `64K` (default) `2M` `2048K` `2097152`
shortcuts	The string to append to the keymap name before the .kbd extension. The keymap name, this string, and the .kbd extension altogether identify the filename of the keymap file that's used when a window isn't in text-entry mode.	String
slog2-pages	The number of 4K pages allocated to the Screen process slog2 buffer. You can specify a number between 1 and 8. The default is 1 page.	Integer
stack-size	The stack size (in units of bytes) that Screen is to use for its message threads. You can specify the size followed by "K" or "M" to represent multiples of 1024 or 1048576 bytes respectively. If not specified, the size is the system's stack default size. This stack-size must be configured appropriately for blitters/compositors that are using Mesa (e.g., gles2blt) because the default stack size is insufficient for these types of blitters/compositors.	Integer or String	Examples: `2M` `2048K` `2097152`
touch-logsize	The size (in bytes) of an internal working ring buffer. You can specify the size followed by "K" or "M" to represent multiples of 1024 or 1048576 bytes respectively.	Integer or String	Examples: `0` (default) `2M` `2048K` `2097152`
winmgr-mode	The mode that determines how a window manager context (i.e., a context whose type includes SCREEN_WINDOW_MANAGER_CONTEXT) behaves.	String	`global` (default) In global mode, all window manager contexts in the system have access to all windows that are in the system. `display` In display mode, window manager contexts have access only to the windows that are on the displays they've registered to manage.

Configure display subsection

Graphics and Screen4.0 (8.x)Screen Graphics Subsystem Developer's GuideAPIProgrammingUtilities

The display subsection specifies the configuration to apply to the physical displays that are supported by the platform.

This section must begin with begin display display_id and end with end display. Include this section in your configuration file only if your system supports displays or if there are applications on your system that require them.

There can be multiple display sections within a configuration file. The number of display sections depends on the number of physical displays supported by the platform.

You use the display_id to associate each display section with a physical display. The display_id has to be a unique number or ID defined by the display driver that identifies the display. Screen applies the configuration parameters to the display whose ID is that specified by display_id.

Below is an example of a display subsection of a graphics.conf file:

begin display 1
   formats = rgba8888 rgbx8888 nv12
   video-mode = 1280 x 720 @ 60
end display

Parameters

The following are valid parameters that can be configured under the display subsection:


Parameter	Description	Type	Possible values (if applicable)
allow-bypass	Specify whether Screen, when possible, can bypass copying window buffers to a framebuffer to show content on the display (i.e., perform composition). Note: Specifying `true` for force-composition voids the effect that's specified by this allow-bypass parmameter.	String	`false` Disallow Screen to bypass composition even when possible. `true` (default) Allow Screen to bypass composition when possible.
background	The background color of the display. Use RGB color code (hexadecimal value) to identify the color (e.g., blue = 0xff).	Integer (hex)	`0x00` (default: black)
background-alpha	The background opacity of the display. Use alpha transparency code (hexadecimal value) to identify the opacity (e.g., transparent = 0x00).	Integer (hex)	`0xff` (default: opaque)
cbabc	Content-based automatic brightness control; specifies the content type of the display	String	`none` The display content is not a video, UI, or photo. `video` The display content is for a video. `ui` The display content is a user interface. `photo` The display content is a static image.
cursor	The visibility of the cursor on the display	String	`auto` (default) The cursor remains visible on the display until there are 10 seconds of cursor inactivity. After that, the cursor is made invisible on the display. `on` The cursor always remains visible on the display, regardless of cursor inactivity. `off` The cursor always remains invisible on the display, regardless of cursor activity.
cursor-type	The configuration required to use a cursor shape. This parameter is specified in the following format: `cursor-type; filename; hotspot_x,hotspot_y` The parameters for cursor-type are defined as follows: `cursor-type` The type of cursor shape that you're defining. The following are valid cursor shapes: `arrow` `keyboard` `home` `menu` `hand` `ibeam` `wait` `zoom-in` `zoom-out` `grab` `grabbing` `cross` `move` `filename` A filename containing the cursor image. Only bitmap images are currently supported. The file is expected to be located in the directory /usr/share/icons. Cursor shapes must have a color depth of 32 bits per pixel. The WFD driver is required to do format conversion if 32 bits per pixel can't be used for cursors. `hotspot_x, hotspot_y` The x and y offsets, respectively, into the image that should align with the cursor position. The actual cursor rectangle corresponds to the cursor position with the hotspot offset applied as a reverse translation. This means clipping may be done on all sides of the image (top, left, right, bottom).	String	Depends on the cursor type
defer-framebuffer-creation	Specify whether Screen creates a framebuffer on startup or only when a framebuffer is required (e.g. for composition).	String	`false` Screen creates a framebuffer always on startup. `true` (default) Screen creates a framebuffer only when a framebuffer is required (e.g. for composition).
force-composition	Specify whether Screen should always use composition. (i.e., Screen always requires a framebuffer) even when the scene doesn't require it. Note: Specifying `true` for force-composition voids the effect that's specified by: the allow-bypass configuration parameter. the class configuration parameter pipeline that's applied to windows the SCREEN_PROPERTY_PIPELINE property that's set through the Screen API	String	`false` (default) Use composition only when the scene requires it. `true` Always perform composition (i.e., Screen always copies window buffers to a framebuffer) even when the scene doesn't require it.
formats	The pixel format(s) supported by the display. You can configure this parameter with multiple values. Specifying the format reduces startup time because Screen doesn't need to discover which formats are supported.	String	`byte` `rgba4444` `rgbx4444` `rgba5551` `rgbx5551` `rgb565` `rgb888` `rgba8888` `rgbx8888` `yvu9` `yuv420` `nv12` `yv12` `uyvy` `yuy2` `v422` `ayuv`
gamma	The gamma value of the WFD driver. The range is specific to the driver. The default value is 1.0, which does not alter the gamma value.	Float	Platform dependent
id_string id-string	The alias for this display. id_string is linked to SCREEN_PROPERTY_ID_STRING and can be retrieved using screen_get_display_property_cv(). This parameter is optional.	String
idle-timeout	The maximum number of time (in seconds) between two input events. When specified, if no events are received within the specified timeout, Screen deems it to be in an idle state (i.e., its SCREEN_PROPERTY_IDLE_STATE is 1). The timer is reset when the display receives an input event; the display exits idle state and SCREEN_PROPERTY_IDLE_STATE property becomes 0. By default, the idle-timeout is off (set to 0) and the display is considered to be always active.	Integer	0 (off) to 18446744073
mirroring	The mirror type.	String	`disabled` Mirroring is disabled. `normal` Mirroring is enabled, and the aspect ratio of the image is 1:1. `stretch` Mirroring is enabled, and the image should fill the display (the aspect ratio may not be preserved). `zoom` Mirroring is enabled, and the image should fill the display while preserving the aspect ratio. Image content may be clipped. `fill` Mirroring is enabled, and the image should fill the display while preserving the aspect ratio. Image may be shown with black bars where applicable.
pipelines	The pipeline identifiers that you want to associate with the display. Valid pipelines that can be associated to the display are driver-specific. When multiple pipelines are specified, each pipeline indentifier must be separated by a comma or space.	Integer
power-mode	The initial power mode of the display when you start up Screen.	String	`off` `suspend` `limited` `on` (default)
position	The position of the display. position=`x`,`y` Where `x` and `y` represent the location (in pixels) of the top left corner of the display.	String	Example:`0,800`
priority	The priority of the update thread (i.e., the thread that renders the framebuffer or framebuffers).	Integer	`15` (default)
protection-enable	Content protection for the window(s) on the display. Typically, you set this parameter only if the application is interested in HDCP (High-Bandwidth Digital Content Protection).	String	`true` `false`
rotation	The desired clockwise rotation of a display, in degrees. Note: Screen ignores this rotation parameter if you set rotation-mode to `none`. If you specify rotation, then you must also set defer-framebuffer-creation to `false`. Otherwise, Screen can't rotate the display.	Integer	`0` `90` `180` `270`
rotation-mode	Your preference of display rotation mode. If the mode of rotation you specify isn't supported by your display controller, then Screen sets the mode to `none`. Note: Screen ignores the rotation parameter if you set this rotation-mode parameter to `none`.	String	`blits` Rotated blits with pipeline rotation where possible `generic` Generic modes can resize `none` No rotation is supported `port` Port rotation, framebuffer resizes `pipeline` Pipeline rotation, framebuffer resizes
splash	The indicator to post the framebuffer on startup. This parameter is considered only if the WFD driver supports it.	Integer	`0`(default) Post the framebuffer immediately (blank screen). `1` Post the framebuffer after the application requests a post.
stack-size	The stack size (in units of bytes) that Screen is to use for its display threads. You can specify the size followed by "K" or "M" to represent multiples of 1024 or 1048576 bytes respectively. If not specified, the size is the system's stack default size. This stack-size must be configured appropriately for blitters/compositors that are using Mesa (e.g., gles2blt) because the default stack size is insufficient for these types of blitters/compositors.	Integer or String	Examples: `2M` `2048K` `2097152`
strict-pipelines	The indicator to request that Screen must use your specified pipeline assignment. You can assign pipelines by using the pipeline parameter in the `class` subsection of your configuration file, or by setting the SCREEN_PROPERTY_PIPELINE property through the Screen API. Note: Screen's application of your pipeline specification may be affected based on your configuration of the force-composition parameter.	String	`false` Screen uses a composition strategy that aims to optimize for the current scene while taking memory bandwidth and available pipelines into consideration. `true` (default) Screen uses your pipeline assignments, if any.
video-mode	The initial resolution and refresh rate for the display port. This configuration must be one that is reported by the WFD driver. If you set this to values that aren't supported, then the resolution and refresh rate defaults to the first mode specified by the driver. The resolution and refresh rate must be in the form of: `width`x`height`@i`refresh` The i indicates that interlacing is set.	String	`video-mode = 1280x720@60`

Configure virtual display subsection

Graphics and Screen4.0 (8.x)Screen Graphics Subsystem Developer's GuideAPIProgrammingUtilities

The virtual display subsection specifies the configuration to apply to created virtual displays.

This section must begin with begin virtual display and end with end virtual display. Include this section in your configuration file only if you wish to create a virtual display. You can have multiple virtual display sections within a configuration file.

Below is an example of a virtual display subsection of a graphics.conf file:

begin virtual display
    id_string = virtual-1
    video-mode = 1280 x 768 @ 60
    format = rgba8888
    usage = vmwgfxdrm
end virtual display

Parameters

The following are valid parameters that can be configured under the virtual display subsection:


Parameter	Description	Type	Possible values (if applicable)
format	The pixel format(s) for the virtual display. You can configure this parameter with multiple values. If this parameter is not set, Screen will use the following order to determine a default: If the SCREEN_DISPLAY_MODE_FORMAT_VALID flag is set, then mode.format is used. If the SCREEN_DISPLAY_MODE_FORMAT_VALID flag is not set, the default is set to `rbgx8888`	String	`byte` `rgba4444` `rgbx4444` `rgba5551` `rgbx5551` `rgb565` `rgb888` `rgba8888` `rgbx8888` (default) `yvu9` `yuv420` `nv12` `yv12` `uyvy` `yuy2` `v422` `ayuv`
id_string id-string	The alias for this virtual display. id_string is linked to SCREEN_PROPERTY_ID_STRING and can be retrieved using screen_get_display_property_cv(). This parameter is optional.	String
usage	The intended usage for the window buffers and/or the composition module (can only be set on the framebuffers). You can configure this parameter using any combination of the following: one or more integers representing a valid usage bit The resulting usage applied to the window buffers is the bitwise OR of all the valid usage flags configured with this parameter. Refer to Screen usage flag types for a complete listing of valid usage flags. one or more strings representing a valid usage bit Valid strings that are used to represent valid usage bits are: display gles2 gles3 native read rotation physical vg vulkan write The resulting usage applied to the window buffers is the bitwise OR of all the valid usage flags configured with this parameter. the name of the user-provided composition module When this configuration consists of a string that doesn't match to any valid usage bits, as a string, (see above), Screen interprets this string as the name of the composition module to use. The string you use to identify the composition module must be less than 21 characters in length and must not be all digits. Screen uses the following algorithm to determine the composition module to load: `"screen-" + <user-provided composition module> + ".so"` Note: This parameter differs from the blitter specified in the blit-config parameter under your `globals` section in graphics.conf. The blitter specified in the blit-config parameter is the blitter that Screen uses when your application explicitly calls the native blit API functions (screen_blit() and screen_fill()). How you configure this usage parameter has implications on the composition module that Screen loads and uses. For example: screen-gles2blt.so The composition module that Screen may use if the following is set: gles2blt When multiple usage flags are configured, each flag in the configuration must be separated by a comma or space. You can combine the composition module name with the usage flags in the same configuration line as long as they're separated by a comma or a space. For example, the following are examples of valid entries for configuring usage: `usage = pvr2d` `usage = sw` `usage = 2 4 8` When multiple usage flags are set, Screen determines the composition module based on the following priorities (from highest to lowest): screen-sw.so screen-`user-provided composition module`.so If usage is not set, Screen will use the following order to determine the default: Use the usage setting of the default display, if it is set. Use the blit-config setting, if it is set. Set usage to sw.	String
video-mode	The initial resolution and refresh rate for the virtual display. The resolution and refresh rate must be in the form of: `width`x`height`@i`refresh` The i indicates that interlacing is set. If video-mode is not set, Screen will use `1024x1024@60` as the default.	String	`1024x1024@60`(default)

Configure class subsection

Graphics and Screen4.0 (8.x)Screen Graphics Subsystem Developer's GuideAPIProgrammingUtilities

The class subsection specifies the default values for window properties.

Windows must be associated with a display. Therefore, include this section in your configuration file only if your system supports displays, or if there are applications on your system that require them. This class section must begin with begin class class_name and end with end class.

The class subsection is used to set default values for the window properties defined within the section; these properties are specified through parameters applied to framebuffers and application windows.

Framebuffers

The number of class subsections that can be defined for framebuffers depends on the number of displays available. Screen allows one framebuffer per display.

You can use the following convention to specify that a class subsection is used for a framebuffer:

framebufferunique_string

The class_name of the class subsection must start with the string framebuffer, then followed by a unique string to identify the class. For example, some valid class name strings are:

framebuffer
framebuffer1
framebufferA
etc.

Below is an example of using multiple class subsections to specify default values for two framebuffers, each for a specific pipeline:

begin class framebuffer1
   pipeline = 1
   display = 1
   format = rgba8888
   usage = pvr2d
   id_string = fb1
end class

begin class framebuffer2
   pipeline = 2
   display = 2
   format = rgba8888
   usage = pvr2d
   id_string = fb2
end class

Application windows

There's no explicit limit on the number of class subsections that can be defined for configuring application windows.

The class_name of the class subsection must be a unique string. This string must also match the window property, SCREEN_PROPERTY_CLASS, that you set in your application.

Below is an example of using a class subsection to specify defaults for an application window:

begin class my_app_properties
  visible = true
  surface-size = 640x480
  source-position = 0,0
  source-size = 640x480
  window-position = 0,0
  window-size = 640x480
end class

If you use the above class subsection in your configuration file, then you need to set the SCREEN_PROPERTY_CLASS window property in your application code. The setting of this property triggers Screen to apply the configured values that are associated with that class to your application window.

For example, if you use the above class section in your configuration file, you can use this in your application code:

...
const char *my_win_class = "my_app_properties";
screen_set_window_property_cv(screen_win, SCREEN_PROPERTY_CLASS,
                              strlen(my_win_class), my_win_class);
...

instead of this:

...
const int visible = 1
const int buffer_size[2] = { 640, 480};
const int src_pos[2] = { 0, 0};
const int src_size[2] = { 640, 480};
const int win_pos[2] = { 0, 0};
const int win_size[2] = { 640, 480};
screen_set_window_property_iv(screen_win, SCREEN_PROPERTY_VISIBLE, &visible);
screen_set_window_property_iv(screen_win, SCREEN_PROPERTY_BUFFER_SIZE, buffer_size);
screen_set_window_property_iv(screen_win, SCREEN_PROPERTY_SOURCE_POSITION, src_pos);
screen_set_window_property_iv(screen_win, SCREEN_PROPERTY_SOURCE_SIZE, src_size);
screen_set_window_property_iv(screen_win, SCREEN_PROPERTY_POSITION, win_pos);
screen_set_window_property_iv(screen_win, SCREEN_PROPERTY_SIZE, win_size);
...

to set your window properties.

Note:

Properties that can be set only when SCREEN_PROPERTY_SELF_LAYOUT has been enabled are referred to as layout-related properties. These properties (and the SCREEN_PROPERTY_SELF_LAYOUT property) of application windows are set by their manager. See SCREEN_PROPERTY_SELF_LAYOUT from Screen property types for more information on layout-related properties.

Application windows can set their layout-related properties only in the following cases:

if there isn't a manager on the system, or
if the manager has enabled the SCREEN_PROPERTY_SELF_LAYOUT for those application windows.

However, when applications windows set their SCREEN_PROPERTY_CLASS property using a predefined class from graphics.conf, all the properties configured in that predefined class are applied.

From the above example, the class, "my_app_properties", configures (among others) the following parameters:

visible
window-position
window-size

These parameters change layout-related properties. In this case, they're configured in a predefined class ("my_app_properties") in graphics.conf. Therefore, they're applied when, at runtime, the application window sets its SCREEN_PROPERTY_CLASS property to "my_app_properties".

If there is a manager running on the system, it will be notified of these property changes.

Parameters

The following are valid parameters that can be configured under the class subsection:


Parameter	Description	Type	Possible value(s)
alpha-mode	The method of alpha blending to use for alpha compositing.	String	`non-pre-multiplied` (default) Uses straight RGBA pixel value. For example, (0, 1, 0, 0.5) is green with 100% intensity and 50% opacity `pre-multiplied` Uses pre-multiplied RGBA pixel value. For example, a non-pre-multiplied value of (0, 1, 0, 0.5) can be interpreted as (0, 1, 0) * 0.5, giving a pre-multiplied value of (0, 0.5, 0, 0.5), where 0.5 is green with 100% intensity and 50% opacity
brightness	The brightness of a window. This configuration depends on the hardware. That is, the brightness can be configured, but whether or not it takes effect is determined by your hardware.	Integer	-255 to 255
buffer-count	The number of buffers that are to be created or attached to a window (can only be set on the framebuffers). Beyond configuration, you can't set the buffer count; you can only query it. There's no explicit limit for this count. The default is 3.	Integer	Example: `3`
buffer-size	The width and height of the window buffer. This configuration must be in the form `width`x`height`.	String	Example: `100x100`
cbabc	Content-based automatic brightness control; specifies the content type of a window. This configuration depends on the hardware. That is, cbabc can be configured, but whether or not it takes effect is determined by your hardware.	String	`none` `video` `ui` `photo`
clip-position	The x- and y- position of a clipped rectangular viewport within the window buffers. This configuration must be in the form `x-position`,`y-position`.	String	Example:`100,100`
clip-size	The width and height (in pixels) of a clipped rectangular viewport within the window buffers. This configuration must be in the form `width`x`height`.	String	Example: `100x100`
color	The background color of a window. Use RGB color code (hexadecimal value) to identify the color. (e.g., opaque blue = 0xff0000ff). For framebuffers, window background color is set using the following: When color is not set, background and background-alpha, of the display associated with the framebuffer, are assigned to the framebuffer's SCREEN_PROPERTY_COLOR. Setting color will override any previously assigned background color. This includes the values of background and background-alpha. The value of color is assigned to the framebuffer's SCREEN_PROPERTY_COLOR. If color and background/background-alpha are not set, then SCREEN_PROPERTY_COLOR is assigned opaque black (`0xff000000`).	Integer (hex)	`0xffcfcfcf` (default for a buffered window: opaque grey) `0x00cfcfcf` (default for a bufferless window: transparent grey) `0xff000000` (default for a framebuffered window: opaque black)
contrast	The contrast adjustment of a window. This configuration depends on the hardware; it can be configured, but may or may not take effect as determined by your hardware.	Integer	-128 to 127
display	The connection type to the display or the display on which the window will be shown. If the configuration is an integer, Screen interprets it as the ID of the display. Otherwise, if the configuration is a string that matches one of the valid display connection types, then Screen interprets the string as the display connection type.	String or Integer	`internal` `composite` `svideo` `YPbPr` `rgb` `rgbhv` `dvi` `hdmi` `1..2`
format	The pixel format used by a window. Only one format is expected; this format must be supported by the display. You can configure the value for format as either a string or integer; as an integer, the value can be expressed in decimal, hexadecimal, or octal. Some platform-specific formats can only be specified as an integer.	String or Integer	`byte` (default) `rgba4444` `rgbx4444` `rgba5551` `rgbx5551` `rgb565` `rgb888` `rgba8888` `rgbx8888` `yvu9` `yuv420` `nv12` `yv12` `uyvy` `yuy2` `v422` `ayuv`
global-alpha	The global alpha mode to apply to a window	Integer	0 to 225
hue	The hue adjustment of a window	Integer	-128 to 127
id_string id-string	A string to identify the contents of a window	String
interval swap_interval swap-interval	The minimum number of vsync periods between posts	Integer	0 to 255
order z-order	The z-order of a window. It's the distance from the bottom that's used when ordering windows and window groups amongst each other.	Integer
permissions	The permissions applied to a window. You can set multiple permissions by separating each valid permission by a comma. See "Permissions and Privileges" for valid permission strings.	String
pipeline	The pipeline identifier that you want to be used with a window of this class. This identifier must be a valid pipeline that's associated to the display. Valid pipelines that can be associated to the display are driver-specific. Note: Screen's application of your pipeline specification may be affected based on your configuration of the following display configuration parameters: force-composition strict-pipelines	Integer
rotation	The clockwise rotation, in degrees, of a window. Window rotation is absolute.	Integer	`0` `90` `180` `270`
saturation	The saturation adjustment of a window	Integer	-128 to 127
self-layout	The capability of a window's owner to set properties that usually can be set only by its manager. When self-layout is set to true, then a window's owner can set the following window properties: SCREEN_PROPERTY_CLIP_POSITION SCREEN_PROPERTY_CLIP_SIZE SCREEN_PROPERTY_DISPLAY SCREEN_PROPERTY_PIPELINE SCREEN_PROPERTY_POSITION SCREEN_PROPERTY_SIZE SCREEN_PROPERTY_VISIBLE SCREEN_PROPERTY_ZORDER	String	`true` `false`
sensitivity	The sensitivity that a window has to input events (e.g., touch, pointer). The sensitivity is comprised of one or more strings representing valid sensitivity masks. Valid strings are: always clipped continue finger_brush fullscreen never no_focus overdrive pointer_brush stop stylus_brush When multiple sensitivity masks are configured, each mask in the configuration must be separated by a comma or space (e.g., `sensitivity = no_focus, fullscreen`). The resulting sensitivity applied to the window is the bitwise OR of all the valid sensitivity masks that are configured with this parameter. If you don't specify this sensitivity parameter in your configuration file, Screen defaults to behaving as follows: Pointer and multi-touch events are forwarded to the window's context if they intersect with the window and are in an area of the window that's not fully transparent. The window receives keyboard, gamepad, joystick events if it has input focus. Raising a window, pointer, or multi-touch release event in the window causes it to acquire input focus.	String	`always` Set SCREEN_SENSITIVITY_MASK_ALWAYS. You can't simultaneously configure `always` and `never`. `clipped` Set SCREEN_SENSITIVITY_MASK_CLIPPED. `continue` Set SCREEN_SENSITIVITY_MASK_CONTINUE. You can't simultaneously configure `continue` and `stop`. `finger_brush` Set SCREEN_SENSITIVITY_MASK_FINGER_BRUSH. `fullscreen` Set SCREEN_SENSITIVITY_MASK_FULLSCREEN. `never` Set SCREEN_SENSITIVITY_MASK_NEVER. You can't simultaneously configure `never` and `always`. `no_focus` Set SCREEN_SENSITIVITY_MASK_NO_FOCUS. `overdrive` Set SCREEN_SENSITIVITY_MASK_OVERDRIVE. `pointer_brush` Set SCREEN_SENSITIVITY_MASK_POINTER_BRUSH. `stop` Set SCREEN_SENSITIVITY_MASK_STOP. You can't simultaneously configure `stop` and `continue`. `stylus_brush` Set SCREEN_SENSITIVITY_MASK_STYLUS_BRUSH.
sensitivity-threshold	The input sensitivity alpha threshold. Specify the sensitivity threshold as an integer in the range [0..255] (0 is the default). When you set the sensitivity threshold, the alpha component of the selected pixel will be compared to this sensitivity threshold. If the alpha is less than or equal to the threshold, the input event will be treated as transparent. Otherwise, if the alpha is greater than the threshold, the input event will be consumed. When you're using formats which have alpha components that don't span the full range [0..255], ensure that you set appropriate upscaled sensitivity threshold values. If you're setting both sensitivity and sensitivity-threshold configuration parameters, note that sensitivity takes priority over your sensitivity-threshold setting.	Integer	`0` (default)
source-position	The x and y coordinates of the top-left corner of a rectangular region within the window buffer that represents the source viewport of a window. This is the portion of the window buffer that's to be displayed. This configuration must be in the form `x-position`,`y-position`.	String	Example: `100,100`
source-size	The width and height (in pixels) of a region within the window buffer that represents the source viewport of the window. This is the portion of the window buffer that's to be displayed. This configuration must be in the form `width`x`height`.	String	Example: `100x100`
static	The indicator of whether the contents of a window are expected to change	Integer	`0` Window content isn't static. `1` Window content is static.
surface-size	Deprecated. Use buffer-size instead.
usage	The intended usage for the window buffers and/or the composition module (can only be set on the framebuffers). You can configure this parameter using any combination of the following: one or more integers representing a valid usage bit The resulting usage applied to the window buffers is the bitwise OR of all the valid usage flags configured with this parameter. Refer to Screen usage flag types for a complete listing of valid usage flags. one or more strings representing a valid usage bit. Valid strings that are used to represent valid usage bits are: display gles2 gles3 native read rotation physical vg vulkan write The resulting usage applied to the window buffers is the bitwise OR of all the valid usage flags configured with this parameter. the name of the user-provided composition module. When this configuration consists of a string that doesn't match to any valid usage bits, as a string, (see above), Screen interprets this string as the name of the composition module to use. The string you use to identify the composition module must be less than 21 characters in length and must not be all digits. Screen uses the following algorithm to determine the composition module to load: `"screen-" + <user-provided composition module> + ".so"` Note: This parameter differs from the blitter specified in the blit-config parameter under your `globals` section in graphics.conf. The blitter specified in the blit-config parameter is the blitter that Screen uses when your application explicitly calls the native blit API functions (screen_blit() and screen_fill()). How you configure this usage parameter has implications on the composition module that Screen loads and uses. For example: screen-gles2blt.so The composition module that Screen may use if the following is set: gles2blt When multiple usage flags are configured, each flag in the configuration must be separated by a comma or space. You can combine the composition module name with the usage flags in the same configuration line as long as they're separated by a comma or a space. For example, the following are examples of valid entries for configuring usage: `usage = pvr2d` `usage = sw` `usage = 2 4 8` When multiple usage flags are set, Screen determines the composition module based on the following priorities (from highest to lowest): screen-sw.so screen-`user-provided composition module`.so	String
visible	The indicator of whether or not a window is visible	String	`true` (visible) `false` (not visible)
window-position	The x and y positions of the window screen coordinates. Remember that the position of child and embedded windows are relative to the parent window. For example, if the position of the application window is (10, 10) and the position of the child window is (10, 10), then the position of the child window on the screen is actually (20, 20). This configuration must be in the form `x-position`,`y-position`.	String	Example:`10,10`
window-size size	The width and height (in pixels) of a window. This configuration must be in the form `width`x`height`.	String	Example: `100x100`

Apply your Screen configuration

Graphics and Screen4.0 (8.x)Screen Graphics Subsystem Developer's GuideAPIProgrammingUtilities

The following procedure describes how to apply your Screen configuration by using a command-line interface.

Screen processes the configuration file, graphics.conf, only when Screen services (screen) starts.

If your target system allows it, you can modify the configuration file and use the following procedure to apply your new configuration. Otherwise, you need to make your modifications to graphics.conf on your host, and then build it into your OS image. When your target boots with the new IFS, and screen starts, your new configuration takes effect.

Prior to starting this procedure, ensure the following:

Your target hardware is running the QNX OS.
You can run a shell and commands, such as pidin.
You've modified graphics.conf with your desired configuration.

To apply your Screen configuration:

Stop screen by using the following command:
slay screen
Verify that your screen process has stopped. Run:
pidin -p screen
and verify that the screen process isn't running.
Optional: If you haven't already, set the LD_LIBRARY_PATH environment variable to include the directories of the shared libraries that Screen needs.
```
export LD_LIBRARY_PATH=:/lib:/usr/lib:/lib/dll:/proc/boot
```
Restart screen by running screen.
Verify that there were no warnings generated from your new configuration by running slog2info.
See the Debugging section for more information.

Page updated: August 09, 2024