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. The global interface exposing Weston screenshooting functionality intended for single shots. This is a privileged inteface. Affects no other protocol objects in any way. 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. 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. If a capture is on-going on this object, this will cancel it and make the image buffer contents undefined. This object is destroyed. 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. 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. 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. 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. 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. 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.