COSMIC output managment

extension protocol to wlr-output-management

This protocol serves as an extension to wlr-output-management.

It primarily adds explicit output mirroring, while upstream is figuring out how to best support that.

It was designed against version 4 of wlr-output-management, but tries it's best to be forward compatible.

Output configuration manager

This interface provides extension points for wlr-output-management types.

Argument
Type
Description
extendednew_id<zcosmic_output_head_v1>
headobject<zwlr_output_head_v1>
Get a zcosmic_output_head_v1 for an existing zwlr_output_head_v1

Gets an extension object for zwlr_output_head_v1.

As soon as the extended output is created, events will be dispatched with an accompanying `done`-event delivered to the matching `zwlr_output_manager_v1` afterwards.

Any further updates will produce new events, if properties of the zcosmic_output_head_v1 change, just like for the original `zwlr_output_head_v1`. Events should be handled as atomic, as denoted by `zwlr_output_manager_v1::done`.

Trying to create more than one zcosmic_output_head_v1 per zwlr_output_head_v1 will raise an "already_extended" error.

Get a zcosmic_output_configuration_v1 for an existing zwlr_output_configuration_v1

Gets an extension object for zwlr_output_configuration_v1.

Trying to create more than one zcosmic_output_configuration_v1 per zwlr_output_configuration_v1 will raise an "already_extended" error.

Get a zcosmic_output_configuration_head_v1 for an existing zwlr_output_configuration_head_v1

Gets an extension object for zwlr_output_configuration_head_v1.

Trying to create more than one zcosmic_output_configuration_head_v1 per zwlr_output_configuration_head_v1 will raise an "already_extended" error.

release()
Destroy this global

Destroys this global. All previously created objects remain valid.

set_xwayland_primary(head: object<zcosmic_output_head_v1>)
Argument
Type
Description
headobject<zcosmic_output_head_v1>allow null
head to be advertised as primary
set head as the primary for xwayland

This requests a head to be advertised as the primary output via randr to Xwayland.

No head has to be marked primary, if `null` is passed Xwayland won't advertise a primary output. Sending a disabled head will be ignored to avoid races.

error { already_extended } 
Argument
Value
Description
already_extended1
object already created

Output extension object

Extension to zwlr_output_head_v1.

Adds additional read-only properties.

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

release()
destroy the output head

Using this request a client can tell the compositor that it is not interested in the head object anymore.

scale_1000(scale_1000: int)
Argument
Type
Description
scale_1000int
current scale

This events describes the scale of the head in the global compositor space multiplied by 1000 for additional precision.

It is only sent if the output is enabled.

mirroring(name: string)
Argument
Type
Description
namestringallow null
mirroring other output

This events describes that the head is mirroring another. In these cases `name` contains the unique name of the matching `zwlr_output_head_v1`. If the name is null, no head is being mirrored onto this one.

For mirrored heads the `position`-event is meaningless.

It is only sent if the output is enabled.

is adaptive_sync available for this head

This events describes if adaptive_sync is available for this head.

It is only sent if the output is enabled.

current adaptive_sync state

This events describes the adaptive_sync state of this head.

It is only sent if the output is enabled.

xwayland_primary(state: uint)
Argument
Type
Description
stateuint
boolean if primary or not
is this head configured as the primary for xwayland

This event describes if this head is advertised as the primary output via randr to Xwayland.

At most one output is marked primary, but it is not guaranteed that any output is marked. It is only sent if the output is enabled.

adaptive_sync_availability { unsupported, requires_modeset, supported } 
Argument
Value
Description
unsupported0
adaptive sync is not supported
requires_modeset1
automatic adaptive_sync is unavailable
supported2
adaptive sync is supported in all states
adaptive_sync_state_ext { disabled, automatic, always } 
Argument
Value
Description
disabled0
adaptive sync is disabled
automatic1
adaptive sync will be actived automatically
always2
adaptive sync is forced to be always active

Output configuration extension object

Extension to zwlr_output_configuration_v1.

Adds additional parameters to be tested/applyed via the original zwlr_output_configuration_v1.

Argument
Type
Description
idnew_id<zwlr_output_configuration_head_v1>
a new object to configure the head
headobject<zwlr_output_head_v1>
the head to be enabled
mirroringobject<zwlr_output_head_v1>
the head to be mirrored
enable and configure a head to mirror another head

Enable a head mirroring another.

This request creates a head configuration object that can be used to change the head's properties.

This is an alternative to `zwlr_output_configuration_v1::enable_head` or `zwlr_output_configuration_v1::disable_head` Using either with the same `head` argument will result in an `already_configured_head` error on the original `zwlr_output_configuration_v1` object.

All properties are still required to be set to the resulting `zwlr_output_configuration_head` by the client as denoted in the original protocol. Some like `set_position` however might be ignored in mirroring configurations.

Trying to set a disabled or mirroring head as `mirroring` or calling `disable_head`/`mirror_head` after using a head as a `mirroring` argument will raise a `mirrored_head_busy` protocol error.

release()
destroy the output configuration

Using this request a client can tell the compositor that it is not going to use the configuration object anymore. Any changes to the outputs will still be attached to the original `zwlr_output_configuration_head_v1` if it isn't destroyed.

finished()
the configuration was used

This event indicates that the configuration is no longer available.

This usually happens when the original configuration was `cancelled`, `suceeded` or `failed`.

Upon receiving this event, the client should destroy this object.

The configration object becomes inert and any requests other than `destroy` will be ignored.

Argument
Value
Description
already_finished1
underlying configuration has already been used
mirrored_head_busy2
mirrored head is not enabled

Output configuration head extension object

Extension to zwlr_output_configuration_head_v1.

Adds additional/alternative parameters to the original zwlr_output_configuration_head_v1.

Once the original `zwlr_output_configuration_head_v1` is destroyed this object will become inert and all requests except `release` will be ignored.

set_scale_1000(scale_1000: int)
Argument
Type
Description
scale_1000int
set the scale multiplied by 1000

This request sets the head's scale multiplied by 1000 for additional precision.

This request is meant to be used in place of `zwlr_output_configuration_head_v1::set_scale`. Using `set_scale` and `set_scale_1000` at once will thus raise an `already_set` error on the original `zwlr_output_configuration_head_v1`.

Any request conflicting with `set_scale` will also conflict with `set_scale_1000`.

release()
destroy the output configuration head

Using this request a client can tell the compositor that it is not going to use the configuration object anymore. Already issued requests will still be attached to the original `zwlr_output_configuration_head_v1` until it is destroyed.

set adaptive sync state

This request requests a new adaptive sync state.

This request is meant to be used in place of `zwlr_output_configuration_head_v1::set_adaptive_sync`. Using `set_adaptive_sync` and `set_adaptive_sync_ext` at once will thus raise an `already_set` error on the original `zwlr_output_configuration_head_v1`.

Any request conflicting with `set_adaptive_sync` will also conflict with `set_adaptive_sync_ext`.


Compositor Support

Mutter
Mutter
48.0
KWin
KWin
6.4
Sway
Sway
1.11
COSMIC
COSMIC
...
Hyprland
Hyprland
0.48
niri
25.02
Weston
Weston
14
Labwc
Labwc
0.9.0
Cage
Cage
0.2.0
Wayfire
Wayfire
0.9.0
GameScope
GameScope
3.15.14
Jay
1.11.0
Mir
Mir
2.19
Treeland
Treeland
0.6.1
Louvre
Louvre
2.14.1
zcosmic_output_manager_v1
x
x
x
3
x
x
x
x
x
x
x
x
x
x
x

Copyright © 2024 Victoria Brekenfeld

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.