Treeland output manager v2
Warning! This protocol is EXPERIMENTAL and under active development. It may change at any time, including in backward-incompatible ways, without incrementing the interface major version and without prior notice. No compatibility guarantees of any kind are provided. Clients and compositors must track the upstream definition in treeland-protocols and must not rely on the current interface names, requests, events, or semantics remaining stable across releases.
This protocol provides two capabilities to privileged clients such as display configuration panels:
1. Designating one connected output as the primary output, which the compositor may use to decide placement of panels, notifications, and newly opened windows.
2. Adjusting the color temperature and brightness of individual outputs via a double-buffered pending/commit model.
Outputs in this protocol are addressed by opaque uuid strings instead of wl_output objects. Clients obtain the uuid of an output from the treeland-output-uuid-unstable-v1 protocol. A uuid remains stable across sessions and output reconnections, which lets clients and the compositor persist per-output settings and restore them after a restart. In the primary_output event an empty uuid means that no primary output is currently designated.
The terms "must", "must not", "should", and "may" in this document are to be interpreted as described in RFC 2119.
treeland_output_manager_v2
A singleton global that exposes two capabilities: designating the primary output and creating per-output picture control objects.
Only one client should bind this interface at a time. The compositor may not advertise this global to additional clients, or may ignore requests from them, while a binding is already active.
On binding, the compositor immediately emits a primary_output event carrying the uuid of the currently designated primary output, or an empty uuid if no primary output has been designated.
destroy()
Destroy the treeland_output_manager_v2 object.
Existing treeland_output_picture_control_v2 objects created through this manager are not affected and must be destroyed separately by the client.
set_primary_output(uuid: string)
Argument | Type | Description |
|---|---|---|
| uuid | string | uuid of an enabled output to designate as primary |
Designate the output identified by the given uuid as the primary output. The compositor uses the primary output as a hint for panel placement, initial window positioning, and other compositor-defined policies.
The uuid must identify a currently connected, enabled output. If the uuid is empty, or no enabled output with this uuid is currently connected, the compositor rejects the request and emits a primary_output_failed event with the invalid_output reason; the primary output designation is unchanged. Neither case is a protocol error, so a request carrying a stale uuid never disconnects the client.
The compositor applies a successful change immediately and confirms it by emitting a primary_output event carrying the uuid of the newly designated primary output.
get_picture_control(id: new_id<treeland_output_picture_control_v2>, uuid: string)
Argument | Type | Description |
|---|---|---|
| id | new_id<treeland_output_picture_control_v2> | new picture control object for the given output |
| uuid | string | uuid of the output to control |
Create a treeland_output_picture_control_v2 object for the output identified by the given uuid. The returned object allows the client to adjust the color temperature and brightness of that output.
The uuid must identify a currently connected, enabled output. If the uuid is empty, or no enabled output with this uuid is currently connected, the request still succeeds as long as the new object id is valid: the picture control object is created, but the compositor immediately emits a result event with the invalid_output result, without waiting for a commit. Such a uuid is not a protocol error. Once an invalid_output result has been delivered on an object, the object is permanently inert: only the destroy request is valid, and no further result, color_temperature, or brightness events are emitted on it. The object does not recover if an output with the same uuid is connected later; the client must destroy the inert object and call get_picture_control again to obtain a usable one.
Multiple picture control objects may exist for the same output at the same time; each object reports value changes independently.
primary_output(uuid: string)
Argument | Type | Description |
|---|---|---|
| uuid | string | uuid of the currently designated primary output, or empty when none is available |
Emitted by the compositor to report the uuid of the current primary output. This event is sent once immediately after the client binds this interface, and again whenever the primary output designation changes — whether in response to a set_primary_output request or through a compositor-driven fallback.
When the designated primary output is disconnected or disabled, the compositor automatically selects another available output as the new primary and emits this event with its uuid. When no output is currently available, the event is emitted with an empty uuid.
primary_output_failed(reason: uint<treeland_output_manager_v2.primary_output_failed_reason>)
Argument | Type | Description |
|---|---|---|
| reason | uint<treeland_output_manager_v2.primary_output_failed_reason> | why the set_primary_output request was rejected |
Emitted when a set_primary_output request cannot be applied, indicating that the primary output designation is unchanged. The reason identifies why the request was rejected: no enabled output with the provided uuid is currently connected.
primary_output_failed_reason { invalid_output }
Argument | Value | Description |
|---|---|---|
| invalid_output | 0 | the provided uuid is empty or no enabled output with this uuid is currently connected |
Reasons returned by the primary_output_failed event.
treeland_output_picture_control_v2
Represents a picture control session bound to the output identified by its uuid, created by treeland_output_manager_v2.get_picture_control.
Color temperature and brightness are managed via a double-buffered pending/commit model. The client accumulates changes with set_color_temperature and set_brightness, then atomically applies them with a single commit request. After a successful commit the compositor emits a color_temperature or brightness event for each value that actually changed.
On creation with a uuid that identifies a live enabled output, the compositor emits color_temperature and brightness events to report the current values of the output before the client has made any changes.
When the object is created for a uuid that does not identify a live enabled output, the compositor immediately emits a result event with the invalid_output result instead of the initial color_temperature and brightness events.
An invalid_output result is terminal, whether it is delivered immediately after creation or in response to a later commit: the object becomes permanently inert, only the destroy request remains valid, and no further events are emitted on it. The object never recovers, even if an output with the same uuid is connected afterwards; the client must destroy the inert object and call get_picture_control again to obtain a new one.
destroy()
Destroy the treeland_output_picture_control_v2 object and release all associated compositor resources. Any uncommitted pending settings are discarded.
After this request the compositor will no longer send result, color_temperature, or brightness events on this object.
set_color_temperature(temperature: uint)
Argument | Type | Description |
|---|---|---|
| temperature | uint | color temperature in Kelvin, in the range [1000, 20000] |
Set the pending color temperature for the output. The value is not applied until the client sends a commit request.
Valid range is [1000, 20000] Kelvin. A value outside this range is rejected immediately with the invalid_color_temperature protocol error, terminating the connection; nothing is stored in the pending state and no commit is required to clear the request.
Multiple calls before commit replace the pending value; only the last value is applied.
set_brightness(brightness: fixed)
Argument | Type | Description |
|---|---|---|
| brightness | fixed | brightness level in the range [0.0, 100.0] |
Set the pending brightness for the output. The value is not applied until the client sends a commit request.
Valid range is [0.0, 100.0]. A value outside this range is rejected immediately with the invalid_brightness protocol error, terminating the connection; nothing is stored in the pending state and no commit is required to clear the request.
Multiple calls before commit replace the pending value; only the last value is applied.
commit()
Atomically apply all pending color temperature and brightness values accumulated since the last commit. The compositor always responds with a result event indicating success or failure. After a successful commit the compositor emits a color_temperature or brightness event for each value that actually changed.
It is valid to call commit without any preceding set_* requests; the compositor treats this as a no-op that succeeds without changing any value.
A failed commit reports its cause through the result event. Range validation of pending values is performed at set_* time and never reaches a commit; a commit therefore only fails because of the output: it does not support the requested adjustment (unsupported, retrying the same settings is unlikely to succeed), the uuid no longer identifies a live enabled output (invalid_output), or the commit could not be applied for a transient or unknown reason (failed). In every failure case the applied settings remain unchanged.
An invalid_output result is terminal: it permanently invalidates the object, so only destroy may be sent afterwards and the object never recovers even if an output with the same uuid is connected again.
result(result: uint<treeland_output_picture_control_v2.commit_result>)
Argument | Type | Description |
|---|---|---|
| result | uint<treeland_output_picture_control_v2.commit_result> | whether the commit succeeded or failed, or the object was created for an invalid uuid |
Emitted by the compositor to report the outcome of a commit request, and immediately after object creation when the object was created for a uuid that does not identify a live enabled output.
In response to a commit request the event is always sent, including commits with no pending changes, to indicate whether the settings were applied. Besides the failed, unsupported, and invalid_output causes, no other result value is defined. Out-of-range pending values are rejected at set_* time with a fatal protocol error and never produce a commit result. After a successful commit, a color_temperature or brightness event is emitted for each value that actually changed.
An invalid_output result is terminal: once it is delivered, the object is permanently inert, only the destroy request remains valid, and no further events are emitted on it. The object never recovers, even if an output with the same uuid is connected afterwards; the client must destroy the object and call get_picture_control again.
color_temperature(temperature: uint)
Argument | Type | Description |
|---|---|---|
| temperature | uint | current color temperature in Kelvin |
Reports the currently applied color temperature of the output. When the object is created for a live enabled output, this event is emitted once immediately after creation to provide the initial value. It is also emitted whenever the applied color temperature changes — whether through a commit on this object, a commit on another color control object for the same output, or a compositor-driven change such as a system setting update.
Color temperature is expressed in Kelvin on a Planckian locus, in the range [1000, 20000].
brightness(brightness: fixed)
Argument | Type | Description |
|---|---|---|
| brightness | fixed | current brightness level in the range [0.0, 100.0] |
Reports the currently applied brightness of the output. When the object is created for a live enabled output, this event is emitted once immediately after creation to provide the initial value. It is also emitted whenever the applied brightness changes — whether through a commit on this object, a commit on another picture control object for the same output, or a compositor-driven change such as a system setting update.
Brightness is expressed as a percentage in the range [0.0, 100.0].
error { invalid_color_temperature, invalid_brightness }
Argument | Value | Description |
|---|---|---|
| invalid_color_temperature | 0 | the color temperature is outside the valid range [1000, 20000] |
| invalid_brightness | 1 | the brightness is outside the valid range [0.0, 100.0] |
Raised by the compositor as a fatal protocol error when a set_color_temperature or set_brightness request carries a value outside its valid range. The connection is terminated and no further requests are processed on this object.
commit_result { success, failed, unsupported, invalid_output }
Argument | Value | Description |
|---|---|---|
| success | 0 | all pending settings were applied successfully |
| failed | 1 | the commit failed to apply for a transient or unknown reason; settings remain unchanged |
| unsupported | 2 | the output does not support the requested adjustment, for example when its hardware cannot apply color temperature changes; settings remain unchanged |
| invalid_output | 3 | the uuid does not identify a live enabled output; the object becomes permanently inert and settings remain unchanged |
Indicates the outcome of a commit request, or of object creation when the object was created for a uuid that does not identify a live enabled output. A commit is reported as applied successfully, or as failed because the output does not support the requested adjustment, because the associated output is no longer available, or for another transient or unknown reason. An invalid_output result is terminal: the object becomes permanently inert and only destroy may be sent.
Compositor Support
Copyright
SPDX-FileCopyrightText: 2024 - 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT