Copyright © 2021-2022 Andri Yngvason 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. This protocol allows clients to ask the compositor to capture screen contents to user submitted buffers. Warning! The protocol described in this file is experimental and backward incompatible changes may be made. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes are done by bumping the version number in the protocol and interface names and resetting the interface version. Once the protocol is to be declared stable, the 'z' prefix and the version number in the protocol and interface names are removed and the interface version number is reset. This object is a manager which offers requests to start capturing from a source. Create a capturing session for an image source. If the "render_cursors" flag is set, cursors shall be composited onto the captured frame. The cursor should not be composited onto the frame if this flag is not set. Create a cursor capturing session for an image source. The options argument has no effect and should be set to 0. This is intended for any future flags that might be added. This is the frame capturing interface. It keeps track of changes between frames. After a screencopy session is created, buffer constraint events will be emitted from the compositor to tell the client which buffer types and formats are supported for reading from the session. When the client knows all the buffer attributes, it can create a buffer, attach it to the screencopy session using the "attach_buffer" request, set the buffer damage using the "damage_buffer" request and then call the "commit" request. After copying, a series of events will be generated, ending with the "ready" event, which means that the buffer is ready to be used and a buffer may be committed to the session again. The buffer may be re-used after the "ready" event. The "wl_buffer.release" event is not used. The compositor should present frames to the client at a steady rate, unless otherwise instructed (see "on_damage" option). A client wishing to capture all frames without missing any of them, should commit a new buffer immediately after receiving the "ready" event. The "failed" event may be sent at any time. When this happens, the client must destroy the session. Depending on the failure reason, the client can create a new session to replace it. Provides the format that must be used for shm buffers. This may be emitted multiple times, in which case the client may choose any given format. Provides the format that must be used for dma buffers. This may be emitted multiple times, in which case the client may choose any given format. Provides the dimensions of the source image in buffer pixel coordinates. The client must submit buffers that are large enough for the source image. This event is sent once when all constraint events have been sent. Attach a buffer to the session. The buffer must satisfy the constraints given by the "buffer_constraints_shm" and "buffer_constraints_dmabuf" events. If an over-sized buffer is committed, the compositor will place the image into the top left corner of the buffer. Apply damage to the buffer which is to be committed next. This is for optimisation purposes. The compositor may use this information to reduce copying. The client must submit damage if it's using multiple buffers. Otherwise, the server might not copy into damaged regions of the buffer. These coordinates originate in the upper left corner of the buffer. Commit the screencopy session. The frame will be copied to the attached buffer on next output commit. A ready event is generated when the buffer is ready. If the "on_damage" flag is set, the compositor should skip sending new frames to the client until there is damage. Destroys the session. This request can be sent at any time by the client. This event is sent before the ready event and holds the output transform of the source buffer. This event is sent before the ready event. It may be generated multiple times for each commit. A capture session's initial damage encompasses the whole captured area. The arguments describe a box around an area that has changed since the last ready event. These coordinates originate in the upper left corner of the buffer. This event indicates that the attempted frame copy has failed. After receiving this event, the client must destroy the object. This event indicates the time at which the frame is presented to the output in system monotonic time. The timestamp is expressed as tv_sec_hi, tv_sec_lo, tv_nsec triples, each component being an unsigned 32-bit value. Whole seconds are in tv_sec which is a 64-bit value combined from tv_sec_hi and tv_sec_lo, and the additional fractional part in tv_nsec as nanoseconds. Hence, for valid timestamps tv_nsec must be in [0, 999999999]. Called as soon as the frame is copied, indicating it is available for reading. The buffer may be re-used by the client after the "ready" event. Gets the screencopy session for this cursor session. Sent when a cursor enters the captured area. It shall be generated before the "position" and "hotspot" events when and only when a cursor enters the area. Sent when a cursor leaves the captured area. No "position" or "hotspot" event is generated for the cursor. Cursors outside the image source do not get captured and no event will be generated for them. The given position is the position of the cursor's hotspot and it is relative to the main buffer's top left corner in transformed buffer pixel coordinates. The hotspot coordinates are relative to the cursor buffers upper left corner. The given coordinates are the hotspot's offset from the origin in buffer coordinates.