1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="weston_output_capture">
<copyright>
Copyright 2020, 2022 Collabora, Ltd.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
</copyright>
<interface name="weston_capture_v1" version="1">
<description summary="image capture factory">
The global interface exposing Weston screenshooting functionality
intended for single shots.
This is a privileged inteface.
</description>
<request name="destroy" type="destructor">
<description summary="unbind image capture factory">
Affects no other protocol objects in any way.
</description>
</request>
<enum name="error">
<entry name="invalid_source" value="0"
summary="invalid source enum value"/>
</enum>
<enum name="source">
<entry name="writeback" value="0" summary="use hardware writeback"/>
<entry name="framebuffer" value="1"
summary="copy from framebuffer, desktop area"/>
<entry name="full_framebuffer" value="2"
summary="copy whole framebuffer, including borders"/>
<entry name="blending" value="3" summary="copy from blending space"/>
</enum>
<request name="create">
<description summary="create an object for capturing output images">
This creates a weston_capture_source_v1 object corresponding to the
given wl_output. The object delivers information for allocating
suitable buffers, and exposes the capture function.
The object will be using the given pixel source for capturing images.
If the source is not available, all attempts to capture will fail
gracefully.
'writeback' source will use hardware writeback feature of DRM KMS for
capturing. This may allow hardware planes to remain used
during the capture. This source is often not available.
'framebuffer' source copies the contents of the final framebuffer.
Using this source temporarily disables all use of hardware planes and
DRM KMS color pipeline features. This source is always available.
'full_framebuffer' is otherwise the same as 'framebuffer' except it
will include also any borders (decorations) that the framebuffer may
contain.
'blending' source copies the contents of the intermediate blending
buffer, which should be in linear-light format. Using this source
temporarily disables all use of hardware planes. This source is only
available when a blending buffer exists, e.g. when color management
is active on the output.
If the pixel source is not one of the defined enumeration values,
'invalid_source' protocol error is raised.
</description>
<arg name="output" type="object" interface="wl_output"
summary="output to shoot"/>
<arg name="source" type="uint" enum="source" summary="pixel source"/>
<arg name="capture_source_new_id" type="new_id"
interface="weston_capture_source_v1" summary="new object"/>
</request>
</interface>
<interface name="weston_capture_source_v1" version="1">
<description summary="image capturing source">
An object representing image capturing functionality for a single
source. When created, it sends the initial events if and only if the
output still exists and the specified pixel source is available on
the output.
</description>
<enum name="error">
<entry name="bad_buffer" value="0"
summary="the wl_buffer is not writable"/>
<entry name="sequence" value="1"
summary="capture requested again before previous retired"/>
</enum>
<request name="destroy" type="destructor">
<description summary="cancel the capture, and destroy">
If a capture is on-going on this object, this will cancel it and
make the image buffer contents undefined.
This object is destroyed.
</description>
</request>
<request name="capture">
<description summary="capture an image">
If the given wl_buffer is compatible, the associated output will go
through a repaint some time after this request has been processed,
and that repaint will execute the capture.
Once the capture is complete, 'complete' event is emitted.
If the given wl_buffer is incompatible, the event 'retry' is
emitted.
If the capture fails or the buffer type is unsupported, the event
'failed' is emitted.
The client must wait for one of these events before attempting
'capture' on this object again. If 'capture' is requested again before
any of those events, 'sequence' protocol error is raised.
The wl_buffer object will not emit wl_buffer.release event due to
this request.
The wl_buffer must refer to compositor-writable storage. If buffer
storage is not writable, either the protocol error bad_buffer or
wl_shm.error.invalid_fd is raised.
If the wl_buffer is destroyed before any event is emitted, the buffer
contents become undefined.
A compositor is required to implement capture into wl_shm buffers.
Other buffer types may or may not be supported.
</description>
<arg name="buffer" type="object" interface="wl_buffer"
summary="a writable image buffer"/>
</request>
<event name="format">
<description summary="pixel format for a buffer">
This event delivers the pixel format that should be used for the
image buffer. Any buffer is incompatible if it does not have
this pixel format.
The format modifier is linear (DRM_FORMAT_MOD_LINEAR).
This is an initial event, and sent whenever the required format
changes.
</description>
<arg name="drm_format" type="uint" summary="DRM pixel format code"/>
</event>
<event name="size">
<description summary="dimensions for a buffer">
This event delivers the size that should be used for the
image buffer. Any buffer is incompatible if it does not have
this size.
Row alignment of the buffer must be 4 bytes, and it must not contain
further row padding. Otherwise the buffer is unsupported.
This is an initial event, and sent whenever the required size
changes.
</description>
<arg name="width" type="int" summary="width in pixels"/>
<arg name="height" type="int" summary="height in pixels"/>
</event>
<event name="complete">
<description summary="capture has completed">
This event is emitted as a response to 'capture' request when it
has successfully completed.
If the buffer used in the shot is a dmabuf, the client also needs to
wait for any implicit fences on it before accessing the contents.
</description>
</event>
<event name="retry">
<description summary="retry image capture with a different buffer">
This event is emitted as a response to 'capture' request when it
cannot succeed due to an incompatible buffer. The client has already
received the events delivering the new buffer parameters. The client
should retry the capture with the new buffer parameters.
</description>
</event>
<event name="failed">
<description summary="capture failed">
This event is emitted as a response to 'capture' request when it
has failed for reasons other than an incompatible buffer. The reasons
may include: unsupported buffer type, unsupported buffer stride,
unsupported image source, the image source (output) was removed, or
compositor policy denied the capture.
The string 'msg' may contain a human-readable explanation of the
failure to aid debugging.
</description>
<arg name="msg" type="string" allow-null="true"
summary="human-readable hint"/>
</event>
</interface>
</protocol>
|
