fdo-mirrors/wayland-protocols
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/wayland/wayland-protocols.git synced 2025-12-20 08:10:07 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

staging/color-management: add ready2 event

Browse source 
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 <pekka.paalanen@collabora.com>
This commit is contained in:
Pekka Paalanen 2025-03-10 15:22:54 +02:00 • committed by Pekka Paalanen
parent b0b1010301
commit 1a6f2cec71
1 changed files with 79 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

122
staging/color-management/color-management-v1.xml
View file

@ -739,27 +739,14 @@
summary="attempted to use an unsupported feature"/>
</enum>
<event name="preferred_changed">
<description summary="the preferred image description changed">
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
<event name="preferred_changed" deprecated-since="2">
<description summary="the preferred image description changed (32-bit)">
Starting from interface version 2, 'preferred_changed2' is sent instead
of this event. See the 'preferred_changed2' event for the definition.
</description>
<arg name="identity" type="uint" summary="image description id number"/>
<arg name="identity" type="uint"
summary="the 32-bit image description id number"/>
</event>
<request name="get_preferred">
@ -816,6 +803,35 @@
<arg name="image_description"
type="new_id" interface="wp_image_description_v1"/>
</request>
<!-- Version 2 additions -->
<event name="preferred_changed2" since="2">
<description summary="the preferred image description changed">
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
</description>
<arg name="identity_hi" type="uint"
summary="high 32 bits of the 64-bit image description id number"/>
<arg name="identity_lo" type="uint"
summary="low 32 bits of the 64-bit image description id number"/>
</event>
</interface>
<interface name="wp_image_description_creator_icc_v1" version="2">
@ -1385,38 +1401,22 @@
summary="ad hoc human-readable explanation"/>
</event>
<event name="ready">
<description summary="indication that the object is ready to be used">
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.
<event name="ready" deprecated-since="2">
<description summary="the object is ready to be used (32-bit)">
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.
</description>
<arg name="identity" type="uint" summary="image description id number"/>
<arg name="identity" type="uint"
summary="the 32-bit image description id number"/>
</event>
<request name="get_information">
@ -1433,6 +1433,42 @@
<arg name="information"
type="new_id" interface="wp_image_description_info_v1"/>
</request>
<!-- Version 2 additions -->
<event name="ready2" since="2">
<description summary="the object is ready to be used">
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.
</description>
<arg name="identity_hi" type="uint"
summary="high 32 bits of the 64-bit image description id number"/>
<arg name="identity_lo" type="uint"
summary="low 32 bits of the 64-bit image description id number"/>
</event>
</interface>
<interface name="wp_image_description_info_v1" version="2">