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