Peter Cai
76f4ae4a73
Also adjust the build scripts so that we don't just export one big Rust file...
800 lines
37 KiB
XML
800 lines
37 KiB
XML
<?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="6">
|
|
<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"/>
|
|
<entry name="hlg" value="6" summary="hybrid log gamma" since="2"/>
|
|
<entry name="bt709" value="7" summary="gamma for rec709 encoded videos" since="2"/>
|
|
<entry name="extendedsrgb10" value="8" summary="sRGB transfer function with headroom for HDR" since="2"/>
|
|
<entry name="smpte170m" value="9" summary="SMPTE240M transfer function" since="5"/>
|
|
<entry name="smpte240m" value="10" summary="SMPTE240M transfer function" since="5"/>
|
|
<entry name="smptest428_1" value="11" summary="SMPTEST428_1 transfer function" since="5"/>
|
|
<entry name="log" value="12" summary="LOG transfer function" since="5"/>
|
|
<entry name="log_sqrt" value="13" summary="LOG Sqrt transfer function" since="5"/>
|
|
<entry name="iec61966_2_4" value="14" summary="IEC61966_2_4 transfer function" since="5"/>
|
|
<entry name="bt1361_ecg" value="15" summary="BT1361_ECG transfer function" since="5"/>
|
|
<entry name="bt2020_10" value="16" summary="BT2020_10 transfer function" since="5"/>
|
|
<entry name="bt2020_12" value="17" summary="BT2020_12 transfer function" since="5"/>
|
|
<entry name="scrgb_linear_80_nits" value="18" summary="SCRGB Linear transfer function" since="5"/>
|
|
<entry name="gamma18" value="19" summary="GAMMA18 transfer function" since="5"/>
|
|
<entry name="gamma28" value="20" summary="GAMMA28 transfer function" since="5"/>
|
|
<entry name="srgb_hdr" value="21" summary="sRGB transfer function" since="6"/>
|
|
</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"/>
|
|
<entry name="wide_gamut_color_spin" value="9"
|
|
summary="" since="5"/>
|
|
<entry name="bt470m" value="10"
|
|
summary="" since="5"/>
|
|
<entry name="smpte240m" value="11"
|
|
summary="" since="5"/>
|
|
<entry name="xyz_d50" value="12"
|
|
summary="" since="5"/>
|
|
<entry name="smptest428_1" value="13"
|
|
summary="" since="5"/>
|
|
<entry name="smptest431_2" value="14"
|
|
summary="" since="5"/>
|
|
<entry name="film" value="15"
|
|
summary="" since="5"/>
|
|
</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">
|
|
[Deprecated] 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. Use create_color_space_from_complete_names
|
|
instead.
|
|
</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">
|
|
[Deprecated] 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. Use create_color_space_from_complete_params
|
|
instead.
|
|
</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>
|
|
|
|
<!-- Version 3 additions -->
|
|
|
|
<enum name="matrix_names">
|
|
<description summary="For specifying color matrices">
|
|
Names that describe typical ColorSpace Matrix IDs
|
|
|
|
</description>
|
|
<entry name="unknown" value="0" summary="Unknown range"/>
|
|
<entry name="rgb" value="1" summary="RGB matrix"/>
|
|
<entry name="bt709" value="2" summary="BT709 matrix"/>
|
|
<entry name="bt2020_ncl" value="3" summary="BT2020_NCL matrix"/>
|
|
<entry name="bt2020_cl" value="4" summary="BT2020_CL matrix"/>
|
|
<entry name="fcc" value="5" summary="FCC matrix"/>
|
|
<entry name="smpte170m" value="6" summary="SMPTE170M matrix"/>
|
|
<entry name="smpte240m" value="7" summary="SMPTE240M matrix"/>
|
|
<entry name="ydzdx" value="8" summary="YDZDX matrix" since="5"/>
|
|
<entry name="bt470bg" value="9" summary="BT470BG matrix" since="5"/>
|
|
<entry name="gbr" value="10" summary="GBR matrix" since="5"/>
|
|
<entry name="ycocg" value="11" summary="YCOCG matrix" since="5"/>
|
|
</enum>
|
|
|
|
<enum name="range_names">
|
|
<description summary="For specifying RGB ranges">
|
|
Names that describe typical RGB value ranges.
|
|
|
|
</description>
|
|
<entry name="unknown" value="0" summary="Unknown range"/>
|
|
<entry name="limited" value="1" summary="Limited RGB color range (values from 16-235 for 8-bit)"/>
|
|
<entry name="full" value="2" summary="Full RGB color range (values from 0 to 255 for 8-bit)"/>
|
|
<entry name="derived" value="3" summary="Range is defined by EOTF/MatrixID"/>
|
|
</enum>
|
|
|
|
<request name="create_color_space_from_complete_names" since="3">
|
|
<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.
|
|
|
|
This request additionally includes matrix and range information.
|
|
|
|
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"/>
|
|
<arg name="matrix" type="uint" enum="matrix_names" summary="color matrix"/>
|
|
<arg name="range" type="uint" enum="range_names" summary="color range"/>
|
|
</request>
|
|
|
|
<request name="create_color_space_from_complete_params" since="3">
|
|
<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.
|
|
|
|
This request additionally includes matrix and range information.
|
|
|
|
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="matrix" type="uint" enum="matrix_names" summary="Color matrix"/>
|
|
<arg name="range" type="uint" enum="range_names" summary="Color range"/>
|
|
<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>
|
|
</interface>
|
|
|
|
<interface name="zcr_color_management_output_v1" version="4">
|
|
<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="4">
|
|
<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="4">
|
|
<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="4">
|
|
<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">
|
|
[Deprecated] 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. Use complete_names instead.
|
|
</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">
|
|
[Deprecated] 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. Use
|
|
complete_params instead.
|
|
</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>
|
|
|
|
<!-- Version 3 additions -->
|
|
|
|
<event name="complete_names" since="3">
|
|
<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, matrix, range 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"/>
|
|
<arg name="matrix" type="uint" enum="zcr_color_manager_v1.matrix_names" summary="Color matrix"/>
|
|
<arg name="range" type="uint" enum="zcr_color_manager_v1.range_names" summary="Color range"/>
|
|
</event>
|
|
|
|
<event name="complete_params" since="3">
|
|
<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="matrix" type="uint" enum="zcr_color_manager_v1.matrix_names" summary="Color matrix"/>
|
|
<arg name="range" type="uint" enum="zcr_color_manager_v1.range_names" summary="Color range"/>
|
|
<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>
|
|
</interface>
|
|
|
|
</protocol>
|