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