diff --git a/protocol/wayland.xml b/protocol/wayland.xml index 513b8fd8..9c13e534 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -2858,14 +2858,80 @@ - + + + This interface provides a way to list available outputs. + + The original way to announce available outputs is to create a wl_output + global for every output. However, the biggest flaw with that design is that + output removal is racy and can lead to client crashes. The wl_output_list + interface provides a safer way to deal with output updates. + + Note that the minimum supported wl_output_list version is 5. If this + global is bound with a version less than 5, the unsupported_version error + will be posted. + + + + + These errors can be emitted in response to wl_output_list requests. + + + + + + + This event is sent in response to the wl_output_list.stop request. The + compositor will immediately destroy the wl_output_list object after + sending this event. The wl_output objects will be unaffected. + + The client is free to destroy its client-side wl_output_list proxy object + after receiving this event. + + + + + + This request indicates that the client no longer wants to receive new + output announcements. The compositor will send the finished event in + response to this request. + + Since communication between the client and the compositor is asynchronous, + it is possible to receive the "wl_output_list.output" event after calling + this request. After the compositor processes the stop request, no new + output announcements will be sent. + + + + + + This event is sent when a new output is available or after binding this + global to list all available outputs. + + + + + + An output describes part of the compositor geometry. The compositor works in the 'compositor coordinate system' and an output corresponds to a rectangular area in that space that is actually visible. This typically corresponds to a monitor that - displays part of the compositor space. This object is published - as global during start up, or when a monitor is hotplugged. + displays part of the compositor space. + + This object is published as global during start up, or when a monitor + is hotplugged. + + If the compositor announces the wl_output_list global, it is subject + to compositor policies whether available outputs are published as + wl_output globals too. For the compatibility reasons, it is recommended + that the compositors announce wl_output globals as well. + + Note! New clients should use the wl_output_list instead of binding + wl_output globals. wl_output globals are prone to races that can lead + to various client crashes. @@ -3098,6 +3164,15 @@ + + + + + This event is sent when the output is no longer available. After this + event, no new output updates will be sent. The client should call the + wl_output.release request after receiving this event. + +