output configuration representation

An output device describes a display device available to the compositor. output_device is similar to wl_output, but focuses on output configuration management.

A client can query all global output_device objects to enlist all available display devices, even those that may currently not be represented by the compositor as a wl_output.

The client sends configuration changes to the server through the outputconfiguration interface, and the server applies the configuration changes to the hardware and signals changes to the output devices accordingly.

This object is published as global during start up for every available display devices, or when one later becomes available, for example by being hotplugged via a physical connector.

Warning! The protocol described in this file is a desktop environment implementation detail. Regular clients must not use this protocol. Backward incompatible changes may be added without bumping the major version of the extension.

geometry(x: int, y: int, physical_width: int, physical_height: int, subpixel: int, make: string, model: string, transform: int)
Argument
Type
Description
xint
x position within the global compositor space
yint
y position within the global compositor space
physical_widthint
width in millimeters of the output
physical_heightint
height in millimeters of the output
subpixelint
subpixel orientation of the output
makestring
textual description of the manufacturer
modelstring
textual description of the model
transformint
transform that maps framebuffer to output
geometric properties of the output

The geometry event describes geometric properties of the output. The event is sent when binding to the output object and whenever any of the properties change.

current_mode(mode: object<kde_output_device_mode_v2>)
Argument
Type
Description
modeobject<kde_output_device_mode_v2>
current mode

This event describes the mode currently in use for this head. It is only sent if the output is enabled.

Argument
Type
Description
modenew_id<kde_output_device_mode_v2>
advertise available output modes and current one

The mode event describes an available mode for the output.

When the client binds to the output_device object, the server sends this event once for every available mode the output_device can be operated by.

There will always be at least one event sent out on initial binding, which represents the current mode.

Later if an output changes, its mode event is sent again for the eventual added modes and lastly the current mode. In other words, the current mode is always represented by the latest event sent with the current flag set.

The size of a mode is given in physical hardware units of the output device. This is not necessarily the same as the output size in the global compositor space. For instance, the output may be scaled, as described in kde_output_device_v2.scale, or transformed, as described in kde_output_device_v2.transform.

done()
sent all information about output

This event is sent after all other properties have been sent on binding to the output object as well as after any other output property change have been applied later on. This allows to see changes to the output properties as atomic, even if multiple events successively announce them.

scale(factor: fixed)
Argument
Type
Description
factorfixed
scaling factor of output
output scaling properties

This event contains scaling geometry information that is not in the geometry event. It may be sent after binding the output object or if the output scale changes later. If it is not sent, the client should assume a scale of 1.

A scale larger than 1 means that the compositor will automatically scale surface buffers by this amount when rendering. This is used for high resolution displays where applications rendering at the native resolution would be too small to be legible.

It is intended that scaling aware clients track the current output of a surface, and if it is on a scaled output it should use wl_surface.set_buffer_scale with the scale of the output. That way the compositor can avoid scaling the surface, and the client can supply a higher detail image.

edid(raw: string)
Argument
Type
Description
rawstring
base64-encoded EDID string
advertise EDID data for the output

The edid event encapsulates the EDID data for the outputdevice.

The event is sent when binding to the output object. The EDID data may be empty, in which case this event is sent anyway. If the EDID information is empty, you can fall back to the name et al. properties of the outputdevice.

enabled(enabled: int)
Argument
Type
Description
enabledint
output enabled state
output is enabled or disabled

The enabled event notifies whether this output is currently enabled and used for displaying content by the server. The event is sent when binding to the output object and whenever later on an output changes its state by becoming enabled or disabled.

uuid(uuid: string)
Argument
Type
Description
uuidstring
output devices ID
A unique id for this outputdevice

The uuid can be used to identify the output. It's controlled by the server entirely. The server should make sure the uuid is persistent across restarts. An empty uuid is considered invalid.

serial_number(serialNumber: string)
Argument
Type
Description
serialNumberstring
textual representation of serial number
Serial Number

Serial ID of the monitor, sent on startup before the first done event.

eisa_id(eisaId: string)
Argument
Type
Description
eisaIdstring
textual representation of EISA identifier
EISA ID

EISA ID of the monitor, sent on startup before the first done event.

Argument
Type
Description
flagsuint<kde_output_device_v2.capability>
capability flags

What capabilities this device has, sent on startup before the first done event.

overscan(overscan: uint)
Argument
Type
Description
overscanuint
amount of overscan of the monitor
overscan

Overscan value of the monitor in percent, sent on startup before the first done event.

Argument
Type
Description
vrr_policyuint<kde_output_device_v2.vrr_policy>
Variable Refresh Rate Policy

What policy the compositor will employ regarding its use of variable refresh rate.

Argument
Type
Description
rgb_rangeuint<kde_output_device_v2.rgb_range>
RGB range

What rgb range the compositor is using for this output

name(name: string)
Argument
Type
Description
namestring
Output's name

Name of the output, it's useful to cross-reference to an zxdg_output_v1 and ultimately QScreen

high_dynamic_range(hdr_enabled: uint)
Argument
Type
Description
hdr_enableduint
1 if enabled, 0 if disabled
if HDR is enabled

Whether or not high dynamic range is enabled for this output

sdr_brightness(sdr_brightness: uint)
Argument
Type
Description
sdr_brightnessuint
the brightness of sdr if hdr is enabled

If high dynamic range is used, this value defines the brightness in nits for content that's in standard dynamic range format. Note that while the value is in nits, that doesn't necessarily translate to the same brightness on the screen.

wide_color_gamut(wcg_enabled: uint)
Argument
Type
Description
wcg_enableduint
1 if enabled, 0 if disabled
if WCG is enabled

Whether or not the use of a wide color gamut is enabled for this output

describes when auto rotate is used
icc_profile_path(profile_path: string)
Argument
Type
Description
profile_pathstring
describes when auto rotate is used
brightness_metadata(max_peak_brightness: uint, max_frame_average_brightness: uint, min_brightness: uint)
Argument
Type
Description
max_peak_brightnessuint
in nits
max_frame_average_brightnessuint
in nits
min_brightnessuint
in 0.0001 nits
metadata about the screen's brightness limits
brightness_overrides(max_peak_brightness: int, max_average_brightness: int, min_brightness: int)
Argument
Type
Description
max_peak_brightnessint
-1 for no override, positive values are the brightness in nits
max_average_brightnessint
-1 for no override, positive values are the brightness in nits
min_brightnessint
-1 for no override, positive values are the brightness in 0.0001 nits
overrides for the screen's brightness limits
sdr_gamut_wideness(gamut_wideness: uint)
Argument
Type
Description
gamut_widenessuint
0 means rec.709 primaries, 10000 means native primaries
describes which gamut is assumed for sRGB applications

This can be used to provide the colors users assume sRGB applications should have based on the default experience on many modern sRGB screens.

describes which source the compositor uses for the color profile on an output
brightness(brightness: uint)
Argument
Type
Description
brightnessuint
brightness in 0-10000
brightness multiplier

This is the brightness modifier of the output. It doesn't specify any absolute values, but is merely a multiplier on top of other brightness values, like sdr_brightness and brightness_metadata. 0 is the minimum brightness (not completely dark) and 10000 is the maximum brightness. This is currently only supported / meaningful while HDR is active.

subpixel geometry information

This enumeration describes how the physical pixels on an output are laid out.

transform from framebuffer to output

This describes the transform, that a compositor will apply to a surface to compensate for the rotation or mirroring of an output device.

The flipped values correspond to an initial flip around a vertical axis followed by rotation.

The purpose is mainly to allow clients to render accordingly and tell the compositor, so that for fullscreen surfaces, the compositor is still able to scan out directly client surfaces.

Argument
Value
Description
overscan0x1
if this output_device can use overscan
vrr0x2
if this outputdevice supports variable refresh rate
rgb_range0x4
if setting the rgb range is possible
high_dynamic_rangesince 30x8
if this outputdevice supports high dynamic range
wide_color_gamutsince 30x10
if this outputdevice supports a wide color gamut
auto_rotatesince 40x20
if this outputdevice supports autorotation
icc_profilesince 50x40
if this outputdevice supports icc profiles
brightnesssince 90x80
if this outputdevice supports the brightness setting
describes capabilities of the outputdevice

Describes what capabilities this device has.

vrr_policy { never, always, automatic } 
Argument
Value
Description
never0
always1
automatic2
describes vrr policy

Describes when the compositor may employ variable refresh rate

rgb_range { automatic, full, limited } 
Argument
Value
Description
automatic0
full1
limited2
describes RGB range policy

Whether full or limited color range should be used

auto_rotate_policy { never, in_tablet_mode, always } 
Argument
Value
Description
never0
in_tablet_mode1
always2
describes when auto rotate should be used
color_profile_source { sRGB, ICC, EDID } 
Argument
Value
Description
sRGB0
ICC1
EDID2
which source the compositor should use for the color profile on an output

output mode

This object describes an output mode.

Some heads don't support output modes, in which case modes won't be advertised.

Properties sent via this interface are applied atomically via the kde_output_device.done event. No guarantees are made regarding the order in which properties are sent.

size(width: int, height: int)
Argument
Type
Description
widthint
width of the mode in hardware units
heightint
height of the mode in hardware units
mode size

This event describes the mode size. The size is given in physical hardware units of the output device. This is not necessarily the same as the output size in the global compositor space. For instance, the output may be scaled or transformed.

refresh(refresh: int)
Argument
Type
Description
refreshint
vertical refresh rate in mHz
mode refresh rate

This event describes the mode's fixed vertical refresh rate. It is only sent if the mode has a fixed refresh rate.

preferred()
mode is preferred

This event advertises this mode as preferred.

removed()
the mode has been destroyed

The compositor will destroy the object immediately after sending this event, so it will become invalid and the client should release any resources associated with it.


Compositor Support

Mutter
Mutter
46
KWin
KWin
6.2
Sway
Sway
1.9
COSMIC
COSMIC
1.0.0
Hyprland
Hyprland
0.42.0
niri
0.1.8
Weston
Weston
13
Mir
Mir
2.19
GameScope
GameScope
3.15.14
Jay
1.7.0
kde_output_device_v2
x
9
x
x
x
x
x
x
x
x

SPDX-FileCopyrightText: 2008-2011 Kristian Høgsberg SPDX-FileCopyrightText: 2010-2011 Intel Corporation SPDX-FileCopyrightText: 2012-2013 Collabora, Ltd. SPDX-FileCopyrightText: 2015 Sebastian Kügler <sebas@kde.org> SPDX-FileCopyrightText: 2021 Méven Car <meven.car@enioka.com>

SPDX-License-Identifier: MIT-CMU