Configuring Screen

Updated: May 27, 2022

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 (e.g., armle-v7), 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
  • 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

or

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:
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 hdmi
    formats = rgba8888 rgbx8888 nv12
    video-mode = 1280 x 720 @ 60
  end display

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

Configure khronos section

Updated: May 27, 2022

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

Updated: May 27, 2022

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

Updated: May 27, 2022

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, e.g., armle-v7) and platform is the name of your target's platform (e.g., imx6x).

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

Updated: May 27, 2022

The winmgr section specifies the parameters related to Screen.

Your graphics.conf configuration file must include a winmgr section where your global, 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 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.

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

Updated: May 27, 2022

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
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 a port number, or you can specify a string value.

This parameter is valid only if your system supports displays.

Integer A numeric value specifying the port number or one of these string values:
  • composite
  • svideo
  • YPbPr
  • rgb
  • rgbhv
  • dvi
  • hdmi
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 of all keymap files and/or the name of the default keymap file to use when a new keyboard device is created. This parameter is applicable only to HID keyboards. This parameter is optional. If keymap isn't set, then Screen uses /usr/share/keyboard/en_US_101. String /usr/share/keyboard/en_US_101 (default)
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  
stack-size The stack size (in units of bytes) that Screen is to use for its 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

Updated: May 27, 2022

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 can be a number identifying the display, or it can be the connection type of the display.

If the display_id is an integer, Screen applies the configuration parameters to the display whose ID is that specified by display_id. Otherwise, if the display_id is a string that matches one of the valid display connection types, then Screen applies the configuration parameters to the first available display whose connection type matches that specified by the display_id.

Below is an example of a display subsection of a graphics.conf file. In this example, the display_id is a connection type of hdmi; therefore, the configuration parameters are applied to the first available display that supports hdmi:

begin display hdmi
   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

rgbx5111

rgb565

rgb888

rgba8888

rgbx8888

yvu9

yuv420

nv12

yv12

uyvy

yuy2

v422

ayuv

gamma The gamma value of the WFD driver. The range for this gamma value is specific to the driver. Integer 0 to 255
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 identifier 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)

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 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.
touch-adjustments The x and y adjustments to be added to all touch events. This configuration must be in the form: x-adjustment,y-adjustment String Example: 10,10
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:

widthxheight@irefresh

The i indicates that interlacing is set.

String video-mode = 1280x720@60

Configure class subsection

Updated: May 27, 2022

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 widthxheight. 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 widthxheight. 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

rgbx5111

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 A string to identify the contents of a window String  
interval The minimum number of vsync periods between posts Integer 0 to 255
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:
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 widthxheight. 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:
    • gles1
    • gles2
    • gles3
    • native
    • read
    • rotation
    • vg
    • 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:

screen-gles1.so
The composition module that Screen may use if at least one of the following is set:
  • gles1
  • 16 (SCREEN_USAGE_OPENGL_ES1)
screen-gles2.so
The composition module that Screen may use if at least one of the following is set:
  • gles2
  • 32 (SCREEN_USAGE_OPENGL_ES2)
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
  • screen-gles1.so
  • screen-gles2.so
For example, if your usage configuration is: usage = gles1 2 pvr2d, you're specifying a user-provided composition module pvr2d, as well as setting the following usage flags:
  • SCREEN_USAGE_OPENGL_ES1
  • SCREEN_USAGE_READ
Screen loads screen-sw.so as the composition module according to its priorities. Although the user-provided composition module (screen-pvr2d.so) takes precedence over the gles1 module (screen-gles1.so), the usage flag SCREEN_USAGE_READ is set. This flag causes Screen to use the screen-sw.so composition module—which has an even higher priority than the user-provided composition module.
String
gles1
OpenGL ES 1.X is used for rendering the buffer(s) associated with the window
gles2
OpenGL ES 2.X is used for rendering the buffer(s) associated with the window
gles3
OpenGL ES 3.X is used for rendering the buffer(s) associated with the window
native
Buffer(s) associated with the window can be used for native API operations. For example, if your application explicitly calls ( screen_blit() and/or screen_fill()), then this flag must be set.
rotation
Buffer(s) associated with the window can be reconfigured from landscape to portrait orientation without having the need for reallocation.
read
Buffer(s) associated with the window can be read from.
vg
OpenVG is used for rendering the buffer(s) associated with the window
write
Buffer(s) associated with the window can be written to.
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 The width and height (in pixels) of a window. This configuration must be in the form widthxheight. String

Example: 100x100

Apply your Screen configuration

Updated: May 27, 2022

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 Neutrino RTOS.

  • You can run a shell and commands, such as pidin.

  • You've modified graphics.conf with your desired configuration.
To apply your Screen configuration:
  1. Stop screen by using the following command:

    slay screen

  2. Verify that your screen process has stopped. Run:
    pidin -p screen

    and verify that the screen process isn't running.

  3. 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
                        
  4. Restart screen by running screen.
  5. Verify that there were no warnings generated from your new configuration by running slog2info.

    See the Debugging section for more information.