--- /srv/reproducible-results/rbuild-debian/r-b-build.WrDOrgL9/b1/pywayland_0.4.18-1_i386.changes +++ /srv/reproducible-results/rbuild-debian/r-b-build.WrDOrgL9/b2/pywayland_0.4.18-1_i386.changes ├── Files │ @@ -1,4 +1,4 @@ │ │ 7b7337a70f90f24cade7bcfd19981e72 38912 debug optional python3-pywayland-dbgsym_0.4.18-1_i386.deb │ - d10e4e77ceb112321a70d3695d71d8d2 51644 doc optional python3-pywayland-doc_0.4.18-1_all.deb │ - c067e7a12cba61a3840d5f58ee6dd187 119436 python optional python3-pywayland_0.4.18-1_i386.deb │ + ed30936179ad036fe6973f65cc2525a7 51980 doc optional python3-pywayland-doc_0.4.18-1_all.deb │ + 75f203e8379ba77d4f71439b91e472ed 119752 python optional python3-pywayland_0.4.18-1_i386.deb ├── python3-pywayland-doc_0.4.18-1_all.deb │ ├── file list │ │ @@ -1,3 +1,3 @@ │ │ -rw-r--r-- 0 0 0 4 2024-10-11 20:38:19.000000 debian-binary │ │ -rw-r--r-- 0 0 0 1304 2024-10-11 20:38:19.000000 control.tar.xz │ │ --rw-r--r-- 0 0 0 50148 2024-10-11 20:38:19.000000 data.tar.xz │ │ +-rw-r--r-- 0 0 0 50484 2024-10-11 20:38:19.000000 data.tar.xz │ ├── control.tar.xz │ │ ├── control.tar │ │ │ ├── ./md5sums │ │ │ │ ├── ./md5sums │ │ │ │ │┄ Files differ │ ├── data.tar.xz │ │ ├── data.tar │ │ │ ├── file list │ │ │ │ @@ -12,15 +12,15 @@ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 1092 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/text/index.txt │ │ │ │ -rw-r--r-- 0 root (0) root (0) 1693 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/text/install.txt.gz │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/text/module/ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 2629 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/text/module/client.txt.gz │ │ │ │ -rw-r--r-- 0 root (0) root (0) 515 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/text/module/index.txt │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/text/module/protocol/ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 482 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/text/module/protocol/index.txt │ │ │ │ --rw-r--r-- 0 root (0) root (0) 30286 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/text/module/protocol/wayland.txt.gz │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 30610 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/text/module/protocol/wayland.txt.gz │ │ │ │ -rw-r--r-- 0 root (0) root (0) 1839 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/text/module/protocol_core.txt.gz │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/text/module/scanner/ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 1018 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/text/module/scanner/argument.txt │ │ │ │ -rw-r--r-- 0 root (0) root (0) 405 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/text/module/scanner/entry.txt │ │ │ │ -rw-r--r-- 0 root (0) root (0) 358 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/text/module/scanner/enum.txt │ │ │ │ -rw-r--r-- 0 root (0) root (0) 688 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/text/module/scanner/event.txt │ │ │ │ -rw-r--r-- 0 root (0) root (0) 296 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/text/module/scanner/index.txt │ │ │ ├── ./usr/share/doc/python3-pywayland/text/module/protocol/index.txt │ │ │ │┄ Ordering differences only │ │ │ │ @@ -2,50 +2,50 @@ │ │ │ │ **************** │ │ │ │ │ │ │ │ Wayland protocols built against Wayland 1.21.0 and Wayland Protocols │ │ │ │ 1.25. │ │ │ │ │ │ │ │ * wayland Module │ │ │ │ │ │ │ │ - * WlDataSource │ │ │ │ + * WlDisplay │ │ │ │ │ │ │ │ - * WlSubsurface │ │ │ │ + * WlCallback │ │ │ │ + │ │ │ │ + * WlDataOffer │ │ │ │ + │ │ │ │ + * WlTouch │ │ │ │ + │ │ │ │ + * WlCompositor │ │ │ │ │ │ │ │ * WlDataDevice │ │ │ │ │ │ │ │ - * WlShellSurface │ │ │ │ + * WlShmPool │ │ │ │ │ │ │ │ - * WlSurface │ │ │ │ + * WlShellSurface │ │ │ │ │ │ │ │ - * WlTouch │ │ │ │ + * WlOutput │ │ │ │ │ │ │ │ - * WlRegion │ │ │ │ + * WlRegistry │ │ │ │ │ │ │ │ - * WlSubcompositor │ │ │ │ + * WlDataSource │ │ │ │ │ │ │ │ * WlPointer │ │ │ │ │ │ │ │ - * WlDataOffer │ │ │ │ + * WlDataDeviceManager │ │ │ │ │ │ │ │ - * WlSeat │ │ │ │ + * WlShm │ │ │ │ │ │ │ │ * WlBuffer │ │ │ │ │ │ │ │ - * WlCompositor │ │ │ │ + * WlSurface │ │ │ │ │ │ │ │ - * WlCallback │ │ │ │ + * WlSubsurface │ │ │ │ │ │ │ │ * WlKeyboard │ │ │ │ │ │ │ │ - * WlOutput │ │ │ │ - │ │ │ │ - * WlRegistry │ │ │ │ - │ │ │ │ - * WlDataDeviceManager │ │ │ │ + * WlSeat │ │ │ │ │ │ │ │ * WlShell │ │ │ │ │ │ │ │ - * WlShm │ │ │ │ - │ │ │ │ - * WlDisplay │ │ │ │ + * WlRegion │ │ │ │ │ │ │ │ - * WlShmPool │ │ │ │ + * WlSubcompositor │ │ │ ├── ./usr/share/doc/python3-pywayland/text/module/protocol/wayland.txt.gz │ │ │ │ ├── wayland.txt │ │ │ │ │┄ Ordering differences only │ │ │ │ │ @@ -1,387 +1,583 @@ │ │ │ │ │ wayland Module │ │ │ │ │ ************** │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ -WlDataSource │ │ │ │ │ -============ │ │ │ │ │ +WlDisplay │ │ │ │ │ +========= │ │ │ │ │ │ │ │ │ │ -class pywayland.protocol.wayland.WlDataSource │ │ │ │ │ +class pywayland.protocol.wayland.WlDisplay │ │ │ │ │ │ │ │ │ │ - Offer to transfer data │ │ │ │ │ + Core global object │ │ │ │ │ │ │ │ │ │ - The "WlDataSource" object is the source side of a "WlDataOffer". It │ │ │ │ │ - is created by the source client in a data transfer and provides a │ │ │ │ │ - way to describe the offered data and a way to respond to requests │ │ │ │ │ - to transfer the data. │ │ │ │ │ + The core global object. This is a special singleton object. It is │ │ │ │ │ + used for internal Wayland protocol features. │ │ │ │ │ │ │ │ │ │ - offer(mime_type: 'str') -> 'None' │ │ │ │ │ + sync() -> 'Proxy[WlCallback]' │ │ │ │ │ │ │ │ │ │ -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Add an offered mime type │ │ │ │ │ + Asynchronous roundtrip │ │ │ │ │ │ │ │ │ │ - This request adds a mime type to the set of mime types │ │ │ │ │ - advertised to targets. Can be called several times to offer │ │ │ │ │ - multiple types. │ │ │ │ │ + The sync request asks the server to emit the 'done' event on the │ │ │ │ │ + returned "WlCallback" object. Since requests are handled in- │ │ │ │ │ + order and events are delivered in-order, this can be used as a │ │ │ │ │ + barrier to ensure all previous requests and the resulting events │ │ │ │ │ + have been handled. │ │ │ │ │ │ │ │ │ │ - Parameters: │ │ │ │ │ - **mime_type** (*ArgumentType.String*) -- mime type offered by │ │ │ │ │ - the data source │ │ │ │ │ + The object returned by this request will be destroyed by the │ │ │ │ │ + compositor after the callback is fired and as such the client │ │ │ │ │ + must not attempt to use it after that point. │ │ │ │ │ │ │ │ │ │ - destroy() -> 'None' │ │ │ │ │ + The callback_data passed in the callback is undefined and should │ │ │ │ │ + be ignored. │ │ │ │ │ + │ │ │ │ │ + Returns: │ │ │ │ │ + "WlCallback" -- callback object for the sync request │ │ │ │ │ + │ │ │ │ │ + get_registry() -> 'Proxy[WlRegistry]' │ │ │ │ │ │ │ │ │ │ -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Destroy the data source │ │ │ │ │ + Get global registry object │ │ │ │ │ │ │ │ │ │ - Destroy the data source. │ │ │ │ │ + This request creates a registry object that allows the client to │ │ │ │ │ + list and bind the global objects available from the compositor. │ │ │ │ │ │ │ │ │ │ - set_actions(dnd_actions: 'int') -> 'None' │ │ │ │ │ + It should be noted that the server side resources consumed in │ │ │ │ │ + response to a get_registry request can only be released when the │ │ │ │ │ + client disconnects, not when the client side proxy is destroyed. │ │ │ │ │ + Therefore, clients should invoke get_registry as infrequently as │ │ │ │ │ + possible to avoid wasting memory. │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 2 (attached to "Resource" instance) ]- │ │ │ │ │ + Returns: │ │ │ │ │ + "WlRegistry" -- global registry object │ │ │ │ │ │ │ │ │ │ - Set the available drag-and-drop actions │ │ │ │ │ + error(object_id: 'Any', code: 'int', message: 'str') -> 'None' │ │ │ │ │ │ │ │ │ │ - Sets the actions that the source side client supports for this │ │ │ │ │ - operation. This request may trigger "WlDataSource.action()" and │ │ │ │ │ - "WlDataOffer.action()" events if the compositor needs to change │ │ │ │ │ - the selected action. │ │ │ │ │ + -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - The dnd_actions argument must contain only values expressed in │ │ │ │ │ - the "WlDataDeviceManager.dnd_actions()" enum, otherwise it will │ │ │ │ │ - result in a protocol error. │ │ │ │ │ + Fatal error event │ │ │ │ │ │ │ │ │ │ - This request must be made once only, and can only be made on │ │ │ │ │ - sources used in drag-and-drop, so it must be performed before │ │ │ │ │ - "WlDataDevice.start_drag()". Attempting to use the source other │ │ │ │ │ - than for drag-and-drop will raise a protocol error. │ │ │ │ │ + The error event is sent out when a fatal (non-recoverable) error │ │ │ │ │ + has occurred. The object_id argument is the object where the │ │ │ │ │ + error occurred, most often in response to a request to that │ │ │ │ │ + object. The code identifies the error and is defined by the │ │ │ │ │ + object interface. As such, each interface defines its own set │ │ │ │ │ + of error codes. The message is a brief description of the │ │ │ │ │ + error, for (debugging) convenience. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - **dnd_actions** (*ArgumentType.Uint*) -- actions supported by │ │ │ │ │ - the data source │ │ │ │ │ + * **object_id** (*ArgumentType.Object*) -- object where the │ │ │ │ │ + error occurred │ │ │ │ │ │ │ │ │ │ - target(mime_type: 'str | None') -> 'None' │ │ │ │ │ + * **code** (*ArgumentType.Uint*) -- error code │ │ │ │ │ + │ │ │ │ │ + * **message** (*ArgumentType.String*) -- error description │ │ │ │ │ + │ │ │ │ │ + delete_id(id: 'int') -> 'None' │ │ │ │ │ + │ │ │ │ │ + -[ Event -- opcode 1 (attached to "Proxy" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Acknowledge object id deletion │ │ │ │ │ + │ │ │ │ │ + This event is used internally by the object ID management logic. │ │ │ │ │ + When a client deletes an object that it had created, the server │ │ │ │ │ + will send this event to acknowledge that it has seen the delete │ │ │ │ │ + request. When the client receives this event, it will know that │ │ │ │ │ + it can safely reuse the object ID. │ │ │ │ │ + │ │ │ │ │ + Parameters: │ │ │ │ │ + **id** (*ArgumentType.Uint*) -- deleted object ID │ │ │ │ │ + │ │ │ │ │ + │ │ │ │ │ +WlCallback │ │ │ │ │ +========== │ │ │ │ │ + │ │ │ │ │ +class pywayland.protocol.wayland.WlCallback │ │ │ │ │ + │ │ │ │ │ + Callback object │ │ │ │ │ + │ │ │ │ │ + Clients can handle the 'done' event to get notified when the │ │ │ │ │ + related request is done. │ │ │ │ │ + │ │ │ │ │ + Note, because "WlCallback" objects are created from multiple │ │ │ │ │ + independent factory interfaces, the "WlCallback" interface is │ │ │ │ │ + frozen at version 1. │ │ │ │ │ + │ │ │ │ │ + done(callback_data: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - A target accepts an offered mime type │ │ │ │ │ + Done event │ │ │ │ │ │ │ │ │ │ - Sent when a target accepts pointer_focus or motion events. If a │ │ │ │ │ - target does not accept any of the offered types, type is NULL. │ │ │ │ │ + Notify the client when the related request is done. │ │ │ │ │ │ │ │ │ │ - Used for feedback during drag-and-drop. │ │ │ │ │ + Parameters: │ │ │ │ │ + **callback_data** (*ArgumentType.Uint*) -- request-specific │ │ │ │ │ + data for the callback │ │ │ │ │ + │ │ │ │ │ + │ │ │ │ │ +WlDataOffer │ │ │ │ │ +=========== │ │ │ │ │ + │ │ │ │ │ +class pywayland.protocol.wayland.WlDataOffer │ │ │ │ │ + │ │ │ │ │ + Offer to transfer data │ │ │ │ │ + │ │ │ │ │ + A "WlDataOffer" represents a piece of data offered for transfer by │ │ │ │ │ + another client (the source client). It is used by the copy-and- │ │ │ │ │ + paste and drag-and-drop mechanisms. The offer describes the │ │ │ │ │ + different mime types that the data can be converted to and provides │ │ │ │ │ + the mechanism for transferring the data directly from the source │ │ │ │ │ + client. │ │ │ │ │ + │ │ │ │ │ + accept(serial: 'int', mime_type: 'str | None') -> 'None' │ │ │ │ │ + │ │ │ │ │ + -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Accept one of the offered mime types │ │ │ │ │ + │ │ │ │ │ + Indicate that the client can accept the given mime type, or NULL │ │ │ │ │ + for not accepted. │ │ │ │ │ + │ │ │ │ │ + For objects of version 2 or older, this request is used by the │ │ │ │ │ + client to give feedback whether the client can receive the given │ │ │ │ │ + mime type, or NULL if none is accepted; the feedback does not │ │ │ │ │ + determine whether the drag-and-drop operation succeeds or not. │ │ │ │ │ + │ │ │ │ │ + For objects of version 3 or newer, this request determines the │ │ │ │ │ + final result of the drag-and-drop operation. If the end result │ │ │ │ │ + is that no mime types were accepted, the drag-and-drop operation │ │ │ │ │ + will be cancelled and the corresponding drag source will receive │ │ │ │ │ + "WlDataSource.cancelled()". Clients may still use this event in │ │ │ │ │ + conjunction with "WlDataSource.action()" for feedback. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - **mime_type** (*ArgumentType.String* or *None*) -- mime type │ │ │ │ │ - accepted by the target │ │ │ │ │ + * **serial** (*ArgumentType.Uint*) -- serial number of the │ │ │ │ │ + accept request │ │ │ │ │ │ │ │ │ │ - send(mime_type: 'str', fd: 'int') -> 'None' │ │ │ │ │ + * **mime_type** (*ArgumentType.String* or *None*) -- mime │ │ │ │ │ + type accepted by the client │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 1 (attached to "Proxy" instance) ]- │ │ │ │ │ + receive(mime_type: 'str', fd: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - Send the data │ │ │ │ │ + -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Request for data from the client. Send the data as the │ │ │ │ │ - specified mime type over the passed file descriptor, then close │ │ │ │ │ - it. │ │ │ │ │ + Request that the data is transferred │ │ │ │ │ + │ │ │ │ │ + To transfer the offered data, the client issues this request and │ │ │ │ │ + indicates the mime type it wants to receive. The transfer │ │ │ │ │ + happens through the passed file descriptor (typically created │ │ │ │ │ + with the pipe system call). The source client writes the data │ │ │ │ │ + in the mime type representation requested and then closes the │ │ │ │ │ + file descriptor. │ │ │ │ │ + │ │ │ │ │ + The receiving client reads from the read end of the pipe until │ │ │ │ │ + EOF and then closes its end, at which point the transfer is │ │ │ │ │ + complete. │ │ │ │ │ + │ │ │ │ │ + This request may happen multiple times for different mime types, │ │ │ │ │ + both before and after "WlDataDevice.drop()". Drag-and-drop │ │ │ │ │ + destination clients may preemptively fetch data or examine it │ │ │ │ │ + more closely to determine acceptance. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - * **mime_type** (*ArgumentType.String*) -- mime type for the │ │ │ │ │ - data │ │ │ │ │ + * **mime_type** (*ArgumentType.String*) -- mime type desired │ │ │ │ │ + by receiver │ │ │ │ │ │ │ │ │ │ * **fd** (*ArgumentType.FileDescriptor*) -- file descriptor │ │ │ │ │ - for the data │ │ │ │ │ + for data transfer │ │ │ │ │ │ │ │ │ │ - cancelled() -> 'None' │ │ │ │ │ + destroy() -> 'None' │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 2 (attached to "Proxy" instance) ]- │ │ │ │ │ + -[ Request -- opcode 2 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Selection was cancelled │ │ │ │ │ + Destroy data offer │ │ │ │ │ │ │ │ │ │ - This data source is no longer valid. There are several reasons │ │ │ │ │ - why this could happen: │ │ │ │ │ + Destroy the data offer. │ │ │ │ │ │ │ │ │ │ - * The data source has been replaced by another data source. │ │ │ │ │ + finish() -> 'None' │ │ │ │ │ │ │ │ │ │ - * The drag-and-drop operation was performed, but the drop │ │ │ │ │ - destination did not accept any of the mime types offered │ │ │ │ │ - through "WlDataSource.target()". │ │ │ │ │ + -[ Request -- opcode 3 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - * The drag-and-drop operation was performed, but the drop │ │ │ │ │ - destination did not select any of the actions present in the │ │ │ │ │ - mask offered through "WlDataSource.action()". │ │ │ │ │ + The offer will no longer be used │ │ │ │ │ │ │ │ │ │ - * The drag-and-drop operation was performed but didn't happen │ │ │ │ │ - over a surface. │ │ │ │ │ + Notifies the compositor that the drag destination successfully │ │ │ │ │ + finished the drag-and-drop operation. │ │ │ │ │ │ │ │ │ │ - * The compositor cancelled the drag-and-drop operation (e.g. │ │ │ │ │ - compositor dependent timeouts to avoid stale drag-and-drop │ │ │ │ │ - transfers). │ │ │ │ │ + Upon receiving this request, the compositor will emit │ │ │ │ │ + "WlDataSource.dnd_finished()" on the drag source client. │ │ │ │ │ │ │ │ │ │ - The client should clean up and destroy this data source. │ │ │ │ │ + It is a client error to perform other requests than │ │ │ │ │ + "WlDataOffer.destroy()" after this one. It is also an error to │ │ │ │ │ + perform this request after a NULL mime type has been set in │ │ │ │ │ + "WlDataOffer.accept()" or no action was received through │ │ │ │ │ + "WlDataOffer.action()". │ │ │ │ │ │ │ │ │ │ - For objects of version 2 or older, "WlDataSource.cancelled()" │ │ │ │ │ - will only be emitted if the data source was replaced by another │ │ │ │ │ - data source. │ │ │ │ │ + If "WlDataOffer.finish()" request is received for a non drag and │ │ │ │ │ + drop operation, the invalid_finish protocol error is raised. │ │ │ │ │ │ │ │ │ │ - dnd_drop_performed() -> 'None' │ │ │ │ │ + set_actions(dnd_actions: 'int', preferred_action: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 3 (attached to "Proxy" instance) ]- │ │ │ │ │ + -[ Request -- opcode 4 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - The drag-and-drop operation physically finished │ │ │ │ │ + Set the available/preferred drag-and-drop actions │ │ │ │ │ │ │ │ │ │ - The user performed the drop action. This event does not indicate │ │ │ │ │ - acceptance, "WlDataSource.cancelled()" may still be emitted │ │ │ │ │ - afterwards if the drop destination does not accept any mime │ │ │ │ │ - type. │ │ │ │ │ + Sets the actions that the destination side client supports for │ │ │ │ │ + this operation. This request may trigger the emission of │ │ │ │ │ + "WlDataSource.action()" and "WlDataOffer.action()" events if the │ │ │ │ │ + compositor needs to change the selected action. │ │ │ │ │ │ │ │ │ │ - However, this event might however not be received if the │ │ │ │ │ - compositor cancelled the drag-and-drop operation before this │ │ │ │ │ - event could happen. │ │ │ │ │ + This request can be called multiple times throughout the drag- │ │ │ │ │ + and-drop operation, typically in response to │ │ │ │ │ + "WlDataDevice.enter()" or "WlDataDevice.motion()" events. │ │ │ │ │ │ │ │ │ │ - Note that the data_source may still be used in the future and │ │ │ │ │ - should not be destroyed here. │ │ │ │ │ + This request determines the final result of the drag-and-drop │ │ │ │ │ + operation. If the end result is that no action is accepted, the │ │ │ │ │ + drag source will receive "WlDataSource.cancelled()". │ │ │ │ │ │ │ │ │ │ - dnd_finished() -> 'None' │ │ │ │ │ + The dnd_actions argument must contain only values expressed in │ │ │ │ │ + the "WlDataDeviceManager.dnd_actions()" enum, and the │ │ │ │ │ + preferred_action argument must only contain one of those values │ │ │ │ │ + set, otherwise it will result in a protocol error. │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 4 (attached to "Proxy" instance) ]- │ │ │ │ │ + While managing an "ask" action, the destination drag-and-drop │ │ │ │ │ + client may perform further "WlDataOffer.receive()" requests, and │ │ │ │ │ + is expected to perform one last "WlDataOffer.set_actions()" │ │ │ │ │ + request with a preferred action other than "ask" (and optionally │ │ │ │ │ + "WlDataOffer.accept()") before requesting │ │ │ │ │ + "WlDataOffer.finish()", in order to convey the action selected │ │ │ │ │ + by the user. If the preferred action is not in the │ │ │ │ │ + "WlDataOffer.source_actions()" mask, an error will be raised. │ │ │ │ │ │ │ │ │ │ - The drag-and-drop operation concluded │ │ │ │ │ + If the "ask" action is dismissed (e.g. user cancellation), the │ │ │ │ │ + client is expected to perform "WlDataOffer.destroy()" right │ │ │ │ │ + away. │ │ │ │ │ │ │ │ │ │ - The drop destination finished interoperating with this data │ │ │ │ │ - source, so the client is now free to destroy this data source │ │ │ │ │ - and free all associated data. │ │ │ │ │ + This request can only be made on drag-and-drop offers, a │ │ │ │ │ + protocol error will be raised otherwise. │ │ │ │ │ │ │ │ │ │ - If the action used to perform the operation was "move", the │ │ │ │ │ - source can now delete the transferred data. │ │ │ │ │ + Parameters: │ │ │ │ │ + * **dnd_actions** (*ArgumentType.Uint*) -- actions supported │ │ │ │ │ + by the destination client │ │ │ │ │ + │ │ │ │ │ + * **preferred_action** (*ArgumentType.Uint*) -- action │ │ │ │ │ + preferred by the destination client │ │ │ │ │ + │ │ │ │ │ + offer(mime_type: 'str') -> 'None' │ │ │ │ │ + │ │ │ │ │ + -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Advertise offered mime type │ │ │ │ │ + │ │ │ │ │ + Sent immediately after creating the "WlDataOffer" object. One │ │ │ │ │ + event per offered mime type. │ │ │ │ │ + │ │ │ │ │ + Parameters: │ │ │ │ │ + **mime_type** (*ArgumentType.String*) -- offered mime type │ │ │ │ │ + │ │ │ │ │ + source_actions(source_actions: 'int') -> 'None' │ │ │ │ │ + │ │ │ │ │ + -[ Event -- opcode 1 (attached to "Proxy" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Notify the source-side available actions │ │ │ │ │ + │ │ │ │ │ + This event indicates the actions offered by the data source. It │ │ │ │ │ + will be sent immediately after creating the "WlDataOffer" │ │ │ │ │ + object, or anytime the source side changes its offered actions │ │ │ │ │ + through "WlDataSource.set_actions()". │ │ │ │ │ + │ │ │ │ │ + Parameters: │ │ │ │ │ + **source_actions** (*ArgumentType.Uint*) -- actions offered │ │ │ │ │ + by the data source │ │ │ │ │ │ │ │ │ │ action(dnd_action: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 5 (attached to "Proxy" instance) ]- │ │ │ │ │ + -[ Event -- opcode 2 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ Notify the selected action │ │ │ │ │ │ │ │ │ │ This event indicates the action selected by the compositor after │ │ │ │ │ matching the source/destination side actions. Only one action │ │ │ │ │ (or none) will be offered here. │ │ │ │ │ │ │ │ │ │ This event can be emitted multiple times during the drag-and- │ │ │ │ │ - drop operation, mainly in response to destination side changes │ │ │ │ │ - through "WlDataOffer.set_actions()", and as the data device │ │ │ │ │ - enters/leaves surfaces. │ │ │ │ │ + drop operation in response to destination side action changes │ │ │ │ │ + through "WlDataOffer.set_actions()". │ │ │ │ │ │ │ │ │ │ - It is only possible to receive this event after │ │ │ │ │ - "WlDataSource.dnd_drop_performed()" if the drag-and-drop │ │ │ │ │ - operation ended in an "ask" action, in which case the final │ │ │ │ │ - "WlDataSource.action()" event will happen immediately before │ │ │ │ │ - "WlDataSource.dnd_finished()". │ │ │ │ │ + This event will no longer be emitted after "WlDataDevice.drop()" │ │ │ │ │ + happened on the drag- and-drop destination, the client must │ │ │ │ │ + honor the last action received, or the last preferred one set │ │ │ │ │ + through "WlDataOffer.set_actions()" when handling an "ask" │ │ │ │ │ + action. │ │ │ │ │ │ │ │ │ │ Compositors may also change the selected action on the fly, │ │ │ │ │ mainly in response to keyboard modifier changes during the drag- │ │ │ │ │ and-drop operation. │ │ │ │ │ │ │ │ │ │ - The most recent action received is always the valid one. The │ │ │ │ │ - chosen action may change alongside negotiation (e.g. an "ask" │ │ │ │ │ - action can turn into a "move" operation), so the effects of the │ │ │ │ │ - final action must always be applied in │ │ │ │ │ - "WlDataOffer.dnd_finished()". │ │ │ │ │ + The most recent action received is always the valid one. Prior │ │ │ │ │ + to receiving "WlDataDevice.drop()", the chosen action may change │ │ │ │ │ + (e.g. due to keyboard modifiers being pressed). At the time of │ │ │ │ │ + receiving "WlDataDevice.drop()" the drag-and-drop destination │ │ │ │ │ + must honor the last action received. │ │ │ │ │ │ │ │ │ │ - Clients can trigger cursor surface changes from this point, so │ │ │ │ │ - they reflect the current action. │ │ │ │ │ + Action changes may still happen after "WlDataDevice.drop()", │ │ │ │ │ + especially on "ask" actions, where the drag-and-drop destination │ │ │ │ │ + may choose another action afterwards. Action changes happening │ │ │ │ │ + at this stage are always the result of inter-client negotiation, │ │ │ │ │ + the compositor shall no longer be able to induce a different │ │ │ │ │ + action. │ │ │ │ │ + │ │ │ │ │ + Upon "ask" actions, it is expected that the drag-and-drop │ │ │ │ │ + destination may potentially choose a different action and/or │ │ │ │ │ + mime type, based on "WlDataOffer.source_actions()" and finally │ │ │ │ │ + chosen by the user (e.g. popping up a menu with the available │ │ │ │ │ + options). The final "WlDataOffer.set_actions()" and │ │ │ │ │ + "WlDataOffer.accept()" requests must happen before the call to │ │ │ │ │ + "WlDataOffer.finish()". │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ **dnd_action** (*ArgumentType.Uint*) -- action selected by │ │ │ │ │ the compositor │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ -WlSubsurface │ │ │ │ │ -============ │ │ │ │ │ +WlTouch │ │ │ │ │ +======= │ │ │ │ │ │ │ │ │ │ -class pywayland.protocol.wayland.WlSubsurface │ │ │ │ │ +class pywayland.protocol.wayland.WlTouch │ │ │ │ │ │ │ │ │ │ - Sub-surface interface to a "WlSurface" │ │ │ │ │ + Touchscreen input device │ │ │ │ │ │ │ │ │ │ - An additional interface to a "WlSurface" object, which has been │ │ │ │ │ - made a sub-surface. A sub-surface has one parent surface. A sub- │ │ │ │ │ - surface's size and position are not limited to that of the parent. │ │ │ │ │ - Particularly, a sub-surface is not automatically clipped to its │ │ │ │ │ - parent's area. │ │ │ │ │ + The "WlTouch" interface represents a touchscreen associated with a │ │ │ │ │ + seat. │ │ │ │ │ │ │ │ │ │ - A sub-surface becomes mapped, when a non-NULL "WlBuffer" is applied │ │ │ │ │ - and the parent surface is mapped. The order of which one happens │ │ │ │ │ - first is irrelevant. A sub-surface is hidden if the parent becomes │ │ │ │ │ - hidden, or if a NULL "WlBuffer" is applied. These rules apply │ │ │ │ │ - recursively through the tree of surfaces. │ │ │ │ │ + Touch interactions can consist of one or more contacts. For each │ │ │ │ │ + contact, a series of events is generated, starting with a down │ │ │ │ │ + event, followed by zero or more motion events, and ending with an │ │ │ │ │ + up event. Events relating to the same contact point can be │ │ │ │ │ + identified by the ID of the sequence. │ │ │ │ │ │ │ │ │ │ - The behaviour of a "WlSurface.commit()" request on a sub-surface │ │ │ │ │ - depends on the sub-surface's mode. The possible modes are │ │ │ │ │ - synchronized and desynchronized, see methods │ │ │ │ │ - "WlSubsurface.set_sync()" and "WlSubsurface.set_desync()". │ │ │ │ │ - Synchronized mode caches the "WlSurface" state to be applied when │ │ │ │ │ - the parent's state gets applied, and desynchronized mode applies │ │ │ │ │ - the pending "WlSurface" state directly. A sub- surface is initially │ │ │ │ │ - in the synchronized mode. │ │ │ │ │ + release() -> 'None' │ │ │ │ │ │ │ │ │ │ - Sub-surfaces also have another kind of state, which is managed by │ │ │ │ │ - "WlSubsurface" requests, as opposed to "WlSurface" requests. This │ │ │ │ │ - state includes the sub-surface position relative to the parent │ │ │ │ │ - surface ("WlSubsurface.set_position()"), and the stacking order of │ │ │ │ │ - the parent and its sub-surfaces ("WlSubsurface.place_above()" and │ │ │ │ │ - .place_below). This state is applied when the parent surface's │ │ │ │ │ - "WlSurface" state is applied, regardless of the sub-surface's mode. │ │ │ │ │ - As the exception, set_sync and set_desync are effective │ │ │ │ │ - immediately. │ │ │ │ │ + -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - The main surface can be thought to be always in desynchronized │ │ │ │ │ - mode, since it does not have a parent in the sub-surfaces sense. │ │ │ │ │ + Release the touch object │ │ │ │ │ │ │ │ │ │ - Even if a sub-surface is in desynchronized mode, it will behave as │ │ │ │ │ - in synchronized mode, if its parent surface behaves as in │ │ │ │ │ - synchronized mode. This rule is applied recursively throughout the │ │ │ │ │ - tree of surfaces. This means, that one can set a sub-surface into │ │ │ │ │ - synchronized mode, and then assume that all its child and grand- │ │ │ │ │ - child sub-surfaces are synchronized, too, without explicitly │ │ │ │ │ - setting them. │ │ │ │ │ + down(serial: 'int', time: 'int', surface: 'WlSurface', id: 'int', x: 'float', y: 'float') -> 'None' │ │ │ │ │ │ │ │ │ │ - Destroying a sub-surface takes effect immediately. If you need to │ │ │ │ │ - synchronize the removal of a sub-surface to the parent surface │ │ │ │ │ - update, unmap the sub-surface first by attaching a NULL "WlBuffer", │ │ │ │ │ - update parent, and then destroy the sub-surface. │ │ │ │ │ + -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - If the parent "WlSurface" object is destroyed, the sub-surface is │ │ │ │ │ - unmapped. │ │ │ │ │ + Touch down event and beginning of a touch sequence │ │ │ │ │ │ │ │ │ │ - A sub-surface never has the keyboard focus of any seat. │ │ │ │ │ + A new touch point has appeared on the surface. This touch point │ │ │ │ │ + is assigned a unique ID. Future events from this touch point │ │ │ │ │ + reference this ID. The ID ceases to be valid after a touch up │ │ │ │ │ + event and may be reused in the future. │ │ │ │ │ │ │ │ │ │ - The "WlSurface.offset()" request is ignored: clients must use │ │ │ │ │ - set_position instead to move the sub-surface. │ │ │ │ │ + Parameters: │ │ │ │ │ + * **serial** (*ArgumentType.Uint*) -- serial number of the │ │ │ │ │ + touch down event │ │ │ │ │ │ │ │ │ │ - destroy() -> 'None' │ │ │ │ │ + * **time** (*ArgumentType.Uint*) -- timestamp with │ │ │ │ │ + millisecond granularity │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ + * **surface** ("WlSurface") -- surface touched │ │ │ │ │ │ │ │ │ │ - Remove sub-surface interface │ │ │ │ │ + * **id** (*ArgumentType.Int*) -- the unique ID of this touch │ │ │ │ │ + point │ │ │ │ │ │ │ │ │ │ - The sub-surface interface is removed from the "WlSurface" object │ │ │ │ │ - that was turned into a sub-surface with a │ │ │ │ │ - "WlSubcompositor.get_subsurface()" request. The wl_surface's │ │ │ │ │ - association to the parent is deleted. The "WlSurface" is │ │ │ │ │ - unmapped immediately. │ │ │ │ │ + * **x** (*ArgumentType.Fixed*) -- surface-local x coordinate │ │ │ │ │ │ │ │ │ │ - set_position(x: 'int', y: 'int') -> 'None' │ │ │ │ │ + * **y** (*ArgumentType.Fixed*) -- surface-local y coordinate │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ + up(serial: 'int', time: 'int', id: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - Reposition the sub-surface │ │ │ │ │ + -[ Event -- opcode 1 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - This schedules a sub-surface position change. The sub-surface │ │ │ │ │ - will be moved so that its origin (top left corner pixel) will be │ │ │ │ │ - at the location x, y of the parent surface coordinate system. │ │ │ │ │ - The coordinates are not restricted to the parent surface area. │ │ │ │ │ - Negative values are allowed. │ │ │ │ │ + End of a touch event sequence │ │ │ │ │ │ │ │ │ │ - The scheduled coordinates will take effect whenever the state of │ │ │ │ │ - the parent surface is applied. │ │ │ │ │ + The touch point has disappeared. No further events will be sent │ │ │ │ │ + for this touch point and the touch point's ID is released and │ │ │ │ │ + may be reused in a future touch down event. │ │ │ │ │ │ │ │ │ │ - If more than one set_position request is invoked by the client │ │ │ │ │ - before the commit of the parent surface, the position of a new │ │ │ │ │ - request always replaces the scheduled position from any previous │ │ │ │ │ - request. │ │ │ │ │ + Parameters: │ │ │ │ │ + * **serial** (*ArgumentType.Uint*) -- serial number of the │ │ │ │ │ + touch up event │ │ │ │ │ │ │ │ │ │ - The initial position is 0, 0. │ │ │ │ │ + * **time** (*ArgumentType.Uint*) -- timestamp with │ │ │ │ │ + millisecond granularity │ │ │ │ │ + │ │ │ │ │ + * **id** (*ArgumentType.Int*) -- the unique ID of this touch │ │ │ │ │ + point │ │ │ │ │ + │ │ │ │ │ + motion(time: 'int', id: 'int', x: 'float', y: 'float') -> 'None' │ │ │ │ │ + │ │ │ │ │ + -[ Event -- opcode 2 (attached to "Proxy" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Update of touch point coordinates │ │ │ │ │ + │ │ │ │ │ + A touch point has changed coordinates. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - * **x** (*ArgumentType.Int*) -- x coordinate in the parent │ │ │ │ │ - surface │ │ │ │ │ + * **time** (*ArgumentType.Uint*) -- timestamp with │ │ │ │ │ + millisecond granularity │ │ │ │ │ │ │ │ │ │ - * **y** (*ArgumentType.Int*) -- y coordinate in the parent │ │ │ │ │ - surface │ │ │ │ │ + * **id** (*ArgumentType.Int*) -- the unique ID of this touch │ │ │ │ │ + point │ │ │ │ │ │ │ │ │ │ - place_above(sibling: 'WlSurface') -> 'None' │ │ │ │ │ + * **x** (*ArgumentType.Fixed*) -- surface-local x coordinate │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 2 (attached to "Resource" instance) ]- │ │ │ │ │ + * **y** (*ArgumentType.Fixed*) -- surface-local y coordinate │ │ │ │ │ │ │ │ │ │ - Restack the sub-surface │ │ │ │ │ + frame() -> 'None' │ │ │ │ │ │ │ │ │ │ - This sub-surface is taken from the stack, and put back just │ │ │ │ │ - above the reference surface, changing the z-order of the sub- │ │ │ │ │ - surfaces. The reference surface must be one of the sibling │ │ │ │ │ - surfaces, or the parent surface. Using any other surface, │ │ │ │ │ - including this sub-surface, will cause a protocol error. │ │ │ │ │ + -[ Event -- opcode 3 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - The z-order is double-buffered. Requests are handled in order │ │ │ │ │ - and applied immediately to a pending state. The final pending │ │ │ │ │ - state is copied to the active state the next time the state of │ │ │ │ │ - the parent surface is applied. │ │ │ │ │ + End of touch frame event │ │ │ │ │ │ │ │ │ │ - A new sub-surface is initially added as the top-most in the │ │ │ │ │ - stack of its siblings and parent. │ │ │ │ │ + Indicates the end of a set of events that logically belong │ │ │ │ │ + together. A client is expected to accumulate the data in all │ │ │ │ │ + events within the frame before proceeding. │ │ │ │ │ + │ │ │ │ │ + A "WlTouch.frame()" terminates at least one event but otherwise │ │ │ │ │ + no guarantee is provided about the set of events within a frame. │ │ │ │ │ + A client must assume that any state not updated in a frame is │ │ │ │ │ + unchanged from the previously known state. │ │ │ │ │ + │ │ │ │ │ + cancel() -> 'None' │ │ │ │ │ + │ │ │ │ │ + -[ Event -- opcode 4 (attached to "Proxy" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Touch session cancelled │ │ │ │ │ + │ │ │ │ │ + Sent if the compositor decides the touch stream is a global │ │ │ │ │ + gesture. No further events are sent to the clients from that │ │ │ │ │ + particular gesture. Touch cancellation applies to all touch │ │ │ │ │ + points currently active on this client's surface. The client is │ │ │ │ │ + responsible for finalizing the touch points, future touch points │ │ │ │ │ + on this surface may reuse the touch point ID. │ │ │ │ │ + │ │ │ │ │ + No frame event is required after the cancel event. │ │ │ │ │ + │ │ │ │ │ + shape(id: 'int', major: 'float', minor: 'float') -> 'None' │ │ │ │ │ + │ │ │ │ │ + -[ Event -- opcode 5 (attached to "Proxy" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Update shape of touch point │ │ │ │ │ + │ │ │ │ │ + Sent when a touchpoint has changed its shape. │ │ │ │ │ + │ │ │ │ │ + This event does not occur on its own. It is sent before a │ │ │ │ │ + "WlTouch.frame()" event and carries the new shape information │ │ │ │ │ + for any previously reported, or new touch points of that frame. │ │ │ │ │ + │ │ │ │ │ + Other events describing the touch point such as │ │ │ │ │ + "WlTouch.down()", "WlTouch.motion()" or "WlTouch.orientation()" │ │ │ │ │ + may be sent within the same "WlTouch.frame()". A client should │ │ │ │ │ + treat these events as a single logical touch point update. The │ │ │ │ │ + order of "WlTouch.shape()", "WlTouch.orientation()" and │ │ │ │ │ + "WlTouch.motion()" is not guaranteed. A "WlTouch.down()" event │ │ │ │ │ + is guaranteed to occur before the first "WlTouch.shape()" event │ │ │ │ │ + for this touch ID but both events may occur within the same │ │ │ │ │ + "WlTouch.frame()". │ │ │ │ │ + │ │ │ │ │ + A touchpoint shape is approximated by an ellipse through the │ │ │ │ │ + major and minor axis length. The major axis length describes the │ │ │ │ │ + longer diameter of the ellipse, while the minor axis length │ │ │ │ │ + describes the shorter diameter. Major and minor are orthogonal │ │ │ │ │ + and both are specified in surface-local coordinates. The center │ │ │ │ │ + of the ellipse is always at the touchpoint location as reported │ │ │ │ │ + by "WlTouch.down()" or "WlTouch.move()". │ │ │ │ │ + │ │ │ │ │ + This event is only sent by the compositor if the touch device │ │ │ │ │ + supports shape reports. The client has to make reasonable │ │ │ │ │ + assumptions about the shape if it did not receive this event. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - **sibling** ("WlSurface") -- the reference surface │ │ │ │ │ + * **id** (*ArgumentType.Int*) -- the unique ID of this touch │ │ │ │ │ + point │ │ │ │ │ │ │ │ │ │ - place_below(sibling: 'WlSurface') -> 'None' │ │ │ │ │ + * **major** (*ArgumentType.Fixed*) -- length of the major │ │ │ │ │ + axis in surface-local coordinates │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 3 (attached to "Resource" instance) ]- │ │ │ │ │ + * **minor** (*ArgumentType.Fixed*) -- length of the minor │ │ │ │ │ + axis in surface-local coordinates │ │ │ │ │ │ │ │ │ │ - Restack the sub-surface │ │ │ │ │ + orientation(id: 'int', orientation: 'float') -> 'None' │ │ │ │ │ │ │ │ │ │ - The sub-surface is placed just below the reference surface. See │ │ │ │ │ - "WlSubsurface.place_above()". │ │ │ │ │ + -[ Event -- opcode 6 (attached to "Proxy" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Update orientation of touch point │ │ │ │ │ + │ │ │ │ │ + Sent when a touchpoint has changed its orientation. │ │ │ │ │ + │ │ │ │ │ + This event does not occur on its own. It is sent before a │ │ │ │ │ + "WlTouch.frame()" event and carries the new shape information │ │ │ │ │ + for any previously reported, or new touch points of that frame. │ │ │ │ │ + │ │ │ │ │ + Other events describing the touch point such as │ │ │ │ │ + "WlTouch.down()", "WlTouch.motion()" or "WlTouch.shape()" may be │ │ │ │ │ + sent within the same "WlTouch.frame()". A client should treat │ │ │ │ │ + these events as a single logical touch point update. The order │ │ │ │ │ + of "WlTouch.shape()", "WlTouch.orientation()" and │ │ │ │ │ + "WlTouch.motion()" is not guaranteed. A "WlTouch.down()" event │ │ │ │ │ + is guaranteed to occur before the first "WlTouch.orientation()" │ │ │ │ │ + event for this touch ID but both events may occur within the │ │ │ │ │ + same "WlTouch.frame()". │ │ │ │ │ + │ │ │ │ │ + The orientation describes the clockwise angle of a touchpoint's │ │ │ │ │ + major axis to the positive surface y-axis and is normalized to │ │ │ │ │ + the -180 to +180 degree range. The granularity of orientation │ │ │ │ │ + depends on the touch device, some devices only support binary │ │ │ │ │ + rotation values between 0 and 90 degrees. │ │ │ │ │ + │ │ │ │ │ + This event is only sent by the compositor if the touch device │ │ │ │ │ + supports orientation reports. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - **sibling** ("WlSurface") -- the reference surface │ │ │ │ │ + * **id** (*ArgumentType.Int*) -- the unique ID of this touch │ │ │ │ │ + point │ │ │ │ │ │ │ │ │ │ - set_sync() -> 'None' │ │ │ │ │ + * **orientation** (*ArgumentType.Fixed*) -- angle between │ │ │ │ │ + major axis and positive surface y-axis in degrees │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 4 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Set sub-surface to synchronized mode │ │ │ │ │ +WlCompositor │ │ │ │ │ +============ │ │ │ │ │ │ │ │ │ │ - Change the commit behaviour of the sub-surface to synchronized │ │ │ │ │ - mode, also described as the parent dependent mode. │ │ │ │ │ +class pywayland.protocol.wayland.WlCompositor │ │ │ │ │ │ │ │ │ │ - In synchronized mode, "WlSurface.commit()" on a sub-surface will │ │ │ │ │ - accumulate the committed state in a cache, but the state will │ │ │ │ │ - not be applied and hence will not change the compositor output. │ │ │ │ │ - The cached state is applied to the sub-surface immediately after │ │ │ │ │ - the parent surface's state is applied. This ensures atomic │ │ │ │ │ - updates of the parent and all its synchronized sub-surfaces. │ │ │ │ │ - Applying the cached state will invalidate the cache, so further │ │ │ │ │ - parent surface commits do not (re-)apply old state. │ │ │ │ │ + The compositor singleton │ │ │ │ │ │ │ │ │ │ - See "WlSubsurface" for the recursive effect of this mode. │ │ │ │ │ + A compositor. This object is a singleton global. The compositor │ │ │ │ │ + is in charge of combining the contents of multiple surfaces into │ │ │ │ │ + one displayable output. │ │ │ │ │ │ │ │ │ │ - set_desync() -> 'None' │ │ │ │ │ + create_surface() -> 'Proxy[WlSurface]' │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 5 (attached to "Resource" instance) ]- │ │ │ │ │ + -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Set sub-surface to desynchronized mode │ │ │ │ │ + Create new surface │ │ │ │ │ │ │ │ │ │ - Change the commit behaviour of the sub-surface to desynchronized │ │ │ │ │ - mode, also described as independent or freely running mode. │ │ │ │ │ + Ask the compositor to create a new surface. │ │ │ │ │ │ │ │ │ │ - In desynchronized mode, "WlSurface.commit()" on a sub-surface │ │ │ │ │ - will apply the pending state directly, without caching, as │ │ │ │ │ - happens normally with a "WlSurface". Calling │ │ │ │ │ - "WlSurface.commit()" on the parent surface has no effect on the │ │ │ │ │ - sub-surface's "WlSurface" state. This mode allows a sub-surface │ │ │ │ │ - to be updated on its own. │ │ │ │ │ + Returns: │ │ │ │ │ + "WlSurface" -- the new surface │ │ │ │ │ │ │ │ │ │ - If cached state exists when "WlSurface.commit()" is called in │ │ │ │ │ - desynchronized mode, the pending state is added to the cached │ │ │ │ │ - state, and applied as a whole. This invalidates the cache. │ │ │ │ │ + create_region() -> 'Proxy[WlRegion]' │ │ │ │ │ │ │ │ │ │ - Note: even if a sub-surface is set to desynchronized, a parent │ │ │ │ │ - sub- surface may override it to behave as synchronized. For │ │ │ │ │ - details, see "WlSubsurface". │ │ │ │ │ + -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - If a surface's parent surface behaves as desynchronized, then │ │ │ │ │ - the cached state is applied on set_desync. │ │ │ │ │ + Create new region │ │ │ │ │ + │ │ │ │ │ + Ask the compositor to create a new region. │ │ │ │ │ + │ │ │ │ │ + Returns: │ │ │ │ │ + "WlRegion" -- the new region │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ WlDataDevice │ │ │ │ │ ============ │ │ │ │ │ │ │ │ │ │ class pywayland.protocol.wayland.WlDataDevice │ │ │ │ │ │ │ │ │ │ @@ -582,14 +778,97 @@ │ │ │ │ │ data_offer, if any, upon receiving this event. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ **id** ("WlDataOffer" or *None*) -- selection data_offer │ │ │ │ │ object │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ +WlShmPool │ │ │ │ │ +========= │ │ │ │ │ + │ │ │ │ │ +class pywayland.protocol.wayland.WlShmPool │ │ │ │ │ + │ │ │ │ │ + A shared memory pool │ │ │ │ │ + │ │ │ │ │ + The "WlShmPool" object encapsulates a piece of memory shared │ │ │ │ │ + between the compositor and client. Through the "WlShmPool" object, │ │ │ │ │ + the client can allocate shared memory "WlBuffer" objects. All │ │ │ │ │ + objects created through the same pool share the same underlying │ │ │ │ │ + mapped memory. Reusing the mapped memory avoids the setup/teardown │ │ │ │ │ + overhead and is useful when interactively resizing a surface or for │ │ │ │ │ + many small buffers. │ │ │ │ │ + │ │ │ │ │ + create_buffer(offset: 'int', width: 'int', height: 'int', stride: 'int', format: 'int') -> 'Proxy[WlBuffer]' │ │ │ │ │ + │ │ │ │ │ + -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Create a buffer from the pool │ │ │ │ │ + │ │ │ │ │ + Create a "WlBuffer" object from the pool. │ │ │ │ │ + │ │ │ │ │ + The buffer is created offset bytes into the pool and has width │ │ │ │ │ + and height as specified. The stride argument specifies the │ │ │ │ │ + number of bytes from the beginning of one row to the beginning │ │ │ │ │ + of the next. The format is the pixel format of the buffer and │ │ │ │ │ + must be one of those advertised through the "WlShm.format()" │ │ │ │ │ + event. │ │ │ │ │ + │ │ │ │ │ + A buffer will keep a reference to the pool it was created from │ │ │ │ │ + so it is valid to destroy the pool immediately after creating a │ │ │ │ │ + buffer from it. │ │ │ │ │ + │ │ │ │ │ + Parameters: │ │ │ │ │ + * **offset** (*ArgumentType.Int*) -- buffer byte offset │ │ │ │ │ + within the pool │ │ │ │ │ + │ │ │ │ │ + * **width** (*ArgumentType.Int*) -- buffer width, in pixels │ │ │ │ │ + │ │ │ │ │ + * **height** (*ArgumentType.Int*) -- buffer height, in pixels │ │ │ │ │ + │ │ │ │ │ + * **stride** (*ArgumentType.Int*) -- number of bytes from the │ │ │ │ │ + beginning of one row to the beginning of the next row │ │ │ │ │ + │ │ │ │ │ + * **format** (*ArgumentType.Uint*) -- buffer pixel format │ │ │ │ │ + │ │ │ │ │ + Returns: │ │ │ │ │ + "WlBuffer" -- buffer to create │ │ │ │ │ + │ │ │ │ │ + destroy() -> 'None' │ │ │ │ │ + │ │ │ │ │ + -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Destroy the pool │ │ │ │ │ + │ │ │ │ │ + Destroy the shared memory pool. │ │ │ │ │ + │ │ │ │ │ + The mmapped memory will be released when all buffers that have │ │ │ │ │ + been created from this pool are gone. │ │ │ │ │ + │ │ │ │ │ + resize(size: 'int') -> 'None' │ │ │ │ │ + │ │ │ │ │ + -[ Request -- opcode 2 (attached to "Resource" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Change the size of the pool mapping │ │ │ │ │ + │ │ │ │ │ + This request will cause the server to remap the backing memory │ │ │ │ │ + for the pool from the file descriptor passed when the pool was │ │ │ │ │ + created, but using the new size. This request can only be used │ │ │ │ │ + to make the pool bigger. │ │ │ │ │ + │ │ │ │ │ + This request only changes the amount of bytes that are mmapped │ │ │ │ │ + by the server and does not touch the file corresponding to the │ │ │ │ │ + file descriptor passed at creation time. It is the client's │ │ │ │ │ + responsibility to ensure that the file is at least as big as the │ │ │ │ │ + new pool size. │ │ │ │ │ + │ │ │ │ │ + Parameters: │ │ │ │ │ + **size** (*ArgumentType.Int*) -- new size of the pool, in │ │ │ │ │ + bytes │ │ │ │ │ + │ │ │ │ │ + │ │ │ │ │ WlShellSurface │ │ │ │ │ ============== │ │ │ │ │ │ │ │ │ │ class pywayland.protocol.wayland.WlShellSurface │ │ │ │ │ │ │ │ │ │ Desktop-style metadata interface │ │ │ │ │ │ │ │ │ │ @@ -896,905 +1175,528 @@ │ │ │ │ │ Popup interaction is done │ │ │ │ │ │ │ │ │ │ The popup_done event is sent out when a popup grab is broken, │ │ │ │ │ that is, when the user clicks a surface that doesn't belong to │ │ │ │ │ the client owning the popup surface. │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ -WlSurface │ │ │ │ │ -========= │ │ │ │ │ - │ │ │ │ │ -class pywayland.protocol.wayland.WlSurface │ │ │ │ │ - │ │ │ │ │ - An onscreen surface │ │ │ │ │ - │ │ │ │ │ - A surface is a rectangular area that may be displayed on zero or │ │ │ │ │ - more outputs, and shown any number of times at the compositor's │ │ │ │ │ - discretion. They can present wl_buffers, receive user input, and │ │ │ │ │ - define a local coordinate system. │ │ │ │ │ - │ │ │ │ │ - The size of a surface (and relative positions on it) is described │ │ │ │ │ - in surface-local coordinates, which may differ from the buffer │ │ │ │ │ - coordinates of the pixel content, in case a buffer_transform or a │ │ │ │ │ - buffer_scale is used. │ │ │ │ │ - │ │ │ │ │ - A surface without a "role" is fairly useless: a compositor does not │ │ │ │ │ - know where, when or how to present it. The role is the purpose of a │ │ │ │ │ - "WlSurface". Examples of roles are a cursor for a pointer (as set │ │ │ │ │ - by "WlPointer.set_cursor()"), a drag icon │ │ │ │ │ - ("WlDataDevice.start_drag()"), a sub-surface │ │ │ │ │ - ("WlSubcompositor.get_subsurface()"), and a window as defined by a │ │ │ │ │ - shell protocol (e.g. "WlShell.get_shell_surface()"). │ │ │ │ │ +WlOutput │ │ │ │ │ +======== │ │ │ │ │ │ │ │ │ │ - A surface can have only one role at a time. Initially a "WlSurface" │ │ │ │ │ - does not have a role. Once a "WlSurface" is given a role, it is set │ │ │ │ │ - permanently for the whole lifetime of the "WlSurface" object. │ │ │ │ │ - Giving the current role again is allowed, unless explicitly │ │ │ │ │ - forbidden by the relevant interface specification. │ │ │ │ │ +class pywayland.protocol.wayland.WlOutput │ │ │ │ │ │ │ │ │ │ - Surface roles are given by requests in other interfaces such as │ │ │ │ │ - "WlPointer.set_cursor()". The request should explicitly mention │ │ │ │ │ - that this request gives a role to a "WlSurface". Often, this │ │ │ │ │ - request also creates a new protocol object that represents the role │ │ │ │ │ - and adds additional functionality to "WlSurface". When a client │ │ │ │ │ - wants to destroy a "WlSurface", they must destroy this role object │ │ │ │ │ - before the "WlSurface", otherwise a defunct_role_object error is │ │ │ │ │ - sent. │ │ │ │ │ + Compositor output region │ │ │ │ │ │ │ │ │ │ - Destroying the role object does not remove the role from the │ │ │ │ │ - "WlSurface", but it may stop the "WlSurface" from "playing the │ │ │ │ │ - role". For instance, if a "WlSubsurface" object is destroyed, the │ │ │ │ │ - "WlSurface" it was created for will be unmapped and forget its │ │ │ │ │ - position and z-order. It is allowed to create a "WlSubsurface" for │ │ │ │ │ - the same "WlSurface" again, but it is not allowed to use the │ │ │ │ │ - "WlSurface" as a cursor (cursor is a different role than sub- │ │ │ │ │ - surface, and role switching is not allowed). │ │ │ │ │ + An output describes part of the compositor geometry. The │ │ │ │ │ + compositor works in the 'compositor coordinate system' and an │ │ │ │ │ + output corresponds to a rectangular area in that space that is │ │ │ │ │ + actually visible. This typically corresponds to a monitor that │ │ │ │ │ + displays part of the compositor space. This object is published as │ │ │ │ │ + global during start up, or when a monitor is hotplugged. │ │ │ │ │ │ │ │ │ │ - destroy() -> 'None' │ │ │ │ │ + release() -> 'None' │ │ │ │ │ │ │ │ │ │ -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Delete surface │ │ │ │ │ - │ │ │ │ │ - Deletes the surface and invalidates its object ID. │ │ │ │ │ - │ │ │ │ │ - attach(buffer: 'WlBuffer | None', x: 'int', y: 'int') -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Set the surface contents │ │ │ │ │ - │ │ │ │ │ - Set a buffer as the content of this surface. │ │ │ │ │ - │ │ │ │ │ - The new size of the surface is calculated based on the buffer │ │ │ │ │ - size transformed by the inverse buffer_transform and the inverse │ │ │ │ │ - buffer_scale. This means that at commit time the supplied buffer │ │ │ │ │ - size must be an integer multiple of the buffer_scale. If that's │ │ │ │ │ - not the case, an invalid_size error is sent. │ │ │ │ │ - │ │ │ │ │ - The x and y arguments specify the location of the new pending │ │ │ │ │ - buffer's upper left corner, relative to the current buffer's │ │ │ │ │ - upper left corner, in surface-local coordinates. In other words, │ │ │ │ │ - the x and y, combined with the new surface size define in which │ │ │ │ │ - directions the surface's size changes. Setting anything other │ │ │ │ │ - than 0 as x and y arguments is discouraged, and should instead │ │ │ │ │ - be replaced with using the separate "WlSurface.offset()" │ │ │ │ │ - request. │ │ │ │ │ - │ │ │ │ │ - When the bound "WlSurface" version is 5 or higher, passing any │ │ │ │ │ - non-zero x or y is a protocol violation, and will result in an │ │ │ │ │ - 'invalid_offset' error being raised. The x and y arguments are │ │ │ │ │ - ignored and do not change the pending state. To achieve │ │ │ │ │ - equivalent semantics, use "WlSurface.offset()". │ │ │ │ │ - │ │ │ │ │ - Surface contents are double-buffered state, see │ │ │ │ │ - "WlSurface.commit()". │ │ │ │ │ - │ │ │ │ │ - The initial surface contents are void; there is no content. │ │ │ │ │ - "WlSurface.attach()" assigns the given "WlBuffer" as the pending │ │ │ │ │ - "WlBuffer". "WlSurface.commit()" makes the pending "WlBuffer" │ │ │ │ │ - the new surface contents, and the size of the surface becomes │ │ │ │ │ - the size calculated from the "WlBuffer", as described above. │ │ │ │ │ - After commit, there is no pending buffer until the next attach. │ │ │ │ │ - │ │ │ │ │ - Committing a pending "WlBuffer" allows the compositor to read │ │ │ │ │ - the pixels in the "WlBuffer". The compositor may access the │ │ │ │ │ - pixels at any time after the "WlSurface.commit()" request. When │ │ │ │ │ - the compositor will not access the pixels anymore, it will send │ │ │ │ │ - the "WlBuffer.release()" event. Only after receiving │ │ │ │ │ - "WlBuffer.release()", the client may reuse the "WlBuffer". A │ │ │ │ │ - "WlBuffer" that has been attached and then replaced by another │ │ │ │ │ - attach instead of committed will not receive a release event, │ │ │ │ │ - and is not used by the compositor. │ │ │ │ │ - │ │ │ │ │ - If a pending "WlBuffer" has been committed to more than one │ │ │ │ │ - "WlSurface", the delivery of "WlBuffer.release()" events becomes │ │ │ │ │ - undefined. A well behaved client should not rely on │ │ │ │ │ - "WlBuffer.release()" events in this case. Alternatively, a │ │ │ │ │ - client could create multiple "WlBuffer" objects from the same │ │ │ │ │ - backing storage or use wp_linux_buffer_release. │ │ │ │ │ - │ │ │ │ │ - Destroying the "WlBuffer" after "WlBuffer.release()" does not │ │ │ │ │ - change the surface contents. Destroying the "WlBuffer" before │ │ │ │ │ - "WlBuffer.release()" is allowed as long as the underlying buffer │ │ │ │ │ - storage isn't re-used (this can happen e.g. on client process │ │ │ │ │ - termination). However, if the client destroys the "WlBuffer" │ │ │ │ │ - before receiving the "WlBuffer.release()" event and mutates the │ │ │ │ │ - underlying buffer storage, the surface contents become undefined │ │ │ │ │ - immediately. │ │ │ │ │ - │ │ │ │ │ - If "WlSurface.attach()" is sent with a NULL "WlBuffer", the │ │ │ │ │ - following "WlSurface.commit()" will remove the surface content. │ │ │ │ │ - │ │ │ │ │ - If a pending "WlBuffer" has been destroyed, the result is not │ │ │ │ │ - specified. Many compositors are known to remove the surface │ │ │ │ │ - content on the following "WlSurface.commit()", but this │ │ │ │ │ - behaviour is not universal. Clients seeking to maximise │ │ │ │ │ - compatibility should not destroy pending buffers and should │ │ │ │ │ - ensure that they explicitly remove content from surfaces, even │ │ │ │ │ - after destroying buffers. │ │ │ │ │ - │ │ │ │ │ - Parameters: │ │ │ │ │ - * **buffer** ("WlBuffer" or *None*) -- buffer of surface │ │ │ │ │ - contents │ │ │ │ │ - │ │ │ │ │ - * **x** (*ArgumentType.Int*) -- surface-local x coordinate │ │ │ │ │ - │ │ │ │ │ - * **y** (*ArgumentType.Int*) -- surface-local y coordinate │ │ │ │ │ + Release the output object │ │ │ │ │ │ │ │ │ │ - damage(x: 'int', y: 'int', width: 'int', height: 'int') -> 'None' │ │ │ │ │ + Using this request a client can tell the server that it is not │ │ │ │ │ + going to use the output object anymore. │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 2 (attached to "Resource" instance) ]- │ │ │ │ │ + geometry(x: 'int', y: 'int', physical_width: 'int', physical_height: 'int', subpixel: 'int', make: 'str', model: 'str', transform: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - Mark part of the surface damaged │ │ │ │ │ + -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - This request is used to describe the regions where the pending │ │ │ │ │ - buffer is different from the current surface contents, and where │ │ │ │ │ - the surface therefore needs to be repainted. The compositor │ │ │ │ │ - ignores the parts of the damage that fall outside of the │ │ │ │ │ - surface. │ │ │ │ │ + Properties of the output │ │ │ │ │ │ │ │ │ │ - Damage is double-buffered state, see "WlSurface.commit()". │ │ │ │ │ + The geometry event describes geometric properties of the output. │ │ │ │ │ + The event is sent when binding to the output object and whenever │ │ │ │ │ + any of the properties change. │ │ │ │ │ │ │ │ │ │ - The damage rectangle is specified in surface-local coordinates, │ │ │ │ │ - where x and y specify the upper left corner of the damage │ │ │ │ │ - rectangle. │ │ │ │ │ + The physical size can be set to zero if it doesn't make sense │ │ │ │ │ + for this output (e.g. for projectors or virtual outputs). │ │ │ │ │ │ │ │ │ │ - The initial value for pending damage is empty: no damage. │ │ │ │ │ - "WlSurface.damage()" adds pending damage: the new pending damage │ │ │ │ │ - is the union of old pending damage and the given rectangle. │ │ │ │ │ + The geometry event will be followed by a done event (starting │ │ │ │ │ + from version 2). │ │ │ │ │ │ │ │ │ │ - "WlSurface.commit()" assigns pending damage as the current │ │ │ │ │ - damage, and clears pending damage. The server will clear the │ │ │ │ │ - current damage as it repaints the surface. │ │ │ │ │ + Clients should use "WlSurface.preferred_buffer_transform()" │ │ │ │ │ + instead of the transform advertised by this event to find the │ │ │ │ │ + preferred buffer transform to use for a surface. │ │ │ │ │ │ │ │ │ │ - Note! New clients should not use this request. Instead damage │ │ │ │ │ - can be posted with "WlSurface.damage_buffer()" which uses buffer │ │ │ │ │ - coordinates instead of surface coordinates. │ │ │ │ │ + Note: "WlOutput" only advertises partial information about the │ │ │ │ │ + output position and identification. Some compositors, for │ │ │ │ │ + instance those not implementing a desktop-style output layout or │ │ │ │ │ + those exposing virtual outputs, might fake this information. │ │ │ │ │ + Instead of using x and y, clients should use │ │ │ │ │ + xdg_output.logical_position. Instead of using make and model, │ │ │ │ │ + clients should use name and description. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - * **x** (*ArgumentType.Int*) -- surface-local x coordinate │ │ │ │ │ - │ │ │ │ │ - * **y** (*ArgumentType.Int*) -- surface-local y coordinate │ │ │ │ │ - │ │ │ │ │ - * **width** (*ArgumentType.Int*) -- width of damage rectangle │ │ │ │ │ - │ │ │ │ │ - * **height** (*ArgumentType.Int*) -- height of damage │ │ │ │ │ - rectangle │ │ │ │ │ - │ │ │ │ │ - frame() -> 'Proxy[WlCallback]' │ │ │ │ │ - │ │ │ │ │ - -[ Request -- opcode 3 (attached to "Resource" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Request a frame throttling hint │ │ │ │ │ + * **x** (*ArgumentType.Int*) -- x position within the global │ │ │ │ │ + compositor space │ │ │ │ │ │ │ │ │ │ - Request a notification when it is a good time to start drawing a │ │ │ │ │ - new frame, by creating a frame callback. This is useful for │ │ │ │ │ - throttling redrawing operations, and driving animations. │ │ │ │ │ + * **y** (*ArgumentType.Int*) -- y position within the global │ │ │ │ │ + compositor space │ │ │ │ │ │ │ │ │ │ - When a client is animating on a "WlSurface", it can use the │ │ │ │ │ - 'frame' request to get notified when it is a good time to draw │ │ │ │ │ - and commit the next frame of animation. If the client commits an │ │ │ │ │ - update earlier than that, it is likely that some updates will │ │ │ │ │ - not make it to the display, and the client is wasting resources │ │ │ │ │ - by drawing too often. │ │ │ │ │ + * **physical_width** (*ArgumentType.Int*) -- width in │ │ │ │ │ + millimeters of the output │ │ │ │ │ │ │ │ │ │ - The frame request will take effect on the next │ │ │ │ │ - "WlSurface.commit()". The notification will only be posted for │ │ │ │ │ - one frame unless requested again. For a "WlSurface", the │ │ │ │ │ - notifications are posted in the order the frame requests were │ │ │ │ │ - committed. │ │ │ │ │ + * **physical_height** (*ArgumentType.Int*) -- height in │ │ │ │ │ + millimeters of the output │ │ │ │ │ │ │ │ │ │ - The server must send the notifications so that a client will not │ │ │ │ │ - send excessive updates, while still allowing the highest │ │ │ │ │ - possible update rate for clients that wait for the reply before │ │ │ │ │ - drawing again. The server should give some time for the client │ │ │ │ │ - to draw and commit after sending the frame callback events to │ │ │ │ │ - let it hit the next output refresh. │ │ │ │ │ + * **subpixel** (*ArgumentType.Int*) -- subpixel orientation │ │ │ │ │ + of the output │ │ │ │ │ │ │ │ │ │ - A server should avoid signaling the frame callbacks if the │ │ │ │ │ - surface is not visible in any way, e.g. the surface is off- │ │ │ │ │ - screen, or completely obscured by other opaque surfaces. │ │ │ │ │ + * **make** (*ArgumentType.String*) -- textual description of │ │ │ │ │ + the manufacturer │ │ │ │ │ │ │ │ │ │ - The object returned by this request will be destroyed by the │ │ │ │ │ - compositor after the callback is fired and as such the client │ │ │ │ │ - must not attempt to use it after that point. │ │ │ │ │ + * **model** (*ArgumentType.String*) -- textual description of │ │ │ │ │ + the model │ │ │ │ │ │ │ │ │ │ - The callback_data passed in the callback is the current time, in │ │ │ │ │ - milliseconds, with an undefined base. │ │ │ │ │ + * **transform** (*ArgumentType.Int*) -- additional │ │ │ │ │ + transformation applied to buffer contents during │ │ │ │ │ + presentation │ │ │ │ │ │ │ │ │ │ - Returns: │ │ │ │ │ - "WlCallback" -- callback object for the frame request │ │ │ │ │ + mode(flags: 'int', width: 'int', height: 'int', refresh: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - set_opaque_region(region: 'WlRegion | None') -> 'None' │ │ │ │ │ + -[ Event -- opcode 1 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 4 (attached to "Resource" instance) ]- │ │ │ │ │ + Advertise available modes for the output │ │ │ │ │ │ │ │ │ │ - Set opaque region │ │ │ │ │ + The mode event describes an available mode for the output. │ │ │ │ │ │ │ │ │ │ - This request sets the region of the surface that contains opaque │ │ │ │ │ - content. │ │ │ │ │ + The event is sent when binding to the output object and there │ │ │ │ │ + will always be one mode, the current mode. The event is sent │ │ │ │ │ + again if an output changes mode, for the mode that is now │ │ │ │ │ + current. In other words, the current mode is always the last │ │ │ │ │ + mode that was received with the current flag set. │ │ │ │ │ │ │ │ │ │ - The opaque region is an optimization hint for the compositor │ │ │ │ │ - that lets it optimize the redrawing of content behind opaque │ │ │ │ │ - regions. Setting an opaque region is not required for correct │ │ │ │ │ - behaviour, but marking transparent content as opaque will result │ │ │ │ │ - in repaint artifacts. │ │ │ │ │ + Non-current modes are deprecated. A compositor can decide to │ │ │ │ │ + only advertise the current mode and never send other modes. │ │ │ │ │ + Clients should not rely on non-current modes. │ │ │ │ │ │ │ │ │ │ - The opaque region is specified in surface-local coordinates. │ │ │ │ │ + The size of a mode is given in physical hardware units of the │ │ │ │ │ + output device. This is not necessarily the same as the output │ │ │ │ │ + size in the global compositor space. For instance, the output │ │ │ │ │ + may be scaled, as described in "WlOutput.scale()", or │ │ │ │ │ + transformed, as described in "WlOutput.transform()". Clients │ │ │ │ │ + willing to retrieve the output size in the global compositor │ │ │ │ │ + space should use xdg_output.logical_size instead. │ │ │ │ │ │ │ │ │ │ - The compositor ignores the parts of the opaque region that fall │ │ │ │ │ - outside of the surface. │ │ │ │ │ + The vertical refresh rate can be set to zero if it doesn't make │ │ │ │ │ + sense for this output (e.g. for virtual outputs). │ │ │ │ │ │ │ │ │ │ - Opaque region is double-buffered state, see │ │ │ │ │ - "WlSurface.commit()". │ │ │ │ │ + The mode event will be followed by a done event (starting from │ │ │ │ │ + version 2). │ │ │ │ │ │ │ │ │ │ - "WlSurface.set_opaque_region()" changes the pending opaque │ │ │ │ │ - region. "WlSurface.commit()" copies the pending region to the │ │ │ │ │ - current region. Otherwise, the pending and current regions are │ │ │ │ │ - never changed. │ │ │ │ │ + Clients should not use the refresh rate to schedule frames. │ │ │ │ │ + Instead, they should use the "WlSurface.frame()" event or the │ │ │ │ │ + presentation-time protocol. │ │ │ │ │ │ │ │ │ │ - The initial value for an opaque region is empty. Setting the │ │ │ │ │ - pending opaque region has copy semantics, and the "WlRegion" │ │ │ │ │ - object can be destroyed immediately. A NULL "WlRegion" causes │ │ │ │ │ - the pending opaque region to be set to empty. │ │ │ │ │ + Note: this information is not always meaningful for all outputs. │ │ │ │ │ + Some compositors, such as those exposing virtual outputs, might │ │ │ │ │ + fake the refresh rate or the size. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - **region** ("WlRegion" or *None*) -- opaque region of the │ │ │ │ │ - surface │ │ │ │ │ - │ │ │ │ │ - set_input_region(region: 'WlRegion | None') -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Request -- opcode 5 (attached to "Resource" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Set input region │ │ │ │ │ + * **flags** (*ArgumentType.Uint*) -- bitfield of mode flags │ │ │ │ │ │ │ │ │ │ - This request sets the region of the surface that can receive │ │ │ │ │ - pointer and touch events. │ │ │ │ │ + * **width** (*ArgumentType.Int*) -- width of the mode in │ │ │ │ │ + hardware units │ │ │ │ │ │ │ │ │ │ - Input events happening outside of this region will try the next │ │ │ │ │ - surface in the server surface stack. The compositor ignores the │ │ │ │ │ - parts of the input region that fall outside of the surface. │ │ │ │ │ + * **height** (*ArgumentType.Int*) -- height of the mode in │ │ │ │ │ + hardware units │ │ │ │ │ │ │ │ │ │ - The input region is specified in surface-local coordinates. │ │ │ │ │ + * **refresh** (*ArgumentType.Int*) -- vertical refresh rate │ │ │ │ │ + in mHz │ │ │ │ │ │ │ │ │ │ - Input region is double-buffered state, see "WlSurface.commit()". │ │ │ │ │ + done() -> 'None' │ │ │ │ │ │ │ │ │ │ - "WlSurface.set_input_region()" changes the pending input region. │ │ │ │ │ - "WlSurface.commit()" copies the pending region to the current │ │ │ │ │ - region. Otherwise the pending and current regions are never │ │ │ │ │ - changed, except cursor and icon surfaces are special cases, see │ │ │ │ │ - "WlPointer.set_cursor()" and "WlDataDevice.start_drag()". │ │ │ │ │ + -[ Event -- opcode 2 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - The initial value for an input region is infinite. That means │ │ │ │ │ - the whole surface will accept input. Setting the pending input │ │ │ │ │ - region has copy semantics, and the "WlRegion" object can be │ │ │ │ │ - destroyed immediately. A NULL "WlRegion" causes the input region │ │ │ │ │ - to be set to infinite. │ │ │ │ │ + Sent all information about output │ │ │ │ │ │ │ │ │ │ - Parameters: │ │ │ │ │ - **region** ("WlRegion" or *None*) -- input region of the │ │ │ │ │ - surface │ │ │ │ │ + This event is sent after all other properties have been sent │ │ │ │ │ + after binding to the output object and after any other property │ │ │ │ │ + changes done after that. This allows changes to the output │ │ │ │ │ + properties to be seen as atomic, even if they happen via │ │ │ │ │ + multiple events. │ │ │ │ │ │ │ │ │ │ - commit() -> 'None' │ │ │ │ │ + scale(factor: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 6 (attached to "Resource" instance) ]- │ │ │ │ │ + -[ Event -- opcode 3 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - Commit pending surface state │ │ │ │ │ + Output scaling properties │ │ │ │ │ │ │ │ │ │ - Surface state (input, opaque, and damage regions, attached │ │ │ │ │ - buffers, etc.) is double-buffered. Protocol requests modify the │ │ │ │ │ - pending state, as opposed to the active state in use by the │ │ │ │ │ - compositor. │ │ │ │ │ + This event contains scaling geometry information that is not in │ │ │ │ │ + the geometry event. It may be sent after binding the output │ │ │ │ │ + object or if the output scale changes later. The compositor will │ │ │ │ │ + emit a non-zero, positive value for scale. If it is not sent, │ │ │ │ │ + the client should assume a scale of 1. │ │ │ │ │ │ │ │ │ │ - A commit request atomically creates a content update from the │ │ │ │ │ - pending state, even if the pending state has not been touched. │ │ │ │ │ - The content update is placed in a queue until it becomes active. │ │ │ │ │ - After commit, the new pending state is as documented for each │ │ │ │ │ - related request. │ │ │ │ │ + A scale larger than 1 means that the compositor will │ │ │ │ │ + automatically scale surface buffers by this amount when │ │ │ │ │ + rendering. This is used for very high resolution displays where │ │ │ │ │ + applications rendering at the native resolution would be too │ │ │ │ │ + small to be legible. │ │ │ │ │ │ │ │ │ │ - When the content update is applied, the "WlBuffer" is applied │ │ │ │ │ - before all other state. This means that all coordinates in │ │ │ │ │ - double-buffered state are relative to the newly attached │ │ │ │ │ - wl_buffers, except for "WlSurface.attach()" itself. If there is │ │ │ │ │ - no newly attached "WlBuffer", the coordinates are relative to │ │ │ │ │ - the previous content update. │ │ │ │ │ + Clients should use "WlSurface.preferred_buffer_scale()" instead │ │ │ │ │ + of this event to find the preferred buffer scale to use for a │ │ │ │ │ + surface. │ │ │ │ │ │ │ │ │ │ - All requests that need a commit to become effective are │ │ │ │ │ - documented to affect double-buffered state. │ │ │ │ │ + The scale event will be followed by a done event. │ │ │ │ │ │ │ │ │ │ - Other interfaces may add further double-buffered surface state. │ │ │ │ │ + Parameters: │ │ │ │ │ + **factor** (*ArgumentType.Int*) -- scaling factor of output │ │ │ │ │ │ │ │ │ │ - set_buffer_transform(transform: 'int') -> 'None' │ │ │ │ │ + name(name: 'str') -> 'None' │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 7 (attached to "Resource" instance) ]- │ │ │ │ │ + -[ Event -- opcode 4 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - Sets the buffer transformation │ │ │ │ │ + Name of this output │ │ │ │ │ │ │ │ │ │ - This request sets the transformation that the client has already │ │ │ │ │ - applied to the content of the buffer. The accepted values for │ │ │ │ │ - the transform parameter are the values for │ │ │ │ │ - "WlOutput.transform()". │ │ │ │ │ + Many compositors will assign user-friendly names to their │ │ │ │ │ + outputs, show them to the user, allow the user to refer to an │ │ │ │ │ + output, etc. The client may wish to know this name as well to │ │ │ │ │ + offer the user similar behaviors. │ │ │ │ │ │ │ │ │ │ - The compositor applies the inverse of this transformation │ │ │ │ │ - whenever it uses the buffer contents. │ │ │ │ │ + The name is a UTF-8 string with no convention defined for its │ │ │ │ │ + contents. Each name is unique among all "WlOutput" globals. The │ │ │ │ │ + name is only guaranteed to be unique for the compositor │ │ │ │ │ + instance. │ │ │ │ │ │ │ │ │ │ - Buffer transform is double-buffered state, see │ │ │ │ │ - "WlSurface.commit()". │ │ │ │ │ + The same output name is used for all clients for a given │ │ │ │ │ + "WlOutput" global. Thus, the name can be shared across processes │ │ │ │ │ + to refer to a specific "WlOutput" global. │ │ │ │ │ │ │ │ │ │ - A newly created surface has its buffer transformation set to │ │ │ │ │ - normal. │ │ │ │ │ + The name is not guaranteed to be persistent across sessions, │ │ │ │ │ + thus cannot be used to reliably identify an output in e.g. │ │ │ │ │ + configuration files. │ │ │ │ │ │ │ │ │ │ - "WlSurface.set_buffer_transform()" changes the pending buffer │ │ │ │ │ - transformation. "WlSurface.commit()" copies the pending buffer │ │ │ │ │ - transformation to the current one. Otherwise, the pending and │ │ │ │ │ - current values are never changed. │ │ │ │ │ + Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc. │ │ │ │ │ + However, do not assume that the name is a reflection of an │ │ │ │ │ + underlying DRM connector, X11 connection, etc. │ │ │ │ │ │ │ │ │ │ - The purpose of this request is to allow clients to render │ │ │ │ │ - content according to the output transform, thus permitting the │ │ │ │ │ - compositor to use certain optimizations even if the display is │ │ │ │ │ - rotated. Using hardware overlays and scanning out a client │ │ │ │ │ - buffer for fullscreen surfaces are examples of such │ │ │ │ │ - optimizations. Those optimizations are highly dependent on the │ │ │ │ │ - compositor implementation, so the use of this request should be │ │ │ │ │ - considered on a case-by-case basis. │ │ │ │ │ + The name event is sent after binding the output object. This │ │ │ │ │ + event is only sent once per output object, and the name does not │ │ │ │ │ + change over the lifetime of the "WlOutput" global. │ │ │ │ │ │ │ │ │ │ - Note that if the transform value includes 90 or 270 degree │ │ │ │ │ - rotation, the width of the buffer will become the surface height │ │ │ │ │ - and the height of the buffer will become the surface width. │ │ │ │ │ + Compositors may re-use the same output name if the "WlOutput" │ │ │ │ │ + global is destroyed and re-created later. Compositors should │ │ │ │ │ + avoid re- using the same name if possible. │ │ │ │ │ │ │ │ │ │ - If transform is not one of the values from the │ │ │ │ │ - "WlOutput.transform()" enum the invalid_transform protocol error │ │ │ │ │ - is raised. │ │ │ │ │ + The name event will be followed by a done event. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - **transform** (*ArgumentType.Int*) -- transform for │ │ │ │ │ - interpreting buffer contents │ │ │ │ │ - │ │ │ │ │ - set_buffer_scale(scale: 'int') -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Request -- opcode 8 (attached to "Resource" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Sets the buffer scaling factor │ │ │ │ │ + **name** (*ArgumentType.String*) -- output name │ │ │ │ │ │ │ │ │ │ - This request sets an optional scaling factor on how the │ │ │ │ │ - compositor interprets the contents of the buffer attached to the │ │ │ │ │ - window. │ │ │ │ │ + description(description: 'str') -> 'None' │ │ │ │ │ │ │ │ │ │ - Buffer scale is double-buffered state, see "WlSurface.commit()". │ │ │ │ │ + -[ Event -- opcode 5 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - A newly created surface has its buffer scale set to 1. │ │ │ │ │ + Human-readable description of this output │ │ │ │ │ │ │ │ │ │ - "WlSurface.set_buffer_scale()" changes the pending buffer scale. │ │ │ │ │ - "WlSurface.commit()" copies the pending buffer scale to the │ │ │ │ │ - current one. Otherwise, the pending and current values are never │ │ │ │ │ - changed. │ │ │ │ │ + Many compositors can produce human-readable descriptions of │ │ │ │ │ + their outputs. The client may wish to know this description as │ │ │ │ │ + well, e.g. for output selection purposes. │ │ │ │ │ │ │ │ │ │ - The purpose of this request is to allow clients to supply higher │ │ │ │ │ - resolution buffer data for use on high resolution outputs. It is │ │ │ │ │ - intended that you pick the same buffer scale as the scale of the │ │ │ │ │ - output that the surface is displayed on. This means the │ │ │ │ │ - compositor can avoid scaling when rendering the surface on that │ │ │ │ │ - output. │ │ │ │ │ + The description is a UTF-8 string with no convention defined for │ │ │ │ │ + its contents. The description is not guaranteed to be unique │ │ │ │ │ + among all "WlOutput" globals. Examples might include 'Foocorp │ │ │ │ │ + 11" Display' or 'Virtual X11 output via :1'. │ │ │ │ │ │ │ │ │ │ - Note that if the scale is larger than 1, then you have to attach │ │ │ │ │ - a buffer that is larger (by a factor of scale in each dimension) │ │ │ │ │ - than the desired surface size. │ │ │ │ │ + The description event is sent after binding the output object │ │ │ │ │ + and whenever the description changes. The description is │ │ │ │ │ + optional, and may not be sent at all. │ │ │ │ │ │ │ │ │ │ - If scale is not greater than 0 the invalid_scale protocol error │ │ │ │ │ - is raised. │ │ │ │ │ + The description event will be followed by a done event. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - **scale** (*ArgumentType.Int*) -- scale for interpreting │ │ │ │ │ - buffer contents │ │ │ │ │ - │ │ │ │ │ - damage_buffer(x: 'int', y: 'int', width: 'int', height: 'int') -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Request -- opcode 9 (attached to "Resource" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Mark part of the surface damaged using buffer coordinates │ │ │ │ │ - │ │ │ │ │ - This request is used to describe the regions where the pending │ │ │ │ │ - buffer is different from the current surface contents, and where │ │ │ │ │ - the surface therefore needs to be repainted. The compositor │ │ │ │ │ - ignores the parts of the damage that fall outside of the │ │ │ │ │ - surface. │ │ │ │ │ - │ │ │ │ │ - Damage is double-buffered state, see "WlSurface.commit()". │ │ │ │ │ - │ │ │ │ │ - The damage rectangle is specified in buffer coordinates, where x │ │ │ │ │ - and y specify the upper left corner of the damage rectangle. │ │ │ │ │ - │ │ │ │ │ - The initial value for pending damage is empty: no damage. │ │ │ │ │ - "WlSurface.damage_buffer()" adds pending damage: the new pending │ │ │ │ │ - damage is the union of old pending damage and the given │ │ │ │ │ - rectangle. │ │ │ │ │ - │ │ │ │ │ - "WlSurface.commit()" assigns pending damage as the current │ │ │ │ │ - damage, and clears pending damage. The server will clear the │ │ │ │ │ - current damage as it repaints the surface. │ │ │ │ │ - │ │ │ │ │ - This request differs from "WlSurface.damage()" in only one way - │ │ │ │ │ - it takes damage in buffer coordinates instead of surface-local │ │ │ │ │ - coordinates. While this generally is more intuitive than surface │ │ │ │ │ - coordinates, it is especially desirable when using wp_viewport │ │ │ │ │ - or when a drawing library (like EGL) is unaware of buffer scale │ │ │ │ │ - and buffer transform. │ │ │ │ │ + **description** (*ArgumentType.String*) -- output description │ │ │ │ │ │ │ │ │ │ - Note: Because buffer transformation changes and damage requests │ │ │ │ │ - may be interleaved in the protocol stream, it is impossible to │ │ │ │ │ - determine the actual mapping between surface and buffer damage │ │ │ │ │ - until "WlSurface.commit()" time. Therefore, compositors wishing │ │ │ │ │ - to take both kinds of damage into account will have to │ │ │ │ │ - accumulate damage from the two requests separately and only │ │ │ │ │ - transform from one to the other after receiving the │ │ │ │ │ - "WlSurface.commit()". │ │ │ │ │ │ │ │ │ │ - Parameters: │ │ │ │ │ - * **x** (*ArgumentType.Int*) -- buffer-local x coordinate │ │ │ │ │ +WlRegistry │ │ │ │ │ +========== │ │ │ │ │ │ │ │ │ │ - * **y** (*ArgumentType.Int*) -- buffer-local y coordinate │ │ │ │ │ +class pywayland.protocol.wayland.WlRegistry │ │ │ │ │ │ │ │ │ │ - * **width** (*ArgumentType.Int*) -- width of damage rectangle │ │ │ │ │ + Global registry object │ │ │ │ │ │ │ │ │ │ - * **height** (*ArgumentType.Int*) -- height of damage │ │ │ │ │ - rectangle │ │ │ │ │ + The singleton global registry object. The server has a number of │ │ │ │ │ + global objects that are available to all clients. These objects │ │ │ │ │ + typically represent an actual object in the server (for example, an │ │ │ │ │ + input device) or they are singleton objects that provide extension │ │ │ │ │ + functionality. │ │ │ │ │ │ │ │ │ │ - offset(x: 'int', y: 'int') -> 'None' │ │ │ │ │ + When a client creates a registry object, the registry object will │ │ │ │ │ + emit a global event for each global currently in the registry. │ │ │ │ │ + Globals come and go as a result of device or monitor hotplugs, │ │ │ │ │ + reconfiguration or other events, and the registry will send out │ │ │ │ │ + global and global_remove events to keep the client up to date with │ │ │ │ │ + the changes. To mark the end of the initial burst of events, the │ │ │ │ │ + client can use the "WlDisplay.sync()" request immediately after │ │ │ │ │ + calling "WlDisplay.get_registry()". │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 10 (attached to "Resource" instance) ]- │ │ │ │ │ + A client can bind to a global object by using the bind request. │ │ │ │ │ + This creates a client-side handle that lets the object emit events │ │ │ │ │ + to the client and lets the client invoke requests on the object. │ │ │ │ │ │ │ │ │ │ - Set the surface contents offset │ │ │ │ │ + bind(name: 'int', interface: 'type[T]', version: 'int') -> 'Proxy[T]' │ │ │ │ │ │ │ │ │ │ - The x and y arguments specify the location of the new pending │ │ │ │ │ - buffer's upper left corner, relative to the current buffer's │ │ │ │ │ - upper left corner, in surface-local coordinates. In other words, │ │ │ │ │ - the x and y, combined with the new surface size define in which │ │ │ │ │ - directions the surface's size changes. │ │ │ │ │ + -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Surface location offset is double-buffered state, see │ │ │ │ │ - "WlSurface.commit()". │ │ │ │ │ + Bind an object to the display │ │ │ │ │ │ │ │ │ │ - This request is semantically equivalent to and the replaces the │ │ │ │ │ - x and y arguments in the "WlSurface.attach()" request in │ │ │ │ │ - "WlSurface" versions prior to 5. See "WlSurface.attach()" for │ │ │ │ │ - details. │ │ │ │ │ + Binds a new, client-created object to the server using the │ │ │ │ │ + specified name as the identifier. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - * **x** (*ArgumentType.Int*) -- surface-local x coordinate │ │ │ │ │ - │ │ │ │ │ - * **y** (*ArgumentType.Int*) -- surface-local y coordinate │ │ │ │ │ - │ │ │ │ │ - enter(output: 'WlOutput') -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Surface enters an output │ │ │ │ │ + * **name** (*ArgumentType.Uint*) -- unique numeric name of │ │ │ │ │ + the object │ │ │ │ │ │ │ │ │ │ - This is emitted whenever a surface's creation, movement, or │ │ │ │ │ - resizing results in some part of it being within the scanout │ │ │ │ │ - region of an output. │ │ │ │ │ + * **interface** (*string*) -- Interface name │ │ │ │ │ │ │ │ │ │ - Note that a surface may be overlapping with zero or more │ │ │ │ │ - outputs. │ │ │ │ │ + * **version** (*int*) -- Interface version │ │ │ │ │ │ │ │ │ │ - Parameters: │ │ │ │ │ - **output** ("WlOutput") -- output entered by the surface │ │ │ │ │ + Returns: │ │ │ │ │ + "pywayland.client.proxy.Proxy" of specified Interface -- │ │ │ │ │ + bounded object │ │ │ │ │ │ │ │ │ │ - leave(output: 'WlOutput') -> 'None' │ │ │ │ │ + global_(name: 'int', interface: 'str', version: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 1 (attached to "Proxy" instance) ]- │ │ │ │ │ + -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - Surface leaves an output │ │ │ │ │ + Announce global object │ │ │ │ │ │ │ │ │ │ - This is emitted whenever a surface's creation, movement, or │ │ │ │ │ - resizing results in it no longer having any part of it within │ │ │ │ │ - the scanout region of an output. │ │ │ │ │ + Notify the client of global objects. │ │ │ │ │ │ │ │ │ │ - Clients should not use the number of outputs the surface is on │ │ │ │ │ - for frame throttling purposes. The surface might be hidden even │ │ │ │ │ - if no leave event has been sent, and the compositor might expect │ │ │ │ │ - new surface content updates even if no enter event has been │ │ │ │ │ - sent. The frame event should be used instead. │ │ │ │ │ + The event notifies the client that a global object with the │ │ │ │ │ + given name is now available, and it implements the given version │ │ │ │ │ + of the given interface. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - **output** ("WlOutput") -- output left by the surface │ │ │ │ │ - │ │ │ │ │ - preferred_buffer_scale(factor: 'int') -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Event -- opcode 2 (attached to "Proxy" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Preferred buffer scale for the surface │ │ │ │ │ - │ │ │ │ │ - This event indicates the preferred buffer scale for this │ │ │ │ │ - surface. It is sent whenever the compositor's preference │ │ │ │ │ - changes. │ │ │ │ │ - │ │ │ │ │ - Before receiving this event the preferred buffer scale for this │ │ │ │ │ - surface is 1. │ │ │ │ │ - │ │ │ │ │ - It is intended that scaling aware clients use this event to │ │ │ │ │ - scale their content and use "WlSurface.set_buffer_scale()" to │ │ │ │ │ - indicate the scale they have rendered with. This allows clients │ │ │ │ │ - to supply a higher detail buffer. │ │ │ │ │ + * **name** (*ArgumentType.Uint*) -- numeric name of the │ │ │ │ │ + global object │ │ │ │ │ │ │ │ │ │ - The compositor shall emit a scale value greater than 0. │ │ │ │ │ + * **interface** (*ArgumentType.String*) -- interface │ │ │ │ │ + implemented by the object │ │ │ │ │ │ │ │ │ │ - Parameters: │ │ │ │ │ - **factor** (*ArgumentType.Int*) -- preferred scaling factor │ │ │ │ │ + * **version** (*ArgumentType.Uint*) -- interface version │ │ │ │ │ │ │ │ │ │ - preferred_buffer_transform(transform: 'int') -> 'None' │ │ │ │ │ + global_remove(name: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 3 (attached to "Proxy" instance) ]- │ │ │ │ │ + -[ Event -- opcode 1 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - Preferred buffer transform for the surface │ │ │ │ │ + Announce removal of global object │ │ │ │ │ │ │ │ │ │ - This event indicates the preferred buffer transform for this │ │ │ │ │ - surface. It is sent whenever the compositor's preference │ │ │ │ │ - changes. │ │ │ │ │ + Notify the client of removed global objects. │ │ │ │ │ │ │ │ │ │ - Before receiving this event the preferred buffer transform for │ │ │ │ │ - this surface is normal. │ │ │ │ │ + This event notifies the client that the global identified by │ │ │ │ │ + name is no longer available. If the client bound to the global │ │ │ │ │ + using the bind request, the client should now destroy that │ │ │ │ │ + object. │ │ │ │ │ │ │ │ │ │ - Applying this transformation to the surface buffer contents and │ │ │ │ │ - using "WlSurface.set_buffer_transform()" might allow the │ │ │ │ │ - compositor to use the surface buffer more efficiently. │ │ │ │ │ + The object remains valid and requests to the object will be │ │ │ │ │ + ignored until the client destroys it, to avoid races between the │ │ │ │ │ + global going away and a client sending a request to it. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - **transform** (*ArgumentType.Uint*) -- preferred transform │ │ │ │ │ + **name** (*ArgumentType.Uint*) -- numeric name of the global │ │ │ │ │ + object │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ -WlTouch │ │ │ │ │ -======= │ │ │ │ │ - │ │ │ │ │ -class pywayland.protocol.wayland.WlTouch │ │ │ │ │ +WlDataSource │ │ │ │ │ +============ │ │ │ │ │ │ │ │ │ │ - Touchscreen input device │ │ │ │ │ +class pywayland.protocol.wayland.WlDataSource │ │ │ │ │ │ │ │ │ │ - The "WlTouch" interface represents a touchscreen associated with a │ │ │ │ │ - seat. │ │ │ │ │ + Offer to transfer data │ │ │ │ │ │ │ │ │ │ - Touch interactions can consist of one or more contacts. For each │ │ │ │ │ - contact, a series of events is generated, starting with a down │ │ │ │ │ - event, followed by zero or more motion events, and ending with an │ │ │ │ │ - up event. Events relating to the same contact point can be │ │ │ │ │ - identified by the ID of the sequence. │ │ │ │ │ + The "WlDataSource" object is the source side of a "WlDataOffer". It │ │ │ │ │ + is created by the source client in a data transfer and provides a │ │ │ │ │ + way to describe the offered data and a way to respond to requests │ │ │ │ │ + to transfer the data. │ │ │ │ │ │ │ │ │ │ - release() -> 'None' │ │ │ │ │ + offer(mime_type: 'str') -> 'None' │ │ │ │ │ │ │ │ │ │ -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Release the touch object │ │ │ │ │ - │ │ │ │ │ - down(serial: 'int', time: 'int', surface: 'WlSurface', id: 'int', x: 'float', y: 'float') -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Touch down event and beginning of a touch sequence │ │ │ │ │ + Add an offered mime type │ │ │ │ │ │ │ │ │ │ - A new touch point has appeared on the surface. This touch point │ │ │ │ │ - is assigned a unique ID. Future events from this touch point │ │ │ │ │ - reference this ID. The ID ceases to be valid after a touch up │ │ │ │ │ - event and may be reused in the future. │ │ │ │ │ + This request adds a mime type to the set of mime types │ │ │ │ │ + advertised to targets. Can be called several times to offer │ │ │ │ │ + multiple types. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - * **serial** (*ArgumentType.Uint*) -- serial number of the │ │ │ │ │ - touch down event │ │ │ │ │ - │ │ │ │ │ - * **time** (*ArgumentType.Uint*) -- timestamp with │ │ │ │ │ - millisecond granularity │ │ │ │ │ - │ │ │ │ │ - * **surface** ("WlSurface") -- surface touched │ │ │ │ │ - │ │ │ │ │ - * **id** (*ArgumentType.Int*) -- the unique ID of this touch │ │ │ │ │ - point │ │ │ │ │ - │ │ │ │ │ - * **x** (*ArgumentType.Fixed*) -- surface-local x coordinate │ │ │ │ │ - │ │ │ │ │ - * **y** (*ArgumentType.Fixed*) -- surface-local y coordinate │ │ │ │ │ - │ │ │ │ │ - up(serial: 'int', time: 'int', id: 'int') -> 'None' │ │ │ │ │ + **mime_type** (*ArgumentType.String*) -- mime type offered by │ │ │ │ │ + the data source │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 1 (attached to "Proxy" instance) ]- │ │ │ │ │ + destroy() -> 'None' │ │ │ │ │ │ │ │ │ │ - End of a touch event sequence │ │ │ │ │ + -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - The touch point has disappeared. No further events will be sent │ │ │ │ │ - for this touch point and the touch point's ID is released and │ │ │ │ │ - may be reused in a future touch down event. │ │ │ │ │ + Destroy the data source │ │ │ │ │ │ │ │ │ │ - Parameters: │ │ │ │ │ - * **serial** (*ArgumentType.Uint*) -- serial number of the │ │ │ │ │ - touch up event │ │ │ │ │ + Destroy the data source. │ │ │ │ │ │ │ │ │ │ - * **time** (*ArgumentType.Uint*) -- timestamp with │ │ │ │ │ - millisecond granularity │ │ │ │ │ + set_actions(dnd_actions: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - * **id** (*ArgumentType.Int*) -- the unique ID of this touch │ │ │ │ │ - point │ │ │ │ │ + -[ Request -- opcode 2 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - motion(time: 'int', id: 'int', x: 'float', y: 'float') -> 'None' │ │ │ │ │ + Set the available drag-and-drop actions │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 2 (attached to "Proxy" instance) ]- │ │ │ │ │ + Sets the actions that the source side client supports for this │ │ │ │ │ + operation. This request may trigger "WlDataSource.action()" and │ │ │ │ │ + "WlDataOffer.action()" events if the compositor needs to change │ │ │ │ │ + the selected action. │ │ │ │ │ │ │ │ │ │ - Update of touch point coordinates │ │ │ │ │ + The dnd_actions argument must contain only values expressed in │ │ │ │ │ + the "WlDataDeviceManager.dnd_actions()" enum, otherwise it will │ │ │ │ │ + result in a protocol error. │ │ │ │ │ │ │ │ │ │ - A touch point has changed coordinates. │ │ │ │ │ + This request must be made once only, and can only be made on │ │ │ │ │ + sources used in drag-and-drop, so it must be performed before │ │ │ │ │ + "WlDataDevice.start_drag()". Attempting to use the source other │ │ │ │ │ + than for drag-and-drop will raise a protocol error. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - * **time** (*ArgumentType.Uint*) -- timestamp with │ │ │ │ │ - millisecond granularity │ │ │ │ │ - │ │ │ │ │ - * **id** (*ArgumentType.Int*) -- the unique ID of this touch │ │ │ │ │ - point │ │ │ │ │ - │ │ │ │ │ - * **x** (*ArgumentType.Fixed*) -- surface-local x coordinate │ │ │ │ │ - │ │ │ │ │ - * **y** (*ArgumentType.Fixed*) -- surface-local y coordinate │ │ │ │ │ - │ │ │ │ │ - frame() -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Event -- opcode 3 (attached to "Proxy" instance) ]- │ │ │ │ │ - │ │ │ │ │ - End of touch frame event │ │ │ │ │ - │ │ │ │ │ - Indicates the end of a set of events that logically belong │ │ │ │ │ - together. A client is expected to accumulate the data in all │ │ │ │ │ - events within the frame before proceeding. │ │ │ │ │ - │ │ │ │ │ - A "WlTouch.frame()" terminates at least one event but otherwise │ │ │ │ │ - no guarantee is provided about the set of events within a frame. │ │ │ │ │ - A client must assume that any state not updated in a frame is │ │ │ │ │ - unchanged from the previously known state. │ │ │ │ │ - │ │ │ │ │ - cancel() -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Event -- opcode 4 (attached to "Proxy" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Touch session cancelled │ │ │ │ │ - │ │ │ │ │ - Sent if the compositor decides the touch stream is a global │ │ │ │ │ - gesture. No further events are sent to the clients from that │ │ │ │ │ - particular gesture. Touch cancellation applies to all touch │ │ │ │ │ - points currently active on this client's surface. The client is │ │ │ │ │ - responsible for finalizing the touch points, future touch points │ │ │ │ │ - on this surface may reuse the touch point ID. │ │ │ │ │ - │ │ │ │ │ - No frame event is required after the cancel event. │ │ │ │ │ - │ │ │ │ │ - shape(id: 'int', major: 'float', minor: 'float') -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Event -- opcode 5 (attached to "Proxy" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Update shape of touch point │ │ │ │ │ + **dnd_actions** (*ArgumentType.Uint*) -- actions supported by │ │ │ │ │ + the data source │ │ │ │ │ │ │ │ │ │ - Sent when a touchpoint has changed its shape. │ │ │ │ │ + target(mime_type: 'str | None') -> 'None' │ │ │ │ │ │ │ │ │ │ - This event does not occur on its own. It is sent before a │ │ │ │ │ - "WlTouch.frame()" event and carries the new shape information │ │ │ │ │ - for any previously reported, or new touch points of that frame. │ │ │ │ │ + -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - Other events describing the touch point such as │ │ │ │ │ - "WlTouch.down()", "WlTouch.motion()" or "WlTouch.orientation()" │ │ │ │ │ - may be sent within the same "WlTouch.frame()". A client should │ │ │ │ │ - treat these events as a single logical touch point update. The │ │ │ │ │ - order of "WlTouch.shape()", "WlTouch.orientation()" and │ │ │ │ │ - "WlTouch.motion()" is not guaranteed. A "WlTouch.down()" event │ │ │ │ │ - is guaranteed to occur before the first "WlTouch.shape()" event │ │ │ │ │ - for this touch ID but both events may occur within the same │ │ │ │ │ - "WlTouch.frame()". │ │ │ │ │ + A target accepts an offered mime type │ │ │ │ │ │ │ │ │ │ - A touchpoint shape is approximated by an ellipse through the │ │ │ │ │ - major and minor axis length. The major axis length describes the │ │ │ │ │ - longer diameter of the ellipse, while the minor axis length │ │ │ │ │ - describes the shorter diameter. Major and minor are orthogonal │ │ │ │ │ - and both are specified in surface-local coordinates. The center │ │ │ │ │ - of the ellipse is always at the touchpoint location as reported │ │ │ │ │ - by "WlTouch.down()" or "WlTouch.move()". │ │ │ │ │ + Sent when a target accepts pointer_focus or motion events. If a │ │ │ │ │ + target does not accept any of the offered types, type is NULL. │ │ │ │ │ │ │ │ │ │ - This event is only sent by the compositor if the touch device │ │ │ │ │ - supports shape reports. The client has to make reasonable │ │ │ │ │ - assumptions about the shape if it did not receive this event. │ │ │ │ │ + Used for feedback during drag-and-drop. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - * **id** (*ArgumentType.Int*) -- the unique ID of this touch │ │ │ │ │ - point │ │ │ │ │ - │ │ │ │ │ - * **major** (*ArgumentType.Fixed*) -- length of the major │ │ │ │ │ - axis in surface-local coordinates │ │ │ │ │ - │ │ │ │ │ - * **minor** (*ArgumentType.Fixed*) -- length of the minor │ │ │ │ │ - axis in surface-local coordinates │ │ │ │ │ - │ │ │ │ │ - orientation(id: 'int', orientation: 'float') -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Event -- opcode 6 (attached to "Proxy" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Update orientation of touch point │ │ │ │ │ - │ │ │ │ │ - Sent when a touchpoint has changed its orientation. │ │ │ │ │ + **mime_type** (*ArgumentType.String* or *None*) -- mime type │ │ │ │ │ + accepted by the target │ │ │ │ │ │ │ │ │ │ - This event does not occur on its own. It is sent before a │ │ │ │ │ - "WlTouch.frame()" event and carries the new shape information │ │ │ │ │ - for any previously reported, or new touch points of that frame. │ │ │ │ │ + send(mime_type: 'str', fd: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - Other events describing the touch point such as │ │ │ │ │ - "WlTouch.down()", "WlTouch.motion()" or "WlTouch.shape()" may be │ │ │ │ │ - sent within the same "WlTouch.frame()". A client should treat │ │ │ │ │ - these events as a single logical touch point update. The order │ │ │ │ │ - of "WlTouch.shape()", "WlTouch.orientation()" and │ │ │ │ │ - "WlTouch.motion()" is not guaranteed. A "WlTouch.down()" event │ │ │ │ │ - is guaranteed to occur before the first "WlTouch.orientation()" │ │ │ │ │ - event for this touch ID but both events may occur within the │ │ │ │ │ - same "WlTouch.frame()". │ │ │ │ │ + -[ Event -- opcode 1 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - The orientation describes the clockwise angle of a touchpoint's │ │ │ │ │ - major axis to the positive surface y-axis and is normalized to │ │ │ │ │ - the -180 to +180 degree range. The granularity of orientation │ │ │ │ │ - depends on the touch device, some devices only support binary │ │ │ │ │ - rotation values between 0 and 90 degrees. │ │ │ │ │ + Send the data │ │ │ │ │ │ │ │ │ │ - This event is only sent by the compositor if the touch device │ │ │ │ │ - supports orientation reports. │ │ │ │ │ + Request for data from the client. Send the data as the │ │ │ │ │ + specified mime type over the passed file descriptor, then close │ │ │ │ │ + it. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - * **id** (*ArgumentType.Int*) -- the unique ID of this touch │ │ │ │ │ - point │ │ │ │ │ - │ │ │ │ │ - * **orientation** (*ArgumentType.Fixed*) -- angle between │ │ │ │ │ - major axis and positive surface y-axis in degrees │ │ │ │ │ - │ │ │ │ │ - │ │ │ │ │ -WlRegion │ │ │ │ │ -======== │ │ │ │ │ - │ │ │ │ │ -class pywayland.protocol.wayland.WlRegion │ │ │ │ │ - │ │ │ │ │ - Region interface │ │ │ │ │ - │ │ │ │ │ - A region object describes an area. │ │ │ │ │ - │ │ │ │ │ - Region objects are used to describe the opaque and input regions of │ │ │ │ │ - a surface. │ │ │ │ │ - │ │ │ │ │ - destroy() -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Destroy region │ │ │ │ │ - │ │ │ │ │ - Destroy the region. This will invalidate the object ID. │ │ │ │ │ - │ │ │ │ │ - add(x: 'int', y: 'int', width: 'int', height: 'int') -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Add rectangle to region │ │ │ │ │ - │ │ │ │ │ - Add the specified rectangle to the region. │ │ │ │ │ + * **mime_type** (*ArgumentType.String*) -- mime type for the │ │ │ │ │ + data │ │ │ │ │ │ │ │ │ │ - Parameters: │ │ │ │ │ - * **x** (*ArgumentType.Int*) -- region-local x coordinate │ │ │ │ │ + * **fd** (*ArgumentType.FileDescriptor*) -- file descriptor │ │ │ │ │ + for the data │ │ │ │ │ │ │ │ │ │ - * **y** (*ArgumentType.Int*) -- region-local y coordinate │ │ │ │ │ + cancelled() -> 'None' │ │ │ │ │ │ │ │ │ │ - * **width** (*ArgumentType.Int*) -- rectangle width │ │ │ │ │ + -[ Event -- opcode 2 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - * **height** (*ArgumentType.Int*) -- rectangle height │ │ │ │ │ + Selection was cancelled │ │ │ │ │ │ │ │ │ │ - subtract(x: 'int', y: 'int', width: 'int', height: 'int') -> 'None' │ │ │ │ │ + This data source is no longer valid. There are several reasons │ │ │ │ │ + why this could happen: │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 2 (attached to "Resource" instance) ]- │ │ │ │ │ + * The data source has been replaced by another data source. │ │ │ │ │ │ │ │ │ │ - Subtract rectangle from region │ │ │ │ │ + * The drag-and-drop operation was performed, but the drop │ │ │ │ │ + destination did not accept any of the mime types offered │ │ │ │ │ + through "WlDataSource.target()". │ │ │ │ │ │ │ │ │ │ - Subtract the specified rectangle from the region. │ │ │ │ │ + * The drag-and-drop operation was performed, but the drop │ │ │ │ │ + destination did not select any of the actions present in the │ │ │ │ │ + mask offered through "WlDataSource.action()". │ │ │ │ │ │ │ │ │ │ - Parameters: │ │ │ │ │ - * **x** (*ArgumentType.Int*) -- region-local x coordinate │ │ │ │ │ + * The drag-and-drop operation was performed but didn't happen │ │ │ │ │ + over a surface. │ │ │ │ │ │ │ │ │ │ - * **y** (*ArgumentType.Int*) -- region-local y coordinate │ │ │ │ │ + * The compositor cancelled the drag-and-drop operation (e.g. │ │ │ │ │ + compositor dependent timeouts to avoid stale drag-and-drop │ │ │ │ │ + transfers). │ │ │ │ │ │ │ │ │ │ - * **width** (*ArgumentType.Int*) -- rectangle width │ │ │ │ │ + The client should clean up and destroy this data source. │ │ │ │ │ │ │ │ │ │ - * **height** (*ArgumentType.Int*) -- rectangle height │ │ │ │ │ + For objects of version 2 or older, "WlDataSource.cancelled()" │ │ │ │ │ + will only be emitted if the data source was replaced by another │ │ │ │ │ + data source. │ │ │ │ │ │ │ │ │ │ + dnd_drop_performed() -> 'None' │ │ │ │ │ │ │ │ │ │ -WlSubcompositor │ │ │ │ │ -=============== │ │ │ │ │ + -[ Event -- opcode 3 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ -class pywayland.protocol.wayland.WlSubcompositor │ │ │ │ │ + The drag-and-drop operation physically finished │ │ │ │ │ │ │ │ │ │ - Sub-surface compositing │ │ │ │ │ + The user performed the drop action. This event does not indicate │ │ │ │ │ + acceptance, "WlDataSource.cancelled()" may still be emitted │ │ │ │ │ + afterwards if the drop destination does not accept any mime │ │ │ │ │ + type. │ │ │ │ │ │ │ │ │ │ - The global interface exposing sub-surface compositing capabilities. │ │ │ │ │ - A "WlSurface", that has sub-surfaces associated, is called the │ │ │ │ │ - parent surface. Sub-surfaces can be arbitrarily nested and create a │ │ │ │ │ - tree of sub-surfaces. │ │ │ │ │ + However, this event might however not be received if the │ │ │ │ │ + compositor cancelled the drag-and-drop operation before this │ │ │ │ │ + event could happen. │ │ │ │ │ │ │ │ │ │ - The root surface in a tree of sub-surfaces is the main surface. The │ │ │ │ │ - main surface cannot be a sub-surface, because sub-surfaces must │ │ │ │ │ - always have a parent. │ │ │ │ │ + Note that the data_source may still be used in the future and │ │ │ │ │ + should not be destroyed here. │ │ │ │ │ │ │ │ │ │ - A main surface with its sub-surfaces forms a (compound) window. For │ │ │ │ │ - window management purposes, this set of "WlSurface" objects is to │ │ │ │ │ - be considered as a single window, and it should also behave as │ │ │ │ │ - such. │ │ │ │ │ + dnd_finished() -> 'None' │ │ │ │ │ │ │ │ │ │ - The aim of sub-surfaces is to offload some of the compositing work │ │ │ │ │ - within a window from clients to the compositor. A prime example is │ │ │ │ │ - a video player with decorations and video in separate "WlSurface" │ │ │ │ │ - objects. This should allow the compositor to pass YUV video buffer │ │ │ │ │ - processing to dedicated overlay hardware when possible. │ │ │ │ │ + -[ Event -- opcode 4 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - destroy() -> 'None' │ │ │ │ │ + The drag-and-drop operation concluded │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ + The drop destination finished interoperating with this data │ │ │ │ │ + source, so the client is now free to destroy this data source │ │ │ │ │ + and free all associated data. │ │ │ │ │ │ │ │ │ │ - Unbind from the subcompositor interface │ │ │ │ │ + If the action used to perform the operation was "move", the │ │ │ │ │ + source can now delete the transferred data. │ │ │ │ │ │ │ │ │ │ - Informs the server that the client will not be using this │ │ │ │ │ - protocol object anymore. This does not affect any other objects, │ │ │ │ │ - "WlSubsurface" objects included. │ │ │ │ │ + action(dnd_action: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - get_subsurface(surface: 'WlSurface', parent: 'WlSurface') -> 'Proxy[WlSubsurface]' │ │ │ │ │ + -[ Event -- opcode 5 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ + Notify the selected action │ │ │ │ │ │ │ │ │ │ - Give a surface the role sub-surface │ │ │ │ │ + This event indicates the action selected by the compositor after │ │ │ │ │ + matching the source/destination side actions. Only one action │ │ │ │ │ + (or none) will be offered here. │ │ │ │ │ │ │ │ │ │ - Create a sub-surface interface for the given surface, and │ │ │ │ │ - associate it with the given parent surface. This turns a plain │ │ │ │ │ - "WlSurface" into a sub-surface. │ │ │ │ │ + This event can be emitted multiple times during the drag-and- │ │ │ │ │ + drop operation, mainly in response to destination side changes │ │ │ │ │ + through "WlDataOffer.set_actions()", and as the data device │ │ │ │ │ + enters/leaves surfaces. │ │ │ │ │ │ │ │ │ │ - The to-be sub-surface must not already have another role, and it │ │ │ │ │ - must not have an existing "WlSubsurface" object. Otherwise the │ │ │ │ │ - bad_surface protocol error is raised. │ │ │ │ │ + It is only possible to receive this event after │ │ │ │ │ + "WlDataSource.dnd_drop_performed()" if the drag-and-drop │ │ │ │ │ + operation ended in an "ask" action, in which case the final │ │ │ │ │ + "WlDataSource.action()" event will happen immediately before │ │ │ │ │ + "WlDataSource.dnd_finished()". │ │ │ │ │ │ │ │ │ │ - Adding sub-surfaces to a parent is a double-buffered operation │ │ │ │ │ - on the parent (see "WlSurface.commit()"). The effect of adding a │ │ │ │ │ - sub-surface becomes visible on the next time the state of the │ │ │ │ │ - parent surface is applied. │ │ │ │ │ + Compositors may also change the selected action on the fly, │ │ │ │ │ + mainly in response to keyboard modifier changes during the drag- │ │ │ │ │ + and-drop operation. │ │ │ │ │ │ │ │ │ │ - The parent surface must not be one of the child surface's │ │ │ │ │ - descendants, and the parent must be different from the child │ │ │ │ │ - surface, otherwise the bad_parent protocol error is raised. │ │ │ │ │ + The most recent action received is always the valid one. The │ │ │ │ │ + chosen action may change alongside negotiation (e.g. an "ask" │ │ │ │ │ + action can turn into a "move" operation), so the effects of the │ │ │ │ │ + final action must always be applied in │ │ │ │ │ + "WlDataOffer.dnd_finished()". │ │ │ │ │ │ │ │ │ │ - This request modifies the behaviour of "WlSurface.commit()" │ │ │ │ │ - request on the sub- surface, see the documentation on │ │ │ │ │ - "WlSubsurface" interface. │ │ │ │ │ + Clients can trigger cursor surface changes from this point, so │ │ │ │ │ + they reflect the current action. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - * **surface** ("WlSurface") -- the surface to be turned into │ │ │ │ │ - a sub-surface │ │ │ │ │ - │ │ │ │ │ - * **parent** ("WlSurface") -- the parent surface │ │ │ │ │ - │ │ │ │ │ - Returns: │ │ │ │ │ - "WlSubsurface" -- the new sub- surface object ID │ │ │ │ │ + **dnd_action** (*ArgumentType.Uint*) -- action selected by │ │ │ │ │ + the compositor │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ WlPointer │ │ │ │ │ ========= │ │ │ │ │ │ │ │ │ │ class pywayland.protocol.wayland.WlPointer │ │ │ │ │ │ │ │ │ │ @@ -2230,495 +2132,923 @@ │ │ │ │ │ Parameters: │ │ │ │ │ * **axis** (*ArgumentType.Uint*) -- axis type │ │ │ │ │ │ │ │ │ │ * **direction** (*ArgumentType.Uint*) -- physical direction │ │ │ │ │ relative to axis motion │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ -WlDataOffer │ │ │ │ │ -=========== │ │ │ │ │ +WlDataDeviceManager │ │ │ │ │ +=================== │ │ │ │ │ │ │ │ │ │ -class pywayland.protocol.wayland.WlDataOffer │ │ │ │ │ +class pywayland.protocol.wayland.WlDataDeviceManager │ │ │ │ │ │ │ │ │ │ - Offer to transfer data │ │ │ │ │ + Data transfer interface │ │ │ │ │ │ │ │ │ │ - A "WlDataOffer" represents a piece of data offered for transfer by │ │ │ │ │ - another client (the source client). It is used by the copy-and- │ │ │ │ │ - paste and drag-and-drop mechanisms. The offer describes the │ │ │ │ │ - different mime types that the data can be converted to and provides │ │ │ │ │ - the mechanism for transferring the data directly from the source │ │ │ │ │ - client. │ │ │ │ │ + The "WlDataDeviceManager" is a singleton global object that │ │ │ │ │ + provides access to inter-client data transfer mechanisms such as │ │ │ │ │ + copy-and-paste and drag-and-drop. These mechanisms are tied to a │ │ │ │ │ + "WlSeat" and this interface lets a client get a "WlDataDevice" │ │ │ │ │ + corresponding to a "WlSeat". │ │ │ │ │ │ │ │ │ │ - accept(serial: 'int', mime_type: 'str | None') -> 'None' │ │ │ │ │ + Depending on the version bound, the objects created from the bound │ │ │ │ │ + "WlDataDeviceManager" object will have different requirements for │ │ │ │ │ + functioning properly. See "WlDataSource.set_actions()", │ │ │ │ │ + "WlDataOffer.accept()" and "WlDataOffer.finish()" for details. │ │ │ │ │ + │ │ │ │ │ + create_data_source() -> 'Proxy[WlDataSource]' │ │ │ │ │ │ │ │ │ │ -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Accept one of the offered mime types │ │ │ │ │ + Create a new data source │ │ │ │ │ │ │ │ │ │ - Indicate that the client can accept the given mime type, or NULL │ │ │ │ │ - for not accepted. │ │ │ │ │ + Create a new data source. │ │ │ │ │ │ │ │ │ │ - For objects of version 2 or older, this request is used by the │ │ │ │ │ - client to give feedback whether the client can receive the given │ │ │ │ │ - mime type, or NULL if none is accepted; the feedback does not │ │ │ │ │ - determine whether the drag-and-drop operation succeeds or not. │ │ │ │ │ + Returns: │ │ │ │ │ + "WlDataSource" -- data source to create │ │ │ │ │ │ │ │ │ │ - For objects of version 3 or newer, this request determines the │ │ │ │ │ - final result of the drag-and-drop operation. If the end result │ │ │ │ │ - is that no mime types were accepted, the drag-and-drop operation │ │ │ │ │ - will be cancelled and the corresponding drag source will receive │ │ │ │ │ - "WlDataSource.cancelled()". Clients may still use this event in │ │ │ │ │ - conjunction with "WlDataSource.action()" for feedback. │ │ │ │ │ + get_data_device(seat: 'WlSeat') -> 'Proxy[WlDataDevice]' │ │ │ │ │ + │ │ │ │ │ + -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Create a new data device │ │ │ │ │ + │ │ │ │ │ + Create a new data device for a given seat. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - * **serial** (*ArgumentType.Uint*) -- serial number of the │ │ │ │ │ - accept request │ │ │ │ │ + **seat** ("WlSeat") -- seat associated with the data device │ │ │ │ │ │ │ │ │ │ - * **mime_type** (*ArgumentType.String* or *None*) -- mime │ │ │ │ │ - type accepted by the client │ │ │ │ │ + Returns: │ │ │ │ │ + "WlDataDevice" -- data device to create │ │ │ │ │ │ │ │ │ │ - receive(mime_type: 'str', fd: 'int') -> 'None' │ │ │ │ │ + │ │ │ │ │ +WlShm │ │ │ │ │ +===== │ │ │ │ │ + │ │ │ │ │ +class pywayland.protocol.wayland.WlShm │ │ │ │ │ + │ │ │ │ │ + Shared memory support │ │ │ │ │ + │ │ │ │ │ + A singleton global object that provides support for shared memory. │ │ │ │ │ + │ │ │ │ │ + Clients can create "WlShmPool" objects using the create_pool │ │ │ │ │ + request. │ │ │ │ │ + │ │ │ │ │ + On binding the "WlShm" object one or more format events are emitted │ │ │ │ │ + to inform clients about the valid pixel formats that can be used │ │ │ │ │ + for buffers. │ │ │ │ │ + │ │ │ │ │ + create_pool(fd: 'int', size: 'int') -> 'Proxy[WlShmPool]' │ │ │ │ │ + │ │ │ │ │ + -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Create a shm pool │ │ │ │ │ + │ │ │ │ │ + Create a new "WlShmPool" object. │ │ │ │ │ + │ │ │ │ │ + The pool can be used to create shared memory based buffer │ │ │ │ │ + objects. The server will mmap size bytes of the passed file │ │ │ │ │ + descriptor, to use as backing memory for the pool. │ │ │ │ │ + │ │ │ │ │ + Parameters: │ │ │ │ │ + * **fd** (*ArgumentType.FileDescriptor*) -- file descriptor │ │ │ │ │ + for the pool │ │ │ │ │ + │ │ │ │ │ + * **size** (*ArgumentType.Int*) -- pool size, in bytes │ │ │ │ │ + │ │ │ │ │ + Returns: │ │ │ │ │ + "WlShmPool" -- pool to create │ │ │ │ │ + │ │ │ │ │ + release() -> 'None' │ │ │ │ │ │ │ │ │ │ -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Request that the data is transferred │ │ │ │ │ + Release the shm object │ │ │ │ │ │ │ │ │ │ - To transfer the offered data, the client issues this request and │ │ │ │ │ - indicates the mime type it wants to receive. The transfer │ │ │ │ │ - happens through the passed file descriptor (typically created │ │ │ │ │ - with the pipe system call). The source client writes the data │ │ │ │ │ - in the mime type representation requested and then closes the │ │ │ │ │ - file descriptor. │ │ │ │ │ + Using this request a client can tell the server that it is not │ │ │ │ │ + going to use the shm object anymore. │ │ │ │ │ │ │ │ │ │ - The receiving client reads from the read end of the pipe until │ │ │ │ │ - EOF and then closes its end, at which point the transfer is │ │ │ │ │ - complete. │ │ │ │ │ + Objects created via this interface remain unaffected. │ │ │ │ │ │ │ │ │ │ - This request may happen multiple times for different mime types, │ │ │ │ │ - both before and after "WlDataDevice.drop()". Drag-and-drop │ │ │ │ │ - destination clients may preemptively fetch data or examine it │ │ │ │ │ - more closely to determine acceptance. │ │ │ │ │ + format(format: 'int') -> 'None' │ │ │ │ │ + │ │ │ │ │ + -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Pixel format description │ │ │ │ │ + │ │ │ │ │ + Informs the client about a valid pixel format that can be used │ │ │ │ │ + for buffers. Known formats include argb8888 and xrgb8888. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - * **mime_type** (*ArgumentType.String*) -- mime type desired │ │ │ │ │ - by receiver │ │ │ │ │ + **format** (*ArgumentType.Uint*) -- buffer pixel format │ │ │ │ │ │ │ │ │ │ - * **fd** (*ArgumentType.FileDescriptor*) -- file descriptor │ │ │ │ │ - for data transfer │ │ │ │ │ + │ │ │ │ │ +WlBuffer │ │ │ │ │ +======== │ │ │ │ │ + │ │ │ │ │ +class pywayland.protocol.wayland.WlBuffer │ │ │ │ │ + │ │ │ │ │ + Content for a "WlSurface" │ │ │ │ │ + │ │ │ │ │ + A buffer provides the content for a "WlSurface". Buffers are │ │ │ │ │ + created through factory interfaces such as "WlShm", │ │ │ │ │ + wp_linux_buffer_params (from the linux-dmabuf protocol extension) │ │ │ │ │ + or similar. It has a width and a height and can be attached to a │ │ │ │ │ + "WlSurface", but the mechanism by which a client provides and │ │ │ │ │ + updates the contents is defined by the buffer factory interface. │ │ │ │ │ + │ │ │ │ │ + Color channels are assumed to be electrical rather than optical (in │ │ │ │ │ + other words, encoded with a transfer function) unless otherwise │ │ │ │ │ + specified. If the buffer uses a format that has an alpha channel, │ │ │ │ │ + the alpha channel is assumed to be premultiplied into the │ │ │ │ │ + electrical color channel values (after transfer function encoding) │ │ │ │ │ + unless otherwise specified. │ │ │ │ │ + │ │ │ │ │ + Note, because "WlBuffer" objects are created from multiple │ │ │ │ │ + independent factory interfaces, the "WlBuffer" interface is frozen │ │ │ │ │ + at version 1. │ │ │ │ │ + │ │ │ │ │ + destroy() -> 'None' │ │ │ │ │ + │ │ │ │ │ + -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Destroy a buffer │ │ │ │ │ + │ │ │ │ │ + Destroy a buffer. If and how you need to release the backing │ │ │ │ │ + storage is defined by the buffer factory interface. │ │ │ │ │ + │ │ │ │ │ + For possible side-effects to a surface, see │ │ │ │ │ + "WlSurface.attach()". │ │ │ │ │ + │ │ │ │ │ + release() -> 'None' │ │ │ │ │ + │ │ │ │ │ + -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Compositor releases buffer │ │ │ │ │ + │ │ │ │ │ + Sent when this "WlBuffer" is no longer used by the compositor. │ │ │ │ │ + The client is now free to reuse or destroy this buffer and its │ │ │ │ │ + backing storage. │ │ │ │ │ + │ │ │ │ │ + If a client receives a release event before the frame callback │ │ │ │ │ + requested in the same "WlSurface.commit()" that attaches this │ │ │ │ │ + "WlBuffer" to a surface, then the client is immediately free to │ │ │ │ │ + reuse the buffer and its backing storage, and does not need a │ │ │ │ │ + second buffer for the next surface content update. Typically │ │ │ │ │ + this is possible, when the compositor maintains a copy of the │ │ │ │ │ + "WlSurface" contents, e.g. as a GL texture. This is an important │ │ │ │ │ + optimization for GL(ES) compositors with "WlShm" clients. │ │ │ │ │ + │ │ │ │ │ + │ │ │ │ │ +WlSurface │ │ │ │ │ +========= │ │ │ │ │ + │ │ │ │ │ +class pywayland.protocol.wayland.WlSurface │ │ │ │ │ + │ │ │ │ │ + An onscreen surface │ │ │ │ │ + │ │ │ │ │ + A surface is a rectangular area that may be displayed on zero or │ │ │ │ │ + more outputs, and shown any number of times at the compositor's │ │ │ │ │ + discretion. They can present wl_buffers, receive user input, and │ │ │ │ │ + define a local coordinate system. │ │ │ │ │ + │ │ │ │ │ + The size of a surface (and relative positions on it) is described │ │ │ │ │ + in surface-local coordinates, which may differ from the buffer │ │ │ │ │ + coordinates of the pixel content, in case a buffer_transform or a │ │ │ │ │ + buffer_scale is used. │ │ │ │ │ + │ │ │ │ │ + A surface without a "role" is fairly useless: a compositor does not │ │ │ │ │ + know where, when or how to present it. The role is the purpose of a │ │ │ │ │ + "WlSurface". Examples of roles are a cursor for a pointer (as set │ │ │ │ │ + by "WlPointer.set_cursor()"), a drag icon │ │ │ │ │ + ("WlDataDevice.start_drag()"), a sub-surface │ │ │ │ │ + ("WlSubcompositor.get_subsurface()"), and a window as defined by a │ │ │ │ │ + shell protocol (e.g. "WlShell.get_shell_surface()"). │ │ │ │ │ + │ │ │ │ │ + A surface can have only one role at a time. Initially a "WlSurface" │ │ │ │ │ + does not have a role. Once a "WlSurface" is given a role, it is set │ │ │ │ │ + permanently for the whole lifetime of the "WlSurface" object. │ │ │ │ │ + Giving the current role again is allowed, unless explicitly │ │ │ │ │ + forbidden by the relevant interface specification. │ │ │ │ │ + │ │ │ │ │ + Surface roles are given by requests in other interfaces such as │ │ │ │ │ + "WlPointer.set_cursor()". The request should explicitly mention │ │ │ │ │ + that this request gives a role to a "WlSurface". Often, this │ │ │ │ │ + request also creates a new protocol object that represents the role │ │ │ │ │ + and adds additional functionality to "WlSurface". When a client │ │ │ │ │ + wants to destroy a "WlSurface", they must destroy this role object │ │ │ │ │ + before the "WlSurface", otherwise a defunct_role_object error is │ │ │ │ │ + sent. │ │ │ │ │ + │ │ │ │ │ + Destroying the role object does not remove the role from the │ │ │ │ │ + "WlSurface", but it may stop the "WlSurface" from "playing the │ │ │ │ │ + role". For instance, if a "WlSubsurface" object is destroyed, the │ │ │ │ │ + "WlSurface" it was created for will be unmapped and forget its │ │ │ │ │ + position and z-order. It is allowed to create a "WlSubsurface" for │ │ │ │ │ + the same "WlSurface" again, but it is not allowed to use the │ │ │ │ │ + "WlSurface" as a cursor (cursor is a different role than sub- │ │ │ │ │ + surface, and role switching is not allowed). │ │ │ │ │ │ │ │ │ │ destroy() -> 'None' │ │ │ │ │ │ │ │ │ │ + -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Delete surface │ │ │ │ │ + │ │ │ │ │ + Deletes the surface and invalidates its object ID. │ │ │ │ │ + │ │ │ │ │ + attach(buffer: 'WlBuffer | None', x: 'int', y: 'int') -> 'None' │ │ │ │ │ + │ │ │ │ │ + -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Set the surface contents │ │ │ │ │ + │ │ │ │ │ + Set a buffer as the content of this surface. │ │ │ │ │ + │ │ │ │ │ + The new size of the surface is calculated based on the buffer │ │ │ │ │ + size transformed by the inverse buffer_transform and the inverse │ │ │ │ │ + buffer_scale. This means that at commit time the supplied buffer │ │ │ │ │ + size must be an integer multiple of the buffer_scale. If that's │ │ │ │ │ + not the case, an invalid_size error is sent. │ │ │ │ │ + │ │ │ │ │ + The x and y arguments specify the location of the new pending │ │ │ │ │ + buffer's upper left corner, relative to the current buffer's │ │ │ │ │ + upper left corner, in surface-local coordinates. In other words, │ │ │ │ │ + the x and y, combined with the new surface size define in which │ │ │ │ │ + directions the surface's size changes. Setting anything other │ │ │ │ │ + than 0 as x and y arguments is discouraged, and should instead │ │ │ │ │ + be replaced with using the separate "WlSurface.offset()" │ │ │ │ │ + request. │ │ │ │ │ + │ │ │ │ │ + When the bound "WlSurface" version is 5 or higher, passing any │ │ │ │ │ + non-zero x or y is a protocol violation, and will result in an │ │ │ │ │ + 'invalid_offset' error being raised. The x and y arguments are │ │ │ │ │ + ignored and do not change the pending state. To achieve │ │ │ │ │ + equivalent semantics, use "WlSurface.offset()". │ │ │ │ │ + │ │ │ │ │ + Surface contents are double-buffered state, see │ │ │ │ │ + "WlSurface.commit()". │ │ │ │ │ + │ │ │ │ │ + The initial surface contents are void; there is no content. │ │ │ │ │ + "WlSurface.attach()" assigns the given "WlBuffer" as the pending │ │ │ │ │ + "WlBuffer". "WlSurface.commit()" makes the pending "WlBuffer" │ │ │ │ │ + the new surface contents, and the size of the surface becomes │ │ │ │ │ + the size calculated from the "WlBuffer", as described above. │ │ │ │ │ + After commit, there is no pending buffer until the next attach. │ │ │ │ │ + │ │ │ │ │ + Committing a pending "WlBuffer" allows the compositor to read │ │ │ │ │ + the pixels in the "WlBuffer". The compositor may access the │ │ │ │ │ + pixels at any time after the "WlSurface.commit()" request. When │ │ │ │ │ + the compositor will not access the pixels anymore, it will send │ │ │ │ │ + the "WlBuffer.release()" event. Only after receiving │ │ │ │ │ + "WlBuffer.release()", the client may reuse the "WlBuffer". A │ │ │ │ │ + "WlBuffer" that has been attached and then replaced by another │ │ │ │ │ + attach instead of committed will not receive a release event, │ │ │ │ │ + and is not used by the compositor. │ │ │ │ │ + │ │ │ │ │ + If a pending "WlBuffer" has been committed to more than one │ │ │ │ │ + "WlSurface", the delivery of "WlBuffer.release()" events becomes │ │ │ │ │ + undefined. A well behaved client should not rely on │ │ │ │ │ + "WlBuffer.release()" events in this case. Alternatively, a │ │ │ │ │ + client could create multiple "WlBuffer" objects from the same │ │ │ │ │ + backing storage or use wp_linux_buffer_release. │ │ │ │ │ + │ │ │ │ │ + Destroying the "WlBuffer" after "WlBuffer.release()" does not │ │ │ │ │ + change the surface contents. Destroying the "WlBuffer" before │ │ │ │ │ + "WlBuffer.release()" is allowed as long as the underlying buffer │ │ │ │ │ + storage isn't re-used (this can happen e.g. on client process │ │ │ │ │ + termination). However, if the client destroys the "WlBuffer" │ │ │ │ │ + before receiving the "WlBuffer.release()" event and mutates the │ │ │ │ │ + underlying buffer storage, the surface contents become undefined │ │ │ │ │ + immediately. │ │ │ │ │ + │ │ │ │ │ + If "WlSurface.attach()" is sent with a NULL "WlBuffer", the │ │ │ │ │ + following "WlSurface.commit()" will remove the surface content. │ │ │ │ │ + │ │ │ │ │ + If a pending "WlBuffer" has been destroyed, the result is not │ │ │ │ │ + specified. Many compositors are known to remove the surface │ │ │ │ │ + content on the following "WlSurface.commit()", but this │ │ │ │ │ + behaviour is not universal. Clients seeking to maximise │ │ │ │ │ + compatibility should not destroy pending buffers and should │ │ │ │ │ + ensure that they explicitly remove content from surfaces, even │ │ │ │ │ + after destroying buffers. │ │ │ │ │ + │ │ │ │ │ + Parameters: │ │ │ │ │ + * **buffer** ("WlBuffer" or *None*) -- buffer of surface │ │ │ │ │ + contents │ │ │ │ │ + │ │ │ │ │ + * **x** (*ArgumentType.Int*) -- surface-local x coordinate │ │ │ │ │ + │ │ │ │ │ + * **y** (*ArgumentType.Int*) -- surface-local y coordinate │ │ │ │ │ + │ │ │ │ │ + damage(x: 'int', y: 'int', width: 'int', height: 'int') -> 'None' │ │ │ │ │ + │ │ │ │ │ -[ Request -- opcode 2 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Destroy data offer │ │ │ │ │ + Mark part of the surface damaged │ │ │ │ │ │ │ │ │ │ - Destroy the data offer. │ │ │ │ │ + This request is used to describe the regions where the pending │ │ │ │ │ + buffer is different from the current surface contents, and where │ │ │ │ │ + the surface therefore needs to be repainted. The compositor │ │ │ │ │ + ignores the parts of the damage that fall outside of the │ │ │ │ │ + surface. │ │ │ │ │ │ │ │ │ │ - finish() -> 'None' │ │ │ │ │ + Damage is double-buffered state, see "WlSurface.commit()". │ │ │ │ │ + │ │ │ │ │ + The damage rectangle is specified in surface-local coordinates, │ │ │ │ │ + where x and y specify the upper left corner of the damage │ │ │ │ │ + rectangle. │ │ │ │ │ + │ │ │ │ │ + The initial value for pending damage is empty: no damage. │ │ │ │ │ + "WlSurface.damage()" adds pending damage: the new pending damage │ │ │ │ │ + is the union of old pending damage and the given rectangle. │ │ │ │ │ + │ │ │ │ │ + "WlSurface.commit()" assigns pending damage as the current │ │ │ │ │ + damage, and clears pending damage. The server will clear the │ │ │ │ │ + current damage as it repaints the surface. │ │ │ │ │ + │ │ │ │ │ + Note! New clients should not use this request. Instead damage │ │ │ │ │ + can be posted with "WlSurface.damage_buffer()" which uses buffer │ │ │ │ │ + coordinates instead of surface coordinates. │ │ │ │ │ + │ │ │ │ │ + Parameters: │ │ │ │ │ + * **x** (*ArgumentType.Int*) -- surface-local x coordinate │ │ │ │ │ + │ │ │ │ │ + * **y** (*ArgumentType.Int*) -- surface-local y coordinate │ │ │ │ │ + │ │ │ │ │ + * **width** (*ArgumentType.Int*) -- width of damage rectangle │ │ │ │ │ + │ │ │ │ │ + * **height** (*ArgumentType.Int*) -- height of damage │ │ │ │ │ + rectangle │ │ │ │ │ + │ │ │ │ │ + frame() -> 'Proxy[WlCallback]' │ │ │ │ │ │ │ │ │ │ -[ Request -- opcode 3 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - The offer will no longer be used │ │ │ │ │ + Request a frame throttling hint │ │ │ │ │ │ │ │ │ │ - Notifies the compositor that the drag destination successfully │ │ │ │ │ - finished the drag-and-drop operation. │ │ │ │ │ + Request a notification when it is a good time to start drawing a │ │ │ │ │ + new frame, by creating a frame callback. This is useful for │ │ │ │ │ + throttling redrawing operations, and driving animations. │ │ │ │ │ │ │ │ │ │ - Upon receiving this request, the compositor will emit │ │ │ │ │ - "WlDataSource.dnd_finished()" on the drag source client. │ │ │ │ │ + When a client is animating on a "WlSurface", it can use the │ │ │ │ │ + 'frame' request to get notified when it is a good time to draw │ │ │ │ │ + and commit the next frame of animation. If the client commits an │ │ │ │ │ + update earlier than that, it is likely that some updates will │ │ │ │ │ + not make it to the display, and the client is wasting resources │ │ │ │ │ + by drawing too often. │ │ │ │ │ │ │ │ │ │ - It is a client error to perform other requests than │ │ │ │ │ - "WlDataOffer.destroy()" after this one. It is also an error to │ │ │ │ │ - perform this request after a NULL mime type has been set in │ │ │ │ │ - "WlDataOffer.accept()" or no action was received through │ │ │ │ │ - "WlDataOffer.action()". │ │ │ │ │ + The frame request will take effect on the next │ │ │ │ │ + "WlSurface.commit()". The notification will only be posted for │ │ │ │ │ + one frame unless requested again. For a "WlSurface", the │ │ │ │ │ + notifications are posted in the order the frame requests were │ │ │ │ │ + committed. │ │ │ │ │ │ │ │ │ │ - If "WlDataOffer.finish()" request is received for a non drag and │ │ │ │ │ - drop operation, the invalid_finish protocol error is raised. │ │ │ │ │ + The server must send the notifications so that a client will not │ │ │ │ │ + send excessive updates, while still allowing the highest │ │ │ │ │ + possible update rate for clients that wait for the reply before │ │ │ │ │ + drawing again. The server should give some time for the client │ │ │ │ │ + to draw and commit after sending the frame callback events to │ │ │ │ │ + let it hit the next output refresh. │ │ │ │ │ │ │ │ │ │ - set_actions(dnd_actions: 'int', preferred_action: 'int') -> 'None' │ │ │ │ │ + A server should avoid signaling the frame callbacks if the │ │ │ │ │ + surface is not visible in any way, e.g. the surface is off- │ │ │ │ │ + screen, or completely obscured by other opaque surfaces. │ │ │ │ │ + │ │ │ │ │ + The object returned by this request will be destroyed by the │ │ │ │ │ + compositor after the callback is fired and as such the client │ │ │ │ │ + must not attempt to use it after that point. │ │ │ │ │ + │ │ │ │ │ + The callback_data passed in the callback is the current time, in │ │ │ │ │ + milliseconds, with an undefined base. │ │ │ │ │ + │ │ │ │ │ + Returns: │ │ │ │ │ + "WlCallback" -- callback object for the frame request │ │ │ │ │ + │ │ │ │ │ + set_opaque_region(region: 'WlRegion | None') -> 'None' │ │ │ │ │ │ │ │ │ │ -[ Request -- opcode 4 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Set the available/preferred drag-and-drop actions │ │ │ │ │ + Set opaque region │ │ │ │ │ │ │ │ │ │ - Sets the actions that the destination side client supports for │ │ │ │ │ - this operation. This request may trigger the emission of │ │ │ │ │ - "WlDataSource.action()" and "WlDataOffer.action()" events if the │ │ │ │ │ - compositor needs to change the selected action. │ │ │ │ │ + This request sets the region of the surface that contains opaque │ │ │ │ │ + content. │ │ │ │ │ │ │ │ │ │ - This request can be called multiple times throughout the drag- │ │ │ │ │ - and-drop operation, typically in response to │ │ │ │ │ - "WlDataDevice.enter()" or "WlDataDevice.motion()" events. │ │ │ │ │ + The opaque region is an optimization hint for the compositor │ │ │ │ │ + that lets it optimize the redrawing of content behind opaque │ │ │ │ │ + regions. Setting an opaque region is not required for correct │ │ │ │ │ + behaviour, but marking transparent content as opaque will result │ │ │ │ │ + in repaint artifacts. │ │ │ │ │ │ │ │ │ │ - This request determines the final result of the drag-and-drop │ │ │ │ │ - operation. If the end result is that no action is accepted, the │ │ │ │ │ - drag source will receive "WlDataSource.cancelled()". │ │ │ │ │ + The opaque region is specified in surface-local coordinates. │ │ │ │ │ │ │ │ │ │ - The dnd_actions argument must contain only values expressed in │ │ │ │ │ - the "WlDataDeviceManager.dnd_actions()" enum, and the │ │ │ │ │ - preferred_action argument must only contain one of those values │ │ │ │ │ - set, otherwise it will result in a protocol error. │ │ │ │ │ + The compositor ignores the parts of the opaque region that fall │ │ │ │ │ + outside of the surface. │ │ │ │ │ │ │ │ │ │ - While managing an "ask" action, the destination drag-and-drop │ │ │ │ │ - client may perform further "WlDataOffer.receive()" requests, and │ │ │ │ │ - is expected to perform one last "WlDataOffer.set_actions()" │ │ │ │ │ - request with a preferred action other than "ask" (and optionally │ │ │ │ │ - "WlDataOffer.accept()") before requesting │ │ │ │ │ - "WlDataOffer.finish()", in order to convey the action selected │ │ │ │ │ - by the user. If the preferred action is not in the │ │ │ │ │ - "WlDataOffer.source_actions()" mask, an error will be raised. │ │ │ │ │ + Opaque region is double-buffered state, see │ │ │ │ │ + "WlSurface.commit()". │ │ │ │ │ │ │ │ │ │ - If the "ask" action is dismissed (e.g. user cancellation), the │ │ │ │ │ - client is expected to perform "WlDataOffer.destroy()" right │ │ │ │ │ - away. │ │ │ │ │ + "WlSurface.set_opaque_region()" changes the pending opaque │ │ │ │ │ + region. "WlSurface.commit()" copies the pending region to the │ │ │ │ │ + current region. Otherwise, the pending and current regions are │ │ │ │ │ + never changed. │ │ │ │ │ │ │ │ │ │ - This request can only be made on drag-and-drop offers, a │ │ │ │ │ - protocol error will be raised otherwise. │ │ │ │ │ + The initial value for an opaque region is empty. Setting the │ │ │ │ │ + pending opaque region has copy semantics, and the "WlRegion" │ │ │ │ │ + object can be destroyed immediately. A NULL "WlRegion" causes │ │ │ │ │ + the pending opaque region to be set to empty. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - * **dnd_actions** (*ArgumentType.Uint*) -- actions supported │ │ │ │ │ - by the destination client │ │ │ │ │ + **region** ("WlRegion" or *None*) -- opaque region of the │ │ │ │ │ + surface │ │ │ │ │ │ │ │ │ │ - * **preferred_action** (*ArgumentType.Uint*) -- action │ │ │ │ │ - preferred by the destination client │ │ │ │ │ + set_input_region(region: 'WlRegion | None') -> 'None' │ │ │ │ │ │ │ │ │ │ - offer(mime_type: 'str') -> 'None' │ │ │ │ │ + -[ Request -- opcode 5 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ + Set input region │ │ │ │ │ │ │ │ │ │ - Advertise offered mime type │ │ │ │ │ + This request sets the region of the surface that can receive │ │ │ │ │ + pointer and touch events. │ │ │ │ │ │ │ │ │ │ - Sent immediately after creating the "WlDataOffer" object. One │ │ │ │ │ - event per offered mime type. │ │ │ │ │ + Input events happening outside of this region will try the next │ │ │ │ │ + surface in the server surface stack. The compositor ignores the │ │ │ │ │ + parts of the input region that fall outside of the surface. │ │ │ │ │ + │ │ │ │ │ + The input region is specified in surface-local coordinates. │ │ │ │ │ + │ │ │ │ │ + Input region is double-buffered state, see "WlSurface.commit()". │ │ │ │ │ + │ │ │ │ │ + "WlSurface.set_input_region()" changes the pending input region. │ │ │ │ │ + "WlSurface.commit()" copies the pending region to the current │ │ │ │ │ + region. Otherwise the pending and current regions are never │ │ │ │ │ + changed, except cursor and icon surfaces are special cases, see │ │ │ │ │ + "WlPointer.set_cursor()" and "WlDataDevice.start_drag()". │ │ │ │ │ + │ │ │ │ │ + The initial value for an input region is infinite. That means │ │ │ │ │ + the whole surface will accept input. Setting the pending input │ │ │ │ │ + region has copy semantics, and the "WlRegion" object can be │ │ │ │ │ + destroyed immediately. A NULL "WlRegion" causes the input region │ │ │ │ │ + to be set to infinite. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - **mime_type** (*ArgumentType.String*) -- offered mime type │ │ │ │ │ + **region** ("WlRegion" or *None*) -- input region of the │ │ │ │ │ + surface │ │ │ │ │ │ │ │ │ │ - source_actions(source_actions: 'int') -> 'None' │ │ │ │ │ + commit() -> 'None' │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 1 (attached to "Proxy" instance) ]- │ │ │ │ │ + -[ Request -- opcode 6 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Notify the source-side available actions │ │ │ │ │ + Commit pending surface state │ │ │ │ │ │ │ │ │ │ - This event indicates the actions offered by the data source. It │ │ │ │ │ - will be sent immediately after creating the "WlDataOffer" │ │ │ │ │ - object, or anytime the source side changes its offered actions │ │ │ │ │ - through "WlDataSource.set_actions()". │ │ │ │ │ + Surface state (input, opaque, and damage regions, attached │ │ │ │ │ + buffers, etc.) is double-buffered. Protocol requests modify the │ │ │ │ │ + pending state, as opposed to the active state in use by the │ │ │ │ │ + compositor. │ │ │ │ │ │ │ │ │ │ - Parameters: │ │ │ │ │ - **source_actions** (*ArgumentType.Uint*) -- actions offered │ │ │ │ │ - by the data source │ │ │ │ │ + A commit request atomically creates a content update from the │ │ │ │ │ + pending state, even if the pending state has not been touched. │ │ │ │ │ + The content update is placed in a queue until it becomes active. │ │ │ │ │ + After commit, the new pending state is as documented for each │ │ │ │ │ + related request. │ │ │ │ │ │ │ │ │ │ - action(dnd_action: 'int') -> 'None' │ │ │ │ │ + When the content update is applied, the "WlBuffer" is applied │ │ │ │ │ + before all other state. This means that all coordinates in │ │ │ │ │ + double-buffered state are relative to the newly attached │ │ │ │ │ + wl_buffers, except for "WlSurface.attach()" itself. If there is │ │ │ │ │ + no newly attached "WlBuffer", the coordinates are relative to │ │ │ │ │ + the previous content update. │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 2 (attached to "Proxy" instance) ]- │ │ │ │ │ + All requests that need a commit to become effective are │ │ │ │ │ + documented to affect double-buffered state. │ │ │ │ │ │ │ │ │ │ - Notify the selected action │ │ │ │ │ + Other interfaces may add further double-buffered surface state. │ │ │ │ │ │ │ │ │ │ - This event indicates the action selected by the compositor after │ │ │ │ │ - matching the source/destination side actions. Only one action │ │ │ │ │ - (or none) will be offered here. │ │ │ │ │ + set_buffer_transform(transform: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - This event can be emitted multiple times during the drag-and- │ │ │ │ │ - drop operation in response to destination side action changes │ │ │ │ │ - through "WlDataOffer.set_actions()". │ │ │ │ │ + -[ Request -- opcode 7 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - This event will no longer be emitted after "WlDataDevice.drop()" │ │ │ │ │ - happened on the drag- and-drop destination, the client must │ │ │ │ │ - honor the last action received, or the last preferred one set │ │ │ │ │ - through "WlDataOffer.set_actions()" when handling an "ask" │ │ │ │ │ - action. │ │ │ │ │ + Sets the buffer transformation │ │ │ │ │ │ │ │ │ │ - Compositors may also change the selected action on the fly, │ │ │ │ │ - mainly in response to keyboard modifier changes during the drag- │ │ │ │ │ - and-drop operation. │ │ │ │ │ + This request sets the transformation that the client has already │ │ │ │ │ + applied to the content of the buffer. The accepted values for │ │ │ │ │ + the transform parameter are the values for │ │ │ │ │ + "WlOutput.transform()". │ │ │ │ │ │ │ │ │ │ - The most recent action received is always the valid one. Prior │ │ │ │ │ - to receiving "WlDataDevice.drop()", the chosen action may change │ │ │ │ │ - (e.g. due to keyboard modifiers being pressed). At the time of │ │ │ │ │ - receiving "WlDataDevice.drop()" the drag-and-drop destination │ │ │ │ │ - must honor the last action received. │ │ │ │ │ + The compositor applies the inverse of this transformation │ │ │ │ │ + whenever it uses the buffer contents. │ │ │ │ │ │ │ │ │ │ - Action changes may still happen after "WlDataDevice.drop()", │ │ │ │ │ - especially on "ask" actions, where the drag-and-drop destination │ │ │ │ │ - may choose another action afterwards. Action changes happening │ │ │ │ │ - at this stage are always the result of inter-client negotiation, │ │ │ │ │ - the compositor shall no longer be able to induce a different │ │ │ │ │ - action. │ │ │ │ │ + Buffer transform is double-buffered state, see │ │ │ │ │ + "WlSurface.commit()". │ │ │ │ │ │ │ │ │ │ - Upon "ask" actions, it is expected that the drag-and-drop │ │ │ │ │ - destination may potentially choose a different action and/or │ │ │ │ │ - mime type, based on "WlDataOffer.source_actions()" and finally │ │ │ │ │ - chosen by the user (e.g. popping up a menu with the available │ │ │ │ │ - options). The final "WlDataOffer.set_actions()" and │ │ │ │ │ - "WlDataOffer.accept()" requests must happen before the call to │ │ │ │ │ - "WlDataOffer.finish()". │ │ │ │ │ + A newly created surface has its buffer transformation set to │ │ │ │ │ + normal. │ │ │ │ │ + │ │ │ │ │ + "WlSurface.set_buffer_transform()" changes the pending buffer │ │ │ │ │ + transformation. "WlSurface.commit()" copies the pending buffer │ │ │ │ │ + transformation to the current one. Otherwise, the pending and │ │ │ │ │ + current values are never changed. │ │ │ │ │ + │ │ │ │ │ + The purpose of this request is to allow clients to render │ │ │ │ │ + content according to the output transform, thus permitting the │ │ │ │ │ + compositor to use certain optimizations even if the display is │ │ │ │ │ + rotated. Using hardware overlays and scanning out a client │ │ │ │ │ + buffer for fullscreen surfaces are examples of such │ │ │ │ │ + optimizations. Those optimizations are highly dependent on the │ │ │ │ │ + compositor implementation, so the use of this request should be │ │ │ │ │ + considered on a case-by-case basis. │ │ │ │ │ + │ │ │ │ │ + Note that if the transform value includes 90 or 270 degree │ │ │ │ │ + rotation, the width of the buffer will become the surface height │ │ │ │ │ + and the height of the buffer will become the surface width. │ │ │ │ │ + │ │ │ │ │ + If transform is not one of the values from the │ │ │ │ │ + "WlOutput.transform()" enum the invalid_transform protocol error │ │ │ │ │ + is raised. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - **dnd_action** (*ArgumentType.Uint*) -- action selected by │ │ │ │ │ - the compositor │ │ │ │ │ + **transform** (*ArgumentType.Int*) -- transform for │ │ │ │ │ + interpreting buffer contents │ │ │ │ │ │ │ │ │ │ + set_buffer_scale(scale: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ -WlSeat │ │ │ │ │ -====== │ │ │ │ │ + -[ Request -- opcode 8 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ -class pywayland.protocol.wayland.WlSeat │ │ │ │ │ + Sets the buffer scaling factor │ │ │ │ │ │ │ │ │ │ - Group of input devices │ │ │ │ │ + This request sets an optional scaling factor on how the │ │ │ │ │ + compositor interprets the contents of the buffer attached to the │ │ │ │ │ + window. │ │ │ │ │ │ │ │ │ │ - A seat is a group of keyboards, pointer and touch devices. This │ │ │ │ │ - object is published as a global during start up, or when such a │ │ │ │ │ - device is hot plugged. A seat typically has a pointer and │ │ │ │ │ - maintains a keyboard focus and a pointer focus. │ │ │ │ │ + Buffer scale is double-buffered state, see "WlSurface.commit()". │ │ │ │ │ │ │ │ │ │ - get_pointer() -> 'Proxy[WlPointer]' │ │ │ │ │ + A newly created surface has its buffer scale set to 1. │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ + "WlSurface.set_buffer_scale()" changes the pending buffer scale. │ │ │ │ │ + "WlSurface.commit()" copies the pending buffer scale to the │ │ │ │ │ + current one. Otherwise, the pending and current values are never │ │ │ │ │ + changed. │ │ │ │ │ │ │ │ │ │ - Return pointer object │ │ │ │ │ + The purpose of this request is to allow clients to supply higher │ │ │ │ │ + resolution buffer data for use on high resolution outputs. It is │ │ │ │ │ + intended that you pick the same buffer scale as the scale of the │ │ │ │ │ + output that the surface is displayed on. This means the │ │ │ │ │ + compositor can avoid scaling when rendering the surface on that │ │ │ │ │ + output. │ │ │ │ │ │ │ │ │ │ - The ID provided will be initialized to the "WlPointer" interface │ │ │ │ │ - for this seat. │ │ │ │ │ + Note that if the scale is larger than 1, then you have to attach │ │ │ │ │ + a buffer that is larger (by a factor of scale in each dimension) │ │ │ │ │ + than the desired surface size. │ │ │ │ │ │ │ │ │ │ - This request only takes effect if the seat has the pointer │ │ │ │ │ - capability, or has had the pointer capability in the past. It is │ │ │ │ │ - a protocol violation to issue this request on a seat that has │ │ │ │ │ - never had the pointer capability. The missing_capability error │ │ │ │ │ - will be sent in this case. │ │ │ │ │ + If scale is not greater than 0 the invalid_scale protocol error │ │ │ │ │ + is raised. │ │ │ │ │ │ │ │ │ │ - Returns: │ │ │ │ │ - "WlPointer" -- seat pointer │ │ │ │ │ + Parameters: │ │ │ │ │ + **scale** (*ArgumentType.Int*) -- scale for interpreting │ │ │ │ │ + buffer contents │ │ │ │ │ │ │ │ │ │ - get_keyboard() -> 'Proxy[WlKeyboard]' │ │ │ │ │ + damage_buffer(x: 'int', y: 'int', width: 'int', height: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ + -[ Request -- opcode 9 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Return keyboard object │ │ │ │ │ + Mark part of the surface damaged using buffer coordinates │ │ │ │ │ │ │ │ │ │ - The ID provided will be initialized to the "WlKeyboard" │ │ │ │ │ - interface for this seat. │ │ │ │ │ + This request is used to describe the regions where the pending │ │ │ │ │ + buffer is different from the current surface contents, and where │ │ │ │ │ + the surface therefore needs to be repainted. The compositor │ │ │ │ │ + ignores the parts of the damage that fall outside of the │ │ │ │ │ + surface. │ │ │ │ │ │ │ │ │ │ - This request only takes effect if the seat has the keyboard │ │ │ │ │ - capability, or has had the keyboard capability in the past. It │ │ │ │ │ - is a protocol violation to issue this request on a seat that has │ │ │ │ │ - never had the keyboard capability. The missing_capability error │ │ │ │ │ - will be sent in this case. │ │ │ │ │ + Damage is double-buffered state, see "WlSurface.commit()". │ │ │ │ │ │ │ │ │ │ - Returns: │ │ │ │ │ - "WlKeyboard" -- seat keyboard │ │ │ │ │ + The damage rectangle is specified in buffer coordinates, where x │ │ │ │ │ + and y specify the upper left corner of the damage rectangle. │ │ │ │ │ │ │ │ │ │ - get_touch() -> 'Proxy[WlTouch]' │ │ │ │ │ + The initial value for pending damage is empty: no damage. │ │ │ │ │ + "WlSurface.damage_buffer()" adds pending damage: the new pending │ │ │ │ │ + damage is the union of old pending damage and the given │ │ │ │ │ + rectangle. │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 2 (attached to "Resource" instance) ]- │ │ │ │ │ + "WlSurface.commit()" assigns pending damage as the current │ │ │ │ │ + damage, and clears pending damage. The server will clear the │ │ │ │ │ + current damage as it repaints the surface. │ │ │ │ │ │ │ │ │ │ - Return touch object │ │ │ │ │ + This request differs from "WlSurface.damage()" in only one way - │ │ │ │ │ + it takes damage in buffer coordinates instead of surface-local │ │ │ │ │ + coordinates. While this generally is more intuitive than surface │ │ │ │ │ + coordinates, it is especially desirable when using wp_viewport │ │ │ │ │ + or when a drawing library (like EGL) is unaware of buffer scale │ │ │ │ │ + and buffer transform. │ │ │ │ │ │ │ │ │ │ - The ID provided will be initialized to the "WlTouch" interface │ │ │ │ │ - for this seat. │ │ │ │ │ + Note: Because buffer transformation changes and damage requests │ │ │ │ │ + may be interleaved in the protocol stream, it is impossible to │ │ │ │ │ + determine the actual mapping between surface and buffer damage │ │ │ │ │ + until "WlSurface.commit()" time. Therefore, compositors wishing │ │ │ │ │ + to take both kinds of damage into account will have to │ │ │ │ │ + accumulate damage from the two requests separately and only │ │ │ │ │ + transform from one to the other after receiving the │ │ │ │ │ + "WlSurface.commit()". │ │ │ │ │ │ │ │ │ │ - This request only takes effect if the seat has the touch │ │ │ │ │ - capability, or has had the touch capability in the past. It is a │ │ │ │ │ - protocol violation to issue this request on a seat that has │ │ │ │ │ - never had the touch capability. The missing_capability error │ │ │ │ │ - will be sent in this case. │ │ │ │ │ + Parameters: │ │ │ │ │ + * **x** (*ArgumentType.Int*) -- buffer-local x coordinate │ │ │ │ │ │ │ │ │ │ - Returns: │ │ │ │ │ - "WlTouch" -- seat touch interface │ │ │ │ │ + * **y** (*ArgumentType.Int*) -- buffer-local y coordinate │ │ │ │ │ │ │ │ │ │ - release() -> 'None' │ │ │ │ │ + * **width** (*ArgumentType.Int*) -- width of damage rectangle │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 3 (attached to "Resource" instance) ]- │ │ │ │ │ + * **height** (*ArgumentType.Int*) -- height of damage │ │ │ │ │ + rectangle │ │ │ │ │ │ │ │ │ │ - Release the seat object │ │ │ │ │ + offset(x: 'int', y: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - Using this request a client can tell the server that it is not │ │ │ │ │ - going to use the seat object anymore. │ │ │ │ │ + -[ Request -- opcode 10 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - capabilities(capabilities: 'int') -> 'None' │ │ │ │ │ + Set the surface contents offset │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ + The x and y arguments specify the location of the new pending │ │ │ │ │ + buffer's upper left corner, relative to the current buffer's │ │ │ │ │ + upper left corner, in surface-local coordinates. In other words, │ │ │ │ │ + the x and y, combined with the new surface size define in which │ │ │ │ │ + directions the surface's size changes. │ │ │ │ │ │ │ │ │ │ - Seat capabilities changed │ │ │ │ │ + Surface location offset is double-buffered state, see │ │ │ │ │ + "WlSurface.commit()". │ │ │ │ │ │ │ │ │ │ - This is emitted whenever a seat gains or loses the pointer, │ │ │ │ │ - keyboard or touch capabilities. The argument is a capability │ │ │ │ │ - enum containing the complete set of capabilities this seat has. │ │ │ │ │ + This request is semantically equivalent to and the replaces the │ │ │ │ │ + x and y arguments in the "WlSurface.attach()" request in │ │ │ │ │ + "WlSurface" versions prior to 5. See "WlSurface.attach()" for │ │ │ │ │ + details. │ │ │ │ │ │ │ │ │ │ - When the pointer capability is added, a client may create a │ │ │ │ │ - "WlPointer" object using the "WlSeat.get_pointer()" request. │ │ │ │ │ - This object will receive pointer events until the capability is │ │ │ │ │ - removed in the future. │ │ │ │ │ + Parameters: │ │ │ │ │ + * **x** (*ArgumentType.Int*) -- surface-local x coordinate │ │ │ │ │ │ │ │ │ │ - When the pointer capability is removed, a client should destroy │ │ │ │ │ - the "WlPointer" objects associated with the seat where the │ │ │ │ │ - capability was removed, using the "WlPointer.release()" request. │ │ │ │ │ - No further pointer events will be received on these objects. │ │ │ │ │ + * **y** (*ArgumentType.Int*) -- surface-local y coordinate │ │ │ │ │ │ │ │ │ │ - In some compositors, if a seat regains the pointer capability │ │ │ │ │ - and a client has a previously obtained "WlPointer" object of │ │ │ │ │ - version 4 or less, that object may start sending pointer events │ │ │ │ │ - again. This behavior is considered a misinterpretation of the │ │ │ │ │ - intended behavior and must not be relied upon by the client. │ │ │ │ │ - "WlPointer" objects of version 5 or later must not send events │ │ │ │ │ - if created before the most recent event notifying the client of │ │ │ │ │ - an added pointer capability. │ │ │ │ │ + enter(output: 'WlOutput') -> 'None' │ │ │ │ │ │ │ │ │ │ - The above behavior also applies to "WlKeyboard" and "WlTouch" │ │ │ │ │ - with the keyboard and touch capabilities, respectively. │ │ │ │ │ + -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Surface enters an output │ │ │ │ │ + │ │ │ │ │ + This is emitted whenever a surface's creation, movement, or │ │ │ │ │ + resizing results in some part of it being within the scanout │ │ │ │ │ + region of an output. │ │ │ │ │ + │ │ │ │ │ + Note that a surface may be overlapping with zero or more │ │ │ │ │ + outputs. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - **capabilities** (*ArgumentType.Uint*) -- capabilities of the │ │ │ │ │ - seat │ │ │ │ │ + **output** ("WlOutput") -- output entered by the surface │ │ │ │ │ │ │ │ │ │ - name(name: 'str') -> 'None' │ │ │ │ │ + leave(output: 'WlOutput') -> 'None' │ │ │ │ │ │ │ │ │ │ -[ Event -- opcode 1 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - Unique identifier for this seat │ │ │ │ │ + Surface leaves an output │ │ │ │ │ │ │ │ │ │ - In a multi-seat configuration the seat name can be used by │ │ │ │ │ - clients to help identify which physical devices the seat │ │ │ │ │ - represents. │ │ │ │ │ + This is emitted whenever a surface's creation, movement, or │ │ │ │ │ + resizing results in it no longer having any part of it within │ │ │ │ │ + the scanout region of an output. │ │ │ │ │ │ │ │ │ │ - The seat name is a UTF-8 string with no convention defined for │ │ │ │ │ - its contents. Each name is unique among all "WlSeat" globals. │ │ │ │ │ - The name is only guaranteed to be unique for the current │ │ │ │ │ - compositor instance. │ │ │ │ │ + Clients should not use the number of outputs the surface is on │ │ │ │ │ + for frame throttling purposes. The surface might be hidden even │ │ │ │ │ + if no leave event has been sent, and the compositor might expect │ │ │ │ │ + new surface content updates even if no enter event has been │ │ │ │ │ + sent. The frame event should be used instead. │ │ │ │ │ │ │ │ │ │ - The same seat names are used for all clients. Thus, the name can │ │ │ │ │ - be shared across processes to refer to a specific "WlSeat" │ │ │ │ │ - global. │ │ │ │ │ + Parameters: │ │ │ │ │ + **output** ("WlOutput") -- output left by the surface │ │ │ │ │ │ │ │ │ │ - The name event is sent after binding to the seat global. This │ │ │ │ │ - event is only sent once per seat object, and the name does not │ │ │ │ │ - change over the lifetime of the "WlSeat" global. │ │ │ │ │ + preferred_buffer_scale(factor: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - Compositors may re-use the same seat name if the "WlSeat" global │ │ │ │ │ - is destroyed and re-created later. │ │ │ │ │ + -[ Event -- opcode 2 (attached to "Proxy" instance) ]- │ │ │ │ │ + │ │ │ │ │ + Preferred buffer scale for the surface │ │ │ │ │ + │ │ │ │ │ + This event indicates the preferred buffer scale for this │ │ │ │ │ + surface. It is sent whenever the compositor's preference │ │ │ │ │ + changes. │ │ │ │ │ + │ │ │ │ │ + Before receiving this event the preferred buffer scale for this │ │ │ │ │ + surface is 1. │ │ │ │ │ + │ │ │ │ │ + It is intended that scaling aware clients use this event to │ │ │ │ │ + scale their content and use "WlSurface.set_buffer_scale()" to │ │ │ │ │ + indicate the scale they have rendered with. This allows clients │ │ │ │ │ + to supply a higher detail buffer. │ │ │ │ │ + │ │ │ │ │ + The compositor shall emit a scale value greater than 0. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - **name** (*ArgumentType.String*) -- seat identifier │ │ │ │ │ + **factor** (*ArgumentType.Int*) -- preferred scaling factor │ │ │ │ │ │ │ │ │ │ + preferred_buffer_transform(transform: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ -WlBuffer │ │ │ │ │ -======== │ │ │ │ │ + -[ Event -- opcode 3 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ -class pywayland.protocol.wayland.WlBuffer │ │ │ │ │ + Preferred buffer transform for the surface │ │ │ │ │ │ │ │ │ │ - Content for a "WlSurface" │ │ │ │ │ + This event indicates the preferred buffer transform for this │ │ │ │ │ + surface. It is sent whenever the compositor's preference │ │ │ │ │ + changes. │ │ │ │ │ │ │ │ │ │ - A buffer provides the content for a "WlSurface". Buffers are │ │ │ │ │ - created through factory interfaces such as "WlShm", │ │ │ │ │ - wp_linux_buffer_params (from the linux-dmabuf protocol extension) │ │ │ │ │ - or similar. It has a width and a height and can be attached to a │ │ │ │ │ - "WlSurface", but the mechanism by which a client provides and │ │ │ │ │ - updates the contents is defined by the buffer factory interface. │ │ │ │ │ + Before receiving this event the preferred buffer transform for │ │ │ │ │ + this surface is normal. │ │ │ │ │ │ │ │ │ │ - Color channels are assumed to be electrical rather than optical (in │ │ │ │ │ - other words, encoded with a transfer function) unless otherwise │ │ │ │ │ - specified. If the buffer uses a format that has an alpha channel, │ │ │ │ │ - the alpha channel is assumed to be premultiplied into the │ │ │ │ │ - electrical color channel values (after transfer function encoding) │ │ │ │ │ - unless otherwise specified. │ │ │ │ │ + Applying this transformation to the surface buffer contents and │ │ │ │ │ + using "WlSurface.set_buffer_transform()" might allow the │ │ │ │ │ + compositor to use the surface buffer more efficiently. │ │ │ │ │ │ │ │ │ │ - Note, because "WlBuffer" objects are created from multiple │ │ │ │ │ - independent factory interfaces, the "WlBuffer" interface is frozen │ │ │ │ │ - at version 1. │ │ │ │ │ + Parameters: │ │ │ │ │ + **transform** (*ArgumentType.Uint*) -- preferred transform │ │ │ │ │ + │ │ │ │ │ + │ │ │ │ │ +WlSubsurface │ │ │ │ │ +============ │ │ │ │ │ + │ │ │ │ │ +class pywayland.protocol.wayland.WlSubsurface │ │ │ │ │ + │ │ │ │ │ + Sub-surface interface to a "WlSurface" │ │ │ │ │ + │ │ │ │ │ + An additional interface to a "WlSurface" object, which has been │ │ │ │ │ + made a sub-surface. A sub-surface has one parent surface. A sub- │ │ │ │ │ + surface's size and position are not limited to that of the parent. │ │ │ │ │ + Particularly, a sub-surface is not automatically clipped to its │ │ │ │ │ + parent's area. │ │ │ │ │ + │ │ │ │ │ + A sub-surface becomes mapped, when a non-NULL "WlBuffer" is applied │ │ │ │ │ + and the parent surface is mapped. The order of which one happens │ │ │ │ │ + first is irrelevant. A sub-surface is hidden if the parent becomes │ │ │ │ │ + hidden, or if a NULL "WlBuffer" is applied. These rules apply │ │ │ │ │ + recursively through the tree of surfaces. │ │ │ │ │ + │ │ │ │ │ + The behaviour of a "WlSurface.commit()" request on a sub-surface │ │ │ │ │ + depends on the sub-surface's mode. The possible modes are │ │ │ │ │ + synchronized and desynchronized, see methods │ │ │ │ │ + "WlSubsurface.set_sync()" and "WlSubsurface.set_desync()". │ │ │ │ │ + Synchronized mode caches the "WlSurface" state to be applied when │ │ │ │ │ + the parent's state gets applied, and desynchronized mode applies │ │ │ │ │ + the pending "WlSurface" state directly. A sub- surface is initially │ │ │ │ │ + in the synchronized mode. │ │ │ │ │ + │ │ │ │ │ + Sub-surfaces also have another kind of state, which is managed by │ │ │ │ │ + "WlSubsurface" requests, as opposed to "WlSurface" requests. This │ │ │ │ │ + state includes the sub-surface position relative to the parent │ │ │ │ │ + surface ("WlSubsurface.set_position()"), and the stacking order of │ │ │ │ │ + the parent and its sub-surfaces ("WlSubsurface.place_above()" and │ │ │ │ │ + .place_below). This state is applied when the parent surface's │ │ │ │ │ + "WlSurface" state is applied, regardless of the sub-surface's mode. │ │ │ │ │ + As the exception, set_sync and set_desync are effective │ │ │ │ │ + immediately. │ │ │ │ │ + │ │ │ │ │ + The main surface can be thought to be always in desynchronized │ │ │ │ │ + mode, since it does not have a parent in the sub-surfaces sense. │ │ │ │ │ + │ │ │ │ │ + Even if a sub-surface is in desynchronized mode, it will behave as │ │ │ │ │ + in synchronized mode, if its parent surface behaves as in │ │ │ │ │ + synchronized mode. This rule is applied recursively throughout the │ │ │ │ │ + tree of surfaces. This means, that one can set a sub-surface into │ │ │ │ │ + synchronized mode, and then assume that all its child and grand- │ │ │ │ │ + child sub-surfaces are synchronized, too, without explicitly │ │ │ │ │ + setting them. │ │ │ │ │ + │ │ │ │ │ + Destroying a sub-surface takes effect immediately. If you need to │ │ │ │ │ + synchronize the removal of a sub-surface to the parent surface │ │ │ │ │ + update, unmap the sub-surface first by attaching a NULL "WlBuffer", │ │ │ │ │ + update parent, and then destroy the sub-surface. │ │ │ │ │ + │ │ │ │ │ + If the parent "WlSurface" object is destroyed, the sub-surface is │ │ │ │ │ + unmapped. │ │ │ │ │ + │ │ │ │ │ + A sub-surface never has the keyboard focus of any seat. │ │ │ │ │ + │ │ │ │ │ + The "WlSurface.offset()" request is ignored: clients must use │ │ │ │ │ + set_position instead to move the sub-surface. │ │ │ │ │ │ │ │ │ │ destroy() -> 'None' │ │ │ │ │ │ │ │ │ │ -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Destroy a buffer │ │ │ │ │ + Remove sub-surface interface │ │ │ │ │ │ │ │ │ │ - Destroy a buffer. If and how you need to release the backing │ │ │ │ │ - storage is defined by the buffer factory interface. │ │ │ │ │ + The sub-surface interface is removed from the "WlSurface" object │ │ │ │ │ + that was turned into a sub-surface with a │ │ │ │ │ + "WlSubcompositor.get_subsurface()" request. The wl_surface's │ │ │ │ │ + association to the parent is deleted. The "WlSurface" is │ │ │ │ │ + unmapped immediately. │ │ │ │ │ │ │ │ │ │ - For possible side-effects to a surface, see │ │ │ │ │ - "WlSurface.attach()". │ │ │ │ │ + set_position(x: 'int', y: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - release() -> 'None' │ │ │ │ │ + -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ + Reposition the sub-surface │ │ │ │ │ │ │ │ │ │ - Compositor releases buffer │ │ │ │ │ + This schedules a sub-surface position change. The sub-surface │ │ │ │ │ + will be moved so that its origin (top left corner pixel) will be │ │ │ │ │ + at the location x, y of the parent surface coordinate system. │ │ │ │ │ + The coordinates are not restricted to the parent surface area. │ │ │ │ │ + Negative values are allowed. │ │ │ │ │ │ │ │ │ │ - Sent when this "WlBuffer" is no longer used by the compositor. │ │ │ │ │ - The client is now free to reuse or destroy this buffer and its │ │ │ │ │ - backing storage. │ │ │ │ │ + The scheduled coordinates will take effect whenever the state of │ │ │ │ │ + the parent surface is applied. │ │ │ │ │ │ │ │ │ │ - If a client receives a release event before the frame callback │ │ │ │ │ - requested in the same "WlSurface.commit()" that attaches this │ │ │ │ │ - "WlBuffer" to a surface, then the client is immediately free to │ │ │ │ │ - reuse the buffer and its backing storage, and does not need a │ │ │ │ │ - second buffer for the next surface content update. Typically │ │ │ │ │ - this is possible, when the compositor maintains a copy of the │ │ │ │ │ - "WlSurface" contents, e.g. as a GL texture. This is an important │ │ │ │ │ - optimization for GL(ES) compositors with "WlShm" clients. │ │ │ │ │ + If more than one set_position request is invoked by the client │ │ │ │ │ + before the commit of the parent surface, the position of a new │ │ │ │ │ + request always replaces the scheduled position from any previous │ │ │ │ │ + request. │ │ │ │ │ │ │ │ │ │ + The initial position is 0, 0. │ │ │ │ │ │ │ │ │ │ -WlCompositor │ │ │ │ │ -============ │ │ │ │ │ + Parameters: │ │ │ │ │ + * **x** (*ArgumentType.Int*) -- x coordinate in the parent │ │ │ │ │ + surface │ │ │ │ │ │ │ │ │ │ -class pywayland.protocol.wayland.WlCompositor │ │ │ │ │ + * **y** (*ArgumentType.Int*) -- y coordinate in the parent │ │ │ │ │ + surface │ │ │ │ │ │ │ │ │ │ - The compositor singleton │ │ │ │ │ + place_above(sibling: 'WlSurface') -> 'None' │ │ │ │ │ │ │ │ │ │ - A compositor. This object is a singleton global. The compositor │ │ │ │ │ - is in charge of combining the contents of multiple surfaces into │ │ │ │ │ - one displayable output. │ │ │ │ │ + -[ Request -- opcode 2 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - create_surface() -> 'Proxy[WlSurface]' │ │ │ │ │ + Restack the sub-surface │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ + This sub-surface is taken from the stack, and put back just │ │ │ │ │ + above the reference surface, changing the z-order of the sub- │ │ │ │ │ + surfaces. The reference surface must be one of the sibling │ │ │ │ │ + surfaces, or the parent surface. Using any other surface, │ │ │ │ │ + including this sub-surface, will cause a protocol error. │ │ │ │ │ │ │ │ │ │ - Create new surface │ │ │ │ │ + The z-order is double-buffered. Requests are handled in order │ │ │ │ │ + and applied immediately to a pending state. The final pending │ │ │ │ │ + state is copied to the active state the next time the state of │ │ │ │ │ + the parent surface is applied. │ │ │ │ │ │ │ │ │ │ - Ask the compositor to create a new surface. │ │ │ │ │ + A new sub-surface is initially added as the top-most in the │ │ │ │ │ + stack of its siblings and parent. │ │ │ │ │ │ │ │ │ │ - Returns: │ │ │ │ │ - "WlSurface" -- the new surface │ │ │ │ │ + Parameters: │ │ │ │ │ + **sibling** ("WlSurface") -- the reference surface │ │ │ │ │ │ │ │ │ │ - create_region() -> 'Proxy[WlRegion]' │ │ │ │ │ + place_below(sibling: 'WlSurface') -> 'None' │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ + -[ Request -- opcode 3 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Create new region │ │ │ │ │ + Restack the sub-surface │ │ │ │ │ │ │ │ │ │ - Ask the compositor to create a new region. │ │ │ │ │ + The sub-surface is placed just below the reference surface. See │ │ │ │ │ + "WlSubsurface.place_above()". │ │ │ │ │ │ │ │ │ │ - Returns: │ │ │ │ │ - "WlRegion" -- the new region │ │ │ │ │ + Parameters: │ │ │ │ │ + **sibling** ("WlSurface") -- the reference surface │ │ │ │ │ │ │ │ │ │ + set_sync() -> 'None' │ │ │ │ │ │ │ │ │ │ -WlCallback │ │ │ │ │ -========== │ │ │ │ │ + -[ Request -- opcode 4 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ -class pywayland.protocol.wayland.WlCallback │ │ │ │ │ + Set sub-surface to synchronized mode │ │ │ │ │ │ │ │ │ │ - Callback object │ │ │ │ │ + Change the commit behaviour of the sub-surface to synchronized │ │ │ │ │ + mode, also described as the parent dependent mode. │ │ │ │ │ │ │ │ │ │ - Clients can handle the 'done' event to get notified when the │ │ │ │ │ - related request is done. │ │ │ │ │ + In synchronized mode, "WlSurface.commit()" on a sub-surface will │ │ │ │ │ + accumulate the committed state in a cache, but the state will │ │ │ │ │ + not be applied and hence will not change the compositor output. │ │ │ │ │ + The cached state is applied to the sub-surface immediately after │ │ │ │ │ + the parent surface's state is applied. This ensures atomic │ │ │ │ │ + updates of the parent and all its synchronized sub-surfaces. │ │ │ │ │ + Applying the cached state will invalidate the cache, so further │ │ │ │ │ + parent surface commits do not (re-)apply old state. │ │ │ │ │ │ │ │ │ │ - Note, because "WlCallback" objects are created from multiple │ │ │ │ │ - independent factory interfaces, the "WlCallback" interface is │ │ │ │ │ - frozen at version 1. │ │ │ │ │ + See "WlSubsurface" for the recursive effect of this mode. │ │ │ │ │ │ │ │ │ │ - done(callback_data: 'int') -> 'None' │ │ │ │ │ + set_desync() -> 'None' │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ + -[ Request -- opcode 5 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Done event │ │ │ │ │ + Set sub-surface to desynchronized mode │ │ │ │ │ │ │ │ │ │ - Notify the client when the related request is done. │ │ │ │ │ + Change the commit behaviour of the sub-surface to desynchronized │ │ │ │ │ + mode, also described as independent or freely running mode. │ │ │ │ │ │ │ │ │ │ - Parameters: │ │ │ │ │ - **callback_data** (*ArgumentType.Uint*) -- request-specific │ │ │ │ │ - data for the callback │ │ │ │ │ + In desynchronized mode, "WlSurface.commit()" on a sub-surface │ │ │ │ │ + will apply the pending state directly, without caching, as │ │ │ │ │ + happens normally with a "WlSurface". Calling │ │ │ │ │ + "WlSurface.commit()" on the parent surface has no effect on the │ │ │ │ │ + sub-surface's "WlSurface" state. This mode allows a sub-surface │ │ │ │ │ + to be updated on its own. │ │ │ │ │ + │ │ │ │ │ + If cached state exists when "WlSurface.commit()" is called in │ │ │ │ │ + desynchronized mode, the pending state is added to the cached │ │ │ │ │ + state, and applied as a whole. This invalidates the cache. │ │ │ │ │ + │ │ │ │ │ + Note: even if a sub-surface is set to desynchronized, a parent │ │ │ │ │ + sub- surface may override it to behave as synchronized. For │ │ │ │ │ + details, see "WlSubsurface". │ │ │ │ │ + │ │ │ │ │ + If a surface's parent surface behaves as desynchronized, then │ │ │ │ │ + the cached state is applied on set_desync. │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ WlKeyboard │ │ │ │ │ ========== │ │ │ │ │ │ │ │ │ │ class pywayland.protocol.wayland.WlKeyboard │ │ │ │ │ │ │ │ │ │ @@ -2915,380 +3245,153 @@ │ │ │ │ │ * **rate** (*ArgumentType.Int*) -- the rate of repeating keys │ │ │ │ │ in characters per second │ │ │ │ │ │ │ │ │ │ * **delay** (*ArgumentType.Int*) -- delay in milliseconds │ │ │ │ │ since key down until repeating starts │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ -WlOutput │ │ │ │ │ -======== │ │ │ │ │ +WlSeat │ │ │ │ │ +====== │ │ │ │ │ │ │ │ │ │ -class pywayland.protocol.wayland.WlOutput │ │ │ │ │ +class pywayland.protocol.wayland.WlSeat │ │ │ │ │ │ │ │ │ │ - Compositor output region │ │ │ │ │ + Group of input devices │ │ │ │ │ │ │ │ │ │ - An output describes part of the compositor geometry. The │ │ │ │ │ - compositor works in the 'compositor coordinate system' and an │ │ │ │ │ - output corresponds to a rectangular area in that space that is │ │ │ │ │ - actually visible. This typically corresponds to a monitor that │ │ │ │ │ - displays part of the compositor space. This object is published as │ │ │ │ │ - global during start up, or when a monitor is hotplugged. │ │ │ │ │ + A seat is a group of keyboards, pointer and touch devices. This │ │ │ │ │ + object is published as a global during start up, or when such a │ │ │ │ │ + device is hot plugged. A seat typically has a pointer and │ │ │ │ │ + maintains a keyboard focus and a pointer focus. │ │ │ │ │ │ │ │ │ │ - release() -> 'None' │ │ │ │ │ + get_pointer() -> 'Proxy[WlPointer]' │ │ │ │ │ │ │ │ │ │ -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Release the output object │ │ │ │ │ - │ │ │ │ │ - Using this request a client can tell the server that it is not │ │ │ │ │ - going to use the output object anymore. │ │ │ │ │ - │ │ │ │ │ - geometry(x: 'int', y: 'int', physical_width: 'int', physical_height: 'int', subpixel: 'int', make: 'str', model: 'str', transform: 'int') -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Properties of the output │ │ │ │ │ - │ │ │ │ │ - The geometry event describes geometric properties of the output. │ │ │ │ │ - The event is sent when binding to the output object and whenever │ │ │ │ │ - any of the properties change. │ │ │ │ │ - │ │ │ │ │ - The physical size can be set to zero if it doesn't make sense │ │ │ │ │ - for this output (e.g. for projectors or virtual outputs). │ │ │ │ │ - │ │ │ │ │ - The geometry event will be followed by a done event (starting │ │ │ │ │ - from version 2). │ │ │ │ │ - │ │ │ │ │ - Clients should use "WlSurface.preferred_buffer_transform()" │ │ │ │ │ - instead of the transform advertised by this event to find the │ │ │ │ │ - preferred buffer transform to use for a surface. │ │ │ │ │ - │ │ │ │ │ - Note: "WlOutput" only advertises partial information about the │ │ │ │ │ - output position and identification. Some compositors, for │ │ │ │ │ - instance those not implementing a desktop-style output layout or │ │ │ │ │ - those exposing virtual outputs, might fake this information. │ │ │ │ │ - Instead of using x and y, clients should use │ │ │ │ │ - xdg_output.logical_position. Instead of using make and model, │ │ │ │ │ - clients should use name and description. │ │ │ │ │ - │ │ │ │ │ - Parameters: │ │ │ │ │ - * **x** (*ArgumentType.Int*) -- x position within the global │ │ │ │ │ - compositor space │ │ │ │ │ - │ │ │ │ │ - * **y** (*ArgumentType.Int*) -- y position within the global │ │ │ │ │ - compositor space │ │ │ │ │ - │ │ │ │ │ - * **physical_width** (*ArgumentType.Int*) -- width in │ │ │ │ │ - millimeters of the output │ │ │ │ │ - │ │ │ │ │ - * **physical_height** (*ArgumentType.Int*) -- height in │ │ │ │ │ - millimeters of the output │ │ │ │ │ - │ │ │ │ │ - * **subpixel** (*ArgumentType.Int*) -- subpixel orientation │ │ │ │ │ - of the output │ │ │ │ │ - │ │ │ │ │ - * **make** (*ArgumentType.String*) -- textual description of │ │ │ │ │ - the manufacturer │ │ │ │ │ - │ │ │ │ │ - * **model** (*ArgumentType.String*) -- textual description of │ │ │ │ │ - the model │ │ │ │ │ + Return pointer object │ │ │ │ │ │ │ │ │ │ - * **transform** (*ArgumentType.Int*) -- additional │ │ │ │ │ - transformation applied to buffer contents during │ │ │ │ │ - presentation │ │ │ │ │ + The ID provided will be initialized to the "WlPointer" interface │ │ │ │ │ + for this seat. │ │ │ │ │ │ │ │ │ │ - mode(flags: 'int', width: 'int', height: 'int', refresh: 'int') -> 'None' │ │ │ │ │ + This request only takes effect if the seat has the pointer │ │ │ │ │ + capability, or has had the pointer capability in the past. It is │ │ │ │ │ + a protocol violation to issue this request on a seat that has │ │ │ │ │ + never had the pointer capability. The missing_capability error │ │ │ │ │ + will be sent in this case. │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 1 (attached to "Proxy" instance) ]- │ │ │ │ │ + Returns: │ │ │ │ │ + "WlPointer" -- seat pointer │ │ │ │ │ │ │ │ │ │ - Advertise available modes for the output │ │ │ │ │ + get_keyboard() -> 'Proxy[WlKeyboard]' │ │ │ │ │ │ │ │ │ │ - The mode event describes an available mode for the output. │ │ │ │ │ + -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - The event is sent when binding to the output object and there │ │ │ │ │ - will always be one mode, the current mode. The event is sent │ │ │ │ │ - again if an output changes mode, for the mode that is now │ │ │ │ │ - current. In other words, the current mode is always the last │ │ │ │ │ - mode that was received with the current flag set. │ │ │ │ │ + Return keyboard object │ │ │ │ │ │ │ │ │ │ - Non-current modes are deprecated. A compositor can decide to │ │ │ │ │ - only advertise the current mode and never send other modes. │ │ │ │ │ - Clients should not rely on non-current modes. │ │ │ │ │ + The ID provided will be initialized to the "WlKeyboard" │ │ │ │ │ + interface for this seat. │ │ │ │ │ │ │ │ │ │ - The size of a mode is given in physical hardware units of the │ │ │ │ │ - output device. This is not necessarily the same as the output │ │ │ │ │ - size in the global compositor space. For instance, the output │ │ │ │ │ - may be scaled, as described in "WlOutput.scale()", or │ │ │ │ │ - transformed, as described in "WlOutput.transform()". Clients │ │ │ │ │ - willing to retrieve the output size in the global compositor │ │ │ │ │ - space should use xdg_output.logical_size instead. │ │ │ │ │ + This request only takes effect if the seat has the keyboard │ │ │ │ │ + capability, or has had the keyboard capability in the past. It │ │ │ │ │ + is a protocol violation to issue this request on a seat that has │ │ │ │ │ + never had the keyboard capability. The missing_capability error │ │ │ │ │ + will be sent in this case. │ │ │ │ │ │ │ │ │ │ - The vertical refresh rate can be set to zero if it doesn't make │ │ │ │ │ - sense for this output (e.g. for virtual outputs). │ │ │ │ │ + Returns: │ │ │ │ │ + "WlKeyboard" -- seat keyboard │ │ │ │ │ │ │ │ │ │ - The mode event will be followed by a done event (starting from │ │ │ │ │ - version 2). │ │ │ │ │ + get_touch() -> 'Proxy[WlTouch]' │ │ │ │ │ │ │ │ │ │ - Clients should not use the refresh rate to schedule frames. │ │ │ │ │ - Instead, they should use the "WlSurface.frame()" event or the │ │ │ │ │ - presentation-time protocol. │ │ │ │ │ + -[ Request -- opcode 2 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Note: this information is not always meaningful for all outputs. │ │ │ │ │ - Some compositors, such as those exposing virtual outputs, might │ │ │ │ │ - fake the refresh rate or the size. │ │ │ │ │ + Return touch object │ │ │ │ │ │ │ │ │ │ - Parameters: │ │ │ │ │ - * **flags** (*ArgumentType.Uint*) -- bitfield of mode flags │ │ │ │ │ + The ID provided will be initialized to the "WlTouch" interface │ │ │ │ │ + for this seat. │ │ │ │ │ │ │ │ │ │ - * **width** (*ArgumentType.Int*) -- width of the mode in │ │ │ │ │ - hardware units │ │ │ │ │ + This request only takes effect if the seat has the touch │ │ │ │ │ + capability, or has had the touch capability in the past. It is a │ │ │ │ │ + protocol violation to issue this request on a seat that has │ │ │ │ │ + never had the touch capability. The missing_capability error │ │ │ │ │ + will be sent in this case. │ │ │ │ │ │ │ │ │ │ - * **height** (*ArgumentType.Int*) -- height of the mode in │ │ │ │ │ - hardware units │ │ │ │ │ + Returns: │ │ │ │ │ + "WlTouch" -- seat touch interface │ │ │ │ │ │ │ │ │ │ - * **refresh** (*ArgumentType.Int*) -- vertical refresh rate │ │ │ │ │ - in mHz │ │ │ │ │ + release() -> 'None' │ │ │ │ │ │ │ │ │ │ - done() -> 'None' │ │ │ │ │ + -[ Request -- opcode 3 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 2 (attached to "Proxy" instance) ]- │ │ │ │ │ + Release the seat object │ │ │ │ │ │ │ │ │ │ - Sent all information about output │ │ │ │ │ + Using this request a client can tell the server that it is not │ │ │ │ │ + going to use the seat object anymore. │ │ │ │ │ │ │ │ │ │ - This event is sent after all other properties have been sent │ │ │ │ │ - after binding to the output object and after any other property │ │ │ │ │ - changes done after that. This allows changes to the output │ │ │ │ │ - properties to be seen as atomic, even if they happen via │ │ │ │ │ - multiple events. │ │ │ │ │ + capabilities(capabilities: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - scale(factor: 'int') -> 'None' │ │ │ │ │ + -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 3 (attached to "Proxy" instance) ]- │ │ │ │ │ + Seat capabilities changed │ │ │ │ │ │ │ │ │ │ - Output scaling properties │ │ │ │ │ + This is emitted whenever a seat gains or loses the pointer, │ │ │ │ │ + keyboard or touch capabilities. The argument is a capability │ │ │ │ │ + enum containing the complete set of capabilities this seat has. │ │ │ │ │ │ │ │ │ │ - This event contains scaling geometry information that is not in │ │ │ │ │ - the geometry event. It may be sent after binding the output │ │ │ │ │ - object or if the output scale changes later. The compositor will │ │ │ │ │ - emit a non-zero, positive value for scale. If it is not sent, │ │ │ │ │ - the client should assume a scale of 1. │ │ │ │ │ + When the pointer capability is added, a client may create a │ │ │ │ │ + "WlPointer" object using the "WlSeat.get_pointer()" request. │ │ │ │ │ + This object will receive pointer events until the capability is │ │ │ │ │ + removed in the future. │ │ │ │ │ │ │ │ │ │ - A scale larger than 1 means that the compositor will │ │ │ │ │ - automatically scale surface buffers by this amount when │ │ │ │ │ - rendering. This is used for very high resolution displays where │ │ │ │ │ - applications rendering at the native resolution would be too │ │ │ │ │ - small to be legible. │ │ │ │ │ + When the pointer capability is removed, a client should destroy │ │ │ │ │ + the "WlPointer" objects associated with the seat where the │ │ │ │ │ + capability was removed, using the "WlPointer.release()" request. │ │ │ │ │ + No further pointer events will be received on these objects. │ │ │ │ │ │ │ │ │ │ - Clients should use "WlSurface.preferred_buffer_scale()" instead │ │ │ │ │ - of this event to find the preferred buffer scale to use for a │ │ │ │ │ - surface. │ │ │ │ │ + In some compositors, if a seat regains the pointer capability │ │ │ │ │ + and a client has a previously obtained "WlPointer" object of │ │ │ │ │ + version 4 or less, that object may start sending pointer events │ │ │ │ │ + again. This behavior is considered a misinterpretation of the │ │ │ │ │ + intended behavior and must not be relied upon by the client. │ │ │ │ │ + "WlPointer" objects of version 5 or later must not send events │ │ │ │ │ + if created before the most recent event notifying the client of │ │ │ │ │ + an added pointer capability. │ │ │ │ │ │ │ │ │ │ - The scale event will be followed by a done event. │ │ │ │ │ + The above behavior also applies to "WlKeyboard" and "WlTouch" │ │ │ │ │ + with the keyboard and touch capabilities, respectively. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - **factor** (*ArgumentType.Int*) -- scaling factor of output │ │ │ │ │ + **capabilities** (*ArgumentType.Uint*) -- capabilities of the │ │ │ │ │ + seat │ │ │ │ │ │ │ │ │ │ name(name: 'str') -> 'None' │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 4 (attached to "Proxy" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Name of this output │ │ │ │ │ - │ │ │ │ │ - Many compositors will assign user-friendly names to their │ │ │ │ │ - outputs, show them to the user, allow the user to refer to an │ │ │ │ │ - output, etc. The client may wish to know this name as well to │ │ │ │ │ - offer the user similar behaviors. │ │ │ │ │ - │ │ │ │ │ - The name is a UTF-8 string with no convention defined for its │ │ │ │ │ - contents. Each name is unique among all "WlOutput" globals. The │ │ │ │ │ - name is only guaranteed to be unique for the compositor │ │ │ │ │ - instance. │ │ │ │ │ - │ │ │ │ │ - The same output name is used for all clients for a given │ │ │ │ │ - "WlOutput" global. Thus, the name can be shared across processes │ │ │ │ │ - to refer to a specific "WlOutput" global. │ │ │ │ │ - │ │ │ │ │ - The name is not guaranteed to be persistent across sessions, │ │ │ │ │ - thus cannot be used to reliably identify an output in e.g. │ │ │ │ │ - configuration files. │ │ │ │ │ - │ │ │ │ │ - Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc. │ │ │ │ │ - However, do not assume that the name is a reflection of an │ │ │ │ │ - underlying DRM connector, X11 connection, etc. │ │ │ │ │ - │ │ │ │ │ - The name event is sent after binding the output object. This │ │ │ │ │ - event is only sent once per output object, and the name does not │ │ │ │ │ - change over the lifetime of the "WlOutput" global. │ │ │ │ │ - │ │ │ │ │ - Compositors may re-use the same output name if the "WlOutput" │ │ │ │ │ - global is destroyed and re-created later. Compositors should │ │ │ │ │ - avoid re- using the same name if possible. │ │ │ │ │ - │ │ │ │ │ - The name event will be followed by a done event. │ │ │ │ │ - │ │ │ │ │ - Parameters: │ │ │ │ │ - **name** (*ArgumentType.String*) -- output name │ │ │ │ │ - │ │ │ │ │ - description(description: 'str') -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Event -- opcode 5 (attached to "Proxy" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Human-readable description of this output │ │ │ │ │ - │ │ │ │ │ - Many compositors can produce human-readable descriptions of │ │ │ │ │ - their outputs. The client may wish to know this description as │ │ │ │ │ - well, e.g. for output selection purposes. │ │ │ │ │ - │ │ │ │ │ - The description is a UTF-8 string with no convention defined for │ │ │ │ │ - its contents. The description is not guaranteed to be unique │ │ │ │ │ - among all "WlOutput" globals. Examples might include 'Foocorp │ │ │ │ │ - 11" Display' or 'Virtual X11 output via :1'. │ │ │ │ │ - │ │ │ │ │ - The description event is sent after binding the output object │ │ │ │ │ - and whenever the description changes. The description is │ │ │ │ │ - optional, and may not be sent at all. │ │ │ │ │ - │ │ │ │ │ - The description event will be followed by a done event. │ │ │ │ │ - │ │ │ │ │ - Parameters: │ │ │ │ │ - **description** (*ArgumentType.String*) -- output description │ │ │ │ │ - │ │ │ │ │ - │ │ │ │ │ -WlRegistry │ │ │ │ │ -========== │ │ │ │ │ - │ │ │ │ │ -class pywayland.protocol.wayland.WlRegistry │ │ │ │ │ - │ │ │ │ │ - Global registry object │ │ │ │ │ - │ │ │ │ │ - The singleton global registry object. The server has a number of │ │ │ │ │ - global objects that are available to all clients. These objects │ │ │ │ │ - typically represent an actual object in the server (for example, an │ │ │ │ │ - input device) or they are singleton objects that provide extension │ │ │ │ │ - functionality. │ │ │ │ │ - │ │ │ │ │ - When a client creates a registry object, the registry object will │ │ │ │ │ - emit a global event for each global currently in the registry. │ │ │ │ │ - Globals come and go as a result of device or monitor hotplugs, │ │ │ │ │ - reconfiguration or other events, and the registry will send out │ │ │ │ │ - global and global_remove events to keep the client up to date with │ │ │ │ │ - the changes. To mark the end of the initial burst of events, the │ │ │ │ │ - client can use the "WlDisplay.sync()" request immediately after │ │ │ │ │ - calling "WlDisplay.get_registry()". │ │ │ │ │ - │ │ │ │ │ - A client can bind to a global object by using the bind request. │ │ │ │ │ - This creates a client-side handle that lets the object emit events │ │ │ │ │ - to the client and lets the client invoke requests on the object. │ │ │ │ │ - │ │ │ │ │ - bind(name: 'int', interface: 'type[T]', version: 'int') -> 'Proxy[T]' │ │ │ │ │ - │ │ │ │ │ - -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Bind an object to the display │ │ │ │ │ - │ │ │ │ │ - Binds a new, client-created object to the server using the │ │ │ │ │ - specified name as the identifier. │ │ │ │ │ - │ │ │ │ │ - Parameters: │ │ │ │ │ - * **name** (*ArgumentType.Uint*) -- unique numeric name of │ │ │ │ │ - the object │ │ │ │ │ - │ │ │ │ │ - * **interface** (*string*) -- Interface name │ │ │ │ │ - │ │ │ │ │ - * **version** (*int*) -- Interface version │ │ │ │ │ - │ │ │ │ │ - Returns: │ │ │ │ │ - "pywayland.client.proxy.Proxy" of specified Interface -- │ │ │ │ │ - bounded object │ │ │ │ │ - │ │ │ │ │ - global_(name: 'int', interface: 'str', version: 'int') -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Announce global object │ │ │ │ │ - │ │ │ │ │ - Notify the client of global objects. │ │ │ │ │ - │ │ │ │ │ - The event notifies the client that a global object with the │ │ │ │ │ - given name is now available, and it implements the given version │ │ │ │ │ - of the given interface. │ │ │ │ │ - │ │ │ │ │ - Parameters: │ │ │ │ │ - * **name** (*ArgumentType.Uint*) -- numeric name of the │ │ │ │ │ - global object │ │ │ │ │ - │ │ │ │ │ - * **interface** (*ArgumentType.String*) -- interface │ │ │ │ │ - implemented by the object │ │ │ │ │ - │ │ │ │ │ - * **version** (*ArgumentType.Uint*) -- interface version │ │ │ │ │ - │ │ │ │ │ - global_remove(name: 'int') -> 'None' │ │ │ │ │ - │ │ │ │ │ -[ Event -- opcode 1 (attached to "Proxy" instance) ]- │ │ │ │ │ │ │ │ │ │ - Announce removal of global object │ │ │ │ │ - │ │ │ │ │ - Notify the client of removed global objects. │ │ │ │ │ - │ │ │ │ │ - This event notifies the client that the global identified by │ │ │ │ │ - name is no longer available. If the client bound to the global │ │ │ │ │ - using the bind request, the client should now destroy that │ │ │ │ │ - object. │ │ │ │ │ - │ │ │ │ │ - The object remains valid and requests to the object will be │ │ │ │ │ - ignored until the client destroys it, to avoid races between the │ │ │ │ │ - global going away and a client sending a request to it. │ │ │ │ │ - │ │ │ │ │ - Parameters: │ │ │ │ │ - **name** (*ArgumentType.Uint*) -- numeric name of the global │ │ │ │ │ - object │ │ │ │ │ - │ │ │ │ │ - │ │ │ │ │ -WlDataDeviceManager │ │ │ │ │ -=================== │ │ │ │ │ - │ │ │ │ │ -class pywayland.protocol.wayland.WlDataDeviceManager │ │ │ │ │ - │ │ │ │ │ - Data transfer interface │ │ │ │ │ - │ │ │ │ │ - The "WlDataDeviceManager" is a singleton global object that │ │ │ │ │ - provides access to inter-client data transfer mechanisms such as │ │ │ │ │ - copy-and-paste and drag-and-drop. These mechanisms are tied to a │ │ │ │ │ - "WlSeat" and this interface lets a client get a "WlDataDevice" │ │ │ │ │ - corresponding to a "WlSeat". │ │ │ │ │ - │ │ │ │ │ - Depending on the version bound, the objects created from the bound │ │ │ │ │ - "WlDataDeviceManager" object will have different requirements for │ │ │ │ │ - functioning properly. See "WlDataSource.set_actions()", │ │ │ │ │ - "WlDataOffer.accept()" and "WlDataOffer.finish()" for details. │ │ │ │ │ - │ │ │ │ │ - create_data_source() -> 'Proxy[WlDataSource]' │ │ │ │ │ - │ │ │ │ │ - -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Create a new data source │ │ │ │ │ - │ │ │ │ │ - Create a new data source. │ │ │ │ │ + Unique identifier for this seat │ │ │ │ │ │ │ │ │ │ - Returns: │ │ │ │ │ - "WlDataSource" -- data source to create │ │ │ │ │ + In a multi-seat configuration the seat name can be used by │ │ │ │ │ + clients to help identify which physical devices the seat │ │ │ │ │ + represents. │ │ │ │ │ │ │ │ │ │ - get_data_device(seat: 'WlSeat') -> 'Proxy[WlDataDevice]' │ │ │ │ │ + The seat name is a UTF-8 string with no convention defined for │ │ │ │ │ + its contents. Each name is unique among all "WlSeat" globals. │ │ │ │ │ + The name is only guaranteed to be unique for the current │ │ │ │ │ + compositor instance. │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ + The same seat names are used for all clients. Thus, the name can │ │ │ │ │ + be shared across processes to refer to a specific "WlSeat" │ │ │ │ │ + global. │ │ │ │ │ │ │ │ │ │ - Create a new data device │ │ │ │ │ + The name event is sent after binding to the seat global. This │ │ │ │ │ + event is only sent once per seat object, and the name does not │ │ │ │ │ + change over the lifetime of the "WlSeat" global. │ │ │ │ │ │ │ │ │ │ - Create a new data device for a given seat. │ │ │ │ │ + Compositors may re-use the same seat name if the "WlSeat" global │ │ │ │ │ + is destroyed and re-created later. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - **seat** ("WlSeat") -- seat associated with the data device │ │ │ │ │ - │ │ │ │ │ - Returns: │ │ │ │ │ - "WlDataDevice" -- data device to create │ │ │ │ │ + **name** (*ArgumentType.String*) -- seat identifier │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ WlShell │ │ │ │ │ ======= │ │ │ │ │ │ │ │ │ │ class pywayland.protocol.wayland.WlShell │ │ │ │ │ │ │ │ │ │ @@ -3320,237 +3423,134 @@ │ │ │ │ │ **surface** ("WlSurface") -- surface to be given the shell │ │ │ │ │ surface role │ │ │ │ │ │ │ │ │ │ Returns: │ │ │ │ │ "WlShellSurface" -- shell surface to create │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ -WlShm │ │ │ │ │ -===== │ │ │ │ │ - │ │ │ │ │ -class pywayland.protocol.wayland.WlShm │ │ │ │ │ +WlRegion │ │ │ │ │ +======== │ │ │ │ │ │ │ │ │ │ - Shared memory support │ │ │ │ │ +class pywayland.protocol.wayland.WlRegion │ │ │ │ │ │ │ │ │ │ - A singleton global object that provides support for shared memory. │ │ │ │ │ + Region interface │ │ │ │ │ │ │ │ │ │ - Clients can create "WlShmPool" objects using the create_pool │ │ │ │ │ - request. │ │ │ │ │ + A region object describes an area. │ │ │ │ │ │ │ │ │ │ - On binding the "WlShm" object one or more format events are emitted │ │ │ │ │ - to inform clients about the valid pixel formats that can be used │ │ │ │ │ - for buffers. │ │ │ │ │ + Region objects are used to describe the opaque and input regions of │ │ │ │ │ + a surface. │ │ │ │ │ │ │ │ │ │ - create_pool(fd: 'int', size: 'int') -> 'Proxy[WlShmPool]' │ │ │ │ │ + destroy() -> 'None' │ │ │ │ │ │ │ │ │ │ -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Create a shm pool │ │ │ │ │ - │ │ │ │ │ - Create a new "WlShmPool" object. │ │ │ │ │ - │ │ │ │ │ - The pool can be used to create shared memory based buffer │ │ │ │ │ - objects. The server will mmap size bytes of the passed file │ │ │ │ │ - descriptor, to use as backing memory for the pool. │ │ │ │ │ - │ │ │ │ │ - Parameters: │ │ │ │ │ - * **fd** (*ArgumentType.FileDescriptor*) -- file descriptor │ │ │ │ │ - for the pool │ │ │ │ │ - │ │ │ │ │ - * **size** (*ArgumentType.Int*) -- pool size, in bytes │ │ │ │ │ + Destroy region │ │ │ │ │ │ │ │ │ │ - Returns: │ │ │ │ │ - "WlShmPool" -- pool to create │ │ │ │ │ + Destroy the region. This will invalidate the object ID. │ │ │ │ │ │ │ │ │ │ - release() -> 'None' │ │ │ │ │ + add(x: 'int', y: 'int', width: 'int', height: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Release the shm object │ │ │ │ │ - │ │ │ │ │ - Using this request a client can tell the server that it is not │ │ │ │ │ - going to use the shm object anymore. │ │ │ │ │ - │ │ │ │ │ - Objects created via this interface remain unaffected. │ │ │ │ │ - │ │ │ │ │ - format(format: 'int') -> 'None' │ │ │ │ │ - │ │ │ │ │ - -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Pixel format description │ │ │ │ │ + Add rectangle to region │ │ │ │ │ │ │ │ │ │ - Informs the client about a valid pixel format that can be used │ │ │ │ │ - for buffers. Known formats include argb8888 and xrgb8888. │ │ │ │ │ + Add the specified rectangle to the region. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - **format** (*ArgumentType.Uint*) -- buffer pixel format │ │ │ │ │ - │ │ │ │ │ - │ │ │ │ │ -WlDisplay │ │ │ │ │ -========= │ │ │ │ │ - │ │ │ │ │ -class pywayland.protocol.wayland.WlDisplay │ │ │ │ │ - │ │ │ │ │ - Core global object │ │ │ │ │ - │ │ │ │ │ - The core global object. This is a special singleton object. It is │ │ │ │ │ - used for internal Wayland protocol features. │ │ │ │ │ - │ │ │ │ │ - sync() -> 'Proxy[WlCallback]' │ │ │ │ │ - │ │ │ │ │ - -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Asynchronous roundtrip │ │ │ │ │ - │ │ │ │ │ - The sync request asks the server to emit the 'done' event on the │ │ │ │ │ - returned "WlCallback" object. Since requests are handled in- │ │ │ │ │ - order and events are delivered in-order, this can be used as a │ │ │ │ │ - barrier to ensure all previous requests and the resulting events │ │ │ │ │ - have been handled. │ │ │ │ │ - │ │ │ │ │ - The object returned by this request will be destroyed by the │ │ │ │ │ - compositor after the callback is fired and as such the client │ │ │ │ │ - must not attempt to use it after that point. │ │ │ │ │ - │ │ │ │ │ - The callback_data passed in the callback is undefined and should │ │ │ │ │ - be ignored. │ │ │ │ │ - │ │ │ │ │ - Returns: │ │ │ │ │ - "WlCallback" -- callback object for the sync request │ │ │ │ │ - │ │ │ │ │ - get_registry() -> 'Proxy[WlRegistry]' │ │ │ │ │ - │ │ │ │ │ - -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ - │ │ │ │ │ - Get global registry object │ │ │ │ │ + * **x** (*ArgumentType.Int*) -- region-local x coordinate │ │ │ │ │ │ │ │ │ │ - This request creates a registry object that allows the client to │ │ │ │ │ - list and bind the global objects available from the compositor. │ │ │ │ │ + * **y** (*ArgumentType.Int*) -- region-local y coordinate │ │ │ │ │ │ │ │ │ │ - It should be noted that the server side resources consumed in │ │ │ │ │ - response to a get_registry request can only be released when the │ │ │ │ │ - client disconnects, not when the client side proxy is destroyed. │ │ │ │ │ - Therefore, clients should invoke get_registry as infrequently as │ │ │ │ │ - possible to avoid wasting memory. │ │ │ │ │ + * **width** (*ArgumentType.Int*) -- rectangle width │ │ │ │ │ │ │ │ │ │ - Returns: │ │ │ │ │ - "WlRegistry" -- global registry object │ │ │ │ │ + * **height** (*ArgumentType.Int*) -- rectangle height │ │ │ │ │ │ │ │ │ │ - error(object_id: 'Any', code: 'int', message: 'str') -> 'None' │ │ │ │ │ + subtract(x: 'int', y: 'int', width: 'int', height: 'int') -> 'None' │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 0 (attached to "Proxy" instance) ]- │ │ │ │ │ + -[ Request -- opcode 2 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Fatal error event │ │ │ │ │ + Subtract rectangle from region │ │ │ │ │ │ │ │ │ │ - The error event is sent out when a fatal (non-recoverable) error │ │ │ │ │ - has occurred. The object_id argument is the object where the │ │ │ │ │ - error occurred, most often in response to a request to that │ │ │ │ │ - object. The code identifies the error and is defined by the │ │ │ │ │ - object interface. As such, each interface defines its own set │ │ │ │ │ - of error codes. The message is a brief description of the │ │ │ │ │ - error, for (debugging) convenience. │ │ │ │ │ + Subtract the specified rectangle from the region. │ │ │ │ │ │ │ │ │ │ Parameters: │ │ │ │ │ - * **object_id** (*ArgumentType.Object*) -- object where the │ │ │ │ │ - error occurred │ │ │ │ │ - │ │ │ │ │ - * **code** (*ArgumentType.Uint*) -- error code │ │ │ │ │ + * **x** (*ArgumentType.Int*) -- region-local x coordinate │ │ │ │ │ │ │ │ │ │ - * **message** (*ArgumentType.String*) -- error description │ │ │ │ │ + * **y** (*ArgumentType.Int*) -- region-local y coordinate │ │ │ │ │ │ │ │ │ │ - delete_id(id: 'int') -> 'None' │ │ │ │ │ + * **width** (*ArgumentType.Int*) -- rectangle width │ │ │ │ │ │ │ │ │ │ - -[ Event -- opcode 1 (attached to "Proxy" instance) ]- │ │ │ │ │ + * **height** (*ArgumentType.Int*) -- rectangle height │ │ │ │ │ │ │ │ │ │ - Acknowledge object id deletion │ │ │ │ │ │ │ │ │ │ - This event is used internally by the object ID management logic. │ │ │ │ │ - When a client deletes an object that it had created, the server │ │ │ │ │ - will send this event to acknowledge that it has seen the delete │ │ │ │ │ - request. When the client receives this event, it will know that │ │ │ │ │ - it can safely reuse the object ID. │ │ │ │ │ +WlSubcompositor │ │ │ │ │ +=============== │ │ │ │ │ │ │ │ │ │ - Parameters: │ │ │ │ │ - **id** (*ArgumentType.Uint*) -- deleted object ID │ │ │ │ │ +class pywayland.protocol.wayland.WlSubcompositor │ │ │ │ │ │ │ │ │ │ + Sub-surface compositing │ │ │ │ │ │ │ │ │ │ -WlShmPool │ │ │ │ │ -========= │ │ │ │ │ + The global interface exposing sub-surface compositing capabilities. │ │ │ │ │ + A "WlSurface", that has sub-surfaces associated, is called the │ │ │ │ │ + parent surface. Sub-surfaces can be arbitrarily nested and create a │ │ │ │ │ + tree of sub-surfaces. │ │ │ │ │ │ │ │ │ │ -class pywayland.protocol.wayland.WlShmPool │ │ │ │ │ + The root surface in a tree of sub-surfaces is the main surface. The │ │ │ │ │ + main surface cannot be a sub-surface, because sub-surfaces must │ │ │ │ │ + always have a parent. │ │ │ │ │ │ │ │ │ │ - A shared memory pool │ │ │ │ │ + A main surface with its sub-surfaces forms a (compound) window. For │ │ │ │ │ + window management purposes, this set of "WlSurface" objects is to │ │ │ │ │ + be considered as a single window, and it should also behave as │ │ │ │ │ + such. │ │ │ │ │ │ │ │ │ │ - The "WlShmPool" object encapsulates a piece of memory shared │ │ │ │ │ - between the compositor and client. Through the "WlShmPool" object, │ │ │ │ │ - the client can allocate shared memory "WlBuffer" objects. All │ │ │ │ │ - objects created through the same pool share the same underlying │ │ │ │ │ - mapped memory. Reusing the mapped memory avoids the setup/teardown │ │ │ │ │ - overhead and is useful when interactively resizing a surface or for │ │ │ │ │ - many small buffers. │ │ │ │ │ + The aim of sub-surfaces is to offload some of the compositing work │ │ │ │ │ + within a window from clients to the compositor. A prime example is │ │ │ │ │ + a video player with decorations and video in separate "WlSurface" │ │ │ │ │ + objects. This should allow the compositor to pass YUV video buffer │ │ │ │ │ + processing to dedicated overlay hardware when possible. │ │ │ │ │ │ │ │ │ │ - create_buffer(offset: 'int', width: 'int', height: 'int', stride: 'int', format: 'int') -> 'Proxy[WlBuffer]' │ │ │ │ │ + destroy() -> 'None' │ │ │ │ │ │ │ │ │ │ -[ Request -- opcode 0 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Create a buffer from the pool │ │ │ │ │ - │ │ │ │ │ - Create a "WlBuffer" object from the pool. │ │ │ │ │ - │ │ │ │ │ - The buffer is created offset bytes into the pool and has width │ │ │ │ │ - and height as specified. The stride argument specifies the │ │ │ │ │ - number of bytes from the beginning of one row to the beginning │ │ │ │ │ - of the next. The format is the pixel format of the buffer and │ │ │ │ │ - must be one of those advertised through the "WlShm.format()" │ │ │ │ │ - event. │ │ │ │ │ - │ │ │ │ │ - A buffer will keep a reference to the pool it was created from │ │ │ │ │ - so it is valid to destroy the pool immediately after creating a │ │ │ │ │ - buffer from it. │ │ │ │ │ - │ │ │ │ │ - Parameters: │ │ │ │ │ - * **offset** (*ArgumentType.Int*) -- buffer byte offset │ │ │ │ │ - within the pool │ │ │ │ │ - │ │ │ │ │ - * **width** (*ArgumentType.Int*) -- buffer width, in pixels │ │ │ │ │ - │ │ │ │ │ - * **height** (*ArgumentType.Int*) -- buffer height, in pixels │ │ │ │ │ - │ │ │ │ │ - * **stride** (*ArgumentType.Int*) -- number of bytes from the │ │ │ │ │ - beginning of one row to the beginning of the next row │ │ │ │ │ - │ │ │ │ │ - * **format** (*ArgumentType.Uint*) -- buffer pixel format │ │ │ │ │ + Unbind from the subcompositor interface │ │ │ │ │ │ │ │ │ │ - Returns: │ │ │ │ │ - "WlBuffer" -- buffer to create │ │ │ │ │ + Informs the server that the client will not be using this │ │ │ │ │ + protocol object anymore. This does not affect any other objects, │ │ │ │ │ + "WlSubsurface" objects included. │ │ │ │ │ │ │ │ │ │ - destroy() -> 'None' │ │ │ │ │ + get_subsurface(surface: 'WlSurface', parent: 'WlSurface') -> 'Proxy[WlSubsurface]' │ │ │ │ │ │ │ │ │ │ -[ Request -- opcode 1 (attached to "Resource" instance) ]- │ │ │ │ │ │ │ │ │ │ - Destroy the pool │ │ │ │ │ + Give a surface the role sub-surface │ │ │ │ │ │ │ │ │ │ - Destroy the shared memory pool. │ │ │ │ │ + Create a sub-surface interface for the given surface, and │ │ │ │ │ + associate it with the given parent surface. This turns a plain │ │ │ │ │ + "WlSurface" into a sub-surface. │ │ │ │ │ │ │ │ │ │ - The mmapped memory will be released when all buffers that have │ │ │ │ │ - been created from this pool are gone. │ │ │ │ │ + The to-be sub-surface must not already have another role, and it │ │ │ │ │ + must not have an existing "WlSubsurface" object. Otherwise the │ │ │ │ │ + bad_surface protocol error is raised. │ │ │ │ │ │ │ │ │ │ - resize(size: 'int') -> 'None' │ │ │ │ │ + Adding sub-surfaces to a parent is a double-buffered operation │ │ │ │ │ + on the parent (see "WlSurface.commit()"). The effect of adding a │ │ │ │ │ + sub-surface becomes visible on the next time the state of the │ │ │ │ │ + parent surface is applied. │ │ │ │ │ │ │ │ │ │ - -[ Request -- opcode 2 (attached to "Resource" instance) ]- │ │ │ │ │ + The parent surface must not be one of the child surface's │ │ │ │ │ + descendants, and the parent must be different from the child │ │ │ │ │ + surface, otherwise the bad_parent protocol error is raised. │ │ │ │ │ │ │ │ │ │ - Change the size of the pool mapping │ │ │ │ │ + This request modifies the behaviour of "WlSurface.commit()" │ │ │ │ │ + request on the sub- surface, see the documentation on │ │ │ │ │ + "WlSubsurface" interface. │ │ │ │ │ │ │ │ │ │ - This request will cause the server to remap the backing memory │ │ │ │ │ - for the pool from the file descriptor passed when the pool was │ │ │ │ │ - created, but using the new size. This request can only be used │ │ │ │ │ - to make the pool bigger. │ │ │ │ │ + Parameters: │ │ │ │ │ + * **surface** ("WlSurface") -- the surface to be turned into │ │ │ │ │ + a sub-surface │ │ │ │ │ │ │ │ │ │ - This request only changes the amount of bytes that are mmapped │ │ │ │ │ - by the server and does not touch the file corresponding to the │ │ │ │ │ - file descriptor passed at creation time. It is the client's │ │ │ │ │ - responsibility to ensure that the file is at least as big as the │ │ │ │ │ - new pool size. │ │ │ │ │ + * **parent** ("WlSurface") -- the parent surface │ │ │ │ │ │ │ │ │ │ - Parameters: │ │ │ │ │ - **size** (*ArgumentType.Int*) -- new size of the pool, in │ │ │ │ │ - bytes │ │ │ │ │ + Returns: │ │ │ │ │ + "WlSubsurface" -- the new sub- surface object ID ├── python3-pywayland_0.4.18-1_i386.deb │ ├── file list │ │ @@ -1,3 +1,3 @@ │ │ -rw-r--r-- 0 0 0 4 2024-10-11 20:38:19.000000 debian-binary │ │ -rw-r--r-- 0 0 0 2916 2024-10-11 20:38:19.000000 control.tar.xz │ │ --rw-r--r-- 0 0 0 116328 2024-10-11 20:38:19.000000 data.tar.xz │ │ +-rw-r--r-- 0 0 0 116644 2024-10-11 20:38:19.000000 data.tar.xz │ ├── control.tar.xz │ │ ├── control.tar │ │ │ ├── ./md5sums │ │ │ │ ├── ./md5sums │ │ │ │ │┄ Files differ │ ├── data.tar.xz │ │ ├── data.tar │ │ │ ├── file list │ │ │ │ @@ -88,8 +88,8 @@ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 170 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/changelog.Debian.gz │ │ │ │ -rw-r--r-- 0 root (0) root (0) 4446 2024-10-11 20:38:19.000000 ./usr/share/doc/python3-pywayland/copyright │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2024-10-11 20:38:19.000000 ./usr/share/lintian/ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2024-10-11 20:38:19.000000 ./usr/share/lintian/overrides/ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 170 2024-10-11 20:38:19.000000 ./usr/share/lintian/overrides/python3-pywayland │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2024-10-11 20:38:19.000000 ./usr/share/man/ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2024-10-11 20:38:19.000000 ./usr/share/man/man1/ │ │ │ │ --rw-r--r-- 0 root (0) root (0) 40992 2024-10-11 20:38:19.000000 ./usr/share/man/man1/pywayland-scanner.1.gz │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 41309 2024-10-11 20:38:19.000000 ./usr/share/man/man1/pywayland-scanner.1.gz │ │ │ ├── ./usr/share/man/man1/pywayland-scanner.1.gz │ │ │ │ ├── pywayland-scanner.1 │ │ │ │ │┄ Ordering differences only │ │ │ │ │ @@ -1095,429 +1095,657 @@ │ │ │ │ │ .TP │ │ │ │ │ .B class pywayland.protocol_core.argument.ArgumentType(value, names=, *values, module=None, qualname=None, type=None, start=1, boundary=None) │ │ │ │ │ .UNINDENT │ │ │ │ │ .SS Protocol Modules │ │ │ │ │ .sp │ │ │ │ │ Wayland protocols built against Wayland 1.21.0 and Wayland Protocols 1.25. │ │ │ │ │ .SS wayland Module │ │ │ │ │ -.SS WlDataSource │ │ │ │ │ +.SS WlDisplay │ │ │ │ │ .INDENT 0.0 │ │ │ │ │ .TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlDataSource │ │ │ │ │ -Offer to transfer data │ │ │ │ │ +.B class pywayland.protocol.wayland.WlDisplay │ │ │ │ │ +Core global object │ │ │ │ │ .sp │ │ │ │ │ -The \fI\%WlDataSource\fP object is the source side of a │ │ │ │ │ -\fI\%WlDataOffer\fP\&. It is created by the │ │ │ │ │ -source client in a data transfer and provides a way to describe the offered │ │ │ │ │ -data and a way to respond to requests to transfer the data. │ │ │ │ │ +The core global object. This is a special singleton object. It is used │ │ │ │ │ +for internal Wayland protocol features. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B offer(mime_type: \(aqstr\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B sync() -> \(aqProxy[WlCallback]\(aq │ │ │ │ │ .sp │ │ │ │ │ Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Add an offered mime type │ │ │ │ │ +Asynchronous roundtrip │ │ │ │ │ .sp │ │ │ │ │ -This request adds a mime type to the set of mime types advertised to │ │ │ │ │ -targets. Can be called several times to offer multiple types. │ │ │ │ │ +The sync request asks the server to emit the \(aqdone\(aq event on the │ │ │ │ │ +returned \fI\%WlCallback\fP object. Since │ │ │ │ │ +requests are handled in\-order and events are delivered in\-order, this │ │ │ │ │ +can be used as a barrier to ensure all previous requests and the │ │ │ │ │ +resulting events have been handled. │ │ │ │ │ +.sp │ │ │ │ │ +The object returned by this request will be destroyed by the compositor │ │ │ │ │ +after the callback is fired and as such the client must not attempt to │ │ │ │ │ +use it after that point. │ │ │ │ │ +.sp │ │ │ │ │ +The callback_data passed in the callback is undefined and should be │ │ │ │ │ +ignored. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -\fBmime_type\fP (\fIArgumentType.String\fP) \-\- mime type offered by the data source │ │ │ │ │ +.B Returns │ │ │ │ │ +\fI\%WlCallback\fP \-\- callback object │ │ │ │ │ +for the sync request │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B destroy() -> \(aqNone\(aq │ │ │ │ │ +.B get_registry() -> \(aqProxy[WlRegistry]\(aq │ │ │ │ │ .sp │ │ │ │ │ Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Destroy the data source │ │ │ │ │ +Get global registry object │ │ │ │ │ .sp │ │ │ │ │ -Destroy the data source. │ │ │ │ │ +This request creates a registry object that allows the client to list │ │ │ │ │ +and bind the global objects available from the compositor. │ │ │ │ │ +.sp │ │ │ │ │ +It should be noted that the server side resources consumed in response │ │ │ │ │ +to a get_registry request can only be released when the client │ │ │ │ │ +disconnects, not when the client side proxy is destroyed. Therefore, │ │ │ │ │ +clients should invoke get_registry as infrequently as possible to avoid │ │ │ │ │ +wasting memory. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Returns │ │ │ │ │ +\fI\%WlRegistry\fP \-\- global registry │ │ │ │ │ +object │ │ │ │ │ +.UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B set_actions(dnd_actions: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B error(object_id: \(aqAny\(aq, code: \(aqint\(aq, message: \(aqstr\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 2 (attached to \fBResource\fP instance) │ │ │ │ │ +Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Set the available drag\-and\-drop actions │ │ │ │ │ +Fatal error event │ │ │ │ │ .sp │ │ │ │ │ -Sets the actions that the source side client supports for this │ │ │ │ │ -operation. This request may trigger \fI\%WlDataSource.action()\fP and │ │ │ │ │ -\fI\%WlDataOffer.action()\fP events if the │ │ │ │ │ -compositor needs to change the selected action. │ │ │ │ │ +The error event is sent out when a fatal (non\-recoverable) error has │ │ │ │ │ +occurred. The object_id argument is the object where the error │ │ │ │ │ +occurred, most often in response to a request to that object. The code │ │ │ │ │ +identifies the error and is defined by the object interface. As such, │ │ │ │ │ +each interface defines its own set of error codes. The message is a │ │ │ │ │ +brief description of the error, for (debugging) convenience. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Parameters │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBobject_id\fP (\fIArgumentType.Object\fP) \-\- object where the error occurred │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBcode\fP (\fIArgumentType.Uint\fP) \-\- error code │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBmessage\fP (\fIArgumentType.String\fP) \-\- error description │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B delete_id(id: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -The dnd_actions argument must contain only values expressed in the │ │ │ │ │ -\fBWlDataDeviceManager.dnd_actions()\fP enum, │ │ │ │ │ -otherwise it will result in a protocol error. │ │ │ │ │ +Event \-\- opcode 1 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -This request must be made once only, and can only be made on sources │ │ │ │ │ -used in drag\-and\-drop, so it must be performed before │ │ │ │ │ -\fI\%WlDataDevice.start_drag()\fP\&. Attempting to │ │ │ │ │ -use the source other than for drag\-and\-drop will raise a protocol │ │ │ │ │ -error. │ │ │ │ │ +Acknowledge object id deletion │ │ │ │ │ +.sp │ │ │ │ │ +This event is used internally by the object ID management logic. When a │ │ │ │ │ +client deletes an object that it had created, the server will send this │ │ │ │ │ +event to acknowledge that it has seen the delete request. When the │ │ │ │ │ +client receives this event, it will know that it can safely reuse the │ │ │ │ │ +object ID. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -\fBdnd_actions\fP (\fIArgumentType.Uint\fP) \-\- actions supported by the data source │ │ │ │ │ +\fBid\fP (\fIArgumentType.Uint\fP) \-\- deleted object ID │ │ │ │ │ +.UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ +.SS WlCallback │ │ │ │ │ +.INDENT 0.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B class pywayland.protocol.wayland.WlCallback │ │ │ │ │ +Callback object │ │ │ │ │ +.sp │ │ │ │ │ +Clients can handle the \(aqdone\(aq event to get notified when the related │ │ │ │ │ +request is done. │ │ │ │ │ +.sp │ │ │ │ │ +Note, because \fI\%WlCallback\fP objects are created from multiple │ │ │ │ │ +independent factory interfaces, the \fI\%WlCallback\fP interface is frozen │ │ │ │ │ +at version 1. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B target(mime_type: \(aqstr | None\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B done(callback_data: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -A target accepts an offered mime type │ │ │ │ │ -.sp │ │ │ │ │ -Sent when a target accepts pointer_focus or motion events. If a target │ │ │ │ │ -does not accept any of the offered types, type is NULL. │ │ │ │ │ +Done event │ │ │ │ │ .sp │ │ │ │ │ -Used for feedback during drag\-and\-drop. │ │ │ │ │ +Notify the client when the related request is done. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -\fBmime_type\fP (\fIArgumentType.String\fP or \fINone\fP) \-\- mime type accepted by the target │ │ │ │ │ +\fBcallback_data\fP (\fIArgumentType.Uint\fP) \-\- request\-specific data for the callback │ │ │ │ │ +.UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ +.SS WlDataOffer │ │ │ │ │ +.INDENT 0.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B class pywayland.protocol.wayland.WlDataOffer │ │ │ │ │ +Offer to transfer data │ │ │ │ │ +.sp │ │ │ │ │ +A \fI\%WlDataOffer\fP represents a piece of data offered for transfer by │ │ │ │ │ +another client (the source client). It is used by the copy\-and\-paste and │ │ │ │ │ +drag\-and\-drop mechanisms. The offer describes the different mime types │ │ │ │ │ +that the data can be converted to and provides the mechanism for │ │ │ │ │ +transferring the data directly from the source client. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B send(mime_type: \(aqstr\(aq, fd: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B accept(serial: \(aqint\(aq, mime_type: \(aqstr | None\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 1 (attached to \fBProxy\fP instance) │ │ │ │ │ +Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Send the data │ │ │ │ │ +Accept one of the offered mime types │ │ │ │ │ .sp │ │ │ │ │ -Request for data from the client. Send the data as the specified mime │ │ │ │ │ -type over the passed file descriptor, then close it. │ │ │ │ │ +Indicate that the client can accept the given mime type, or NULL for │ │ │ │ │ +not accepted. │ │ │ │ │ +.sp │ │ │ │ │ +For objects of version 2 or older, this request is used by the client │ │ │ │ │ +to give feedback whether the client can receive the given mime type, or │ │ │ │ │ +NULL if none is accepted; the feedback does not determine whether the │ │ │ │ │ +drag\-and\-drop operation succeeds or not. │ │ │ │ │ +.sp │ │ │ │ │ +For objects of version 3 or newer, this request determines the final │ │ │ │ │ +result of the drag\-and\-drop operation. If the end result is that no │ │ │ │ │ +mime types were accepted, the drag\-and\-drop operation will be cancelled │ │ │ │ │ +and the corresponding drag source will receive │ │ │ │ │ +\fI\%WlDataSource.cancelled()\fP\&. Clients may still │ │ │ │ │ +use this event in conjunction with \fI\%WlDataSource.action()\fP for feedback. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBmime_type\fP (\fIArgumentType.String\fP) \-\- mime type for the data │ │ │ │ │ +\fBserial\fP (\fIArgumentType.Uint\fP) \-\- serial number of the accept request │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBfd\fP (\fIArgumentType.FileDescriptor\fP) \-\- file descriptor for the data │ │ │ │ │ +\fBmime_type\fP (\fIArgumentType.String\fP or \fINone\fP) \-\- mime type accepted by the client │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B cancelled() -> \(aqNone\(aq │ │ │ │ │ +.B receive(mime_type: \(aqstr\(aq, fd: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 2 (attached to \fBProxy\fP instance) │ │ │ │ │ +Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Selection was cancelled │ │ │ │ │ +Request that the data is transferred │ │ │ │ │ .sp │ │ │ │ │ -This data source is no longer valid. There are several reasons why this │ │ │ │ │ -could happen: │ │ │ │ │ +To transfer the offered data, the client issues this request and │ │ │ │ │ +indicates the mime type it wants to receive. The transfer happens │ │ │ │ │ +through the passed file descriptor (typically created with the pipe │ │ │ │ │ +system call). The source client writes the data in the mime type │ │ │ │ │ +representation requested and then closes the file descriptor. │ │ │ │ │ +.sp │ │ │ │ │ +The receiving client reads from the read end of the pipe until EOF and │ │ │ │ │ +then closes its end, at which point the transfer is complete. │ │ │ │ │ +.sp │ │ │ │ │ +This request may happen multiple times for different mime types, both │ │ │ │ │ +before and after \fI\%WlDataDevice.drop()\fP\&. Drag\-and\-drop │ │ │ │ │ +destination clients may preemptively fetch data or examine it more │ │ │ │ │ +closely to determine acceptance. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Parameters │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -The data source has been replaced by another data source. │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -The drag\-and\-drop operation was performed, but the drop destination │ │ │ │ │ -did not accept any of the mime types offered through │ │ │ │ │ -\fI\%WlDataSource.target()\fP\&. │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -The drag\-and\-drop operation was performed, but the drop destination │ │ │ │ │ -did not select any of the actions present in the mask offered through │ │ │ │ │ -\fI\%WlDataSource.action()\fP\&. │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -The drag\-and\-drop operation was performed but didn\(aqt happen over a │ │ │ │ │ -surface. │ │ │ │ │ +\fBmime_type\fP (\fIArgumentType.String\fP) \-\- mime type desired by receiver │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -The compositor cancelled the drag\-and\-drop operation (e.g. compositor │ │ │ │ │ -dependent timeouts to avoid stale drag\-and\-drop transfers). │ │ │ │ │ +\fBfd\fP (\fIArgumentType.FileDescriptor\fP) \-\- file descriptor for data transfer │ │ │ │ │ .UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B destroy() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -The client should clean up and destroy this data source. │ │ │ │ │ +Request \-\- opcode 2 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -For objects of version 2 or older, \fI\%WlDataSource.cancelled()\fP │ │ │ │ │ -will only be emitted if the data source was replaced by another data │ │ │ │ │ -source. │ │ │ │ │ +Destroy data offer │ │ │ │ │ +.sp │ │ │ │ │ +Destroy the data offer. │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B dnd_drop_performed() -> \(aqNone\(aq │ │ │ │ │ +.B finish() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 3 (attached to \fBProxy\fP instance) │ │ │ │ │ +Request \-\- opcode 3 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -The drag\-and\-drop operation physically finished │ │ │ │ │ +The offer will no longer be used │ │ │ │ │ .sp │ │ │ │ │ -The user performed the drop action. This event does not indicate │ │ │ │ │ -acceptance, \fI\%WlDataSource.cancelled()\fP may still be emitted │ │ │ │ │ -afterwards if the drop destination does not accept any mime type. │ │ │ │ │ +Notifies the compositor that the drag destination successfully finished │ │ │ │ │ +the drag\-and\-drop operation. │ │ │ │ │ .sp │ │ │ │ │ -However, this event might however not be received if the compositor │ │ │ │ │ -cancelled the drag\-and\-drop operation before this event could happen. │ │ │ │ │ +Upon receiving this request, the compositor will emit │ │ │ │ │ +\fI\%WlDataSource.dnd_finished()\fP on the drag │ │ │ │ │ +source client. │ │ │ │ │ .sp │ │ │ │ │ -Note that the data_source may still be used in the future and should │ │ │ │ │ -not be destroyed here. │ │ │ │ │ +It is a client error to perform other requests than │ │ │ │ │ +\fI\%WlDataOffer.destroy()\fP after this one. It is also an error to │ │ │ │ │ +perform this request after a NULL mime type has been set in │ │ │ │ │ +\fI\%WlDataOffer.accept()\fP or no action was received through │ │ │ │ │ +\fI\%WlDataOffer.action()\fP\&. │ │ │ │ │ +.sp │ │ │ │ │ +If \fI\%WlDataOffer.finish()\fP request is received for a non drag and │ │ │ │ │ +drop operation, the invalid_finish protocol error is raised. │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B dnd_finished() -> \(aqNone\(aq │ │ │ │ │ +.B set_actions(dnd_actions: \(aqint\(aq, preferred_action: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 4 (attached to \fBProxy\fP instance) │ │ │ │ │ +Request \-\- opcode 4 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -The drag\-and\-drop operation concluded │ │ │ │ │ +Set the available/preferred drag\-and\-drop actions │ │ │ │ │ .sp │ │ │ │ │ -The drop destination finished interoperating with this data source, so │ │ │ │ │ -the client is now free to destroy this data source and free all │ │ │ │ │ -associated data. │ │ │ │ │ +Sets the actions that the destination side client supports for this │ │ │ │ │ +operation. This request may trigger the emission of │ │ │ │ │ +\fI\%WlDataSource.action()\fP and │ │ │ │ │ +\fI\%WlDataOffer.action()\fP events if the compositor needs to change │ │ │ │ │ +the selected action. │ │ │ │ │ .sp │ │ │ │ │ -If the action used to perform the operation was \(dqmove\(dq, the source can │ │ │ │ │ -now delete the transferred data. │ │ │ │ │ +This request can be called multiple times throughout the drag\-and\-drop │ │ │ │ │ +operation, typically in response to \fI\%WlDataDevice.enter()\fP or │ │ │ │ │ +\fI\%WlDataDevice.motion()\fP events. │ │ │ │ │ +.sp │ │ │ │ │ +This request determines the final result of the drag\-and\-drop │ │ │ │ │ +operation. If the end result is that no action is accepted, the drag │ │ │ │ │ +source will receive \fI\%WlDataSource.cancelled()\fP\&. │ │ │ │ │ +.sp │ │ │ │ │ +The dnd_actions argument must contain only values expressed in the │ │ │ │ │ +\fBWlDataDeviceManager.dnd_actions()\fP enum, and │ │ │ │ │ +the preferred_action argument must only contain one of those values │ │ │ │ │ +set, otherwise it will result in a protocol error. │ │ │ │ │ +.sp │ │ │ │ │ +While managing an \(dqask\(dq action, the destination drag\-and\-drop client │ │ │ │ │ +may perform further \fI\%WlDataOffer.receive()\fP requests, and is │ │ │ │ │ +expected to perform one last \fI\%WlDataOffer.set_actions()\fP request │ │ │ │ │ +with a preferred action other than \(dqask\(dq (and optionally │ │ │ │ │ +\fI\%WlDataOffer.accept()\fP) before requesting │ │ │ │ │ +\fI\%WlDataOffer.finish()\fP, in order to convey the action selected by │ │ │ │ │ +the user. If the preferred action is not in the │ │ │ │ │ +\fI\%WlDataOffer.source_actions()\fP mask, an error will be raised. │ │ │ │ │ +.sp │ │ │ │ │ +If the \(dqask\(dq action is dismissed (e.g. user cancellation), the client │ │ │ │ │ +is expected to perform \fI\%WlDataOffer.destroy()\fP right away. │ │ │ │ │ +.sp │ │ │ │ │ +This request can only be made on drag\-and\-drop offers, a protocol error │ │ │ │ │ +will be raised otherwise. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Parameters │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBdnd_actions\fP (\fIArgumentType.Uint\fP) \-\- actions supported by the destination client │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBpreferred_action\fP (\fIArgumentType.Uint\fP) \-\- action preferred by the destination client │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B offer(mime_type: \(aqstr\(aq) -> \(aqNone\(aq │ │ │ │ │ +.sp │ │ │ │ │ +Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ +.sp │ │ │ │ │ +Advertise offered mime type │ │ │ │ │ +.sp │ │ │ │ │ +Sent immediately after creating the \fI\%WlDataOffer\fP object. One │ │ │ │ │ +event per offered mime type. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Parameters │ │ │ │ │ +\fBmime_type\fP (\fIArgumentType.String\fP) \-\- offered mime type │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B source_actions(source_actions: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +.sp │ │ │ │ │ +Event \-\- opcode 1 (attached to \fBProxy\fP instance) │ │ │ │ │ +.sp │ │ │ │ │ +Notify the source\-side available actions │ │ │ │ │ +.sp │ │ │ │ │ +This event indicates the actions offered by the data source. It will be │ │ │ │ │ +sent immediately after creating the \fI\%WlDataOffer\fP object, or │ │ │ │ │ +anytime the source side changes its offered actions through │ │ │ │ │ +\fI\%WlDataSource.set_actions()\fP\&. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Parameters │ │ │ │ │ +\fBsource_actions\fP (\fIArgumentType.Uint\fP) \-\- actions offered by the data source │ │ │ │ │ +.UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B action(dnd_action: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 5 (attached to \fBProxy\fP instance) │ │ │ │ │ +Event \-\- opcode 2 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ Notify the selected action │ │ │ │ │ .sp │ │ │ │ │ This event indicates the action selected by the compositor after │ │ │ │ │ matching the source/destination side actions. Only one action (or none) │ │ │ │ │ will be offered here. │ │ │ │ │ .sp │ │ │ │ │ This event can be emitted multiple times during the drag\-and\-drop │ │ │ │ │ -operation, mainly in response to destination side changes through │ │ │ │ │ -\fI\%WlDataOffer.set_actions()\fP, and as the data │ │ │ │ │ -device enters/leaves surfaces. │ │ │ │ │ +operation in response to destination side action changes through │ │ │ │ │ +\fI\%WlDataOffer.set_actions()\fP\&. │ │ │ │ │ .sp │ │ │ │ │ -It is only possible to receive this event after │ │ │ │ │ -\fI\%WlDataSource.dnd_drop_performed()\fP if the drag\-and\-drop │ │ │ │ │ -operation ended in an \(dqask\(dq action, in which case the final │ │ │ │ │ -\fI\%WlDataSource.action()\fP event will happen immediately before │ │ │ │ │ -\fI\%WlDataSource.dnd_finished()\fP\&. │ │ │ │ │ +This event will no longer be emitted after \fI\%WlDataDevice.drop()\fP happened on the drag\- │ │ │ │ │ +and\-drop destination, the client must honor the last action received, │ │ │ │ │ +or the last preferred one set through \fI\%WlDataOffer.set_actions()\fP │ │ │ │ │ +when handling an \(dqask\(dq action. │ │ │ │ │ .sp │ │ │ │ │ Compositors may also change the selected action on the fly, mainly in │ │ │ │ │ response to keyboard modifier changes during the drag\-and\-drop │ │ │ │ │ operation. │ │ │ │ │ .sp │ │ │ │ │ -The most recent action received is always the valid one. The chosen │ │ │ │ │ -action may change alongside negotiation (e.g. an \(dqask\(dq action can turn │ │ │ │ │ -into a \(dqmove\(dq operation), so the effects of the final action must │ │ │ │ │ -always be applied in \fBWlDataOffer.dnd_finished()\fP\&. │ │ │ │ │ +The most recent action received is always the valid one. Prior to │ │ │ │ │ +receiving \fI\%WlDataDevice.drop()\fP, the chosen action may │ │ │ │ │ +change (e.g. due to keyboard modifiers being pressed). At the time of │ │ │ │ │ +receiving \fI\%WlDataDevice.drop()\fP the drag\-and\-drop │ │ │ │ │ +destination must honor the last action received. │ │ │ │ │ .sp │ │ │ │ │ -Clients can trigger cursor surface changes from this point, so they │ │ │ │ │ -reflect the current action. │ │ │ │ │ +Action changes may still happen after \fI\%WlDataDevice.drop()\fP, especially on \(dqask\(dq │ │ │ │ │ +actions, where the drag\-and\-drop destination may choose another action │ │ │ │ │ +afterwards. Action changes happening at this stage are always the │ │ │ │ │ +result of inter\-client negotiation, the compositor shall no longer be │ │ │ │ │ +able to induce a different action. │ │ │ │ │ +.sp │ │ │ │ │ +Upon \(dqask\(dq actions, it is expected that the drag\-and\-drop destination │ │ │ │ │ +may potentially choose a different action and/or mime type, based on │ │ │ │ │ +\fI\%WlDataOffer.source_actions()\fP and finally chosen by the user │ │ │ │ │ +(e.g. popping up a menu with the available options). The final │ │ │ │ │ +\fI\%WlDataOffer.set_actions()\fP and \fI\%WlDataOffer.accept()\fP │ │ │ │ │ +requests must happen before the call to \fI\%WlDataOffer.finish()\fP\&. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ \fBdnd_action\fP (\fIArgumentType.Uint\fP) \-\- action selected by the compositor │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ -.SS WlSubsurface │ │ │ │ │ +.SS WlTouch │ │ │ │ │ .INDENT 0.0 │ │ │ │ │ .TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlSubsurface │ │ │ │ │ -Sub\-surface interface to a \fI\%WlSurface\fP │ │ │ │ │ -.sp │ │ │ │ │ -An additional interface to a \fI\%WlSurface\fP │ │ │ │ │ -object, which has been made a sub\-surface. A sub\-surface has one parent │ │ │ │ │ -surface. A sub\-surface\(aqs size and position are not limited to that of the │ │ │ │ │ -parent. Particularly, a sub\-surface is not automatically clipped to its │ │ │ │ │ -parent\(aqs area. │ │ │ │ │ -.sp │ │ │ │ │ -A sub\-surface becomes mapped, when a non\-NULL │ │ │ │ │ -\fI\%WlBuffer\fP is applied and the parent │ │ │ │ │ -surface is mapped. The order of which one happens first is irrelevant. A │ │ │ │ │ -sub\-surface is hidden if the parent becomes hidden, or if a NULL │ │ │ │ │ -\fI\%WlBuffer\fP is applied. These rules apply │ │ │ │ │ -recursively through the tree of surfaces. │ │ │ │ │ -.sp │ │ │ │ │ -The behaviour of a \fI\%WlSurface.commit()\fP request on a sub\-surface │ │ │ │ │ -depends on the sub\-surface\(aqs mode. The possible modes are synchronized and │ │ │ │ │ -desynchronized, see methods \fI\%WlSubsurface.set_sync()\fP and │ │ │ │ │ -\fI\%WlSubsurface.set_desync()\fP\&. Synchronized mode caches the │ │ │ │ │ -\fI\%WlSurface\fP state to be applied when the │ │ │ │ │ -parent\(aqs state gets applied, and desynchronized mode applies the pending │ │ │ │ │ -\fI\%WlSurface\fP state directly. A sub\- │ │ │ │ │ -surface is initially in the synchronized mode. │ │ │ │ │ -.sp │ │ │ │ │ -Sub\-surfaces also have another kind of state, which is managed by │ │ │ │ │ -\fI\%WlSubsurface\fP requests, as opposed to │ │ │ │ │ -\fI\%WlSurface\fP requests. This state │ │ │ │ │ -includes the sub\-surface position relative to the parent surface │ │ │ │ │ -(\fI\%WlSubsurface.set_position()\fP), and the stacking order of the parent │ │ │ │ │ -and its sub\-surfaces (\fI\%WlSubsurface.place_above()\fP and .place_below). │ │ │ │ │ -This state is applied when the parent surface\(aqs │ │ │ │ │ -\fI\%WlSurface\fP state is applied, regardless │ │ │ │ │ -of the sub\-surface\(aqs mode. As the exception, set_sync and set_desync are │ │ │ │ │ -effective immediately. │ │ │ │ │ -.sp │ │ │ │ │ -The main surface can be thought to be always in desynchronized mode, since │ │ │ │ │ -it does not have a parent in the sub\-surfaces sense. │ │ │ │ │ -.sp │ │ │ │ │ -Even if a sub\-surface is in desynchronized mode, it will behave as in │ │ │ │ │ -synchronized mode, if its parent surface behaves as in synchronized mode. │ │ │ │ │ -This rule is applied recursively throughout the tree of surfaces. This │ │ │ │ │ -means, that one can set a sub\-surface into synchronized mode, and then │ │ │ │ │ -assume that all its child and grand\-child sub\-surfaces are synchronized, │ │ │ │ │ -too, without explicitly setting them. │ │ │ │ │ +.B class pywayland.protocol.wayland.WlTouch │ │ │ │ │ +Touchscreen input device │ │ │ │ │ .sp │ │ │ │ │ -Destroying a sub\-surface takes effect immediately. If you need to │ │ │ │ │ -synchronize the removal of a sub\-surface to the parent surface update, │ │ │ │ │ -unmap the sub\-surface first by attaching a NULL │ │ │ │ │ -\fI\%WlBuffer\fP, update parent, and then │ │ │ │ │ -destroy the sub\-surface. │ │ │ │ │ +The \fI\%WlTouch\fP interface represents a touchscreen associated with a │ │ │ │ │ +seat. │ │ │ │ │ .sp │ │ │ │ │ -If the parent \fI\%WlSurface\fP object is │ │ │ │ │ -destroyed, the sub\-surface is unmapped. │ │ │ │ │ +Touch interactions can consist of one or more contacts. For each contact, a │ │ │ │ │ +series of events is generated, starting with a down event, followed by zero │ │ │ │ │ +or more motion events, and ending with an up event. Events relating to the │ │ │ │ │ +same contact point can be identified by the ID of the sequence. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B release() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -A sub\-surface never has the keyboard focus of any seat. │ │ │ │ │ +Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -The \fI\%WlSurface.offset()\fP request is ignored: clients │ │ │ │ │ -must use set_position instead to move the sub\-surface. │ │ │ │ │ +Release the touch object │ │ │ │ │ +.UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B destroy() -> \(aqNone\(aq │ │ │ │ │ +.B down(serial: \(aqint\(aq, time: \(aqint\(aq, surface: \(aqWlSurface\(aq, id: \(aqint\(aq, x: \(aqfloat\(aq, y: \(aqfloat\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ +Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Remove sub\-surface interface │ │ │ │ │ +Touch down event and beginning of a touch sequence │ │ │ │ │ .sp │ │ │ │ │ -The sub\-surface interface is removed from the │ │ │ │ │ -\fI\%WlSurface\fP object that was turned │ │ │ │ │ -into a sub\-surface with a \fI\%WlSubcompositor.get_subsurface()\fP request. │ │ │ │ │ -The wl_surface\(aqs association to the parent is deleted. The │ │ │ │ │ -\fI\%WlSurface\fP is unmapped immediately. │ │ │ │ │ +A new touch point has appeared on the surface. This touch point is │ │ │ │ │ +assigned a unique ID. Future events from this touch point reference │ │ │ │ │ +this ID. The ID ceases to be valid after a touch up event and may be │ │ │ │ │ +reused in the future. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Parameters │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBserial\fP (\fIArgumentType.Uint\fP) \-\- serial number of the touch down event │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBtime\fP (\fIArgumentType.Uint\fP) \-\- timestamp with millisecond granularity │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBsurface\fP (\fI\%WlSurface\fP) \-\- surface touched │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBid\fP (\fIArgumentType.Int\fP) \-\- the unique ID of this touch point │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBx\fP (\fIArgumentType.Fixed\fP) \-\- surface\-local x coordinate │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBy\fP (\fIArgumentType.Fixed\fP) \-\- surface\-local y coordinate │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B set_position(x: \(aqint\(aq, y: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B up(serial: \(aqint\(aq, time: \(aqint\(aq, id: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ +Event \-\- opcode 1 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Reposition the sub\-surface │ │ │ │ │ +End of a touch event sequence │ │ │ │ │ .sp │ │ │ │ │ -This schedules a sub\-surface position change. The sub\-surface will be │ │ │ │ │ -moved so that its origin (top left corner pixel) will be at the │ │ │ │ │ -location x, y of the parent surface coordinate system. The coordinates │ │ │ │ │ -are not restricted to the parent surface area. Negative values are │ │ │ │ │ -allowed. │ │ │ │ │ +The touch point has disappeared. No further events will be sent for │ │ │ │ │ +this touch point and the touch point\(aqs ID is released and may be reused │ │ │ │ │ +in a future touch down event. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Parameters │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBserial\fP (\fIArgumentType.Uint\fP) \-\- serial number of the touch up event │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBtime\fP (\fIArgumentType.Uint\fP) \-\- timestamp with millisecond granularity │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBid\fP (\fIArgumentType.Int\fP) \-\- the unique ID of this touch point │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B motion(time: \(aqint\(aq, id: \(aqint\(aq, x: \(aqfloat\(aq, y: \(aqfloat\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -The scheduled coordinates will take effect whenever the state of the │ │ │ │ │ -parent surface is applied. │ │ │ │ │ +Event \-\- opcode 2 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -If more than one set_position request is invoked by the client before │ │ │ │ │ -the commit of the parent surface, the position of a new request always │ │ │ │ │ -replaces the scheduled position from any previous request. │ │ │ │ │ +Update of touch point coordinates │ │ │ │ │ .sp │ │ │ │ │ -The initial position is 0, 0. │ │ │ │ │ +A touch point has changed coordinates. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBx\fP (\fIArgumentType.Int\fP) \-\- x coordinate in the parent surface │ │ │ │ │ +\fBtime\fP (\fIArgumentType.Uint\fP) \-\- timestamp with millisecond granularity │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBy\fP (\fIArgumentType.Int\fP) \-\- y coordinate in the parent surface │ │ │ │ │ +\fBid\fP (\fIArgumentType.Int\fP) \-\- the unique ID of this touch point │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBx\fP (\fIArgumentType.Fixed\fP) \-\- surface\-local x coordinate │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBy\fP (\fIArgumentType.Fixed\fP) \-\- surface\-local y coordinate │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B place_above(sibling: \(aqWlSurface\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Request \-\- opcode 2 (attached to \fBResource\fP instance) │ │ │ │ │ +.B frame() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Restack the sub\-surface │ │ │ │ │ +Event \-\- opcode 3 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -This sub\-surface is taken from the stack, and put back just above the │ │ │ │ │ -reference surface, changing the z\-order of the sub\-surfaces. The │ │ │ │ │ -reference surface must be one of the sibling surfaces, or the parent │ │ │ │ │ -surface. Using any other surface, including this sub\-surface, will │ │ │ │ │ -cause a protocol error. │ │ │ │ │ +End of touch frame event │ │ │ │ │ .sp │ │ │ │ │ -The z\-order is double\-buffered. Requests are handled in order and │ │ │ │ │ -applied immediately to a pending state. The final pending state is │ │ │ │ │ -copied to the active state the next time the state of the parent │ │ │ │ │ -surface is applied. │ │ │ │ │ +Indicates the end of a set of events that logically belong together. A │ │ │ │ │ +client is expected to accumulate the data in all events within the │ │ │ │ │ +frame before proceeding. │ │ │ │ │ .sp │ │ │ │ │ -A new sub\-surface is initially added as the top\-most in the stack of │ │ │ │ │ -its siblings and parent. │ │ │ │ │ +A \fI\%WlTouch.frame()\fP terminates at least one event but otherwise │ │ │ │ │ +no guarantee is provided about the set of events within a frame. A │ │ │ │ │ +client must assume that any state not updated in a frame is unchanged │ │ │ │ │ +from the previously known state. │ │ │ │ │ +.UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -\fBsibling\fP (\fI\%WlSurface\fP) \-\- the reference surface │ │ │ │ │ -.UNINDENT │ │ │ │ │ +.B cancel() -> \(aqNone\(aq │ │ │ │ │ +.sp │ │ │ │ │ +Event \-\- opcode 4 (attached to \fBProxy\fP instance) │ │ │ │ │ +.sp │ │ │ │ │ +Touch session cancelled │ │ │ │ │ +.sp │ │ │ │ │ +Sent if the compositor decides the touch stream is a global gesture. No │ │ │ │ │ +further events are sent to the clients from that particular gesture. │ │ │ │ │ +Touch cancellation applies to all touch points currently active on this │ │ │ │ │ +client\(aqs surface. The client is responsible for finalizing the touch │ │ │ │ │ +points, future touch points on this surface may reuse the touch point │ │ │ │ │ +ID. │ │ │ │ │ +.sp │ │ │ │ │ +No frame event is required after the cancel event. │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B place_below(sibling: \(aqWlSurface\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B shape(id: \(aqint\(aq, major: \(aqfloat\(aq, minor: \(aqfloat\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 3 (attached to \fBResource\fP instance) │ │ │ │ │ +Event \-\- opcode 5 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Restack the sub\-surface │ │ │ │ │ +Update shape of touch point │ │ │ │ │ .sp │ │ │ │ │ -The sub\-surface is placed just below the reference surface. See │ │ │ │ │ -\fI\%WlSubsurface.place_above()\fP\&. │ │ │ │ │ +Sent when a touchpoint has changed its shape. │ │ │ │ │ +.sp │ │ │ │ │ +This event does not occur on its own. It is sent before a │ │ │ │ │ +\fI\%WlTouch.frame()\fP event and carries the new shape information for │ │ │ │ │ +any previously reported, or new touch points of that frame. │ │ │ │ │ +.sp │ │ │ │ │ +Other events describing the touch point such as \fI\%WlTouch.down()\fP, │ │ │ │ │ +\fI\%WlTouch.motion()\fP or \fI\%WlTouch.orientation()\fP may be sent │ │ │ │ │ +within the same \fI\%WlTouch.frame()\fP\&. A client should treat these │ │ │ │ │ +events as a single logical touch point update. The order of │ │ │ │ │ +\fI\%WlTouch.shape()\fP, \fI\%WlTouch.orientation()\fP and │ │ │ │ │ +\fI\%WlTouch.motion()\fP is not guaranteed. A \fI\%WlTouch.down()\fP │ │ │ │ │ +event is guaranteed to occur before the first \fI\%WlTouch.shape()\fP │ │ │ │ │ +event for this touch ID but both events may occur within the same │ │ │ │ │ +\fI\%WlTouch.frame()\fP\&. │ │ │ │ │ +.sp │ │ │ │ │ +A touchpoint shape is approximated by an ellipse through the major and │ │ │ │ │ +minor axis length. The major axis length describes the longer diameter │ │ │ │ │ +of the ellipse, while the minor axis length describes the shorter │ │ │ │ │ +diameter. Major and minor are orthogonal and both are specified in │ │ │ │ │ +surface\-local coordinates. The center of the ellipse is always at the │ │ │ │ │ +touchpoint location as reported by \fI\%WlTouch.down()\fP or │ │ │ │ │ +\fBWlTouch.move()\fP\&. │ │ │ │ │ +.sp │ │ │ │ │ +This event is only sent by the compositor if the touch device supports │ │ │ │ │ +shape reports. The client has to make reasonable assumptions about the │ │ │ │ │ +shape if it did not receive this event. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -\fBsibling\fP (\fI\%WlSurface\fP) \-\- the reference surface │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBid\fP (\fIArgumentType.Int\fP) \-\- the unique ID of this touch point │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBmajor\fP (\fIArgumentType.Fixed\fP) \-\- length of the major axis in surface\-local coordinates │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBminor\fP (\fIArgumentType.Fixed\fP) \-\- length of the minor axis in surface\-local coordinates │ │ │ │ │ +.UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B set_sync() -> \(aqNone\(aq │ │ │ │ │ +.B orientation(id: \(aqint\(aq, orientation: \(aqfloat\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 4 (attached to \fBResource\fP instance) │ │ │ │ │ +Event \-\- opcode 6 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Set sub\-surface to synchronized mode │ │ │ │ │ +Update orientation of touch point │ │ │ │ │ .sp │ │ │ │ │ -Change the commit behaviour of the sub\-surface to synchronized mode, │ │ │ │ │ -also described as the parent dependent mode. │ │ │ │ │ +Sent when a touchpoint has changed its orientation. │ │ │ │ │ .sp │ │ │ │ │ -In synchronized mode, \fI\%WlSurface.commit()\fP on a sub\-surface will │ │ │ │ │ -accumulate the committed state in a cache, but the state will not be │ │ │ │ │ -applied and hence will not change the compositor output. The cached │ │ │ │ │ -state is applied to the sub\-surface immediately after the parent │ │ │ │ │ -surface\(aqs state is applied. This ensures atomic updates of the parent │ │ │ │ │ -and all its synchronized sub\-surfaces. Applying the cached state will │ │ │ │ │ -invalidate the cache, so further parent surface commits do not │ │ │ │ │ -(re\-)apply old state. │ │ │ │ │ +This event does not occur on its own. It is sent before a │ │ │ │ │ +\fI\%WlTouch.frame()\fP event and carries the new shape information for │ │ │ │ │ +any previously reported, or new touch points of that frame. │ │ │ │ │ .sp │ │ │ │ │ -See \fI\%WlSubsurface\fP for the recursive effect of this mode. │ │ │ │ │ -.UNINDENT │ │ │ │ │ +Other events describing the touch point such as \fI\%WlTouch.down()\fP, │ │ │ │ │ +\fI\%WlTouch.motion()\fP or \fI\%WlTouch.shape()\fP may be sent within │ │ │ │ │ +the same \fI\%WlTouch.frame()\fP\&. A client should treat these events as │ │ │ │ │ +a single logical touch point update. The order of │ │ │ │ │ +\fI\%WlTouch.shape()\fP, \fI\%WlTouch.orientation()\fP and │ │ │ │ │ +\fI\%WlTouch.motion()\fP is not guaranteed. A \fI\%WlTouch.down()\fP │ │ │ │ │ +event is guaranteed to occur before the first │ │ │ │ │ +\fI\%WlTouch.orientation()\fP event for this touch ID but both events │ │ │ │ │ +may occur within the same \fI\%WlTouch.frame()\fP\&. │ │ │ │ │ +.sp │ │ │ │ │ +The orientation describes the clockwise angle of a touchpoint\(aqs major │ │ │ │ │ +axis to the positive surface y\-axis and is normalized to the \-180 to │ │ │ │ │ ++180 degree range. The granularity of orientation depends on the touch │ │ │ │ │ +device, some devices only support binary rotation values between 0 and │ │ │ │ │ +90 degrees. │ │ │ │ │ +.sp │ │ │ │ │ +This event is only sent by the compositor if the touch device supports │ │ │ │ │ +orientation reports. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B set_desync() -> \(aqNone\(aq │ │ │ │ │ +.B Parameters │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBid\fP (\fIArgumentType.Int\fP) \-\- the unique ID of this touch point │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBorientation\fP (\fIArgumentType.Fixed\fP) \-\- angle between major axis and positive surface y\-axis in degrees │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.SS WlCompositor │ │ │ │ │ +.INDENT 0.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B class pywayland.protocol.wayland.WlCompositor │ │ │ │ │ +The compositor singleton │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 5 (attached to \fBResource\fP instance) │ │ │ │ │ +A compositor. This object is a singleton global. The compositor is in │ │ │ │ │ +charge of combining the contents of multiple surfaces into one displayable │ │ │ │ │ +output. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B create_surface() -> \(aqProxy[WlSurface]\(aq │ │ │ │ │ .sp │ │ │ │ │ -Set sub\-surface to desynchronized mode │ │ │ │ │ +Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Change the commit behaviour of the sub\-surface to desynchronized mode, │ │ │ │ │ -also described as independent or freely running mode. │ │ │ │ │ +Create new surface │ │ │ │ │ .sp │ │ │ │ │ -In desynchronized mode, \fI\%WlSurface.commit()\fP on a sub\-surface will │ │ │ │ │ -apply the pending state directly, without caching, as happens normally │ │ │ │ │ -with a \fI\%WlSurface\fP\&. Calling │ │ │ │ │ -\fI\%WlSurface.commit()\fP on the parent surface │ │ │ │ │ -has no effect on the sub\-surface\(aqs │ │ │ │ │ -\fI\%WlSurface\fP state. This mode allows │ │ │ │ │ -a sub\-surface to be updated on its own. │ │ │ │ │ +Ask the compositor to create a new surface. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Returns │ │ │ │ │ +\fI\%WlSurface\fP \-\- the new surface │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B create_region() -> \(aqProxy[WlRegion]\(aq │ │ │ │ │ .sp │ │ │ │ │ -If cached state exists when \fI\%WlSurface.commit()\fP is called in │ │ │ │ │ -desynchronized mode, the pending state is added to the cached state, │ │ │ │ │ -and applied as a whole. This invalidates the cache. │ │ │ │ │ +Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Note: even if a sub\-surface is set to desynchronized, a parent sub\- │ │ │ │ │ -surface may override it to behave as synchronized. For details, see │ │ │ │ │ -\fI\%WlSubsurface\fP\&. │ │ │ │ │ +Create new region │ │ │ │ │ .sp │ │ │ │ │ -If a surface\(aqs parent surface behaves as desynchronized, then the │ │ │ │ │ -cached state is applied on set_desync. │ │ │ │ │ +Ask the compositor to create a new region. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Returns │ │ │ │ │ +\fI\%WlRegion\fP \-\- the new region │ │ │ │ │ +.UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .SS WlDataDevice │ │ │ │ │ .INDENT 0.0 │ │ │ │ │ .TP │ │ │ │ │ .B class pywayland.protocol.wayland.WlDataDevice │ │ │ │ │ Data transfer device │ │ │ │ │ @@ -1745,14 +1973,104 @@ │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ \fBid\fP (\fI\%WlDataOffer\fP or \fINone\fP) \-\- selection data_offer object │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ +.SS WlShmPool │ │ │ │ │ +.INDENT 0.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B class pywayland.protocol.wayland.WlShmPool │ │ │ │ │ +A shared memory pool │ │ │ │ │ +.sp │ │ │ │ │ +The \fI\%WlShmPool\fP object encapsulates a piece of memory shared between │ │ │ │ │ +the compositor and client. Through the \fI\%WlShmPool\fP object, the │ │ │ │ │ +client can allocate shared memory │ │ │ │ │ +\fI\%WlBuffer\fP objects. All objects created │ │ │ │ │ +through the same pool share the same underlying mapped memory. Reusing the │ │ │ │ │ +mapped memory avoids the setup/teardown overhead and is useful when │ │ │ │ │ +interactively resizing a surface or for many small buffers. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B create_buffer(offset: \(aqint\(aq, width: \(aqint\(aq, height: \(aqint\(aq, stride: \(aqint\(aq, format: \(aqint\(aq) -> \(aqProxy[WlBuffer]\(aq │ │ │ │ │ +.sp │ │ │ │ │ +Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ +.sp │ │ │ │ │ +Create a buffer from the pool │ │ │ │ │ +.sp │ │ │ │ │ +Create a \fI\%WlBuffer\fP object from the │ │ │ │ │ +pool. │ │ │ │ │ +.sp │ │ │ │ │ +The buffer is created offset bytes into the pool and has width and │ │ │ │ │ +height as specified. The stride argument specifies the number of bytes │ │ │ │ │ +from the beginning of one row to the beginning of the next. The format │ │ │ │ │ +is the pixel format of the buffer and must be one of those advertised │ │ │ │ │ +through the \fI\%WlShm.format()\fP event. │ │ │ │ │ +.sp │ │ │ │ │ +A buffer will keep a reference to the pool it was created from so it is │ │ │ │ │ +valid to destroy the pool immediately after creating a buffer from it. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Parameters │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBoffset\fP (\fIArgumentType.Int\fP) \-\- buffer byte offset within the pool │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBwidth\fP (\fIArgumentType.Int\fP) \-\- buffer width, in pixels │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBheight\fP (\fIArgumentType.Int\fP) \-\- buffer height, in pixels │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBstride\fP (\fIArgumentType.Int\fP) \-\- number of bytes from the beginning of one row to the beginning of │ │ │ │ │ +the next row │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBformat\fP (\fIArgumentType.Uint\fP) \-\- buffer pixel format │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.TP │ │ │ │ │ +.B Returns │ │ │ │ │ +\fI\%WlBuffer\fP \-\- buffer to create │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B destroy() -> \(aqNone\(aq │ │ │ │ │ +.sp │ │ │ │ │ +Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ +.sp │ │ │ │ │ +Destroy the pool │ │ │ │ │ +.sp │ │ │ │ │ +Destroy the shared memory pool. │ │ │ │ │ +.sp │ │ │ │ │ +The mmapped memory will be released when all buffers that have been │ │ │ │ │ +created from this pool are gone. │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B resize(size: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +.sp │ │ │ │ │ +Request \-\- opcode 2 (attached to \fBResource\fP instance) │ │ │ │ │ +.sp │ │ │ │ │ +Change the size of the pool mapping │ │ │ │ │ +.sp │ │ │ │ │ +This request will cause the server to remap the backing memory for the │ │ │ │ │ +pool from the file descriptor passed when the pool was created, but │ │ │ │ │ +using the new size. This request can only be used to make the pool │ │ │ │ │ +bigger. │ │ │ │ │ +.sp │ │ │ │ │ +This request only changes the amount of bytes that are mmapped by the │ │ │ │ │ +server and does not touch the file corresponding to the file descriptor │ │ │ │ │ +passed at creation time. It is the client\(aqs responsibility to ensure │ │ │ │ │ +that the file is at least as big as the new pool size. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Parameters │ │ │ │ │ +\fBsize\fP (\fIArgumentType.Int\fP) \-\- new size of the pool, in bytes │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ .SS WlShellSurface │ │ │ │ │ .INDENT 0.0 │ │ │ │ │ .TP │ │ │ │ │ .B class pywayland.protocol.wayland.WlShellSurface │ │ │ │ │ Desktop\-style metadata interface │ │ │ │ │ .sp │ │ │ │ │ An interface that may be implemented by a │ │ │ │ │ @@ -2102,1008 +2420,567 @@ │ │ │ │ │ Popup interaction is done │ │ │ │ │ .sp │ │ │ │ │ The popup_done event is sent out when a popup grab is broken, that is, │ │ │ │ │ when the user clicks a surface that doesn\(aqt belong to the client owning │ │ │ │ │ the popup surface. │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ -.SS WlSurface │ │ │ │ │ +.SS WlOutput │ │ │ │ │ .INDENT 0.0 │ │ │ │ │ .TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlSurface │ │ │ │ │ -An onscreen surface │ │ │ │ │ -.sp │ │ │ │ │ -A surface is a rectangular area that may be displayed on zero or more │ │ │ │ │ -outputs, and shown any number of times at the compositor\(aqs discretion. They │ │ │ │ │ -can present wl_buffers, receive user input, and define a local coordinate │ │ │ │ │ -system. │ │ │ │ │ -.sp │ │ │ │ │ -The size of a surface (and relative positions on it) is described in │ │ │ │ │ -surface\-local coordinates, which may differ from the buffer coordinates of │ │ │ │ │ -the pixel content, in case a buffer_transform or a buffer_scale is used. │ │ │ │ │ -.sp │ │ │ │ │ -A surface without a \(dqrole\(dq is fairly useless: a compositor does not know │ │ │ │ │ -where, when or how to present it. The role is the purpose of a │ │ │ │ │ -\fI\%WlSurface\fP\&. Examples of roles are a cursor for a pointer (as set by │ │ │ │ │ -\fI\%WlPointer.set_cursor()\fP), a drag icon │ │ │ │ │ -(\fI\%WlDataDevice.start_drag()\fP), a sub\-surface │ │ │ │ │ -(\fI\%WlSubcompositor.get_subsurface()\fP), and a window │ │ │ │ │ -as defined by a shell protocol (e.g. \fI\%WlShell.get_shell_surface()\fP). │ │ │ │ │ -.sp │ │ │ │ │ -A surface can have only one role at a time. Initially a \fI\%WlSurface\fP │ │ │ │ │ -does not have a role. Once a \fI\%WlSurface\fP is given a role, it is set │ │ │ │ │ -permanently for the whole lifetime of the \fI\%WlSurface\fP object. Giving │ │ │ │ │ -the current role again is allowed, unless explicitly forbidden by the │ │ │ │ │ -relevant interface specification. │ │ │ │ │ -.sp │ │ │ │ │ -Surface roles are given by requests in other interfaces such as │ │ │ │ │ -\fI\%WlPointer.set_cursor()\fP\&. The request should │ │ │ │ │ -explicitly mention that this request gives a role to a \fI\%WlSurface\fP\&. │ │ │ │ │ -Often, this request also creates a new protocol object that represents the │ │ │ │ │ -role and adds additional functionality to \fI\%WlSurface\fP\&. When a client │ │ │ │ │ -wants to destroy a \fI\%WlSurface\fP, they must destroy this role object │ │ │ │ │ -before the \fI\%WlSurface\fP, otherwise a defunct_role_object error is │ │ │ │ │ -sent. │ │ │ │ │ +.B class pywayland.protocol.wayland.WlOutput │ │ │ │ │ +Compositor output region │ │ │ │ │ .sp │ │ │ │ │ -Destroying the role object does not remove the role from the │ │ │ │ │ -\fI\%WlSurface\fP, but it may stop the \fI\%WlSurface\fP from \(dqplaying │ │ │ │ │ -the role\(dq. For instance, if a │ │ │ │ │ -\fI\%WlSubsurface\fP object is destroyed, the │ │ │ │ │ -\fI\%WlSurface\fP it was created for will be unmapped and forget its │ │ │ │ │ -position and z\-order. It is allowed to create a │ │ │ │ │ -\fI\%WlSubsurface\fP for the same │ │ │ │ │ -\fI\%WlSurface\fP again, but it is not allowed to use the │ │ │ │ │ -\fI\%WlSurface\fP as a cursor (cursor is a different role than sub\- │ │ │ │ │ -surface, and role switching is not allowed). │ │ │ │ │ +An output describes part of the compositor geometry. The compositor works │ │ │ │ │ +in the \(aqcompositor coordinate system\(aq and an output corresponds to a │ │ │ │ │ +rectangular area in that space that is actually visible. This typically │ │ │ │ │ +corresponds to a monitor that displays part of the compositor space. This │ │ │ │ │ +object is published as global during start up, or when a monitor is │ │ │ │ │ +hotplugged. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B destroy() -> \(aqNone\(aq │ │ │ │ │ +.B release() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Delete surface │ │ │ │ │ +Release the output object │ │ │ │ │ .sp │ │ │ │ │ -Deletes the surface and invalidates its object ID. │ │ │ │ │ +Using this request a client can tell the server that it is not going to │ │ │ │ │ +use the output object anymore. │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B attach(buffer: \(aqWlBuffer | None\(aq, x: \(aqint\(aq, y: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Set the surface contents │ │ │ │ │ -.sp │ │ │ │ │ -Set a buffer as the content of this surface. │ │ │ │ │ -.sp │ │ │ │ │ -The new size of the surface is calculated based on the buffer size │ │ │ │ │ -transformed by the inverse buffer_transform and the inverse │ │ │ │ │ -buffer_scale. This means that at commit time the supplied buffer size │ │ │ │ │ -must be an integer multiple of the buffer_scale. If that\(aqs not the │ │ │ │ │ -case, an invalid_size error is sent. │ │ │ │ │ -.sp │ │ │ │ │ -The x and y arguments specify the location of the new pending buffer\(aqs │ │ │ │ │ -upper left corner, relative to the current buffer\(aqs upper left corner, │ │ │ │ │ -in surface\-local coordinates. In other words, the x and y, combined │ │ │ │ │ -with the new surface size define in which directions the surface\(aqs size │ │ │ │ │ -changes. Setting anything other than 0 as x and y arguments is │ │ │ │ │ -discouraged, and should instead be replaced with using the separate │ │ │ │ │ -\fI\%WlSurface.offset()\fP request. │ │ │ │ │ -.sp │ │ │ │ │ -When the bound \fI\%WlSurface\fP version is 5 or higher, passing any │ │ │ │ │ -non\-zero x or y is a protocol violation, and will result in an │ │ │ │ │ -\(aqinvalid_offset\(aq error being raised. The x and y arguments are ignored │ │ │ │ │ -and do not change the pending state. To achieve equivalent semantics, │ │ │ │ │ -use \fI\%WlSurface.offset()\fP\&. │ │ │ │ │ +.B geometry(x: \(aqint\(aq, y: \(aqint\(aq, physical_width: \(aqint\(aq, physical_height: \(aqint\(aq, subpixel: \(aqint\(aq, make: \(aqstr\(aq, model: \(aqstr\(aq, transform: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Surface contents are double\-buffered state, see │ │ │ │ │ -\fI\%WlSurface.commit()\fP\&. │ │ │ │ │ +Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -The initial surface contents are void; there is no content. │ │ │ │ │ -\fI\%WlSurface.attach()\fP assigns the given │ │ │ │ │ -\fI\%WlBuffer\fP as the pending │ │ │ │ │ -\fI\%WlBuffer\fP\&. │ │ │ │ │ -\fI\%WlSurface.commit()\fP makes the pending │ │ │ │ │ -\fI\%WlBuffer\fP the new surface contents, │ │ │ │ │ -and the size of the surface becomes the size calculated from the │ │ │ │ │ -\fI\%WlBuffer\fP, as described above. │ │ │ │ │ -After commit, there is no pending buffer until the next attach. │ │ │ │ │ +Properties of the output │ │ │ │ │ .sp │ │ │ │ │ -Committing a pending \fI\%WlBuffer\fP │ │ │ │ │ -allows the compositor to read the pixels in the │ │ │ │ │ -\fI\%WlBuffer\fP\&. The compositor may │ │ │ │ │ -access the pixels at any time after the \fI\%WlSurface.commit()\fP │ │ │ │ │ -request. When the compositor will not access the pixels anymore, it │ │ │ │ │ -will send the \fI\%WlBuffer.release()\fP event. Only after │ │ │ │ │ -receiving \fI\%WlBuffer.release()\fP, the client may reuse │ │ │ │ │ -the \fI\%WlBuffer\fP\&. A │ │ │ │ │ -\fI\%WlBuffer\fP that has been attached │ │ │ │ │ -and then replaced by another attach instead of committed will not │ │ │ │ │ -receive a release event, and is not used by the compositor. │ │ │ │ │ +The geometry event describes geometric properties of the output. The │ │ │ │ │ +event is sent when binding to the output object and whenever any of the │ │ │ │ │ +properties change. │ │ │ │ │ .sp │ │ │ │ │ -If a pending \fI\%WlBuffer\fP has been │ │ │ │ │ -committed to more than one \fI\%WlSurface\fP, the delivery of │ │ │ │ │ -\fI\%WlBuffer.release()\fP events becomes │ │ │ │ │ -undefined. A well behaved client should not rely on │ │ │ │ │ -\fI\%WlBuffer.release()\fP events in this case. │ │ │ │ │ -Alternatively, a client could create multiple │ │ │ │ │ -\fI\%WlBuffer\fP objects from the same │ │ │ │ │ -backing storage or use wp_linux_buffer_release. │ │ │ │ │ +The physical size can be set to zero if it doesn\(aqt make sense for this │ │ │ │ │ +output (e.g. for projectors or virtual outputs). │ │ │ │ │ .sp │ │ │ │ │ -Destroying the \fI\%WlBuffer\fP after │ │ │ │ │ -\fI\%WlBuffer.release()\fP does not change the │ │ │ │ │ -surface contents. Destroying the │ │ │ │ │ -\fI\%WlBuffer\fP before │ │ │ │ │ -\fI\%WlBuffer.release()\fP is allowed as long as │ │ │ │ │ -the underlying buffer storage isn\(aqt re\-used (this can happen e.g. on │ │ │ │ │ -client process termination). However, if the client destroys the │ │ │ │ │ -\fI\%WlBuffer\fP before receiving the │ │ │ │ │ -\fI\%WlBuffer.release()\fP event and mutates the │ │ │ │ │ -underlying buffer storage, the surface contents become undefined │ │ │ │ │ -immediately. │ │ │ │ │ +The geometry event will be followed by a done event (starting from │ │ │ │ │ +version 2). │ │ │ │ │ .sp │ │ │ │ │ -If \fI\%WlSurface.attach()\fP is sent with a NULL │ │ │ │ │ -\fI\%WlBuffer\fP, the following │ │ │ │ │ -\fI\%WlSurface.commit()\fP will remove the surface content. │ │ │ │ │ +Clients should use \fI\%WlSurface.preferred_buffer_transform()\fP │ │ │ │ │ +instead of the transform advertised by this event to find the preferred │ │ │ │ │ +buffer transform to use for a surface. │ │ │ │ │ .sp │ │ │ │ │ -If a pending \fI\%WlBuffer\fP has been │ │ │ │ │ -destroyed, the result is not specified. Many compositors are known to │ │ │ │ │ -remove the surface content on the following \fI\%WlSurface.commit()\fP, │ │ │ │ │ -but this behaviour is not universal. Clients seeking to maximise │ │ │ │ │ -compatibility should not destroy pending buffers and should ensure that │ │ │ │ │ -they explicitly remove content from surfaces, even after destroying │ │ │ │ │ -buffers. │ │ │ │ │ +Note: \fI\%WlOutput\fP only advertises partial information about the │ │ │ │ │ +output position and identification. Some compositors, for instance │ │ │ │ │ +those not implementing a desktop\-style output layout or those exposing │ │ │ │ │ +virtual outputs, might fake this information. Instead of using x and y, │ │ │ │ │ +clients should use xdg_output.logical_position. Instead of using make │ │ │ │ │ +and model, clients should use name and description. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBbuffer\fP (\fI\%WlBuffer\fP or \fINone\fP) \-\- buffer of surface contents │ │ │ │ │ +\fBx\fP (\fIArgumentType.Int\fP) \-\- x position within the global compositor space │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBx\fP (\fIArgumentType.Int\fP) \-\- surface\-local x coordinate │ │ │ │ │ +\fBy\fP (\fIArgumentType.Int\fP) \-\- y position within the global compositor space │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBy\fP (\fIArgumentType.Int\fP) \-\- surface\-local y coordinate │ │ │ │ │ +\fBphysical_width\fP (\fIArgumentType.Int\fP) \-\- width in millimeters of the output │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBphysical_height\fP (\fIArgumentType.Int\fP) \-\- height in millimeters of the output │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBsubpixel\fP (\fIArgumentType.Int\fP) \-\- subpixel orientation of the output │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBmake\fP (\fIArgumentType.String\fP) \-\- textual description of the manufacturer │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBmodel\fP (\fIArgumentType.String\fP) \-\- textual description of the model │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBtransform\fP (\fIArgumentType.Int\fP) \-\- additional transformation applied to buffer contents during │ │ │ │ │ +presentation │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B damage(x: \(aqint\(aq, y: \(aqint\(aq, width: \(aqint\(aq, height: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B mode(flags: \(aqint\(aq, width: \(aqint\(aq, height: \(aqint\(aq, refresh: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 2 (attached to \fBResource\fP instance) │ │ │ │ │ +Event \-\- opcode 1 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Mark part of the surface damaged │ │ │ │ │ +Advertise available modes for the output │ │ │ │ │ .sp │ │ │ │ │ -This request is used to describe the regions where the pending buffer │ │ │ │ │ -is different from the current surface contents, and where the surface │ │ │ │ │ -therefore needs to be repainted. The compositor ignores the parts of │ │ │ │ │ -the damage that fall outside of the surface. │ │ │ │ │ +The mode event describes an available mode for the output. │ │ │ │ │ .sp │ │ │ │ │ -Damage is double\-buffered state, see \fI\%WlSurface.commit()\fP\&. │ │ │ │ │ +The event is sent when binding to the output object and there will │ │ │ │ │ +always be one mode, the current mode. The event is sent again if an │ │ │ │ │ +output changes mode, for the mode that is now current. In other words, │ │ │ │ │ +the current mode is always the last mode that was received with the │ │ │ │ │ +current flag set. │ │ │ │ │ .sp │ │ │ │ │ -The damage rectangle is specified in surface\-local coordinates, where x │ │ │ │ │ -and y specify the upper left corner of the damage rectangle. │ │ │ │ │ +Non\-current modes are deprecated. A compositor can decide to only │ │ │ │ │ +advertise the current mode and never send other modes. Clients should │ │ │ │ │ +not rely on non\-current modes. │ │ │ │ │ .sp │ │ │ │ │ -The initial value for pending damage is empty: no damage. │ │ │ │ │ -\fI\%WlSurface.damage()\fP adds pending damage: the new pending damage │ │ │ │ │ -is the union of old pending damage and the given rectangle. │ │ │ │ │ +The size of a mode is given in physical hardware units of the output │ │ │ │ │ +device. This is not necessarily the same as the output size in the │ │ │ │ │ +global compositor space. For instance, the output may be scaled, as │ │ │ │ │ +described in \fI\%WlOutput.scale()\fP, or transformed, as described in │ │ │ │ │ +\fBWlOutput.transform()\fP\&. Clients willing to retrieve the output │ │ │ │ │ +size in the global compositor space should use xdg_output.logical_size │ │ │ │ │ +instead. │ │ │ │ │ .sp │ │ │ │ │ -\fI\%WlSurface.commit()\fP assigns pending damage as the current │ │ │ │ │ -damage, and clears pending damage. The server will clear the current │ │ │ │ │ -damage as it repaints the surface. │ │ │ │ │ +The vertical refresh rate can be set to zero if it doesn\(aqt make sense │ │ │ │ │ +for this output (e.g. for virtual outputs). │ │ │ │ │ .sp │ │ │ │ │ -Note! New clients should not use this request. Instead damage can be │ │ │ │ │ -posted with \fI\%WlSurface.damage_buffer()\fP which uses buffer │ │ │ │ │ -coordinates instead of surface coordinates. │ │ │ │ │ +The mode event will be followed by a done event (starting from version │ │ │ │ │ +2). │ │ │ │ │ +.sp │ │ │ │ │ +Clients should not use the refresh rate to schedule frames. Instead, │ │ │ │ │ +they should use the \fI\%WlSurface.frame()\fP event or the │ │ │ │ │ +presentation\-time protocol. │ │ │ │ │ +.sp │ │ │ │ │ +Note: this information is not always meaningful for all outputs. Some │ │ │ │ │ +compositors, such as those exposing virtual outputs, might fake the │ │ │ │ │ +refresh rate or the size. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBx\fP (\fIArgumentType.Int\fP) \-\- surface\-local x coordinate │ │ │ │ │ +\fBflags\fP (\fIArgumentType.Uint\fP) \-\- bitfield of mode flags │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBy\fP (\fIArgumentType.Int\fP) \-\- surface\-local y coordinate │ │ │ │ │ +\fBwidth\fP (\fIArgumentType.Int\fP) \-\- width of the mode in hardware units │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBwidth\fP (\fIArgumentType.Int\fP) \-\- width of damage rectangle │ │ │ │ │ +\fBheight\fP (\fIArgumentType.Int\fP) \-\- height of the mode in hardware units │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBheight\fP (\fIArgumentType.Int\fP) \-\- height of damage rectangle │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ +\fBrefresh\fP (\fIArgumentType.Int\fP) \-\- vertical refresh rate in mHz │ │ │ │ │ .UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B frame() -> \(aqProxy[WlCallback]\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Request \-\- opcode 3 (attached to \fBResource\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Request a frame throttling hint │ │ │ │ │ -.sp │ │ │ │ │ -Request a notification when it is a good time to start drawing a new │ │ │ │ │ -frame, by creating a frame callback. This is useful for throttling │ │ │ │ │ -redrawing operations, and driving animations. │ │ │ │ │ -.sp │ │ │ │ │ -When a client is animating on a \fI\%WlSurface\fP, it can use the │ │ │ │ │ -\(aqframe\(aq request to get notified when it is a good time to draw and │ │ │ │ │ -commit the next frame of animation. If the client commits an update │ │ │ │ │ -earlier than that, it is likely that some updates will not make it to │ │ │ │ │ -the display, and the client is wasting resources by drawing too often. │ │ │ │ │ -.sp │ │ │ │ │ -The frame request will take effect on the next │ │ │ │ │ -\fI\%WlSurface.commit()\fP\&. The notification will only be posted for │ │ │ │ │ -one frame unless requested again. For a \fI\%WlSurface\fP, the │ │ │ │ │ -notifications are posted in the order the frame requests were │ │ │ │ │ -committed. │ │ │ │ │ -.sp │ │ │ │ │ -The server must send the notifications so that a client will not send │ │ │ │ │ -excessive updates, while still allowing the highest possible update │ │ │ │ │ -rate for clients that wait for the reply before drawing again. The │ │ │ │ │ -server should give some time for the client to draw and commit after │ │ │ │ │ -sending the frame callback events to let it hit the next output │ │ │ │ │ -refresh. │ │ │ │ │ -.sp │ │ │ │ │ -A server should avoid signaling the frame callbacks if the surface is │ │ │ │ │ -not visible in any way, e.g. the surface is off\-screen, or completely │ │ │ │ │ -obscured by other opaque surfaces. │ │ │ │ │ -.sp │ │ │ │ │ -The object returned by this request will be destroyed by the compositor │ │ │ │ │ -after the callback is fired and as such the client must not attempt to │ │ │ │ │ -use it after that point. │ │ │ │ │ -.sp │ │ │ │ │ -The callback_data passed in the callback is the current time, in │ │ │ │ │ -milliseconds, with an undefined base. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Returns │ │ │ │ │ -\fI\%WlCallback\fP \-\- callback object │ │ │ │ │ -for the frame request │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B set_opaque_region(region: \(aqWlRegion | None\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Request \-\- opcode 4 (attached to \fBResource\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Set opaque region │ │ │ │ │ -.sp │ │ │ │ │ -This request sets the region of the surface that contains opaque │ │ │ │ │ -content. │ │ │ │ │ -.sp │ │ │ │ │ -The opaque region is an optimization hint for the compositor that lets │ │ │ │ │ -it optimize the redrawing of content behind opaque regions. Setting an │ │ │ │ │ -opaque region is not required for correct behaviour, but marking │ │ │ │ │ -transparent content as opaque will result in repaint artifacts. │ │ │ │ │ -.sp │ │ │ │ │ -The opaque region is specified in surface\-local coordinates. │ │ │ │ │ -.sp │ │ │ │ │ -The compositor ignores the parts of the opaque region that fall outside │ │ │ │ │ -of the surface. │ │ │ │ │ +.B done() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Opaque region is double\-buffered state, see \fI\%WlSurface.commit()\fP\&. │ │ │ │ │ +Event \-\- opcode 2 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -\fI\%WlSurface.set_opaque_region()\fP changes the pending opaque │ │ │ │ │ -region. \fI\%WlSurface.commit()\fP copies the pending region to the │ │ │ │ │ -current region. Otherwise, the pending and current regions are never │ │ │ │ │ -changed. │ │ │ │ │ +Sent all information about output │ │ │ │ │ .sp │ │ │ │ │ -The initial value for an opaque region is empty. Setting the pending │ │ │ │ │ -opaque region has copy semantics, and the │ │ │ │ │ -\fI\%WlRegion\fP object can be destroyed │ │ │ │ │ -immediately. A NULL \fI\%WlRegion\fP │ │ │ │ │ -causes the pending opaque region to be set to empty. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -\fBregion\fP (\fI\%WlRegion\fP or \fINone\fP) \-\- opaque region of the surface │ │ │ │ │ -.UNINDENT │ │ │ │ │ +This event is sent after all other properties have been sent after │ │ │ │ │ +binding to the output object and after any other property changes done │ │ │ │ │ +after that. This allows changes to the output properties to be seen as │ │ │ │ │ +atomic, even if they happen via multiple events. │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B set_input_region(region: \(aqWlRegion | None\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Request \-\- opcode 5 (attached to \fBResource\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Set input region │ │ │ │ │ +.B scale(factor: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -This request sets the region of the surface that can receive pointer │ │ │ │ │ -and touch events. │ │ │ │ │ +Event \-\- opcode 3 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Input events happening outside of this region will try the next surface │ │ │ │ │ -in the server surface stack. The compositor ignores the parts of the │ │ │ │ │ -input region that fall outside of the surface. │ │ │ │ │ +Output scaling properties │ │ │ │ │ .sp │ │ │ │ │ -The input region is specified in surface\-local coordinates. │ │ │ │ │ +This event contains scaling geometry information that is not in the │ │ │ │ │ +geometry event. It may be sent after binding the output object or if │ │ │ │ │ +the output scale changes later. The compositor will emit a non\-zero, │ │ │ │ │ +positive value for scale. If it is not sent, the client should assume a │ │ │ │ │ +scale of 1. │ │ │ │ │ .sp │ │ │ │ │ -Input region is double\-buffered state, see \fI\%WlSurface.commit()\fP\&. │ │ │ │ │ +A scale larger than 1 means that the compositor will automatically │ │ │ │ │ +scale surface buffers by this amount when rendering. This is used for │ │ │ │ │ +very high resolution displays where applications rendering at the │ │ │ │ │ +native resolution would be too small to be legible. │ │ │ │ │ .sp │ │ │ │ │ -\fI\%WlSurface.set_input_region()\fP changes the pending input region. │ │ │ │ │ -\fI\%WlSurface.commit()\fP copies the pending region to the current │ │ │ │ │ -region. Otherwise the pending and current regions are never changed, │ │ │ │ │ -except cursor and icon surfaces are special cases, see │ │ │ │ │ -\fI\%WlPointer.set_cursor()\fP and │ │ │ │ │ -\fI\%WlDataDevice.start_drag()\fP\&. │ │ │ │ │ +Clients should use \fI\%WlSurface.preferred_buffer_scale()\fP instead │ │ │ │ │ +of this event to find the preferred buffer scale to use for a surface. │ │ │ │ │ .sp │ │ │ │ │ -The initial value for an input region is infinite. That means the whole │ │ │ │ │ -surface will accept input. Setting the pending input region has copy │ │ │ │ │ -semantics, and the \fI\%WlRegion\fP object │ │ │ │ │ -can be destroyed immediately. A NULL │ │ │ │ │ -\fI\%WlRegion\fP causes the input region │ │ │ │ │ -to be set to infinite. │ │ │ │ │ +The scale event will be followed by a done event. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -\fBregion\fP (\fI\%WlRegion\fP or \fINone\fP) \-\- input region of the surface │ │ │ │ │ -.UNINDENT │ │ │ │ │ +\fBfactor\fP (\fIArgumentType.Int\fP) \-\- scaling factor of output │ │ │ │ │ .UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B commit() -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Request \-\- opcode 6 (attached to \fBResource\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Commit pending surface state │ │ │ │ │ -.sp │ │ │ │ │ -Surface state (input, opaque, and damage regions, attached buffers, │ │ │ │ │ -etc.) is double\-buffered. Protocol requests modify the pending state, │ │ │ │ │ -as opposed to the active state in use by the compositor. │ │ │ │ │ -.sp │ │ │ │ │ -A commit request atomically creates a content update from the pending │ │ │ │ │ -state, even if the pending state has not been touched. The content │ │ │ │ │ -update is placed in a queue until it becomes active. After commit, the │ │ │ │ │ -new pending state is as documented for each related request. │ │ │ │ │ -.sp │ │ │ │ │ -When the content update is applied, the │ │ │ │ │ -\fI\%WlBuffer\fP is applied before all │ │ │ │ │ -other state. This means that all coordinates in double\-buffered state │ │ │ │ │ -are relative to the newly attached wl_buffers, except for │ │ │ │ │ -\fI\%WlSurface.attach()\fP itself. If there is no newly attached │ │ │ │ │ -\fI\%WlBuffer\fP, the coordinates are │ │ │ │ │ -relative to the previous content update. │ │ │ │ │ -.sp │ │ │ │ │ -All requests that need a commit to become effective are documented to │ │ │ │ │ -affect double\-buffered state. │ │ │ │ │ -.sp │ │ │ │ │ -Other interfaces may add further double\-buffered surface state. │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B set_buffer_transform(transform: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B name(name: \(aqstr\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 7 (attached to \fBResource\fP instance) │ │ │ │ │ +Event \-\- opcode 4 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Sets the buffer transformation │ │ │ │ │ +Name of this output │ │ │ │ │ .sp │ │ │ │ │ -This request sets the transformation that the client has already │ │ │ │ │ -applied to the content of the buffer. The accepted values for the │ │ │ │ │ -transform parameter are the values for \fBWlOutput.transform()\fP\&. │ │ │ │ │ +Many compositors will assign user\-friendly names to their outputs, show │ │ │ │ │ +them to the user, allow the user to refer to an output, etc. The client │ │ │ │ │ +may wish to know this name as well to offer the user similar behaviors. │ │ │ │ │ .sp │ │ │ │ │ -The compositor applies the inverse of this transformation whenever it │ │ │ │ │ -uses the buffer contents. │ │ │ │ │ +The name is a UTF\-8 string with no convention defined for its contents. │ │ │ │ │ +Each name is unique among all \fI\%WlOutput\fP globals. The name is │ │ │ │ │ +only guaranteed to be unique for the compositor instance. │ │ │ │ │ .sp │ │ │ │ │ -Buffer transform is double\-buffered state, see │ │ │ │ │ -\fI\%WlSurface.commit()\fP\&. │ │ │ │ │ +The same output name is used for all clients for a given │ │ │ │ │ +\fI\%WlOutput\fP global. Thus, the name can be shared across processes │ │ │ │ │ +to refer to a specific \fI\%WlOutput\fP global. │ │ │ │ │ .sp │ │ │ │ │ -A newly created surface has its buffer transformation set to normal. │ │ │ │ │ +The name is not guaranteed to be persistent across sessions, thus │ │ │ │ │ +cannot be used to reliably identify an output in e.g. configuration │ │ │ │ │ +files. │ │ │ │ │ .sp │ │ │ │ │ -\fI\%WlSurface.set_buffer_transform()\fP changes the pending buffer │ │ │ │ │ -transformation. \fI\%WlSurface.commit()\fP copies the pending buffer │ │ │ │ │ -transformation to the current one. Otherwise, the pending and current │ │ │ │ │ -values are never changed. │ │ │ │ │ +Examples of names include \(aqHDMI\-A\-1\(aq, \(aqWL\-1\(aq, \(aqX11\-1\(aq, etc. However, do │ │ │ │ │ +not assume that the name is a reflection of an underlying DRM │ │ │ │ │ +connector, X11 connection, etc. │ │ │ │ │ .sp │ │ │ │ │ -The purpose of this request is to allow clients to render content │ │ │ │ │ -according to the output transform, thus permitting the compositor to │ │ │ │ │ -use certain optimizations even if the display is rotated. Using │ │ │ │ │ -hardware overlays and scanning out a client buffer for fullscreen │ │ │ │ │ -surfaces are examples of such optimizations. Those optimizations are │ │ │ │ │ -highly dependent on the compositor implementation, so the use of this │ │ │ │ │ -request should be considered on a case\-by\-case basis. │ │ │ │ │ +The name event is sent after binding the output object. This event is │ │ │ │ │ +only sent once per output object, and the name does not change over the │ │ │ │ │ +lifetime of the \fI\%WlOutput\fP global. │ │ │ │ │ .sp │ │ │ │ │ -Note that if the transform value includes 90 or 270 degree rotation, │ │ │ │ │ -the width of the buffer will become the surface height and the height │ │ │ │ │ -of the buffer will become the surface width. │ │ │ │ │ +Compositors may re\-use the same output name if the \fI\%WlOutput\fP │ │ │ │ │ +global is destroyed and re\-created later. Compositors should avoid re\- │ │ │ │ │ +using the same name if possible. │ │ │ │ │ .sp │ │ │ │ │ -If transform is not one of the values from the │ │ │ │ │ -\fBWlOutput.transform()\fP enum the │ │ │ │ │ -invalid_transform protocol error is raised. │ │ │ │ │ +The name event will be followed by a done event. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -\fBtransform\fP (\fIArgumentType.Int\fP) \-\- transform for interpreting buffer contents │ │ │ │ │ +\fBname\fP (\fIArgumentType.String\fP) \-\- output name │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B set_buffer_scale(scale: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Request \-\- opcode 8 (attached to \fBResource\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Sets the buffer scaling factor │ │ │ │ │ -.sp │ │ │ │ │ -This request sets an optional scaling factor on how the compositor │ │ │ │ │ -interprets the contents of the buffer attached to the window. │ │ │ │ │ +.B description(description: \(aqstr\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Buffer scale is double\-buffered state, see \fI\%WlSurface.commit()\fP\&. │ │ │ │ │ +Event \-\- opcode 5 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -A newly created surface has its buffer scale set to 1. │ │ │ │ │ +Human\-readable description of this output │ │ │ │ │ .sp │ │ │ │ │ -\fI\%WlSurface.set_buffer_scale()\fP changes the pending buffer scale. │ │ │ │ │ -\fI\%WlSurface.commit()\fP copies the pending buffer scale to the │ │ │ │ │ -current one. Otherwise, the pending and current values are never │ │ │ │ │ -changed. │ │ │ │ │ +Many compositors can produce human\-readable descriptions of their │ │ │ │ │ +outputs. The client may wish to know this description as well, e.g. for │ │ │ │ │ +output selection purposes. │ │ │ │ │ .sp │ │ │ │ │ -The purpose of this request is to allow clients to supply higher │ │ │ │ │ -resolution buffer data for use on high resolution outputs. It is │ │ │ │ │ -intended that you pick the same buffer scale as the scale of the output │ │ │ │ │ -that the surface is displayed on. This means the compositor can avoid │ │ │ │ │ -scaling when rendering the surface on that output. │ │ │ │ │ +The description is a UTF\-8 string with no convention defined for its │ │ │ │ │ +contents. The description is not guaranteed to be unique among all │ │ │ │ │ +\fI\%WlOutput\fP globals. Examples might include \(aqFoocorp 11\(dq Display\(aq │ │ │ │ │ +or \(aqVirtual X11 output via :1\(aq. │ │ │ │ │ .sp │ │ │ │ │ -Note that if the scale is larger than 1, then you have to attach a │ │ │ │ │ -buffer that is larger (by a factor of scale in each dimension) than the │ │ │ │ │ -desired surface size. │ │ │ │ │ +The description event is sent after binding the output object and │ │ │ │ │ +whenever the description changes. The description is optional, and may │ │ │ │ │ +not be sent at all. │ │ │ │ │ .sp │ │ │ │ │ -If scale is not greater than 0 the invalid_scale protocol error is │ │ │ │ │ -raised. │ │ │ │ │ +The description event will be followed by a done event. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -\fBscale\fP (\fIArgumentType.Int\fP) \-\- scale for interpreting buffer contents │ │ │ │ │ +\fBdescription\fP (\fIArgumentType.String\fP) \-\- output description │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.SS WlRegistry │ │ │ │ │ +.INDENT 0.0 │ │ │ │ │ .TP │ │ │ │ │ -.B damage_buffer(x: \(aqint\(aq, y: \(aqint\(aq, width: \(aqint\(aq, height: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Request \-\- opcode 9 (attached to \fBResource\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Mark part of the surface damaged using buffer coordinates │ │ │ │ │ -.sp │ │ │ │ │ -This request is used to describe the regions where the pending buffer │ │ │ │ │ -is different from the current surface contents, and where the surface │ │ │ │ │ -therefore needs to be repainted. The compositor ignores the parts of │ │ │ │ │ -the damage that fall outside of the surface. │ │ │ │ │ +.B class pywayland.protocol.wayland.WlRegistry │ │ │ │ │ +Global registry object │ │ │ │ │ .sp │ │ │ │ │ -Damage is double\-buffered state, see \fI\%WlSurface.commit()\fP\&. │ │ │ │ │ +The singleton global registry object. The server has a number of global │ │ │ │ │ +objects that are available to all clients. These objects typically │ │ │ │ │ +represent an actual object in the server (for example, an input device) or │ │ │ │ │ +they are singleton objects that provide extension functionality. │ │ │ │ │ .sp │ │ │ │ │ -The damage rectangle is specified in buffer coordinates, where x and y │ │ │ │ │ -specify the upper left corner of the damage rectangle. │ │ │ │ │ +When a client creates a registry object, the registry object will emit a │ │ │ │ │ +global event for each global currently in the registry. Globals come and │ │ │ │ │ +go as a result of device or monitor hotplugs, reconfiguration or other │ │ │ │ │ +events, and the registry will send out global and global_remove events to │ │ │ │ │ +keep the client up to date with the changes. To mark the end of the │ │ │ │ │ +initial burst of events, the client can use the \fI\%WlDisplay.sync()\fP request immediately after │ │ │ │ │ +calling \fI\%WlDisplay.get_registry()\fP\&. │ │ │ │ │ .sp │ │ │ │ │ -The initial value for pending damage is empty: no damage. │ │ │ │ │ -\fI\%WlSurface.damage_buffer()\fP adds pending damage: the new pending │ │ │ │ │ -damage is the union of old pending damage and the given rectangle. │ │ │ │ │ +A client can bind to a global object by using the bind request. This │ │ │ │ │ +creates a client\-side handle that lets the object emit events to the client │ │ │ │ │ +and lets the client invoke requests on the object. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B bind(name: \(aqint\(aq, interface: \(aqtype[T]\(aq, version: \(aqint\(aq) -> \(aqProxy[T]\(aq │ │ │ │ │ .sp │ │ │ │ │ -\fI\%WlSurface.commit()\fP assigns pending damage as the current │ │ │ │ │ -damage, and clears pending damage. The server will clear the current │ │ │ │ │ -damage as it repaints the surface. │ │ │ │ │ +Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -This request differs from \fI\%WlSurface.damage()\fP in only one way \- │ │ │ │ │ -it takes damage in buffer coordinates instead of surface\-local │ │ │ │ │ -coordinates. While this generally is more intuitive than surface │ │ │ │ │ -coordinates, it is especially desirable when using wp_viewport or when │ │ │ │ │ -a drawing library (like EGL) is unaware of buffer scale and buffer │ │ │ │ │ -transform. │ │ │ │ │ +Bind an object to the display │ │ │ │ │ .sp │ │ │ │ │ -Note: Because buffer transformation changes and damage requests may be │ │ │ │ │ -interleaved in the protocol stream, it is impossible to determine the │ │ │ │ │ -actual mapping between surface and buffer damage until │ │ │ │ │ -\fI\%WlSurface.commit()\fP time. Therefore, compositors wishing to take │ │ │ │ │ -both kinds of damage into account will have to accumulate damage from │ │ │ │ │ -the two requests separately and only transform from one to the other │ │ │ │ │ -after receiving the \fI\%WlSurface.commit()\fP\&. │ │ │ │ │ +Binds a new, client\-created object to the server using the specified │ │ │ │ │ +name as the identifier. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBx\fP (\fIArgumentType.Int\fP) \-\- buffer\-local x coordinate │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBy\fP (\fIArgumentType.Int\fP) \-\- buffer\-local y coordinate │ │ │ │ │ +\fBname\fP (\fIArgumentType.Uint\fP) \-\- unique numeric name of the object │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBwidth\fP (\fIArgumentType.Int\fP) \-\- width of damage rectangle │ │ │ │ │ +\fBinterface\fP (\fIstring\fP) \-\- Interface name │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBheight\fP (\fIArgumentType.Int\fP) \-\- height of damage rectangle │ │ │ │ │ +\fBversion\fP (\fIint\fP) \-\- Interface version │ │ │ │ │ .UNINDENT │ │ │ │ │ +.TP │ │ │ │ │ +.B Returns │ │ │ │ │ +\fBpywayland.client.proxy.Proxy\fP of specified Interface \-\- │ │ │ │ │ +bounded object │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B offset(x: \(aqint\(aq, y: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Request \-\- opcode 10 (attached to \fBResource\fP instance) │ │ │ │ │ +.B global_(name: \(aqint\(aq, interface: \(aqstr\(aq, version: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Set the surface contents offset │ │ │ │ │ +Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -The x and y arguments specify the location of the new pending buffer\(aqs │ │ │ │ │ -upper left corner, relative to the current buffer\(aqs upper left corner, │ │ │ │ │ -in surface\-local coordinates. In other words, the x and y, combined │ │ │ │ │ -with the new surface size define in which directions the surface\(aqs size │ │ │ │ │ -changes. │ │ │ │ │ +Announce global object │ │ │ │ │ .sp │ │ │ │ │ -Surface location offset is double\-buffered state, see │ │ │ │ │ -\fI\%WlSurface.commit()\fP\&. │ │ │ │ │ +Notify the client of global objects. │ │ │ │ │ .sp │ │ │ │ │ -This request is semantically equivalent to and the replaces the x and y │ │ │ │ │ -arguments in the \fI\%WlSurface.attach()\fP request in │ │ │ │ │ -\fI\%WlSurface\fP versions prior to 5. See \fI\%WlSurface.attach()\fP │ │ │ │ │ -for details. │ │ │ │ │ +The event notifies the client that a global object with the given name │ │ │ │ │ +is now available, and it implements the given version of the given │ │ │ │ │ +interface. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBx\fP (\fIArgumentType.Int\fP) \-\- surface\-local x coordinate │ │ │ │ │ +\fBname\fP (\fIArgumentType.Uint\fP) \-\- numeric name of the global object │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBy\fP (\fIArgumentType.Int\fP) \-\- surface\-local y coordinate │ │ │ │ │ +\fBinterface\fP (\fIArgumentType.String\fP) \-\- interface implemented by the object │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBversion\fP (\fIArgumentType.Uint\fP) \-\- interface version │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B enter(output: \(aqWlOutput\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B global_remove(name: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ +Event \-\- opcode 1 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Surface enters an output │ │ │ │ │ +Announce removal of global object │ │ │ │ │ .sp │ │ │ │ │ -This is emitted whenever a surface\(aqs creation, movement, or resizing │ │ │ │ │ -results in some part of it being within the scanout region of an │ │ │ │ │ -output. │ │ │ │ │ +Notify the client of removed global objects. │ │ │ │ │ .sp │ │ │ │ │ -Note that a surface may be overlapping with zero or more outputs. │ │ │ │ │ +This event notifies the client that the global identified by name is no │ │ │ │ │ +longer available. If the client bound to the global using the bind │ │ │ │ │ +request, the client should now destroy that object. │ │ │ │ │ +.sp │ │ │ │ │ +The object remains valid and requests to the object will be ignored │ │ │ │ │ +until the client destroys it, to avoid races between the global going │ │ │ │ │ +away and a client sending a request to it. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -\fBoutput\fP (\fI\%WlOutput\fP) \-\- output entered by the surface │ │ │ │ │ +\fBname\fP (\fIArgumentType.Uint\fP) \-\- numeric name of the global object │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.SS WlDataSource │ │ │ │ │ +.INDENT 0.0 │ │ │ │ │ .TP │ │ │ │ │ -.B leave(output: \(aqWlOutput\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B class pywayland.protocol.wayland.WlDataSource │ │ │ │ │ +Offer to transfer data │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 1 (attached to \fBProxy\fP instance) │ │ │ │ │ +The \fI\%WlDataSource\fP object is the source side of a │ │ │ │ │ +\fI\%WlDataOffer\fP\&. It is created by the │ │ │ │ │ +source client in a data transfer and provides a way to describe the offered │ │ │ │ │ +data and a way to respond to requests to transfer the data. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B offer(mime_type: \(aqstr\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Surface leaves an output │ │ │ │ │ +Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -This is emitted whenever a surface\(aqs creation, movement, or resizing │ │ │ │ │ -results in it no longer having any part of it within the scanout region │ │ │ │ │ -of an output. │ │ │ │ │ +Add an offered mime type │ │ │ │ │ .sp │ │ │ │ │ -Clients should not use the number of outputs the surface is on for │ │ │ │ │ -frame throttling purposes. The surface might be hidden even if no leave │ │ │ │ │ -event has been sent, and the compositor might expect new surface │ │ │ │ │ -content updates even if no enter event has been sent. The frame event │ │ │ │ │ -should be used instead. │ │ │ │ │ +This request adds a mime type to the set of mime types advertised to │ │ │ │ │ +targets. Can be called several times to offer multiple types. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -\fBoutput\fP (\fI\%WlOutput\fP) \-\- output left by the surface │ │ │ │ │ +\fBmime_type\fP (\fIArgumentType.String\fP) \-\- mime type offered by the data source │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B preferred_buffer_scale(factor: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Event \-\- opcode 2 (attached to \fBProxy\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Preferred buffer scale for the surface │ │ │ │ │ -.sp │ │ │ │ │ -This event indicates the preferred buffer scale for this surface. It is │ │ │ │ │ -sent whenever the compositor\(aqs preference changes. │ │ │ │ │ +.B destroy() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Before receiving this event the preferred buffer scale for this surface │ │ │ │ │ -is 1. │ │ │ │ │ +Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -It is intended that scaling aware clients use this event to scale their │ │ │ │ │ -content and use \fI\%WlSurface.set_buffer_scale()\fP to indicate the │ │ │ │ │ -scale they have rendered with. This allows clients to supply a higher │ │ │ │ │ -detail buffer. │ │ │ │ │ +Destroy the data source │ │ │ │ │ .sp │ │ │ │ │ -The compositor shall emit a scale value greater than 0. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -\fBfactor\fP (\fIArgumentType.Int\fP) \-\- preferred scaling factor │ │ │ │ │ -.UNINDENT │ │ │ │ │ +Destroy the data source. │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B preferred_buffer_transform(transform: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B set_actions(dnd_actions: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 3 (attached to \fBProxy\fP instance) │ │ │ │ │ +Request \-\- opcode 2 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Preferred buffer transform for the surface │ │ │ │ │ +Set the available drag\-and\-drop actions │ │ │ │ │ .sp │ │ │ │ │ -This event indicates the preferred buffer transform for this surface. │ │ │ │ │ -It is sent whenever the compositor\(aqs preference changes. │ │ │ │ │ +Sets the actions that the source side client supports for this │ │ │ │ │ +operation. This request may trigger \fI\%WlDataSource.action()\fP and │ │ │ │ │ +\fI\%WlDataOffer.action()\fP events if the │ │ │ │ │ +compositor needs to change the selected action. │ │ │ │ │ .sp │ │ │ │ │ -Before receiving this event the preferred buffer transform for this │ │ │ │ │ -surface is normal. │ │ │ │ │ +The dnd_actions argument must contain only values expressed in the │ │ │ │ │ +\fBWlDataDeviceManager.dnd_actions()\fP enum, │ │ │ │ │ +otherwise it will result in a protocol error. │ │ │ │ │ .sp │ │ │ │ │ -Applying this transformation to the surface buffer contents and using │ │ │ │ │ -\fI\%WlSurface.set_buffer_transform()\fP might allow the compositor to │ │ │ │ │ -use the surface buffer more efficiently. │ │ │ │ │ +This request must be made once only, and can only be made on sources │ │ │ │ │ +used in drag\-and\-drop, so it must be performed before │ │ │ │ │ +\fI\%WlDataDevice.start_drag()\fP\&. Attempting to │ │ │ │ │ +use the source other than for drag\-and\-drop will raise a protocol │ │ │ │ │ +error. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -\fBtransform\fP (\fIArgumentType.Uint\fP) \-\- preferred transform │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ +\fBdnd_actions\fP (\fIArgumentType.Uint\fP) \-\- actions supported by the data source │ │ │ │ │ .UNINDENT │ │ │ │ │ -.SS WlTouch │ │ │ │ │ -.INDENT 0.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlTouch │ │ │ │ │ -Touchscreen input device │ │ │ │ │ -.sp │ │ │ │ │ -The \fI\%WlTouch\fP interface represents a touchscreen associated with a │ │ │ │ │ -seat. │ │ │ │ │ -.sp │ │ │ │ │ -Touch interactions can consist of one or more contacts. For each contact, a │ │ │ │ │ -series of events is generated, starting with a down event, followed by zero │ │ │ │ │ -or more motion events, and ending with an up event. Events relating to the │ │ │ │ │ -same contact point can be identified by the ID of the sequence. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B release() -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Release the touch object │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B down(serial: \(aqint\(aq, time: \(aqint\(aq, surface: \(aqWlSurface\(aq, id: \(aqint\(aq, x: \(aqfloat\(aq, y: \(aqfloat\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B target(mime_type: \(aqstr | None\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Touch down event and beginning of a touch sequence │ │ │ │ │ +A target accepts an offered mime type │ │ │ │ │ .sp │ │ │ │ │ -A new touch point has appeared on the surface. This touch point is │ │ │ │ │ -assigned a unique ID. Future events from this touch point reference │ │ │ │ │ -this ID. The ID ceases to be valid after a touch up event and may be │ │ │ │ │ -reused in the future. │ │ │ │ │ +Sent when a target accepts pointer_focus or motion events. If a target │ │ │ │ │ +does not accept any of the offered types, type is NULL. │ │ │ │ │ +.sp │ │ │ │ │ +Used for feedback during drag\-and\-drop. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBserial\fP (\fIArgumentType.Uint\fP) \-\- serial number of the touch down event │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBtime\fP (\fIArgumentType.Uint\fP) \-\- timestamp with millisecond granularity │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBsurface\fP (\fI\%WlSurface\fP) \-\- surface touched │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBid\fP (\fIArgumentType.Int\fP) \-\- the unique ID of this touch point │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBx\fP (\fIArgumentType.Fixed\fP) \-\- surface\-local x coordinate │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBy\fP (\fIArgumentType.Fixed\fP) \-\- surface\-local y coordinate │ │ │ │ │ -.UNINDENT │ │ │ │ │ +\fBmime_type\fP (\fIArgumentType.String\fP or \fINone\fP) \-\- mime type accepted by the target │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B up(serial: \(aqint\(aq, time: \(aqint\(aq, id: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B send(mime_type: \(aqstr\(aq, fd: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ Event \-\- opcode 1 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -End of a touch event sequence │ │ │ │ │ +Send the data │ │ │ │ │ .sp │ │ │ │ │ -The touch point has disappeared. No further events will be sent for │ │ │ │ │ -this touch point and the touch point\(aqs ID is released and may be reused │ │ │ │ │ -in a future touch down event. │ │ │ │ │ +Request for data from the client. Send the data as the specified mime │ │ │ │ │ +type over the passed file descriptor, then close it. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBserial\fP (\fIArgumentType.Uint\fP) \-\- serial number of the touch up event │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBtime\fP (\fIArgumentType.Uint\fP) \-\- timestamp with millisecond granularity │ │ │ │ │ +\fBmime_type\fP (\fIArgumentType.String\fP) \-\- mime type for the data │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBid\fP (\fIArgumentType.Int\fP) \-\- the unique ID of this touch point │ │ │ │ │ +\fBfd\fP (\fIArgumentType.FileDescriptor\fP) \-\- file descriptor for the data │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B motion(time: \(aqint\(aq, id: \(aqint\(aq, x: \(aqfloat\(aq, y: \(aqfloat\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B cancelled() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ Event \-\- opcode 2 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Update of touch point coordinates │ │ │ │ │ +Selection was cancelled │ │ │ │ │ .sp │ │ │ │ │ -A touch point has changed coordinates. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Parameters │ │ │ │ │ +This data source is no longer valid. There are several reasons why this │ │ │ │ │ +could happen: │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBtime\fP (\fIArgumentType.Uint\fP) \-\- timestamp with millisecond granularity │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBid\fP (\fIArgumentType.Int\fP) \-\- the unique ID of this touch point │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBx\fP (\fIArgumentType.Fixed\fP) \-\- surface\-local x coordinate │ │ │ │ │ +The data source has been replaced by another data source. │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBy\fP (\fIArgumentType.Fixed\fP) \-\- surface\-local y coordinate │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B frame() -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Event \-\- opcode 3 (attached to \fBProxy\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -End of touch frame event │ │ │ │ │ -.sp │ │ │ │ │ -Indicates the end of a set of events that logically belong together. A │ │ │ │ │ -client is expected to accumulate the data in all events within the │ │ │ │ │ -frame before proceeding. │ │ │ │ │ -.sp │ │ │ │ │ -A \fI\%WlTouch.frame()\fP terminates at least one event but otherwise │ │ │ │ │ -no guarantee is provided about the set of events within a frame. A │ │ │ │ │ -client must assume that any state not updated in a frame is unchanged │ │ │ │ │ -from the previously known state. │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B cancel() -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Event \-\- opcode 4 (attached to \fBProxy\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Touch session cancelled │ │ │ │ │ -.sp │ │ │ │ │ -Sent if the compositor decides the touch stream is a global gesture. No │ │ │ │ │ -further events are sent to the clients from that particular gesture. │ │ │ │ │ -Touch cancellation applies to all touch points currently active on this │ │ │ │ │ -client\(aqs surface. The client is responsible for finalizing the touch │ │ │ │ │ -points, future touch points on this surface may reuse the touch point │ │ │ │ │ -ID. │ │ │ │ │ -.sp │ │ │ │ │ -No frame event is required after the cancel event. │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B shape(id: \(aqint\(aq, major: \(aqfloat\(aq, minor: \(aqfloat\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Event \-\- opcode 5 (attached to \fBProxy\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Update shape of touch point │ │ │ │ │ -.sp │ │ │ │ │ -Sent when a touchpoint has changed its shape. │ │ │ │ │ -.sp │ │ │ │ │ -This event does not occur on its own. It is sent before a │ │ │ │ │ -\fI\%WlTouch.frame()\fP event and carries the new shape information for │ │ │ │ │ -any previously reported, or new touch points of that frame. │ │ │ │ │ -.sp │ │ │ │ │ -Other events describing the touch point such as \fI\%WlTouch.down()\fP, │ │ │ │ │ -\fI\%WlTouch.motion()\fP or \fI\%WlTouch.orientation()\fP may be sent │ │ │ │ │ -within the same \fI\%WlTouch.frame()\fP\&. A client should treat these │ │ │ │ │ -events as a single logical touch point update. The order of │ │ │ │ │ -\fI\%WlTouch.shape()\fP, \fI\%WlTouch.orientation()\fP and │ │ │ │ │ -\fI\%WlTouch.motion()\fP is not guaranteed. A \fI\%WlTouch.down()\fP │ │ │ │ │ -event is guaranteed to occur before the first \fI\%WlTouch.shape()\fP │ │ │ │ │ -event for this touch ID but both events may occur within the same │ │ │ │ │ -\fI\%WlTouch.frame()\fP\&. │ │ │ │ │ -.sp │ │ │ │ │ -A touchpoint shape is approximated by an ellipse through the major and │ │ │ │ │ -minor axis length. The major axis length describes the longer diameter │ │ │ │ │ -of the ellipse, while the minor axis length describes the shorter │ │ │ │ │ -diameter. Major and minor are orthogonal and both are specified in │ │ │ │ │ -surface\-local coordinates. The center of the ellipse is always at the │ │ │ │ │ -touchpoint location as reported by \fI\%WlTouch.down()\fP or │ │ │ │ │ -\fBWlTouch.move()\fP\&. │ │ │ │ │ -.sp │ │ │ │ │ -This event is only sent by the compositor if the touch device supports │ │ │ │ │ -shape reports. The client has to make reasonable assumptions about the │ │ │ │ │ -shape if it did not receive this event. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ +The drag\-and\-drop operation was performed, but the drop destination │ │ │ │ │ +did not accept any of the mime types offered through │ │ │ │ │ +\fI\%WlDataSource.target()\fP\&. │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBid\fP (\fIArgumentType.Int\fP) \-\- the unique ID of this touch point │ │ │ │ │ +The drag\-and\-drop operation was performed, but the drop destination │ │ │ │ │ +did not select any of the actions present in the mask offered through │ │ │ │ │ +\fI\%WlDataSource.action()\fP\&. │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBmajor\fP (\fIArgumentType.Fixed\fP) \-\- length of the major axis in surface\-local coordinates │ │ │ │ │ +The drag\-and\-drop operation was performed but didn\(aqt happen over a │ │ │ │ │ +surface. │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBminor\fP (\fIArgumentType.Fixed\fP) \-\- length of the minor axis in surface\-local coordinates │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ +The compositor cancelled the drag\-and\-drop operation (e.g. compositor │ │ │ │ │ +dependent timeouts to avoid stale drag\-and\-drop transfers). │ │ │ │ │ .UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B orientation(id: \(aqint\(aq, orientation: \(aqfloat\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Event \-\- opcode 6 (attached to \fBProxy\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Update orientation of touch point │ │ │ │ │ .sp │ │ │ │ │ -Sent when a touchpoint has changed its orientation. │ │ │ │ │ -.sp │ │ │ │ │ -This event does not occur on its own. It is sent before a │ │ │ │ │ -\fI\%WlTouch.frame()\fP event and carries the new shape information for │ │ │ │ │ -any previously reported, or new touch points of that frame. │ │ │ │ │ -.sp │ │ │ │ │ -Other events describing the touch point such as \fI\%WlTouch.down()\fP, │ │ │ │ │ -\fI\%WlTouch.motion()\fP or \fI\%WlTouch.shape()\fP may be sent within │ │ │ │ │ -the same \fI\%WlTouch.frame()\fP\&. A client should treat these events as │ │ │ │ │ -a single logical touch point update. The order of │ │ │ │ │ -\fI\%WlTouch.shape()\fP, \fI\%WlTouch.orientation()\fP and │ │ │ │ │ -\fI\%WlTouch.motion()\fP is not guaranteed. A \fI\%WlTouch.down()\fP │ │ │ │ │ -event is guaranteed to occur before the first │ │ │ │ │ -\fI\%WlTouch.orientation()\fP event for this touch ID but both events │ │ │ │ │ -may occur within the same \fI\%WlTouch.frame()\fP\&. │ │ │ │ │ -.sp │ │ │ │ │ -The orientation describes the clockwise angle of a touchpoint\(aqs major │ │ │ │ │ -axis to the positive surface y\-axis and is normalized to the \-180 to │ │ │ │ │ -+180 degree range. The granularity of orientation depends on the touch │ │ │ │ │ -device, some devices only support binary rotation values between 0 and │ │ │ │ │ -90 degrees. │ │ │ │ │ +The client should clean up and destroy this data source. │ │ │ │ │ .sp │ │ │ │ │ -This event is only sent by the compositor if the touch device supports │ │ │ │ │ -orientation reports. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBid\fP (\fIArgumentType.Int\fP) \-\- the unique ID of this touch point │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBorientation\fP (\fIArgumentType.Fixed\fP) \-\- angle between major axis and positive surface y\-axis in degrees │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ +For objects of version 2 or older, \fI\%WlDataSource.cancelled()\fP │ │ │ │ │ +will only be emitted if the data source was replaced by another data │ │ │ │ │ +source. │ │ │ │ │ .UNINDENT │ │ │ │ │ -.SS WlRegion │ │ │ │ │ -.INDENT 0.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlRegion │ │ │ │ │ -Region interface │ │ │ │ │ -.sp │ │ │ │ │ -A region object describes an area. │ │ │ │ │ -.sp │ │ │ │ │ -Region objects are used to describe the opaque and input regions of a │ │ │ │ │ -surface. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B destroy() -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ +.B dnd_drop_performed() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Destroy region │ │ │ │ │ +Event \-\- opcode 3 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Destroy the region. This will invalidate the object ID. │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B add(x: \(aqint\(aq, y: \(aqint\(aq, width: \(aqint\(aq, height: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +The drag\-and\-drop operation physically finished │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ +The user performed the drop action. This event does not indicate │ │ │ │ │ +acceptance, \fI\%WlDataSource.cancelled()\fP may still be emitted │ │ │ │ │ +afterwards if the drop destination does not accept any mime type. │ │ │ │ │ .sp │ │ │ │ │ -Add rectangle to region │ │ │ │ │ +However, this event might however not be received if the compositor │ │ │ │ │ +cancelled the drag\-and\-drop operation before this event could happen. │ │ │ │ │ .sp │ │ │ │ │ -Add the specified rectangle to the region. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBx\fP (\fIArgumentType.Int\fP) \-\- region\-local x coordinate │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBy\fP (\fIArgumentType.Int\fP) \-\- region\-local y coordinate │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBwidth\fP (\fIArgumentType.Int\fP) \-\- rectangle width │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBheight\fP (\fIArgumentType.Int\fP) \-\- rectangle height │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ +Note that the data_source may still be used in the future and should │ │ │ │ │ +not be destroyed here. │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B subtract(x: \(aqint\(aq, y: \(aqint\(aq, width: \(aqint\(aq, height: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Request \-\- opcode 2 (attached to \fBResource\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Subtract rectangle from region │ │ │ │ │ -.sp │ │ │ │ │ -Subtract the specified rectangle from the region. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBx\fP (\fIArgumentType.Int\fP) \-\- region\-local x coordinate │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBy\fP (\fIArgumentType.Int\fP) \-\- region\-local y coordinate │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBwidth\fP (\fIArgumentType.Int\fP) \-\- rectangle width │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBheight\fP (\fIArgumentType.Int\fP) \-\- rectangle height │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.SS WlSubcompositor │ │ │ │ │ -.INDENT 0.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlSubcompositor │ │ │ │ │ -Sub\-surface compositing │ │ │ │ │ -.sp │ │ │ │ │ -The global interface exposing sub\-surface compositing capabilities. A │ │ │ │ │ -\fI\%WlSurface\fP, that has sub\-surfaces │ │ │ │ │ -associated, is called the parent surface. Sub\-surfaces can be arbitrarily │ │ │ │ │ -nested and create a tree of sub\-surfaces. │ │ │ │ │ -.sp │ │ │ │ │ -The root surface in a tree of sub\-surfaces is the main surface. The main │ │ │ │ │ -surface cannot be a sub\-surface, because sub\-surfaces must always have a │ │ │ │ │ -parent. │ │ │ │ │ -.sp │ │ │ │ │ -A main surface with its sub\-surfaces forms a (compound) window. For window │ │ │ │ │ -management purposes, this set of │ │ │ │ │ -\fI\%WlSurface\fP objects is to be considered │ │ │ │ │ -as a single window, and it should also behave as such. │ │ │ │ │ +.B dnd_finished() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -The aim of sub\-surfaces is to offload some of the compositing work within a │ │ │ │ │ -window from clients to the compositor. A prime example is a video player │ │ │ │ │ -with decorations and video in separate │ │ │ │ │ -\fI\%WlSurface\fP objects. This should allow │ │ │ │ │ -the compositor to pass YUV video buffer processing to dedicated overlay │ │ │ │ │ -hardware when possible. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B destroy() -> \(aqNone\(aq │ │ │ │ │ +Event \-\- opcode 4 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ +The drag\-and\-drop operation concluded │ │ │ │ │ .sp │ │ │ │ │ -Unbind from the subcompositor interface │ │ │ │ │ +The drop destination finished interoperating with this data source, so │ │ │ │ │ +the client is now free to destroy this data source and free all │ │ │ │ │ +associated data. │ │ │ │ │ .sp │ │ │ │ │ -Informs the server that the client will not be using this protocol │ │ │ │ │ -object anymore. This does not affect any other objects, │ │ │ │ │ -\fI\%WlSubsurface\fP objects included. │ │ │ │ │ +If the action used to perform the operation was \(dqmove\(dq, the source can │ │ │ │ │ +now delete the transferred data. │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B get_subsurface(surface: \(aqWlSurface\(aq, parent: \(aqWlSurface\(aq) -> \(aqProxy[WlSubsurface]\(aq │ │ │ │ │ +.B action(dnd_action: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ +Event \-\- opcode 5 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Give a surface the role sub\-surface │ │ │ │ │ +Notify the selected action │ │ │ │ │ .sp │ │ │ │ │ -Create a sub\-surface interface for the given surface, and associate it │ │ │ │ │ -with the given parent surface. This turns a plain │ │ │ │ │ -\fI\%WlSurface\fP into a sub\-surface. │ │ │ │ │ +This event indicates the action selected by the compositor after │ │ │ │ │ +matching the source/destination side actions. Only one action (or none) │ │ │ │ │ +will be offered here. │ │ │ │ │ .sp │ │ │ │ │ -The to\-be sub\-surface must not already have another role, and it must │ │ │ │ │ -not have an existing \fI\%WlSubsurface\fP │ │ │ │ │ -object. Otherwise the bad_surface protocol error is raised. │ │ │ │ │ +This event can be emitted multiple times during the drag\-and\-drop │ │ │ │ │ +operation, mainly in response to destination side changes through │ │ │ │ │ +\fI\%WlDataOffer.set_actions()\fP, and as the data │ │ │ │ │ +device enters/leaves surfaces. │ │ │ │ │ .sp │ │ │ │ │ -Adding sub\-surfaces to a parent is a double\-buffered operation on the │ │ │ │ │ -parent (see \fI\%WlSurface.commit()\fP). The effect of adding a │ │ │ │ │ -sub\-surface becomes visible on the next time the state of the parent │ │ │ │ │ -surface is applied. │ │ │ │ │ +It is only possible to receive this event after │ │ │ │ │ +\fI\%WlDataSource.dnd_drop_performed()\fP if the drag\-and\-drop │ │ │ │ │ +operation ended in an \(dqask\(dq action, in which case the final │ │ │ │ │ +\fI\%WlDataSource.action()\fP event will happen immediately before │ │ │ │ │ +\fI\%WlDataSource.dnd_finished()\fP\&. │ │ │ │ │ .sp │ │ │ │ │ -The parent surface must not be one of the child surface\(aqs descendants, │ │ │ │ │ -and the parent must be different from the child surface, otherwise the │ │ │ │ │ -bad_parent protocol error is raised. │ │ │ │ │ +Compositors may also change the selected action on the fly, mainly in │ │ │ │ │ +response to keyboard modifier changes during the drag\-and\-drop │ │ │ │ │ +operation. │ │ │ │ │ .sp │ │ │ │ │ -This request modifies the behaviour of \fI\%WlSurface.commit()\fP request on the sub\- │ │ │ │ │ -surface, see the documentation on │ │ │ │ │ -\fI\%WlSubsurface\fP interface. │ │ │ │ │ +The most recent action received is always the valid one. The chosen │ │ │ │ │ +action may change alongside negotiation (e.g. an \(dqask\(dq action can turn │ │ │ │ │ +into a \(dqmove\(dq operation), so the effects of the final action must │ │ │ │ │ +always be applied in \fBWlDataOffer.dnd_finished()\fP\&. │ │ │ │ │ +.sp │ │ │ │ │ +Clients can trigger cursor surface changes from this point, so they │ │ │ │ │ +reflect the current action. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBsurface\fP (\fI\%WlSurface\fP) \-\- the surface to be turned into a sub\-surface │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBparent\fP (\fI\%WlSurface\fP) \-\- the parent surface │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.TP │ │ │ │ │ -.B Returns │ │ │ │ │ -\fI\%WlSubsurface\fP \-\- the new sub\- │ │ │ │ │ -surface object ID │ │ │ │ │ +\fBdnd_action\fP (\fIArgumentType.Uint\fP) \-\- action selected by the compositor │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .SS WlPointer │ │ │ │ │ .INDENT 0.0 │ │ │ │ │ .TP │ │ │ │ │ .B class pywayland.protocol.wayland.WlPointer │ │ │ │ │ @@ -3583,549 +3460,1022 @@ │ │ │ │ │ \fBaxis\fP (\fIArgumentType.Uint\fP) \-\- axis type │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ \fBdirection\fP (\fIArgumentType.Uint\fP) \-\- physical direction relative to axis motion │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ -.SS WlDataOffer │ │ │ │ │ +.SS WlDataDeviceManager │ │ │ │ │ .INDENT 0.0 │ │ │ │ │ .TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlDataOffer │ │ │ │ │ -Offer to transfer data │ │ │ │ │ +.B class pywayland.protocol.wayland.WlDataDeviceManager │ │ │ │ │ +Data transfer interface │ │ │ │ │ .sp │ │ │ │ │ -A \fI\%WlDataOffer\fP represents a piece of data offered for transfer by │ │ │ │ │ -another client (the source client). It is used by the copy\-and\-paste and │ │ │ │ │ -drag\-and\-drop mechanisms. The offer describes the different mime types │ │ │ │ │ -that the data can be converted to and provides the mechanism for │ │ │ │ │ -transferring the data directly from the source client. │ │ │ │ │ +The \fI\%WlDataDeviceManager\fP is a singleton global object that provides │ │ │ │ │ +access to inter\-client data transfer mechanisms such as copy\-and\-paste and │ │ │ │ │ +drag\-and\-drop. These mechanisms are tied to a │ │ │ │ │ +\fI\%WlSeat\fP and this interface lets a │ │ │ │ │ +client get a \fI\%WlDataDevice\fP │ │ │ │ │ +corresponding to a \fI\%WlSeat\fP\&. │ │ │ │ │ +.sp │ │ │ │ │ +Depending on the version bound, the objects created from the bound │ │ │ │ │ +\fI\%WlDataDeviceManager\fP object will have different requirements for │ │ │ │ │ +functioning properly. See \fI\%WlDataSource.set_actions()\fP, │ │ │ │ │ +\fI\%WlDataOffer.accept()\fP and │ │ │ │ │ +\fI\%WlDataOffer.finish()\fP for details. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B accept(serial: \(aqint\(aq, mime_type: \(aqstr | None\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B create_data_source() -> \(aqProxy[WlDataSource]\(aq │ │ │ │ │ .sp │ │ │ │ │ Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Accept one of the offered mime types │ │ │ │ │ +Create a new data source │ │ │ │ │ .sp │ │ │ │ │ -Indicate that the client can accept the given mime type, or NULL for │ │ │ │ │ -not accepted. │ │ │ │ │ +Create a new data source. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Returns │ │ │ │ │ +\fI\%WlDataSource\fP \-\- data source to │ │ │ │ │ +create │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B get_data_device(seat: \(aqWlSeat\(aq) -> \(aqProxy[WlDataDevice]\(aq │ │ │ │ │ .sp │ │ │ │ │ -For objects of version 2 or older, this request is used by the client │ │ │ │ │ -to give feedback whether the client can receive the given mime type, or │ │ │ │ │ -NULL if none is accepted; the feedback does not determine whether the │ │ │ │ │ -drag\-and\-drop operation succeeds or not. │ │ │ │ │ +Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -For objects of version 3 or newer, this request determines the final │ │ │ │ │ -result of the drag\-and\-drop operation. If the end result is that no │ │ │ │ │ -mime types were accepted, the drag\-and\-drop operation will be cancelled │ │ │ │ │ -and the corresponding drag source will receive │ │ │ │ │ -\fI\%WlDataSource.cancelled()\fP\&. Clients may still │ │ │ │ │ -use this event in conjunction with \fI\%WlDataSource.action()\fP for feedback. │ │ │ │ │ +Create a new data device │ │ │ │ │ +.sp │ │ │ │ │ +Create a new data device for a given seat. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Parameters │ │ │ │ │ +\fBseat\fP (\fI\%WlSeat\fP) \-\- seat associated with the data device │ │ │ │ │ +.TP │ │ │ │ │ +.B Returns │ │ │ │ │ +\fI\%WlDataDevice\fP \-\- data device to │ │ │ │ │ +create │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.SS WlShm │ │ │ │ │ +.INDENT 0.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B class pywayland.protocol.wayland.WlShm │ │ │ │ │ +Shared memory support │ │ │ │ │ +.sp │ │ │ │ │ +A singleton global object that provides support for shared memory. │ │ │ │ │ +.sp │ │ │ │ │ +Clients can create \fI\%WlShmPool\fP objects │ │ │ │ │ +using the create_pool request. │ │ │ │ │ +.sp │ │ │ │ │ +On binding the \fI\%WlShm\fP object one or more format events are emitted │ │ │ │ │ +to inform clients about the valid pixel formats that can be used for │ │ │ │ │ +buffers. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B create_pool(fd: \(aqint\(aq, size: \(aqint\(aq) -> \(aqProxy[WlShmPool]\(aq │ │ │ │ │ +.sp │ │ │ │ │ +Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ +.sp │ │ │ │ │ +Create a shm pool │ │ │ │ │ +.sp │ │ │ │ │ +Create a new \fI\%WlShmPool\fP object. │ │ │ │ │ +.sp │ │ │ │ │ +The pool can be used to create shared memory based buffer objects. The │ │ │ │ │ +server will mmap size bytes of the passed file descriptor, to use as │ │ │ │ │ +backing memory for the pool. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBserial\fP (\fIArgumentType.Uint\fP) \-\- serial number of the accept request │ │ │ │ │ +\fBfd\fP (\fIArgumentType.FileDescriptor\fP) \-\- file descriptor for the pool │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBmime_type\fP (\fIArgumentType.String\fP or \fINone\fP) \-\- mime type accepted by the client │ │ │ │ │ +\fBsize\fP (\fIArgumentType.Int\fP) \-\- pool size, in bytes │ │ │ │ │ .UNINDENT │ │ │ │ │ +.TP │ │ │ │ │ +.B Returns │ │ │ │ │ +\fI\%WlShmPool\fP \-\- pool to create │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B receive(mime_type: \(aqstr\(aq, fd: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B release() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Request that the data is transferred │ │ │ │ │ +Release the shm object │ │ │ │ │ .sp │ │ │ │ │ -To transfer the offered data, the client issues this request and │ │ │ │ │ -indicates the mime type it wants to receive. The transfer happens │ │ │ │ │ -through the passed file descriptor (typically created with the pipe │ │ │ │ │ -system call). The source client writes the data in the mime type │ │ │ │ │ -representation requested and then closes the file descriptor. │ │ │ │ │ +Using this request a client can tell the server that it is not going to │ │ │ │ │ +use the shm object anymore. │ │ │ │ │ .sp │ │ │ │ │ -The receiving client reads from the read end of the pipe until EOF and │ │ │ │ │ -then closes its end, at which point the transfer is complete. │ │ │ │ │ +Objects created via this interface remain unaffected. │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B format(format: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -This request may happen multiple times for different mime types, both │ │ │ │ │ -before and after \fI\%WlDataDevice.drop()\fP\&. Drag\-and\-drop │ │ │ │ │ -destination clients may preemptively fetch data or examine it more │ │ │ │ │ -closely to determine acceptance. │ │ │ │ │ +Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ +.sp │ │ │ │ │ +Pixel format description │ │ │ │ │ +.sp │ │ │ │ │ +Informs the client about a valid pixel format that can be used for │ │ │ │ │ +buffers. Known formats include argb8888 and xrgb8888. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBmime_type\fP (\fIArgumentType.String\fP) \-\- mime type desired by receiver │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBfd\fP (\fIArgumentType.FileDescriptor\fP) \-\- file descriptor for data transfer │ │ │ │ │ +\fBformat\fP (\fIArgumentType.Uint\fP) \-\- buffer pixel format │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ +.SS WlBuffer │ │ │ │ │ +.INDENT 0.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B class pywayland.protocol.wayland.WlBuffer │ │ │ │ │ +Content for a \fI\%WlSurface\fP │ │ │ │ │ +.sp │ │ │ │ │ +A buffer provides the content for a │ │ │ │ │ +\fI\%WlSurface\fP\&. Buffers are created through │ │ │ │ │ +factory interfaces such as \fI\%WlShm\fP, │ │ │ │ │ +wp_linux_buffer_params (from the linux\-dmabuf protocol extension) or │ │ │ │ │ +similar. It has a width and a height and can be attached to a │ │ │ │ │ +\fI\%WlSurface\fP, but the mechanism by which │ │ │ │ │ +a client provides and updates the contents is defined by the buffer factory │ │ │ │ │ +interface. │ │ │ │ │ +.sp │ │ │ │ │ +Color channels are assumed to be electrical rather than optical (in other │ │ │ │ │ +words, encoded with a transfer function) unless otherwise specified. If the │ │ │ │ │ +buffer uses a format that has an alpha channel, the alpha channel is │ │ │ │ │ +assumed to be premultiplied into the electrical color channel values (after │ │ │ │ │ +transfer function encoding) unless otherwise specified. │ │ │ │ │ +.sp │ │ │ │ │ +Note, because \fI\%WlBuffer\fP objects are created from multiple │ │ │ │ │ +independent factory interfaces, the \fI\%WlBuffer\fP interface is frozen │ │ │ │ │ +at version 1. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B destroy() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 2 (attached to \fBResource\fP instance) │ │ │ │ │ +Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Destroy data offer │ │ │ │ │ +Destroy a buffer │ │ │ │ │ .sp │ │ │ │ │ -Destroy the data offer. │ │ │ │ │ +Destroy a buffer. If and how you need to release the backing storage is │ │ │ │ │ +defined by the buffer factory interface. │ │ │ │ │ +.sp │ │ │ │ │ +For possible side\-effects to a surface, see \fI\%WlSurface.attach()\fP\&. │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B finish() -> \(aqNone\(aq │ │ │ │ │ +.B release() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 3 (attached to \fBResource\fP instance) │ │ │ │ │ +Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -The offer will no longer be used │ │ │ │ │ +Compositor releases buffer │ │ │ │ │ .sp │ │ │ │ │ -Notifies the compositor that the drag destination successfully finished │ │ │ │ │ -the drag\-and\-drop operation. │ │ │ │ │ +Sent when this \fI\%WlBuffer\fP is no longer used by the compositor. │ │ │ │ │ +The client is now free to reuse or destroy this buffer and its backing │ │ │ │ │ +storage. │ │ │ │ │ .sp │ │ │ │ │ -Upon receiving this request, the compositor will emit │ │ │ │ │ -\fI\%WlDataSource.dnd_finished()\fP on the drag │ │ │ │ │ -source client. │ │ │ │ │ +If a client receives a release event before the frame callback │ │ │ │ │ +requested in the same \fI\%WlSurface.commit()\fP that attaches this │ │ │ │ │ +\fI\%WlBuffer\fP to a surface, then the client is immediately free to │ │ │ │ │ +reuse the buffer and its backing storage, and does not need a second │ │ │ │ │ +buffer for the next surface content update. Typically this is possible, │ │ │ │ │ +when the compositor maintains a copy of the │ │ │ │ │ +\fI\%WlSurface\fP contents, e.g. as a GL │ │ │ │ │ +texture. This is an important optimization for GL(ES) compositors with │ │ │ │ │ +\fI\%WlShm\fP clients. │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.SS WlSurface │ │ │ │ │ +.INDENT 0.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B class pywayland.protocol.wayland.WlSurface │ │ │ │ │ +An onscreen surface │ │ │ │ │ .sp │ │ │ │ │ -It is a client error to perform other requests than │ │ │ │ │ -\fI\%WlDataOffer.destroy()\fP after this one. It is also an error to │ │ │ │ │ -perform this request after a NULL mime type has been set in │ │ │ │ │ -\fI\%WlDataOffer.accept()\fP or no action was received through │ │ │ │ │ -\fI\%WlDataOffer.action()\fP\&. │ │ │ │ │ +A surface is a rectangular area that may be displayed on zero or more │ │ │ │ │ +outputs, and shown any number of times at the compositor\(aqs discretion. They │ │ │ │ │ +can present wl_buffers, receive user input, and define a local coordinate │ │ │ │ │ +system. │ │ │ │ │ .sp │ │ │ │ │ -If \fI\%WlDataOffer.finish()\fP request is received for a non drag and │ │ │ │ │ -drop operation, the invalid_finish protocol error is raised. │ │ │ │ │ +The size of a surface (and relative positions on it) is described in │ │ │ │ │ +surface\-local coordinates, which may differ from the buffer coordinates of │ │ │ │ │ +the pixel content, in case a buffer_transform or a buffer_scale is used. │ │ │ │ │ +.sp │ │ │ │ │ +A surface without a \(dqrole\(dq is fairly useless: a compositor does not know │ │ │ │ │ +where, when or how to present it. The role is the purpose of a │ │ │ │ │ +\fI\%WlSurface\fP\&. Examples of roles are a cursor for a pointer (as set by │ │ │ │ │ +\fI\%WlPointer.set_cursor()\fP), a drag icon │ │ │ │ │ +(\fI\%WlDataDevice.start_drag()\fP), a sub\-surface │ │ │ │ │ +(\fI\%WlSubcompositor.get_subsurface()\fP), and a window │ │ │ │ │ +as defined by a shell protocol (e.g. \fI\%WlShell.get_shell_surface()\fP). │ │ │ │ │ +.sp │ │ │ │ │ +A surface can have only one role at a time. Initially a \fI\%WlSurface\fP │ │ │ │ │ +does not have a role. Once a \fI\%WlSurface\fP is given a role, it is set │ │ │ │ │ +permanently for the whole lifetime of the \fI\%WlSurface\fP object. Giving │ │ │ │ │ +the current role again is allowed, unless explicitly forbidden by the │ │ │ │ │ +relevant interface specification. │ │ │ │ │ +.sp │ │ │ │ │ +Surface roles are given by requests in other interfaces such as │ │ │ │ │ +\fI\%WlPointer.set_cursor()\fP\&. The request should │ │ │ │ │ +explicitly mention that this request gives a role to a \fI\%WlSurface\fP\&. │ │ │ │ │ +Often, this request also creates a new protocol object that represents the │ │ │ │ │ +role and adds additional functionality to \fI\%WlSurface\fP\&. When a client │ │ │ │ │ +wants to destroy a \fI\%WlSurface\fP, they must destroy this role object │ │ │ │ │ +before the \fI\%WlSurface\fP, otherwise a defunct_role_object error is │ │ │ │ │ +sent. │ │ │ │ │ +.sp │ │ │ │ │ +Destroying the role object does not remove the role from the │ │ │ │ │ +\fI\%WlSurface\fP, but it may stop the \fI\%WlSurface\fP from \(dqplaying │ │ │ │ │ +the role\(dq. For instance, if a │ │ │ │ │ +\fI\%WlSubsurface\fP object is destroyed, the │ │ │ │ │ +\fI\%WlSurface\fP it was created for will be unmapped and forget its │ │ │ │ │ +position and z\-order. It is allowed to create a │ │ │ │ │ +\fI\%WlSubsurface\fP for the same │ │ │ │ │ +\fI\%WlSurface\fP again, but it is not allowed to use the │ │ │ │ │ +\fI\%WlSurface\fP as a cursor (cursor is a different role than sub\- │ │ │ │ │ +surface, and role switching is not allowed). │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B destroy() -> \(aqNone\(aq │ │ │ │ │ +.sp │ │ │ │ │ +Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ +.sp │ │ │ │ │ +Delete surface │ │ │ │ │ +.sp │ │ │ │ │ +Deletes the surface and invalidates its object ID. │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B set_actions(dnd_actions: \(aqint\(aq, preferred_action: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B attach(buffer: \(aqWlBuffer | None\(aq, x: \(aqint\(aq, y: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 4 (attached to \fBResource\fP instance) │ │ │ │ │ +Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Set the available/preferred drag\-and\-drop actions │ │ │ │ │ +Set the surface contents │ │ │ │ │ .sp │ │ │ │ │ -Sets the actions that the destination side client supports for this │ │ │ │ │ -operation. This request may trigger the emission of │ │ │ │ │ -\fI\%WlDataSource.action()\fP and │ │ │ │ │ -\fI\%WlDataOffer.action()\fP events if the compositor needs to change │ │ │ │ │ -the selected action. │ │ │ │ │ +Set a buffer as the content of this surface. │ │ │ │ │ .sp │ │ │ │ │ -This request can be called multiple times throughout the drag\-and\-drop │ │ │ │ │ -operation, typically in response to \fI\%WlDataDevice.enter()\fP or │ │ │ │ │ -\fI\%WlDataDevice.motion()\fP events. │ │ │ │ │ +The new size of the surface is calculated based on the buffer size │ │ │ │ │ +transformed by the inverse buffer_transform and the inverse │ │ │ │ │ +buffer_scale. This means that at commit time the supplied buffer size │ │ │ │ │ +must be an integer multiple of the buffer_scale. If that\(aqs not the │ │ │ │ │ +case, an invalid_size error is sent. │ │ │ │ │ .sp │ │ │ │ │ -This request determines the final result of the drag\-and\-drop │ │ │ │ │ -operation. If the end result is that no action is accepted, the drag │ │ │ │ │ -source will receive \fI\%WlDataSource.cancelled()\fP\&. │ │ │ │ │ +The x and y arguments specify the location of the new pending buffer\(aqs │ │ │ │ │ +upper left corner, relative to the current buffer\(aqs upper left corner, │ │ │ │ │ +in surface\-local coordinates. In other words, the x and y, combined │ │ │ │ │ +with the new surface size define in which directions the surface\(aqs size │ │ │ │ │ +changes. Setting anything other than 0 as x and y arguments is │ │ │ │ │ +discouraged, and should instead be replaced with using the separate │ │ │ │ │ +\fI\%WlSurface.offset()\fP request. │ │ │ │ │ .sp │ │ │ │ │ -The dnd_actions argument must contain only values expressed in the │ │ │ │ │ -\fBWlDataDeviceManager.dnd_actions()\fP enum, and │ │ │ │ │ -the preferred_action argument must only contain one of those values │ │ │ │ │ -set, otherwise it will result in a protocol error. │ │ │ │ │ +When the bound \fI\%WlSurface\fP version is 5 or higher, passing any │ │ │ │ │ +non\-zero x or y is a protocol violation, and will result in an │ │ │ │ │ +\(aqinvalid_offset\(aq error being raised. The x and y arguments are ignored │ │ │ │ │ +and do not change the pending state. To achieve equivalent semantics, │ │ │ │ │ +use \fI\%WlSurface.offset()\fP\&. │ │ │ │ │ .sp │ │ │ │ │ -While managing an \(dqask\(dq action, the destination drag\-and\-drop client │ │ │ │ │ -may perform further \fI\%WlDataOffer.receive()\fP requests, and is │ │ │ │ │ -expected to perform one last \fI\%WlDataOffer.set_actions()\fP request │ │ │ │ │ -with a preferred action other than \(dqask\(dq (and optionally │ │ │ │ │ -\fI\%WlDataOffer.accept()\fP) before requesting │ │ │ │ │ -\fI\%WlDataOffer.finish()\fP, in order to convey the action selected by │ │ │ │ │ -the user. If the preferred action is not in the │ │ │ │ │ -\fI\%WlDataOffer.source_actions()\fP mask, an error will be raised. │ │ │ │ │ +Surface contents are double\-buffered state, see │ │ │ │ │ +\fI\%WlSurface.commit()\fP\&. │ │ │ │ │ .sp │ │ │ │ │ -If the \(dqask\(dq action is dismissed (e.g. user cancellation), the client │ │ │ │ │ -is expected to perform \fI\%WlDataOffer.destroy()\fP right away. │ │ │ │ │ +The initial surface contents are void; there is no content. │ │ │ │ │ +\fI\%WlSurface.attach()\fP assigns the given │ │ │ │ │ +\fI\%WlBuffer\fP as the pending │ │ │ │ │ +\fI\%WlBuffer\fP\&. │ │ │ │ │ +\fI\%WlSurface.commit()\fP makes the pending │ │ │ │ │ +\fI\%WlBuffer\fP the new surface contents, │ │ │ │ │ +and the size of the surface becomes the size calculated from the │ │ │ │ │ +\fI\%WlBuffer\fP, as described above. │ │ │ │ │ +After commit, there is no pending buffer until the next attach. │ │ │ │ │ .sp │ │ │ │ │ -This request can only be made on drag\-and\-drop offers, a protocol error │ │ │ │ │ -will be raised otherwise. │ │ │ │ │ +Committing a pending \fI\%WlBuffer\fP │ │ │ │ │ +allows the compositor to read the pixels in the │ │ │ │ │ +\fI\%WlBuffer\fP\&. The compositor may │ │ │ │ │ +access the pixels at any time after the \fI\%WlSurface.commit()\fP │ │ │ │ │ +request. When the compositor will not access the pixels anymore, it │ │ │ │ │ +will send the \fI\%WlBuffer.release()\fP event. Only after │ │ │ │ │ +receiving \fI\%WlBuffer.release()\fP, the client may reuse │ │ │ │ │ +the \fI\%WlBuffer\fP\&. A │ │ │ │ │ +\fI\%WlBuffer\fP that has been attached │ │ │ │ │ +and then replaced by another attach instead of committed will not │ │ │ │ │ +receive a release event, and is not used by the compositor. │ │ │ │ │ +.sp │ │ │ │ │ +If a pending \fI\%WlBuffer\fP has been │ │ │ │ │ +committed to more than one \fI\%WlSurface\fP, the delivery of │ │ │ │ │ +\fI\%WlBuffer.release()\fP events becomes │ │ │ │ │ +undefined. A well behaved client should not rely on │ │ │ │ │ +\fI\%WlBuffer.release()\fP events in this case. │ │ │ │ │ +Alternatively, a client could create multiple │ │ │ │ │ +\fI\%WlBuffer\fP objects from the same │ │ │ │ │ +backing storage or use wp_linux_buffer_release. │ │ │ │ │ +.sp │ │ │ │ │ +Destroying the \fI\%WlBuffer\fP after │ │ │ │ │ +\fI\%WlBuffer.release()\fP does not change the │ │ │ │ │ +surface contents. Destroying the │ │ │ │ │ +\fI\%WlBuffer\fP before │ │ │ │ │ +\fI\%WlBuffer.release()\fP is allowed as long as │ │ │ │ │ +the underlying buffer storage isn\(aqt re\-used (this can happen e.g. on │ │ │ │ │ +client process termination). However, if the client destroys the │ │ │ │ │ +\fI\%WlBuffer\fP before receiving the │ │ │ │ │ +\fI\%WlBuffer.release()\fP event and mutates the │ │ │ │ │ +underlying buffer storage, the surface contents become undefined │ │ │ │ │ +immediately. │ │ │ │ │ +.sp │ │ │ │ │ +If \fI\%WlSurface.attach()\fP is sent with a NULL │ │ │ │ │ +\fI\%WlBuffer\fP, the following │ │ │ │ │ +\fI\%WlSurface.commit()\fP will remove the surface content. │ │ │ │ │ +.sp │ │ │ │ │ +If a pending \fI\%WlBuffer\fP has been │ │ │ │ │ +destroyed, the result is not specified. Many compositors are known to │ │ │ │ │ +remove the surface content on the following \fI\%WlSurface.commit()\fP, │ │ │ │ │ +but this behaviour is not universal. Clients seeking to maximise │ │ │ │ │ +compatibility should not destroy pending buffers and should ensure that │ │ │ │ │ +they explicitly remove content from surfaces, even after destroying │ │ │ │ │ +buffers. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBdnd_actions\fP (\fIArgumentType.Uint\fP) \-\- actions supported by the destination client │ │ │ │ │ +\fBbuffer\fP (\fI\%WlBuffer\fP or \fINone\fP) \-\- buffer of surface contents │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBpreferred_action\fP (\fIArgumentType.Uint\fP) \-\- action preferred by the destination client │ │ │ │ │ +\fBx\fP (\fIArgumentType.Int\fP) \-\- surface\-local x coordinate │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBy\fP (\fIArgumentType.Int\fP) \-\- surface\-local y coordinate │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B offer(mime_type: \(aqstr\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B damage(x: \(aqint\(aq, y: \(aqint\(aq, width: \(aqint\(aq, height: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ +Request \-\- opcode 2 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Advertise offered mime type │ │ │ │ │ +Mark part of the surface damaged │ │ │ │ │ .sp │ │ │ │ │ -Sent immediately after creating the \fI\%WlDataOffer\fP object. One │ │ │ │ │ -event per offered mime type. │ │ │ │ │ +This request is used to describe the regions where the pending buffer │ │ │ │ │ +is different from the current surface contents, and where the surface │ │ │ │ │ +therefore needs to be repainted. The compositor ignores the parts of │ │ │ │ │ +the damage that fall outside of the surface. │ │ │ │ │ +.sp │ │ │ │ │ +Damage is double\-buffered state, see \fI\%WlSurface.commit()\fP\&. │ │ │ │ │ +.sp │ │ │ │ │ +The damage rectangle is specified in surface\-local coordinates, where x │ │ │ │ │ +and y specify the upper left corner of the damage rectangle. │ │ │ │ │ +.sp │ │ │ │ │ +The initial value for pending damage is empty: no damage. │ │ │ │ │ +\fI\%WlSurface.damage()\fP adds pending damage: the new pending damage │ │ │ │ │ +is the union of old pending damage and the given rectangle. │ │ │ │ │ +.sp │ │ │ │ │ +\fI\%WlSurface.commit()\fP assigns pending damage as the current │ │ │ │ │ +damage, and clears pending damage. The server will clear the current │ │ │ │ │ +damage as it repaints the surface. │ │ │ │ │ +.sp │ │ │ │ │ +Note! New clients should not use this request. Instead damage can be │ │ │ │ │ +posted with \fI\%WlSurface.damage_buffer()\fP which uses buffer │ │ │ │ │ +coordinates instead of surface coordinates. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -\fBmime_type\fP (\fIArgumentType.String\fP) \-\- offered mime type │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBx\fP (\fIArgumentType.Int\fP) \-\- surface\-local x coordinate │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBy\fP (\fIArgumentType.Int\fP) \-\- surface\-local y coordinate │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBwidth\fP (\fIArgumentType.Int\fP) \-\- width of damage rectangle │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBheight\fP (\fIArgumentType.Int\fP) \-\- height of damage rectangle │ │ │ │ │ +.UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B source_actions(source_actions: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B frame() -> \(aqProxy[WlCallback]\(aq │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 1 (attached to \fBProxy\fP instance) │ │ │ │ │ +Request \-\- opcode 3 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Notify the source\-side available actions │ │ │ │ │ +Request a frame throttling hint │ │ │ │ │ .sp │ │ │ │ │ -This event indicates the actions offered by the data source. It will be │ │ │ │ │ -sent immediately after creating the \fI\%WlDataOffer\fP object, or │ │ │ │ │ -anytime the source side changes its offered actions through │ │ │ │ │ -\fI\%WlDataSource.set_actions()\fP\&. │ │ │ │ │ +Request a notification when it is a good time to start drawing a new │ │ │ │ │ +frame, by creating a frame callback. This is useful for throttling │ │ │ │ │ +redrawing operations, and driving animations. │ │ │ │ │ +.sp │ │ │ │ │ +When a client is animating on a \fI\%WlSurface\fP, it can use the │ │ │ │ │ +\(aqframe\(aq request to get notified when it is a good time to draw and │ │ │ │ │ +commit the next frame of animation. If the client commits an update │ │ │ │ │ +earlier than that, it is likely that some updates will not make it to │ │ │ │ │ +the display, and the client is wasting resources by drawing too often. │ │ │ │ │ +.sp │ │ │ │ │ +The frame request will take effect on the next │ │ │ │ │ +\fI\%WlSurface.commit()\fP\&. The notification will only be posted for │ │ │ │ │ +one frame unless requested again. For a \fI\%WlSurface\fP, the │ │ │ │ │ +notifications are posted in the order the frame requests were │ │ │ │ │ +committed. │ │ │ │ │ +.sp │ │ │ │ │ +The server must send the notifications so that a client will not send │ │ │ │ │ +excessive updates, while still allowing the highest possible update │ │ │ │ │ +rate for clients that wait for the reply before drawing again. The │ │ │ │ │ +server should give some time for the client to draw and commit after │ │ │ │ │ +sending the frame callback events to let it hit the next output │ │ │ │ │ +refresh. │ │ │ │ │ +.sp │ │ │ │ │ +A server should avoid signaling the frame callbacks if the surface is │ │ │ │ │ +not visible in any way, e.g. the surface is off\-screen, or completely │ │ │ │ │ +obscured by other opaque surfaces. │ │ │ │ │ +.sp │ │ │ │ │ +The object returned by this request will be destroyed by the compositor │ │ │ │ │ +after the callback is fired and as such the client must not attempt to │ │ │ │ │ +use it after that point. │ │ │ │ │ +.sp │ │ │ │ │ +The callback_data passed in the callback is the current time, in │ │ │ │ │ +milliseconds, with an undefined base. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -\fBsource_actions\fP (\fIArgumentType.Uint\fP) \-\- actions offered by the data source │ │ │ │ │ +.B Returns │ │ │ │ │ +\fI\%WlCallback\fP \-\- callback object │ │ │ │ │ +for the frame request │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B action(dnd_action: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B set_opaque_region(region: \(aqWlRegion | None\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 2 (attached to \fBProxy\fP instance) │ │ │ │ │ +Request \-\- opcode 4 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Notify the selected action │ │ │ │ │ +Set opaque region │ │ │ │ │ .sp │ │ │ │ │ -This event indicates the action selected by the compositor after │ │ │ │ │ -matching the source/destination side actions. Only one action (or none) │ │ │ │ │ -will be offered here. │ │ │ │ │ +This request sets the region of the surface that contains opaque │ │ │ │ │ +content. │ │ │ │ │ .sp │ │ │ │ │ -This event can be emitted multiple times during the drag\-and\-drop │ │ │ │ │ -operation in response to destination side action changes through │ │ │ │ │ -\fI\%WlDataOffer.set_actions()\fP\&. │ │ │ │ │ +The opaque region is an optimization hint for the compositor that lets │ │ │ │ │ +it optimize the redrawing of content behind opaque regions. Setting an │ │ │ │ │ +opaque region is not required for correct behaviour, but marking │ │ │ │ │ +transparent content as opaque will result in repaint artifacts. │ │ │ │ │ .sp │ │ │ │ │ -This event will no longer be emitted after \fI\%WlDataDevice.drop()\fP happened on the drag\- │ │ │ │ │ -and\-drop destination, the client must honor the last action received, │ │ │ │ │ -or the last preferred one set through \fI\%WlDataOffer.set_actions()\fP │ │ │ │ │ -when handling an \(dqask\(dq action. │ │ │ │ │ +The opaque region is specified in surface\-local coordinates. │ │ │ │ │ .sp │ │ │ │ │ -Compositors may also change the selected action on the fly, mainly in │ │ │ │ │ -response to keyboard modifier changes during the drag\-and\-drop │ │ │ │ │ -operation. │ │ │ │ │ +The compositor ignores the parts of the opaque region that fall outside │ │ │ │ │ +of the surface. │ │ │ │ │ .sp │ │ │ │ │ -The most recent action received is always the valid one. Prior to │ │ │ │ │ -receiving \fI\%WlDataDevice.drop()\fP, the chosen action may │ │ │ │ │ -change (e.g. due to keyboard modifiers being pressed). At the time of │ │ │ │ │ -receiving \fI\%WlDataDevice.drop()\fP the drag\-and\-drop │ │ │ │ │ -destination must honor the last action received. │ │ │ │ │ +Opaque region is double\-buffered state, see \fI\%WlSurface.commit()\fP\&. │ │ │ │ │ .sp │ │ │ │ │ -Action changes may still happen after \fI\%WlDataDevice.drop()\fP, especially on \(dqask\(dq │ │ │ │ │ -actions, where the drag\-and\-drop destination may choose another action │ │ │ │ │ -afterwards. Action changes happening at this stage are always the │ │ │ │ │ -result of inter\-client negotiation, the compositor shall no longer be │ │ │ │ │ -able to induce a different action. │ │ │ │ │ +\fI\%WlSurface.set_opaque_region()\fP changes the pending opaque │ │ │ │ │ +region. \fI\%WlSurface.commit()\fP copies the pending region to the │ │ │ │ │ +current region. Otherwise, the pending and current regions are never │ │ │ │ │ +changed. │ │ │ │ │ .sp │ │ │ │ │ -Upon \(dqask\(dq actions, it is expected that the drag\-and\-drop destination │ │ │ │ │ -may potentially choose a different action and/or mime type, based on │ │ │ │ │ -\fI\%WlDataOffer.source_actions()\fP and finally chosen by the user │ │ │ │ │ -(e.g. popping up a menu with the available options). The final │ │ │ │ │ -\fI\%WlDataOffer.set_actions()\fP and \fI\%WlDataOffer.accept()\fP │ │ │ │ │ -requests must happen before the call to \fI\%WlDataOffer.finish()\fP\&. │ │ │ │ │ +The initial value for an opaque region is empty. Setting the pending │ │ │ │ │ +opaque region has copy semantics, and the │ │ │ │ │ +\fI\%WlRegion\fP object can be destroyed │ │ │ │ │ +immediately. A NULL \fI\%WlRegion\fP │ │ │ │ │ +causes the pending opaque region to be set to empty. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -\fBdnd_action\fP (\fIArgumentType.Uint\fP) \-\- action selected by the compositor │ │ │ │ │ +\fBregion\fP (\fI\%WlRegion\fP or \fINone\fP) \-\- opaque region of the surface │ │ │ │ │ +.UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B set_input_region(region: \(aqWlRegion | None\(aq) -> \(aqNone\(aq │ │ │ │ │ +.sp │ │ │ │ │ +Request \-\- opcode 5 (attached to \fBResource\fP instance) │ │ │ │ │ +.sp │ │ │ │ │ +Set input region │ │ │ │ │ +.sp │ │ │ │ │ +This request sets the region of the surface that can receive pointer │ │ │ │ │ +and touch events. │ │ │ │ │ +.sp │ │ │ │ │ +Input events happening outside of this region will try the next surface │ │ │ │ │ +in the server surface stack. The compositor ignores the parts of the │ │ │ │ │ +input region that fall outside of the surface. │ │ │ │ │ +.sp │ │ │ │ │ +The input region is specified in surface\-local coordinates. │ │ │ │ │ +.sp │ │ │ │ │ +Input region is double\-buffered state, see \fI\%WlSurface.commit()\fP\&. │ │ │ │ │ +.sp │ │ │ │ │ +\fI\%WlSurface.set_input_region()\fP changes the pending input region. │ │ │ │ │ +\fI\%WlSurface.commit()\fP copies the pending region to the current │ │ │ │ │ +region. Otherwise the pending and current regions are never changed, │ │ │ │ │ +except cursor and icon surfaces are special cases, see │ │ │ │ │ +\fI\%WlPointer.set_cursor()\fP and │ │ │ │ │ +\fI\%WlDataDevice.start_drag()\fP\&. │ │ │ │ │ +.sp │ │ │ │ │ +The initial value for an input region is infinite. That means the whole │ │ │ │ │ +surface will accept input. Setting the pending input region has copy │ │ │ │ │ +semantics, and the \fI\%WlRegion\fP object │ │ │ │ │ +can be destroyed immediately. A NULL │ │ │ │ │ +\fI\%WlRegion\fP causes the input region │ │ │ │ │ +to be set to infinite. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Parameters │ │ │ │ │ +\fBregion\fP (\fI\%WlRegion\fP or \fINone\fP) \-\- input region of the surface │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ -.SS WlSeat │ │ │ │ │ -.INDENT 0.0 │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlSeat │ │ │ │ │ -Group of input devices │ │ │ │ │ +.B commit() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -A seat is a group of keyboards, pointer and touch devices. This object is │ │ │ │ │ -published as a global during start up, or when such a device is hot │ │ │ │ │ -plugged. A seat typically has a pointer and maintains a keyboard focus and │ │ │ │ │ -a pointer focus. │ │ │ │ │ +Request \-\- opcode 6 (attached to \fBResource\fP instance) │ │ │ │ │ +.sp │ │ │ │ │ +Commit pending surface state │ │ │ │ │ +.sp │ │ │ │ │ +Surface state (input, opaque, and damage regions, attached buffers, │ │ │ │ │ +etc.) is double\-buffered. Protocol requests modify the pending state, │ │ │ │ │ +as opposed to the active state in use by the compositor. │ │ │ │ │ +.sp │ │ │ │ │ +A commit request atomically creates a content update from the pending │ │ │ │ │ +state, even if the pending state has not been touched. The content │ │ │ │ │ +update is placed in a queue until it becomes active. After commit, the │ │ │ │ │ +new pending state is as documented for each related request. │ │ │ │ │ +.sp │ │ │ │ │ +When the content update is applied, the │ │ │ │ │ +\fI\%WlBuffer\fP is applied before all │ │ │ │ │ +other state. This means that all coordinates in double\-buffered state │ │ │ │ │ +are relative to the newly attached wl_buffers, except for │ │ │ │ │ +\fI\%WlSurface.attach()\fP itself. If there is no newly attached │ │ │ │ │ +\fI\%WlBuffer\fP, the coordinates are │ │ │ │ │ +relative to the previous content update. │ │ │ │ │ +.sp │ │ │ │ │ +All requests that need a commit to become effective are documented to │ │ │ │ │ +affect double\-buffered state. │ │ │ │ │ +.sp │ │ │ │ │ +Other interfaces may add further double\-buffered surface state. │ │ │ │ │ +.UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B get_pointer() -> \(aqProxy[WlPointer]\(aq │ │ │ │ │ +.B set_buffer_transform(transform: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ +Request \-\- opcode 7 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Return pointer object │ │ │ │ │ +Sets the buffer transformation │ │ │ │ │ .sp │ │ │ │ │ -The ID provided will be initialized to the │ │ │ │ │ -\fI\%WlPointer\fP interface for this seat. │ │ │ │ │ +This request sets the transformation that the client has already │ │ │ │ │ +applied to the content of the buffer. The accepted values for the │ │ │ │ │ +transform parameter are the values for \fBWlOutput.transform()\fP\&. │ │ │ │ │ .sp │ │ │ │ │ -This request only takes effect if the seat has the pointer capability, │ │ │ │ │ -or has had the pointer capability in the past. It is a protocol │ │ │ │ │ -violation to issue this request on a seat that has never had the │ │ │ │ │ -pointer capability. The missing_capability error will be sent in this │ │ │ │ │ -case. │ │ │ │ │ +The compositor applies the inverse of this transformation whenever it │ │ │ │ │ +uses the buffer contents. │ │ │ │ │ +.sp │ │ │ │ │ +Buffer transform is double\-buffered state, see │ │ │ │ │ +\fI\%WlSurface.commit()\fP\&. │ │ │ │ │ +.sp │ │ │ │ │ +A newly created surface has its buffer transformation set to normal. │ │ │ │ │ +.sp │ │ │ │ │ +\fI\%WlSurface.set_buffer_transform()\fP changes the pending buffer │ │ │ │ │ +transformation. \fI\%WlSurface.commit()\fP copies the pending buffer │ │ │ │ │ +transformation to the current one. Otherwise, the pending and current │ │ │ │ │ +values are never changed. │ │ │ │ │ +.sp │ │ │ │ │ +The purpose of this request is to allow clients to render content │ │ │ │ │ +according to the output transform, thus permitting the compositor to │ │ │ │ │ +use certain optimizations even if the display is rotated. Using │ │ │ │ │ +hardware overlays and scanning out a client buffer for fullscreen │ │ │ │ │ +surfaces are examples of such optimizations. Those optimizations are │ │ │ │ │ +highly dependent on the compositor implementation, so the use of this │ │ │ │ │ +request should be considered on a case\-by\-case basis. │ │ │ │ │ +.sp │ │ │ │ │ +Note that if the transform value includes 90 or 270 degree rotation, │ │ │ │ │ +the width of the buffer will become the surface height and the height │ │ │ │ │ +of the buffer will become the surface width. │ │ │ │ │ +.sp │ │ │ │ │ +If transform is not one of the values from the │ │ │ │ │ +\fBWlOutput.transform()\fP enum the │ │ │ │ │ +invalid_transform protocol error is raised. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B Returns │ │ │ │ │ -\fI\%WlPointer\fP \-\- seat pointer │ │ │ │ │ +.B Parameters │ │ │ │ │ +\fBtransform\fP (\fIArgumentType.Int\fP) \-\- transform for interpreting buffer contents │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B get_keyboard() -> \(aqProxy[WlKeyboard]\(aq │ │ │ │ │ +.B set_buffer_scale(scale: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ +Request \-\- opcode 8 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Return keyboard object │ │ │ │ │ +Sets the buffer scaling factor │ │ │ │ │ .sp │ │ │ │ │ -The ID provided will be initialized to the │ │ │ │ │ -\fI\%WlKeyboard\fP interface for this │ │ │ │ │ -seat. │ │ │ │ │ +This request sets an optional scaling factor on how the compositor │ │ │ │ │ +interprets the contents of the buffer attached to the window. │ │ │ │ │ .sp │ │ │ │ │ -This request only takes effect if the seat has the keyboard capability, │ │ │ │ │ -or has had the keyboard capability in the past. It is a protocol │ │ │ │ │ -violation to issue this request on a seat that has never had the │ │ │ │ │ -keyboard capability. The missing_capability error will be sent in this │ │ │ │ │ -case. │ │ │ │ │ +Buffer scale is double\-buffered state, see \fI\%WlSurface.commit()\fP\&. │ │ │ │ │ +.sp │ │ │ │ │ +A newly created surface has its buffer scale set to 1. │ │ │ │ │ +.sp │ │ │ │ │ +\fI\%WlSurface.set_buffer_scale()\fP changes the pending buffer scale. │ │ │ │ │ +\fI\%WlSurface.commit()\fP copies the pending buffer scale to the │ │ │ │ │ +current one. Otherwise, the pending and current values are never │ │ │ │ │ +changed. │ │ │ │ │ +.sp │ │ │ │ │ +The purpose of this request is to allow clients to supply higher │ │ │ │ │ +resolution buffer data for use on high resolution outputs. It is │ │ │ │ │ +intended that you pick the same buffer scale as the scale of the output │ │ │ │ │ +that the surface is displayed on. This means the compositor can avoid │ │ │ │ │ +scaling when rendering the surface on that output. │ │ │ │ │ +.sp │ │ │ │ │ +Note that if the scale is larger than 1, then you have to attach a │ │ │ │ │ +buffer that is larger (by a factor of scale in each dimension) than the │ │ │ │ │ +desired surface size. │ │ │ │ │ +.sp │ │ │ │ │ +If scale is not greater than 0 the invalid_scale protocol error is │ │ │ │ │ +raised. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B Returns │ │ │ │ │ -\fI\%WlKeyboard\fP \-\- seat keyboard │ │ │ │ │ +.B Parameters │ │ │ │ │ +\fBscale\fP (\fIArgumentType.Int\fP) \-\- scale for interpreting buffer contents │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B get_touch() -> \(aqProxy[WlTouch]\(aq │ │ │ │ │ +.B damage_buffer(x: \(aqint\(aq, y: \(aqint\(aq, width: \(aqint\(aq, height: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 2 (attached to \fBResource\fP instance) │ │ │ │ │ +Request \-\- opcode 9 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Return touch object │ │ │ │ │ +Mark part of the surface damaged using buffer coordinates │ │ │ │ │ .sp │ │ │ │ │ -The ID provided will be initialized to the │ │ │ │ │ -\fI\%WlTouch\fP interface for this seat. │ │ │ │ │ +This request is used to describe the regions where the pending buffer │ │ │ │ │ +is different from the current surface contents, and where the surface │ │ │ │ │ +therefore needs to be repainted. The compositor ignores the parts of │ │ │ │ │ +the damage that fall outside of the surface. │ │ │ │ │ .sp │ │ │ │ │ -This request only takes effect if the seat has the touch capability, or │ │ │ │ │ -has had the touch capability in the past. It is a protocol violation to │ │ │ │ │ -issue this request on a seat that has never had the touch capability. │ │ │ │ │ -The missing_capability error will be sent in this case. │ │ │ │ │ +Damage is double\-buffered state, see \fI\%WlSurface.commit()\fP\&. │ │ │ │ │ +.sp │ │ │ │ │ +The damage rectangle is specified in buffer coordinates, where x and y │ │ │ │ │ +specify the upper left corner of the damage rectangle. │ │ │ │ │ +.sp │ │ │ │ │ +The initial value for pending damage is empty: no damage. │ │ │ │ │ +\fI\%WlSurface.damage_buffer()\fP adds pending damage: the new pending │ │ │ │ │ +damage is the union of old pending damage and the given rectangle. │ │ │ │ │ +.sp │ │ │ │ │ +\fI\%WlSurface.commit()\fP assigns pending damage as the current │ │ │ │ │ +damage, and clears pending damage. The server will clear the current │ │ │ │ │ +damage as it repaints the surface. │ │ │ │ │ +.sp │ │ │ │ │ +This request differs from \fI\%WlSurface.damage()\fP in only one way \- │ │ │ │ │ +it takes damage in buffer coordinates instead of surface\-local │ │ │ │ │ +coordinates. While this generally is more intuitive than surface │ │ │ │ │ +coordinates, it is especially desirable when using wp_viewport or when │ │ │ │ │ +a drawing library (like EGL) is unaware of buffer scale and buffer │ │ │ │ │ +transform. │ │ │ │ │ +.sp │ │ │ │ │ +Note: Because buffer transformation changes and damage requests may be │ │ │ │ │ +interleaved in the protocol stream, it is impossible to determine the │ │ │ │ │ +actual mapping between surface and buffer damage until │ │ │ │ │ +\fI\%WlSurface.commit()\fP time. Therefore, compositors wishing to take │ │ │ │ │ +both kinds of damage into account will have to accumulate damage from │ │ │ │ │ +the two requests separately and only transform from one to the other │ │ │ │ │ +after receiving the \fI\%WlSurface.commit()\fP\&. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B Returns │ │ │ │ │ -\fI\%WlTouch\fP \-\- seat touch │ │ │ │ │ -interface │ │ │ │ │ +.B Parameters │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBx\fP (\fIArgumentType.Int\fP) \-\- buffer\-local x coordinate │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBy\fP (\fIArgumentType.Int\fP) \-\- buffer\-local y coordinate │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBwidth\fP (\fIArgumentType.Int\fP) \-\- width of damage rectangle │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBheight\fP (\fIArgumentType.Int\fP) \-\- height of damage rectangle │ │ │ │ │ +.UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B release() -> \(aqNone\(aq │ │ │ │ │ +.B offset(x: \(aqint\(aq, y: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 3 (attached to \fBResource\fP instance) │ │ │ │ │ +Request \-\- opcode 10 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Release the seat object │ │ │ │ │ +Set the surface contents offset │ │ │ │ │ .sp │ │ │ │ │ -Using this request a client can tell the server that it is not going to │ │ │ │ │ -use the seat object anymore. │ │ │ │ │ +The x and y arguments specify the location of the new pending buffer\(aqs │ │ │ │ │ +upper left corner, relative to the current buffer\(aqs upper left corner, │ │ │ │ │ +in surface\-local coordinates. In other words, the x and y, combined │ │ │ │ │ +with the new surface size define in which directions the surface\(aqs size │ │ │ │ │ +changes. │ │ │ │ │ +.sp │ │ │ │ │ +Surface location offset is double\-buffered state, see │ │ │ │ │ +\fI\%WlSurface.commit()\fP\&. │ │ │ │ │ +.sp │ │ │ │ │ +This request is semantically equivalent to and the replaces the x and y │ │ │ │ │ +arguments in the \fI\%WlSurface.attach()\fP request in │ │ │ │ │ +\fI\%WlSurface\fP versions prior to 5. See \fI\%WlSurface.attach()\fP │ │ │ │ │ +for details. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Parameters │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBx\fP (\fIArgumentType.Int\fP) \-\- surface\-local x coordinate │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBy\fP (\fIArgumentType.Int\fP) \-\- surface\-local y coordinate │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B capabilities(capabilities: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B enter(output: \(aqWlOutput\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Seat capabilities changed │ │ │ │ │ +Surface enters an output │ │ │ │ │ .sp │ │ │ │ │ -This is emitted whenever a seat gains or loses the pointer, keyboard or │ │ │ │ │ -touch capabilities. The argument is a capability enum containing the │ │ │ │ │ -complete set of capabilities this seat has. │ │ │ │ │ +This is emitted whenever a surface\(aqs creation, movement, or resizing │ │ │ │ │ +results in some part of it being within the scanout region of an │ │ │ │ │ +output. │ │ │ │ │ .sp │ │ │ │ │ -When the pointer capability is added, a client may create a │ │ │ │ │ -\fI\%WlPointer\fP object using the │ │ │ │ │ -\fI\%WlSeat.get_pointer()\fP request. This object will receive pointer │ │ │ │ │ -events until the capability is removed in the future. │ │ │ │ │ +Note that a surface may be overlapping with zero or more outputs. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Parameters │ │ │ │ │ +\fBoutput\fP (\fI\%WlOutput\fP) \-\- output entered by the surface │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B leave(output: \(aqWlOutput\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -When the pointer capability is removed, a client should destroy the │ │ │ │ │ -\fI\%WlPointer\fP objects associated with │ │ │ │ │ -the seat where the capability was removed, using the │ │ │ │ │ -\fI\%WlPointer.release()\fP request. No further │ │ │ │ │ -pointer events will be received on these objects. │ │ │ │ │ +Event \-\- opcode 1 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -In some compositors, if a seat regains the pointer capability and a │ │ │ │ │ -client has a previously obtained │ │ │ │ │ -\fI\%WlPointer\fP object of version 4 or │ │ │ │ │ -less, that object may start sending pointer events again. This behavior │ │ │ │ │ -is considered a misinterpretation of the intended behavior and must not │ │ │ │ │ -be relied upon by the client. │ │ │ │ │ -\fI\%WlPointer\fP objects of version 5 or │ │ │ │ │ -later must not send events if created before the most recent event │ │ │ │ │ -notifying the client of an added pointer capability. │ │ │ │ │ +Surface leaves an output │ │ │ │ │ .sp │ │ │ │ │ -The above behavior also applies to │ │ │ │ │ -\fI\%WlKeyboard\fP and │ │ │ │ │ -\fI\%WlTouch\fP with the keyboard and │ │ │ │ │ -touch capabilities, respectively. │ │ │ │ │ +This is emitted whenever a surface\(aqs creation, movement, or resizing │ │ │ │ │ +results in it no longer having any part of it within the scanout region │ │ │ │ │ +of an output. │ │ │ │ │ +.sp │ │ │ │ │ +Clients should not use the number of outputs the surface is on for │ │ │ │ │ +frame throttling purposes. The surface might be hidden even if no leave │ │ │ │ │ +event has been sent, and the compositor might expect new surface │ │ │ │ │ +content updates even if no enter event has been sent. The frame event │ │ │ │ │ +should be used instead. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -\fBcapabilities\fP (\fIArgumentType.Uint\fP) \-\- capabilities of the seat │ │ │ │ │ +\fBoutput\fP (\fI\%WlOutput\fP) \-\- output left by the surface │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B name(name: \(aqstr\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B preferred_buffer_scale(factor: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 1 (attached to \fBProxy\fP instance) │ │ │ │ │ +Event \-\- opcode 2 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Unique identifier for this seat │ │ │ │ │ +Preferred buffer scale for the surface │ │ │ │ │ .sp │ │ │ │ │ -In a multi\-seat configuration the seat name can be used by clients to │ │ │ │ │ -help identify which physical devices the seat represents. │ │ │ │ │ +This event indicates the preferred buffer scale for this surface. It is │ │ │ │ │ +sent whenever the compositor\(aqs preference changes. │ │ │ │ │ .sp │ │ │ │ │ -The seat name is a UTF\-8 string with no convention defined for its │ │ │ │ │ -contents. Each name is unique among all \fI\%WlSeat\fP globals. The │ │ │ │ │ -name is only guaranteed to be unique for the current compositor │ │ │ │ │ -instance. │ │ │ │ │ +Before receiving this event the preferred buffer scale for this surface │ │ │ │ │ +is 1. │ │ │ │ │ .sp │ │ │ │ │ -The same seat names are used for all clients. Thus, the name can be │ │ │ │ │ -shared across processes to refer to a specific \fI\%WlSeat\fP global. │ │ │ │ │ +It is intended that scaling aware clients use this event to scale their │ │ │ │ │ +content and use \fI\%WlSurface.set_buffer_scale()\fP to indicate the │ │ │ │ │ +scale they have rendered with. This allows clients to supply a higher │ │ │ │ │ +detail buffer. │ │ │ │ │ .sp │ │ │ │ │ -The name event is sent after binding to the seat global. This event is │ │ │ │ │ -only sent once per seat object, and the name does not change over the │ │ │ │ │ -lifetime of the \fI\%WlSeat\fP global. │ │ │ │ │ +The compositor shall emit a scale value greater than 0. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Parameters │ │ │ │ │ +\fBfactor\fP (\fIArgumentType.Int\fP) \-\- preferred scaling factor │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B preferred_buffer_transform(transform: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Compositors may re\-use the same seat name if the \fI\%WlSeat\fP global │ │ │ │ │ -is destroyed and re\-created later. │ │ │ │ │ +Event \-\- opcode 3 (attached to \fBProxy\fP instance) │ │ │ │ │ +.sp │ │ │ │ │ +Preferred buffer transform for the surface │ │ │ │ │ +.sp │ │ │ │ │ +This event indicates the preferred buffer transform for this surface. │ │ │ │ │ +It is sent whenever the compositor\(aqs preference changes. │ │ │ │ │ +.sp │ │ │ │ │ +Before receiving this event the preferred buffer transform for this │ │ │ │ │ +surface is normal. │ │ │ │ │ +.sp │ │ │ │ │ +Applying this transformation to the surface buffer contents and using │ │ │ │ │ +\fI\%WlSurface.set_buffer_transform()\fP might allow the compositor to │ │ │ │ │ +use the surface buffer more efficiently. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -\fBname\fP (\fIArgumentType.String\fP) \-\- seat identifier │ │ │ │ │ +\fBtransform\fP (\fIArgumentType.Uint\fP) \-\- preferred transform │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ -.SS WlBuffer │ │ │ │ │ +.SS WlSubsurface │ │ │ │ │ .INDENT 0.0 │ │ │ │ │ .TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlBuffer │ │ │ │ │ -Content for a \fI\%WlSurface\fP │ │ │ │ │ +.B class pywayland.protocol.wayland.WlSubsurface │ │ │ │ │ +Sub\-surface interface to a \fI\%WlSurface\fP │ │ │ │ │ .sp │ │ │ │ │ -A buffer provides the content for a │ │ │ │ │ -\fI\%WlSurface\fP\&. Buffers are created through │ │ │ │ │ -factory interfaces such as \fI\%WlShm\fP, │ │ │ │ │ -wp_linux_buffer_params (from the linux\-dmabuf protocol extension) or │ │ │ │ │ -similar. It has a width and a height and can be attached to a │ │ │ │ │ -\fI\%WlSurface\fP, but the mechanism by which │ │ │ │ │ -a client provides and updates the contents is defined by the buffer factory │ │ │ │ │ -interface. │ │ │ │ │ +An additional interface to a \fI\%WlSurface\fP │ │ │ │ │ +object, which has been made a sub\-surface. A sub\-surface has one parent │ │ │ │ │ +surface. A sub\-surface\(aqs size and position are not limited to that of the │ │ │ │ │ +parent. Particularly, a sub\-surface is not automatically clipped to its │ │ │ │ │ +parent\(aqs area. │ │ │ │ │ .sp │ │ │ │ │ -Color channels are assumed to be electrical rather than optical (in other │ │ │ │ │ -words, encoded with a transfer function) unless otherwise specified. If the │ │ │ │ │ -buffer uses a format that has an alpha channel, the alpha channel is │ │ │ │ │ -assumed to be premultiplied into the electrical color channel values (after │ │ │ │ │ -transfer function encoding) unless otherwise specified. │ │ │ │ │ +A sub\-surface becomes mapped, when a non\-NULL │ │ │ │ │ +\fI\%WlBuffer\fP is applied and the parent │ │ │ │ │ +surface is mapped. The order of which one happens first is irrelevant. A │ │ │ │ │ +sub\-surface is hidden if the parent becomes hidden, or if a NULL │ │ │ │ │ +\fI\%WlBuffer\fP is applied. These rules apply │ │ │ │ │ +recursively through the tree of surfaces. │ │ │ │ │ .sp │ │ │ │ │ -Note, because \fI\%WlBuffer\fP objects are created from multiple │ │ │ │ │ -independent factory interfaces, the \fI\%WlBuffer\fP interface is frozen │ │ │ │ │ -at version 1. │ │ │ │ │ +The behaviour of a \fI\%WlSurface.commit()\fP request on a sub\-surface │ │ │ │ │ +depends on the sub\-surface\(aqs mode. The possible modes are synchronized and │ │ │ │ │ +desynchronized, see methods \fI\%WlSubsurface.set_sync()\fP and │ │ │ │ │ +\fI\%WlSubsurface.set_desync()\fP\&. Synchronized mode caches the │ │ │ │ │ +\fI\%WlSurface\fP state to be applied when the │ │ │ │ │ +parent\(aqs state gets applied, and desynchronized mode applies the pending │ │ │ │ │ +\fI\%WlSurface\fP state directly. A sub\- │ │ │ │ │ +surface is initially in the synchronized mode. │ │ │ │ │ +.sp │ │ │ │ │ +Sub\-surfaces also have another kind of state, which is managed by │ │ │ │ │ +\fI\%WlSubsurface\fP requests, as opposed to │ │ │ │ │ +\fI\%WlSurface\fP requests. This state │ │ │ │ │ +includes the sub\-surface position relative to the parent surface │ │ │ │ │ +(\fI\%WlSubsurface.set_position()\fP), and the stacking order of the parent │ │ │ │ │ +and its sub\-surfaces (\fI\%WlSubsurface.place_above()\fP and .place_below). │ │ │ │ │ +This state is applied when the parent surface\(aqs │ │ │ │ │ +\fI\%WlSurface\fP state is applied, regardless │ │ │ │ │ +of the sub\-surface\(aqs mode. As the exception, set_sync and set_desync are │ │ │ │ │ +effective immediately. │ │ │ │ │ +.sp │ │ │ │ │ +The main surface can be thought to be always in desynchronized mode, since │ │ │ │ │ +it does not have a parent in the sub\-surfaces sense. │ │ │ │ │ +.sp │ │ │ │ │ +Even if a sub\-surface is in desynchronized mode, it will behave as in │ │ │ │ │ +synchronized mode, if its parent surface behaves as in synchronized mode. │ │ │ │ │ +This rule is applied recursively throughout the tree of surfaces. This │ │ │ │ │ +means, that one can set a sub\-surface into synchronized mode, and then │ │ │ │ │ +assume that all its child and grand\-child sub\-surfaces are synchronized, │ │ │ │ │ +too, without explicitly setting them. │ │ │ │ │ +.sp │ │ │ │ │ +Destroying a sub\-surface takes effect immediately. If you need to │ │ │ │ │ +synchronize the removal of a sub\-surface to the parent surface update, │ │ │ │ │ +unmap the sub\-surface first by attaching a NULL │ │ │ │ │ +\fI\%WlBuffer\fP, update parent, and then │ │ │ │ │ +destroy the sub\-surface. │ │ │ │ │ +.sp │ │ │ │ │ +If the parent \fI\%WlSurface\fP object is │ │ │ │ │ +destroyed, the sub\-surface is unmapped. │ │ │ │ │ +.sp │ │ │ │ │ +A sub\-surface never has the keyboard focus of any seat. │ │ │ │ │ +.sp │ │ │ │ │ +The \fI\%WlSurface.offset()\fP request is ignored: clients │ │ │ │ │ +must use set_position instead to move the sub\-surface. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B destroy() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Destroy a buffer │ │ │ │ │ -.sp │ │ │ │ │ -Destroy a buffer. If and how you need to release the backing storage is │ │ │ │ │ -defined by the buffer factory interface. │ │ │ │ │ +Remove sub\-surface interface │ │ │ │ │ .sp │ │ │ │ │ -For possible side\-effects to a surface, see \fI\%WlSurface.attach()\fP\&. │ │ │ │ │ +The sub\-surface interface is removed from the │ │ │ │ │ +\fI\%WlSurface\fP object that was turned │ │ │ │ │ +into a sub\-surface with a \fI\%WlSubcompositor.get_subsurface()\fP request. │ │ │ │ │ +The wl_surface\(aqs association to the parent is deleted. The │ │ │ │ │ +\fI\%WlSurface\fP is unmapped immediately. │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B release() -> \(aqNone\(aq │ │ │ │ │ +.B set_position(x: \(aqint\(aq, y: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ +Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Compositor releases buffer │ │ │ │ │ +Reposition the sub\-surface │ │ │ │ │ .sp │ │ │ │ │ -Sent when this \fI\%WlBuffer\fP is no longer used by the compositor. │ │ │ │ │ -The client is now free to reuse or destroy this buffer and its backing │ │ │ │ │ -storage. │ │ │ │ │ +This schedules a sub\-surface position change. The sub\-surface will be │ │ │ │ │ +moved so that its origin (top left corner pixel) will be at the │ │ │ │ │ +location x, y of the parent surface coordinate system. The coordinates │ │ │ │ │ +are not restricted to the parent surface area. Negative values are │ │ │ │ │ +allowed. │ │ │ │ │ .sp │ │ │ │ │ -If a client receives a release event before the frame callback │ │ │ │ │ -requested in the same \fI\%WlSurface.commit()\fP that attaches this │ │ │ │ │ -\fI\%WlBuffer\fP to a surface, then the client is immediately free to │ │ │ │ │ -reuse the buffer and its backing storage, and does not need a second │ │ │ │ │ -buffer for the next surface content update. Typically this is possible, │ │ │ │ │ -when the compositor maintains a copy of the │ │ │ │ │ -\fI\%WlSurface\fP contents, e.g. as a GL │ │ │ │ │ -texture. This is an important optimization for GL(ES) compositors with │ │ │ │ │ -\fI\%WlShm\fP clients. │ │ │ │ │ +The scheduled coordinates will take effect whenever the state of the │ │ │ │ │ +parent surface is applied. │ │ │ │ │ +.sp │ │ │ │ │ +If more than one set_position request is invoked by the client before │ │ │ │ │ +the commit of the parent surface, the position of a new request always │ │ │ │ │ +replaces the scheduled position from any previous request. │ │ │ │ │ +.sp │ │ │ │ │ +The initial position is 0, 0. │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.TP │ │ │ │ │ +.B Parameters │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBx\fP (\fIArgumentType.Int\fP) \-\- x coordinate in the parent surface │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBy\fP (\fIArgumentType.Int\fP) \-\- y coordinate in the parent surface │ │ │ │ │ +.UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ -.SS WlCompositor │ │ │ │ │ -.INDENT 0.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlCompositor │ │ │ │ │ -The compositor singleton │ │ │ │ │ -.sp │ │ │ │ │ -A compositor. This object is a singleton global. The compositor is in │ │ │ │ │ -charge of combining the contents of multiple surfaces into one displayable │ │ │ │ │ -output. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B create_surface() -> \(aqProxy[WlSurface]\(aq │ │ │ │ │ +.B place_above(sibling: \(aqWlSurface\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ +Request \-\- opcode 2 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Create new surface │ │ │ │ │ +Restack the sub\-surface │ │ │ │ │ .sp │ │ │ │ │ -Ask the compositor to create a new surface. │ │ │ │ │ +This sub\-surface is taken from the stack, and put back just above the │ │ │ │ │ +reference surface, changing the z\-order of the sub\-surfaces. The │ │ │ │ │ +reference surface must be one of the sibling surfaces, or the parent │ │ │ │ │ +surface. Using any other surface, including this sub\-surface, will │ │ │ │ │ +cause a protocol error. │ │ │ │ │ +.sp │ │ │ │ │ +The z\-order is double\-buffered. Requests are handled in order and │ │ │ │ │ +applied immediately to a pending state. The final pending state is │ │ │ │ │ +copied to the active state the next time the state of the parent │ │ │ │ │ +surface is applied. │ │ │ │ │ +.sp │ │ │ │ │ +A new sub\-surface is initially added as the top\-most in the stack of │ │ │ │ │ +its siblings and parent. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B Returns │ │ │ │ │ -\fI\%WlSurface\fP \-\- the new surface │ │ │ │ │ +.B Parameters │ │ │ │ │ +\fBsibling\fP (\fI\%WlSurface\fP) \-\- the reference surface │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B create_region() -> \(aqProxy[WlRegion]\(aq │ │ │ │ │ +.B place_below(sibling: \(aqWlSurface\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ +Request \-\- opcode 3 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Create new region │ │ │ │ │ +Restack the sub\-surface │ │ │ │ │ .sp │ │ │ │ │ -Ask the compositor to create a new region. │ │ │ │ │ +The sub\-surface is placed just below the reference surface. See │ │ │ │ │ +\fI\%WlSubsurface.place_above()\fP\&. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B Returns │ │ │ │ │ -\fI\%WlRegion\fP \-\- the new region │ │ │ │ │ -.UNINDENT │ │ │ │ │ +.B Parameters │ │ │ │ │ +\fBsibling\fP (\fI\%WlSurface\fP) \-\- the reference surface │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ -.SS WlCallback │ │ │ │ │ -.INDENT 0.0 │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlCallback │ │ │ │ │ -Callback object │ │ │ │ │ +.B set_sync() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Clients can handle the \(aqdone\(aq event to get notified when the related │ │ │ │ │ -request is done. │ │ │ │ │ +Request \-\- opcode 4 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Note, because \fI\%WlCallback\fP objects are created from multiple │ │ │ │ │ -independent factory interfaces, the \fI\%WlCallback\fP interface is frozen │ │ │ │ │ -at version 1. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B done(callback_data: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +Set sub\-surface to synchronized mode │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ +Change the commit behaviour of the sub\-surface to synchronized mode, │ │ │ │ │ +also described as the parent dependent mode. │ │ │ │ │ .sp │ │ │ │ │ -Done event │ │ │ │ │ +In synchronized mode, \fI\%WlSurface.commit()\fP on a sub\-surface will │ │ │ │ │ +accumulate the committed state in a cache, but the state will not be │ │ │ │ │ +applied and hence will not change the compositor output. The cached │ │ │ │ │ +state is applied to the sub\-surface immediately after the parent │ │ │ │ │ +surface\(aqs state is applied. This ensures atomic updates of the parent │ │ │ │ │ +and all its synchronized sub\-surfaces. Applying the cached state will │ │ │ │ │ +invalidate the cache, so further parent surface commits do not │ │ │ │ │ +(re\-)apply old state. │ │ │ │ │ .sp │ │ │ │ │ -Notify the client when the related request is done. │ │ │ │ │ +See \fI\%WlSubsurface\fP for the recursive effect of this mode. │ │ │ │ │ +.UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -\fBcallback_data\fP (\fIArgumentType.Uint\fP) \-\- request\-specific data for the callback │ │ │ │ │ -.UNINDENT │ │ │ │ │ +.B set_desync() -> \(aqNone\(aq │ │ │ │ │ +.sp │ │ │ │ │ +Request \-\- opcode 5 (attached to \fBResource\fP instance) │ │ │ │ │ +.sp │ │ │ │ │ +Set sub\-surface to desynchronized mode │ │ │ │ │ +.sp │ │ │ │ │ +Change the commit behaviour of the sub\-surface to desynchronized mode, │ │ │ │ │ +also described as independent or freely running mode. │ │ │ │ │ +.sp │ │ │ │ │ +In desynchronized mode, \fI\%WlSurface.commit()\fP on a sub\-surface will │ │ │ │ │ +apply the pending state directly, without caching, as happens normally │ │ │ │ │ +with a \fI\%WlSurface\fP\&. Calling │ │ │ │ │ +\fI\%WlSurface.commit()\fP on the parent surface │ │ │ │ │ +has no effect on the sub\-surface\(aqs │ │ │ │ │ +\fI\%WlSurface\fP state. This mode allows │ │ │ │ │ +a sub\-surface to be updated on its own. │ │ │ │ │ +.sp │ │ │ │ │ +If cached state exists when \fI\%WlSurface.commit()\fP is called in │ │ │ │ │ +desynchronized mode, the pending state is added to the cached state, │ │ │ │ │ +and applied as a whole. This invalidates the cache. │ │ │ │ │ +.sp │ │ │ │ │ +Note: even if a sub\-surface is set to desynchronized, a parent sub\- │ │ │ │ │ +surface may override it to behave as synchronized. For details, see │ │ │ │ │ +\fI\%WlSubsurface\fP\&. │ │ │ │ │ +.sp │ │ │ │ │ +If a surface\(aqs parent surface behaves as desynchronized, then the │ │ │ │ │ +cached state is applied on set_desync. │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .SS WlKeyboard │ │ │ │ │ .INDENT 0.0 │ │ │ │ │ .TP │ │ │ │ │ .B class pywayland.protocol.wayland.WlKeyboard │ │ │ │ │ Keyboard input device │ │ │ │ │ @@ -4349,409 +4699,174 @@ │ │ │ │ │ \fBrate\fP (\fIArgumentType.Int\fP) \-\- the rate of repeating keys in characters per second │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ \fBdelay\fP (\fIArgumentType.Int\fP) \-\- delay in milliseconds since key down until repeating starts │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ -.SS WlOutput │ │ │ │ │ +.SS WlSeat │ │ │ │ │ .INDENT 0.0 │ │ │ │ │ .TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlOutput │ │ │ │ │ -Compositor output region │ │ │ │ │ +.B class pywayland.protocol.wayland.WlSeat │ │ │ │ │ +Group of input devices │ │ │ │ │ .sp │ │ │ │ │ -An output describes part of the compositor geometry. The compositor works │ │ │ │ │ -in the \(aqcompositor coordinate system\(aq and an output corresponds to a │ │ │ │ │ -rectangular area in that space that is actually visible. This typically │ │ │ │ │ -corresponds to a monitor that displays part of the compositor space. This │ │ │ │ │ -object is published as global during start up, or when a monitor is │ │ │ │ │ -hotplugged. │ │ │ │ │ +A seat is a group of keyboards, pointer and touch devices. This object is │ │ │ │ │ +published as a global during start up, or when such a device is hot │ │ │ │ │ +plugged. A seat typically has a pointer and maintains a keyboard focus and │ │ │ │ │ +a pointer focus. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B release() -> \(aqNone\(aq │ │ │ │ │ +.B get_pointer() -> \(aqProxy[WlPointer]\(aq │ │ │ │ │ .sp │ │ │ │ │ Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Release the output object │ │ │ │ │ -.sp │ │ │ │ │ -Using this request a client can tell the server that it is not going to │ │ │ │ │ -use the output object anymore. │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B geometry(x: \(aqint\(aq, y: \(aqint\(aq, physical_width: \(aqint\(aq, physical_height: \(aqint\(aq, subpixel: \(aqint\(aq, make: \(aqstr\(aq, model: \(aqstr\(aq, transform: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Properties of the output │ │ │ │ │ -.sp │ │ │ │ │ -The geometry event describes geometric properties of the output. The │ │ │ │ │ -event is sent when binding to the output object and whenever any of the │ │ │ │ │ -properties change. │ │ │ │ │ -.sp │ │ │ │ │ -The physical size can be set to zero if it doesn\(aqt make sense for this │ │ │ │ │ -output (e.g. for projectors or virtual outputs). │ │ │ │ │ -.sp │ │ │ │ │ -The geometry event will be followed by a done event (starting from │ │ │ │ │ -version 2). │ │ │ │ │ -.sp │ │ │ │ │ -Clients should use \fI\%WlSurface.preferred_buffer_transform()\fP │ │ │ │ │ -instead of the transform advertised by this event to find the preferred │ │ │ │ │ -buffer transform to use for a surface. │ │ │ │ │ -.sp │ │ │ │ │ -Note: \fI\%WlOutput\fP only advertises partial information about the │ │ │ │ │ -output position and identification. Some compositors, for instance │ │ │ │ │ -those not implementing a desktop\-style output layout or those exposing │ │ │ │ │ -virtual outputs, might fake this information. Instead of using x and y, │ │ │ │ │ -clients should use xdg_output.logical_position. Instead of using make │ │ │ │ │ -and model, clients should use name and description. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBx\fP (\fIArgumentType.Int\fP) \-\- x position within the global compositor space │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBy\fP (\fIArgumentType.Int\fP) \-\- y position within the global compositor space │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBphysical_width\fP (\fIArgumentType.Int\fP) \-\- width in millimeters of the output │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBphysical_height\fP (\fIArgumentType.Int\fP) \-\- height in millimeters of the output │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBsubpixel\fP (\fIArgumentType.Int\fP) \-\- subpixel orientation of the output │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBmake\fP (\fIArgumentType.String\fP) \-\- textual description of the manufacturer │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBmodel\fP (\fIArgumentType.String\fP) \-\- textual description of the model │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBtransform\fP (\fIArgumentType.Int\fP) \-\- additional transformation applied to buffer contents during │ │ │ │ │ -presentation │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B mode(flags: \(aqint\(aq, width: \(aqint\(aq, height: \(aqint\(aq, refresh: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Event \-\- opcode 1 (attached to \fBProxy\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Advertise available modes for the output │ │ │ │ │ -.sp │ │ │ │ │ -The mode event describes an available mode for the output. │ │ │ │ │ -.sp │ │ │ │ │ -The event is sent when binding to the output object and there will │ │ │ │ │ -always be one mode, the current mode. The event is sent again if an │ │ │ │ │ -output changes mode, for the mode that is now current. In other words, │ │ │ │ │ -the current mode is always the last mode that was received with the │ │ │ │ │ -current flag set. │ │ │ │ │ -.sp │ │ │ │ │ -Non\-current modes are deprecated. A compositor can decide to only │ │ │ │ │ -advertise the current mode and never send other modes. Clients should │ │ │ │ │ -not rely on non\-current modes. │ │ │ │ │ -.sp │ │ │ │ │ -The size of a mode is given in physical hardware units of the output │ │ │ │ │ -device. This is not necessarily the same as the output size in the │ │ │ │ │ -global compositor space. For instance, the output may be scaled, as │ │ │ │ │ -described in \fI\%WlOutput.scale()\fP, or transformed, as described in │ │ │ │ │ -\fBWlOutput.transform()\fP\&. Clients willing to retrieve the output │ │ │ │ │ -size in the global compositor space should use xdg_output.logical_size │ │ │ │ │ -instead. │ │ │ │ │ -.sp │ │ │ │ │ -The vertical refresh rate can be set to zero if it doesn\(aqt make sense │ │ │ │ │ -for this output (e.g. for virtual outputs). │ │ │ │ │ -.sp │ │ │ │ │ -The mode event will be followed by a done event (starting from version │ │ │ │ │ -2). │ │ │ │ │ +Return pointer object │ │ │ │ │ .sp │ │ │ │ │ -Clients should not use the refresh rate to schedule frames. Instead, │ │ │ │ │ -they should use the \fI\%WlSurface.frame()\fP event or the │ │ │ │ │ -presentation\-time protocol. │ │ │ │ │ +The ID provided will be initialized to the │ │ │ │ │ +\fI\%WlPointer\fP interface for this seat. │ │ │ │ │ .sp │ │ │ │ │ -Note: this information is not always meaningful for all outputs. Some │ │ │ │ │ -compositors, such as those exposing virtual outputs, might fake the │ │ │ │ │ -refresh rate or the size. │ │ │ │ │ +This request only takes effect if the seat has the pointer capability, │ │ │ │ │ +or has had the pointer capability in the past. It is a protocol │ │ │ │ │ +violation to issue this request on a seat that has never had the │ │ │ │ │ +pointer capability. The missing_capability error will be sent in this │ │ │ │ │ +case. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBflags\fP (\fIArgumentType.Uint\fP) \-\- bitfield of mode flags │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBwidth\fP (\fIArgumentType.Int\fP) \-\- width of the mode in hardware units │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBheight\fP (\fIArgumentType.Int\fP) \-\- height of the mode in hardware units │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBrefresh\fP (\fIArgumentType.Int\fP) \-\- vertical refresh rate in mHz │ │ │ │ │ -.UNINDENT │ │ │ │ │ +.B Returns │ │ │ │ │ +\fI\%WlPointer\fP \-\- seat pointer │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B done() -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Event \-\- opcode 2 (attached to \fBProxy\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Sent all information about output │ │ │ │ │ -.sp │ │ │ │ │ -This event is sent after all other properties have been sent after │ │ │ │ │ -binding to the output object and after any other property changes done │ │ │ │ │ -after that. This allows changes to the output properties to be seen as │ │ │ │ │ -atomic, even if they happen via multiple events. │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B scale(factor: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Event \-\- opcode 3 (attached to \fBProxy\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Output scaling properties │ │ │ │ │ +.B get_keyboard() -> \(aqProxy[WlKeyboard]\(aq │ │ │ │ │ .sp │ │ │ │ │ -This event contains scaling geometry information that is not in the │ │ │ │ │ -geometry event. It may be sent after binding the output object or if │ │ │ │ │ -the output scale changes later. The compositor will emit a non\-zero, │ │ │ │ │ -positive value for scale. If it is not sent, the client should assume a │ │ │ │ │ -scale of 1. │ │ │ │ │ +Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -A scale larger than 1 means that the compositor will automatically │ │ │ │ │ -scale surface buffers by this amount when rendering. This is used for │ │ │ │ │ -very high resolution displays where applications rendering at the │ │ │ │ │ -native resolution would be too small to be legible. │ │ │ │ │ +Return keyboard object │ │ │ │ │ .sp │ │ │ │ │ -Clients should use \fI\%WlSurface.preferred_buffer_scale()\fP instead │ │ │ │ │ -of this event to find the preferred buffer scale to use for a surface. │ │ │ │ │ +The ID provided will be initialized to the │ │ │ │ │ +\fI\%WlKeyboard\fP interface for this │ │ │ │ │ +seat. │ │ │ │ │ .sp │ │ │ │ │ -The scale event will be followed by a done event. │ │ │ │ │ +This request only takes effect if the seat has the keyboard capability, │ │ │ │ │ +or has had the keyboard capability in the past. It is a protocol │ │ │ │ │ +violation to issue this request on a seat that has never had the │ │ │ │ │ +keyboard capability. The missing_capability error will be sent in this │ │ │ │ │ +case. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -\fBfactor\fP (\fIArgumentType.Int\fP) \-\- scaling factor of output │ │ │ │ │ +.B Returns │ │ │ │ │ +\fI\%WlKeyboard\fP \-\- seat keyboard │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B name(name: \(aqstr\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Event \-\- opcode 4 (attached to \fBProxy\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Name of this output │ │ │ │ │ -.sp │ │ │ │ │ -Many compositors will assign user\-friendly names to their outputs, show │ │ │ │ │ -them to the user, allow the user to refer to an output, etc. The client │ │ │ │ │ -may wish to know this name as well to offer the user similar behaviors. │ │ │ │ │ -.sp │ │ │ │ │ -The name is a UTF\-8 string with no convention defined for its contents. │ │ │ │ │ -Each name is unique among all \fI\%WlOutput\fP globals. The name is │ │ │ │ │ -only guaranteed to be unique for the compositor instance. │ │ │ │ │ -.sp │ │ │ │ │ -The same output name is used for all clients for a given │ │ │ │ │ -\fI\%WlOutput\fP global. Thus, the name can be shared across processes │ │ │ │ │ -to refer to a specific \fI\%WlOutput\fP global. │ │ │ │ │ -.sp │ │ │ │ │ -The name is not guaranteed to be persistent across sessions, thus │ │ │ │ │ -cannot be used to reliably identify an output in e.g. configuration │ │ │ │ │ -files. │ │ │ │ │ +.B get_touch() -> \(aqProxy[WlTouch]\(aq │ │ │ │ │ .sp │ │ │ │ │ -Examples of names include \(aqHDMI\-A\-1\(aq, \(aqWL\-1\(aq, \(aqX11\-1\(aq, etc. However, do │ │ │ │ │ -not assume that the name is a reflection of an underlying DRM │ │ │ │ │ -connector, X11 connection, etc. │ │ │ │ │ +Request \-\- opcode 2 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -The name event is sent after binding the output object. This event is │ │ │ │ │ -only sent once per output object, and the name does not change over the │ │ │ │ │ -lifetime of the \fI\%WlOutput\fP global. │ │ │ │ │ +Return touch object │ │ │ │ │ .sp │ │ │ │ │ -Compositors may re\-use the same output name if the \fI\%WlOutput\fP │ │ │ │ │ -global is destroyed and re\-created later. Compositors should avoid re\- │ │ │ │ │ -using the same name if possible. │ │ │ │ │ +The ID provided will be initialized to the │ │ │ │ │ +\fI\%WlTouch\fP interface for this seat. │ │ │ │ │ .sp │ │ │ │ │ -The name event will be followed by a done event. │ │ │ │ │ +This request only takes effect if the seat has the touch capability, or │ │ │ │ │ +has had the touch capability in the past. It is a protocol violation to │ │ │ │ │ +issue this request on a seat that has never had the touch capability. │ │ │ │ │ +The missing_capability error will be sent in this case. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -\fBname\fP (\fIArgumentType.String\fP) \-\- output name │ │ │ │ │ +.B Returns │ │ │ │ │ +\fI\%WlTouch\fP \-\- seat touch │ │ │ │ │ +interface │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B description(description: \(aqstr\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Event \-\- opcode 5 (attached to \fBProxy\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Human\-readable description of this output │ │ │ │ │ -.sp │ │ │ │ │ -Many compositors can produce human\-readable descriptions of their │ │ │ │ │ -outputs. The client may wish to know this description as well, e.g. for │ │ │ │ │ -output selection purposes. │ │ │ │ │ +.B release() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -The description is a UTF\-8 string with no convention defined for its │ │ │ │ │ -contents. The description is not guaranteed to be unique among all │ │ │ │ │ -\fI\%WlOutput\fP globals. Examples might include \(aqFoocorp 11\(dq Display\(aq │ │ │ │ │ -or \(aqVirtual X11 output via :1\(aq. │ │ │ │ │ +Request \-\- opcode 3 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -The description event is sent after binding the output object and │ │ │ │ │ -whenever the description changes. The description is optional, and may │ │ │ │ │ -not be sent at all. │ │ │ │ │ +Release the seat object │ │ │ │ │ .sp │ │ │ │ │ -The description event will be followed by a done event. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -\fBdescription\fP (\fIArgumentType.String\fP) \-\- output description │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ +Using this request a client can tell the server that it is not going to │ │ │ │ │ +use the seat object anymore. │ │ │ │ │ .UNINDENT │ │ │ │ │ -.SS WlRegistry │ │ │ │ │ -.INDENT 0.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlRegistry │ │ │ │ │ -Global registry object │ │ │ │ │ -.sp │ │ │ │ │ -The singleton global registry object. The server has a number of global │ │ │ │ │ -objects that are available to all clients. These objects typically │ │ │ │ │ -represent an actual object in the server (for example, an input device) or │ │ │ │ │ -they are singleton objects that provide extension functionality. │ │ │ │ │ -.sp │ │ │ │ │ -When a client creates a registry object, the registry object will emit a │ │ │ │ │ -global event for each global currently in the registry. Globals come and │ │ │ │ │ -go as a result of device or monitor hotplugs, reconfiguration or other │ │ │ │ │ -events, and the registry will send out global and global_remove events to │ │ │ │ │ -keep the client up to date with the changes. To mark the end of the │ │ │ │ │ -initial burst of events, the client can use the \fI\%WlDisplay.sync()\fP request immediately after │ │ │ │ │ -calling \fI\%WlDisplay.get_registry()\fP\&. │ │ │ │ │ -.sp │ │ │ │ │ -A client can bind to a global object by using the bind request. This │ │ │ │ │ -creates a client\-side handle that lets the object emit events to the client │ │ │ │ │ -and lets the client invoke requests on the object. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B bind(name: \(aqint\(aq, interface: \(aqtype[T]\(aq, version: \(aqint\(aq) -> \(aqProxy[T]\(aq │ │ │ │ │ +.B capabilities(capabilities: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ +Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Bind an object to the display │ │ │ │ │ +Seat capabilities changed │ │ │ │ │ .sp │ │ │ │ │ -Binds a new, client\-created object to the server using the specified │ │ │ │ │ -name as the identifier. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBname\fP (\fIArgumentType.Uint\fP) \-\- unique numeric name of the object │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBinterface\fP (\fIstring\fP) \-\- Interface name │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBversion\fP (\fIint\fP) \-\- Interface version │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.TP │ │ │ │ │ -.B Returns │ │ │ │ │ -\fBpywayland.client.proxy.Proxy\fP of specified Interface \-\- │ │ │ │ │ -bounded object │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B global_(name: \(aqint\(aq, interface: \(aqstr\(aq, version: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +This is emitted whenever a seat gains or loses the pointer, keyboard or │ │ │ │ │ +touch capabilities. The argument is a capability enum containing the │ │ │ │ │ +complete set of capabilities this seat has. │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ +When the pointer capability is added, a client may create a │ │ │ │ │ +\fI\%WlPointer\fP object using the │ │ │ │ │ +\fI\%WlSeat.get_pointer()\fP request. This object will receive pointer │ │ │ │ │ +events until the capability is removed in the future. │ │ │ │ │ .sp │ │ │ │ │ -Announce global object │ │ │ │ │ +When the pointer capability is removed, a client should destroy the │ │ │ │ │ +\fI\%WlPointer\fP objects associated with │ │ │ │ │ +the seat where the capability was removed, using the │ │ │ │ │ +\fI\%WlPointer.release()\fP request. No further │ │ │ │ │ +pointer events will be received on these objects. │ │ │ │ │ .sp │ │ │ │ │ -Notify the client of global objects. │ │ │ │ │ +In some compositors, if a seat regains the pointer capability and a │ │ │ │ │ +client has a previously obtained │ │ │ │ │ +\fI\%WlPointer\fP object of version 4 or │ │ │ │ │ +less, that object may start sending pointer events again. This behavior │ │ │ │ │ +is considered a misinterpretation of the intended behavior and must not │ │ │ │ │ +be relied upon by the client. │ │ │ │ │ +\fI\%WlPointer\fP objects of version 5 or │ │ │ │ │ +later must not send events if created before the most recent event │ │ │ │ │ +notifying the client of an added pointer capability. │ │ │ │ │ .sp │ │ │ │ │ -The event notifies the client that a global object with the given name │ │ │ │ │ -is now available, and it implements the given version of the given │ │ │ │ │ -interface. │ │ │ │ │ +The above behavior also applies to │ │ │ │ │ +\fI\%WlKeyboard\fP and │ │ │ │ │ +\fI\%WlTouch\fP with the keyboard and │ │ │ │ │ +touch capabilities, respectively. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBname\fP (\fIArgumentType.Uint\fP) \-\- numeric name of the global object │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBinterface\fP (\fIArgumentType.String\fP) \-\- interface implemented by the object │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBversion\fP (\fIArgumentType.Uint\fP) \-\- interface version │ │ │ │ │ -.UNINDENT │ │ │ │ │ +\fBcapabilities\fP (\fIArgumentType.Uint\fP) \-\- capabilities of the seat │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B global_remove(name: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B name(name: \(aqstr\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ Event \-\- opcode 1 (attached to \fBProxy\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Announce removal of global object │ │ │ │ │ -.sp │ │ │ │ │ -Notify the client of removed global objects. │ │ │ │ │ -.sp │ │ │ │ │ -This event notifies the client that the global identified by name is no │ │ │ │ │ -longer available. If the client bound to the global using the bind │ │ │ │ │ -request, the client should now destroy that object. │ │ │ │ │ -.sp │ │ │ │ │ -The object remains valid and requests to the object will be ignored │ │ │ │ │ -until the client destroys it, to avoid races between the global going │ │ │ │ │ -away and a client sending a request to it. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -\fBname\fP (\fIArgumentType.Uint\fP) \-\- numeric name of the global object │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.SS WlDataDeviceManager │ │ │ │ │ -.INDENT 0.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlDataDeviceManager │ │ │ │ │ -Data transfer interface │ │ │ │ │ -.sp │ │ │ │ │ -The \fI\%WlDataDeviceManager\fP is a singleton global object that provides │ │ │ │ │ -access to inter\-client data transfer mechanisms such as copy\-and\-paste and │ │ │ │ │ -drag\-and\-drop. These mechanisms are tied to a │ │ │ │ │ -\fI\%WlSeat\fP and this interface lets a │ │ │ │ │ -client get a \fI\%WlDataDevice\fP │ │ │ │ │ -corresponding to a \fI\%WlSeat\fP\&. │ │ │ │ │ -.sp │ │ │ │ │ -Depending on the version bound, the objects created from the bound │ │ │ │ │ -\fI\%WlDataDeviceManager\fP object will have different requirements for │ │ │ │ │ -functioning properly. See \fI\%WlDataSource.set_actions()\fP, │ │ │ │ │ -\fI\%WlDataOffer.accept()\fP and │ │ │ │ │ -\fI\%WlDataOffer.finish()\fP for details. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B create_data_source() -> \(aqProxy[WlDataSource]\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ +Unique identifier for this seat │ │ │ │ │ .sp │ │ │ │ │ -Create a new data source │ │ │ │ │ +In a multi\-seat configuration the seat name can be used by clients to │ │ │ │ │ +help identify which physical devices the seat represents. │ │ │ │ │ .sp │ │ │ │ │ -Create a new data source. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Returns │ │ │ │ │ -\fI\%WlDataSource\fP \-\- data source to │ │ │ │ │ -create │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B get_data_device(seat: \(aqWlSeat\(aq) -> \(aqProxy[WlDataDevice]\(aq │ │ │ │ │ +The seat name is a UTF\-8 string with no convention defined for its │ │ │ │ │ +contents. Each name is unique among all \fI\%WlSeat\fP globals. The │ │ │ │ │ +name is only guaranteed to be unique for the current compositor │ │ │ │ │ +instance. │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ +The same seat names are used for all clients. Thus, the name can be │ │ │ │ │ +shared across processes to refer to a specific \fI\%WlSeat\fP global. │ │ │ │ │ .sp │ │ │ │ │ -Create a new data device │ │ │ │ │ +The name event is sent after binding to the seat global. This event is │ │ │ │ │ +only sent once per seat object, and the name does not change over the │ │ │ │ │ +lifetime of the \fI\%WlSeat\fP global. │ │ │ │ │ .sp │ │ │ │ │ -Create a new data device for a given seat. │ │ │ │ │ +Compositors may re\-use the same seat name if the \fI\%WlSeat\fP global │ │ │ │ │ +is destroyed and re\-created later. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -\fBseat\fP (\fI\%WlSeat\fP) \-\- seat associated with the data device │ │ │ │ │ -.TP │ │ │ │ │ -.B Returns │ │ │ │ │ -\fI\%WlDataDevice\fP \-\- data device to │ │ │ │ │ -create │ │ │ │ │ +\fBname\fP (\fIArgumentType.String\fP) \-\- seat identifier │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .SS WlShell │ │ │ │ │ .INDENT 0.0 │ │ │ │ │ .TP │ │ │ │ │ .B class pywayland.protocol.wayland.WlShell │ │ │ │ │ @@ -4787,277 +4902,162 @@ │ │ │ │ │ .TP │ │ │ │ │ .B Returns │ │ │ │ │ \fI\%WlShellSurface\fP \-\- shell │ │ │ │ │ surface to create │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ -.SS WlShm │ │ │ │ │ +.SS WlRegion │ │ │ │ │ .INDENT 0.0 │ │ │ │ │ .TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlShm │ │ │ │ │ -Shared memory support │ │ │ │ │ -.sp │ │ │ │ │ -A singleton global object that provides support for shared memory. │ │ │ │ │ +.B class pywayland.protocol.wayland.WlRegion │ │ │ │ │ +Region interface │ │ │ │ │ .sp │ │ │ │ │ -Clients can create \fI\%WlShmPool\fP objects │ │ │ │ │ -using the create_pool request. │ │ │ │ │ +A region object describes an area. │ │ │ │ │ .sp │ │ │ │ │ -On binding the \fI\%WlShm\fP object one or more format events are emitted │ │ │ │ │ -to inform clients about the valid pixel formats that can be used for │ │ │ │ │ -buffers. │ │ │ │ │ +Region objects are used to describe the opaque and input regions of a │ │ │ │ │ +surface. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B create_pool(fd: \(aqint\(aq, size: \(aqint\(aq) -> \(aqProxy[WlShmPool]\(aq │ │ │ │ │ +.B destroy() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Create a shm pool │ │ │ │ │ -.sp │ │ │ │ │ -Create a new \fI\%WlShmPool\fP object. │ │ │ │ │ +Destroy region │ │ │ │ │ .sp │ │ │ │ │ -The pool can be used to create shared memory based buffer objects. The │ │ │ │ │ -server will mmap size bytes of the passed file descriptor, to use as │ │ │ │ │ -backing memory for the pool. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBfd\fP (\fIArgumentType.FileDescriptor\fP) \-\- file descriptor for the pool │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBsize\fP (\fIArgumentType.Int\fP) \-\- pool size, in bytes │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.TP │ │ │ │ │ -.B Returns │ │ │ │ │ -\fI\%WlShmPool\fP \-\- pool to create │ │ │ │ │ -.UNINDENT │ │ │ │ │ +Destroy the region. This will invalidate the object ID. │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B release() -> \(aqNone\(aq │ │ │ │ │ +.B add(x: \(aqint\(aq, y: \(aqint\(aq, width: \(aqint\(aq, height: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Release the shm object │ │ │ │ │ -.sp │ │ │ │ │ -Using this request a client can tell the server that it is not going to │ │ │ │ │ -use the shm object anymore. │ │ │ │ │ -.sp │ │ │ │ │ -Objects created via this interface remain unaffected. │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B format(format: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Pixel format description │ │ │ │ │ +Add rectangle to region │ │ │ │ │ .sp │ │ │ │ │ -Informs the client about a valid pixel format that can be used for │ │ │ │ │ -buffers. Known formats include argb8888 and xrgb8888. │ │ │ │ │ +Add the specified rectangle to the region. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -\fBformat\fP (\fIArgumentType.Uint\fP) \-\- buffer pixel format │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.SS WlDisplay │ │ │ │ │ -.INDENT 0.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlDisplay │ │ │ │ │ -Core global object │ │ │ │ │ -.sp │ │ │ │ │ -The core global object. This is a special singleton object. It is used │ │ │ │ │ -for internal Wayland protocol features. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B sync() -> \(aqProxy[WlCallback]\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Asynchronous roundtrip │ │ │ │ │ -.sp │ │ │ │ │ -The sync request asks the server to emit the \(aqdone\(aq event on the │ │ │ │ │ -returned \fI\%WlCallback\fP object. Since │ │ │ │ │ -requests are handled in\-order and events are delivered in\-order, this │ │ │ │ │ -can be used as a barrier to ensure all previous requests and the │ │ │ │ │ -resulting events have been handled. │ │ │ │ │ -.sp │ │ │ │ │ -The object returned by this request will be destroyed by the compositor │ │ │ │ │ -after the callback is fired and as such the client must not attempt to │ │ │ │ │ -use it after that point. │ │ │ │ │ -.sp │ │ │ │ │ -The callback_data passed in the callback is undefined and should be │ │ │ │ │ -ignored. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Returns │ │ │ │ │ -\fI\%WlCallback\fP \-\- callback object │ │ │ │ │ -for the sync request │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBx\fP (\fIArgumentType.Int\fP) \-\- region\-local x coordinate │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBy\fP (\fIArgumentType.Int\fP) \-\- region\-local y coordinate │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBwidth\fP (\fIArgumentType.Int\fP) \-\- rectangle width │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBheight\fP (\fIArgumentType.Int\fP) \-\- rectangle height │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B get_registry() -> \(aqProxy[WlRegistry]\(aq │ │ │ │ │ -.sp │ │ │ │ │ -Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ -.sp │ │ │ │ │ -Get global registry object │ │ │ │ │ -.sp │ │ │ │ │ -This request creates a registry object that allows the client to list │ │ │ │ │ -and bind the global objects available from the compositor. │ │ │ │ │ -.sp │ │ │ │ │ -It should be noted that the server side resources consumed in response │ │ │ │ │ -to a get_registry request can only be released when the client │ │ │ │ │ -disconnects, not when the client side proxy is destroyed. Therefore, │ │ │ │ │ -clients should invoke get_registry as infrequently as possible to avoid │ │ │ │ │ -wasting memory. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Returns │ │ │ │ │ -\fI\%WlRegistry\fP \-\- global registry │ │ │ │ │ -object │ │ │ │ │ -.UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B error(object_id: \(aqAny\(aq, code: \(aqint\(aq, message: \(aqstr\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B subtract(x: \(aqint\(aq, y: \(aqint\(aq, width: \(aqint\(aq, height: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 0 (attached to \fBProxy\fP instance) │ │ │ │ │ +Request \-\- opcode 2 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Fatal error event │ │ │ │ │ +Subtract rectangle from region │ │ │ │ │ .sp │ │ │ │ │ -The error event is sent out when a fatal (non\-recoverable) error has │ │ │ │ │ -occurred. The object_id argument is the object where the error │ │ │ │ │ -occurred, most often in response to a request to that object. The code │ │ │ │ │ -identifies the error and is defined by the object interface. As such, │ │ │ │ │ -each interface defines its own set of error codes. The message is a │ │ │ │ │ -brief description of the error, for (debugging) convenience. │ │ │ │ │ +Subtract the specified rectangle from the region. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBobject_id\fP (\fIArgumentType.Object\fP) \-\- object where the error occurred │ │ │ │ │ +\fBx\fP (\fIArgumentType.Int\fP) \-\- region\-local x coordinate │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBcode\fP (\fIArgumentType.Uint\fP) \-\- error code │ │ │ │ │ +\fBy\fP (\fIArgumentType.Int\fP) \-\- region\-local y coordinate │ │ │ │ │ .IP \(bu 2 │ │ │ │ │ -\fBmessage\fP (\fIArgumentType.String\fP) \-\- error description │ │ │ │ │ +\fBwidth\fP (\fIArgumentType.Int\fP) \-\- rectangle width │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBheight\fP (\fIArgumentType.Int\fP) \-\- rectangle height │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.SS WlSubcompositor │ │ │ │ │ +.INDENT 0.0 │ │ │ │ │ .TP │ │ │ │ │ -.B delete_id(id: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +.B class pywayland.protocol.wayland.WlSubcompositor │ │ │ │ │ +Sub\-surface compositing │ │ │ │ │ .sp │ │ │ │ │ -Event \-\- opcode 1 (attached to \fBProxy\fP instance) │ │ │ │ │ +The global interface exposing sub\-surface compositing capabilities. A │ │ │ │ │ +\fI\%WlSurface\fP, that has sub\-surfaces │ │ │ │ │ +associated, is called the parent surface. Sub\-surfaces can be arbitrarily │ │ │ │ │ +nested and create a tree of sub\-surfaces. │ │ │ │ │ .sp │ │ │ │ │ -Acknowledge object id deletion │ │ │ │ │ +The root surface in a tree of sub\-surfaces is the main surface. The main │ │ │ │ │ +surface cannot be a sub\-surface, because sub\-surfaces must always have a │ │ │ │ │ +parent. │ │ │ │ │ .sp │ │ │ │ │ -This event is used internally by the object ID management logic. When a │ │ │ │ │ -client deletes an object that it had created, the server will send this │ │ │ │ │ -event to acknowledge that it has seen the delete request. When the │ │ │ │ │ -client receives this event, it will know that it can safely reuse the │ │ │ │ │ -object ID. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -\fBid\fP (\fIArgumentType.Uint\fP) \-\- deleted object ID │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.SS WlShmPool │ │ │ │ │ -.INDENT 0.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B class pywayland.protocol.wayland.WlShmPool │ │ │ │ │ -A shared memory pool │ │ │ │ │ +A main surface with its sub\-surfaces forms a (compound) window. For window │ │ │ │ │ +management purposes, this set of │ │ │ │ │ +\fI\%WlSurface\fP objects is to be considered │ │ │ │ │ +as a single window, and it should also behave as such. │ │ │ │ │ .sp │ │ │ │ │ -The \fI\%WlShmPool\fP object encapsulates a piece of memory shared between │ │ │ │ │ -the compositor and client. Through the \fI\%WlShmPool\fP object, the │ │ │ │ │ -client can allocate shared memory │ │ │ │ │ -\fI\%WlBuffer\fP objects. All objects created │ │ │ │ │ -through the same pool share the same underlying mapped memory. Reusing the │ │ │ │ │ -mapped memory avoids the setup/teardown overhead and is useful when │ │ │ │ │ -interactively resizing a surface or for many small buffers. │ │ │ │ │ +The aim of sub\-surfaces is to offload some of the compositing work within a │ │ │ │ │ +window from clients to the compositor. A prime example is a video player │ │ │ │ │ +with decorations and video in separate │ │ │ │ │ +\fI\%WlSurface\fP objects. This should allow │ │ │ │ │ +the compositor to pass YUV video buffer processing to dedicated overlay │ │ │ │ │ +hardware when possible. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B create_buffer(offset: \(aqint\(aq, width: \(aqint\(aq, height: \(aqint\(aq, stride: \(aqint\(aq, format: \(aqint\(aq) -> \(aqProxy[WlBuffer]\(aq │ │ │ │ │ +.B destroy() -> \(aqNone\(aq │ │ │ │ │ .sp │ │ │ │ │ Request \-\- opcode 0 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Create a buffer from the pool │ │ │ │ │ -.sp │ │ │ │ │ -Create a \fI\%WlBuffer\fP object from the │ │ │ │ │ -pool. │ │ │ │ │ -.sp │ │ │ │ │ -The buffer is created offset bytes into the pool and has width and │ │ │ │ │ -height as specified. The stride argument specifies the number of bytes │ │ │ │ │ -from the beginning of one row to the beginning of the next. The format │ │ │ │ │ -is the pixel format of the buffer and must be one of those advertised │ │ │ │ │ -through the \fI\%WlShm.format()\fP event. │ │ │ │ │ +Unbind from the subcompositor interface │ │ │ │ │ .sp │ │ │ │ │ -A buffer will keep a reference to the pool it was created from so it is │ │ │ │ │ -valid to destroy the pool immediately after creating a buffer from it. │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B Parameters │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBoffset\fP (\fIArgumentType.Int\fP) \-\- buffer byte offset within the pool │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBwidth\fP (\fIArgumentType.Int\fP) \-\- buffer width, in pixels │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBheight\fP (\fIArgumentType.Int\fP) \-\- buffer height, in pixels │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBstride\fP (\fIArgumentType.Int\fP) \-\- number of bytes from the beginning of one row to the beginning of │ │ │ │ │ -the next row │ │ │ │ │ -.IP \(bu 2 │ │ │ │ │ -\fBformat\fP (\fIArgumentType.Uint\fP) \-\- buffer pixel format │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.TP │ │ │ │ │ -.B Returns │ │ │ │ │ -\fI\%WlBuffer\fP \-\- buffer to create │ │ │ │ │ -.UNINDENT │ │ │ │ │ +Informs the server that the client will not be using this protocol │ │ │ │ │ +object anymore. This does not affect any other objects, │ │ │ │ │ +\fI\%WlSubsurface\fP objects included. │ │ │ │ │ .UNINDENT │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ -.B destroy() -> \(aqNone\(aq │ │ │ │ │ +.B get_subsurface(surface: \(aqWlSurface\(aq, parent: \(aqWlSurface\(aq) -> \(aqProxy[WlSubsurface]\(aq │ │ │ │ │ .sp │ │ │ │ │ Request \-\- opcode 1 (attached to \fBResource\fP instance) │ │ │ │ │ .sp │ │ │ │ │ -Destroy the pool │ │ │ │ │ -.sp │ │ │ │ │ -Destroy the shared memory pool. │ │ │ │ │ +Give a surface the role sub\-surface │ │ │ │ │ .sp │ │ │ │ │ -The mmapped memory will be released when all buffers that have been │ │ │ │ │ -created from this pool are gone. │ │ │ │ │ -.UNINDENT │ │ │ │ │ -.INDENT 7.0 │ │ │ │ │ -.TP │ │ │ │ │ -.B resize(size: \(aqint\(aq) -> \(aqNone\(aq │ │ │ │ │ +Create a sub\-surface interface for the given surface, and associate it │ │ │ │ │ +with the given parent surface. This turns a plain │ │ │ │ │ +\fI\%WlSurface\fP into a sub\-surface. │ │ │ │ │ .sp │ │ │ │ │ -Request \-\- opcode 2 (attached to \fBResource\fP instance) │ │ │ │ │ +The to\-be sub\-surface must not already have another role, and it must │ │ │ │ │ +not have an existing \fI\%WlSubsurface\fP │ │ │ │ │ +object. Otherwise the bad_surface protocol error is raised. │ │ │ │ │ .sp │ │ │ │ │ -Change the size of the pool mapping │ │ │ │ │ +Adding sub\-surfaces to a parent is a double\-buffered operation on the │ │ │ │ │ +parent (see \fI\%WlSurface.commit()\fP). The effect of adding a │ │ │ │ │ +sub\-surface becomes visible on the next time the state of the parent │ │ │ │ │ +surface is applied. │ │ │ │ │ .sp │ │ │ │ │ -This request will cause the server to remap the backing memory for the │ │ │ │ │ -pool from the file descriptor passed when the pool was created, but │ │ │ │ │ -using the new size. This request can only be used to make the pool │ │ │ │ │ -bigger. │ │ │ │ │ +The parent surface must not be one of the child surface\(aqs descendants, │ │ │ │ │ +and the parent must be different from the child surface, otherwise the │ │ │ │ │ +bad_parent protocol error is raised. │ │ │ │ │ .sp │ │ │ │ │ -This request only changes the amount of bytes that are mmapped by the │ │ │ │ │ -server and does not touch the file corresponding to the file descriptor │ │ │ │ │ -passed at creation time. It is the client\(aqs responsibility to ensure │ │ │ │ │ -that the file is at least as big as the new pool size. │ │ │ │ │ +This request modifies the behaviour of \fI\%WlSurface.commit()\fP request on the sub\- │ │ │ │ │ +surface, see the documentation on │ │ │ │ │ +\fI\%WlSubsurface\fP interface. │ │ │ │ │ .INDENT 7.0 │ │ │ │ │ .TP │ │ │ │ │ .B Parameters │ │ │ │ │ -\fBsize\fP (\fIArgumentType.Int\fP) \-\- new size of the pool, in bytes │ │ │ │ │ +.INDENT 7.0 │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBsurface\fP (\fI\%WlSurface\fP) \-\- the surface to be turned into a sub\-surface │ │ │ │ │ +.IP \(bu 2 │ │ │ │ │ +\fBparent\fP (\fI\%WlSurface\fP) \-\- the parent surface │ │ │ │ │ +.UNINDENT │ │ │ │ │ +.TP │ │ │ │ │ +.B Returns │ │ │ │ │ +\fI\%WlSubsurface\fP \-\- the new sub\- │ │ │ │ │ +surface object ID │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .UNINDENT │ │ │ │ │ .SS Scanner Modules │ │ │ │ │ .SS Argumet │ │ │ │ │ .INDENT 0.0 │ │ │ │ │ .TP