zwp_linux_explicit_synchronization_unstable_v1 Module

ZwpLinuxSurfaceSynchronizationV1

class pywayland.protocol.zwp_linux_explicit_synchronization_unstable_v1.ZwpLinuxSurfaceSynchronizationV1

Per-surface explicit synchronization support

This object implements per-surface explicit synchronization.

Synchronization refers to co-ordination of pipelined operations performed on buffers. Most GPU clients will schedule an asynchronous operation to render to the buffer, then immediately send the buffer to the compositor to be attached to a surface.

In implicit synchronization, ensuring that the rendering operation is complete before the compositor displays the buffer is an implementation detail handled by either the kernel or userspace graphics driver.

By contrast, in explicit synchronization, dma_fence objects mark when the asynchronous operations are complete. When submitting a buffer, the client provides an acquire fence which will be waited on before the compositor accesses the buffer. The Wayland server, through a ZwpLinuxBufferReleaseV1 object, will inform the client with an event which may be accompanied by a release fence, when the compositor will no longer access the buffer contents due to the specific commit that requested the release event.

Each surface can be associated with only one object of this interface at any time.

In version 1 of this interface, explicit synchronization is only guaranteed to be supported for buffers created with any version of the wp_linux_dmabuf buffer factory. Version 2 additionally guarantees explicit synchronization support for opaque EGL buffers, which is a type of platform specific buffers described in the EGL_WL_bind_wayland_display extension. Compositors are free to support explicit synchronization for additional buffer types.

destroy()

Request – opcode 0 (attached to Resource instance)

Destroy synchronization object

Destroy this explicit synchronization object.

Any fence set by this object with set_acquire_fence since the last commit will be discarded by the server. Any fences set by this object before the last commit are not affected.

ZwpLinuxBufferReleaseV1 objects created by this object are not affected by this request.

set_acquire_fence(fd)

Request – opcode 1 (attached to Resource instance)

Set the acquire fence

Set the acquire fence that must be signaled before the compositor may sample from the buffer attached with WlSurface.attach(). The fence is a dma_fence kernel object.

The acquire fence is double-buffered state, and will be applied on the next WlSurface.commit() request for the associated surface. Thus, it applies only to the buffer that is attached to the surface at commit time.

If the provided fd is not a valid dma_fence fd, then an INVALID_FENCE error is raised.

If a fence has already been attached during the same commit cycle, a DUPLICATE_FENCE error is raised.

If the associated WlSurface was destroyed, a NO_SURFACE error is raised.

If at surface commit time the attached buffer does not support explicit synchronization, an UNSUPPORTED_BUFFER error is raised.

If at surface commit time there is no buffer attached, a NO_BUFFER error is raised.

Parameters:fd (fd) – acquire fence fd
get_release()

Request – opcode 2 (attached to Resource instance)

Release fence for last-attached buffer

Create a listener for the release of the buffer attached by the client with WlSurface.attach(). See ZwpLinuxBufferReleaseV1 documentation for more information.

The release object is double-buffered state, and will be associated with the buffer that is attached to the surface at WlSurface.commit() time.

If a ZwpLinuxBufferReleaseV1 object has already been requested for the surface in the same commit cycle, a DUPLICATE_RELEASE error is raised.

If the associated WlSurface was destroyed, a NO_SURFACE error is raised.

If at surface commit time there is no buffer attached, a NO_BUFFER error is raised.

Returns:ZwpLinuxBufferReleaseV1 – new ZwpLinuxBufferReleaseV1 object

ZwpLinuxBufferReleaseV1

class pywayland.protocol.zwp_linux_explicit_synchronization_unstable_v1.ZwpLinuxBufferReleaseV1

Buffer release explicit synchronization

This object is instantiated in response to a ZwpLinuxSurfaceSynchronizationV1.get_release() request.

It provides an alternative to WlBuffer.release() events, providing a unique release from a single WlSurface.commit() request. The release event also supports explicit synchronization, providing a fence FD for the client to synchronize against.

Exactly one event, either a fenced_release or an immediate_release, will be emitted for the WlSurface.commit() request. The compositor can choose release by release which event it uses.

This event does not replace WlBuffer.release() events; servers are still required to send those events.

Once a buffer release object has delivered a ‘fenced_release’ or an ‘immediate_release’ event it is automatically destroyed.

fenced_release(fence)

Event – opcode 0 (attached to Proxy instance)

Release buffer with fence

Sent when the compositor has finalised its usage of the associated buffer for the relevant commit, providing a dma_fence which will be signaled when all operations by the compositor on that buffer for that commit have finished.

Once the fence has signaled, and assuming the associated buffer is not pending release from other WlSurface.commit() requests, no additional explicit or implicit synchronization is required to safely reuse or destroy the buffer.

This event destroys the ZwpLinuxBufferReleaseV1 object.

Parameters:fence (fd) – fence for last operation on buffer
immediate_release()

Event – opcode 1 (attached to Proxy instance)

Release buffer immediately

Sent when the compositor has finalised its usage of the associated buffer for the relevant commit, and either performed no operations using it, or has a guarantee that all its operations on that buffer for that commit have finished.

Once this event is received, and assuming the associated buffer is not pending release from other WlSurface.commit() requests, no additional explicit or implicit synchronization is required to safely reuse or destroy the buffer.

This event destroys the ZwpLinuxBufferReleaseV1 object.

ZwpLinuxExplicitSynchronizationV1

class pywayland.protocol.zwp_linux_explicit_synchronization_unstable_v1.ZwpLinuxExplicitSynchronizationV1

Protocol for providing explicit synchronization

This global is a factory interface, allowing clients to request explicit synchronization for buffers on a per-surface basis.

See ZwpLinuxSurfaceSynchronizationV1 for more information.

This interface is derived from Chromium’s zcr_linux_explicit_synchronization_v1.

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.

destroy()

Request – opcode 0 (attached to Resource instance)

Destroy explicit synchronization factory object

Destroy this explicit synchronization factory object. Other objects, including ZwpLinuxSurfaceSynchronizationV1 objects created by this factory, shall not be affected by this request.

get_synchronization(surface)

Request – opcode 1 (attached to Resource instance)

Extend surface interface for explicit synchronization

Instantiate an interface extension for the given WlSurface to provide explicit synchronization.

If the given WlSurface already has an explicit synchronization object associated, the synchronization_exists protocol error is raised.

Graphics APIs, like EGL or Vulkan, that manage the buffer queue and commits of a WlSurface themselves, are likely to be using this extension internally. If a client is using such an API for a WlSurface, it should not directly use this extension on that surface, to avoid raising a synchronization_exists protocol error.

Parameters:surface (WlSurface) – the surface
Returns:ZwpLinuxSurfaceSynchronizationV1 – the new synchronization interface id