In wp_color_management_surface_v1.set_image_description. Image
descriptions which have received neither failed nor ready are being
ignored by the current wording, making it undefined behavior.
Fix this by prohibiting image descriptions in all states other than
ready from being set on a surface.
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
This mostly reverts "color: st2084_pq dictates min/max_lum".
This aligns better with the improved definitions of minimum and maximum
luminance: they include display minimum emission and ambient flare.
Since the PQ EOTF has the range of [0.0, 10000.0] cd/m², require that to
be maintained so that max_lum - min_lum = EOTF range.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
'set_luminances' request is intended to reflect the viewing conditions,
not only the display emission levels. Mention explicitly that it
includes display light leak and ambient flare, as these cannot be
avoided while viewing.
Ambient flare is physically additive. I was thinking of LCD light
leaks as the minimum display emission, which I presume to be roughly
additive. Effects that are additive in non-optical spaces, e.g.
black-level lift in electrical space, would need their own
parametrization to account for. To keep things simpler, we assume
non-optical additives are zero.
The same definition is applied to the MDCV and target color volume. I
believe it would be confusing otherwise. I can only hope that this is
compatible with SMPTE ST 2086.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Although most profiles are small in size in practice, one could
theoretically contain a 3D LUT in everyday. In the example suggested by
@pq, assuming 63 elements per dimensions would result in a calculation
of 12 tags * 63^3 elements/tag * 3 channels/element * 4 bytes/channel ~=
34 MB. That is well over the old limit. Raise the number and give a
comfortable amount of breathing room for any ICC profile realistically
out there in the wild.
Signed-off-by: Dudemanguy <random342@airmail.cc>
Not every client is able to or wants to deal with ICC profiles. This request
allows them to get a preferred parametric image description for the surface,
even if the compositor's actual preferred iamge description is an ICC profile.
Signed-off-by: Xaver Hugl <xaver.hugl@kde.org>
There was some confusion about which events are sent at which time, so this
simply explicitly lists all the events the compositor *must* send.
Signed-off-by: Xaver Hugl <xaver.hugl@kde.org>
BT.709 defines a camera characteristic (OETF). A camera characteristic
is irrelevant for video distribution and broadcast, because the signal
is color graded while watching the result on a reference display
(producing a display-referred signal). BT.709 does not define any
display characteristic, but refers to BT.1886 in a footnote.
BT.601 and BT.2020 are similar to BT.709 in this respect.
The meaning of this enum entry remains the same, only its name is
changed to refer to an actual display characteristic definition.
H.273 mentions more references. Two of them are historical and withdrawn
by the ITU in 2015. BT.1700 NTSC refers to SMPTE ST 170 which is unclear
about the display characteristic: it claims the display EOTF is the
exact inverse of the given OETF. This does not match BT.1886 even though
H.273 implies it does. Hence these are not listed in our enum entry.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
This historical recommendation has been withdrawn by ITU in 2015.
The "conventional color gamut" portion is equivalent to BT.709 which is
to be decoded with BT.1886.
The "extended color gamut" portion that uses negative RGB values is
unclear how it should be decoded. I haven't seen any recommendation to
that yet. BT.1886 clamps negative values to zero at zero black level
lift.
Therefore I believe it is unlikely to need this in the protocol.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Even though the HLG OOTF adapts to a display, the HLG signal is still
display-referred because it is color graded by looking at a display
exclusively.
Explain the origin of the reference white level, similar to st2084_pq.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
We've opted to graceful failure the image description creation when bad
custom primaries or mastering display primaries are set. But we forgot
to update the errors related to that.
This renames 'invalid_primaries' to 'invalid_named_primaries',
clarifying that it is only possible to have such errors when clients set
primaries through the enums.
Also, this drops the 'invalid_mastering' error, as it is now unused in
the spec.
Signed-off-by: Leandro Ribeiro <leandro.ribeiro@collabora.com>
This changes the ext_linear default primary color volume minimum back to
0.2 cd/m². This is consistent with the sRGB reference display
characteristics, like with all other transfer functions except st2084_pq
and hlg.
The purpose is that whether content uses srgb, gamma22 or ext_linear
transfer function, it occupies the same (sRGB SDR) dynamic range by
default.
For rendering intents that employ black-point compensation, including
the perceptual rendering intent, this changes nothing.
The set_luminances request can be used to set more appropriate values as
necessary.
Suggested-by: @swick
Removed the wording about implied luminances, because it applies to
almost all TFs, not just this one.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
These are the logical requirements. Also if the computation of maxFALL
and maxCLL follow the ANSI/CTA-861-I Annex P algorithms, then
necessarily maxFALL <= maxCLL.
On one hand, making these a protocol requirement causes clients to have
to check these themselves and fix things up in any arbitrary way, while
the compositors will do the exact same checks to send protocol errors.
On the other hand, clients checking these explicitly gives clients the
opportunity to employ a desired fix-up scheme and/or show a UI complaint
that the video content metadata is inconsistent. That would be more
difficult if only some compositors sent a graceful failure when these
requirements are not met.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
ST 2084 a.k.a perceptual quantizer is an absolute luminance encoding
dealing in cd/m². This sets it apart for most other transfer
characteristics that are relative to the target display dynamic range.
Therefore the primary color volume minimum and maximum are fixed by the
ST 2084 specification, and cannot be changed. The reference white is not
fixed and remains settable.
ST 2084 allows displays to deviate from the specified EOTF due to
hardware limitations. How that works is not defined. Therefore code
point zero may produce more than 0 cd/m², but accoding to BT.2100 should
be less or equal to 0.005 cd/m². The difference between decoding with
the exact EOTF and then tone-mapping to display capability, and decoding
straight to display capability is mostly philosophical. The ideal
presentation is defined to be exactly as the ST 2084 specified EOTF.
I believe the image description should reflect this ideal presentation.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
This change makes the scRGB color space transfer characteristics
encodable as "ext_linear". The key points are supporting negative and
greater than one values, and the implied luminances.
We avoid the need to add another TF just for scRGB. I am not aware of
any use case that would be broken by these differences to the H.273 code
point; material using H.273-linear code point should presumably work
just fine with the protocol "ext_linear". Still, the name "linear" is
left unused in case we need it later.
The luminances are chosen to represent typical SDR content. The minimum
luminance of zero anchors the black point, making it indifferent to the
choice of relative vs. absolute luminance.
When this TF is used in the absolute luminance context, it implies the
Windows-scRGB (HDR) convention of [1.0, 1.0, 1.0] = 80 cd/m².
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
There seem to be no uses left for this error code. The error already_set
takes care of any inconsistency that could exist.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Originally, st2084_pq was the only transfer function providing cd/m².
Since MaxCLL and MaxFALL are defined in cd/m², it made sense to restrict
them to st2084_pq.
Nowadays we have set_luminances and its defaults, meaning we can always
compute cd/m², even from proportional luminance. We can allow MaxCLL and
MaxFALL always.
MaxCLL and MaxFALL were originally intended for the tone mapping in
st2084_pq mode displays as the video system inherently requires. These
values are unique from all the other values in the parametric interface,
and presumably they should help automatic tone mapping also outside of
st2084_pq.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
This started from
https://gitlab.freedesktop.org/swick/wayland-protocols/-/merge_requests/90
where it was desireable for a compositor to send invalid image
description ids because it does not track and de-duplicate image
description records.
Concensus decided the opposite: the id number must be valid. The ability
to skip get_information request was seen valuable, and the effort to
implement id allocation was deemed not too high. It is also to the
majority taste to deliver image descriptions with valid id.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
The Windows flavor of scRGB color space for HDR cannot easily be
represented with the parametric image description factory. The reference
white level is unknown, and the target color volume / MDCV is unknown
yet negative and greater than one color channel values must be
supported. Also gamescope wants to support this without implementing
set_luminances request.
I thought of writing a new factory for enumerated image descriptions,
but decided to reduce the boilerplate by making windows_scrgb just
another feature flag in itself. If we need more enumerated image
descriptions, extending this way seems fine, all the support
advertisements are in the wp_color_manager_v1 interface anyway even if
they are specific to a factory.
It is not possible for a compositor to indicate Windows-scRGB as an
output or a surface's preferred image description in this design. I
cannot see the use for that given how much of the image description is
essentially unknown, especially the reference white level.
Having Windows-scRGB is useful for supporting HDR applications and games
written primarily for Windows. It is not meant for "native" Wayland
applications, they can get better and more reliable results by using the
parametric image description factory.
See also: https://gitlab.freedesktop.org/swick/wayland-protocols/-/merge_requests/78
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Starting from 0 is pretty unwieldy for end users. Lots of clients will
probably need to do some kind of enum -> enum mapping (e.g. like mapping
libplacebo enums to xx-color-management ones). It's much more convenient
for 0 to be the "unsupported/don't use" value instead of forcing in a -1
or something similar.
Signed-off-by: Dudemanguy <random342@airmail.cc>
Don't say that max-cll and max-fall have well-defined defaults
when the setters say that these properties are undefined initially.
Signed-off-by: Matthias Clasen <mclasen@redhat.com>
Change the single place that talks about a "pixel description" to
say "image description" like every other place.
Signed-off-by: Matthias Clasen <mclasen@redhat.com>
When values are out of the defined transfer function range they cannot
be processed by the definition. State this, and recommend a workaround
to avoid producing an invalid composite image.
Clamping is not required, because the requirement might not be
fulfillable by display hardware via KMS. We don't want to lose KMS
off-loading opportunities by a mere possibility of badly formed data.
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
[Pekka: made clamping optional]
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
H.273 CICP tends to define the valid domains for the transfer functions,
so we should do so as well. Then it will become possible to state about
the handling of out-of-range values.
Also make this TF an extended one for no particular reason.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Some standards require a higher resolution than 1/10000 for primaries, so the protocol
needs be able to transfer sufficient resolution for all these use cases.
50.000 is the biggest used multiplier for primaries that I know of, so 1 million
should be safe.
Signed-off-by: Xaver Hugl <xaver.hugl@kde.org>
The case where reference white luminance would be higher than the
primary color volume maximum luminance is the Windows-style linear
scRGB. (1.0, 1.0, 1.0) is 80 cd/m², but the reference white could e.g.
match the PQ system's 203 cd/m² ~ (2.5, 2.5, 2.5).
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
To make the client's life slightly easier, allow destroying the image description
immediately after setting it.
Signed-off-by: Xaver Hugl <xaver.hugl@kde.org>
This allows longer-running clients who keep a cache to quickly reuse
the image description without needing further communication.
Signed-off-by: Benjamin Otte <otte@redhat.com>
There's no reason to restrict getting the preferred image description on a surface
to only the part of the code that also sets the color management properties on it.
Signed-off-by: Xaver Hugl <xaver.hugl@kde.org>
ICC v4.4 specification explicitly says that ColorSpace profiles may be
embedded in images.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Clears up what happens when an image description is attached to a
wl_surface, as well as what an image description from an output means
and what the preffered image description does.
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
The expectation is that the named, well-known transfer characteristics
of an image description describes that the image was encoded according
to the specification of that transfer characteristic.
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
The one example needing this is the ACES AP0 color space.
For consistency, allow negative values everywhere.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Some requests set_* from wp_image_description_creator_params_v1
documents that an inconsistent param set results in the
inconsistent_protocol error on the create request.
E.g. using set_max_cll but setting the TF to something different from
Rec. ITU-R BT.2100-2 perceptual quantization system.
This patch documents that on the create request description itself.
Signed-off-by: Leandro Ribeiro <leandro.ribeiro@collabora.com>
Currently request set_image_description does not have a protocol error
for invalid image description. This adds that.
Invalid image description are those that didn't receive the "ready"
event, but the "failed" one.
Signed-off-by: Leandro Ribeiro <leandro.ribeiro@collabora.com>
After inspecting EGL and Vulkan APIs, there does not seem to be a need
to allow multiple color management extensions on the same wl_surface.
This reduces the chances of application components fighting over who
sets up the image description.
(There is also an unrelated whitespace fix.)
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
"set default" may give the impression that there is a specific default
image description that would be set. There is no such though, a surface
without an image description could be processed differently on different
outputs for example.
The new wording is less misleading.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
