From 1a6f2cec714d3462400ccfc5354c81f01da56ae8 Mon Sep 17 00:00:00 2001 From: Pekka Paalanen Date: Mon, 10 Mar 2025 15:22:54 +0200 Subject: [PATCH] staging/color-management: add ready2 event A 32-bit image description identity number could theoretically wrap around in 1.4 years if a new one is allocated 100 times per second. Compositors that avoid 32-bit wrap-around are allowed to aggressively recycle numbers, which poses a requirement on clients to hold on to the image description object in order to keep its number live. Clients might not do so regardless of documentation, and on compositors that recycle only after wrap-around clients would not see any problems. This could cause strange issues in clients on former kind of compositors. In order to avoid all that, introduce a new 64-bit image description identity number which has no fear of wrap-around, and require such numbers to be never recycled. This makes the compositor number allocator trivial, and clients are more likely to handle it correctly by accident. Fixes: https://gitlab.freedesktop.org/wayland/wayland-protocols/-/issues/246 Signed-off-by: Pekka Paalanen --- .../color-management/color-management-v1.xml | 122 ++++++++++++------ 1 file changed, 79 insertions(+), 43 deletions(-) diff --git a/staging/color-management/color-management-v1.xml b/staging/color-management/color-management-v1.xml index 879ba39..1312ac3 100644 --- a/staging/color-management/color-management-v1.xml +++ b/staging/color-management/color-management-v1.xml @@ -739,27 +739,14 @@ summary="attempted to use an unsupported feature"/> - - - The preferred image description is the one which likely has the most - performance and/or quality benefits for the compositor if used by the - client for its wl_surface contents. This event is sent whenever the - compositor changes the wl_surface's preferred image description. - - This event sends the identity of the new preferred state as the argument, - so clients who are aware of the image description already can reuse it. - Otherwise, if the client client wants to know what the preferred image - description is, it shall use the get_preferred request. - - The preferred image description is not automatically used for anything. - It is only a hint, and clients may set any valid image description with - set_image_description, but there might be performance and color accuracy - improvements by providing the wl_surface contents in the preferred - image description. Therefore clients that can, should render according - to the preferred image description + + + Starting from interface version 2, 'preferred_changed2' is sent instead + of this event. See the 'preferred_changed2' event for the definition. - + @@ -816,6 +803,35 @@ + + + + + + The preferred image description is the one which likely has the most + performance and/or quality benefits for the compositor if used by the + client for its wl_surface contents. This event is sent whenever the + compositor changes the wl_surface's preferred image description. + + This event sends the identity of the new preferred state as the argument, + so clients who are aware of the image description already can reuse it. + Otherwise, if the client client wants to know what the preferred image + description is, it shall use the get_preferred request. + + The preferred image description is not automatically used for anything. + It is only a hint, and clients may set any valid image description with + set_image_description, but there might be performance and color accuracy + improvements by providing the wl_surface contents in the preferred + image description. Therefore clients that can, should render according + to the preferred image description + + + + + + @@ -1385,38 +1401,22 @@ summary="ad hoc human-readable explanation"/> - - - Once this event has been sent, the wp_image_description_v1 object is - deemed "ready". Ready objects can be used to send requests and can be - used through other interfaces. + + + Starting from interface version 2, the 'ready2' event is sent instead + of this event. - Every ready wp_image_description_v1 protocol object refers to an - underlying image description record in the compositor. Multiple protocol - objects may end up referring to the same record. Clients may identify - these "copies" by comparing their id numbers: if the numbers from two - protocol objects are identical, the protocol objects refer to the same - image description record. Two different image description records - cannot have the same id number simultaneously. The id number does not - change during the lifetime of the image description record. + For the definition of this event, see the 'ready2' event. The + difference to this event is as follows. The id number is valid only as long as the protocol object is alive. If all protocol objects referring to the same image description record are destroyed, the id number may be recycled for a different image description record. - - Image description id number is not a protocol object id. Zero is - reserved as an invalid id number. It shall not be possible for a client - to refer to an image description by its id number in protocol. The id - numbers might not be portable between Wayland connections. A compositor - shall not send an invalid id number. - - This identity allows clients to de-duplicate image description records - and avoid get_information request if they already have the image - description information. - + @@ -1433,6 +1433,42 @@ + + + + + + Once this event has been sent, the wp_image_description_v1 object is + deemed "ready". Ready objects can be used to send requests and can be + used through other interfaces. + + Every ready wp_image_description_v1 protocol object refers to an + underlying image description record in the compositor. Multiple protocol + objects may end up referring to the same record. Clients may identify + these "copies" by comparing their id numbers: if the numbers from two + protocol objects are identical, the protocol objects refer to the same + image description record. Two different image description records + cannot have the same id number simultaneously. The id number does not + change during the lifetime of the image description record. + + Image description id number is not a protocol object id. Zero is + reserved as an invalid id number. It shall not be possible for a client + to refer to an image description by its id number in protocol. The id + numbers might not be portable between Wayland connections. A compositor + shall not send an invalid id number. + + Compositors must not recycle image description id numbers. + + This identity allows clients to de-duplicate image description records + and avoid get_information request if they already have the image + description information. + + + + +