diff --git a/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml b/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml index 1ac4369..41d8fe5 100644 --- a/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml +++ b/staging/ext-image-copy-capture/ext-image-copy-capture-v1.xml @@ -199,7 +199,7 @@ - + This object represents an image capture frame. @@ -211,12 +211,31 @@ event. If the capture fails, the compositor must send the failed event. + + Explicit synchronization may be enabled by setting an acquire and a + release timeline point before calling capture. Both points must be set, + or else the no_acquire_point or no_release_point protocol error is raised. + If neither is set the compositor falls back to implicit synchronization, + preserving backwards compatibility with version 1 compositors and clients. + + The acquire and release timeline points must come from timeline objects + imported via wp_linux_drm_syncobj_manager_v1.import_timeline from the + linux-drm-syncobj-v1 protocol. Explicit synchronization is guaranteed for + dma-buf buffers. Compositors may support it for other buffer types. + + + + @@ -281,6 +300,9 @@ This request may only be sent once, or else the already_captured protocol error is raised. A buffer must be attached before this request is sent, or else the no_buffer protocol error is raised. + + If an acquire or release timeline point has been set, both must be set + or the no_acquire_point or no_release_point protocol error is raised. @@ -336,6 +358,10 @@ The buffer may be re-used by the client after this event. + When explicit synchronization is in use, the delivery of this event + becomes undefined. Clients must instead wait for the release timeline + point to be signalled before accessing the buffer contents. + After receiving this event, the client must destroy the object. @@ -367,6 +393,68 @@ + + + + Set the timeline point the compositor must wait for before it may write + captured content into the buffer. + + The compositor waits on this point before beginning the write into + the attached buffer. The client must signal this point once it has + finished any reads from a previous use of the same buffer, so the + compositor may safely overwrite it. + + The 64-bit unsigned value combined from point_hi and point_lo is the + point value. + + This request must not be sent after capture, or else the + already_captured protocol error is raised. + + If at capture time a release point has been set but no acquire point + has been set, the no_acquire_point protocol error is raised. + + If at capture time the acquire and release timelines are identical, + the acquire point value must be strictly less than the release point + value, or else the conflicting_points protocol error is raised. + + + + + + + + + Set the timeline point the compositor will signal once it has finished + writing captured content into the buffer. + + After this point is signalled the client may safely access the captured + buffer contents without additional synchronization. + + Because signalling a timeline point also signals every earlier point, + it is strongly recommended that each buffer use a dedicated timeline for + its release points. Reusing the same timeline for multiple buffers' + release points risks a release point being signalled before the + compositor has finished writing, if the compositor signals them out of + submission order. + + The 64-bit unsigned value combined from point_hi and point_lo is the + point value. + + This request must not be sent after capture, or else the + already_captured protocol error is raised. + + If at capture time an acquire point has been set but no release point + has been set, the no_release_point protocol error is raised. + + If at capture time the attached buffer does not support explicit + synchronization, the unsupported_buffer protocol error is raised. + + + + +