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.

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.


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 also be destroyed.

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.


Compositor Support

Mutter
Mutter
46
KWin
KWin
6.1
Sway
Sway
1.9
COSMIC
COSMIC
1.0.0
Hyprland
Hyprland
0.42.0
niri
0.1.8
Weston
Weston
13
Mir
Mir
2.17
GameScope
GameScope
3.14.22
zcosmic_output_manager_v1
x
x
x
1
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.