kde_output_device_v2 protocol
kde_output_device_v2 interface version 2
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.
Events
geometry since version 0
geometry(x int, y int, physical_width int, physical_height int, subpixel int, make string, model string, transform int)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.
Arguments
| Name | Type | Description |
|---|---|---|
| x | int | x position within the global compositor space |
| y | int | y position within the global compositor space |
| physical_width | int | width in millimeters of the output |
| physical_height | int | height in millimeters of the output |
| subpixel | int | subpixel orientation of the output |
| make | string | textual description of the manufacturer |
| model | string | textual description of the model |
| transform | int | transform that maps framebuffer to output |
current_mode since version 0
current_mode(mode object[kde_output_device_mode_v2])This event describes the mode currently in use for this head. It is only sent if the output is enabled.
Arguments
| Name | Type | Description |
|---|---|---|
| mode | object[kde_output_device_mode_v2] |
mode since version 0
mode(mode new_id[kde_output_device_mode_v2])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.
Arguments
| Name | Type | Description |
|---|---|---|
| mode | new_id[kde_output_device_mode_v2] |
done since version 0
done()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 since version 0
scale(factor fixed)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.
Arguments
| Name | Type | Description |
|---|---|---|
| factor | fixed | scaling factor of output |
edid since version 0
edid(raw string)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.
Arguments
| Name | Type | Description |
|---|---|---|
| raw | string | base64-encoded EDID string |
enabled since version 0
enabled(enabled int)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.
Arguments
| Name | Type | Description |
|---|---|---|
| enabled | int | output enabled state |
uuid since version 0
uuid(uuid string)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.
Arguments
| Name | Type | Description |
|---|---|---|
| uuid | string | output devices ID |
serial_number since version 0
serial_number(serialNumber string)Serial ID of the monitor, sent on startup before the first done event.
Arguments
| Name | Type | Description |
|---|---|---|
| serialNumber | string | textual representation of serial number |
eisa_id since version 0
eisa_id(eisaId string)EISA ID of the monitor, sent on startup before the first done event.
Arguments
| Name | Type | Description |
|---|---|---|
| eisaId | string | textual representation of EISA identifier |
capabilities since version 0
capabilities(flags uint)What capabilities this device has, sent on startup before the first done event.
Arguments
| Name | Type | Description |
|---|---|---|
| flags | uint |
overscan since version 0
overscan(overscan uint)Overscan value of the monitor in percent, sent on startup before the first done event.
Arguments
| Name | Type | Description |
|---|---|---|
| overscan | uint | amount of overscan of the monitor |
vrr_policy since version 0
vrr_policy(vrr_policy uint)What policy the compositor will employ regarding its use of variable refresh rate.
Arguments
| Name | Type | Description |
|---|---|---|
| vrr_policy | uint |
rgb_range since version 0
rgb_range(rgb_range uint)What rgb range the compositor is using for this output
Arguments
| Name | Type | Description |
|---|---|---|
| rgb_range | uint |
name since version 2
name(name string)Name of the output, it's useful to cross-reference to an zxdg_output_v1 and ultimately QScreen
Arguments
| Name | Type | Description |
|---|---|---|
| name | string |
Enums
subpixel since version 0
This enumeration describes how the physical pixels on an output are laid out.
enum subpixel {
unknown = 0,
none = 1,
horizontal_rgb = 2,
horizontal_bgr = 3,
vertical_rgb = 4,
vertical_bgr = 5,
}Entries
| Name | Value | Description |
|---|---|---|
| unknown | 0 | |
| none | 1 | |
| horizontal_rgb | 2 | |
| horizontal_bgr | 3 | |
| vertical_rgb | 4 | |
| vertical_bgr | 5 |
transform since version 0
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.
enum transform {
normal = 0,
90 = 1,
180 = 2,
270 = 3,
flipped = 4,
flipped_90 = 5,
flipped_180 = 6,
flipped_270 = 7,
}Entries
| Name | Value | Description |
|---|---|---|
| normal | 0 | |
| 90 | 1 | |
| 180 | 2 | |
| 270 | 3 | |
| flipped | 4 | |
| flipped_90 | 5 | |
| flipped_180 | 6 | |
| flipped_270 | 7 |
Flagset capability since version 0
Describes what capabilities this device has.
enum capability {
overscan = 1,
vrr = 2,
rgb_range = 4,
}Entries
| Name | Value | Description |
|---|---|---|
| overscan | 1 | if this output_device can use overscan |
| vrr | 2 | if this outputdevice supports variable refresh rate |
| rgb_range | 4 | if setting the rgb range is possible |
vrr_policy since version 0
Describes when the compositor may employ variable refresh rate
enum vrr_policy {
never = 0,
always = 1,
automatic = 2,
}Entries
| Name | Value | Description |
|---|---|---|
| never | 0 | |
| always | 1 | |
| automatic | 2 |
rgb_range since version 0
Whether full or limited color range should be used
enum rgb_range {
automatic = 0,
full = 1,
limited = 2,
}Entries
| Name | Value | Description |
|---|---|---|
| automatic | 0 | |
| full | 1 | |
| limited | 2 |
kde_output_device_mode_v2 interface version 1
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.
Events
size since version 0
size(width int, height int)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.
Arguments
| Name | Type | Description |
|---|---|---|
| width | int | width of the mode in hardware units |
| height | int | height of the mode in hardware units |
refresh since version 0
refresh(refresh int)This event describes the mode's fixed vertical refresh rate. It is only sent if the mode has a fixed refresh rate.
Arguments
| Name | Type | Description |
|---|---|---|
| refresh | int | vertical refresh rate in mHz |
preferred since version 0
preferred()This event advertises this mode as preferred.
removed since version 0
removed()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.
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