KDE output device v2
kde_output_device_v2
输出设备描述了合成器可用的显示设备。output_device 与 wl_output 类似，但侧重于输出配置管理。
客户端可以查询所有全局 output_device 对象以列出所有可用的显示设备，包括那些当前可能未被合成器表示为 wl_output 的设备。
客户端通过 outputconfiguration 接口向服务器发送配置更改，服务器将配置更改应用到硬件并向输出设备发出相应的更改信号。
此对象在启动时作为全局对象发布，用于每个可用的显示设备，或在设备稍后可用时发布（例如通过物理连接器热插拔）。
警告！此文件中描述的协议是桌面环境的实现细节。普通客户端不得使用此协议。可能会在不增加扩展主版本的情况下添加向后不兼容的更改。
geometry(x: int, y: int, physical_width: int, physical_height: int, subpixel: int, make: string, model: string, transform: int)
参数 | 类型 | 描述 |
|---|---|---|
| x | int | x position within the global compositor space |
| y | int | y position within the global compositor space |
| physical_width | int | width in millimeters of the output |
| physical_height | int | height in millimeters of the output |
| subpixel | int | subpixel orientation of the output |
| make | string | textual description of the manufacturer |
| model | string | textual description of the model |
| transform | int | transform that maps framebuffer to output |
geometry 事件描述输出的几何属性。该事件在绑定到输出对象时以及任何属性更改时发送。
current_mode(mode: object<kde_output_device_mode_v2>)
参数 | 类型 | 描述 |
|---|---|---|
| mode | object<kde_output_device_mode_v2> |
此事件描述此输出头当前使用的模式。仅在输出启用时发送。
mode(mode: new_id<kde_output_device_mode_v2>)
参数 | 类型 | 描述 |
|---|---|---|
| mode | new_id<kde_output_device_mode_v2> |
mode 事件描述输出的可用模式。
当客户端绑定到 output_device 对象时，服务器会为 output_device 可以操作的每个可用模式发送一次此事件。
初始绑定时至少会发送一个事件，表示当前模式。
之后如果输出发生变化，其 mode 事件会再次发送，用于最终添加的模式，最后是当前模式。换句话说，当前模式始终由最后发送的带有 current 标志的事件表示。
模式的大小以输出设备的物理硬件单位给出。这不一定与全局合成器空间中的输出大小相同。例如，输出可能被缩放（如 kde_output_device_v2.scale 中所述）或变换（如 kde_output_device_v2.transform 中所述）。
done()
此事件在绑定到输出对象时所有其他属性发送完毕后，以及之后任何其他输出属性更改应用后发送。这允许将输出属性的更改视为原子操作，即使多个事件连续宣布它们。
scale(factor: fixed)
参数 | 类型 | 描述 |
|---|---|---|
| factor | fixed | scaling factor of output |
此事件包含 geometry 事件中未包含的缩放几何信息。可以在绑定输出对象后或输出缩放稍后更改时发送。如果未发送，客户端应假设缩放比例为 1。
缩放比例大于 1 意味着合成器在渲染时会自动按此倍数缩放表面缓冲区。这用于高分辨率显示器，在这些显示器上应用程序以原生分辨率渲染会太小而难以阅读。
缩放感知客户端应跟踪表面的当前输出，如果它在缩放的输出上，应使用 wl_surface.set_buffer_scale 设置输出的缩放比例。这样合成器可以避免缩放表面，客户端可以提供更高质量的图像。
edid(raw: string)
参数 | 类型 | 描述 |
|---|---|---|
| raw | string | base64-encoded EDID string |
edid 事件封装了输出设备的 EDID 数据。
该事件在绑定到输出对象时发送。EDID 数据可能为空，在这种情况下仍会发送此事件。如果 EDID 信息为空，可以回退使用输出设备的 name 等属性。
enabled(enabled: int)
参数 | 类型 | 描述 |
|---|---|---|
| enabled | int | output enabled state |
enabled 事件通知此输出当前是否已启用并被服务器用于显示内容。该事件在绑定到输出对象时以及输出稍后通过启用或禁用更改状态时发送。
uuid(uuid: string)
参数 | 类型 | 描述 |
|---|---|---|
| uuid | string | output devices ID |
uuid 可用于标识输出。它完全由服务器控制。服务器应确保 uuid 在重启后保持持久。空的 uuid 被视为无效。
serial_number(serialNumber: string)
参数 | 类型 | 描述 |
|---|---|---|
| serialNumber | string | textual representation of serial number |
显示器的序列号，在启动时第一个 done 事件之前发送。
eisa_id(eisaId: string)
参数 | 类型 | 描述 |
|---|---|---|
| eisaId | string | textual representation of EISA identifier |
显示器的 EISA ID，在启动时第一个 done 事件之前发送。
capabilities(flags: uint<kde_output_device_v2.capability>)
参数 | 类型 | 描述 |
|---|---|---|
| flags | uint<kde_output_device_v2.capability> |
此设备具有哪些功能，在启动时第一个 done 事件之前发送。
overscan(overscan: uint)
参数 | 类型 | 描述 |
|---|---|---|
| overscan | uint | amount of overscan of the monitor |
显示器的过扫描值（百分比），在启动时第一个 done 事件之前发送。
vrr_policy(vrr_policy: uint<kde_output_device_v2.vrr_policy>)
参数 | 类型 | 描述 |
|---|---|---|
| vrr_policy | uint<kde_output_device_v2.vrr_policy> |
合成器在使用可变刷新率方面将采用什么策略。
rgb_range(rgb_range: uint<kde_output_device_v2.rgb_range>)
参数 | 类型 | 描述 |
|---|---|---|
| rgb_range | uint<kde_output_device_v2.rgb_range> |
合成器对此输出使用的 RGB 范围
high_dynamic_range(hdr_enabled: uint)
参数 | 类型 | 描述 |
|---|---|---|
| hdr_enabled | uint | 1 if enabled, 0 if disabled |
此输出是否启用了高动态范围
sdr_brightness(sdr_brightness: uint)
参数 | 类型 | 描述 |
|---|---|---|
| sdr_brightness | uint |
如果使用高动态范围，此值定义标准动态范围格式内容的亮度（以尼特为单位）。请注意，虽然该值以尼特为单位，但这不一定等同于屏幕上的相同亮度。
wide_color_gamut(wcg_enabled: uint)
参数 | 类型 | 描述 |
|---|---|---|
| wcg_enabled | uint | 1 if enabled, 0 if disabled |
此输出是否启用了广色域
auto_rotate_policy(policy: uint<kde_output_device_v2.auto_rotate_policy>)
参数 | 类型 | 描述 |
|---|---|---|
| policy | uint<kde_output_device_v2.auto_rotate_policy> |
brightness_metadata(max_peak_brightness: uint, max_frame_average_brightness: uint, min_brightness: uint)
参数 | 类型 | 描述 |
|---|---|---|
| max_peak_brightness | uint | in nits |
| max_frame_average_brightness | uint | in nits |
| min_brightness | uint | in 0.0001 nits |
brightness_overrides(max_peak_brightness: int, max_average_brightness: int, min_brightness: int)
参数 | 类型 | 描述 |
|---|---|---|
| max_peak_brightness | int | -1 for no override, positive values are the brightness in nits |
| max_average_brightness | int | -1 for no override, positive values are the brightness in nits |
| min_brightness | int | -1 for no override, positive values are the brightness in 0.0001 nits |
sdr_gamut_wideness(gamut_wideness: uint)
参数 | 类型 | 描述 |
|---|---|---|
| gamut_wideness | uint | 0 means rec.709 primaries, 10000 means native primaries |
可用于提供用户认为 sRGB 应用程序应具有的颜色，基于许多现代 sRGB 屏幕上的默认体验。
color_profile_source(source: uint<kde_output_device_v2.color_profile_source>)
参数 | 类型 | 描述 |
|---|---|---|
| source | uint<kde_output_device_v2.color_profile_source> |
brightness(brightness: uint)
参数 | 类型 | 描述 |
|---|---|---|
| brightness | uint | brightness in 0-10000 |
这是输出的亮度调节器。它不指定任何绝对值，而只是在其他亮度值（如 sdr_brightness 和 brightness_metadata）之上的乘数。0 是最小亮度（不是完全黑暗），10000 是最大亮度。 目前仅在 HDR 激活时支持/有意义。
color_power_tradeoff(preference: uint<kde_output_device_v2.color_power_tradeoff>)
dimming(multiplier: uint)
参数 | 类型 | 描述 |
|---|---|---|
| multiplier | uint | multiplier in 0-10000 |
这是输出的调光乘数。这与亮度设置类似，但它只是临时设置，不是持久的，并且可能根据显示器的不同以不同方式实现。0 是最小调光系数（不是完全黑暗），10000 表示输出未被调光。
ddc_ci_allowed(allowed: uint)
参数 | 类型 | 描述 |
|---|---|---|
| allowed | uint | 1 if allowed, 0 if disabled |
如果存在 ddc_ci 功能，这决定了是否应使用 DDC/CI 设置亮度、对比度等。
max_bits_per_color(max_bpc: uint)
参数 | 类型 | 描述 |
|---|---|---|
| max_bpc | uint | 0 for the default / automatic |
这限制了发送到显示器的每颜色位数。
参数 | 类型 | 描述 |
|---|---|---|
| min_value | uint | the minimum supported by the driver |
| max_value | uint | the maximum supported by the driver |
automatic_max_bits_per_color_limit(max_bpc_limit: uint)
参数 | 类型 | 描述 |
|---|---|---|
| max_bpc_limit | uint | which value automatic bpc gets limited to. 0 if not limited |
edr_policy(policy: uint<kde_output_device_v2.edr_policy>)
参数 | 类型 | 描述 |
|---|---|---|
| policy | uint<kde_output_device_v2.edr_policy> |
当 EDR 启用时，合成器可能会将背光提高到用户指定的设置之上，以便在没有原生 HDR 支持的显示器上呈现 HDR 内容。这通常会带来更好的视觉效果，但也会增加电池消耗。
sharpness(sharpness: uint)
参数 | 类型 | 描述 |
|---|---|---|
| sharpness | uint | sharpness in 0-10000 |
这是输出的锐度调节器。0 表示禁用锐度，10000 表示最大锐度
priority(priority: uint)
参数 | 类型 | 描述 |
|---|---|---|
| priority | uint | priority |
描述输出在输出顺序列表中的位置，值较小的在列表中靠前。列表没有特定的起始值，此值仅用于排序输出。
请注意，输出顺序协议对此不够充分，因为如果输出被禁用或正在镜像另一个屏幕，它可能不在输出顺序中。
subpixel { unknown, none, horizontal_rgb, horizontal_bgr, vertical_rgb, vertical_bgr }
此枚举描述输出上物理像素的排列方式。
transform { normal, 90, 180, 270, flipped, flipped_90, flipped_180, flipped_270 }
这描述了合成器将应用于表面的变换，以补偿输出设备的旋转或镜像。
翻转值对应于围绕垂直轴的初始翻转，然后是旋转。
其目的主要是允许客户端相应地渲染并通知合成器，以便对于全屏表面，合成器仍然可以直接扫描客户端表面。
capability { overscan, vrr, rgb_range, high_dynamic_range, wide_color_gamut, auto_rotate, icc_profile, brightness, built_in_color, ddc_ci, max_bits_per_color, edr, sharpness, custom_modes, auto_brightness }
参数 | 值 | 描述 |
|---|---|---|
| overscan | 0x1 | 此 output_device 是否支持过扫描 |
| vrr | 0x2 | 此 outputdevice 是否支持可变刷新率 |
| rgb_range | 0x4 | 是否可以设置 RGB 范围 |
| high_dynamic_range起始版本 3 | 0x8 | 此 outputdevice 是否支持高动态范围 |
| wide_color_gamut起始版本 3 | 0x10 | 此 outputdevice 是否支持广色域 |
| auto_rotate起始版本 4 | 0x20 | 此 outputdevice 是否支持自动旋转 |
| icc_profile起始版本 5 | 0x40 | 此 outputdevice 是否支持 ICC 配置文件 |
| brightness起始版本 9 | 0x80 | 此 outputdevice 是否支持亮度设置 |
| built_in_color起始版本 12 | 0x100 | 此 outputdevice 是否支持内置颜色配置文件 |
| ddc_ci起始版本 14 | 0x200 | 此 outputdevice 是否支持 DDC/CI |
| max_bits_per_color起始版本 15 | 0x400 | 此 outputdevice 是否支持设置最大每颜色位数 |
| edr起始版本 16 | 0x800 | 此 outputdevice 是否支持 EDR |
| sharpness起始版本 17 | 0x1000 | 此 outputdevice 是否支持锐度设置 |
| custom_modes起始版本 18 | 0x2000 | 此 outputdevice 是否支持自定义模式 |
| auto_brightness起始版本 19 | 0x4000 |
描述此设备具有哪些功能。
描述合成器何时可以使用可变刷新率
应使用全范围还是有限范围颜色
color_power_tradeoff { efficiency, accuracy }
参数 | 值 | 描述 |
|---|---|---|
| efficiency | 0 | 优先考虑效率和性能 |
| accuracy | 1 | 优先考虑准确性 |
合成器可以做很多事情来权衡性能、功耗和颜色准确性。此设置描述了用户关于应在哪个方向进行权衡的高级偏好。
此对象描述输出模式。
某些输出头不支持输出模式，在这种情况下不会公布模式。
通过此接口发送的属性通过 kde_output_device.done 事件原子性地应用。不保证属性的发送顺序。
此事件描述模式大小。大小以输出设备的物理硬件单位给出。这不一定与全局合成器空间中的输出大小相同。例如，输出可能被缩放或变换。
refresh(refresh: int)
参数 | 类型 | 描述 |
|---|---|---|
| refresh | int | vertical refresh rate in mHz |
此事件描述模式的固定垂直刷新率。仅在模式具有固定刷新率时发送。
flags(flags: uint<kde_output_device_mode_v2.flags>)
参数 | 类型 | 描述 |
|---|---|---|
| flags | uint<kde_output_device_mode_v2.flags> |
此事件描述模式的标志。
合成器支持
Cage  | COSMIC  | GameScope  | Hyprland  | Jay | KWin  | Labwc  | Louvre  | Mir  | Muffin  | Mutter  | niri  | phoc  | river  | Sway  | Treeland  | Wayfire  | Weston  | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| kde_output_device_v2 | x | x | x | x | x | 20 | x | x | x | x | x | x | x | x | x | x | x | x |
Copyright
SPDX-FileCopyrightText: 2008-2011 Kristian Høgsberg SPDX-FileCopyrightText: 2010-2011 Intel Corporation SPDX-FileCopyrightText: 2012-2013 Collabora, Ltd. SPDX-FileCopyrightText: 2015 Sebastian Kügler <sebas@kde.org> SPDX-FileCopyrightText: 2021 Méven Car <meven.car@enioka.com>
SPDX-License-Identifier: MIT-CMU