KDE output management v2

Configuration of server outputs through clients

This interface enables clients to set properties of output devices for screen configuration purposes via the server. To this end output devices are referenced by global kde_output_device_v2 objects.

outputmanagement (wl_global) -------------------------- request: * create_configuration -> outputconfiguration (wl_resource)

outputconfiguration (wl_resource) -------------------------- requests: * enable(outputdevice, bool) * mode(outputdevice, mode) * transformation(outputdevice, flag) * position(outputdevice, x, y) * apply

events: * applied * failed

The server registers one outputmanagement object as a global object. In order to configure outputs a client requests create_configuration, which provides a resource referencing an outputconfiguration for one-time configuration. That way the server knows which requests belong together and can group them by that.

On the outputconfiguration object the client calls for each output whether the output should be enabled, which mode should be set (by referencing the mode from the list of announced modes) and the output's global position. Once all outputs are configured that way, the client calls apply. At that point and not earlier the server should try to apply the configuration. If this succeeds the server emits the applied signal, otherwise the failed signal, such that the configuring client is noticed about the success of its configuration request.

Through this design the interface enables atomic output configuration changes if internally supported by the server.

create_configuration(id: new_id<kde_output_configuration_v2>)
Argument
Type
Description
idnew_id<kde_output_configuration_v2>
Provide outputconfiguration object for configuring outputs

Request an outputconfiguration object through which the client can configure output devices.


Configure single output devices

outputconfiguration is a client-specific resource that can be used to ask the server to apply changes to available output devices.

The client receives a list of output devices from the registry. When it wants to apply new settings, it creates a configuration object from the outputmanagement global, writes changes through this object's enable, scale, transform and mode calls. It then asks the server to apply these settings in an atomic fashion, for example through Linux' DRM interface.

The server signals back whether the new settings have applied successfully or failed to apply. outputdevice objects are updated after the changes have been applied to the hardware and before the server side sends the applied event.

Argument
Type
Description
outputdeviceobject<kde_output_device_v2>
outputdevice to be en- or disabled
enableint
1 to enable or 0 to disable this output
Enable or disable an output

Mark the output as enabled or disabled.

Argument
Type
Description
outputdeviceobject<kde_output_device_v2>
outputdevice this mode change applies to
modeobject<kde_output_device_mode_v2>
the mode to apply
Switch output-device to mode

Sets the mode for a given output.

transform(outputdevice: object<kde_output_device_v2>, transform: int)
Argument
Type
Description
outputdeviceobject<kde_output_device_v2>
outputdevice this transformation change applies to
transformint
transform enum
Transform output-device

Sets the transformation for a given output.

position(outputdevice: object<kde_output_device_v2>, x: int, y: int)
Argument
Type
Description
outputdeviceobject<kde_output_device_v2>
outputdevice this position applies to
xint
position on the x-axis
yint
position on the y-axis
Position output in global space

Sets the position for this output device. (x,y) describe the top-left corner of the output in global space, whereby the origin (0,0) of the global space has to be aligned with the top-left corner of the most left and in case this does not define a single one the top output.

There may be no gaps or overlaps between outputs, i.e. the outputs are stacked horizontally, vertically, or both on each other.

scale(outputdevice: object<kde_output_device_v2>, scale: fixed)
Argument
Type
Description
outputdeviceobject<kde_output_device_v2>
outputdevice this scale change applies to
scalefixed
scaling factor
Set scaling factor of this output

Sets the scaling factor for this output device.

apply()
Apply configuration changes to all output devices

Asks the server to apply property changes requested through this outputconfiguration object to all outputs on the server side.

The output configuration can be applied only once. The already_applied protocol error will be posted if the apply request is called the second time.

destroy()
Release the outputconfiguration object
overscan(outputdevice: object<kde_output_device_v2>, overscan: uint)
Argument
Type
Description
outputdeviceobject<kde_output_device_v2>
outputdevice overscan applies to
overscanuint
overscan value
Set overscan value

Set the overscan value of this output device with a value in percent.

Argument
Type
Description
outputdeviceobject<kde_output_device_v2>
outputdevice this VRR policy applies to
policyuint<kde_output_configuration_v2.vrr_policy>
the vrr policy to apply
Set the VRR policy

Set what policy the compositor should employ regarding its use of variable refresh rate.

Argument
Type
Description
outputdeviceobject<kde_output_device_v2>
outputdevice the rgb range applies to
rgb_rangeuint<kde_output_configuration_v2.rgb_range>
RGB range

Whether full or limited color range should be used

set_primary_output(output: object<kde_output_device_v2>)
Argument
Type
Description
outputobject<kde_output_device_v2>allow null
Select which primary output to use
set_priority(outputdevice: object<kde_output_device_v2>, priority: uint)
Argument
Type
Description
outputdeviceobject<kde_output_device_v2>
outputdevice the index applies to
priorityuint
the priority of the output
Set the order of outputs

The order of outputs can be used to assign desktop environment components to a specific screen, see kde_output_order_v1 for details. The priority is 1-based for outputs that will be enabled after this changeset is applied, all outputs that are disabled need to have the index set to zero.

applied()
Configuration changes have been applied

Sent after the server has successfully applied the changes. .

failed()
Configuration changes failed to apply

Sent if the server rejects the changes or failed to apply them.

error { already_applied } 
Argument
Value
Description
already_applied0
the config is already applied
Kde_output_configuration_v2 error values

These error can be emitted in response to kde_output_configuration_v2 requests.

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 this output should use full or limited rgb.


Compositor Support

Mutter
Mutter
45.4
KWin
KWin
6.0.1
Sway
Sway
1.9
Hyprland
Hyprland
0.35
Weston
Weston
13
Mir
Mir
...
GameScope
GameScope
...
kde_output_management_v2
x
7
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