mirrors/wlroots
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/wlroots/wlroots.git synced 2025-10-28 05:40:11 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

protocols: sync with wlr-protocols, apply non-breaking updates and doc improvements

Browse source 
This sync includes minor non-breaking updates from recent years:

- Fix typos and grammatical issues (e.g. "a an" → "an", "inexistent" → "nonexistent")
- Improve description consistency with `wl_output` (e.g. name, description, make, model, serial)
- Add `destructor` annotation to relevant events (e.g. `finished` in foreign-toplevel)
- Clarify event emission timing and behavior for output management
- No functional or semantic protocol changes introduced

These changes improve the accuracy and consistency of protocol descriptions without impacting compatibility.
This commit is contained in:
rewine 2025-08-05 15:56:27 +08:00 • committed by Simon Zeni
parent 905465b0fa
commit cdd2c7e006
6 changed files with 30 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

4
protocol/wlr-export-dmabuf-unstable-v1.xml
View file

@ -43,7 +43,7 @@
<request name="capture_output">
<description summary="capture a frame from an output">
Capture the next frame of a an entire output.
Capture the next frame of an entire output.
</description>
<arg name="frame" type="new_id" interface="zwlr_export_dmabuf_frame_v1"/>
<arg name="overlay_cursor" type="int"
@ -136,7 +136,7 @@
<arg name="stride" type="uint"
summary="line size in bytes"/>
<arg name="plane_index" type="uint"
summary="index of the the plane the data in the object applies to"/>
summary="index of the plane the data in the object applies to"/>
</event>
<event name="ready">

2
protocol/wlr-foreign-toplevel-management-unstable-v1.xml
View file

@ -58,7 +58,7 @@
</description>
</request>
<event name="finished">
<event name="finished" type="destructor">
<description summary="the compositor has finished with the toplevel manager">
This event indicates that the compositor is done sending events to the
zwlr_foreign_toplevel_manager_v1. The server will destroy the object

2
protocol/wlr-gamma-control-unstable-v1.xml
View file

@ -72,7 +72,7 @@
tables. At any time the compositor can send a failed event indicating that
this object is no longer valid.
There must always be at most one gamma control object per output, which
There can only be at most one gamma control object per output, which
has exclusive access to this particular output. When the gamma control
object is destroyed, the gamma table is restored to its original value.
</description>

30
protocol/wlr-output-management-unstable-v1.xml
View file

@ -156,8 +156,8 @@
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.
If this head matches a wl_output, the wl_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
@ -176,8 +176,8 @@
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.
If this head matches a wl_output, the wl_output.description event must
report the same name.
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
@ -191,6 +191,10 @@
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).
The physical size event is sent after a wlr_output_head object is created. This
event is only sent once per object, and the physical size does not change over
the lifetime of the wlr_output_head object.
</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"/>
@ -264,9 +268,6 @@
<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.
@ -278,6 +279,10 @@
identify the head by available information from other events but should
be aware that there is an increased risk of false positives.
If sent, the make event is sent after a wlr_output_head object is
created and only sent once per object. The make does not change over
the lifetime of the wlr_output_head object.
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>
@ -288,9 +293,6 @@
<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.
@ -302,6 +304,10 @@
identify the head by available information from other events but should
be aware that there is an increased risk of false positives.
If sent, the model event is sent after a wlr_output_head object is
created and only sent once per object. The model does not change over
the lifetime of the wlr_output_head object.
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>
@ -323,6 +329,10 @@
available information from other events but should be aware that there
is an increased risk of false positives.
If sent, the serial number event is sent after a wlr_output_head object
is created and only sent once per object. The serial number does not
change over the lifetime of the wlr_output_head object.
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.

4
protocol/wlr-output-power-management-unstable-v1.xml
View file

@ -50,7 +50,7 @@
<request name="get_output_power">
<description summary="get a power management for an output">
Create a output power management mode control that can be used to
Create an output power management mode control that can be used to
adjust the power management mode for a given output.
</description>
<arg name="id" type="new_id" interface="zwlr_output_power_v1"/>
@ -79,7 +79,7 @@
</enum>
<enum name="error">
<entry name="invalid_mode" value="1" summary="inexistent power save mode"/>
<entry name="invalid_mode" value="1" summary="nonexistent power save mode"/>
</enum>
<request name="set_mode">

9
protocol/wlr-screencopy-unstable-v1.xml
View file

@ -88,7 +88,7 @@
supported buffer type. The "buffer_done" event is sent afterwards to
indicate that all supported buffer types have been enumerated. The client
will then be able to send a "copy" request. If the capture is successful,
the compositor will send a "flags" followed by a "ready" event.
the compositor will send a "flags" event followed by a "ready" event.
For objects version 2 or lower, wl_shm buffers are always supported, ie.
the "buffer" event is guaranteed to be sent.
@ -114,12 +114,12 @@
<request name="copy">
<description summary="copy the frame">
Copy the frame to the supplied buffer. The buffer must have a the
Copy the frame to the supplied buffer. The buffer must have the
correct size, see zwlr_screencopy_frame_v1.buffer and
zwlr_screencopy_frame_v1.linux_dmabuf. The buffer needs to have a
supported format.
If the frame is successfully copied, a "flags" and a "ready" events are
If the frame is successfully copied, "flags" and "ready" events are
sent. Otherwise, a "failed" event is sent.
</description>
<arg name="buffer" type="object" interface="wl_buffer"/>
@ -147,8 +147,7 @@
<event name="ready">
<description summary="indicates frame is available for reading">
Called as soon as the frame is copied, indicating it is available
for reading. This event includes the time at which presentation happened
at.
for reading. This event includes the time at which the presentation took place.
The timestamp is expressed as tv_sec_hi, tv_sec_lo, tv_nsec triples,
each component being an unsigned 32-bit value. Whole seconds are in