Note that wp_image_description_v1 is not a frozen interface. Therefore
it must always be a descendant of wp_color_manager_v1.
In order to allow other protocols, such as ext-image-capture-source-v1,
to define the equivalent of
wp_color_management_output_v1.get_image_description, we must therefore
create an indirection between the new protocol and
wp_image_description_v1 that is resolved through wp_color_manager_v1
itself.
This is a prerequisite for adding color management support to the
ext-image-copy-capture-v1 protocol.
Signed-off-by: Julian Orth <ju.orth@gmail.com>
ICC-based calibrated print workflows have generally used the sRGB
two-piece transfer characteristic. The CRT era monitors were exclusively
power curve, but print workflows used software calibration to meet the
two-piece curve. Everyone else used the monitor native transfer
characteristic.
Acknowledge that both ways exist, and allow describing both as what they
are.
Mesa is already using "srgb" if it is available, for programs that
actually expect gamma22. Exposing "srgb" with its literal definition
would make a compositor (KWin has been named) appear regressing in
picture quality. The same with "ext_srgb" as Mesa used to map
VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT to it, probably incorrectly.
sRGB is specified to use a power-law 2.2 display, and reality is not
consistent. Some compositors take srgb to mean gamma22 already, so there
is practical ambiguity. There are also endless discussions about which
one sRGB actually is and when: power-law 2.2 or the piece-wise function.
Monitors are manufactured both ways and they are often even switchable
between the two. Therefore deprecate the "srgb" value, it is too easy to
pick and assume one behavior while someone else assumes the other
behavior.
Additionally, extending the range beyond 1.0 would significantly diverge
between srgb and gamma22 because of the different exponent. Assuming
that ext_srgb is identical to srgb for [0.0, 1.0] would conflict with a
compositor that takes srgb as gamma22 but implements ext_srgb by the
piece-wise function.
Given that monitors with the piece-wise function exist or are calibrated
to it, and materials are prepared on them, add a new value explicitly
for the sRGB piece-wise function. Its name deliberately does not include
"srgb".
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
This rendering intent is a modified absolute rendering intent that
assumes the viewer is not adapted to the display white point, so no
white point adaptation between surface and display is done.
This can be useful for color proofing applications.
Signed-off-by: Xaver Hugl <xaver.hugl@kde.org>
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>
ANSI/CTA-861-H does not require that maxCLL or maxFALL be within the
Mastering Display Luminance range, and it is common for movies to have a
maxCLL greater than the Mastering Display Luminance. Additionally,
Microsoft's own documentation* contains an example that does not pass
the restriction in the protocol. These values are valid, used in the
real world, and clients should not need to discard them. We keep the
requirement that maxFALL <= maxCLL since that is required, but these
values have no relation to the Mastering Display Luminance.
See #263 for further details on why the restriction on maxCLL and
maxFALL is not desirable. Fixes#263.
*: https://learn.microsoft.com/en-us/windows/win32/api/dxgi1_5/ns-dxgi1_5-dxgi_hdr_metadata_hdr10
Signed-off-by: Dudemanguy <random342@airmail.cc>
In an attempt to specify clipping behavior[1] it was found that it would
lead to predictable behavior turning into undefined behavior when a
compositor gains support for extended_color_volume. That would be
awkward.
Instead of specifying clipping to the primary color volume bounds (which
may then disappear), let's leave it undefined, and emphasize the
undefined-ness of exceeding the target color volume instead.
[1]: https://gitlab.freedesktop.org/wayland/wayland-protocols/-/merge_requests/453
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Make the connection between parametric image descriptions and Display
class ICC profiles, for clarity.
Suggested-by: Dmitry Kazakov (@dimula73)
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
The adaptation state of the viewer is required for interpreting colors, and
specifically for adapting them to a different white point. This commit defines
it to match existing implementations and display class ICC profiles:
The viewer is assumed to be fully adapted to the primary color volume's white
point.
The mastering display white point is not used for this, as it is both somewhat
unlikely to be relevant for the adaptation state of the content creator, and
also relatively likely to be incorrect in existing images, videos and games.
Signed-off-by: Xaver Hugl <xaver.hugl@kde.org>
It is not possible to write equations nicely in the XML, so we need an
appendix.
First, the appendix explicitly defines the transfer functions that the
protocol enumeration refers to. Leaving them to be inferred from the
ITU-R and other specifications was too confusing.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
References to H.273 are confusing people:
https://gitlab.freedesktop.org/wayland/wayland-protocols/-/merge_requests/442#note_3079717
The confusion arises from H.273 usually referring to encoding standards
which only indirectly define a reference display. Wayland
color-management is only interested in the displays.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
The BT.1886 recommendation is impossible to implement precisely if
min_lum includes other sources than the display emission. BT.1886
transfer function requires L_W and L_B to determine the function
parameters black level lift and gain. The black level lift changes the
non-linearity, and cannot be implemented as an optical addition.
I believe the inclusion of optical additives, particularly the ambient
flare, came from sRGB specification. I do not recall seeing it anywhere
else.
Drop the optical additives from the definitions of the luminances. It
was probably incorrect for everything but sRGB, if they even had it
specified at all. This allows implementing BT.1886 as specified.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Clients are allowed to send any value from the enum (unlike other
requests where only supported values are allowed), however clients
are not allowed to send out-of-enum values.
Signed-off-by: Simon Ser <contact@emersion.fr>
The value was zero because the enum was not a bitfield at some point when the protocol was
developed and I forgot to change the value to one when making it a bitfield.
This is technically a breaking change, but as the client could never receive the blur
capability before this commit, it won't actually break anything - it was already broken.
Signed-off-by: Xaver Hugl <xaver.hugl@kde.org>
This global interface allows applications to request the pointer
to be moved to a position relative to a wl_surface.
Co-authored-by: Xaver Hugl <xaver.hugl@kde.org>
Co-authored-by: Matthias Klumpp <matthias@tenstral.net>
Co-authored-by: Vlad Zahorodnii <vlad.zahorodnii@kde.org>
Signed-off-by: Neal Gompa <neal@gompa.dev>
Reviewed-by: Vlad Zahorodnii <vlad.zahorodnii@kde.org>
https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/wayland_qa.md#q-should-srgb-content-be-decoded-with-the-piecewise-srgb-transfer-function
I found it unfortunate that we left in a TF code that will intuitively
be used incorrectly. It is as if we designed the protocol so that
compositors will need to fix up client image descriptions.
I am not aware of any use case that would want to target a display with
the sRGB piece-wise transfer function, that would be a non-standard
display.
This patch does not help compositors avoid needing to second-guess
client image descriptions using srgb TF, but it at least documents the
situation. We could choose to out-law srgb TF in a minor version bump,
or drop it completely in the next major version. Compositors can also
not advertise support for srgb TF.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
This protocol allows the client to specify a region behind the surface that should
be blurred, with the intention to improve the visuals of for example panels or
terminals.
This protocol is roughly based on the org_kde_kwin_blur protocol, which has been
in use since 2015. The protocol is made more generically though, so that other
related effects can be added in the future, like for example contrast improvements.
Signed-off-by: Xaver Hugl <xaver.hugl@kde.org>
This new protocol aims to let clients define the remaining bits of the color
encoding they are using in their buffers.
In particular, this lets clients define the how the alpha has been encoded and
how conversions from YCbCr to RGB take place.
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
Co-authored-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Co-authored-by: Robert Mader <robert.mader@collabora.com>
Co-authored-by: Sebastian Wick <sebastian.wick@redhat.com>
Co-authored-by: Simon Ser <contact@emersion.fr>
Co-authored-by: Xaver Hugl <xaver.hugl@kde.org>
The window id protocol allows clients to set a tag for toplevels, which
the compositor can use to identify them even after the application
has been restarted. This persistent identification can be used by the
compositor to restore properties like position, size, "always on top",
and it can also be used for allowing users to create rules that change
compositor behavior for specific windows.
Signed-off-by: Xaver Hugl <xaver.hugl@kde.org>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
The move cursor is ambiguous, since it is used in two context:
for DND, and for resizing. This commit adds a separate enum
value for a cursor that indicates something can be resized
in all directions. A suitable image for this value is a four-headed
arrow.
Signed-off-by: Matthias Clasen <mclasen@redhat.com>
This is the cursor shape that corresponds to the ASK drag action
in the core protocol. The expected semantics of ASK are that the
drop target presents the user with a choice of actions when the
drop happens. A typical image for this cursor is a default cursor
with a '?' emblem.
Signed-off-by: Matthias Clasen <mclasen@redhat.com>
Add some hints about related groups of cursor shapes and recommend
that they should use visually compatible images.
Signed-off-by: Matthias Clasen <mclasen@redhat.com>
Niels' efforts predate Sebastian's by another 5 years and they deserve
to be mentioned.
Sorry for missing them from the commit.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
# Wayland Color Management and HDR Design Goals
The goals of Wayland color management and *high dynamic range* (HDR) support
protocol extension are:
- Reliably maintain the display server color setup.
- Support professional color managed applications (presentation).
- Support displaying TV broadcasts and other high quality video content.
- Support a wide variety of monitors and application content,
including wide gamut and/or HDR.
- Bring basic color management to applications that are not color-aware at all.
- Bring adequate color management to Wayland applications that are color-aware
but not color managed.
Once a display system has been calibrated, measured and configured, it should
keep its settings until the user intentionally changes them. Achieving this
reliability requires protecting the system from accidental changes and avoiding
dependency on hardware default state as much as possible. The former is done by
not allowing arbitrary programs to change the settings. The latter is realized
by very careful Wayland compositor implementation that takes into account the
details of the underlying system API. For example, with DRM also unrecognized
KMS properties need to be saved and restored.
It should be reasonably possible to run existing color managed applications,
particularly X11 applications through Xwayland, without need for modification
and get at least the level of color managed presentation features they received
on Xorg. It is possible that this requires e.g. re-creating monitor color profiles,
recalibration, or other reconfiguring.
The use of `xrandr` and similar X11 tools and interfaces are intentionally
not supported as the Wayland desktop paradigm does not allow clients to force
effects on other clients. Those global properties, including video mode
and display color depth, are left to each Wayland compositor's own settings
management as they are end user preferences.
The protocol extension should be usable for professional broadcast display
usage, meaning that it is suitable for use inside a television for all of
aerial, cable, and internet delivered content. However, the extension might not
be completely sufficient, particularly where it would violate the Wayland
desktop paradigm (e.g. requests to change display video mode or calibration
shall not be included).
The support for a wide variety of monitors is achieved by communicating sufficient
information about the monitors to applications, so that applications can adapt
to the monitors if they choose to do so. The proper composition and handling of
a wide variety of application content is achieved by applications describing
the content in sufficient detail for a Wayland compositor to process it
correctly.
Applications that pay no mind whatsoever to color management are called
*color-unaware*. They have been written for an average system that more or less
resembles (or not) sRGB in its color output. This is the large majority of all
applications on X11 and Wayland. On a usual consumer monitor they look pretty
much ok, but on a color managed monitor with special features (wide gamut, HDR)
they might be an eye sore when displayed side by side with properly color
managed applications. A goal for Wayland color management is to make these
application look "pretty much ok" on such special monitors without
modifications to the applications or toolkits, while letting color managed
applications look their best simultaneously.
One step forward from color-unaware applications are *color-aware* applications
that also are not fully color managed applications. These applications are
fixed to one or few well-known color spaces, the traditional sRGB for instance.
They don't try to adapt to the monitor and they might not use any *color
management module* (CMM). These applications can still describe their content's
color space to a Wayland compositor, which will then take care of color managed
presentation of the content.
Finally, *color-managed* applications are fully prepared to do all of their own
color management, and may be using a CMM. They can also adapt their rendering
to different kinds of monitors, and prefer to know everything they can about a
monitor in order to do a perfect job. They expect the window system to not
tamper with the color values they produce.
The above goals imply that a Wayland compositor is an active participant in
color management, converting all application content into some common color
space for display on a monitor. As a compositor can do that separately for each
monitor, it is possible to present the same window adequately color managed on
multiple monitors simultaneously. It is also possible to keep a monitor in HDR
mode while showing both *standard dynamic range* (SDR) (traditional or
unmodified applications) and HDR content simultaneously. A practical use case
for that is a video player showing a HDR video on one Wayland surface and SDR
subtitles and user interface on another surface.
History
Wayland color management has been planned and developed for many years.
This patch is the result of 141 development patches which are stored for
future reference in the wayland-protocols branch history/color-management:
https://gitlab.freedesktop.org/wayland/wayland-protocols/-/commits/history/color-management
The development started some years even before this.
There have been many contributors over the years. The list below has
been collected from those 141 patches, and is surely incomplete.
Co-authored-by: Benjamin Otte <otte@redhat.com>
Co-authored-by: Bhawanpreet Lakha <Bhawanpreet.Lakha@amd.com>
Co-authored-by: Colin Marc <hi@colinmarc.com>
Co-authored-by: Dudemanguy <random342@airmail.cc>
Co-authored-by: Leandro Ribeiro <leandro.ribeiro@collabora.com>
Co-authored-by: Matthias Clasen <mclasen@redhat.com>
Co-authored-by: Naveen Kumar <naveen1.kumar@intel.com>
Co-authored-by: Sebastian Wick <sebastian.wick@redhat.com>
Co-authored-by: Timo Witte <timo.witte@gmail.com>
Co-authored-by: Victoria Brekenfeld <victoria@system76.com>
Co-authored-by: Vitaly Prosyak <vitaly.prosyak@amd.com>
Co-authored-by: Xaver Hugl <xaver.hugl@kde.org>
Signed-off-by: Sebastian Wick <sebastian@sebastianwick.net>
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Drew is no longer active in the Wayland community. Simon Zeni is
the wlroots point-of-contact and is very familiar with DRM leasing.
Signed-off-by: Simon Ser <contact@emersion.fr>
This protocol allows a privileged client to control data devices. In
particular, the client will be able to manage the current selection and take
the role of a clipboard manager.
This is a straight port from wlr-data-control-unstable-v1 to ext-, as it
has not changed in five years and has near-universal compositor adoption.
Signed-off-by: Neal Gompa <neal@gompa.dev>
Add a new protocol for adding timestamps to wayland surface state to
allow deferring processing until later.
Signed-off-by: Derek Foreman <derek.foreman@collabora.com>
Add a new protocol to allow a content update to require a
display refresh pass before it is ready to present.
Signed-off-by: Derek Foreman <derek.foreman@collabora.com>
This is meant to let applications ring the system bell. It needs to be a
Wayland protocol because a system bell is not necessarily audiable; for
for example accessibility reasons, it might need be a visual feedback,
which may be tied to a specific window. Accessibility features are
usually configured globally, and one likely wants identical visual
feedback for all system bell ringings, so it doesn't fit as a client
side only feature.
This aims to replaced and deprecate the `gtk_shell1.system_bell`
request.
Signed-off-by: Jonas Ådahl <jadahl@gmail.com>
It was undefined before how long the wp_cursor_shape_device_v1 has any
effect. Let's specify that the object becomes inert when the pointer cap
goes away or the tablet tool is removed. In those cases the client has
to create a new pointer/tablet tool, and also a new cursor shape device
when the cursor caps or a new tablet tool reappears.
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
Closes: https://gitlab.freedesktop.org/wayland/wayland-protocols/-/issues/186
The current description is not clear about it, though the only available
implementation works like that, so make it explicit in the protocol
description.
Signed-off-by: Nick Diego Yamane <nickdiego@igalia.com>
