Weston output capture

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.

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.