color-management-unstable-v1.xml 26.3 KB
Newer Older
1
2
3
4
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="color_management_unstable_v1">

  <copyright>
Pekka Paalanen's avatar
Pekka Paalanen committed
5
6
7
8
	Copyright 2019 Sebastian Wick
	Copyright 2019 Erwin Burema
	Copyright 2020 AMD
	Copyright 2020 Collabora, Ltd.
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

	Permission is hereby granted, free of charge, to any person obtaining a
	copy of this software and associated documentation files (the "Software"),
	to deal in the Software without restriction, including without limitation
	the rights to use, copy, modify, merge, publish, distribute, sublicense,
	and/or sell copies of the Software, and to permit persons to whom the
	Software is furnished to do so, subject to the following conditions:

	The above copyright notice and this permission notice (including the next
	paragraph) shall be included in all copies or substantial portions of the
	Software.

	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
	THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
	FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
	DEALINGS IN THE SOFTWARE.
  </copyright>

  <description summary="color management protocol">
	This protocol specifies a way for a client to set the color space and
	HDR metadata of a surface and to get information about the color spaces
	and HDR capabilities of outputs.
  </description>

  <interface name="zwp_color_manager_v1" version="1">
Pekka Paalanen's avatar
Pekka Paalanen committed
37
    <description summary="color manager singleton">
38
	A global interface used for getting color management surface and color
Pekka Paalanen's avatar
Pekka Paalanen committed
39
40
	management output objects as well as creating color space objects from
	ICC profiles, parameters, or enumerated names.
41
42
    </description>

43
44
    <enum name="eotf_names">
      <description summary="well-known EOTF names">
Pekka Paalanen's avatar
Pekka Paalanen committed
45
46
47
48
	Names that describe a well-known EOTF.

	A compositor must support all of these based on the protocol interface
	version.
49
      </description>
50
51
52
      <!-- TODO EOTFs -->
      <!-- <entry name="bt1886" value="" summary="BT.1886 transfer function"/> -->
      <!-- <entry name="dci_p3" value="" summary="DCI-P3 transfer function"/> -->
53
      <entry name="unknown" value="0" summary="unknown EOTF"/>
54
55
56
57
      <entry name="linear" value="1" summary="Linear transfer function"/>
      <entry name="srgb" value="2" summary="sRGB transfer function"/>
      <entry name="bt2087" value="3" summary="BT.2087 transfer function"/>
      <entry name="adobergb" value="4" summary="AdobeRGB transfer function"/>
58
59
    </enum>

60
61
    <enum name="chromaticity_names">
      <description summary="well-known chromaticity names">
Pekka Paalanen's avatar
Pekka Paalanen committed
62
63
64
65
	Names that describe well-known chromaticities.

	A compositor must support all of these based on the protocol interface
	version.
66
      </description>
67
      <entry name="unknown" value="0" summary="unknown chromaticity"/>
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
      <entry name="bt601_525_line" value="1"
             summary="ITU-R BT.601 http://www.itu.int/rec/R-REC-BT.601/en"/>
      <entry name="bt601_625_line" value="2"
             summary="ITU-R BT.601 http://www.itu.int/rec/R-REC-BT.601/en"/>
      <entry name="smpte170m" value="3"
             summary="SMPTE 170M-1999 https://www.itu.int/rec/R-REC-BT.1700/en"/>
      <entry name="bt709" value="4"
             summary="ITU-R BT.709 https://www.itu.int/rec/R-REC-BT.709/en"/>
      <entry name="bt2020" value="5"
             summary="ITU-R BT.2020 http://www.itu.int/rec/R-REC-BT.2020/en"/>
      <entry name="srgb" value="6"
             summary="IEC/4WD 61966-2-1: sRGB https://webstore.iec.ch/publication/6169"/>
      <entry name="displayp3" value="7"
             summary="Display P3 https://developer.apple.com/reference/coregraphics/cgcolorspace/1408916-displayp3"/>
      <entry name="adobergb" value="8"
             summary="Adobe RGB https://www.adobe.com/digitalimag/pdfs/AdobeRGB1998.pdf"/>
84
85
    </enum>

86
87
    <enum name="whitepoint_names">
      <description summary="well-known whitepoint names">
Pekka Paalanen's avatar
Pekka Paalanen committed
88
89
90
91
	Names that describe well-known whitepoints.

	A compositor must support all of these based on the protocol interface
	version.
92
      </description>
93
94
      <!-- TODO Whitepoints -->
      <!-- <entry name="d55" value="" summary="D55 whitepoint"/> -->
95
      <entry name="unknown" value="0" summary="unknown whitepoint"/>
96
97
98
      <entry name="dci" value="1" summary="DCI whitepoint"/>
      <entry name="d50" value="2" summary="D50 whitepoint"/>
      <entry name="d65" value="3" summary="D65 whitepoint"/>
99
100
    </enum>

101
102
    <enum name="error">
      <entry name="icc_fd" value="0" summary="given ICC fd has bad properties"/>
Pekka Paalanen's avatar
Pekka Paalanen committed
103
104
      <entry name="bad_enum" value="1" summary="bad value given as a well-known name"/>
      <entry name="bad_param" value="2" summary="bad parameter value"/>
105
106
    </enum>

107
108
109
110
111
    <request name="create_color_space_from_icc">
      <description summary="create a color space object from ICC profiles">
	Create a color space object from an ICC profile. This request returns
	a zwp_color_space_creator_v1 object which either returns an error
	or the successfully created zwp_color_space_v1 object.
112

Pekka Paalanen's avatar
Pekka Paalanen committed
113
	The description of the color space to create is sent in the form of an
114
115
	ICC profile as a file descriptor in the argument icc.

Pekka Paalanen's avatar
Pekka Paalanen committed
116
117
118
119
	The fd must be seekable and the maximum size of the ICC profile is 4 MB.
	Violating these requirements will raise an icc_fd protocol error. A
	compositor must not modify the contents of the file, and the fd may be
	sealed for writes and size changes.
120

Pekka Paalanen's avatar
Pekka Paalanen committed
121
	The file contents must represent a valid ICC profile.
122
123
	The ICC profile version must be 2 or 4, it must be a 3 channel profile
	and the class must be 'input', 'output', 'abstract' or 'display'.
124
125
	Violating these requirements will not result in a protocol error but
	raise the zwp_color_space_creator_v1.error event.
126

127
128
	See the zwp_color_space_v1 and zwp_color_space_creator_v1 interface for
	more details about the created object.
129

Pekka Paalanen's avatar
Pekka Paalanen committed
130
131
	See the specification from International Color Consortium for more
	details about ICC profiles, also known as ISO 15076-1:2010.
132
      </description>
133
      <arg name="id" type="new_id" interface="zwp_color_space_creator_v1"/>
134
      <arg name="icc" type="fd"/>
135
136
137
138
139
140
141
142
    </request>

    <request name="create_color_space_from_names">
      <description summary="create a color space object from well-known names">
	Create a color space object from well-known names. This request returns
	a zwp_color_space_creator_v1 object which either returns an error
	or the successfully created zwp_color_space_v1 object.

Pekka Paalanen's avatar
Pekka Paalanen committed
143
144
145
	EOTF, chromaticity and whitepoint must not be unknown. Otherwise, or
	if a given value is not listed in the enumeration, the protocol error
	bad_enum is raised.
146
147
148
149
150
151
152
153
154
155
156

	See the zwp_color_space_v1 and zwp_color_space_creator_v1 interface for
	more details about the created object.
      </description>
      <arg name="id" type="new_id" interface="zwp_color_space_creator_v1"/>
      <arg name="eotf" type="uint" enum="eotf_names" summary="EOTF"/>
      <arg name="chromaticity" type="uint" enum="chromaticity_names" summary="chromaticity"/>
      <arg name="whitepoint" type="uint" enum="whitepoint_names" summary="whitepoint"/>
    </request>

    <request name="create_color_space_from_params">
Pekka Paalanen's avatar
Pekka Paalanen committed
157
      <description summary="create a color space object from parameters">
158
159
160
161
	Create a color space object from parameters. This request returns
	a zwp_color_space_creator_v1 object which either returns an error
	or the successfully created zwp_color_space_v1 object.

Pekka Paalanen's avatar
Pekka Paalanen committed
162
163
164
165
166
167
168
169
	EOTF must not be unknown. Otherwise, or if a given EOTF is not listed
	in the enumeration, the protocol error bad_enum is raised.

	The white point must be inside the triangle created by the red, green
	and blue primaries. Otherwise the bad_param protocol error is raised.

	All the chromaticity values are multiplied by 10000 to produce the
	integers carried by the protocol.
170
171
172
173
174
175
176
177
178
179
180
181
182
183

	See the zwp_color_space_v1 and zwp_color_space_creator_v1 interface for
	more details about the created object.
      </description>
      <arg name="id" type="new_id" interface="zwp_color_space_creator_v1"/>
      <arg name="eotf" type="uint" enum="eotf_names" summary="EOTF"/>
      <arg name="primary_r_x" type="uint" summary="red primary X * 10000"/>
      <arg name="primary_r_y" type="uint" summary="red primary Y * 10000"/>
      <arg name="primary_g_x" type="uint" summary="green primary X * 10000"/>
      <arg name="primary_g_y" type="uint" summary="green primary Y * 10000"/>
      <arg name="primary_b_x" type="uint" summary="blue primary X * 10000"/>
      <arg name="primary_b_y" type="uint" summary="blue primary Y * 10000"/>
      <arg name="white_point_x" type="uint" summary="white point X * 10000"/>
      <arg name="white_point_y" type="uint" summary="white point Y * 10000"/>
184
185
186
    </request>

    <request name="get_color_management_output">
Pekka Paalanen's avatar
Pekka Paalanen committed
187
      <description summary="create a color management interface for a wl_output">
188
189
	This creates a new zwp_color_management_output_v1 object for the
	given wl_output.
190
191
192
193
194
195
196
197

	See the zwp_color_management_output_v1 interface for more details.
      </description>
      <arg name="id" type="new_id" interface="zwp_color_management_output_v1"/>
      <arg name="output" type="object" interface="wl_output"/>
    </request>

    <request name="get_color_management_surface">
Pekka Paalanen's avatar
Pekka Paalanen committed
198
      <description summary="create a color management interface for a wl_surface">
199
	This creates a new color zwp_color_management_surface_v1 object for the
Pekka Paalanen's avatar
Pekka Paalanen committed
200
201
	given wl_surface.

202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
	See the zwp_color_management_surface_v1 interface for more details.
      </description>
      <arg name="id" type="new_id" interface="zwp_color_management_surface_v1"/>
      <arg name="surface" type="object" interface="wl_surface"/>
    </request>

    <request name="destroy" type="destructor">
      <description summary="destroy the color manager">
	Destroy the zwp_color_manager_v1 object. This does not affect any other
	objects in any way.
      </description>
    </request>
  </interface>

  <interface name="zwp_color_management_output_v1" version="1">
    <description summary="output color properties">
	A zwp_color_management_output_v1 describes the color properties of an
	output.

221
222
223
224
225
226
	When zwp_color_management_output_v1 object is created, it will send
	its initial events followed by a wl_output.done event. When creating
	wl_output and its extension objects, use a final wl_display.sync to
	guarantee that all output events have been received across all
	extensions.

227
228
229
230
231
232
	If the wl_output associated with the zwp_color_management_output_v1 is
	destroyed, the zwp_color_management_output_v1 object becomes inert.
    </description>

    <event name="color_space_changed">
      <description summary="color space changed">
233
	The color_space_changed event is sent whenever the color space of the
234
235
236
237
	output changed, followed by one wl_output.done event common to
	output events across all extensions.

	This is not an initial event.
238
239
240
      </description>
    </event>

241
    <event name="extended_dynamic_range">
Pekka Paalanen's avatar
Pekka Paalanen committed
242
      <description summary="output extended dynamic range">
243
244
245
	This is both an initial event and sent whenever the value changed.
	When the value changed, this event is followed by one wl_output.done
	event common to output events across all extensions.
246
247

	The extended dynamic range value describes how much dynamic range is
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
	available relative to the SDR maximum white. EDR value is proportional
	to luminance, and the luminance of black is used as the zero level.
	A value of 1.0 means that the the display can not display
	anything brighter than SDR maximum white. A value of 3.0 means that the
	SDR maximum white is at one third of the highest luminance the display
	can produce.

	The absolute luminance of the SDR maximum white depends on the monitor
	capabilities, the viewing conditions and the viewer personal
	preferences. A such, it cannot be given a single value in cd/m².
	Compositors using HDR video modes should allow users to control the the
	SDR maximum white level which the output EDR value is calculated from.

	The SDR maximum white is a relative reference luminance that allows
	to tone-map content from different dynamic ranges into a single common
	dynamic range for display.
Pekka Paalanen's avatar
Pekka Paalanen committed
264
265
266

	The EDR value is multiplied by 1000 to produce the integer value
	carried by the protocol.
267
268
269
270
      </description>
      <arg name="value" type="uint" summary="EDR value * 1000"/>
    </event>

271
272
273
    <request name="get_color_space">
      <description summary="get the color space of the output">
	This creates a new zwp_color_space_v1 object for the current color space
Pekka Paalanen's avatar
Pekka Paalanen committed
274
275
276
	of the output. There always is exactly one color space active for an
	output so the client should destroy the color space created by earlier
	invocations of this request. This request is usually sent as a reaction
277
	to the color_space_changed event or when creating a
Pekka Paalanen's avatar
Pekka Paalanen committed
278
279
	zwp_color_management_output_v1 object.

280
281
	The created zwp_color_space_v1 object preserves the color space
	of the output from the time the object was created.
282

283
284
	The resulting color space object allows get_information request.

285
286
287
288
289
290
291
292
293
	See the zwp_color_space_v1 interface for more details.
      </description>
      <arg name="id" type="new_id" interface="zwp_color_space_v1"/>
    </request>

    <!-- TODO: HDR capabilities event -->

    <request name="destroy" type="destructor">
      <description summary="destroy the color management output">
Pekka Paalanen's avatar
Pekka Paalanen committed
294
295
	Destroy the color zwp_color_management_output_v1 object. This does not
	affect any remaining protocol objects.
296
297
298
299
300
      </description>
    </request>
  </interface>

  <interface name="zwp_color_management_surface_v1" version="1">
Pekka Paalanen's avatar
Pekka Paalanen committed
301
    <description summary="color management extension to a surface">
302
303
304
305
306
307
308
309
310
	A zwp_color_management_surface_v1 allows the client to set the color
	space and HDR properties of a surface.

	If the wl_surface associated with the zwp_color_management_surface_v1 is
	destroyed, the zwp_color_management_surface_v1 object becomes inert.
    </description>

    <enum name="render_intent">
      <description summary="render intent">
311
	<!-- FIXME: rendering intent is not just a hint -->
312
313
314
315
316
317
318
319
320
321
322
323
	Rendering intent allow the client to hint at how to perform color space
	transformations.

	See the ICC specification for more details about rendering intent.
      </description>
      <entry name="perceptual" value="0" summary="perceptual"/>
      <entry name="relative" value="1" summary="media-relative colorimetric"/>
      <entry name="saturation" value="2" summary="saturation"/>
      <entry name="absolute" value="3" summary="ICC-absolute colorimetric"/>
      <entry name="relative_bpc" value="4" summary="media-relative colorimetric + black point compensation"/>
    </enum>

324
325
    <enum name="alpha_mode">
      <description summary="alpha mode">
Pekka Paalanen's avatar
Pekka Paalanen committed
326
327
328
	Specifies whether alpha is pre-multiplied into color channels or not.
	If pre-multiplied, the linear alpha value is already multiplied with the
	(non-linear) color channel code values in the color channels.
329
      </description>
Pekka Paalanen's avatar
Pekka Paalanen committed
330
331
      <entry name="straight" value="0" summary="alpha is independent from color channels"/>
      <entry name="premultiplied" value="1" summary="alpha is pre-multiplied into color channels"/>
332
333
    </enum>

334
335
336
337
338
339
340
341
342
343
344
345
346
347
    <request name="set_alpha_mode">
      <description summary="set the surface alpha mode">
	Assuming an alpha channel exists, it is always linear. The alpha mode
	determines whether the color channels include alpha pre-multiplied or
	not. Using straight alpha might have performance benefits.

	Alpha mode is double buffered, and will be applied at the time
	wl_surface.commit of the corresponding wl_surface is called.

	By default, a surface is assumed to have pre-multiplied alpha.
      </description>
      <arg name="alpha_mode" type="uint" enum="alpha_mode" summary="alpha mode"/>
    </request>

348
    <request name="set_extended_dynamic_range">
Pekka Paalanen's avatar
Pekka Paalanen committed
349
350
      <description summary="set the content extended dynamic range">
	Set the extended dynamic range (EDR) value for the underlying surface.
351
352
353
	The EDR value is double buffered, and will be applied at the time
	wl_surface.commit of the corresponding wl_surface is called.

354
355
356
357
358
	The EDR value describes how much dynamic range is encoded relative to
	the SDR maximum white. EDR value is proportional to luminance, using
	the luminance of black as the zero level. A value of 1.0 means that the
	SDR maximum white is the highest possible luminance of the surface. A
	value of 3.0 means that the SDR maximum white is one third of the
Pekka Paalanen's avatar
Pekka Paalanen committed
359
	highest possible luminance of the surface.
360
361
362

	The color space attached to the surface can make the code values in the
	buffer non-linear in regards to the luminance. The code value to produce
Pekka Paalanen's avatar
Pekka Paalanen committed
363
	a third of the luminance of the biggest code value therefore might not
364
365
	be one third of the biggest code value.

366
367
368
369
370
371
	For the definition of the SDR maximum white on an output, see
	zwp_color_management_output_v1.extended_dynamic_range. Content
	producers are free to choose their SDR maximum white level. How it
	shall be displayed depends on the monitor capabilities and the output
	EDR value.

372
	By default the EDR value is 1.0. The compositor will tone map the image
373
374
375
376
377
378
379
	to match the EDR of each output the surface is shown on. The aim for
	the EDR-EDR mapping is to produce a relative luminance mapping that
	looks equally good regardless of the viewing conditions and the monitor
	capabilities, assuming the output EDR value was tuned to the output
	capabilities and the viewing environment. There might be performance
	and image quality benefits from providing content readily tone mapped to
	the EDR value of the output the surface is shown on.
Pekka Paalanen's avatar
Pekka Paalanen committed
380
381
382

	The EDR value is multiplied by 1000 to produce the integer value
	carried by the protocol.
383
384
385
386
      </description>
     <arg name="value" type="uint" summary="EDR value * 1000"/>
    </request>

387
    <request name="set_color_space">
Pekka Paalanen's avatar
Pekka Paalanen committed
388
      <description summary="set the surface color space">
389
390
	Set the color space of the underlying surface. The color space and
	render intent are double buffered, and will be applied
391
	at the time wl_surface.commit of the corresponding wl_surface is called.
392

393
	<!-- FIXME: same problem as in the render_intent enum -->
394
395
396
	The render intent gives the compositor a hint what to optimize for in
	color space transformations.

397
398
	By default, a surface is assumed to have the sRGB color space and an
	arbitrary render intent.
399
400
401
402

	If the color space of the surface matches the color space of an output
	it is shown on the performance and color accuracy might improve. To find
	those color spaces the client can listen to the preferred_color_space or
Pekka Paalanen's avatar
Pekka Paalanen committed
403
404
405
	the wl_surface.enter/leave events. This improvement may require using
	the color space object created by
	zwp_color_management_output_v1.get_color_space.
406
      </description>
407
      <arg name="color_space" type="object" interface="zwp_color_space_v1"/>
408
      <arg name="render_intent" type="uint" enum="render_intent" summary="render intent"/>
409
410
    </request>

411
412
413
414
415
416
417
418
    <request name="set_default_color_space">
      <description summary="set the surface color space to default">
	This request sets the surface color space to the defaults, see
	set_color_space. The setting will be applied at the time
	wl_surface.commit of the corresponding wl_surface is called.
      </description>
    </request>

419
420
421
    <!-- TODO: HDR metadata request -->

    <event name="preferred_color_space">
Pekka Paalanen's avatar
Pekka Paalanen committed
422
423
424
425
426
      <description summary="output for color optimization">
	The preferred_color_space event is sent when the compositor determines
	or switches the output that implies the preferred color space. The
	preferred color space is the one which likely has the most performance
	and quality benefits if used by a client for its surface contents.
427
428
429
430

	The event does not carry a zwp_color_space_v1 but a wl_output object.
	The concrete zwp_color_space_v1 can be created by calling
	zwp_color_management_output_v1.get_color_space on the output and
Pekka Paalanen's avatar
Pekka Paalanen committed
431
432
	listening to zwp_color_management_output_v1.color_space_changed
	events.
433

434
435
436
437
438
	As clients may bind to the same global wl_output multiple
	times, this event is sent for each bound instance that matches
	the preferred color space output. If a client has not bound to
	the right wl_output global at all, this event is not sent.

439
440
441
442
443
444
445
446
	This is only a hint and clients can set any valid color space with
	set_color_space but there might be performance and color accuracy
	improvements by providing the surface in the preferred color space.
      </description>
      <arg name="output" type="object" interface="wl_output"/>
    </event>

    <request name="destroy" type="destructor">
Pekka Paalanen's avatar
Pekka Paalanen committed
447
      <description summary="destroy the color management interface for a surface">
448
449
	Destroy the zwp_color_management_surface_v1 object.

450
451
	When the last zwp_color_management_surface_v1 object for a wl_surface
	is destroyed, the destruction will pend unsetting the wl_surface's
452
453
	color space, render intent and alpha mode similar to set_color_space
	will pend a set.
454
455
456
457
      </description>
    </request>
  </interface>

458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
  <interface name="zwp_color_space_creator_v1" version="1">
    <description summary="color space creator">
	A zwp_color_space_creator_v1 object returns a created color space
	or the error which occured during creation.

	Once a zwp_color_space_creator_v1 object has delivered a 'created'
	or 'error' event it is automatically destroyed.
    </description>

    <enum name="creation_error" bitfield="true">
      <description summary="color space creation error">
	Bitmask of errors which occured while trying to create a color space
      </description>
      <entry name="malformed_icc" value="0x1" summary="malformed ICC profile"/>
      <entry name="bad_icc" value="0x2" summary="ICC profile does not meet requirements"/>
Pekka Paalanen's avatar
Pekka Paalanen committed
473
474
      <entry name="bad_primaries" value="0x4" summary="bad primaries"/>
      <entry name="bad_whitepoint" value="0x8" summary="bad whitepoint"/>
475
476
477
478
    </enum>

    <event name="created">
      <description summary="color space object created">
Pekka Paalanen's avatar
Pekka Paalanen committed
479
	Delivers the successfully created color space.
480
481

	The resulting color space object does not allow get_information request.
482
483
484
485
486
487
      </description>
      <arg name="id" type="new_id" interface="zwp_color_space_v1"/>
    </event>

    <event name="error">
      <description summary="color space creation failed">
Pekka Paalanen's avatar
Pekka Paalanen committed
488
	This event is sent if the color space creation failed.
489
490
491
492
493
      </description>
      <arg name="error" type="uint" enum="creation_error" summary="error bitmask"/>
    </event>
  </interface>

494
495
  <interface name="zwp_color_space_v1" version="1">
    <description summary="color space">
Pekka Paalanen's avatar
Pekka Paalanen committed
496
	Refers to a color space which can be attached to a surface
497
498
499
500
501
502
503
	(zwp_color_management_surface_v1.set_color_space). It may provide
	information like the ICC profile and the well-known names to allow
	clients to know the color space and do color transformations of their
	own.

	Once created and regardless of how it was created, a zwp_color_space_v1
	object always refers to one fixed color space.
504

505
506
507
	The client can create a zwp_color_space_v1 object with
	zwp_color_manager_v1 requests or from an output by calling
	zwp_color_management_output_v1.get_color_space.
508
509
510
511
512
513
514
515
516
517
518

	Other extensions may define more zwp_color_space_v1 factory interfaces.
	Those interfaces must explicitly specify the interface version for the
	object created, otherwise versioning zwp_color_space_v1 correctly
	becomes impossible. Using a 'new_id' argument without 'interface'
	attribute defined in XML forces code generators to add two explicit
	arguments: interface and version. Version is the explicit version
	number needed, and interface should be required to be
	"zwp_color_space_v1". The compositor supported zwp_color_space_v1
	versions are defined by the advertised zwp_color_manager_v1 in
	wl_registry.
519
520
    </description>

521
522
523
524
    <enum name="error">
      <entry name="no_information" value="0" summary="get_information disallowed"/>
    </enum>

525
526
    <request name="get_information">
      <description summary="get information about the color space">
527
528
529
530
	As a reply to this request, the compositor will send all available
	information events describing this color space object and finally
	the 'done' event. Other extensions may define more events to be sent
	before 'done'.
531
532
533
534
535

	This request is allowed only on zwp_color_space_v1 objects where the
	message that created the object specifies that get_information is
	allowed. Otherwise protocol error no_information is raised.

536
537
538
	Every get_information request on the same object will always return the
	exact same data.

539
540
	See zwp_color_management_output_v1.get_color_space and
	zwp_color_space_creator_v1.created.
541
542
543
      </description>
    </request>

544
545
546
    <event name="icc_file">
      <description summary="ICC profile describing the color space">
	This event may be sent only as a response to
547
548
549
550
	zwp_color_space_v1.get_information.

	The icc argument provides a file descriptor to the client which can be
	memory-mapped to provide the ICC profile describing the color space.
Pekka Paalanen's avatar
Pekka Paalanen committed
551
	The fd must be mapped with MAP_PRIVATE and read-only by the client.
552

553
554
555
	Compositors should send this event always when information is requested.
	ICC profiles provide the common foundation which all color managed
	clients may rely on.
556
557
      </description>
      <arg name="icc" type="fd" summary="ICC profile file descriptor"/>
558
      <arg name="icc_size" type="uint" summary="ICC profile size, in bytes"/>
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
    </event>

    <event name="names">
      <description summary="well-known names of a color space">
	This event may be sent only as a response to
	zwp_color_space_v1.get_information.

	EOTF, chromaticity and whitepoint contain well-known names of those
	properties if available and unknown otherwise.

	Compositors should not assume that all clients can understand these
	names. The names are provided for client convenience. If a client
	understands the name triplet, it may ignore other information about
	the color space, the ICC profile for example.
      </description>
574
575
576
      <arg name="eotf" type="uint" enum="zwp_color_manager_v1.eotf_names" summary="EOTF"/>
      <arg name="chromaticity" type="uint" enum="zwp_color_manager_v1.chromaticity_names" summary="chromaticity"/>
      <arg name="whitepoint" type="uint" enum="zwp_color_manager_v1.whitepoint_names" summary="whitepoint"/>
577
578
    </event>

579
580
581
582
583
584
585
586
587
588
    <event name="done">
      <description summary="end of color space information">
	This event may be sent only as a response to
	zwp_color_space_v1.get_information.

	This signifies that all color space information events have been
	delivered for the object.
      </description>
    </event>

589
590
591
    <request name="destroy" type="destructor">
      <description summary="destroy the color space">
	Destroy the zwp_color_space_v1 object.
592
593
594

	Destroying the zwp_color_space_v1 which is active on a surface or an
	output does not change the color space of those objects.
595
596
597
598
599
      </description>
    </request>
  </interface>

</protocol>