1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="color_management_v1">
3 <copyright>
4 Copyright 2019 Sebastian Wick
5 Copyright 2019 Erwin Burema
6 Copyright 2020 AMD
7 Copyright 2020-2024 Collabora, Ltd.
8 Copyright 2024 Xaver Hugl
9 Copyright 2022-2025 Red Hat, Inc.
10
11 Permission is hereby granted, free of charge, to any person obtaining a
12 copy of this software and associated documentation files (the "Software"),
13 to deal in the Software without restriction, including without limitation
14 the rights to use, copy, modify, merge, publish, distribute, sublicense,
15 and/or sell copies of the Software, and to permit persons to whom the
16 Software is furnished to do so, subject to the following conditions:
17
18 The above copyright notice and this permission notice (including the next
19 paragraph) shall be included in all copies or substantial portions of the
20 Software.
21
22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
23 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
25 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
27 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
28 DEALINGS IN THE SOFTWARE.
29 </copyright>
30
31 <description summary="color management protocol">
32 The aim of the color management extension is to allow clients to know
33 the color properties of outputs, and to tell the compositor about the color
34 properties of their content on surfaces. All surface contents must be
35 readily intended for some display, but not necessarily for the display at
36 hand. Doing this enables a compositor to perform automatic color management
37 of content for different outputs according to how content is intended to
38 look like.
39
40 For an introduction, see the section "Color management" in the Wayland
41 documentation at https://wayland.freedesktop.org/docs/html/ .
42
43 The color properties are represented as an image description object which
44 is immutable after it has been created. A wl_output always has an
45 associated image description that clients can observe. A wl_surface
46 always has an associated preferred image description as a hint chosen by
47 the compositor that clients can also observe. Clients can set an image
48 description on a wl_surface to denote the color characteristics of the
49 surface contents.
50
51 An image description essentially defines a display and (indirectly) its
52 viewing environment. An image description includes SDR and HDR colorimetry
53 and encoding, HDR metadata, and some parameters related to the viewing
54 environment. An image description does not include the properties set
55 through color-representation extension. It is expected that the
56 color-representation extension is used in conjunction with the
57 color-management extension when necessary, particularly with the YUV family
58 of pixel formats.
59
60 The normative appendix for this protocol is in the appendix.md file beside
61 this XML file.
62
63 The color-and-hdr repository
64 (https://gitlab.freedesktop.org/pq/color-and-hdr) contains
65 background information on the protocol design and legacy color management.
66 It also contains a glossary, learning resources for digital color, tools,
67 samples and more.
68
69 The terminology used in this protocol is based on common color science and
70 color encoding terminology where possible. The glossary in the color-and-hdr
71 repository shall be the authority on the definition of terms in this
72 protocol.
73
74 Warning! The protocol described in this file is currently in the testing
75 phase. Backward compatible changes may be added together with the
76 corresponding interface version bump. Backward incompatible changes can
77 only be done by creating a new major version of the extension.
78 </description>
79
80 <interface name="wp_color_manager_v1" version="3">
81 <description summary="color manager singleton">
82 A singleton global interface used for getting color management extensions
83 for wl_surface and wl_output objects, and for creating client defined
84 image description objects. The extension interfaces allow
85 getting the image description of outputs and setting the image
86 description of surfaces.
87
88 Compositors should never remove this global.
89 </description>
90
91 <request name="destroy" type="destructor">
92 <description summary="destroy the color manager">
93 Destroy the wp_color_manager_v1 object. This does not affect any other
94 objects in any way.
95 </description>
96 </request>
97
98 <enum name="error">
99 <entry name="unsupported_feature" value="0"
100 summary="request not supported"/>
101 <entry name="surface_exists" value="1"
102 summary="color management surface exists already"/>
103 </enum>
104
105 <enum name="render_intent">
106 <description summary="rendering intents">
107 See the ICC.1:2022 specification from the International Color Consortium
108 for more details about rendering intents.
109
110 The principles of ICC defined rendering intents apply with all types of
111 image descriptions, not only those with ICC file profiles.
112
113 Compositors must support the perceptual rendering intent. Other
114 rendering intents are optional.
115 </description>
116
117 <entry name="perceptual" value="0"
118 summary="perceptual"/>
119 <entry name="relative" value="1"
120 summary="media-relative colorimetric"/>
121 <entry name="saturation" value="2"
122 summary="saturation"/>
123 <entry name="absolute" value="3"
124 summary="ICC-absolute colorimetric"/>
125 <entry name="relative_bpc" value="4"
126 summary="media-relative colorimetric + black point compensation"/>
127 <entry name="absolute_no_adaptation" value="5" since="2">
128 <description summary="ICC-absolute colorimetric without adaptation">
129 This rendering intent is a modified absolute rendering intent that
130 assumes the viewer is not adapted to the display white point, so no
131 chromatic adaptation between surface and display is done.
132 This can be useful for color proofing applications.
133 </description>
134 </entry>
135 </enum>
136
137 <enum name="feature">
138 <description summary="compositor supported features"/>
139
140 <entry name="icc_v2_v4" value="0"
141 summary="create_icc_creator request"/>
142 <entry name="parametric" value="1"
143 summary="create_parametric_creator request"/>
144 <entry name="set_primaries" value="2"
145 summary="parametric set_primaries request"/>
146 <entry name="set_tf_power" value="3"
147 summary="parametric set_tf_power request"/>
148 <entry name="set_luminances" value="4"
149 summary="parametric set_luminances request"/>
150 <entry name="set_mastering_display_primaries" value="5">
151 <description summary="parametric set_mastering_display_primaries request">
152 The compositor supports set_mastering_display_primaries request with a
153 target color volume fully contained inside the primary color volume.
154 </description>
155 </entry>
156 <entry name="extended_target_volume" value="6">
157 <description summary="parametric target exceeds primary color volume">
158 The compositor additionally supports target color volumes that
159 extend outside of the primary color volume.
160
161 This can only be advertised if feature set_mastering_display_primaries
162 is supported as well.
163 </description>
164 </entry>
165 <entry name="windows_scrgb" value="7"
166 summary="create_windows_scrgb request"/>
167 <entry name="windows_bt2100" value="8"
168 summary="create_windows_bt2100 request"/>
169 </enum>
170
171 <enum name="primaries">
172 <description summary="named color primaries">
173 Named color primaries used to encode well-known sets of primaries.
174
175 A value of 0 is invalid and will never be present in the list of enums.
176 </description>
177
178 <entry name="srgb" value="1">
179 <description summary="Color primaries for the sRGB color space as defined by the BT.709 standard">
180 Color primaries as defined by
181 - Rec. ITU-R BT.709-6
182 - Rec. ITU-R BT.1361-0 conventional colour gamut system and extended
183 colour gamut system (historical)
184 - IEC 61966-2-1 sRGB or sYCC
185 - IEC 61966-2-4
186 - Society of Motion Picture and Television Engineers (SMPTE) RP 177
187 (1993) Annex B
188 </description>
189 </entry>
190 <entry name="pal_m" value="2">
191 <description summary="Color primaries for PAL-M as defined by the BT.470 standard">
192 Color primaries as defined by
193 - Rec. ITU-R BT.470-6 System M (historical)
194 - United States National Television System Committee 1953
195 Recommendation for transmission standards for color television
196 - United States Federal Communications Commission (2003) Title 47 Code
197 of Federal Regulations 73.682 (a)(20)
198 </description>
199 </entry>
200 <entry name="pal" value="3">
201 <description summary="Color primaries for PAL as defined by the BT.601 standard">
202 Color primaries as defined by
203 - Rec. ITU-R BT.470-6 System B, G (historical)
204 - Rec. ITU-R BT.601-7 625
205 - Rec. ITU-R BT.1358-0 625 (historical)
206 - Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM
207 </description>
208 </entry>
209 <entry name="ntsc" value="4">
210 <description summary="Color primaries for NTSC as defined by the BT.601 standard">
211 Color primaries as defined by
212 - Rec. ITU-R BT.601-7 525
213 - Rec. ITU-R BT.1358-1 525 or 625 (historical)
214 - Rec. ITU-R BT.1700-0 NTSC
215 - SMPTE 170M (2004)
216 - SMPTE 240M (1999) (historical)
217 </description>
218 </entry>
219 <entry name="generic_film" value="5">
220 <description summary="Generic film with colour filters using Illuminant C">
221 Color primaries as defined by Recommendation ITU-T H.273
222 "Coding-independent code points for video signal type identification"
223 for "generic film".
224 </description>
225 </entry>
226 <entry name="bt2020" value="6">
227 <description summary="Color primaries as defined by the BT.2020 and BT.2100 standard">
228 Color primaries as defined by
229 - Rec. ITU-R BT.2020-2
230 - Rec. ITU-R BT.2100-0
231 </description>
232 </entry>
233 <entry name="cie1931_xyz" value="7">
234 <description summary="Color primaries of the full CIE 1931 XYZ color space">
235 Color primaries as defined as the maximum of the CIE 1931 XYZ color
236 space by
237 - SMPTE ST 428-1
238 - (CIE 1931 XYZ as in ISO 11664-1)
239 </description>
240 </entry>
241 <entry name="dci_p3" value="8">
242 <description summary="Color primaries of the DCI P3 color space as defined by the SMPTE RP 431 standard">
243 Color primaries as defined by Digital Cinema System and published in
244 SMPTE RP 431-2 (2011).
245 </description>
246 </entry>
247 <entry name="display_p3" value="9">
248 <description summary="Color primaries of Display P3 variant of the DCI-P3 color space as defined by the SMPTE EG 432 standard">
249 Color primaries as defined by Digital Cinema System and published in
250 SMPTE EG 432-1 (2010).
251 </description>
252 </entry>
253 <entry name="adobe_rgb" value="10">
254 <description summary="Color primaries of the Adobe RGB color space as defined by the ISO 12640 standard">
255 Color primaries as defined by Adobe as "Adobe RGB" and later published
256 by ISO 12640-4 (2011).
257 </description>
258 </entry>
259 </enum>
260
261 <enum name="transfer_function">
262 <description summary="named transfer functions">
263 Named transfer functions used to represent well-known transfer
264 characteristics of displays.
265
266 A value of 0 is invalid and will never be present in the list of enums.
267
268 See appendix.md for the formulae.
269 </description>
270
271 <entry name="bt1886" value="1">
272 <description summary="BT.1886 display transfer characteristic">
273 Rec. ITU-R BT.1886 is the display transfer characteristic assumed by
274 - Rec. ITU-R BT.601-7 525 and 625
275 - Rec. ITU-R BT.709-6
276 - Rec. ITU-R BT.2020-2
277
278 This TF implies these default luminances from Rec. ITU-R BT.2035:
279 - primary color volume minimum: 0.01 cd/m²
280 - primary color volume maximum: 100 cd/m²
281 - reference white: 100 cd/m²
282 </description>
283 </entry>
284 <entry name="gamma22" value="2">
285 <description summary="Assumed display gamma 2.2 transfer function">
286 Transfer characteristics as defined by
287 - Rec. ITU-R BT.470-6 System M (historical)
288 - United States National Television System Committee 1953
289 Recommendation for transmission standards for color television
290 - United States Federal Communications Commission (2003) Title 47 Code
291 of Federal Regulations 73.682 (a) (20)
292 - Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM
293 - IEC 61966-2-1 (reference display)
294 </description>
295 </entry>
296 <entry name="gamma28" value="3">
297 <description summary="Assumed display gamma 2.8 transfer function">
298 Transfer characteristics as defined by
299 - Rec. ITU-R BT.470-6 System B, G (historical)
300 </description>
301 </entry>
302 <entry name="st240" value="4">
303 <description summary="SMPTE ST 240 transfer function">
304 Transfer characteristics as defined by
305 - SMPTE ST 240 (1999)
306 </description>
307 </entry>
308 <entry name="ext_linear" value="5">
309 <description summary="extended linear transfer function">
310 Linear transfer function defined over all real numbers.
311 Normalised electrical values are equal the normalised optical values.
312 </description>
313 </entry>
314 <entry name="log_100" value="6">
315 <description summary="logarithmic 100:1 transfer function">
316 Logarithmic transfer characteristic (100:1 range).
317 </description>
318 </entry>
319 <entry name="log_316" value="7">
320 <description summary="logarithmic (100*Sqrt(10) : 1) transfer function">
321 Logarithmic transfer characteristic (100 * Sqrt(10) : 1 range).
322 </description>
323 </entry>
324 <entry name="xvycc" value="8">
325 <description summary="IEC 61966-2-4 transfer function">
326 Transfer characteristics as defined by
327 - IEC 61966-2-4
328 </description>
329 </entry>
330 <entry name="srgb" value="9" deprecated-since="2">
331 <description summary="Deprecated (ambiguous sRGB transfer function)">
332 Transfer characteristics as defined by
333 - IEC 61966-2-1 sRGB
334
335 As a rule of thumb, use gamma22 for video, motion picture and
336 computer graphics, or compound_power_2_4 for ICC calibrated print
337 workflows.
338 </description>
339 </entry>
340 <entry name="ext_srgb" value="10" deprecated-since="2">
341 <description summary="Deprecated (Extended sRGB piece-wise transfer function)">
342 Transfer characteristics as defined by
343 - IEC 61966-2-1 sYCC
344 </description>
345 </entry>
346 <entry name="st2084_pq" value="11">
347 <description summary="perceptual quantizer transfer function">
348 Transfer characteristics as defined by
349 - SMPTE ST 2084 (2014) for 10-, 12-, 14- and 16-bit systems
350 - Rec. ITU-R BT.2100-2 perceptual quantization (PQ) system
351
352 This TF implies these default luminances
353 - primary color volume minimum: 0.005 cd/m²
354 - primary color volume maximum: 10000 cd/m²
355 - reference white: 203 cd/m²
356
357 The difference between the primary color volume minimum and maximum
358 must be approximately 10000 cd/m² as that is the swing of the EOTF
359 defined by ST 2084 and BT.2100. The default value for the
360 reference white is a protocol addition: it is suggested by
361 Report ITU-R BT.2408-7 and is not part of ST 2084 or BT.2100.
362 </description>
363 </entry>
364 <entry name="st428" value="12">
365 <description summary="SMPTE ST 428 transfer function">
366 Transfer characteristics as defined by
367 - SMPTE ST 428-1 (2019)
368 </description>
369 </entry>
370 <entry name="hlg" value="13">
371 <description summary="hybrid log-gamma transfer function">
372 Transfer characteristics as defined by
373 - ARIB STD-B67 (2015)
374 - Rec. ITU-R BT.2100-2 hybrid log-gamma (HLG) system
375
376 This TF implies these default luminances
377 - primary color volume minimum: 0.005 cd/m²
378 - primary color volume maximum: 1000 cd/m²
379 - reference white: 203 cd/m²
380
381 HLG is a relative display-referred signal with a specified
382 non-linear mapping to the display peak luminance (the HLG OOTF).
383 All absolute luminance values used here for HLG assume a 1000 cd/m²
384 peak display.
385
386 The default value for the reference white is a protocol addition:
387 it is suggested by Report ITU-R BT.2408-7 and is not part of
388 ARIB STD-B67 or BT.2100.
389 </description>
390 </entry>
391 <entry name="compound_power_2_4" value="14" since="2">
392 <description summary="IEC 61966-2-1 encoding function">
393 Encoding characteristics as defined by IEC 61966-2-1, for displays
394 that invert the encoding function.
395 </description>
396 </entry>
397 </enum>
398
399 <request name="get_output">
400 <description summary="create a color management interface for a wl_output">
401 This creates a new wp_color_management_output_v1 object for the
402 given wl_output.
403
404 See the wp_color_management_output_v1 interface for more details.
405 </description>
406
407 <arg name="id" type="new_id" interface="wp_color_management_output_v1"/>
408 <arg name="output" type="object" interface="wl_output"/>
409 </request>
410
411 <request name="get_surface">
412 <description summary="create a color management interface for a wl_surface">
413 If a wp_color_management_surface_v1 object already exists for the given
414 wl_surface, the protocol error surface_exists is raised.
415
416 This creates a new color wp_color_management_surface_v1 object for the
417 given wl_surface.
418
419 See the wp_color_management_surface_v1 interface for more details.
420 </description>
421
422 <arg name="id" type="new_id" interface="wp_color_management_surface_v1"/>
423 <arg name="surface" type="object" interface="wl_surface"/>
424 </request>
425
426 <request name="get_surface_feedback">
427 <description summary="create a color management feedback interface">
428 This creates a new color wp_color_management_surface_feedback_v1 object
429 for the given wl_surface.
430
431 See the wp_color_management_surface_feedback_v1 interface for more
432 details.
433 </description>
434
435 <arg name="id" type="new_id"
436 interface="wp_color_management_surface_feedback_v1"/>
437 <arg name="surface" type="object" interface="wl_surface"/>
438 </request>
439
440 <request name="create_icc_creator">
441 <description summary="make a new ICC-based image description creator object">
442 Makes a new ICC-based image description creator object with all
443 properties initially unset. The client can then use the object's
444 interface to define all the required properties for an image description
445 and finally create a wp_image_description_v1 object.
446
447 This request can be used when the compositor advertises
448 wp_color_manager_v1.feature.icc_v2_v4.
449 Otherwise this request raises the protocol error unsupported_feature.
450 </description>
451
452 <arg name="obj"
453 type="new_id" interface="wp_image_description_creator_icc_v1"
454 summary="the new creator object"/>
455 </request>
456
457 <request name="create_parametric_creator">
458 <description summary="make a new parametric image description creator object">
459 Makes a new parametric image description creator object with all
460 properties initially unset. The client can then use the object's
461 interface to define all the required properties for an image description
462 and finally create a wp_image_description_v1 object.
463
464 This request can be used when the compositor advertises
465 wp_color_manager_v1.feature.parametric.
466 Otherwise this request raises the protocol error unsupported_feature.
467 </description>
468
469 <arg name="obj"
470 type="new_id" interface="wp_image_description_creator_params_v1"
471 summary="the new creator object"/>
472 </request>
473
474 <request name="create_windows_scrgb">
475 <description summary="create Windows-scRGB image description object">
476 This creates a pre-defined image description for the so-called
477 Windows-scRGB stimulus encoding. This comes from the Windows 10 handling
478 of its own definition of an scRGB color space for an HDR screen
479 driven in BT.2100/PQ signalling mode.
480
481 Windows-scRGB uses sRGB (BT.709) color primaries and white point.
482 The transfer characteristic is extended linear.
483
484 The nominal color channel value range is extended, meaning it includes
485 negative and greater than 1.0 values. Negative values are used to
486 escape the sRGB color gamut boundaries. To make use of the extended
487 range, the client needs to use a pixel format that can represent those
488 values, e.g. floating-point 16 bits per channel.
489
490 Nominal color value R=G=B=0.0 corresponds to BT.2100/PQ system
491 0 cd/m², and R=G=B=1.0 corresponds to BT.2100/PQ system 80 cd/m².
492 The maximum is R=G=B=125.0 corresponding to 10k cd/m².
493
494 Windows-scRGB is displayed by Windows 10 by converting it to
495 BT.2100/PQ, maintaining the CIE 1931 chromaticity and mapping the
496 luminance as above. No adjustment is made to the signal to account
497 for the viewing conditions.
498
499 The reference white level of Windows-scRGB is unknown. If a
500 reference white level must be assumed for compositor processing, it
501 should be R=G=B=2.5375 corresponding to 203 cd/m² of Report ITU-R
502 BT.2408-7.
503
504 The target color volume of Windows-scRGB is unknown. The color gamut
505 may be anything between sRGB and BT.2100.
506
507 Note: EGL_EXT_gl_colorspace_scrgb_linear definition differs from
508 Windows-scRGB by using R=G=B=1.0 as the reference white level, while
509 Windows-scRGB reference white level is unknown or varies. However,
510 it seems probable that Windows implements both
511 EGL_EXT_gl_colorspace_scrgb_linear and Vulkan
512 VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT as Windows-scRGB.
513
514 This request can be used when the compositor advertises
515 wp_color_manager_v1.feature.windows_scrgb.
516 Otherwise this request raises the protocol error unsupported_feature.
517
518 The resulting image description object does not allow get_information
519 request. The wp_image_description_v1.ready event shall be sent.
520 </description>
521
522 <arg name="image_description"
523 type="new_id" interface="wp_image_description_v1"/>
524 </request>
525
526 <event name="supported_intent">
527 <description summary="supported rendering intent">
528 When this object is created, it shall immediately send this event once
529 for each rendering intent the compositor supports.
530
531 A compositor must not advertise intents that are deprecated in the
532 bound version of the interface.
533 </description>
534
535 <arg name="render_intent" type="uint" enum="render_intent"
536 summary="rendering intent"/>
537 </event>
538
539 <event name="supported_feature">
540 <description summary="supported features">
541 When this object is created, it shall immediately send this event once
542 for each compositor supported feature listed in the enumeration.
543
544 A compositor must not advertise features that are deprecated in the
545 bound version of the interface.
546 </description>
547
548 <arg name="feature" type="uint" enum="feature"
549 summary="supported feature"/>
550 </event>
551
552 <event name="supported_tf_named">
553 <description summary="supported named transfer characteristic">
554 When this object is created, it shall immediately send this event once
555 for each named transfer function the compositor supports with the
556 parametric image description creator.
557
558 A compositor must not advertise transfer functions that are deprecated
559 in the bound version of the interface.
560 </description>
561
562 <arg name="tf" type="uint" enum="transfer_function"
563 summary="Named transfer function"/>
564 </event>
565
566 <event name="supported_primaries_named">
567 <description summary="supported named primaries">
568 When this object is created, it shall immediately send this event once
569 for each named set of primaries the compositor supports with the
570 parametric image description creator.
571
572 A compositor must not advertise names that are deprecated in the
573 bound version of the interface.
574 </description>
575
576 <arg name="primaries" type="uint" enum="primaries"
577 summary="Named color primaries"/>
578 </event>
579
580 <event name="done">
581 <description summary="all features have been sent">
582 This event is sent when all supported rendering intents, features,
583 transfer functions and named primaries have been sent.
584 </description>
585 </event>
586
587 <request name="get_image_description" since="2">
588 <description summary="create an image description from a reference">
589 This request retrieves the image description backing a reference.
590
591 The get_information request can be used if and only if the request that
592 creates the reference allows it.
593 </description>
594
595 <arg name="image_description"
596 type="new_id" interface="wp_image_description_v1"/>
597 <arg name="reference"
598 type="object" interface="wp_image_description_reference_v1"/>
599 </request>
600
601 <request name="create_windows_bt2100" since="3">
602 <description summary="create Windows-BT.2100 image description object">
603 This creates a pre-defined image description for the so-called
604 Windows-BT.2100 stimulus encoding. This comes from the Windows 10
605 handling of its own definition of a BT.2100 color space for an HDR
606 screen driven in BT.2100/PQ signalling mode.
607
608 Windows-BT.2100 uses BT.2020 color primaries and white point.
609 The transfer characteristic is st2084_pq.
610
611 Windows-BT.2100 is generally displayed by Windows 10 without any
612 adjustments to the signal to account for viewing conditions.
613
614 The reference white level of Windows-BT.2100 is unknown. If a
615 reference white level must be assumed for compositor processing, it
616 should be 203 cd/m² of Report ITU-R BT.2408-7.
617
618 The target color volume of Windows-BT.2100 is unknown. The color gamut
619 may be anything up to BT.2100.
620
621 This request can be used when the compositor advertises
622 wp_color_manager_v1.feature.windows_bt2100.
623 Otherwise this request raises the protocol error unsupported_feature.
624
625 The resulting image description object does not allow get_information
626 request. The wp_image_description_v1.ready event shall be sent.
627 </description>
628
629 <arg name="image_description"
630 type="new_id" interface="wp_image_description_v1"/>
631 </request>
632 </interface>
633
634 <interface name="wp_color_management_output_v1" version="3">
635 <description summary="output color properties">
636 A wp_color_management_output_v1 describes the color properties of an
637 output.
638
639 The wp_color_management_output_v1 is associated with the wl_output global
640 underlying the wl_output object. Therefore the client destroying the
641 wl_output object has no impact, but the compositor removing the output
642 global makes the wp_color_management_output_v1 object inert.
643 </description>
644
645 <request name="destroy" type="destructor">
646 <description summary="destroy the color management output">
647 Destroy the color wp_color_management_output_v1 object. This does not
648 affect any remaining protocol objects.
649 </description>
650 </request>
651
652 <event name="image_description_changed">
653 <description summary="image description changed">
654 This event is sent whenever the image description of the output changed,
655 followed by one wl_output.done event common to output events across all
656 extensions.
657
658 If the client wants to use the updated image description, it needs to do
659 get_image_description again, because image description objects are
660 immutable.
661 </description>
662 </event>
663
664 <request name="get_image_description">
665 <description summary="get the image description of the output">
666 This creates a new wp_image_description_v1 object for the current image
667 description of the output. There always is exactly one image description
668 active for an output so the client should destroy the image description
669 created by earlier invocations of this request. This request is usually
670 sent as a reaction to the image_description_changed event or when
671 creating a wp_color_management_output_v1 object.
672
673 The image description of an output represents the color encoding the
674 output expects. There might be performance and power advantages, as well
675 as improved color reproduction, if a content update matches the image
676 description of the output it is being shown on. If a content update is
677 shown on any other output than the one it matches the image description
678 of, then the color reproduction on those outputs might be considerably
679 worse.
680
681 The created wp_image_description_v1 object preserves the image
682 description of the output from the time the object was created.
683
684 The resulting image description object allows get_information request.
685
686 If this protocol object is inert, the resulting image description object
687 shall immediately deliver the wp_image_description_v1.failed event with
688 the no_output cause.
689
690 If the interface version is inadequate for the output's image
691 description, meaning that the client does not support all the events
692 needed to deliver the crucial information, the resulting image
693 description object shall immediately deliver the
694 wp_image_description_v1.failed event with the low_version cause.
695
696 Otherwise the object shall immediately deliver the ready event.
697 </description>
698
699 <arg name="image_description"
700 type="new_id" interface="wp_image_description_v1"/>
701 </request>
702 </interface>
703
704 <interface name="wp_color_management_surface_v1" version="3">
705 <description summary="color management extension to a surface">
706 A wp_color_management_surface_v1 allows the client to set the color
707 space and HDR properties of a surface.
708
709 If the wl_surface associated with the wp_color_management_surface_v1 is
710 destroyed, the wp_color_management_surface_v1 object becomes inert.
711 </description>
712
713 <request name="destroy" type="destructor">
714 <description summary="destroy the color management interface for a surface">
715 Destroy the wp_color_management_surface_v1 object and do the same as
716 unset_image_description.
717 </description>
718 </request>
719
720 <enum name="error">
721 <description summary="protocol errors"/>
722 <entry name="render_intent" value="0"
723 summary="unsupported rendering intent"/>
724 <entry name="image_description" value="1"
725 summary="invalid image description"/>
726 <entry name="inert" value="2"
727 summary="forbidden request on inert object"/>
728 </enum>
729
730 <request name="set_image_description">
731 <description summary="set the surface image description">
732 If this protocol object is inert, the protocol error inert is raised.
733
734 Set the image description of the underlying surface. The image
735 description and rendering intent are double-buffered state, see
736 wl_surface.commit.
737
738 It is the client's responsibility to understand the image description
739 it sets on a surface, and to provide content that matches that image
740 description. Compositors might convert images to match their own or any
741 other image descriptions.
742
743 Image descriptions which are not ready (see wp_image_description_v1)
744 are forbidden in this request, and in such case the protocol error
745 image_description is raised.
746
747 All image descriptions which are ready (see wp_image_description_v1)
748 are allowed and must always be accepted by the compositor.
749
750 When an image description is set on a surface, it establishes an
751 explicit link between surface pixel values and surface colorimetry.
752 This link may be undefined for some pixel values, see the image
753 description creator interfaces for the conditions. Non-finite
754 floating-point values (NaN, Inf) always have an undefined colorimetry.
755
756 A rendering intent provides the client's preference on how surface
757 colorimetry should be mapped to each output. The render_intent value
758 must be one advertised by the compositor with
759 wp_color_manager_v1.render_intent event, otherwise the protocol error
760 render_intent is raised.
761
762 By default, a surface does not have an associated image description
763 nor a rendering intent. The handling of color on such surfaces is
764 compositor implementation defined. Compositors should handle such
765 surfaces as sRGB, but may handle them differently if they have specific
766 requirements.
767
768 Setting the image description has copy semantics; after this request,
769 the image description can be immediately destroyed without affecting
770 the pending state of the surface.
771 </description>
772
773 <arg name="image_description"
774 type="object" interface="wp_image_description_v1"/>
775 <arg name="render_intent"
776 type="uint" enum="wp_color_manager_v1.render_intent"
777 summary="rendering intent"/>
778 </request>
779
780 <request name="unset_image_description">
781 <description summary="remove the surface image description">
782 If this protocol object is inert, the protocol error inert is raised.
783
784 This request removes any image description from the surface. See
785 set_image_description for how a compositor handles a surface without
786 an image description. This is double-buffered state, see
787 wl_surface.commit.
788 </description>
789 </request>
790 </interface>
791
792 <interface name="wp_color_management_surface_feedback_v1" version="3">
793 <description summary="color management extension to a surface">
794 A wp_color_management_surface_feedback_v1 allows the client to get the
795 preferred image description of a surface.
796
797 If the wl_surface associated with this object is destroyed, the
798 wp_color_management_surface_feedback_v1 object becomes inert.
799 </description>
800
801 <request name="destroy" type="destructor">
802 <description summary="destroy the color management interface for a surface">
803 Destroy the wp_color_management_surface_feedback_v1 object.
804 </description>
805 </request>
806
807 <enum name="error">
808 <description summary="protocol errors"/>
809 <entry name="inert" value="0"
810 summary="forbidden request on inert object"/>
811 <entry name="unsupported_feature" value="1"
812 summary="attempted to use an unsupported feature"/>
813 </enum>
814
815 <event name="preferred_changed" deprecated-since="2">
816 <description summary="the preferred image description changed (32-bit)">
817 Starting from interface version 2, 'preferred_changed2' is sent instead
818 of this event. See the 'preferred_changed2' event for the definition.
819 </description>
820
821 <arg name="identity" type="uint"
822 summary="the 32-bit image description id number"/>
823 </event>
824
825 <request name="get_preferred">
826 <description summary="get the preferred image description">
827 If this protocol object is inert, the protocol error inert is raised.
828
829 The preferred image description represents the compositor's preferred
830 color encoding for this wl_surface at the current time. There might be
831 performance and power advantages, as well as improved color
832 reproduction, if the image description of a content update matches the
833 preferred image description.
834
835 This creates a new wp_image_description_v1 object for the currently
836 preferred image description for the wl_surface. The client should
837 stop using and destroy the image descriptions created by earlier
838 invocations of this request for the associated wl_surface.
839 This request is usually sent as a reaction to the preferred_changed
840 event or when creating a wp_color_management_surface_feedback_v1 object
841 if the client is capable of adapting to image descriptions.
842
843 The created wp_image_description_v1 object preserves the preferred image
844 description of the wl_surface from the time the object was created.
845
846 The resulting image description object allows get_information request.
847
848 If the image description is parametric, the client should set it on its
849 wl_surface only if the image description is an exact match with the
850 client content. Particularly if everything else matches, but the target
851 color volume is greater than what the client needs, the client should
852 create its own parameric image description with its exact parameters.
853
854 If the interface version is inadequate for the preferred image
855 description, meaning that the client does not support all the
856 events needed to deliver the crucial information, the resulting image
857 description object shall immediately deliver the
858 wp_image_description_v1.failed event with the low_version cause,
859 otherwise the object shall immediately deliver the ready event.
860 </description>
861
862 <arg name="image_description"
863 type="new_id" interface="wp_image_description_v1"/>
864 </request>
865
866 <request name="get_preferred_parametric">
867 <description summary="get the preferred image description">
868 The same description as for get_preferred applies, except the returned
869 image description is guaranteed to be parametric. This is meant for
870 clients that can only deal with parametric image descriptions.
871
872 If the compositor doesn't support parametric image descriptions, the
873 unsupported_feature error is emitted.
874 </description>
875
876 <arg name="image_description"
877 type="new_id" interface="wp_image_description_v1"/>
878 </request>
879
880 <!-- Version 2 additions -->
881
882 <event name="preferred_changed2" since="2">
883 <description summary="the preferred image description changed">
884 The preferred image description is the one which likely has the most
885 performance and/or quality benefits for the compositor if used by the
886 client for its wl_surface contents. This event is sent whenever the
887 compositor changes the wl_surface's preferred image description.
888
889 This event sends the identity of the new preferred state as the argument,
890 so clients who are aware of the image description already can reuse it.
891 Otherwise, if the client client wants to know what the preferred image
892 description is, it shall use the get_preferred request.
893
894 The preferred image description is not automatically used for anything.
895 It is only a hint, and clients may set any valid image description with
896 set_image_description, but there might be performance and color accuracy
897 improvements by providing the wl_surface contents in the preferred
898 image description. Therefore clients that can, should render according
899 to the preferred image description
900 </description>
901
902 <arg name="identity_hi" type="uint"
903 summary="high 32 bits of the 64-bit image description id number"/>
904 <arg name="identity_lo" type="uint"
905 summary="low 32 bits of the 64-bit image description id number"/>
906 </event>
907
908 </interface>
909
910 <interface name="wp_image_description_creator_icc_v1" version="3">
911 <description summary="holder of image description ICC information">
912 This type of object is used for collecting all the information required
913 to create a wp_image_description_v1 object from an ICC file. A complete
914 set of required parameters consists of these properties:
915 - ICC file
916
917 Each required property must be set exactly once if the client is to create
918 an image description. The set requests verify that a property was not
919 already set. The create request verifies that all required properties are
920 set. There may be several alternative requests for setting each property,
921 and in that case the client must choose one of them.
922
923 Once all properties have been set, the create request must be used to
924 create the image description object, destroying the creator in the
925 process.
926
927 The link between a pixel value (a device value in ICC) and its respective
928 colorimetry is defined by the details of the particular ICC profile.
929 Those details also determine when colorimetry becomes undefined.
930 </description>
931
932 <enum name="error">
933 <description summary="protocol errors"/>
934
935 <entry name="incomplete_set" value="0"
936 summary="incomplete parameter set"/>
937 <entry name="already_set" value="1"
938 summary="property already set"/>
939 <entry name="bad_fd" value="2"
940 summary="fd not seekable and readable"/>
941 <entry name="bad_size" value="3"
942 summary="no or too much data"/>
943 <entry name="out_of_file" value="4"
944 summary="offset + length exceeds file size"/>
945 </enum>
946
947 <request name="create" type="destructor">
948 <description summary="Create the image description object from ICC data">
949 Create an image description object based on the ICC information
950 previously set on this object. A compositor must parse the ICC data in
951 some undefined but finite amount of time.
952
953 The completeness of the parameter set is verified. If the set is not
954 complete, the protocol error incomplete_set is raised. For the
955 definition of a complete set, see the description of this interface.
956
957 If the particular combination of the information is not supported
958 by the compositor, the resulting image description object shall
959 immediately deliver the wp_image_description_v1.failed event with the
960 'unsupported' cause. If a valid image description was created from the
961 information, the wp_image_description_v1.ready event will eventually
962 be sent instead.
963
964 This request destroys the wp_image_description_creator_icc_v1 object.
965
966 The resulting image description object does not allow get_information
967 request.
968 </description>
969
970 <arg name="image_description"
971 type="new_id" interface="wp_image_description_v1"/>
972 </request>
973
974 <request name="set_icc_file">
975 <description summary="set the ICC profile file">
976 Sets the ICC profile file to be used as the basis of the image
977 description.
978
979 The data shall be found through the given fd at the given offset, having
980 the given length. The fd must be seekable and readable. Violating these
981 requirements raises the bad_fd protocol error.
982
983 If reading the data fails due to an error independent of the client, the
984 compositor shall send the wp_image_description_v1.failed event on the
985 created wp_image_description_v1 with the 'operating_system' cause.
986
987 The maximum size of the ICC profile is 32 MB. If length is greater than
988 that or zero, the protocol error bad_size is raised. If offset + length
989 exceeds the file size, the protocol error out_of_file is raised.
990
991 A compositor may read the file at any time starting from this request
992 and only until whichever happens first:
993 - If create request was issued, the wp_image_description_v1 object
994 delivers either failed or ready event; or
995 - if create request was not issued, this
996 wp_image_description_creator_icc_v1 object is destroyed.
997
998 A compositor shall not modify the contents of the file, and the fd may
999 be sealed for writes and size changes. The client must ensure to its
1000 best ability that the data does not change while the compositor is
1001 reading it.
1002
1003 The data must represent a valid ICC profile. The ICC profile version
1004 must be 2 or 4, it must be a 3 channel profile and the class must be
1005 Display or ColorSpace. Violating these requirements will not result in a
1006 protocol error, but will eventually send the
1007 wp_image_description_v1.failed event on the created
1008 wp_image_description_v1 with the 'unsupported' cause.
1009
1010 See the International Color Consortium specification ICC.1:2022 for more
1011 details about ICC profiles.
1012
1013 If ICC file has already been set on this object, the protocol error
1014 already_set is raised.
1015 </description>
1016
1017 <arg name="icc_profile" type="fd"
1018 summary="ICC profile"/>
1019 <arg name="offset" type="uint"
1020 summary="byte offset in fd to start of ICC data"/>
1021 <arg name="length" type="uint"
1022 summary="length of ICC data in bytes"/>
1023 </request>
1024 </interface>
1025
1026 <interface name="wp_image_description_creator_params_v1" version="3">
1027 <description summary="holder of image description parameters">
1028 This type of object is used for collecting all the parameters required
1029 to create a wp_image_description_v1 object. A complete set of required
1030 parameters consists of these properties:
1031 - transfer characteristic function (tf)
1032 - chromaticities of primaries and white point (primary color volume)
1033
1034 The following properties are optional and have a well-defined default
1035 if not explicitly set:
1036 - primary color volume luminance range
1037 - reference white luminance level
1038 - mastering display primaries and white point (target color volume)
1039 - mastering luminance range
1040
1041 The following properties are optional and will be ignored
1042 if not explicitly set:
1043 - maximum content light level
1044 - maximum frame-average light level
1045
1046 Each required property must be set exactly once if the client is to create
1047 an image description. The set requests verify that a property was not
1048 already set. The create request verifies that all required properties are
1049 set. There may be several alternative requests for setting each property,
1050 and in that case the client must choose one of them.
1051
1052 Once all properties have been set, the create request must be used to
1053 create the image description object, destroying the creator in the
1054 process.
1055
1056 A viewer, who is viewing the display defined by the resulting image
1057 description (the viewing environment included), is assumed to be fully
1058 adapted to the primary color volume's white point.
1059
1060 Any of the following conditions will cause the colorimetry of a pixel
1061 to become undefined:
1062 - Values outside of the defined range of the transfer characteristic.
1063 - Tristimulus that exceeds the target color volume.
1064 - If extended_target_volume is not supported: tristimulus that exceeds
1065 the primary color volume.
1066
1067 The closest correspondence to an image description created through this
1068 interface is the Display class of profiles in ICC.
1069 </description>
1070
1071 <enum name="error">
1072 <description summary="protocol errors"/>
1073
1074 <entry name="incomplete_set" value="0"
1075 summary="incomplete parameter set"/>
1076 <entry name="already_set" value="1"
1077 summary="property already set"/>
1078 <entry name="unsupported_feature" value="2"
1079 summary="request not supported"/>
1080 <entry name="invalid_tf" value="3"
1081 summary="invalid transfer characteristic"/>
1082 <entry name="invalid_primaries_named" value="4"
1083 summary="invalid primaries named"/>
1084 <entry name="invalid_luminance" value="5"
1085 summary="invalid luminance value or range"/>
1086 </enum>
1087
1088 <request name="create" type="destructor">
1089 <description summary="Create the image description object using params">
1090 Create an image description object based on the parameters previously
1091 set on this object.
1092
1093 The completeness of the parameter set is verified. If the set is not
1094 complete, the protocol error incomplete_set is raised. For the
1095 definition of a complete set, see the description of this interface.
1096
1097 When both max_cll and max_fall are set, max_fall must be less or equal
1098 to max_cll otherwise the invalid_luminance protocol error is raised.
1099
1100 In version 1, these following conditions also result in the
1101 invalid_luminance protocol error. Version 2 and later do not have this
1102 requirement.
1103 - When max_cll is set, it must be greater than min L and less or equal
1104 to max L of the mastering luminance range.
1105 - When max_fall is set, it must be greater than min L and less or equal
1106 to max L of the mastering luminance range.
1107
1108 If the particular combination of the parameter set is not supported
1109 by the compositor, the resulting image description object shall
1110 immediately deliver the wp_image_description_v1.failed event with the
1111 'unsupported' cause. If a valid image description was created from the
1112 parameter set, the wp_image_description_v1.ready event will eventually
1113 be sent instead.
1114
1115 This request destroys the wp_image_description_creator_params_v1
1116 object.
1117
1118 The resulting image description object does not allow get_information
1119 request.
1120 </description>
1121
1122 <arg name="image_description"
1123 type="new_id" interface="wp_image_description_v1"/>
1124 </request>
1125
1126 <request name="set_tf_named">
1127 <description summary="named transfer characteristic">
1128 Sets the transfer characteristic using explicitly enumerated named
1129 functions.
1130
1131 When the resulting image description is attached to an image, the
1132 content should be decoded according to the industry standard
1133 practices for the transfer characteristic.
1134
1135 Only names advertised with wp_color_manager_v1 event supported_tf_named
1136 are allowed. Other values shall raise the protocol error invalid_tf.
1137
1138 If transfer characteristic has already been set on this object, the
1139 protocol error already_set is raised.
1140 </description>
1141
1142 <arg name="tf" type="uint" enum="wp_color_manager_v1.transfer_function"
1143 summary="named transfer function"/>
1144 </request>
1145
1146 <request name="set_tf_power">
1147 <description summary="transfer characteristic as a power curve">
1148 Sets the color component transfer characteristic to a power curve with
1149 the given exponent. Negative values are handled by mirroring the
1150 positive half of the curve through the origin. The valid domain and
1151 range of the curve are all finite real numbers. This curve represents
1152 the conversion from electrical to optical color channel values.
1153
1154 The curve exponent shall be multiplied by 10000 to get the argument eexp
1155 value to carry the precision of 4 decimals.
1156
1157 The curve exponent must be at least 1.0 and at most 10.0. Otherwise the
1158 protocol error invalid_tf is raised.
1159
1160 If transfer characteristic has already been set on this object, the
1161 protocol error already_set is raised.
1162
1163 This request can be used when the compositor advertises
1164 wp_color_manager_v1.feature.set_tf_power. Otherwise this request raises
1165 the protocol error unsupported_feature.
1166 </description>
1167
1168 <arg name="eexp" type="uint" summary="the exponent * 10000"/>
1169 </request>
1170
1171 <request name="set_primaries_named">
1172 <description summary="named primaries">
1173 Sets the color primaries and white point using explicitly named sets.
1174 This describes the primary color volume which is the basis for color
1175 value encoding.
1176
1177 Only names advertised with wp_color_manager_v1 event
1178 supported_primaries_named are allowed. Other values shall raise the
1179 protocol error invalid_primaries_named.
1180
1181 If primaries have already been set on this object, the protocol error
1182 already_set is raised.
1183 </description>
1184
1185 <arg name="primaries" type="uint" enum="wp_color_manager_v1.primaries"
1186 summary="named primaries"/>
1187 </request>
1188
1189 <request name="set_primaries">
1190 <description summary="primaries as chromaticity coordinates">
1191 Sets the color primaries and white point using CIE 1931 xy chromaticity
1192 coordinates. This describes the primary color volume which is the basis
1193 for color value encoding.
1194
1195 Each coordinate value is multiplied by 1 million to get the argument
1196 value to carry precision of 6 decimals.
1197
1198 If primaries have already been set on this object, the protocol error
1199 already_set is raised.
1200
1201 This request can be used if the compositor advertises
1202 wp_color_manager_v1.feature.set_primaries. Otherwise this request raises
1203 the protocol error unsupported_feature.
1204 </description>
1205
1206 <arg name="r_x" type="int" summary="Red x * 1M"/>
1207 <arg name="r_y" type="int" summary="Red y * 1M"/>
1208 <arg name="g_x" type="int" summary="Green x * 1M"/>
1209 <arg name="g_y" type="int" summary="Green y * 1M"/>
1210 <arg name="b_x" type="int" summary="Blue x * 1M"/>
1211 <arg name="b_y" type="int" summary="Blue y * 1M"/>
1212 <arg name="w_x" type="int" summary="White x * 1M"/>
1213 <arg name="w_y" type="int" summary="White y * 1M"/>
1214 </request>
1215
1216 <request name="set_luminances">
1217 <description summary="primary color volume luminance range and reference white">
1218 Sets the primary color volume luminance range and the reference white
1219 luminance level. These values include the minimum display emission, but
1220 not external flare. The minimum display emission is assumed to have
1221 the chromaticity of the primary color volume white point.
1222
1223 The default luminances from
1224 https://www.color.org/chardata/rgb/srgb.xalter are
1225 - primary color volume minimum: 0.2 cd/m²
1226 - primary color volume maximum: 80 cd/m²
1227 - reference white: 80 cd/m²
1228
1229 Setting a named transfer characteristic can imply other default
1230 luminances.
1231
1232 The default luminances get overwritten when this request is used.
1233 With transfer_function.st2084_pq the given 'max_lum' value is ignored,
1234 and 'max_lum' is taken as 'min_lum' + 10000 cd/m².
1235
1236 'min_lum' and 'max_lum' specify the minimum and maximum luminances of
1237 the primary color volume as reproduced by the targeted display.
1238
1239 'reference_lum' specifies the luminance of the reference white as
1240 reproduced by the targeted display, and reflects the targeted viewing
1241 environment.
1242
1243 Compositors should make sure that all content is anchored, meaning that
1244 an input signal level of 'reference_lum' on one image description and
1245 another input signal level of 'reference_lum' on another image
1246 description should produce the same output level, even though the
1247 'reference_lum' on both image representations can be different.
1248
1249 'reference_lum' may be higher than 'max_lum'. In that case reaching
1250 the reference white output level in image content requires the
1251 'extended_target_volume' feature support.
1252
1253 If 'max_lum' or 'reference_lum' are less than or equal to 'min_lum',
1254 the protocol error invalid_luminance is raised.
1255
1256 The minimum luminance is multiplied by 10000 to get the argument
1257 'min_lum' value and carries precision of 4 decimals. The maximum
1258 luminance and reference white luminance values are unscaled.
1259
1260 If the primary color volume luminance range and the reference white
1261 luminance level have already been set on this object, the protocol error
1262 already_set is raised.
1263
1264 This request can be used if the compositor advertises
1265 wp_color_manager_v1.feature.set_luminances. Otherwise this request
1266 raises the protocol error unsupported_feature.
1267 </description>
1268
1269 <arg name="min_lum" type="uint"
1270 summary="minimum luminance (cd/m²) * 10000"/>
1271 <arg name="max_lum" type="uint"
1272 summary="maximum luminance (cd/m²)"/>
1273 <arg name="reference_lum" type="uint"
1274 summary="reference white luminance (cd/m²)"/>
1275 </request>
1276
1277 <request name="set_mastering_display_primaries">
1278 <description summary="mastering display primaries as chromaticity coordinates">
1279 Provides the color primaries and white point of the mastering display
1280 using CIE 1931 xy chromaticity coordinates. This is compatible with the
1281 SMPTE ST 2086 definition of HDR static metadata.
1282
1283 The mastering display primaries and mastering display luminances define
1284 the target color volume.
1285
1286 If mastering display primaries are not explicitly set, the target color
1287 volume is assumed to have the same primaries as the primary color volume.
1288
1289 The target color volume is defined by all tristimulus values between 0.0
1290 and 1.0 (inclusive) of the color space defined by the given mastering
1291 display primaries and white point. The colorimetry is identical between
1292 the container color space and the mastering display color space,
1293 including that no chromatic adaptation is applied even if the white
1294 points differ.
1295
1296 The target color volume can exceed the primary color volume to allow for
1297 a greater color volume with an existing color space definition (for
1298 example scRGB). It can be smaller than the primary color volume to
1299 minimize gamut and tone mapping distances for big color spaces (HDR
1300 metadata).
1301
1302 To make use of the entire target color volume a suitable pixel format
1303 has to be chosen (e.g. floating point to exceed the primary color
1304 volume, or abusing limited quantization range as with xvYCC).
1305
1306 Each coordinate value is multiplied by 1 million to get the argument
1307 value to carry precision of 6 decimals.
1308
1309 If mastering display primaries have already been set on this object, the
1310 protocol error already_set is raised.
1311
1312 This request can be used if the compositor advertises
1313 wp_color_manager_v1.feature.set_mastering_display_primaries. Otherwise
1314 this request raises the protocol error unsupported_feature. The
1315 advertisement implies support only for target color volumes fully
1316 contained within the primary color volume.
1317
1318 If a compositor additionally supports target color volume exceeding the
1319 primary color volume, it must advertise
1320 wp_color_manager_v1.feature.extended_target_volume. If a client uses
1321 target color volume exceeding the primary color volume and the
1322 compositor does not support it, the result is implementation defined.
1323 Compositors are recommended to detect this case and fail the image
1324 description gracefully, but it may as well result in color artifacts.
1325 </description>
1326
1327 <arg name="r_x" type="int" summary="Red x * 1M"/>
1328 <arg name="r_y" type="int" summary="Red y * 1M"/>
1329 <arg name="g_x" type="int" summary="Green x * 1M"/>
1330 <arg name="g_y" type="int" summary="Green y * 1M"/>
1331 <arg name="b_x" type="int" summary="Blue x * 1M"/>
1332 <arg name="b_y" type="int" summary="Blue y * 1M"/>
1333 <arg name="w_x" type="int" summary="White x * 1M"/>
1334 <arg name="w_y" type="int" summary="White y * 1M"/>
1335 </request>
1336
1337 <request name="set_mastering_luminance">
1338 <description summary="display mastering luminance range">
1339 Sets the luminance range that was used during the content mastering
1340 process as the minimum and maximum absolute luminance L. These values
1341 include the minimum display emission and ambient flare luminances,
1342 assumed to be optically additive and have the chromaticity of the
1343 primary color volume white point. This should be
1344 compatible with the SMPTE ST 2086 definition of HDR static metadata.
1345
1346 The mastering display primaries and mastering display luminances define
1347 the target color volume.
1348
1349 If mastering luminances are not explicitly set, the target color volume
1350 is assumed to have the same min and max luminances as the primary color
1351 volume.
1352
1353 If max L is less than or equal to min L, the protocol error
1354 invalid_luminance is raised.
1355
1356 Min L value is multiplied by 10000 to get the argument min_lum value
1357 and carry precision of 4 decimals. Max L value is unscaled for max_lum.
1358
1359 This request can be used if the compositor advertises
1360 wp_color_manager_v1.feature.set_mastering_display_primaries. Otherwise
1361 this request raises the protocol error unsupported_feature. The
1362 advertisement implies support only for target color volumes fully
1363 contained within the primary color volume.
1364
1365 If a compositor additionally supports target color volume exceeding the
1366 primary color volume, it must advertise
1367 wp_color_manager_v1.feature.extended_target_volume. If a client uses
1368 target color volume exceeding the primary color volume and the
1369 compositor does not support it, the result is implementation defined.
1370 Compositors are recommended to detect this case and fail the image
1371 description gracefully, but it may as well result in color artifacts.
1372 </description>
1373
1374 <arg name="min_lum" type="uint" summary="min L (cd/m²) * 10000"/>
1375 <arg name="max_lum" type="uint" summary="max L (cd/m²)"/>
1376 </request>
1377
1378 <request name="set_max_cll">
1379 <description summary="maximum content light level">
1380 Sets the maximum content light level (max_cll) as defined by CTA-861-H.
1381
1382 max_cll is undefined by default.
1383 </description>
1384
1385 <arg name="max_cll" type="uint" summary="Maximum content light level (cd/m²)"/>
1386 </request>
1387
1388 <request name="set_max_fall">
1389 <description summary="maximum frame-average light level">
1390 Sets the maximum frame-average light level (max_fall) as defined by
1391 CTA-861-H.
1392
1393 max_fall is undefined by default.
1394 </description>
1395
1396 <arg name="max_fall" type="uint" summary="Maximum frame-average light level (cd/m²)"/>
1397 </request>
1398 </interface>
1399
1400 <interface name="wp_image_description_v1" version="3">
1401 <description summary="Colorimetric image description">
1402 An image description carries information about the pixel color encoding
1403 and its intended display and viewing environment. The image description is
1404 attached to a wl_surface via
1405 wp_color_management_surface_v1.set_image_description. A compositor can use
1406 this information to decode pixel values into colorimetrically meaningful
1407 quantities, which allows the compositor to transform the surface contents
1408 to become suitable for various displays and viewing environments.
1409
1410 Note, that the wp_image_description_v1 object is not ready to be used
1411 immediately after creation. The object eventually delivers either the
1412 'ready' or the 'failed' event, specified in all requests creating it. The
1413 object is deemed "ready" after receiving the 'ready' event.
1414
1415 An object which is not ready is illegal to use, it can only be destroyed.
1416 Any other request in this interface shall result in the 'not_ready'
1417 protocol error. Attempts to use an object which is not ready through other
1418 interfaces shall raise protocol errors defined there.
1419
1420 Once created and regardless of how it was created, a
1421 wp_image_description_v1 object always refers to one fixed image
1422 description. It cannot change after creation.
1423 </description>
1424
1425 <request name="destroy" type="destructor">
1426 <description summary="destroy the image description">
1427 Destroy this object. It is safe to destroy an object which is not ready.
1428
1429 Destroying a wp_image_description_v1 object has no side-effects, not
1430 even if a wp_color_management_surface_v1.set_image_description has not
1431 yet been followed by a wl_surface.commit.
1432 </description>
1433 </request>
1434
1435 <enum name="error">
1436 <description summary="protocol errors"/>
1437
1438 <entry name="not_ready" value="0"
1439 summary="attempted to use an object which is not ready"/>
1440 <entry name="no_information" value="1"
1441 summary="get_information not allowed"/>
1442 </enum>
1443
1444 <enum name="cause">
1445 <description summary="generic reason for failure"/>
1446
1447 <entry name="low_version" value="0"
1448 summary="interface version too low"/>
1449 <entry name="unsupported" value="1"
1450 summary="unsupported image description data"/>
1451 <entry name="operating_system" value="2"
1452 summary="error independent of the client"/>
1453 <entry name="no_output" value="3"
1454 summary="the relevant output no longer exists"/>
1455 </enum>
1456
1457 <event name="failed">
1458 <description summary="graceful error on creating the image description">
1459 If creating a wp_image_description_v1 object fails for a reason that is
1460 not defined as a protocol error, this event is sent.
1461
1462 The requests that create image description objects define whether and
1463 when this can occur. Only such creation requests can trigger this event.
1464 This event cannot be triggered after the image description was
1465 successfully formed.
1466
1467 Once this event has been sent, the wp_image_description_v1 object will
1468 never become ready and it can only be destroyed.
1469 </description>
1470
1471 <arg name="cause" type="uint" enum="cause"
1472 summary="generic reason"/>
1473 <arg name="msg" type="string"
1474 summary="ad hoc human-readable explanation"/>
1475 </event>
1476
1477 <event name="ready" deprecated-since="2">
1478 <description summary="the object is ready to be used (32-bit)">
1479 Starting from interface version 2, the 'ready2' event is sent instead
1480 of this event.
1481
1482 For the definition of this event, see the 'ready2' event. The
1483 difference to this event is as follows.
1484
1485 The id number is valid only as long as the protocol object is alive. If
1486 all protocol objects referring to the same image description record are
1487 destroyed, the id number may be recycled for a different image
1488 description record.
1489 </description>
1490
1491 <arg name="identity" type="uint"
1492 summary="the 32-bit image description id number"/>
1493 </event>
1494
1495 <request name="get_information">
1496 <description summary="get information about the image description">
1497 Creates a wp_image_description_info_v1 object which delivers the
1498 information that makes up the image description.
1499
1500 Not all image description protocol objects allow get_information
1501 request. Whether it is allowed or not is defined by the request that
1502 created the object. If get_information is not allowed, the protocol
1503 error no_information is raised.
1504 </description>
1505
1506 <arg name="information"
1507 type="new_id" interface="wp_image_description_info_v1"/>
1508 </request>
1509
1510 <!-- Version 2 additions -->
1511
1512 <event name="ready2" since="2">
1513 <description summary="the object is ready to be used">
1514 Once this event has been sent, the wp_image_description_v1 object is
1515 deemed "ready". Ready objects can be used to send requests and can be
1516 used through other interfaces.
1517
1518 Every ready wp_image_description_v1 protocol object refers to an
1519 underlying image description record in the compositor. Multiple protocol
1520 objects may end up referring to the same record. Clients may identify
1521 these "copies" by comparing their id numbers: if the numbers from two
1522 protocol objects are identical, the protocol objects refer to the same
1523 image description record. Two different image description records
1524 cannot have the same id number simultaneously. The id number does not
1525 change during the lifetime of the image description record.
1526
1527 Image description id number is not a protocol object id. Zero is
1528 reserved as an invalid id number. It shall not be possible for a client
1529 to refer to an image description by its id number in protocol. The id
1530 numbers might not be portable between Wayland connections. A compositor
1531 shall not send an invalid id number.
1532
1533 Compositors must not recycle image description id numbers.
1534
1535 This identity allows clients to de-duplicate image description records
1536 and avoid get_information request if they already have the image
1537 description information.
1538 </description>
1539
1540 <arg name="identity_hi" type="uint"
1541 summary="high 32 bits of the 64-bit image description id number"/>
1542 <arg name="identity_lo" type="uint"
1543 summary="low 32 bits of the 64-bit image description id number"/>
1544 </event>
1545 </interface>
1546
1547 <interface name="wp_image_description_info_v1" version="3">
1548 <description summary="Colorimetric image description information">
1549 Sends all matching events describing an image description object exactly
1550 once and finally sends the 'done' event.
1551
1552 This means
1553 - if the image description is parametric, it must send
1554 - primaries
1555 - named_primaries, if applicable
1556 - at least one of tf_power and tf_named, as applicable
1557 - luminances
1558 - target_primaries
1559 - target_luminance
1560 - if the image description is parametric, it may send, if applicable,
1561 - target_max_cll
1562 - target_max_fall
1563 - if the image description contains an ICC profile, it must send the
1564 icc_file event
1565
1566 Once a wp_image_description_info_v1 object has delivered a 'done' event it
1567 is automatically destroyed.
1568
1569 Every wp_image_description_info_v1 created from the same
1570 wp_image_description_v1 shall always return the exact same data.
1571 </description>
1572
1573 <event name="done" type="destructor">
1574 <description summary="end of information">
1575 Signals the end of information events and destroys the object.
1576 </description>
1577 </event>
1578
1579 <event name="icc_file">
1580 <description summary="ICC profile matching the image description">
1581 The icc argument provides a file descriptor to the client which may be
1582 memory-mapped to provide the ICC profile matching the image description.
1583 The fd is read-only, and if mapped then it must be mapped with
1584 MAP_PRIVATE by the client.
1585
1586 The ICC profile version and other details are determined by the
1587 compositor. There is no provision for a client to ask for a specific
1588 kind of a profile.
1589 </description>
1590
1591 <arg name="icc" type="fd" summary="ICC profile file descriptor"/>
1592 <arg name="icc_size" type="uint" summary="ICC profile size, in bytes"/>
1593 <!-- Offset always 0, compositor must not expose unnecessary data. -->
1594 </event>
1595
1596 <event name="primaries">
1597 <description summary="primaries as chromaticity coordinates">
1598 Delivers the primary color volume primaries and white point using CIE
1599 1931 xy chromaticity coordinates.
1600
1601 Each coordinate value is multiplied by 1 million to get the argument
1602 value to carry precision of 6 decimals.
1603 </description>
1604
1605 <arg name="r_x" type="int" summary="Red x * 1M"/>
1606 <arg name="r_y" type="int" summary="Red y * 1M"/>
1607 <arg name="g_x" type="int" summary="Green x * 1M"/>
1608 <arg name="g_y" type="int" summary="Green y * 1M"/>
1609 <arg name="b_x" type="int" summary="Blue x * 1M"/>
1610 <arg name="b_y" type="int" summary="Blue y * 1M"/>
1611 <arg name="w_x" type="int" summary="White x * 1M"/>
1612 <arg name="w_y" type="int" summary="White y * 1M"/>
1613 </event>
1614
1615 <event name="primaries_named">
1616 <description summary="named primaries">
1617 Delivers the primary color volume primaries and white point using an
1618 explicitly enumerated named set.
1619 </description>
1620
1621 <arg name="primaries" type="uint" enum="wp_color_manager_v1.primaries"
1622 summary="named primaries"/>
1623 </event>
1624
1625 <event name="tf_power">
1626 <description summary="transfer characteristic as a power curve">
1627 The color component transfer characteristic of this image description is
1628 a pure power curve. This event provides the exponent of the power
1629 function. This curve represents the conversion from electrical to
1630 optical pixel or color values.
1631
1632 The curve exponent has been multiplied by 10000 to get the argument eexp
1633 value to carry the precision of 4 decimals.
1634 </description>
1635
1636 <arg name="eexp" type="uint" summary="the exponent * 10000"/>
1637 </event>
1638
1639 <event name="tf_named">
1640 <description summary="named transfer characteristic">
1641 Delivers the transfer characteristic using an explicitly enumerated
1642 named function.
1643 </description>
1644
1645 <arg name="tf" type="uint" enum="wp_color_manager_v1.transfer_function"
1646 summary="named transfer function"/>
1647 </event>
1648
1649 <event name="luminances">
1650 <description summary="primary color volume luminance range and reference white">
1651 Delivers the primary color volume luminance range and the reference
1652 white luminance level. These values include the minimum display emission
1653 and ambient flare luminances, assumed to be optically additive and have
1654 the chromaticity of the primary color volume white point.
1655
1656 The minimum luminance is multiplied by 10000 to get the argument
1657 'min_lum' value and carries precision of 4 decimals. The maximum
1658 luminance and reference white luminance values are unscaled.
1659 </description>
1660
1661 <arg name="min_lum" type="uint"
1662 summary="minimum luminance (cd/m²) * 10000"/>
1663 <arg name="max_lum" type="uint"
1664 summary="maximum luminance (cd/m²)"/>
1665 <arg name="reference_lum" type="uint"
1666 summary="reference white luminance (cd/m²)"/>
1667 </event>
1668
1669 <event name="target_primaries">
1670 <description summary="target primaries as chromaticity coordinates">
1671 Provides the color primaries and white point of the target color volume
1672 using CIE 1931 xy chromaticity coordinates. This is compatible with the
1673 SMPTE ST 2086 definition of HDR static metadata for mastering displays.
1674
1675 While primary color volume is about how color is encoded, the target
1676 color volume is the actually displayable color volume.
1677
1678 Each coordinate value is multiplied by 1 million to get the argument
1679 value to carry precision of 6 decimals.
1680 </description>
1681
1682 <arg name="r_x" type="int" summary="Red x * 1M"/>
1683 <arg name="r_y" type="int" summary="Red y * 1M"/>
1684 <arg name="g_x" type="int" summary="Green x * 1M"/>
1685 <arg name="g_y" type="int" summary="Green y * 1M"/>
1686 <arg name="b_x" type="int" summary="Blue x * 1M"/>
1687 <arg name="b_y" type="int" summary="Blue y * 1M"/>
1688 <arg name="w_x" type="int" summary="White x * 1M"/>
1689 <arg name="w_y" type="int" summary="White y * 1M"/>
1690 </event>
1691
1692 <event name="target_luminance">
1693 <description summary="target luminance range">
1694 Provides the luminance range that the image description is targeting as
1695 the minimum and maximum absolute luminance L. These values include the
1696 minimum display emission and ambient flare luminances, assumed to be
1697 optically additive and have the chromaticity of the primary color
1698 volume white point. This should be compatible with the SMPTE ST 2086
1699 definition of HDR static metadata.
1700
1701 This luminance range is only theoretical and may not correspond to the
1702 luminance of light emitted on an actual display.
1703
1704 Min L value is multiplied by 10000 to get the argument min_lum value and
1705 carry precision of 4 decimals. Max L value is unscaled for max_lum.
1706 </description>
1707
1708 <arg name="min_lum" type="uint" summary="min L (cd/m²) * 10000"/>
1709 <arg name="max_lum" type="uint" summary="max L (cd/m²)"/>
1710 </event>
1711
1712 <event name="target_max_cll">
1713 <description summary="target maximum content light level">
1714 Provides the targeted max_cll of the image description. max_cll is
1715 defined by CTA-861-H.
1716
1717 This luminance is only theoretical and may not correspond to the
1718 luminance of light emitted on an actual display.
1719 </description>
1720
1721 <arg name="max_cll" type="uint"
1722 summary="Maximum content light-level (cd/m²)"/>
1723 </event>
1724
1725 <event name="target_max_fall">
1726 <description summary="target maximum frame-average light level">
1727 Provides the targeted max_fall of the image description. max_fall is
1728 defined by CTA-861-H.
1729
1730 This luminance is only theoretical and may not correspond to the
1731 luminance of light emitted on an actual display.
1732 </description>
1733
1734 <arg name="max_fall" type="uint"
1735 summary="Maximum frame-average light level (cd/m²)"/>
1736 </event>
1737 </interface>
1738
1739 <interface name="wp_image_description_reference_v1" version="1" frozen="true">
1740 <description summary="Reference to an image description">
1741 This object is a reference to an image description. This interface is
1742 frozen at version 1 to allow other protocols to create
1743 wp_image_description_v1 objects.
1744
1745 The wp_color_manager_v1.get_image_description request can be used to
1746 retrieve the underlying image description.
1747 </description>
1748
1749 <request name="destroy" type="destructor">
1750 <description summary="destroy the reference">
1751 Destroy this object. This has no effect on the referenced image
1752 description.
1753 </description>
1754 </request>
1755 </interface>
1756</protocol>