1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="ext_image_copy_capture_v1">
3 <copyright>
4 Copyright © 2021-2023 Andri Yngvason
5 Copyright © 2024 Simon Ser
6
7 Permission is hereby granted, free of charge, to any person obtaining a
8 copy of this software and associated documentation files (the "Software"),
9 to deal in the Software without restriction, including without limitation
10 the rights to use, copy, modify, merge, publish, distribute, sublicense,
11 and/or sell copies of the Software, and to permit persons to whom the
12 Software is furnished to do so, subject to the following conditions:
13
14 The above copyright notice and this permission notice (including the next
15 paragraph) shall be included in all copies or substantial portions of the
16 Software.
17
18 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
21 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
23 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
24 DEALINGS IN THE SOFTWARE.
25 </copyright>
26
27 <description summary="image capturing into client buffers">
28 This protocol allows clients to ask the compositor to capture image sources
29 such as outputs and toplevels into user submitted buffers.
30
31 Warning! The protocol described in this file is currently in the testing
32 phase. Backward compatible changes may be added together with the
33 corresponding interface version bump. Backward incompatible changes can
34 only be done by creating a new major version of the extension.
35 </description>
36
37 <interface name="ext_image_copy_capture_manager_v1" version="1">
38 <description summary="manager to inform clients and begin capturing">
39 This object is a manager which offers requests to start capturing from a
40 source.
41 </description>
42
43 <enum name="error">
44 <entry name="invalid_option" value="1" summary="invalid option flag"/>
45 </enum>
46
47 <enum name="options" bitfield="true">
48 <entry name="paint_cursors" value="1" summary="paint cursors onto captured frames"/>
49 </enum>
50
51 <request name="create_session">
52 <description summary="capture an image capture source">
53 Create a capturing session for an image capture source.
54
55 If the paint_cursors option is set, cursors shall be composited onto
56 the captured frame. The cursor must not be composited onto the frame
57 if this flag is not set.
58
59 If the options bitfield is invalid, the invalid_option protocol error
60 is sent.
61 </description>
62 <arg name="session" type="new_id" interface="ext_image_copy_capture_session_v1"/>
63 <arg name="source" type="object" interface="ext_image_capture_source_v1"/>
64 <arg name="options" type="uint" enum="options"/>
65 </request>
66
67 <request name="create_pointer_cursor_session">
68 <description summary="capture the pointer cursor of an image capture source">
69 Create a cursor capturing session for the pointer of an image capture
70 source.
71 </description>
72 <arg name="session" type="new_id" interface="ext_image_copy_capture_cursor_session_v1"/>
73 <arg name="source" type="object" interface="ext_image_capture_source_v1"/>
74 <arg name="pointer" type="object" interface="wl_pointer"/>
75 </request>
76
77 <request name="destroy" type="destructor">
78 <description summary="destroy the manager">
79 Destroy the manager object.
80
81 Other objects created via this interface are unaffected.
82 </description>
83 </request>
84 </interface>
85
86 <interface name="ext_image_copy_capture_session_v1" version="1">
87 <description summary="image copy capture session">
88 This object represents an active image copy capture session.
89
90 After a capture session is created, buffer constraint events will be
91 emitted from the compositor to tell the client which buffer types and
92 formats are supported for reading from the session. The compositor may
93 re-send buffer constraint events whenever they change.
94
95 To advertise buffer constraints, the compositor must send in no
96 particular order: zero or more shm_format and dmabuf_format events, zero
97 or one dmabuf_device event, and exactly one buffer_size event. Then the
98 compositor must send a done event.
99
100 When the client has received all the buffer constraints, it can create a
101 buffer accordingly, attach it to the capture session using the
102 attach_buffer request, set the buffer damage using the damage_buffer
103 request and then send the capture request.
104 </description>
105
106 <enum name="error">
107 <entry name="duplicate_frame" value="1"
108 summary="create_frame sent before destroying previous frame"/>
109 </enum>
110
111 <event name="buffer_size">
112 <description summary="image capture source dimensions">
113 Provides the dimensions of the source image in buffer pixel coordinates.
114
115 The client must attach buffers that match this size.
116 </description>
117 <arg name="width" type="uint" summary="buffer width"/>
118 <arg name="height" type="uint" summary="buffer height"/>
119 </event>
120
121 <event name="shm_format">
122 <description summary="shm buffer format">
123 Provides the format that must be used for shared-memory buffers.
124
125 This event may be emitted multiple times, in which case the client may
126 choose any given format.
127 </description>
128 <arg name="format" type="uint" enum="wl_shm.format" summary="shm format"/>
129 </event>
130
131 <event name="dmabuf_device">
132 <description summary="dma-buf device">
133 This event advertises the device buffers must be allocated on for
134 dma-buf buffers.
135
136 In general the device is a DRM node. The DRM node type (primary vs.
137 render) is unspecified. Clients must not rely on the compositor sending
138 a particular node type. Clients cannot check two devices for equality
139 by comparing the dev_t value.
140 </description>
141 <arg name="device" type="array" summary="device dev_t value"/>
142 </event>
143
144 <event name="dmabuf_format">
145 <description summary="dma-buf format">
146 Provides the format that must be used for dma-buf buffers.
147
148 The client may choose any of the modifiers advertised in the array of
149 64-bit unsigned integers.
150
151 This event may be emitted multiple times, in which case the client may
152 choose any given format.
153 </description>
154 <arg name="format" type="uint" summary="drm format code"/>
155 <arg name="modifiers" type="array" summary="drm format modifiers"/>
156 </event>
157
158 <event name="done">
159 <description summary="all constraints have been sent">
160 This event is sent once when all buffer constraint events have been
161 sent.
162
163 The compositor must always end a batch of buffer constraint events with
164 this event, regardless of whether it sends the initial constraints or
165 an update.
166 </description>
167 </event>
168
169 <event name="stopped">
170 <description summary="session is no longer available">
171 This event indicates that the capture session has stopped and is no
172 longer available. This can happen in a number of cases, e.g. when the
173 underlying source is destroyed, if the user decides to end the image
174 capture, or if an unrecoverable runtime error has occurred.
175
176 The client should destroy the session after receiving this event.
177 </description>
178 </event>
179
180 <request name="create_frame">
181 <description summary="create a frame">
182 Create a capture frame for this session.
183
184 At most one frame object can exist for a given session at any time. If
185 a client sends a create_frame request before a previous frame object
186 has been destroyed, the duplicate_frame protocol error is raised.
187 </description>
188 <arg name="frame" type="new_id" interface="ext_image_copy_capture_frame_v1"/>
189 </request>
190
191 <request name="destroy" type="destructor">
192 <description summary="delete this object">
193 Destroys the session. This request can be sent at any time by the
194 client.
195
196 This request doesn't affect ext_image_copy_capture_frame_v1 objects created by
197 this object.
198 </description>
199 </request>
200 </interface>
201
202 <interface name="ext_image_copy_capture_frame_v1" version="1">
203 <description summary="image capture frame">
204 This object represents an image capture frame.
205
206 The client should attach a buffer, damage the buffer, and then send a
207 capture request.
208
209 If the capture is successful, the compositor must send the frame metadata
210 (transform, damage, presentation_time in any order) followed by the ready
211 event.
212
213 If the capture fails, the compositor must send the failed event.
214 </description>
215
216 <enum name="error">
217 <entry name="no_buffer" value="1" summary="capture sent without attach_buffer"/>
218 <entry name="invalid_buffer_damage" value="2" summary="invalid buffer damage"/>
219 <entry name="already_captured" value="3" summary="capture request has been sent"/>
220 </enum>
221
222 <request name="destroy" type="destructor">
223 <description summary="destroy this object">
224 Destroys the frame. This request can be sent at any time by the
225 client.
226 </description>
227 </request>
228
229 <request name="attach_buffer">
230 <description summary="attach buffer to session">
231 Attach a buffer to the session.
232
233 The wl_buffer.release request is unused.
234
235 The new buffer replaces any previously attached buffer.
236
237 This request must not be sent after capture, or else the
238 already_captured protocol error is raised.
239 </description>
240 <arg name="buffer" type="object" interface="wl_buffer"/>
241 </request>
242
243 <request name="damage_buffer">
244 <description summary="damage buffer">
245 Apply damage to the buffer which is to be captured next. This request
246 may be sent multiple times to describe a region.
247
248 The client indicates the accumulated damage since this wl_buffer was
249 last captured. During capture, the compositor will update the buffer
250 with at least the union of the region passed by the client and the
251 region advertised by ext_image_copy_capture_frame_v1.damage.
252
253 When a wl_buffer is captured for the first time, or when the client
254 doesn't track damage, the client must damage the whole buffer.
255
256 This is for optimisation purposes. The compositor may use this
257 information to reduce copying.
258
259 These coordinates originate from the upper left corner of the buffer.
260
261 If x or y are strictly negative, or if width or height are negative or
262 zero, the invalid_buffer_damage protocol error is raised.
263
264 This request must not be sent after capture, or else the
265 already_captured protocol error is raised.
266 </description>
267 <arg name="x" type="int" summary="region x coordinate"/>
268 <arg name="y" type="int" summary="region y coordinate"/>
269 <arg name="width" type="int" summary="region width"/>
270 <arg name="height" type="int" summary="region height"/>
271 </request>
272
273 <request name="capture">
274 <description summary="capture a frame">
275 Capture a frame.
276
277 Unless this is the first successful captured frame performed in this
278 session, the compositor may wait an indefinite amount of time for the
279 source content to change before performing the copy.
280
281 This request may only be sent once, or else the already_captured
282 protocol error is raised. A buffer must be attached before this request
283 is sent, or else the no_buffer protocol error is raised.
284 </description>
285 </request>
286
287 <event name="transform">
288 <description summary="buffer transform">
289 This event is sent before the ready event and holds the transform that
290 the compositor has applied to the buffer contents.
291 </description>
292 <arg name="transform" type="uint" enum="wl_output.transform"/>
293 </event>
294
295 <event name="damage">
296 <description summary="buffer damaged region">
297 This event is sent before the ready event. It may be generated multiple
298 times to describe a region.
299
300 The first captured frame in a session will always carry full damage.
301 Subsequent frames' damaged regions describe which parts of the buffer
302 have changed since the last ready event.
303
304 These coordinates originate in the upper left corner of the buffer.
305 </description>
306 <arg name="x" type="int" summary="damage x coordinate"/>
307 <arg name="y" type="int" summary="damage y coordinate"/>
308 <arg name="width" type="int" summary="damage width"/>
309 <arg name="height" type="int" summary="damage height"/>
310 </event>
311
312 <event name="presentation_time">
313 <description summary="presentation time of the frame">
314 This event indicates the time at which the frame is presented to the
315 output in system monotonic time. This event is sent before the ready
316 event.
317
318 The timestamp is expressed as tv_sec_hi, tv_sec_lo, tv_nsec triples,
319 each component being an unsigned 32-bit value. Whole seconds are in
320 tv_sec which is a 64-bit value combined from tv_sec_hi and tv_sec_lo,
321 and the additional fractional part in tv_nsec as nanoseconds. Hence,
322 for valid timestamps tv_nsec must be in [0, 999999999].
323 </description>
324 <arg name="tv_sec_hi" type="uint"
325 summary="high 32 bits of the seconds part of the timestamp"/>
326 <arg name="tv_sec_lo" type="uint"
327 summary="low 32 bits of the seconds part of the timestamp"/>
328 <arg name="tv_nsec" type="uint"
329 summary="nanoseconds part of the timestamp"/>
330 </event>
331
332 <event name="ready">
333 <description summary="frame is available for reading">
334 Called as soon as the frame is copied, indicating it is available
335 for reading.
336
337 The buffer may be re-used by the client after this event.
338
339 After receiving this event, the client must destroy the object.
340 </description>
341 </event>
342
343 <enum name="failure_reason">
344 <entry name="unknown" value="0">
345 <description summary="unknown runtime error">
346 An unspecified runtime error has occurred. The client may retry.
347 </description>
348 </entry>
349 <entry name="buffer_constraints" value="1">
350 <description summary="buffer constraints mismatch">
351 The buffer submitted by the client doesn't match the latest session
352 constraints. The client should re-allocate its buffers and retry.
353 </description>
354 </entry>
355 <entry name="stopped" value="2">
356 <description summary="session is no longer available">
357 The session has stopped. See ext_image_copy_capture_session_v1.stopped.
358 </description>
359 </entry>
360 </enum>
361
362 <event name="failed">
363 <description summary="capture failed">
364 This event indicates that the attempted frame copy has failed.
365
366 After receiving this event, the client must destroy the object.
367 </description>
368 <arg name="reason" type="uint" enum="failure_reason"/>
369 </event>
370 </interface>
371
372 <interface name="ext_image_copy_capture_cursor_session_v1" version="1">
373 <description summary="cursor capture session">
374 This object represents a cursor capture session. It extends the base
375 capture session with cursor-specific metadata.
376 </description>
377
378 <enum name="error">
379 <entry name="duplicate_session" value="1" summary="get_capture_session sent twice"/>
380 </enum>
381
382 <request name="destroy" type="destructor">
383 <description summary="delete this object">
384 Destroys the session. This request can be sent at any time by the
385 client.
386
387 This request doesn't affect ext_image_copy_capture_frame_v1 objects created by
388 this object.
389 </description>
390 </request>
391
392 <request name="get_capture_session">
393 <description summary="get image copy capturer session">
394 Gets the image copy capture session for this cursor session.
395
396 The session will produce frames of the cursor image. The compositor may
397 pause the session when the cursor leaves the captured area.
398
399 This request must not be sent more than once, or else the
400 duplicate_session protocol error is raised.
401 </description>
402 <arg name="session" type="new_id" interface="ext_image_copy_capture_session_v1"/>
403 </request>
404
405 <event name="enter">
406 <description summary="cursor entered captured area">
407 Sent when a cursor enters the captured area. It shall be generated
408 before the "position" and "hotspot" events when and only when a cursor
409 enters the area.
410
411 The cursor enters the captured area when the cursor image intersects
412 with the captured area. Note, this is different from e.g.
413 wl_pointer.enter.
414 </description>
415 </event>
416
417 <event name="leave">
418 <description summary="cursor left captured area">
419 Sent when a cursor leaves the captured area. No "position" or "hotspot"
420 event is generated for the cursor until the cursor enters the captured
421 area again.
422 </description>
423 </event>
424
425 <event name="position">
426 <description summary="position changed">
427 Cursors outside the image capture source do not get captured and no
428 event will be generated for them.
429
430 The given position is the position of the cursor's hotspot and it is
431 relative to the main buffer's top left corner in transformed buffer
432 pixel coordinates. The coordinates may be negative or greater than the
433 main buffer size.
434 </description>
435 <arg name="x" type="int" summary="position x coordinates"/>
436 <arg name="y" type="int" summary="position y coordinates"/>
437 </event>
438
439 <event name="hotspot">
440 <description summary="hotspot changed">
441 The hotspot describes the offset between the cursor image and the
442 position of the input device.
443
444 The given coordinates are the hotspot's offset from the origin in
445 buffer coordinates.
446
447 Clients should not apply the hotspot immediately: the hotspot becomes
448 effective when the next ext_image_copy_capture_frame_v1.ready event is received.
449
450 Compositors may delay this event until the client captures a new frame.
451 </description>
452 <arg name="x" type="int" summary="hotspot x coordinates"/>
453 <arg name="y" type="int" summary="hotspot y coordinates"/>
454 </event>
455 </interface>
456</protocol>