This serves two purposes: one is to direct people at the repository to
understand color management, digital color and the protocol design. The
other is to make the glossary the authority on the terms we use in the
protocol.
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
There could be two kinds of additions to wp_image_description_v1 events:
- Crucial ones, without which the description is useless, for example
some completely new form of information that doesn't translate to old
events. E.g. a standard appears for a profile file format that is
utterly incompatible with ICC v4 files.
- Backwards compatible ones, which are additional details to existing
forms of information. E.g. viewing environment parameters. In case
these details are not possible to deliver, we know what assumptions
are made, and can account for those.
When crucial events are missing, there is nothing one can do. In reality
the difference is not that obvious.
When additional detail events are missing, and it actually is possible to
have reasonable assumptions that hold, a compositor could deliver what
it can and follow the assumptions clients have done. However, this means
that the preferred or output image description is not what the
compositor actually has, it is something different, so the compositor
must take that into account. Therefore the backward compatible case
should be used only when it is necessary to keep existing applications
working as well as they did before.
This is to avoid the case where one adds a minor detail in the events,
and suddenly all color critical applications that do their own color
management stop being able to do their job because the compositor
refuses to communicate anything.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
We are a display system, and we should always get pixels intended for
some display. Hence, accept only display class ICC profiles.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Make sure all destroy requests are the very first defined thing in each
interface, for consistency's sake.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Supporting other factories in independent protocol extensions was a nice
idea, but complicates the design for questionable benefit. The existing
design was only half of it, too, because wp_image_description_v1
interface had events related to all factories instead of the factories
having their own events.
Therefore go back to a simple monolithic design, but keep the different
factory requests still optional and discoverable.
This gets rid of the new_id interface hack.
There is also a little bit of unifying the wording, and couple typo
fixes.
The ICC factory is turned into a creator object, because we are not sure
that there cannot be other properties that would need to be set.
When a compositor can read the file is clarified.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
This makes the support for a few requests to be explicitly advertised
and unavailable otherwise. This allows compositors to support only
enumerated transfer functions and primaries, instead of requiring them
to support the arbitrary flavors. This may be useful for
hardware-specific compositors that cannot use programmable shading.
set_mastering_display_primaries is a bit more special. The support for
it is split into two features: basic support, and extended color volume
support. Extended color volume support requires handling color values
outside of the range [0.0, 1.0] which requires special care from
compositors. Silently clipping out-of-range values may or may not be
acceptable, so clients should be aware whether it works. If clipping is
acceptable, they can try an image description without extended color
volume.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Creating an image description might involve reading from file
descriptors which can take a significant amount of time. The previous
specification required image descriptions to fail after a roundtrip
which would make it impossible to send any events while creating an
image description in a compositor.
This commit changes the object to become ready only after receiving a
new ready event. Using the object before it is ready is an erro just
like using the object after receiving a failed event.
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
These are only useful when the image is defined in absolute luminance
units, IOW uses Perceptual Quantizer.
This completes the SMPTE ST 2086 HDR static metadata.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
I accidentally used the term container color volume when I should have
used primary color volume. Fix that, and mention the primary color
volume more to ease cross referencing.
This reverts the change of the names of two requests. It did not feel
good to name them primary_primaries and primary_primaries_cicp.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
If new parameter requests are added in a backward compatible way, I
don't want to leave the create request in the middle.
This is a simple move, the spec is identical.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Destroying is the most important aspect of an interface, so move the
destroy request definitions as the first one.
If new requests for new parameters are added in the future in backward
compatible ways, the destroy request is not sitting in between old and
new parameters.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
This new event mirrors the set_mastering_display_primaries, delivering
similar information. This allows clients to target a suitable color
sub-volume and avoid gamut mapping in the compositor, particularly for
HDR-like use cases.
The old primaries are renamed to container primaries to reduce
confusion.
The terminology follows color-and-hdr glossary.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
The get_information request talks about 'done' event, but it didn't
actually exist, so let's add it.
Clients do not need to ask for wl_display.sync explicitly.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Requests wp_color_management_output_v1.get_image_description and
wp_color_management_surface_v1.get_preferred already explicitly document
that get_information is allowed. Finish the definitions by adding notes
that image description objects created from client's data do not allow
get_informatio, and define the protocol error for the violation.
The principal reason to forbid get_information is the Wayland design
paradigm: if a client sets some data, it is up to the client to save
that data too if it needs it later. Asking the compositor for what the
client already knew is just useless overhead.
The practical reason to forbid get_information, especially for the ICC
factory, is to not require the compositor to store exactly the same data
the client gave it. If a compositor uses an internal representation of a
client given ICC file, then the compositor should not need to keep
*also* a copy of the ICC file around just in case the client might ask
for it.
This also avoids questions around whether a compositor should return
exactly the same data a client gave, or is a similar representation
enough.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Drop the old notes about performance benefits, they are already
explained with preferred_changed. Also don't emphasize getting image
descriptions from outputs, that should not be a usual option. Only
display profiling software should use output-specific image
descriptions.
Maybe a good idea to mention that clients must understand the image
description and not just get_preferred, blindly slap it on the
wl_surface, and render without any adjustments.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
This allows compositors to mimick non-color-managed behavior, or sRGB
assumption, or anything else they might have done or maybe want to do
with untagged surfaces. This may even vary from surface to surface, e.g.
specific applications through Xwayland handled differently from others.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Why pay 208 CHF for an ISO document when allegedly the same is available
from color.org for free under a different name.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
It probably makes sense to let compositors not always implement all
possible rendering intents to lower the barrier to implement this
extension.
Advertising supported rendering intents also trivially allows more
intents to be added later.
Fixed the wording to avoid "hint".
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Move it up so it's the first defined request. Destruction is such a
fundamental part of any interface.
Make it more explicit on what destructions means. I imagine compositors
to use reference-counted image description implementation objects that
are independent of protocol objects. That is already what 'identity'
event implies. It would be more hassle to make sure that
set_image_description, destroy, commit would actually special-case the
destroy, and we would also need to define what that means.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Gamma is a term spoiled with too many different meanings. Let's use
different words to be more clear. This aligns the factory request and
the information event to use the same wording.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Allow the fd to be read(2) as well. Mention that the compositor chooses
the profile details. It is possible that a compositor was not configured
with an output ICC profile, so it cannot sent one in that case.
Add a note about offset, which is different from
wp_image_description_factory_icc_v1: a compositor cannot risk some
client reading data before the given offset leading to an information
leak, so for non-zero offset a compositor would need to clear that
memory, so cannot use any bigger file as the base anyway.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
EDR can be a useful concept for relative luminance HDR, but it is not
needed or used with PQ or HLG.
Let's concentrate on the more well-known video standards using PQ and
HLG first. We can consider re-adding EDR back once we have a better idea
of how it mixes with PQ with metadata and HLG.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
This is copied from the set_primaries request and description slightly
adapted. Now the integer values are clearly defined.
We still need to define when this event is sent, but that is for another
time.
Reported-by: Jérôme Carretero (@zougloub)
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
I think it reads better like this, with the introduction being in more
general terms. Updated to refer to the recently changed interfaces.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
This was already implied in wp_image_description_creator_params_v1
description but was lacking the error code.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Improve the definition and do not talk about gamma. Gamma is still in
the name, but maybe that's fine.
Change the encoding to support three decimals, I think that's well
enough.
Set some limits on the exponent so that compositor implementations do
not get into trouble with nonsense values.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
This way we do not need our own enumeration of what H.273 already
defines.
We can also handle additions to H.273, since compositors advertise the
supported code points explicitly, and using anything else is forbidden.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Since we are going to rely on H.273 CICP, we do not need to have an
enumeration defined for these, we will simply use the CICP values.
It's also problematic to create names for the CICP values, because each
code point matches several standards so they don't have canonical names.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
This will be useful for clients de-duplicating image descriptions (color
profiles). E.g. all wl_surfaces on the same single wl_output would
likely have the same preferred image description.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Rather than pointing to a wl_output for the preferred image description,
deliver it more directly. This decouples the preferred image description
from outputs giving the compositor more freedom in recommendations.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Update how the object must be created so it has an explicit interface
version. This might not be strictly necessary here because the inherited
version would be likely correct, but it's done for consistency.
Take into account that if wp_image_description_v1 interface does need
extending, old versions of it may not be sufficient for describing
outputs.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Since the params object holds mutable state, it would be unorthodox to
create that straight from a global via wl_registry.bind, even though we
could just fine. To make things more familiar, define a separate global
factory interface for params objects.
Define the fatal protocol errors for this interface that are definitely
client bugs rather than unsupported image descriptions. Unsupported
image description errors are punted to a future image description
graceful error event that the ICC factory is going to need as well.
The error codes for duplicate setting of properties will be added later
as fatal protocol errors. More protocol errors for universally
unsupported image descriptions might be added later too.
The created and error events are removed, because the error event will
be in wp_image_description_v1 interface, and we cannot use the created
event because we need to pass the interface version explicitly to avoid
inheriting it. Unqualified new_id argument in an event has never been
tried as I know of, but it works in requests and causes less surprises.
The create request could be a second destructor for this interface, but
it's not a common pattern to have destructor with arguments, even less
with a new_id, so I chose to not try my luck there. Semantically it
would be correct. So, we do what zwp_linux_buffer_params_v1 does and
just say you need to destroy the object.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Turn wp_image_description_creator_icc_v1 into a global interface, so
that compositors can choose whether to advertise it or not. The name is
changed for consistency:
- global interfaces are factories
- one-shot helper objects are creators
set_icc request is turned into simply "create" that creates the image
description object. There is no room for any additional parameters,
because I believe we need to let the ICC handle those. We should not be
modifying their intents by adding e.g. viewing environment variables
here. What the ICC does not define, we do not add.
ICC data offset and length are added, so that ICC profiles embedded in
image files are easier to just pass through. Offset is only 32 bits,
though.
Some protocol errors that are clearly client bugs are defined, but all
other interpretation errors are left for the graceful failure event to
handle.
Add a definition of when a compositor must be finished with reading the
fd, to let clients know when it's safe to e.g. modify the file again.
The creation of the wp_image_description_v1 object requires the client
to set the interface and version explicitly. This is to allow extending
wp_image_description_v1 interface while allowing multiple independent
factories for it: the interface version must be given instead of
inherited.
Details of the error event are to be clarified later.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
The factory/creator interface cannot avoid creating the protocol object
because of the protocol mechanics, but we can still deliver the graceful
failure event immediately on it.
This will be used by all requests that create image description
objects.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
The plan is to have this one as the main global singleton interface, and
then expose type-specific factories for image description objects, e.g.
one for ICC, another for parametrized.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
* Rename zwp_ to wp_
* Rename protocol from color_management_unstable_v1 to color_management_v1
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
