1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="color_representation_v1">
3 <copyright>
4 Copyright 2022 Simon Ser
5 Copyright 2022 Red Hat, Inc.
6 Copyright 2022 Collabora, Ltd.
7 Copyright 2022-2025 Red Hat, Inc.
8
9 Permission is hereby granted, free of charge, to any person obtaining a
10 copy of this software and associated documentation files (the "Software"),
11 to deal in the Software without restriction, including without limitation
12 the rights to use, copy, modify, merge, publish, distribute, sublicense,
13 and/or sell copies of the Software, and to permit persons to whom the
14 Software is furnished to do so, subject to the following conditions:
15
16 The above copyright notice and this permission notice (including the next
17 paragraph) shall be included in all copies or substantial portions of the
18 Software.
19
20 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
23 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
25 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
26 DEALINGS IN THE SOFTWARE.
27 </copyright>
28
29 <description summary="color representation protocol extension">
30 This protocol extension delivers the metadata required to define alpha mode,
31 the color model, sub-sampling and quantization range used when interpreting
32 buffer contents. The main use case is defining how the YCbCr family of pixel
33 formats convert to RGB.
34
35 Note that this protocol does not define the colorimetry of the resulting RGB
36 channels / tristimulus values. Without the help of other extensions the
37 resulting colorimetry is therefore implementation defined.
38
39 If this extension is not used, the color representation used is compositor
40 implementation defined.
41
42 Recommendation ITU-T H.273
43 "Coding-independent code points for video signal type identification"
44 shall be referred to as simply H.273 here.
45 </description>
46
47 <interface name="wp_color_representation_manager_v1" version="1">
48 <description summary="color representation manager singleton">
49 A singleton global interface used for getting color representation
50 extensions for wl_surface. The extension interfaces allow setting the
51 color representation of surfaces.
52
53 Compositors should never remove this global.
54 </description>
55
56 <enum name="error">
57 <description summary="protocol errors"/>
58 <entry name="surface_exists" value="1"
59 summary="color representation surface exists already"/>
60 </enum>
61
62 <request name="destroy" type="destructor">
63 <description summary="destroy the manager">
64 Destroy the wp_color_representation_manager_v1 object. This does not
65 affect any other objects in any way.
66 </description>
67
68 </request>
69
70 <request name="get_surface">
71 <description summary="create a color representation interface for a wl_surface">
72 If a wp_color_representation_surface_v1 object already exists for the
73 given wl_surface, the protocol error surface_exists is raised.
74
75 This creates a new color wp_color_representation_surface_v1 object for
76 the given wl_surface.
77
78 See the wp_color_representation_surface_v1 interface for more details.
79 </description>
80 <arg name="id"
81 type="new_id" interface="wp_color_representation_surface_v1"/>
82 <arg name="surface"
83 type="object" interface="wl_surface"/>
84 </request>
85
86 <event name="supported_alpha_mode">
87 <description summary="supported alpha modes">
88 When this object is created, it shall immediately send this event once
89 for each alpha mode the compositor supports.
90
91 For the definition of the supported values, see the
92 wp_color_representation_surface_v1::alpha_mode enum.
93 </description>
94 <arg name="alpha_mode"
95 type="uint" enum="wp_color_representation_surface_v1.alpha_mode"
96 summary="supported alpha mode"/>
97 </event>
98
99 <event name="supported_coefficients_and_ranges">
100 <description summary="supported matrix coefficients and ranges">
101 When this object is created, it shall immediately send this event once
102 for each matrix coefficient and color range combination the compositor
103 supports.
104
105 For the definition of the supported values, see the
106 wp_color_representation_surface_v1::coefficients and
107 wp_color_representation_surface_v1::range enums.
108 </description>
109 <arg name="coefficients"
110 type="uint" enum="wp_color_representation_surface_v1.coefficients"
111 summary="supported matrix coefficients"/>
112 <arg name="range"
113 type="uint" enum="wp_color_representation_surface_v1.range"
114 summary="full range flag"/>
115 </event>
116
117 <event name="done">
118 <description summary="all features have been sent">
119 This event is sent when all supported features have been sent.
120 </description>
121 </event>
122 </interface>
123
124 <interface name="wp_color_representation_surface_v1" version="1">
125 <description summary="color representation extension to a surface">
126 A wp_color_representation_surface_v1 allows the client to set the color
127 representation metadata of a surface.
128
129 By default, a surface does not have any color representation metadata set.
130 The reconstruction of R, G, B signals on such surfaces is compositor
131 implementation defined. The alpha mode is assumed to be
132 premultiplied_electrical when the alpha mode is unset.
133
134 If the wl_surface associated with the wp_color_representation_surface_v1
135 is destroyed, the wp_color_representation_surface_v1 object becomes inert.
136 </description>
137
138 <enum name="error">
139 <description summary="protocol errors"/>
140 <entry name="alpha_mode" value="1"
141 summary="unsupported alpha mode"/>
142 <entry name="coefficients" value="2"
143 summary="unsupported coefficients"/>
144 <entry name="pixel_format" value="3"
145 summary="the pixel format and a set value are incompatible"/>
146 <entry name="inert" value="4"
147 summary="forbidden request on inert object"/>
148 <entry name="chroma_location" value="5"
149 summary="invalid chroma location"/>
150 </enum>
151
152 <request name="destroy" type="destructor">
153 <description summary="destroy the color representation">
154 Destroy the wp_color_representation_surface_v1 object.
155
156 Destroying this object unsets all the color representation metadata from
157 the surface. See the wp_color_representation_surface_v1 interface
158 description for how a compositor handles a surface without color
159 representation metadata. Unsetting is double-buffered state, see
160 wl_surface.commit.
161 </description>
162 </request>
163
164 <enum name="alpha_mode">
165 <description summary="alpha mode">
166 Specifies how the alpha channel affects the color channels.
167 </description>
168 <entry name="premultiplied_electrical" value="0">
169 <description summary="premultiplied alpha in electrical values">
170 Electrical color channel values (after transfer function encoding)
171 are already multiplied with the alpha channel value.
172 </description>
173 </entry>
174 <entry name="premultiplied_optical" value="1">
175 <description summary="premultiplied alpha in optical values">
176 Optical color channel values (before transfer function encoding)
177 are already multiplied with the alpha channel value.
178 </description>
179 </entry>
180 <entry name="straight" value="2">
181 <description summary="straight alpha">
182 Alpha channel has not been pre-multiplied into color channels.
183 </description>
184 </entry>
185 </enum>
186
187 <enum name="coefficients">
188 <description summary="named coefficients">
189 Named matrix coefficients used to encode well-known sets of
190 coefficients. H.273 is the authority, when it comes to the exact values
191 of coefficients and authoritative specifications, where an equivalent
192 code point exists.
193
194 A value of 0 is invalid and will never be present in the list of enums.
195
196 Descriptions do list the specifications for convenience.
197 </description>
198 <entry name="identity" value="1">
199 <description summary="The identity matrix">
200 Coefficients as defined by
201 - IEC 61966-2-1 sRGB
202 - SMPTE ST 428-1 (2019)
203
204 Equivalent to H.273 MatrixCoefficients code point 0.
205 Compatible with pixel formats of the RGB family.
206 </description>
207 </entry>
208 <entry name="bt709" value="2">
209 <description summary="BT.709 matrix coefficients">
210 Coefficients as defined by
211 - Rec. ITU-R BT.709-6
212 - Rec. ITU-R BT.1361-0 conventional colour gamut system (historical)
213 - Rec. ITU-R BT.1361-0 conventional colour gamut system and extended
214 colour gamut system (historical)
215 - IEC 61966-2-4 xvYCC709
216 - SMPTE RP 177 (1993) Annex B
217
218 Equivalent to H.273 MatrixCoefficients code point 1.
219 Compatible with pixel formats of the YCbCr family.
220 </description>
221 </entry>
222 <entry name="fcc" value="3">
223 <description summary="FCC matrix coefficients">
224 Coefficients as defined by
225 - United States Federal Communications Commission (2003) Title 47
226 Code of Federal Regulations 73.682 (a) (20)
227
228 Equivalent to H.273 MatrixCoefficients code point 4.
229 Compatible with pixel formats of the YCbCr family.
230 </description>
231 </entry>
232 <entry name="bt601" value="4">
233 <description summary="BT.601-7 matrix coefficients">
234 Coefficients as defined by
235 - Rec. ITU-R BT.470-6 System B, G (historical)
236 - Rec. ITU-R BT.601-7 625
237 - Rec. ITU-R BT.601-7 525
238 - Rec. ITU-R BT.1358-0 625 (historical)
239 - Rec. ITU-R BT.1358-1 525 or 625 (historical)
240 - Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM
241 - Rec. ITU-R BT.1700-0 NTSC
242 - IEC 61966-2-1 sYCC
243 - IEC 61966-2-4 xvYCC601
244 - SMPTE ST 170 (2004)
245
246 Equivalent to H.273 MatrixCoefficients code point 5, 6.
247 Compatible with pixel formats of the YCbCr family.
248 </description>
249 </entry>
250 <entry name="smpte240" value="5">
251 <description summary="SMPTE ST 240 matrix coefficients">
252 Coefficients as defined by
253 - SMPTE ST 240 (1999)
254
255 Equivalent to H.273 MatrixCoefficients code point 7.
256 Compatible with pixel formats of the YCbCr family.
257 </description>
258 </entry>
259 <entry name="bt2020" value="6">
260 <description summary="BT.2020 and BT.2100 YCbCr matrix coefficients">
261 Coefficients as defined by
262 - Rec. ITU-R BT.2020-2 (non-constant luminance)
263 - Rec. ITU-R BT.2100-2 Y′CbCr
264
265 Equivalent to H.273 MatrixCoefficients code point 9.
266 Compatible with pixel formats of the YCbCr family.
267 </description>
268 </entry>
269 <entry name="bt2020_cl" value="7">
270 <description summary="BT.2020 matrix coefficients for constant luminance">
271 Coefficients as defined by
272 - Rec. ITU-R BT.2020-2 (constant luminance)
273
274 Equivalent to H.273 MatrixCoefficients code point 10.
275 Compatible with pixel formats of the YCbCr family.
276 </description>
277 </entry>
278 <entry name="ictcp" value="8">
279 <description summary="BT.2100 ICtCp matrix coefficients">
280 Coefficients as defined by
281 - Rec. ITU-R BT.2100-2 ICTCP
282
283 Equivalent to H.273 MatrixCoefficients code point 14.
284 Compatible with pixel formats of the YCbCr family.
285 </description>
286 </entry>
287 </enum>
288
289 <enum name="range">
290 <description summary="Color range values">
291 Possible color range values.
292
293 A value of 0 is invalid and will never be present in the list of enums.
294 </description>
295 <entry name="full" value="1" summary="Full color range"/>
296 <entry name="limited" value="2" summary="Limited color range"/>
297 </enum>
298
299 <enum name="chroma_location">
300 <description summary="Chroma sample location for 4:2:0 YCbCr">
301 Chroma sample location as defined by H.273 Chroma420SampleLocType.
302
303 A value of 0 is invalid and will never be present in the list of enums.
304
305 The descriptions list the matching Vulkan VkChromaLocation combinations
306 for convenience.
307 </description>
308 <entry name="type_0" value="1">
309 <description summary="Horizontal offset of 0, vertical offset of 0.5">
310 Corresponding to VkChromaLocations:
311 - xChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN
312 - yChromaOffset: VK_CHROMA_LOCATION_MIDPOINT
313
314 Equivalent to H.273 Chroma420SampleLocType 0.
315 </description>
316 </entry>
317 <entry name="type_1" value="2">
318 <description summary="Horizontal offset of 0.5, vertical offset of 0.5">
319 Corresponding to VkChromaLocations:
320 - xChromaOffset: VK_CHROMA_LOCATION_MIDPOINT
321 - yChromaOffset: VK_CHROMA_LOCATION_MIDPOINT
322
323 Equivalent to H.273 Chroma420SampleLocType 1.
324 </description>
325 </entry>
326 <entry name="type_2" value="3">
327 <description summary="Horizontal offset of 0, vertical offset of 0">
328 Corresponding to VkChromaLocations:
329 - xChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN
330 - yChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN
331
332 Equivalent to H.273 Chroma420SampleLocType 2.
333 </description>
334 </entry>
335 <entry name="type_3" value="4">
336 <description summary="Horizontal offset of 0.5, vertical offset of 0">
337 Corresponding to VkChromaLocations:
338 - xChromaOffset: VK_CHROMA_LOCATION_MIDPOINT
339 - yChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN
340
341 Equivalent to H.273 Chroma420SampleLocType 3.
342 </description>
343 </entry>
344 <entry name="type_4" value="5">
345 <description summary="Horizontal offset of 0, vertical offset of 1">
346 Equivalent to H.273 Chroma420SampleLocType 4.
347 </description>
348 </entry>
349 <entry name="type_5" value="6">
350 <description summary="Horizontal offset of 0.5, vertical offset of 1">
351 Equivalent to H.273 Chroma420SampleLocType 5.
352 </description>
353 </entry>
354 </enum>
355
356 <request name="set_alpha_mode">
357 <description summary="set the surface alpha mode">
358 If this protocol object is inert, the protocol error inert is raised.
359
360 Assuming an alpha channel exists, it is always linear. The alpha mode
361 determines whether and how the color channels include pre-multiplied
362 alpha. Using straight alpha might have performance benefits.
363
364 Only alpha modes advertised by the compositor are allowed to be used as
365 argument for this request. The "alpha_mode" protocol error is raised
366 otherwise.
367
368 Alpha mode is double buffered, see wl_surface.commit.
369 </description>
370 <arg name="alpha_mode" type="uint" enum="alpha_mode"
371 summary="alpha mode"/>
372 </request>
373
374 <request name="set_coefficients_and_range">
375 <description summary="set the matrix coefficients and range">
376 If this protocol object is inert, the protocol error inert is raised.
377
378 Set the matrix coefficients and video range which defines the formula
379 and the related constants used to derive red, green and blue signals.
380 Usually coefficients correspond to MatrixCoefficients code points in
381 H.273.
382
383 Only combinations advertised by the compositor are allowed to be used as
384 argument for this request. The "coefficients" protocol error is raised
385 otherwise.
386
387 A call to wl_surface.commit verifies that the pixel format and the
388 coefficients-range combination in the committed surface contents are
389 compatible, if contents exist. The "pixel_format" protocol error is
390 raised otherwise.
391
392 A pixel format is compatible with the coefficients-range combination if
393 the related equations and conventions as defined in H.273 can produce
394 the color channels (RGB or YCbCr) of the pixel format.
395
396 For the definition of the supported combination, see the
397 wp_color_representation_surface_v1::coefficients and
398 wp_color_representation_surface_v1::range enums.
399
400 The coefficients-range combination is double-buffered, see
401 wl_surface.commit.
402 </description>
403 <arg name="coefficients" type="uint" enum="coefficients"
404 summary="matrix coefficients"/>
405 <arg name="range" type="uint" enum="range"
406 summary="range"/>
407 </request>
408
409 <request name="set_chroma_location">
410 <description summary="set the chroma location">
411 If this protocol object is inert, the protocol error inert is raised.
412
413 Set the chroma location type which defines the position of downsampled
414 chroma samples, corresponding to Chroma420SampleLocType code points in
415 H.273.
416
417 An invalid chroma location enum value raises the "chroma_location"
418 protocol error.
419
420 A call to wl_surface.commit verifies that the pixel format and chroma
421 location type in the committed surface contents are compatible, if
422 contents exist. The "pixel_format" protocol error is raised otherwise.
423
424 For the definition of the supported chroma location types, see the
425 wp_color_representation_surface_v1::chroma_location enum.
426
427 The chroma location type is double-buffered, see wl_surface.commit.
428 </description>
429 <arg name="chroma_location" type="uint" enum="chroma_location"
430 summary="chroma sample location"/>
431 </request>
432 </interface>
433</protocol>