screen.xml file format
The screen.xml file defines how the application's graphics are rendered. It consists of a single top-level MultiHead element which contains several child elements, including one or more window elements.
Tip
See client-screen-xml for the location of the file.
Info
Refer to video-wall-examples for full examples for specific configurations.
MultiHead parameters
Parameters that can be set for the top-level <MultiHead> element.
vsync
: Set to 1 to wait for the vertical synchronization when rendering a frame to eliminate screen tearing artifacts.
On Linux this basically caps the framerate to display refresh rate, which is typically 60. All displays should have the same refresh rate for this to work properly.
On Windows this is more complicated because of DWM. Setting this to 1 can cause double vsync to occur and the framerate to drop to 30. However, in single-window setups it is typically safe to enable.
In general vsync is almost always a desirable feature since it reduces tearing, but it will introduce some input lag which might make the application feel slow to respond.
Default: 1 on Linux, 0 on Windows.
Note
Enabling vsync only helps with tearing inside displays. If you want to reduce tearing between GPUs, you might need setup frame-locking or you could try to set gl-finish to 1.
layer-size
: Defines the size of the primary content, or root layer size, in the application in graphics coordinates. In practice, this means different things depending on the application:
**Canvus**: the default workspace size is the layer-size if you haven\'t defined any fixed workspaces.
Installations that have video outputs but don\'t have any fixed workspaces, layer-size should match the area reserved for workspaces. Otherwise the default workspace will fill the whole available area, overlapping with the video outputs.
**Launcher**: the background animation is rendered only in the root layer and by default the launcher menu is centered in the root layer.
Installations that have a main wall, breakout screens and video outputs, most likely should have the layer-size match the main wall size. This way the menu is centered in the main wall and the breakout screens and video outputs won\'t display any Launcher content.
**Showcase**: different structure layers (Overlay, Menu, Main, Background) have the same size as layer-size. In practice this affects things like relative sizes and locations for child items for these structure layers. For instance adding a picture with size \"100% 100%\" under the Background layer would have the same size as layer-size in screen.xml.
If set to default (\"0 0\"), the layer-size is calculated automatically from the graphics coordinates.
Default: \"0 0\"
gl-finish
: Enabling this may reduce rendering latency and tearing between GPUs by eliminating frame buffering but at a cost of reduced performance. On a low level this basically specifies if glFinish should be called after every rendered frame.
Default: 0
texture-upload-method
: Specify which method to use to transfer texture data to the GPU. All different options perform the same task, but use different OpenGL techniques. There can be a significant performance difference between the options, but it all depends on the platform and driver.
Options:
- texture
- buffer-upload
- buffer-map (normally the fastest choice)
- buffer-map-nosync
- buffer-map-nosync-orphan
- 0 (same as texture)
- 1 (same as buffer-upload)
- 2 (same as buffer-map)
Default: 2 (buffer-map)
async-texture-upload
: If set to 1, some texture data will be uploaded asynchronously to the GPU using separate upload threads and OpenGL contexts. This can improve GPU upload throughput and reduce \"Render collect\" time and therefore improve performance.
This feature has caused stability issues with older Intel drivers.
Default: 1
prefetched-video-frame-count
: In video playback, the number of video frames to transfer to the GPU before they are needed. Setting this to 1 might improve application performance in certain cases, like when playing a huge video file.
Allowed values: 0 or 1.
Default: 0
Window parameters
Parameters that can be set for each element representing a window, e.g. <GPU1 type="window">.
location
: Window location in desktop coordinates. This doesn\'t affect which part of the application is rendered on this window, this just places the window on the desktop.
Origin (0, 0) is in the top-left corner of the primary display, so if you wish to place your window on a display left of the primary display, you need to use negative values (like \"-1920 0\").
On Windows, this is just the desktop location but in Linux this is relative to the X Screen origin, since all X Screens work as separate desktops with their own independent coordinate system.
Default: The window is placed on the center of the screen.
size
: Window size in desktop coordinates. Like location, this only affects the window size, it doesn\'t affect what is rendered inside the window.
Default: the size is 100% of the display in frameless mode or 80% of the display in windowed mode.
frameless
: Enable or disable frameless window mode.
Frameless window:
- Doesn\'t have borders, title bar, system menu or minimize/maximize/close buttons
- Can\'t be moved or resized
- Can\'t toggle between windowed and full-screen mode using F11
- Disables OS touch gestures on top of the window
- Frameless mode is the recommended way of configuring video wall installations.
Also see stay-on-top and bypass-window-manager.
Default: true
stay-on-top
: Window is placed on top of other windows if stay-on-top is enabled. This is almost always what you want in frameless mode.
Default: true if frameless mode is enabled, otherwise false.
bypass-window-manager
: If true, the window will bypass the window manager on Linux. This makes the application visible on all virtual desktops and also makes the window stay on top of other \"stay-on-top\" windows.
This is needed to make sure we are always on top of system notifications, menus and other windows that have \"stay-on-top\" flag enabled as well.
Default: true if frameless mode is enabled, otherwise false.
fullscreen
: If true, the size attribute is ignored and the window is put to fullscreen mode, which might mean different things on different window managers and operating systems. Typically a fullscreen window fills just one screen in a multi-display environment.
Usually frameless mode is more reliable than fullscreen mode.
Default: false
resizable
: If true, the window can be resized. This flag should not be used with frameless windows. Resizable windows can also be toggled between fullscreen and windowed mode using F11.
Default: false
fsaa-samples
: Number of samples per pixel for full-screen multisample anti-aliasing. Setting this to 0 disables multisampling and improves rendering performance with a cost of aliased rendering. Set to 4 to improve picture quality.
With HiDPI screens multisampling can be disabled or the number of samples could be reduced to 2.
If the value is negative, a default value is chosen based on the available hardware. In practice this means that with Intel GPU we disable multisampling but with everything else we use value 4.
Default: -1
direct-rendering
: If enabled, the areas inside this window are rendered directly to the window. This gives the best performance. If disabled, rendering is done using off-screen buffers that adds overhead, but is required for frame lock and area color correction to work.
If you use frame lock, set this to false.
Default: true
screennumber
: X Screen number starting from 0. The location of the window is relative to the selected X Screen.
Only used in Linux.
Default: -1 which selects the current X Screen.
gpu-affinity-mask
: Controls GPU affinity for this window. GPU affinity in practice means which GPUs render this window. Almost always the default value should work, but in case of buggy drivers or just for debugging this can be useful.
The value itself is a bitmask, where bit 0 is the first GPU, bit 1 the second etc. When a bit is on, then that GPU is selected for this window.
Only used in Windows.
Default: The mask is calculated automatically based on the window size and position.
Area parameters
Parameters that can be set for each element representing an area, e.g. <Area1 type="area">.
location
: Location of the bottom-left corner of the area relative to the bottom-left corner of the window in pixels inside the window. For legacy reasons the coordinate system has the vertical axis going up instead of down like all the other location attributes. Area with a location of (100, 100) would have its bottom left corner from 100 pixels from the left edge of the window and 100 pixels from the bottom edge of the window.
This doesn\'t affect which part of the application is rendered on this area, this just places the area on the window.
Almost always the default (0, 0) works fine, since the optimal setup is to have exactly one area per window, and it makes sense for that area to be the same size as the window.
Default: \"0 0\"
size
: Size of the area, in pixels, inside the window.
Default: size is the same as the window size.
graphicslocation
: See graphicssize below.
Default: \"0 0\"
graphicssize
: In the application virtual graphics coordinates, graphicslocation and graphicssize define the part of the application that is rendered to this area.
This doesn\'t affect where on the window the viewport is rendered, but it defines what part of the application is rendered here.
The graphics size doesn\'t need to be the same as area size or even have the same aspect ratio. The given part of the application is rendered so that it fills the whole area. Different areas can render arbitrary parts of the application, even if the parts overlap. For instance, one could have a big three window 9x3 wall running Showcase, and then one extra area in the first window with area size 900x170 and graphics size 17360x3260 to get a \"preview viewport\" of the whole application on top of the application.
However, in a typical use case the graphics size does match the area size so that we have 1:1 pixel mapping from the virtual application graphics coordinates to the window coordinates so that all the UI elements have the correct size.
Default: size is the same as the area size.