1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="wlr_screencopy_unstable_v1">
3
4 <description summary="screen content capturing on client buffers">
5 This protocol allows clients to ask the compositor to copy part of the
6 screen content to a client buffer.
7
8 Warning! The protocol described in this file is experimental and
9 backward incompatible changes may be made. Backward compatible changes
10 may be added together with the corresponding interface version bump.
11 Backward incompatible changes are done by bumping the version number in
12 the protocol and interface names and resetting the interface version.
13 Once the protocol is to be declared stable, the 'z' prefix and the
14 version number in the protocol and interface names are removed and the
15 interface version number is reset.
16 </description>
17
18 <interface name="zwlr_screencopy_manager_v1" version="1">
19 <description summary="manager to inform clients and begin capturing">
20 This object is a manager which offers requests to start capturing from a
21 source.
22 </description>
23
24 <request name="capture_output">
25 <description summary="capture an output">
26 Capture the next frame of an entire output.
27 </description>
28 <arg name="frame" type="new_id" interface="zwlr_screencopy_frame_v1"/>
29 <arg name="overlay_cursor" type="int"
30 summary="composite cursor onto the frame"/>
31 <arg name="output" type="object" interface="wl_output"/>
32 </request>
33
34 <request name="capture_output_region">
35 <description summary="capture an output's region">
36 Capture the next frame of an output's region.
37
38 The region is given in output logical coordinates, see
39 xdg_output.logical_size. The region will be clipped to the output's
40 extents.
41 </description>
42 <arg name="frame" type="new_id" interface="zwlr_screencopy_frame_v1"/>
43 <arg name="overlay_cursor" type="int"
44 summary="composite cursor onto the frame"/>
45 <arg name="output" type="object" interface="wl_output"/>
46 <arg name="x" type="int"/>
47 <arg name="y" type="int"/>
48 <arg name="width" type="int"/>
49 <arg name="height" type="int"/>
50 </request>
51
52 <request name="destroy" type="destructor">
53 <description summary="destroy the manager">
54 All objects created by the manager will still remain valid, until their
55 appropriate destroy request has been called.
56 </description>
57 </request>
58 </interface>
59
60 <interface name="zwlr_screencopy_frame_v1" version="1">
61 <description summary="a frame ready for copy">
62 This object represents a single frame.
63
64 When created, a "buffer" event will be sent. The client will then be able
65 to send a "copy" request. If the capture is successful, the compositor
66 will send a "flags" followed by a "ready" event.
67
68 If the capture failed, the "failed" event is sent. This can happen anytime
69 before the "ready" event.
70
71 Once either a "ready" or a "failed" event is received, the client should
72 destroy the frame.
73 </description>
74
75 <event name="buffer">
76 <description summary="buffer information">
77 Provides information about the frame's buffer. This event is sent once
78 as soon as the frame is created.
79
80 The client should then create a buffer with the provided attributes, and
81 send a "copy" request.
82 </description>
83 <arg name="format" type="uint" summary="buffer format"/>
84 <arg name="width" type="uint" summary="buffer width"/>
85 <arg name="height" type="uint" summary="buffer height"/>
86 <arg name="stride" type="uint" summary="buffer stride"/>
87 </event>
88
89 <request name="copy">
90 <description summary="copy the frame">
91 Copy the frame to the supplied buffer. The buffer must have a the
92 correct size, see zwlr_screencopy_frame_v1.buffer. The buffer needs to
93 have a supported format.
94
95 If the frame is successfully copied, a "flags" and a "ready" events are
96 sent. Otherwise, a "failed" event is sent.
97 </description>
98 <arg name="buffer" type="object" interface="wl_buffer"/>
99 </request>
100
101 <enum name="error">
102 <entry name="already_used" value="0"
103 summary="the object has already been used to copy a wl_buffer"/>
104 <entry name="invalid_buffer" value="1"
105 summary="buffer attributes are invalid"/>
106 </enum>
107
108 <enum name="flags" bitfield="true">
109 <entry name="y_invert" value="1" summary="contents are y-inverted"/>
110 </enum>
111
112 <event name="flags">
113 <description summary="frame flags">
114 Provides flags about the frame. This event is sent once before the
115 "ready" event.
116 </description>
117 <arg name="flags" type="uint" enum="flags" summary="frame flags"/>
118 </event>
119
120 <event name="ready">
121 <description summary="indicates frame is available for reading">
122 Called as soon as the frame is copied, indicating it is available
123 for reading. This event includes the time at which presentation happened
124 at.
125
126 The timestamp is expressed as tv_sec_hi, tv_sec_lo, tv_nsec triples,
127 each component being an unsigned 32-bit value. Whole seconds are in
128 tv_sec which is a 64-bit value combined from tv_sec_hi and tv_sec_lo,
129 and the additional fractional part in tv_nsec as nanoseconds. Hence,
130 for valid timestamps tv_nsec must be in [0, 999999999]. The seconds part
131 may have an arbitrary offset at start.
132
133 After receiving this event, the client should destroy the object.
134 </description>
135 <arg name="tv_sec_hi" type="uint"
136 summary="high 32 bits of the seconds part of the timestamp"/>
137 <arg name="tv_sec_lo" type="uint"
138 summary="low 32 bits of the seconds part of the timestamp"/>
139 <arg name="tv_nsec" type="uint"
140 summary="nanoseconds part of the timestamp"/>
141 </event>
142
143 <event name="failed">
144 <description summary="frame copy failed">
145 This event indicates that the attempted frame copy has failed.
146
147 After receiving this event, the client should destroy the object.
148 </description>
149 </event>
150
151 <request name="destroy" type="destructor">
152 <description summary="delete this object, used or not">
153 Destroys the frame. This request can be sent at any time by the client.
154 </description>
155 </request>
156 </interface>
157</protocol>