Treeland output UUID
This protocol lets clients obtain a stable uuid for each output, identifying the physical output device behind it. The uuid is an opaque, non-empty UTF-8 string that remains stable across sessions and output reconnections, so clients and the compositor can persist per-output settings and restore them after a restart.
Uuids are fixed-length, exactly 36 bytes, and never contain the NUL byte; the canonical form is a lowercase 8-4-4-4-12 hexadecimal string with hyphens, for example 8dd6d52e-1f60-4649-9c2c-6fb7e055272e.
The uuid is unique among the currently connected outputs: the compositor must ensure that no two connected outputs report the same uuid at the same time. The compositor assigns the uuid to each physical output device and persists the assignment, so a given device keeps the same uuid across sessions and across being disconnected and reconnected. Once assigned, the uuid never changes for the lifetime of the physical output device. Clients must not assume the uuid is derived from any particular device attribute.
Clients obtain a uuid for a wl_output object via get_uuid on this protocol, or for a zwlr_output_head_v1 via the companion treeland-output-uuid-head-unstable-v1 protocol; both entry points return the same uuid for the same physical output device. The head variant can identify an output that is disabled and has no live wl_output global.
Clients must treat the uuid as opaque: they must not parse it, derive meaning from its contents, or present it to users.
The terms "must", "must not", "should", and "may" in this document are to be interpreted as described in RFC 2119.
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.
treeland_output_uuid_manager_v1
A singleton global that creates treeland_output_uuid_v1 objects from wl_output objects. The client calls get_uuid for each output it wants to identify; the compositor reports the uuid in the initial uuid event on the returned object. Multiple uuid objects may be created for the same output; each reports independently.
destroy()
Destroy the treeland_output_uuid_manager_v1 object and release the client's binding to the manager global.
Existing treeland_output_uuid_v1 objects created through this manager are not affected and must be destroyed separately by the client.
get_uuid(id: new_id<treeland_output_uuid_v1>, output: object<wl_output>)
Argument | Type | Description |
|---|---|---|
| id | new_id<treeland_output_uuid_v1> | the new output uuid object |
| output | object<wl_output> | the output to identify |
Create a treeland_output_uuid_v1 object for the given wl_output. The output may be in any state, including disabled: the uuid identifies the physical device regardless of its enabled state.
For an output that is currently disabled and has no live wl_output global, the client should use the companion treeland-output-uuid-head-unstable-v1 protocol with the corresponding zwlr_output_head_v1 instead.
treeland_output_uuid_v1
Represents the uuid identity of the output it was created for, obtained from treeland_output_uuid_manager_v1.get_uuid or from the companion treeland-output-uuid-head-unstable-v1 protocol. The compositor emits the uuid event once immediately after the object is created. The uuid never changes, so the event is not emitted again while the object exists.
The object is not tied to the lifetime of the wl_output global: when the output is unplugged and its wl_output global is destroyed, this object remains valid and the last reported uuid remains the identity of the physical device, which may reappear later with the same uuid. The client should destroy this object when it no longer needs the mapping.
Note, because treeland_output_uuid_v1 objects are created from multiple independent factory interfaces — treeland_output_uuid_manager_v1 on this protocol and treeland_output_uuid_head_manager_v1 on the companion treeland-output-uuid-head-unstable-v1 protocol — the treeland_output_uuid_v1 interface is frozen at version 1.
destroy()
Destroy this object. Only this object is affected; the uuid of the output and other uuid objects for the same output are unchanged.
uuid(uuid: string)
Argument | Type | Description |
|---|---|---|
| uuid | string | opaque uuid identifying the physical output |
Reports the current uuid of the output. It is emitted once immediately after the object is created and never again, because the uuid never changes for the lifetime of the output device.
Compositor Support
Copyright
SPDX-FileCopyrightText: 2024 - 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT