1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="wlr_export_dmabuf_unstable_v1">
3 <copyright>
4 Copyright © 2018 Rostislav Pehlivanov
5
6 Permission is hereby granted, free of charge, to any person obtaining a
7 copy of this software and associated documentation files (the "Software"),
8 to deal in the Software without restriction, including without limitation
9 the rights to use, copy, modify, merge, publish, distribute, sublicense,
10 and/or sell copies of the Software, and to permit persons to whom the
11 Software is furnished to do so, subject to the following conditions:
12
13 The above copyright notice and this permission notice (including the next
14 paragraph) shall be included in all copies or substantial portions of the
15 Software.
16
17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
23 DEALINGS IN THE SOFTWARE.
24 </copyright>
25
26 <description summary="a protocol for low overhead screen content capturing">
27 An interface to capture surfaces in an efficient way by exporting DMA-BUFs.
28
29 Warning! The protocol described in this file is experimental and
30 backward incompatible changes may be made. Backward compatible changes
31 may be added together with the corresponding interface version bump.
32 Backward incompatible changes are done by bumping the version number in
33 the protocol and interface names and resetting the interface version.
34 Once the protocol is to be declared stable, the 'z' prefix and the
35 version number in the protocol and interface names are removed and the
36 interface version number is reset.
37 </description>
38
39 <interface name="zwlr_export_dmabuf_manager_v1" version="1">
40 <description summary="manager to inform clients and begin capturing">
41 This object is a manager with which to start capturing from sources.
42 </description>
43
44 <request name="capture_output">
45 <description summary="capture a frame from an output">
46 Capture the next frame of an entire output.
47 </description>
48 <arg name="frame" type="new_id" interface="zwlr_export_dmabuf_frame_v1"/>
49 <arg name="overlay_cursor" type="int"
50 summary="include custom client hardware cursor on top of the frame"/>
51 <arg name="output" type="object" interface="wl_output"/>
52 </request>
53
54 <request name="destroy" type="destructor">
55 <description summary="destroy the manager">
56 All objects created by the manager will still remain valid, until their
57 appropriate destroy request has been called.
58 </description>
59 </request>
60 </interface>
61
62 <interface name="zwlr_export_dmabuf_frame_v1" version="1">
63 <description summary="a DMA-BUF frame">
64 This object represents a single DMA-BUF frame.
65
66 If the capture is successful, the compositor will first send a "frame"
67 event, followed by one or several "object". When the frame is available
68 for readout, the "ready" event is sent.
69
70 If the capture failed, the "cancel" event is sent. This can happen anytime
71 before the "ready" event.
72
73 Once either a "ready" or a "cancel" event is received, the client should
74 destroy the frame. Once an "object" event is received, the client is
75 responsible for closing the associated file descriptor.
76
77 All frames are read-only and may not be written into or altered.
78 </description>
79
80 <enum name="flags">
81 <description summary="frame flags">
82 Special flags that should be respected by the client.
83 </description>
84 <entry name="transient" value="0x1"
85 summary="clients should copy frame before processing"/>
86 </enum>
87
88 <event name="frame">
89 <description summary="a frame description">
90 Main event supplying the client with information about the frame. If the
91 capture didn't fail, this event is always emitted first before any other
92 events.
93
94 This event is followed by a number of "object" as specified by the
95 "num_objects" argument.
96 </description>
97 <arg name="width" type="uint"
98 summary="frame width in pixels"/>
99 <arg name="height" type="uint"
100 summary="frame height in pixels"/>
101 <arg name="offset_x" type="uint"
102 summary="crop offset for the x axis"/>
103 <arg name="offset_y" type="uint"
104 summary="crop offset for the y axis"/>
105 <arg name="buffer_flags" type="uint"
106 summary="flags which indicate properties (invert, interlacing),
107 has the same values as zwp_linux_buffer_params_v1:flags"/>
108 <arg name="flags" type="uint" enum="flags"
109 summary="indicates special frame features"/>
110 <arg name="format" type="uint"
111 summary="format of the frame (DRM_FORMAT_*)"/>
112 <arg name="mod_high" type="uint"
113 summary="drm format modifier, high"/>
114 <arg name="mod_low" type="uint"
115 summary="drm format modifier, low"/>
116 <arg name="num_objects" type="uint"
117 summary="indicates how many objects (FDs) the frame has (max 4)"/>
118 </event>
119
120 <event name="object">
121 <description summary="an object description">
122 Event which serves to supply the client with the file descriptors
123 containing the data for each object.
124
125 After receiving this event, the client must always close the file
126 descriptor as soon as they're done with it and even if the frame fails.
127 </description>
128 <arg name="index" type="uint"
129 summary="index of the current object"/>
130 <arg name="fd" type="fd"
131 summary="fd of the current object"/>
132 <arg name="size" type="uint"
133 summary="size in bytes for the current object"/>
134 <arg name="offset" type="uint"
135 summary="starting point for the data in the object's fd"/>
136 <arg name="stride" type="uint"
137 summary="line size in bytes"/>
138 <arg name="plane_index" type="uint"
139 summary="index of the plane the data in the object applies to"/>
140 </event>
141
142 <event name="ready">
143 <description summary="indicates frame is available for reading">
144 This event is sent as soon as the frame is presented, indicating it is
145 available for reading. This event includes the time at which
146 presentation happened at.
147
148 The timestamp is expressed as tv_sec_hi, tv_sec_lo, tv_nsec triples,
149 each component being an unsigned 32-bit value. Whole seconds are in
150 tv_sec which is a 64-bit value combined from tv_sec_hi and tv_sec_lo,
151 and the additional fractional part in tv_nsec as nanoseconds. Hence,
152 for valid timestamps tv_nsec must be in [0, 999999999]. The seconds part
153 may have an arbitrary offset at start.
154
155 After receiving this event, the client should destroy this object.
156 </description>
157 <arg name="tv_sec_hi" type="uint"
158 summary="high 32 bits of the seconds part of the timestamp"/>
159 <arg name="tv_sec_lo" type="uint"
160 summary="low 32 bits of the seconds part of the timestamp"/>
161 <arg name="tv_nsec" type="uint"
162 summary="nanoseconds part of the timestamp"/>
163 </event>
164
165 <enum name="cancel_reason">
166 <description summary="cancel reason">
167 Indicates reason for cancelling the frame.
168 </description>
169 <entry name="temporary" value="0"
170 summary="temporary error, source will produce more frames"/>
171 <entry name="permanent" value="1"
172 summary="fatal error, source will not produce frames"/>
173 <entry name="resizing" value="2"
174 summary="temporary error, source will produce more frames"/>
175 </enum>
176
177 <event name="cancel">
178 <description summary="indicates the frame is no longer valid">
179 If the capture failed or if the frame is no longer valid after the
180 "frame" event has been emitted, this event will be used to inform the
181 client to scrap the frame.
182
183 If the failure is temporary, the client may capture again the same
184 source. If the failure is permanent, any further attempts to capture the
185 same source will fail again.
186
187 After receiving this event, the client should destroy this object.
188 </description>
189 <arg name="reason" type="uint" enum="cancel_reason"
190 summary="indicates a reason for cancelling this frame capture"/>
191 </event>
192
193 <request name="destroy" type="destructor">
194 <description summary="delete this object, used or not">
195 Unreferences the frame. This request must be called as soon as it's no
196 longer used.
197
198 It can be called at any time by the client. The client will still have
199 to close any FDs it has been given.
200 </description>
201 </request>
202 </interface>
203</protocol>