+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<protocol name="wlr_output_management_unstable_v1">
- <copyright>
- Copyright © 2019 Purism SPC
-
- Permission to use, copy, modify, distribute, and sell this
- software and its documentation for any purpose is hereby granted
- without fee, provided that the above copyright notice appear in
- all copies and that both that copyright notice and this permission
- notice appear in supporting documentation, and that the name of
- the copyright holders not be used in advertising or publicity
- pertaining to distribution of the software without specific,
- written prior permission. The copyright holders make no
- representations about the suitability of this software for any
- purpose. It is provided "as is" without express or implied
- warranty.
-
- THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
- SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
- FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
- SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
- WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
- AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
- ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
- THIS SOFTWARE.
- </copyright>
-
- <description summary="protocol to configure output devices">
- This protocol exposes interfaces to obtain and modify output device
- configuration.
-
- Warning! The protocol described in this file is experimental and
- backward incompatible changes may be made. Backward compatible changes
- may be added together with the corresponding interface version bump.
- Backward incompatible changes are done by bumping the version number in
- the protocol and interface names and resetting the interface version.
- Once the protocol is to be declared stable, the 'z' prefix and the
- version number in the protocol and interface names are removed and the
- interface version number is reset.
- </description>
-
- <interface name="zwlr_output_manager_v1" version="2">
- <description summary="output device configuration manager">
- This interface is a manager that allows reading and writing the current
- output device configuration.
-
- Output devices that display pixels (e.g. a physical monitor or a virtual
- output in a window) are represented as heads. Heads cannot be created nor
- destroyed by the client, but they can be enabled or disabled and their
- properties can be changed. Each head may have one or more available modes.
-
- Whenever a head appears (e.g. a monitor is plugged in), it will be
- advertised via the head event. Immediately after the output manager is
- bound, all current heads are advertised.
-
- Whenever a head's properties change, the relevant wlr_output_head events
- will be sent. Not all head properties will be sent: only properties that
- have changed need to.
-
- Whenever a head disappears (e.g. a monitor is unplugged), a
- wlr_output_head.finished event will be sent.
-
- After one or more heads appear, change or disappear, the done event will
- be sent. It carries a serial which can be used in a create_configuration
- request to update heads properties.
-
- The information obtained from this protocol should only be used for output
- configuration purposes. This protocol is not designed to be a generic
- output property advertisement protocol for regular clients. Instead,
- protocols such as xdg-output should be used.
- </description>
-
- <event name="head">
- <description summary="introduce a new head">
- This event introduces a new head. This happens whenever a new head
- appears (e.g. a monitor is plugged in) or after the output manager is
- bound.
- </description>
- <arg name="head" type="new_id" interface="zwlr_output_head_v1"/>
- </event>
-
- <event name="done">
- <description summary="sent all information about current configuration">
- This event is sent after all information has been sent after binding to
- the output manager object and after any subsequent changes. This applies
- to child head and mode objects as well. In other words, this event is
- sent whenever a head or mode is created or destroyed and whenever one of
- their properties has been changed. Not all state is re-sent each time
- the current configuration changes: only the actual changes are sent.
-
- This allows changes to the output configuration to be seen as atomic,
- even if they happen via multiple events.
-
- A serial is sent to be used in a future create_configuration request.
- </description>
- <arg name="serial" type="uint" summary="current configuration serial"/>
- </event>
-
- <request name="create_configuration">
- <description summary="create a new output configuration object">
- Create a new output configuration object. This allows to update head
- properties.
- </description>
- <arg name="id" type="new_id" interface="zwlr_output_configuration_v1"/>
- <arg name="serial" type="uint"/>
- </request>
-
- <request name="stop">
- <description summary="stop sending events">
- Indicates the client no longer wishes to receive events for output
- configuration changes. However the compositor may emit further events,
- until the finished event is emitted.
-
- The client must not send any more requests after this one.
- </description>
- </request>
-
- <event name="finished">
- <description summary="the compositor has finished with the manager">
- This event indicates that the compositor is done sending manager events.
- The compositor will destroy the object immediately after sending this
- event, so it will become invalid and the client should release any
- resources associated with it.
- </description>
- </event>
- </interface>
-
- <interface name="zwlr_output_head_v1" version="2">
- <description summary="output device">
- A head is an output device. The difference between a wl_output object and
- a head is that heads are advertised even if they are turned off. A head
- object only advertises properties and cannot be used directly to change
- them.
-
- A head has some read-only properties: modes, name, description and
- physical_size. These cannot be changed by clients.
-
- Other properties can be updated via a wlr_output_configuration object.
-
- 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.
- </description>
-
- <event name="name">
- <description summary="head name">
- This event describes the head name.
-
- The naming convention is compositor defined, but limited to alphanumeric
- characters and dashes (-). Each name is unique among all wlr_output_head
- objects, but if a wlr_output_head object is destroyed the same name may
- be reused later. The names will also remain consistent across sessions
- with the same hardware and software configuration.
-
- Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc. However, do
- not assume that the name is a reflection of an underlying DRM
- connector, X11 connection, etc.
-
- If the compositor implements the xdg-output protocol and this head is
- enabled, the xdg_output.name event must report the same name.
-
- The name event is sent after a wlr_output_head object is created. This
- event is only sent once per object, and the name does not change over
- the lifetime of the wlr_output_head object.
- </description>
- <arg name="name" type="string"/>
- </event>
-
- <event name="description">
- <description summary="head description">
- This event describes a human-readable description of the head.
-
- The description is a UTF-8 string with no convention defined for its
- contents. Examples might include 'Foocorp 11" Display' or 'Virtual X11
- output via :1'. However, do not assume that the name is a reflection of
- the make, model, serial of the underlying DRM connector or the display
- name of the underlying X11 connection, etc.
-
- If the compositor implements xdg-output and this head is enabled,
- the xdg_output.description must report the same description.
-
- The description event is sent after a wlr_output_head object is created.
- This event is only sent once per object, and the description does not
- change over the lifetime of the wlr_output_head object.
- </description>
- <arg name="description" type="string"/>
- </event>
-
- <event name="physical_size">
- <description summary="head physical size">
- This event describes the physical size of the head. This event is only
- sent if the head has a physical size (e.g. is not a projector or a
- virtual device).
- </description>
- <arg name="width" type="int" summary="width in millimeters of the output"/>
- <arg name="height" type="int" summary="height in millimeters of the output"/>
- </event>
-
- <event name="mode">
- <description summary="introduce a mode">
- This event introduces a mode for this head. It is sent once per
- supported mode.
- </description>
- <arg name="mode" type="new_id" interface="zwlr_output_mode_v1"/>
- </event>
-
- <event name="enabled">
- <description summary="head is enabled or disabled">
- This event describes whether the head is enabled. A disabled head is not
- mapped to a region of the global compositor space.
-
- When a head is disabled, some properties (current_mode, position,
- transform and scale) are irrelevant.
- </description>
- <arg name="enabled" type="int" summary="zero if disabled, non-zero if enabled"/>
- </event>
-
- <event name="current_mode">
- <description summary="current mode">
- This event describes the mode currently in use for this head. It is only
- sent if the output is enabled.
- </description>
- <arg name="mode" type="object" interface="zwlr_output_mode_v1"/>
- </event>
-
- <event name="position">
- <description summary="current position">
- This events describes the position of the head in the global compositor
- space. It is only sent if the output is enabled.
- </description>
- <arg name="x" type="int"
- summary="x position within the global compositor space"/>
- <arg name="y" type="int"
- summary="y position within the global compositor space"/>
- </event>
-
- <event name="transform">
- <description summary="current transformation">
- This event describes the transformation currently applied to the head.
- It is only sent if the output is enabled.
- </description>
- <arg name="transform" type="int" enum="wl_output.transform"/>
- </event>
-
- <event name="scale">
- <description summary="current scale">
- This events describes the scale of the head in the global compositor
- space. It is only sent if the output is enabled.
- </description>
- <arg name="scale" type="fixed"/>
- </event>
-
- <event name="finished">
- <description summary="the head has been destroyed">
- The compositor will destroy the object immediately after sending this
- event, so it will become invalid and the client should release any
- resources associated with it.
- </description>
- </event>
-
- <!-- Version 2 additions -->
- <event name="make" since="2">
- <description summary="head manufacturer">
- This event describes the manufacturer of the head.
-
- This must report the same make as the wl_output interface does in its
- geometry event.
-
- Together with the model and serial_number events the purpose is to
- allow clients to recognize heads from previous sessions and for example
- load head-specific configurations back.
-
- It is not guaranteed this event will be ever sent. A reason for that
- can be that the compositor does not have information about the make of
- the head or the definition of a make is not sensible in the current
- setup, for example in a virtual session. Clients can still try to
- identify the head by available information from other events but should
- be aware that there is an increased risk of false positives.
-
- It is not recommended to display the make string in UI to users. For
- that the string provided by the description event should be preferred.
- </description>
- <arg name="make" type="string"/>
- </event>
-
- <event name="model" since="2">
- <description summary="head model">
- This event describes the model of the head.
-
- This must report the same model as the wl_output interface does in its
- geometry event.
-
- Together with the make and serial_number events the purpose is to
- allow clients to recognize heads from previous sessions and for example
- load head-specific configurations back.
-
- It is not guaranteed this event will be ever sent. A reason for that
- can be that the compositor does not have information about the model of
- the head or the definition of a model is not sensible in the current
- setup, for example in a virtual session. Clients can still try to
- identify the head by available information from other events but should
- be aware that there is an increased risk of false positives.
-
- It is not recommended to display the model string in UI to users. For
- that the string provided by the description event should be preferred.
- </description>
- <arg name="model" type="string"/>
- </event>
-
- <event name="serial_number" since="2">
- <description summary="head serial number">
- This event describes the serial number of the head.
-
- Together with the make and model events the purpose is to allow clients
- to recognize heads from previous sessions and for example load head-
- specific configurations back.
-
- It is not guaranteed this event will be ever sent. A reason for that
- can be that the compositor does not have information about the serial
- number of the head or the definition of a serial number is not sensible
- in the current setup. Clients can still try to identify the head by
- available information from other events but should be aware that there
- is an increased risk of false positives.
-
- It is not recommended to display the serial_number string in UI to
- users. For that the string provided by the description event should be
- preferred.
- </description>
- <arg name="serial_number" type="string"/>
- </event>
- </interface>
-
- <interface name="zwlr_output_mode_v1" version="2">
- <description summary="output mode">
- This object describes an output mode.
-
- Some heads don't support output modes, in which case modes won't be
- advertised.
-
- 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.
- </description>
-
- <event name="size">
- <description summary="mode size">
- This event describes the mode size. The size is given in physical
- hardware units of the output device. This is not necessarily the same as
- the output size in the global compositor space. For instance, the output
- may be scaled or transformed.
- </description>
- <arg name="width" type="int" summary="width of the mode in hardware units"/>
- <arg name="height" type="int" summary="height of the mode in hardware units"/>
- </event>
-
- <event name="refresh">
- <description summary="mode refresh rate">
- This event describes the mode's fixed vertical refresh rate. It is only
- sent if the mode has a fixed refresh rate.
- </description>
- <arg name="refresh" type="int" summary="vertical refresh rate in mHz"/>
- </event>
-
- <event name="preferred">
- <description summary="mode is preferred">
- This event advertises this mode as preferred.
- </description>
- </event>
-
- <event name="finished">
- <description summary="the mode has been destroyed">
- The compositor will destroy the object immediately after sending this
- event, so it will become invalid and the client should release any
- resources associated with it.
- </description>
- </event>
- </interface>
-
- <interface name="zwlr_output_configuration_v1" version="2">
- <description summary="output configuration">
- This object is used by the client to describe a full output configuration.
-
- First, the client needs to setup the output configuration. Each head can
- be either enabled (and configured) or disabled. It is a protocol error to
- send two enable_head or disable_head requests with the same head. It is a
- protocol error to omit a head in a configuration.
-
- Then, the client can apply or test the configuration. The compositor will
- then reply with a succeeded, failed or cancelled event. Finally the client
- should destroy the configuration object.
- </description>
-
- <enum name="error">
- <entry name="already_configured_head" value="1"
- summary="head has been configured twice"/>
- <entry name="unconfigured_head" value="2"
- summary="head has not been configured"/>
- <entry name="already_used" value="3"
- summary="request sent after configuration has been applied or tested"/>
- </enum>
-
- <request name="enable_head">
- <description summary="enable and configure a head">
- Enable a head. This request creates a head configuration object that can
- be used to change the head's properties.
- </description>
- <arg name="id" type="new_id" interface="zwlr_output_configuration_head_v1"
- summary="a new object to configure the head"/>
- <arg name="head" type="object" interface="zwlr_output_head_v1"
- summary="the head to be enabled"/>
- </request>
-
- <request name="disable_head">
- <description summary="disable a head">
- Disable a head.
- </description>
- <arg name="head" type="object" interface="zwlr_output_head_v1"
- summary="the head to be disabled"/>
- </request>
-
- <request name="apply">
- <description summary="apply the configuration">
- Apply the new output configuration.
-
- In case the configuration is successfully applied, there is no guarantee
- that the new output state matches completely the requested
- configuration. For instance, a compositor might round the scale if it
- doesn't support fractional scaling.
-
- After this request has been sent, the compositor must respond with an
- succeeded, failed or cancelled event. Sending a request that isn't the
- destructor is a protocol error.
- </description>
- </request>
-
- <request name="test">
- <description summary="test the configuration">
- Test the new output configuration. The configuration won't be applied,
- but will only be validated.
-
- Even if the compositor succeeds to test a configuration, applying it may
- fail.
-
- After this request has been sent, the compositor must respond with an
- succeeded, failed or cancelled event. Sending a request that isn't the
- destructor is a protocol error.
- </description>
- </request>
-
- <event name="succeeded">
- <description summary="configuration changes succeeded">
- Sent after the compositor has successfully applied the changes or
- tested them.
-
- Upon receiving this event, the client should destroy this object.
-
- If the current configuration has changed, events to describe the changes
- will be sent followed by a wlr_output_manager.done event.
- </description>
- </event>
-
- <event name="failed">
- <description summary="configuration changes failed">
- Sent if the compositor rejects the changes or failed to apply them. The
- compositor should revert any changes made by the apply request that
- triggered this event.
-
- Upon receiving this event, the client should destroy this object.
- </description>
- </event>
-
- <event name="cancelled">
- <description summary="configuration has been cancelled">
- Sent if the compositor cancels the configuration because the state of an
- output changed and the client has outdated information (e.g. after an
- output has been hotplugged).
-
- The client can create a new configuration with a newer serial and try
- again.
-
- Upon receiving this event, the client should destroy this object.
- </description>
- </event>
-
- <request name="destroy" type="destructor">
- <description summary="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
- that have not been applied will be discarded.
-
- This request also destroys wlr_output_configuration_head objects created
- via this object.
- </description>
- </request>
- </interface>
-
- <interface name="zwlr_output_configuration_head_v1" version="2">
- <description summary="head configuration">
- This object is used by the client to update a single head's configuration.
-
- It is a protocol error to set the same property twice.
- </description>
-
- <enum name="error">
- <entry name="already_set" value="1" summary="property has already been set"/>
- <entry name="invalid_mode" value="2" summary="mode doesn't belong to head"/>
- <entry name="invalid_custom_mode" value="3" summary="mode is invalid"/>
- <entry name="invalid_transform" value="4" summary="transform value outside enum"/>
- <entry name="invalid_scale" value="5" summary="scale negative or zero"/>
- </enum>
-
- <request name="set_mode">
- <description summary="set the mode">
- This request sets the head's mode.
- </description>
- <arg name="mode" type="object" interface="zwlr_output_mode_v1"/>
- </request>
-
- <request name="set_custom_mode">
- <description summary="set a custom mode">
- This request assigns a custom mode to the head. The size is given in
- physical hardware units of the output device. If set to zero, the
- refresh rate is unspecified.
-
- It is a protocol error to set both a mode and a custom mode.
- </description>
- <arg name="width" type="int" summary="width of the mode in hardware units"/>
- <arg name="height" type="int" summary="height of the mode in hardware units"/>
- <arg name="refresh" type="int" summary="vertical refresh rate in mHz or zero"/>
- </request>
-
- <request name="set_position">
- <description summary="set the position">
- This request sets the head's position in the global compositor space.
- </description>
- <arg name="x" type="int" summary="x position in the global compositor space"/>
- <arg name="y" type="int" summary="y position in the global compositor space"/>
- </request>
-
- <request name="set_transform">
- <description summary="set the transform">
- This request sets the head's transform.
- </description>
- <arg name="transform" type="int" enum="wl_output.transform"/>
- </request>
-
- <request name="set_scale">
- <description summary="set the scale">
- This request sets the head's scale.
- </description>
- <arg name="scale" type="fixed"/>
- </request>
- </interface>
-</protocol>
projects / proto / labwc.git / commitdiff