diff --git a/stable/linux-dmabuf/linux-dmabuf-v1.xml b/stable/linux-dmabuf/linux-dmabuf-v1.xml index 12d09fb..647000f 100644 --- a/stable/linux-dmabuf/linux-dmabuf-v1.xml +++ b/stable/linux-dmabuf/linux-dmabuf-v1.xml @@ -24,7 +24,7 @@ DEALINGS IN THE SOFTWARE. - + This interface offers ways to create generic dmabuf-based wl_buffers. @@ -184,7 +184,7 @@ - + This temporary object is a collection of dmabufs and other parameters that together form a single logical buffer. The temporary @@ -394,9 +394,25 @@ + + + + Set the device the compositor should import the dmabufs to for sampling + in the next create or create_immed request. + + To avoid race conditions when the compositor removes a device from the + tranches, it is not a protocol error if the device hasn't been advertised + by the compositor in a tranche with the sampling flag, but the import is + likely to fail in that case. + + If the client doesn't know a suitable target device, it shouldn't set one, + and the compositor should attempt import on all devices it supports. + + + - + This object advertises dmabuf parameters feedback. This includes the preferred devices and the supported formats/modifiers. @@ -419,10 +435,13 @@ descending order of preference. All formats and modifiers in the same tranche have the same preference. - To send parameters, the compositor sends one main_device event, tranches - (each consisting of one tranche_target_device event, one tranche_flags - event, tranche_formats events and then a tranche_done event), then one - done event. + To send parameters, the compositor sends one main_device event (unless + the client bound version 6 or above), tranches (each consisting of one + tranche_target_device event, one tranche_flags event, tranche_formats + events and then a tranche_done event), then one done event. + + With version 6 and above, the compositor must always advertise at least + one tranche with the sampling flag set. @@ -463,7 +482,7 @@ - + This event advertises the main device that the server prefers to use when direct scan-out to the target device isn't possible. The @@ -488,6 +507,9 @@ If explicit modifiers are not supported and the client performs buffer allocations on a different device than the main device, then the client must force the buffer to have a linear layout. + + With version 6 and above, this event is no longer sent. Clients should + use a device with the sampling flag in the tranches instead. @@ -516,9 +538,9 @@ The client can use this hint to allocate the buffer in a way that makes it accessible from the target device, ideally directly. The buffer must - still be accessible from the main device, either through direct import - or through a potentially more expensive fallback path. If the buffer - can't be directly imported from the main device then clients must be + still be accessible from a device with the sampling flag, either through + direct import or a potentially more expensive fallback path. If the + buffer can't be directly imported for sampling, then clients must be prepared for the compositor changing the tranche priority or making wl_buffer creation fail (see the wp_linux_buffer_params.create and create_immed requests for details). @@ -564,19 +586,30 @@ - + + + The scanout flag is a hint that direct scan-out may be attempted by + the compositor on the target device if the client appropriately + allocates a buffer. How to allocate a buffer that can be scanned out + on the target device is implementation-defined. + + + + + The sampling flag describes that the compositor is able to efficiently + sample from buffers imported to the target device if the client + appropriately allocates a buffer. How to allocate a buffer that can be + efficiently sampled on the target device is implementation defined. + + - This event sets tranche-specific flags. - - The scanout flag is a hint that direct scan-out may be attempted by the - compositor on the target device if the client appropriately allocates a - buffer. How to allocate a buffer that can be scanned out on the target - device is implementation-defined. - - This event is tied to a preference tranche, see the tranche_done event. + This event sets tranche-specific flags. This event is tied to a + preference tranche, see the tranche_done event. + With version 6 and above, the compositor must set at least one flag + in each tranche.