Color management

销毁 wp_color_manager_v1 对象。这不会以任何方式影响任何其他对象。

为给定的 wl_output 创建一个新的 wp_color_management_output_v1 对象。

详见 wp_color_management_output_v1 接口。

如果给定的 wl_surface 已存在 wp_color_management_surface_v1 对象，则引发协议错误 surface_exists。

为给定的 wl_surface 创建一个新的 wp_color_management_surface_v1 对象。

详见 wp_color_management_surface_v1 接口。

为给定的 wl_surface 创建一个新的 wp_color_management_surface_feedback_v1 对象。

详见 wp_color_management_surface_feedback_v1 接口。

创建一个基于 ICC 的图像描述创建器对象，所有属性初始未设置。客户端可以使用该对象的接口定义图像描述所需的所有属性，最终创建 wp_image_description_v1 对象。

当合成器通告 wp_color_manager_v1.feature.icc_v2_v4 时可以使用此请求。否则此请求将引发协议错误 unsupported_feature。

创建一个参数化图像描述创建器对象，所有属性初始未设置。客户端可以使用该对象的接口定义图像描述所需的所有属性，最终创建 wp_image_description_v1 对象。

当合成器通告 wp_color_manager_v1.feature.parametric 时可以使用此请求。否则此请求将引发协议错误 unsupported_feature。

此请求为所谓的 Windows-scRGB 刺激编码创建一个预定义的图像描述。这源自 Windows 10 对其自身 scRGB 色彩空间定义的处理，用于以 BT.2100/PQ 信令模式驱动的 HDR 屏幕。

Windows-scRGB 使用 sRGB (BT.709) 色彩原色和白点。传递特性为扩展线性。

标称色彩通道值范围是扩展的，意味着它包含负值和大于 1.0 的值。负值用于突破 sRGB 色域边界。要使用扩展范围，客户端需要使用能够表示这些值的像素格式，例如每通道 16 位浮点数。

标称色彩值 R=G=B=0.0 对应 BT.2100/PQ 系统 0 cd/m²，R=G=B=1.0 对应 BT.2100/PQ 系统 80 cd/m²。最大值为 R=G=B=125.0 对应 10k cd/m²。

Windows 10 通过将 Windows-scRGB 转换为 BT.2100/PQ 进行显示，保持 CIE 1931 色度并按上述方式映射亮度。信号不进行任何针对观看条件的调整。

Windows-scRGB 的参考白电平未知。如果 compositor 处理必须假定参考白电平，应使用 R=G=B=2.5375 对应 ITU-R BT.2408-7 报告中的 203 cd/m²。

Windows-scRGB 的目标色彩体积未知。色域可能是 sRGB 和 BT.2100 之间的任何范围。

注意：EGL_EXT_gl_colorspace_scrgb_linear 定义与 Windows-scRGB 不同，它使用 R=G=B=1.0 作为参考白电平，而 Windows-scRGB 的参考白电平未知或可变。然而，Windows 可能同时将 EGL_EXT_gl_colorspace_scrgb_linear 和 Vulkan VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT 实现为 Windows-scRGB。

当 compositor 通告 wp_color_manager_v1.feature.windows_scrgb 时可以使用此请求。否则此请求将引发协议错误 unsupported_feature。

生成的图像描述对象不允许 get_information 请求。应发送 wp_image_description_v1.ready 事件。

此请求检索引用背后的图像描述。

get_information 请求仅在创建引用的请求允许时才能使用。

当此对象创建时，应立即为合成器支持的每个渲染意图发送一次此事件。

合成器不得通告在绑定接口版本中已弃用的意图。

当此对象创建时，应立即为枚举中列出的每个合成器支持的功能发送一次此事件。

合成器不得通告在绑定接口版本中已弃用的功能。

当此对象创建时，应立即为合成器在参数化图像描述创建器中支持的每个命名传递函数发送一次此事件。

合成器不得通告在绑定接口版本中已弃用的传递函数。

当此对象创建时，应立即为合成器在参数化图像描述创建器中支持的每组命名原色发送一次此事件。

合成器不得通告在绑定接口版本中已弃用的名称。

当所有支持的渲染意图、功能、传递函数和命名原色都已发送后，发送此事件。

有关渲染意图的更多详情，请参阅 International Color Consortium 的 ICC.1:2022 规范。

ICC 定义的渲染意图原则适用于所有类型的图像描述，不仅限于带有 ICC 文件配置文件的图像描述。

合成器必须支持感知渲染意图。其他渲染意图是可选的。

用于编码已知原色集的命名原色。

值 0 无效，永远不会出现在枚举列表中。

用于表示已知显示设备传递特性的命名传递函数。

值 0 无效，永远不会出现在枚举列表中。

公式见 appendix.md。

销毁 wp_color_management_output_v1 对象。这不会影响任何剩余的协议对象。

为输出的当前图像描述创建一个新的 wp_image_description_v1 对象。输出始终恰好有一个活动的图像描述，因此客户端应销毁此请求先前调用创建的图像描述。此请求通常作为对 image_description_changed 事件的响应或在创建 wp_color_management_output_v1 对象时发送。

输出的图像描述表示输出期望的色彩编码。如果内容更新与其显示输出的图像描述匹配，可能会有性能和功耗优势，以及更好的色彩再现。如果内容更新在与其图像描述不匹配的其他输出上显示，则这些输出上的色彩再现可能会明显更差。

创建的 wp_image_description_v1 对象保存对象创建时输出的图像描述。

生成的图像描述对象允许 get_information 请求。

如果此协议对象是惰性的，生成的图像描述对象应立即发送 wp_image_description_v1.failed 事件，原因为 no_output。

如果接口版本不足以支持输出的图像描述，即客户端不支持传递关键信息所需的所有事件，生成的图像描述对象应立即发送 wp_image_description_v1.failed 事件，原因为 low_version。

否则对象应立即发送 ready 事件。

每当输出的图像描述更改时发送此事件，随后是所有扩展中共用的 wl_output.done 事件。

如果客户端想使用更新后的图像描述，需要再次调用 get_image_description，因为图像描述对象是不可变的。

销毁 wp_color_management_surface_v1 对象，执行与 unset_image_description 相同的操作。

如果此协议对象是惰性的，则引发协议错误 inert。

设置底层 surface 的图像描述。图像描述和渲染意图是双缓冲状态，参见 wl_surface.commit。

客户端有责任理解其在 surface 上设置的图像描述，并提供与该图像描述匹配的内容。合成器可能会转换图像以匹配其自身或其他图像描述。

未就绪的图像描述（参见 wp_image_description_v1）在此请求中是禁止的，在这种情况下将引发协议错误 image_description。

所有已就绪的图像描述（参见 wp_image_description_v1）都是允许的，合成器必须始终接受。

当在 surface 上设置图像描述时，它建立了 surface 像素值与 surface 色度之间的明确链接。对于某些像素值，此链接可能是未定义的，详见图像描述创建器接口。非有限浮点值（NaN、Inf）的色度始终是未定义的。

渲染意图提供了客户端对 surface 色度应如何映射到每个输出的偏好。render_intent 值必须是合成器通过 wp_color_manager_v1.render_intent 事件通告的值之一，否则将引发协议错误 render_intent。

默认情况下，surface 没有关联的图像描述或渲染意图。此类 surface 上的色彩处理由合成器实现定义。合成器应将此类 surface 视为 sRGB 处理，但如果有特定要求也可以不同处理。

设置图像描述具有复制语义；此请求之后，可以立即销毁图像描述而不影响 surface 的待处理状态。

如果此协议对象是惰性的，则引发协议错误 inert。

此请求从 surface 移除任何图像描述。有关合成器如何处理没有图像描述的 surface，参见 set_image_description。这是双缓冲状态，参见 wl_surface.commit。

销毁 wp_color_management_surface_feedback_v1 对象。

如果此协议对象是惰性的，则引发协议错误 inert。

首选图像描述表示合成器当前对此 wl_surface 的首选色彩编码。如果内容更新的图像描述与首选图像描述匹配，可能会有性能和功耗优势，以及更好的色彩再现。

为 wl_surface 的当前首选图像描述创建一个新的 wp_image_description_v1 对象。客户端应停止使用并销毁此请求先前为关联 wl_surface 创建的图像描述。此请求通常作为对 preferred_changed 事件的响应或在创建 wp_color_management_surface_feedback_v1 对象时发送（如果客户端能够适应图像描述）。

创建的 wp_image_description_v1 对象保存对象创建时 wl_surface 的首选图像描述。

生成的图像描述对象允许 get_information 请求。

如果图像是参数化的，客户端应仅在图像描述与客户端内容完全匹配时才将其设置到 wl_surface 上。特别是如果其他一切都匹配，但目标色域大于客户端所需，客户端应使用其精确参数创建自己的参数化图像描述。

如果接口版本不足以支持首选图像描述，即客户端不支持传递关键信息所需的所有事件，生成的图像描述对象应立即发送 wp_image_description_v1.failed 事件，原因为 low_version，否则对象应立即发送 ready 事件。

与 get_preferred 的描述相同，但返回的图像描述保证是参数化的。这适用于只能处理参数化图像描述的客户端。

如果合成器不支持参数化图像描述，将发出 unsupported_feature 错误。

从接口版本 2 开始，发送 'preferred_changed2' 而非此事件。定义参见 'preferred_changed2' 事件。

首选图像描述是客户端用于其 wl_surface 内容时可能为合成器带来最大性能和/或质量优势的图像描述。每当合成器更改 wl_surface 的首选图像描述时发送此事件。

此事件发送新首选状态的标识作为参数，因此已知图像描述的客户端可以重用它。否则，如果客户端想知道首选图像描述是什么，应使用 get_preferred 请求。

首选图像描述不会自动用于任何用途。它只是一个提示，客户端可以通过 set_image_description 设置任何有效的图像描述，但使用首选图像描述提供 wl_surface 内容可能会提高性能和色彩准确性。因此，有能力的客户端应按照首选图像描述进行渲染。

基于先前在此对象上设置的 ICC 信息创建图像描述对象。合成器必须在某个未定义但有限的时间内解析 ICC 数据。

验证参数集的完整性。如果集不完整，将引发协议错误 incomplete_set。完整集的定义参见此接口的描述。

如果合成器不支持该信息的特定组合，生成的图像描述对象应立即发送 wp_image_description_v1.failed 事件，原因为 'unsupported'。如果从该信息创建了有效的图像描述，最终将改为发送 wp_image_description_v1.ready 事件。

此请求销毁 wp_image_description_creator_icc_v1 对象。

生成的图像描述对象不允许 get_information 请求。

设置用作图像描述基础的 ICC 配置文件。

数据应在给定偏移量处通过给定的 fd 找到，具有给定的长度。fd 必须可寻址和可读。违反这些要求将引发协议错误 bad_fd。

如果由于与客户端无关的错误导致读取数据失败，合成器应在创建的 wp_image_description_v1 上发送 wp_image_description_v1.failed 事件，原因为 'operating_system'。

ICC 配置文件的最大大小为 32 MB。如果长度大于该值或为零，将引发协议错误 bad_size。如果 offset + length 超过文件大小，将引发协议错误 out_of_file。

合成器可以在此请求之后的任何时间读取文件，直到以下先发生的情况：

• 如果发出了 create 请求，wp_image_description_v1 对象发送 failed 或 ready 事件；或
• 如果未发出 create 请求，此 wp_image_description_creator_icc_v1 对象被销毁。

合成器不得修改文件内容，fd 可以被密封以防止写入和大小更改。客户端必须尽最大努力确保数据在合成器读取期间不会更改。

数据必须表示有效的 ICC 配置文件。ICC 配置文件版本必须为 2 或 4，必须是 3 通道配置文件，类别必须为 Display 或 ColorSpace。违反这些要求不会导致协议错误，但最终会在创建的 wp_image_description_v1 上发送 wp_image_description_v1.failed 事件，原因为 'unsupported'。

有关 ICC 配置文件的更多详情，请参阅 International Color Consortium 规范 ICC.1:2022。

如果此对象已设置 ICC 文件，将引发协议错误 already_set。

基于先前在此对象上设置的参数创建图像描述对象。

验证参数集的完整性。如果集不完整，将引发协议错误 incomplete_set。完整集的定义参见此接口的描述。

当 max_cll 和 max_fall 都设置时，max_fall 必须小于或等于 max_cll，否则将引发协议错误 invalid_luminance。

在版本 1 中，以下条件也会导致协议错误 invalid_luminance。版本 2 及更高版本没有此要求。

• 当设置 max_cll 时，它必须大于母版亮度范围的 min L 且小于或等于 max L。
• 当设置 max_fall 时，它必须大于母版亮度范围的 min L 且小于或等于 max L。

如果合成器不支持参数集的特定组合，生成的图像描述对象应立即发送 wp_image_description_v1.failed 事件，原因为 'unsupported'。如果从参数集创建了有效的图像描述，最终将改为发送 wp_image_description_v1.ready 事件。

此请求销毁 wp_image_description_creator_params_v1 对象。

生成的图像描述对象不允许 get_information 请求。

使用显式枚举的命名函数设置传递特性。

当生成的图像描述附加到图像时，内容应根据传递特性的行业标准实践进行解码。

仅允许使用通过 wp_color_manager_v1 事件 supported_tf_named 通告的名称。其他值将引发协议错误 invalid_tf。

如果此对象已设置传递特性，将引发协议错误 already_set。

将色彩分量传递特性设置为具有给定指数的幂曲线。负值通过将曲线的正半部分关于原点镜像处理。曲线的有效域和范围是所有有限实数。此曲线表示从电信号到光信号的色彩通道值转换。

曲线指数应乘以 10000 以获得参数 eexp 值，精度为 4 位小数。

曲线指数必须至少为 1.0 且最多为 10.0。否则将引发协议错误 invalid_tf。

如果此对象已设置传递特性，将引发协议错误 already_set。

当合成器通告 wp_color_manager_v1.feature.set_tf_power 时可以使用此请求。否则此请求将引发协议错误 unsupported_feature。

使用显式命名集设置原色和白点。这描述了作为色彩值编码基础的主色域。

仅允许使用通过 wp_color_manager_v1 事件 supported_primaries_named 通告的名称。其他值将引发协议错误 invalid_primaries_named。

如果此对象已设置原色，将引发协议错误 already_set。

使用 CIE 1931 xy 色度坐标设置原色和白点。这描述了作为色彩值编码基础的主色域。

每个坐标值乘以 100 万以获得参数值，精度为 6 位小数。

如果此对象已设置原色，将引发协议错误 already_set。

当合成器通告 wp_color_manager_v1.feature.set_primaries 时可以使用此请求。否则此请求将引发协议错误 unsupported_feature。

设置主色域亮度范围和参考白亮度电平。这些值包括最小显示发射，但不包括外部眩光。最小显示发射被假定具有主色域白点的色度。

来自 https://www.color.org/chardata/rgb/srgb.xalter 的默认亮度为：

• 主色域最小值：0.2 cd/m²
• 主色域最大值：80 cd/m²
• 参考白：80 cd/m²

设置命名传递特性可能隐含其他默认亮度。

使用此请求时，默认亮度将被覆盖。使用 transfer_function.st2084_pq 时，给定的 'max_lum' 值被忽略，'max_lum' 取为 'min_lum' + 10000 cd/m²。

'min_lum' 和 'max_lum' 指定目标显示器再现的主色域最小和最大亮度。

'reference_lum' 指定目标显示器再现的参考白亮度，并反映目标观看环境。

Compositor 应确保所有内容都是锚定的，即一个图像描述上的 'reference_lum' 输入信号电平和另一个图像描述上的 'reference_lum' 输入信号电平应产生相同的输出电平，即使两个图像表示上的 'reference_lum' 可以不同。

'reference_lum' 可以高于 'max_lum'。在这种情况下，要在图像内容中达到参考白输出电平需要 'extended_target_volume' 功能支持。

如果 'max_lum' 或 'reference_lum' 小于或等于 'min_lum'，将引发协议错误 invalid_luminance。

最小亮度乘以 10000 以获得参数 'min_lum' 值，精度为 4 位小数。最大亮度和参考白亮度值不进行缩放。

如果主色域亮度范围和参考白亮度电平已在此对象上设置，将引发协议错误 already_set。

当 compositor 通告 wp_color_manager_v1.feature.set_luminances 时可以使用此请求。否则此请求将引发协议错误 unsupported_feature。

使用 CIE 1931 xy 色度坐标提供母版显示的原色和白点。这与 SMPTE ST 2086 的 HDR 静态元数据定义兼容。

母版显示原色和母版显示亮度定义了目标色域。

如果未明确设置母版显示原色，目标色域被假定具有与主色域相同的原色。

目标色域由给定母版显示原色和白点定义的色彩空间中 0.0 到 1.0（含）之间的所有三刺激值定义。容器色彩空间和母版显示色彩空间之间的色度是相同的，即使白点不同也不应用色度适应。

目标色域可以超出主色域，以允许使用现有色彩空间定义（例如 scRGB）获得更大的色域。它也可以小于主色域，以最小化大色彩空间（HDR 元数据）的色域和色调映射距离。

要使用整个目标色域，需要选择合适的像素格式（例如浮点数以超出主色域，或像 xvYCC 那样滥用有限量化范围）。

每个坐标值乘以 100 万以获得参数值，精度为 6 位小数。

如果此对象已设置母版显示原色，将引发协议错误 already_set。

当合成器通告 wp_color_manager_v1.feature.set_mastering_display_primaries 时可以使用此请求。否则此请求将引发协议错误 unsupported_feature。该通告仅暗示支持完全包含在主色域内的目标色域。

如果合成器还支持超出主色域的目标色域，必须通告 wp_color_manager_v1.feature.extended_target_volume。如果客户端使用超出主色域的目标色域而合成器不支持，结果是实现定义的。建议合成器检测此情况并优雅地使图像描述失败，但也可能导致色彩伪影。

设置内容母版处理期间使用的亮度范围，作为最小和最大绝对亮度 L。这些值包括最小显示发射和环境眩光亮度，假定为光学相加并具有主色域白点的色度。这应与 SMPTE ST 2086 的 HDR 静态元数据定义兼容。

母版显示原色和母版显示亮度定义了目标色域。

如果未明确设置母版亮度，目标色域被假定具有与主色域相同的最小和最大亮度。

如果 max L 小于或等于 min L，将引发协议错误 invalid_luminance。

Min L 值乘以 10000 以获得参数 min_lum 值，精度为 4 位小数。Max L 值不缩放用于 max_lum。

当合成器通告 wp_color_manager_v1.feature.set_mastering_display_primaries 时可以使用此请求。否则此请求将引发协议错误 unsupported_feature。该通告仅暗示支持完全包含在主色域内的目标色域。

如果合成器还支持超出主色域的目标色域，必须通告 wp_color_manager_v1.feature.extended_target_volume。如果客户端使用超出主色域的目标色域而合成器不支持，结果是实现定义的。建议合成器检测此情况并优雅地使图像描述失败，但也可能导致色彩伪影。

设置 CTA-861-H 定义的最大内容亮度电平 (max_cll)。

max_cll 默认未定义。

设置 CTA-861-H 定义的最大帧平均亮度电平 (max_fall)。

max_fall 默认未定义。

销毁此对象。销毁未就绪的对象是安全的。

销毁 wp_image_description_v1 对象没有副作用，即使 wp_color_management_surface_v1.set_image_description 尚未跟随 wl_surface.commit。

创建一个 wp_image_description_info_v1 对象，该对象传递构成图像描述的信息。

并非所有图像描述协议对象都允许 get_information 请求。是否允许由创建对象的请求定义。如果不允许 get_information，将引发协议错误 no_information。

如果创建 wp_image_description_v1 对象因未定义为协议错误的原因而失败，则发送此事件。

创建图像描述对象的请求定义了是否以及何时可能发生这种情况。只有此类创建请求可以触发此事件。图像描述成功形成后不能触发此事件。

一旦发送此事件，wp_image_description_v1 对象将永远不会就绪，只能被销毁。

从接口版本 2 开始，发送 'ready2' 事件而非此事件。

此事件的定义参见 'ready2' 事件。与此事件的区别如下。

id 号仅在协议对象存在期间有效。如果引用同一图像描述记录的所有协议对象被销毁，id 号可能被回收用于不同的图像描述记录。

一旦发送此事件，wp_image_description_v1 对象被视为 "就绪"。就绪的对象可用于发送请求，也可通过其他接口使用。

每个就绪的 wp_image_description_v1 协议对象引用合成器中的底层图像描述记录。多个协议对象可能最终引用同一记录。客户端可以通过比较 id 号来识别这些 "副本"：如果两个协议对象的数字相同，则协议对象引用同一图像描述记录。两个不同的图像描述记录不能同时具有相同的 id 号。id 号在图像描述记录的生命周期内不会更改。

图像描述 id 号不是协议对象 id。零保留为无效 id 号。客户端不应在协议中通过 id 号引用图像描述。id 号可能无法在 Wayland 连接之间移植。合成器不得发送无效的 id 号。

合成器不得回收图像描述 id 号。

此标识允许客户端对图像描述记录进行去重，如果已有图像描述信息则避免 get_information 请求。

信号信息事件结束并销毁对象。

icc 参数向客户端提供一个文件描述符，可以通过内存映射来提供与图像描述匹配的 ICC 配置文件。fd 是只读的，如果映射则客户端必须使用 MAP_PRIVATE 映射。

ICC 配置文件版本和其他详细信息由合成器决定。没有规定客户端可以请求特定类型的配置文件。

使用 CIE 1931 xy 色度坐标传递主色域原色和白点。

每个坐标值乘以 100 万以获得参数值，精度为 6 位小数。

使用显式枚举的命名集传递主色域原色和白点。

此图像描述的色彩分量传递特性是纯幂曲线。此事件提供幂函数的指数。此曲线表示从电信号到光信号的像素或色彩值转换。

曲线指数已乘以 10000 以获得参数 eexp 值，精度为 4 位小数。

使用显式枚举的命名函数传递传递特性。

传递主色域亮度范围和参考白亮度电平。这些值包括最小显示发射和环境眩光亮度，假定为光学相加并具有主色域白点的色度。

最小亮度乘以 10000 以获得参数 'min_lum' 值，精度为 4 位小数。最大亮度和参考白亮度值不缩放。

使用 CIE 1931 xy 色度坐标提供目标色域的原色和白点。这与 SMPTE ST 2086 用于母版显示的 HDR 静态元数据定义兼容。

主色域是关于色彩如何编码的，而目标色域是实际可显示的色域。

每个坐标值乘以 100 万以获得参数值，精度为 6 位小数。

提供图像描述所针对的亮度范围，作为最小和最大绝对亮度 L。这些值包括最小显示发射和环境眩光亮度，假定为光学相加并具有主色域白点的色度。这应与 SMPTE ST 2086 的 HDR 静态元数据定义兼容。

此亮度范围仅为理论值，可能与实际显示发出的光亮度不对应。

Min L 值乘以 10000 以获得参数 min_lum 值，精度为 4 位小数。Max L 值不缩放用于 max_lum。

提供图像描述的目标 max_cll。max_cll 由 CTA-861-H 定义。

此亮度仅为理论值，可能与实际显示发出的光亮度不对应。

提供图像描述的目标 max_fall。max_fall 由 CTA-861-H 定义。

此亮度仅为理论值，可能与实际显示发出的光亮度不对应。

销毁此对象。这对引用的图像描述没有影响。