Color representation

颜色表示（color representation）协议扩展

此协议扩展提供了定义 alpha 模式、颜色模型、子采样和量化范围所需的元数据，用于在解释 buffer 内容时使用。其主要用例是定义 YCbCr 系列像素格式如何转换为 RGB。

请注意，此协议未定义结果 RGB 通道/三刺激值的色度学 (colorimetry)。在没有其他扩展辅助的情况下，最终的色度学是由实现定义的。

如果未使用此扩展，所使用的颜色表示由 compositor 的实现定义。

ITU-T H.273 建议书 "Coding-independent code points for video signal type identification" 在此简称为 H.273。

wp_color_representation_manager_v1

版本 1

颜色表示管理器单例

一个用于为 wl_surface 获取颜色表示扩展的单例全局 interface。该扩展接口允许设置 surface 的颜色表示。

Compositor 绝不应移除此全局对象。

wp_color_representation_manager_v1::destroy

类型: destructor

destroy()

销毁管理器

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

wp_color_representation_manager_v1::get_surface

get_surface(id: new_id<wp_color_representation_surface_v1>, surface: object<wl_surface>)

参数	类型	描述
id	new_id<wp_color_representation_surface_v1>
surface	object<wl_surface>

为 wl_surface 创建一个颜色表示接口

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

这会为给定的 wl_surface 创建一个新的颜色 wp_color_representation_surface_v1 对象。

有关更多详细信息，请参阅 wp_color_representation_surface_v1 interface。

wp_color_representation_manager_v1::supported_alpha_mode

supported_alpha_mode(alpha_mode: uint<wp_color_representation_surface_v1.alpha_mode>)

参数	类型	描述
alpha_mode	uint<wp_color_representation_surface_v1.alpha_mode>	supported alpha mode

支持的 alpha 模式

当创建此对象时，它应立即向每个 compositor 支持的 alpha 模式发送一次此 event。

有关支持的值的定义，请参阅 wp_color_representation_surface_v1::alpha_mode enum。

wp_color_representation_manager_v1::supported_coefficients_and_ranges

supported_coefficients_and_ranges(coefficients: uint<wp_color_representation_surface_v1.coefficients>, range: uint<wp_color_representation_surface_v1.range>)

参数	类型	描述
coefficients	uint<wp_color_representation_surface_v1.coefficients>	supported matrix coefficients
range	uint<wp_color_representation_surface_v1.range>	full range flag

支持的矩阵系数和范围

当创建此对象时，它应立即向每种 compositor 支持的矩阵系数和颜色范围组合发送一次此 event。

有关支持的值的定义，请参阅 wp_color_representation_surface_v1::coefficients 和 wp_color_representation_surface_v1::range enum。

wp_color_representation_manager_v1::done

done()

all features have been sent

This event is sent when all supported features have been sent.

wp_color_representation_manager_v1::error

error { surface_exists }

参数	值	描述
surface_exists	1	对于 wl_surface，wp_color_representation_surface_v1 已经存在

非法的创建请求

wp_color_representation_surface_v1

版本 1

基于 wl_surface 的颜色表示扩展接口

此 interface 用于设置 surface 的颜色表示。

最初，此 interface 将没有关联的颜色表示。这会导致 surface 表现为好像这个对象从未被创建一样。

当此对象的销毁或颜色表示设置导致 surface 失去其关联的颜色表示时，其状态重置回该 interface 未使用时的状态。

wp_color_representation_surface_v1::destroy

类型: destructor

destroy()

销毁颜色表示扩展

销毁 wp_color_representation_surface_v1 对象。这相当于清除状态并调用此对象的 destroy。然后状态将在下一个 wl_surface.commit 时应用。

如果底层 wl_surface 已经被销毁，在此 request 之前未提交的状态将被丢弃。

wp_color_representation_surface_v1::set_alpha_mode

set_alpha_mode(alpha_mode: uint<wp_color_representation_surface_v1.alpha_mode>)

参数	类型	描述
alpha_mode	uint<wp_color_representation_surface_v1.alpha_mode>	alpha mode

设置 alpha 模式

此 request 将 surface 的 alpha 模式状态更新为在下一次 wl_surface.commit 时应用的值。

如果在调用此 request 时附带了不支持的 alpha_mode（即从未通过 wp_color_representation_manager_v1::supported_alpha_mode 发送过），则 compositor 应发送 unsupported_alpha_mode 协议错误。

此状态的初始值为 straight（直通）。

wp_color_representation_surface_v1::set_coefficients_and_range

set_coefficients_and_range(coefficients: uint<wp_color_representation_surface_v1.coefficients>, range: uint<wp_color_representation_surface_v1.range>)

参数	类型	描述
coefficients	uint<wp_color_representation_surface_v1.coefficients>	matrix coefficients
range	uint<wp_color_representation_surface_v1.range>	range

set the matrix coefficients and range

If this protocol object is inert, the protocol error inert is raised.

Set the matrix coefficients and video range which defines the formula and the related constants used to derive red, green and blue signals. Usually coefficients correspond to MatrixCoefficients code points in H.273.

Only combinations advertised by the compositor are allowed to be used as argument for this request. The "coefficients" protocol error is raised otherwise.

A call to wl_surface.commit verifies that the pixel format and the coefficients-range combination in the committed surface contents are compatible, if contents exist. The "pixel_format" protocol error is raised otherwise.

A pixel format is compatible with the coefficients-range combination if the related equations and conventions as defined in H.273 can produce the color channels (RGB or YCbCr) of the pixel format.

For the definition of the supported combination, see the wp_color_representation_surface_v1::coefficients and wp_color_representation_surface_v1::range enums.

The coefficients-range combination is double-buffered, see wl_surface.commit.

wp_color_representation_surface_v1::set_chroma_location

set_chroma_location(chroma_location: uint<wp_color_representation_surface_v1.chroma_location>)

参数	类型	描述
chroma_location	uint<wp_color_representation_surface_v1.chroma_location>	chroma sample location

set the chroma location

If this protocol object is inert, the protocol error inert is raised.

Set the chroma location type which defines the position of downsampled chroma samples, corresponding to Chroma420SampleLocType code points in H.273.

An invalid chroma location enum value raises the "chroma_location" protocol error.

A call to wl_surface.commit verifies that the pixel format and chroma location type in the committed surface contents are compatible, if contents exist. The "pixel_format" protocol error is raised otherwise.

For the definition of the supported chroma location types, see the wp_color_representation_surface_v1::chroma_location enum.

The chroma location type is double-buffered, see wl_surface.commit.

wp_color_representation_surface_v1::error

error { alpha_mode, coefficients, pixel_format, inert, chroma_location }

参数	值	描述
alpha_mode	1	不支持的 alpha 模式
coefficients	2	不支持的矩阵系数
pixel_format	3	像素格式与已设置的值不兼容
inert	4	对无效对象的禁止请求
chroma_location	5	无效的色度位置

颜色表示错误

这些错误可能在违反由该 interface 或通过 compositor 未宣布的受支持属性引起的状态改变请求产生时发出。

wp_color_representation_surface_v1::alpha_mode

alpha_mode { premultiplied_electrical, premultiplied_optical, straight }

参数	值	描述
premultiplied_electrical	0	premultiplied alpha in electrical values Electrical color channel values (after transfer function encoding) are already multiplied with the alpha channel value.
premultiplied_optical	1	premultiplied alpha in optical values Optical color channel values (before transfer function encoding) are already multiplied with the alpha channel value.
straight	2	颜色通道与 alpha 不相关。渲染等效于 src_color * src_alpha + dst_color * (1 - src_alpha) 颜色通道与 alpha 不相关非预乘 (non-premultiplied)。这是通过 wl_surface 和 wl_subsurface 处理 alpha 时隐式采用的设置。在这种情况下，最终混合时的颜色将按给定源和其对应的不透明度因子进行加权。使用这种模式意味着如果附带颜色的颜色模型需要，源可以安全地将非线性变换直接应用于这些颜色分量（而不是使用 pre-multiplied（预乘）模式，后者只能在颜色为线性时工作）。数学上，渲染如下进行：src_color * src_alpha + dst_color * (1 - src_alpha)。

alpha 模式

指定表面 buffer 上的 alpha 通道的值如何与颜色分量相关联。请注意，当附带的 buffer 不提供 alpha 通道或者其颜色未定义时，这些都不会有任何效果。

wp_color_representation_surface_v1::coefficients

coefficients { identity, bt709, fcc, bt601, smpte240, bt2020, bt2020_cl, ictcp }

参数	值	描述
identity	1	Identity The identity matrix Coefficients as defined by IEC 61966-2-1 sRGB SMPTE ST 428-1 (2019) Equivalent to H.273 MatrixCoefficients code point 0. Compatible with pixel formats of the RGB family.
bt709	2	ITU-R BT.709-6 BT.709 matrix coefficients Coefficients as defined by Rec. ITU-R BT.709-6 Rec. ITU-R BT.1361-0 conventional colour gamut system (historical) Rec. ITU-R BT.1361-0 conventional colour gamut system and extended colour gamut system (historical) IEC 61966-2-4 xvYCC709 SMPTE RP 177 (1993) Annex B Equivalent to H.273 MatrixCoefficients code point 1. Compatible with pixel formats of the YCbCr family.
fcc	3	United States Federal Communications Commission Title 47 Code of Federal Regulations FCC matrix coefficients Coefficients as defined by United States Federal Communications Commission (2003) Title 47 Code of Federal Regulations 73.682 (a) (20) Equivalent to H.273 MatrixCoefficients code point 4. Compatible with pixel formats of the YCbCr family.
bt601	4	BT.601-7 matrix coefficients Coefficients as defined by Rec. ITU-R BT.470-6 System B, G (historical) Rec. ITU-R BT.601-7 625 Rec. ITU-R BT.601-7 525 Rec. ITU-R BT.1358-0 625 (historical) Rec. ITU-R BT.1358-1 525 or 625 (historical) Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM Rec. ITU-R BT.1700-0 NTSC IEC 61966-2-1 sYCC IEC 61966-2-4 xvYCC601 SMPTE ST 170 (2004) Equivalent to H.273 MatrixCoefficients code point 5, 6. Compatible with pixel formats of the YCbCr family.
smpte240	5	SMPTE ST 240 matrix coefficients Coefficients as defined by SMPTE ST 240 (1999) Equivalent to H.273 MatrixCoefficients code point 7. Compatible with pixel formats of the YCbCr family.
bt2020	6	ITU-R BT.2020-2 (non-constant luminance) BT.2020 and BT.2100 YCbCr matrix coefficients Coefficients as defined by Rec. ITU-R BT.2020-2 (non-constant luminance) Rec. ITU-R BT.2100-2 Y′CbCr Equivalent to H.273 MatrixCoefficients code point 9. Compatible with pixel formats of the YCbCr family.
bt2020_cl	7	BT.2020 matrix coefficients for constant luminance Coefficients as defined by Rec. ITU-R BT.2020-2 (constant luminance) Equivalent to H.273 MatrixCoefficients code point 10. Compatible with pixel formats of the YCbCr family.
ictcp	8	ITU-R BT.2100-2 ICtCp BT.2100 ICtCp matrix coefficients Coefficients as defined by Rec. ITU-R BT.2100-2 ICTCP Equivalent to H.273 MatrixCoefficients code point 14. Compatible with pixel formats of the YCbCr family.

矩阵系数

指定从 YCbCr 等系列转换为 RGB 等系列时使用的矩阵系数枚举。如 ITU-T H.273 中所指定的。

wp_color_representation_surface_v1::range

range { full, limited }

参数	值	描述
full	1	Full range
limited	2	Limited/Narrow range

颜色范围

指定正在显示的颜色分量应该如何根据为它们所表示的内容保留的最大边界或位数被进行量化。如 ITU-T H.273 中所指定的。

wp_color_representation_surface_v1::chroma_location

chroma_location { type_0, type_1, type_2, type_3, type_4, type_5 }

参数	值	描述
type_0	1	Horizontal offset of 0, vertical offset of 0.5 Corresponding to VkChromaLocations: xChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN yChromaOffset: VK_CHROMA_LOCATION_MIDPOINT Equivalent to H.273 Chroma420SampleLocType 0.
type_1	2	Horizontal offset of 0.5, vertical offset of 0.5 Corresponding to VkChromaLocations: xChromaOffset: VK_CHROMA_LOCATION_MIDPOINT yChromaOffset: VK_CHROMA_LOCATION_MIDPOINT Equivalent to H.273 Chroma420SampleLocType 1.
type_2	3	Horizontal offset of 0, vertical offset of 0 Corresponding to VkChromaLocations: xChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN yChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN Equivalent to H.273 Chroma420SampleLocType 2.
type_3	4	Horizontal offset of 0.5, vertical offset of 0 Corresponding to VkChromaLocations: xChromaOffset: VK_CHROMA_LOCATION_MIDPOINT yChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN Equivalent to H.273 Chroma420SampleLocType 3.
type_4	5	Horizontal offset of 0, vertical offset of 1 Equivalent to H.273 Chroma420SampleLocType 4.
type_5	6	Horizontal offset of 0.5, vertical offset of 1 Equivalent to H.273 Chroma420SampleLocType 5.

色度位置

这些基于基于像素下采样如何完成所确定的值进行枚举。如 ITU-T H.273 中所指定的。

合成器支持

	Cage 0.2.0	COSMIC 1.0.0~beta.8	GameScope 3.15.14	Hyprland 0.52.1	Jay 1.12.0	KWin 6.6	Labwc 0.9.2	Louvre 2.14.1	Mir 2.26	Muffin 6.6.0	Mutter 49.2	niri 25.11	phoc 0.52	river 0.3.13	Sway 1.11	Treeland 0.8.0	Wayfire 0.9.0	Weston 14.0.2
wp_color_representation_manager_v1	x	x	x	x	1	1	x	x	x	x	1	x	x	x	x	x	x	x

Copyright

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.