blob: 2120b1e7dbeca0961a0249ba779161d57fe069fc [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="chrome_color_management">
<!--
NOTE: This protocol was forked from an upstream proposal. Once that proposal
is approved, we'll migrate to it. The proposal can be found at:
https://gitlab.freedesktop.org/wayland/wayland-protocols/-/merge_requests/14
-->
<copyright>
Copyright 2019 Sebastian Wick
Copyright 2019 Erwin Burema
Copyright 2020 AMD
Copyright 2020 Collabora, Ltd.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
</copyright>
<description summary="color management protocol">
This protocol specifies a way for a client to set the color space and
HDR metadata of a surface and to get information about the color spaces
and HDR capabilities of outputs.
This protocol is based on a proposed upstream protocol, which we will migrate
to once it is approved. It may diverge from the proposed upstream protocol
over the course of our development.
</description>
<interface name="zcr_color_manager_v1" version="1">
<description summary="color manager singleton">
A global interface used for getting color management surface and color
management output objects as well as creating color space objects from
ICC profiles, parameters, or enumerated names.
</description>
<enum name="eotf_names">
<description summary="well-known EOTF names">
Names that describe a well-known EOTF.
A compositor must support all of these based on the protocol interface
version.
</description>
<!-- TODO EOTFs -->
<!-- <entry name="bt1886" value="" summary="BT.1886 transfer function"/> -->
<!-- <entry name="dci_p3" value="" summary="DCI-P3 transfer function"/> -->
<entry name="unknown" value="0" summary="unknown EOTF"/>
<entry name="linear" value="1" summary="Linear transfer function"/>
<entry name="srgb" value="2" summary="sRGB transfer function"/>
<entry name="bt2087" value="3" summary="BT.2087 transfer function"/>
<entry name="adobergb" value="4" summary="AdobeRGB transfer function"/>
<entry name="pq" value="5" summary="Perceptual quantizer / SMPTEST2084"/>
</enum>
<enum name="chromaticity_names">
<description summary="well-known chromaticity names">
Names that describe well-known chromaticities.
A compositor must support all of these based on the protocol interface
version.
</description>
<entry name="unknown" value="0" summary="unknown chromaticity"/>
<entry name="bt601_525_line" value="1"
summary="ITU-R BT.601 http://www.itu.int/rec/R-REC-BT.601/en"/>
<entry name="bt601_625_line" value="2"
summary="ITU-R BT.601 http://www.itu.int/rec/R-REC-BT.601/en"/>
<entry name="smpte170m" value="3"
summary="SMPTE 170M-1999 https://www.itu.int/rec/R-REC-BT.1700/en"/>
<entry name="bt709" value="4"
summary="ITU-R BT.709 https://www.itu.int/rec/R-REC-BT.709/en"/>
<entry name="bt2020" value="5"
summary="ITU-R BT.2020 http://www.itu.int/rec/R-REC-BT.2020/en"/>
<entry name="srgb" value="6"
summary="IEC/4WD 61966-2-1: sRGB https://webstore.iec.ch/publication/6169"/>
<entry name="displayp3" value="7"
summary="Display P3 https://developer.apple.com/reference/coregraphics/cgcolorspace/1408916-displayp3"/>
<entry name="adobergb" value="8"
summary="Adobe RGB https://www.adobe.com/digitalimag/pdfs/AdobeRGB1998.pdf"/>
</enum>
<enum name="whitepoint_names">
<description summary="well-known whitepoint names">
Names that describe well-known whitepoints.
A compositor must support all of these based on the protocol interface
version.
</description>
<!-- TODO Whitepoints -->
<!-- <entry name="d55" value="" summary="D55 whitepoint"/> -->
<entry name="unknown" value="0" summary="unknown whitepoint"/>
<entry name="dci" value="1" summary="DCI whitepoint"/>
<entry name="d50" value="2" summary="D50 whitepoint"/>
<entry name="d65" value="3" summary="D65 whitepoint"/>
</enum>
<enum name="error">
<entry name="icc_fd" value="0" summary="given ICC fd has bad properties"/>
<entry name="bad_enum" value="1" summary="bad value given as a well-known name"/>
<entry name="bad_param" value="2" summary="bad parameter value"/>
</enum>
<request name="create_color_space_from_icc">
<description summary="create a color space object from ICC profiles">
Create a color space object from an ICC profile. This request returns
a zcr_color_space_creator_v1 object which either returns an error
or the successfully created zcr_color_space_v1 object.
The description of the color space to create is sent in the form of an
ICC profile as a file descriptor in the argument icc.
The fd must be seekable and the maximum size of the ICC profile is 4 MB.
Violating these requirements will raise an icc_fd protocol error. A
compositor must not modify the contents of the file, and the fd may be
sealed for writes and size changes.
The file contents must represent a valid ICC profile.
The ICC profile version must be 2 or 4, it must be a 3 channel profile
and the class must be 'input', 'output', 'abstract' or 'display'.
Violating these requirements will not result in a protocol error but
raise the zcr_color_space_creator_v1.error event.
See the zcr_color_space_v1 and zcr_color_space_creator_v1 interface for
more details about the created object.
See the specification from International Color Consortium for more
details about ICC profiles, also known as ISO 15076-1:2010.
</description>
<arg name="id" type="new_id" interface="zcr_color_space_creator_v1"/>
<arg name="icc" type="fd"/>
</request>
<request name="create_color_space_from_names">
<description summary="create a color space object from well-known names">
Create a color space object from well-known names. This request returns
a zcr_color_space_creator_v1 object which either returns an error
or the successfully created zcr_color_space_v1 object.
EOTF, chromaticity and whitepoint must not be unknown. Otherwise, or
if a given value is not listed in the enumeration, the protocol error
bad_enum is raised.
See the zcr_color_space_v1 and zcr_color_space_creator_v1 interface for
more details about the created object.
</description>
<arg name="id" type="new_id" interface="zcr_color_space_creator_v1"/>
<arg name="eotf" type="uint" enum="eotf_names" summary="EOTF"/>
<arg name="chromaticity" type="uint" enum="chromaticity_names" summary="chromaticity"/>
<arg name="whitepoint" type="uint" enum="whitepoint_names" summary="whitepoint"/>
</request>
<request name="create_color_space_from_params">
<description summary="create a color space object from parameters">
Create a color space object from parameters. This request returns
a zcr_color_space_creator_v1 object which either returns an error
or the successfully created zcr_color_space_v1 object.
EOTF must not be unknown. Otherwise, or if a given EOTF is not listed
in the enumeration, the protocol error bad_enum is raised.
The white point must be inside the triangle created by the red, green
and blue primaries. Otherwise the bad_param protocol error is raised.
All the chromaticity values are multiplied by 10000 to produce the
integers carried by the protocol.
See the zcr_color_space_v1 and zcr_color_space_creator_v1 interface for
more details about the created object.
</description>
<arg name="id" type="new_id" interface="zcr_color_space_creator_v1"/>
<arg name="eotf" type="uint" enum="eotf_names" summary="EOTF"/>
<arg name="primary_r_x" type="uint" summary="red primary X * 10000"/>
<arg name="primary_r_y" type="uint" summary="red primary Y * 10000"/>
<arg name="primary_g_x" type="uint" summary="green primary X * 10000"/>
<arg name="primary_g_y" type="uint" summary="green primary Y * 10000"/>
<arg name="primary_b_x" type="uint" summary="blue primary X * 10000"/>
<arg name="primary_b_y" type="uint" summary="blue primary Y * 10000"/>
<arg name="white_point_x" type="uint" summary="white point X * 10000"/>
<arg name="white_point_y" type="uint" summary="white point Y * 10000"/>
</request>
<request name="get_color_management_output">
<description summary="create a color management interface for a wl_output">
This creates a new zcr_color_management_output_v1 object for the
given wl_output.
See the zcr_color_management_output_v1 interface for more details.
</description>
<arg name="id" type="new_id" interface="zcr_color_management_output_v1"/>
<arg name="output" type="object" interface="wl_output"/>
</request>
<request name="get_color_management_surface">
<description summary="create a color management interface for a wl_surface">
This creates a new color zcr_color_management_surface_v1 object for the
given wl_surface.
See the zcr_color_management_surface_v1 interface for more details.
</description>
<arg name="id" type="new_id" interface="zcr_color_management_surface_v1"/>
<arg name="surface" type="object" interface="wl_surface"/>
</request>
<request name="destroy" type="destructor">
<description summary="destroy the color manager">
Destroy the zcr_color_manager_v1 object. This does not affect any other
objects in any way.
</description>
</request>
</interface>
<interface name="zcr_color_management_output_v1" version="1">
<description summary="output color properties">
A zcr_color_management_output_v1 describes the color properties of an
output.
When zcr_color_management_output_v1 object is created, it will send
its initial events followed by a wl_output.done event. When creating
wl_output and its extension objects, use a final wl_display.sync to
guarantee that all output events have been received across all
extensions.
If the wl_output associated with the zcr_color_management_output_v1 is
destroyed, the zcr_color_management_output_v1 object becomes inert.
</description>
<event name="color_space_changed">
<description summary="color space changed">
The color_space_changed event is sent whenever the color space of the
output changed, followed by one wl_output.done event common to
output events across all extensions.
This is not an initial event.
</description>
</event>
<event name="extended_dynamic_range">
<description summary="output extended dynamic range">
This is both an initial event and sent whenever the value changed.
When the value changed, this event is followed by one wl_output.done
event common to output events across all extensions.
The extended dynamic range value describes how much dynamic range is
available relative to the SDR maximum white. EDR value is proportional
to luminance, and the luminance of black is used as the zero level.
A value of 1.0 means that the the display can not display
anything brighter than SDR maximum white. A value of 3.0 means that the
SDR maximum white is at one third of the highest luminance the display
can produce.
The absolute luminance of the SDR maximum white depends on the monitor
capabilities, the viewing conditions and the viewer personal
preferences. A such, it cannot be given a single value in cd/m².
Compositors using HDR video modes should allow users to control the the
SDR maximum white level which the output EDR value is calculated from.
The SDR maximum white is a relative reference luminance that allows
to tone-map content from different dynamic ranges into a single common
dynamic range for display.
The EDR value is multiplied by 1000 to produce the integer value
carried by the protocol.
</description>
<arg name="value" type="uint" summary="EDR value * 1000"/>
</event>
<request name="get_color_space">
<description summary="get the color space of the output">
This creates a new zcr_color_space_v1 object for the current color space
of the output. There always is exactly one color space active for an
output so the client should destroy the color space created by earlier
invocations of this request. This request is usually sent as a reaction
to the color_space_changed event or when creating a
zcr_color_management_output_v1 object.
The created zcr_color_space_v1 object preserves the color space
of the output from the time the object was created.
The resulting color space object allows get_information request.
See the zcr_color_space_v1 interface for more details.
</description>
<arg name="id" type="new_id" interface="zcr_color_space_v1"/>
</request>
<!-- TODO: HDR capabilities event -->
<request name="destroy" type="destructor">
<description summary="destroy the color management output">
Destroy the color zcr_color_management_output_v1 object. This does not
affect any remaining protocol objects.
</description>
</request>
</interface>
<interface name="zcr_color_management_surface_v1" version="1">
<description summary="color management extension to a surface">
A zcr_color_management_surface_v1 allows the client to set the color
space and HDR properties of a surface.
If the wl_surface associated with the zcr_color_management_surface_v1 is
destroyed, the zcr_color_management_surface_v1 object becomes inert.
</description>
<enum name="render_intent">
<description summary="render intent">
<!-- FIXME: rendering intent is not just a hint -->
Rendering intent allow the client to hint at how to perform color space
transformations.
See the ICC specification for more details about rendering intent.
</description>
<entry name="perceptual" value="0" summary="perceptual"/>
<entry name="relative" value="1" summary="media-relative colorimetric"/>
<entry name="saturation" value="2" summary="saturation"/>
<entry name="absolute" value="3" summary="ICC-absolute colorimetric"/>
<entry name="relative_bpc" value="4" summary="media-relative colorimetric + black point compensation"/>
</enum>
<enum name="alpha_mode">
<description summary="alpha mode">
Specifies whether alpha is pre-multiplied into color channels or not.
If pre-multiplied, the linear alpha value is already multiplied with the
(non-linear) color channel code values in the color channels.
</description>
<entry name="straight" value="0" summary="alpha is independent from color channels"/>
<entry name="premultiplied" value="1" summary="alpha is pre-multiplied into color channels"/>
</enum>
<request name="set_alpha_mode">
<description summary="set the surface alpha mode">
Assuming an alpha channel exists, it is always linear. The alpha mode
determines whether the color channels include alpha pre-multiplied or
not. Using straight alpha might have performance benefits.
Alpha mode is double buffered, and will be applied at the time
wl_surface.commit of the corresponding wl_surface is called.
By default, a surface is assumed to have pre-multiplied alpha.
</description>
<arg name="alpha_mode" type="uint" enum="alpha_mode" summary="alpha mode"/>
</request>
<request name="set_extended_dynamic_range">
<description summary="set the content extended dynamic range">
Set the extended dynamic range (EDR) value for the underlying surface.
The EDR value is double buffered, and will be applied at the time
wl_surface.commit of the corresponding wl_surface is called.
The EDR value describes how much dynamic range is encoded relative to
the SDR maximum white. EDR value is proportional to luminance, using
the luminance of black as the zero level. A value of 1.0 means that the
SDR maximum white is the highest possible luminance of the surface. A
value of 3.0 means that the SDR maximum white is one third of the
highest possible luminance of the surface.
The color space attached to the surface can make the code values in the
buffer non-linear in regards to the luminance. The code value to produce
a third of the luminance of the biggest code value therefore might not
be one third of the biggest code value.
For the definition of the SDR maximum white on an output, see
zcr_color_management_output_v1.extended_dynamic_range. Content
producers are free to choose their SDR maximum white level. How it
shall be displayed depends on the monitor capabilities and the output
EDR value.
By default the EDR value is 1.0. The compositor will tone map the image
to match the EDR of each output the surface is shown on. The aim for
the EDR-EDR mapping is to produce a relative luminance mapping that
looks equally good regardless of the viewing conditions and the monitor
capabilities, assuming the output EDR value was tuned to the output
capabilities and the viewing environment. There might be performance
and image quality benefits from providing content readily tone mapped to
the EDR value of the output the surface is shown on.
The EDR value is multiplied by 1000 to produce the integer value
carried by the protocol.
</description>
<arg name="value" type="uint" summary="EDR value * 1000"/>
</request>
<request name="set_color_space">
<description summary="set the surface color space">
Set the color space of the underlying surface. The color space and
render intent are double buffered, and will be applied
at the time wl_surface.commit of the corresponding wl_surface is called.
<!-- FIXME: same problem as in the render_intent enum -->
The render intent gives the compositor a hint what to optimize for in
color space transformations.
By default, a surface is assumed to have the sRGB color space and an
arbitrary render intent.
If the color space of the surface matches the color space of an output
it is shown on the performance and color accuracy might improve. To find
those color spaces the client can listen to the preferred_color_space or
the wl_surface.enter/leave events. This improvement may require using
the color space object created by
zcr_color_management_output_v1.get_color_space.
</description>
<arg name="color_space" type="object" interface="zcr_color_space_v1"/>
<arg name="render_intent" type="uint" enum="render_intent" summary="render intent"/>
</request>
<request name="set_default_color_space">
<description summary="set the surface color space to default">
This request sets the surface color space to the defaults, see
set_color_space. The setting will be applied at the time
wl_surface.commit of the corresponding wl_surface is called.
</description>
</request>
<!-- TODO: HDR metadata request -->
<event name="preferred_color_space">
<description summary="output for color optimization">
The preferred_color_space event is sent when the compositor determines
or switches the output that implies the preferred color space. The
preferred color space is the one which likely has the most performance
and quality benefits if used by a client for its surface contents.
The event does not carry a zcr_color_space_v1 but a wl_output object.
The concrete zcr_color_space_v1 can be created by calling
zcr_color_management_output_v1.get_color_space on the output and
listening to zcr_color_management_output_v1.color_space_changed
events.
As clients may bind to the same global wl_output multiple
times, this event is sent for each bound instance that matches
the preferred color space output. If a client has not bound to
the right wl_output global at all, this event is not sent.
This is only a hint and clients can set any valid color space with
set_color_space but there might be performance and color accuracy
improvements by providing the surface in the preferred color space.
</description>
<arg name="output" type="object" interface="wl_output"/>
</event>
<request name="destroy" type="destructor">
<description summary="destroy the color management interface for a surface">
Destroy the zcr_color_management_surface_v1 object.
When the last zcr_color_management_surface_v1 object for a wl_surface
is destroyed, the destruction will pend unsetting the wl_surface's
color space, render intent and alpha mode similar to set_color_space
will pend a set.
</description>
</request>
</interface>
<interface name="zcr_color_space_creator_v1" version="1">
<description summary="color space creator">
A zcr_color_space_creator_v1 object returns a created color space
or the error which occured during creation.
Once a zcr_color_space_creator_v1 object has delivered a 'created'
or 'error' event it is automatically destroyed.
</description>
<enum name="creation_error" bitfield="true">
<description summary="color space creation error">
Bitmask of errors which occured while trying to create a color space
</description>
<entry name="malformed_icc" value="0x1" summary="malformed ICC profile"/>
<entry name="bad_icc" value="0x2" summary="ICC profile does not meet requirements"/>
<entry name="bad_primaries" value="0x4" summary="bad primaries"/>
<entry name="bad_whitepoint" value="0x8" summary="bad whitepoint"/>
</enum>
<event name="created">
<description summary="color space object created">
Delivers the successfully created color space.
The resulting color space object does not allow get_information request.
</description>
<arg name="id" type="new_id" interface="zcr_color_space_v1"/>
</event>
<event name="error">
<description summary="color space creation failed">
This event is sent if the color space creation failed.
</description>
<arg name="error" type="uint" enum="creation_error" summary="error bitmask"/>
</event>
</interface>
<interface name="zcr_color_space_v1" version="1">
<description summary="color space">
Refers to a color space which can be attached to a surface
(zcr_color_management_surface_v1.set_color_space). It may provide
information like the ICC profile and the well-known names to allow
clients to know the color space and do color transformations of their
own.
Once created and regardless of how it was created, a zcr_color_space_v1
object always refers to one fixed color space.
The client can create a zcr_color_space_v1 object with
zcr_color_manager_v1 requests or from an output by calling
zcr_color_management_output_v1.get_color_space.
Other extensions may define more zcr_color_space_v1 factory interfaces.
Those interfaces must explicitly specify the interface version for the
object created, otherwise versioning zcr_color_space_v1 correctly
becomes impossible. Using a 'new_id' argument without 'interface'
attribute defined in XML forces code generators to add two explicit
arguments: interface and version. Version is the explicit version
number needed, and interface should be required to be
"zcr_color_space_v1". The compositor supported zcr_color_space_v1
versions are defined by the advertised zcr_color_manager_v1 in
wl_registry.
</description>
<enum name="error">
<entry name="no_information" value="0" summary="get_information disallowed"/>
</enum>
<request name="get_information">
<description summary="get information about the color space">
As a reply to this request, the compositor will send all available
information events describing this color space object and finally
the 'done' event. Other extensions may define more events to be sent
before 'done'.
This request is allowed only on zcr_color_space_v1 objects where the
message that created the object specifies that get_information is
allowed. Otherwise protocol error no_information is raised.
Every get_information request on the same object will always return the
exact same data.
See zcr_color_management_output_v1.get_color_space and
zcr_color_space_creator_v1.created.
</description>
</request>
<event name="icc_file">
<description summary="ICC profile describing the color space">
This event may be sent only as a response to
zcr_color_space_v1.get_information.
The icc argument provides a file descriptor to the client which can be
memory-mapped to provide the ICC profile describing the color space.
The fd must be mapped with MAP_PRIVATE and read-only by the client.
Compositors should send this event always when information is requested.
ICC profiles provide the common foundation which all color managed
clients may rely on.
</description>
<arg name="icc" type="fd" summary="ICC profile file descriptor"/>
<arg name="icc_size" type="uint" summary="ICC profile size, in bytes"/>
</event>
<event name="names">
<description summary="well-known names of a color space">
This event may be sent only as a response to
zcr_color_space_v1.get_information.
EOTF, chromaticity and whitepoint contain well-known names of those
properties if available and unknown otherwise.
Compositors should not assume that all clients can understand these
names. The names are provided for client convenience. If a client
understands the name triplet, it may ignore other information about
the color space, the ICC profile for example.
</description>
<arg name="eotf" type="uint" enum="zcr_color_manager_v1.eotf_names" summary="EOTF"/>
<arg name="chromaticity" type="uint" enum="zcr_color_manager_v1.chromaticity_names" summary="chromaticity"/>
<arg name="whitepoint" type="uint" enum="zcr_color_manager_v1.whitepoint_names" summary="whitepoint"/>
</event>
<event name="params">
<description summary="RGB primaries along with whitepoint defining color space">
This event may be sent only as a response to
zcr_color_space_v1.get_information.
The RGB primary value arguments along with the whitepoint value arguments
and eotf can be used to define an arbitrary or custom color space.
The eotf enum contains well known names of that property, but the compositor
should not assume that all clients will understand those names.
</description>
<arg name="eotf" type="uint" enum="zcr_color_manager_v1.eotf_names" summary="EOTF"/>
<arg name="primary_r_x" type="uint" summary="red primary X * 10000"/>
<arg name="primary_r_y" type="uint" summary="red primary Y * 10000"/>
<arg name="primary_g_x" type="uint" summary="green primary X * 10000"/>
<arg name="primary_g_y" type="uint" summary="green primary Y * 10000"/>
<arg name="primary_b_x" type="uint" summary="blue primary X * 10000"/>
<arg name="primary_b_y" type="uint" summary="blue primary Y * 10000"/>
<arg name="white_point_x" type="uint" summary="white point X * 10000"/>
<arg name="white_point_y" type="uint" summary="white point Y * 10000"/>
</event>
<event name="done">
<description summary="end of color space information">
This event may be sent only as a response to
zcr_color_space_v1.get_information.
This signifies that all color space information events have been
delivered for the object.
</description>
</event>
<request name="destroy" type="destructor">
<description summary="destroy the color space">
Destroy the zcr_color_space_v1 object.
Destroying the zcr_color_space_v1 which is active on a surface or an
output does not change the color space of those objects.
</description>
</request>
</interface>
</protocol>