From 2341346c9005cef56ff26018fdd4962362da0d82 Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Thu, 18 Jul 2024 14:32:29 +0200 Subject: [PATCH] wayland: Implement the color management protocol v4 To expose it, run mutter/gnome-shell with `--debug-control` and then call `./tools/debug-control.py --enable ColorManagementProtocol`, or set `MUTTER_DEBUG_COLOR_MANAGEMENT_PROTOCOL=1`. Co-authored-by: Joan Torres Part-of: --- src/meson.build | 3 + src/wayland/meta-wayland-color-management.c | 1405 +++++++++++++++++ src/wayland/meta-wayland-color-management.h | 25 + src/wayland/meta-wayland-versions.h | 1 + src/wayland/meta-wayland.c | 2 + src/wayland/protocol/color-management-v1.xml | 1453 ++++++++++++++++++ 6 files changed, 2889 insertions(+) create mode 100644 src/wayland/meta-wayland-color-management.c create mode 100644 src/wayland/meta-wayland-color-management.h create mode 100644 src/wayland/protocol/color-management-v1.xml diff --git a/src/meson.build b/src/meson.build index ac81a1cfd..71192fc81 100644 --- a/src/meson.build +++ b/src/meson.build @@ -602,6 +602,8 @@ if have_wayland 'wayland/meta-wayland.c', 'wayland/meta-wayland-client.c', 'wayland/meta-wayland-client-private.h', + 'wayland/meta-wayland-color-management.c', + 'wayland/meta-wayland-color-management.h', 'wayland/meta-wayland-cursor-surface.c', 'wayland/meta-wayland-cursor-surface.h', 'wayland/meta-wayland-data-device.c', @@ -1103,6 +1105,7 @@ if have_wayland ['xdg-shell', 'stable', ], ['xwayland-keyboard-grab', 'unstable', 'v1', ], ['linux-drm-syncobj-v1', 'private', ], + ['color-management-v1', 'private', ], ] if have_wayland_eglstream wayland_eglstream_protocols_dir = wayland_eglstream_protocols_dep.get_variable('pkgdatadir') diff --git a/src/wayland/meta-wayland-color-management.c b/src/wayland/meta-wayland-color-management.c new file mode 100644 index 000000000..13996f13f --- /dev/null +++ b/src/wayland/meta-wayland-color-management.c @@ -0,0 +1,1405 @@ +/* + * Copyright (C) 2024 SUSE Software Solutions Germany GmbH + * Copyright (C) 2024 Red Hat + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License as + * published by the Free Software Foundation; either version 2 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, see . + * + * Written by: + * Joan Torres + * Sebastian Wick + */ + +#include "config.h" + +#include "meta-wayland-color-management.h" + +#include "backends/meta-color-device.h" +#include "backends/meta-color-manager.h" +#include "compositor/meta-surface-actor-wayland.h" +#include "core/meta-debug-control-private.h" +#include "wayland/meta-wayland-private.h" +#include "wayland/meta-wayland-versions.h" +#include "wayland/meta-wayland-outputs.h" + +#include "color-management-v1-server-protocol.h" + +struct _MetaWaylandColorManager +{ + GObject parent; + + MetaWaylandCompositor *compositor; + struct wl_global *global; + + gulong color_state_changed_handler_id; + + /* struct wl_resource */ + GList *resources; + + /* Key: MetaMonitor + * Value: MetaWaylandColorManagementOutput + */ + GHashTable *outputs; + + /* Key: MetaWaylandSurface + * Value: MetaWaylandColorManagementSurface + */ + GHashTable *surfaces; +}; + +#define META_TYPE_WAYLAND_COLOR_MANAGER (meta_wayland_color_manager_get_type ()) +G_DECLARE_FINAL_TYPE (MetaWaylandColorManager, + meta_wayland_color_manager, + META, WAYLAND_COLOR_MANAGER, + GObject) + +G_DEFINE_TYPE (MetaWaylandColorManager, + meta_wayland_color_manager, + G_TYPE_OBJECT) + +typedef struct _MetaWaylandColorManagementOutput +{ + MetaWaylandColorManager *color_manager; + + /* struct wl_resource */ + GList *resources; + MetaWaylandOutput *output; + gulong output_destroyed_handler_id; +} MetaWaylandColorManagementOutput; + +typedef struct _MetaWaylandColorManagementSurface +{ + MetaWaylandColorManager *color_manager; + + struct wl_resource *resource; + /* struct wl_resource */ + GList *feedback_resources; + + MetaWaylandSurface *surface; + gulong surface_destroyed_handler_id; + gulong surface_main_monitor_handler_id; + ClutterColorState *preferred_color_state; +} MetaWaylandColorManagementSurface; + +typedef enum _MetaWaylandImageDescriptionState +{ + META_WAYLAND_IMAGE_DESCRIPTION_STATE_PENDING, + META_WAYLAND_IMAGE_DESCRIPTION_STATE_READY, + META_WAYLAND_IMAGE_DESCRIPTION_STATE_FAILED, +} MetaWaylandImageDescriptionState; + +typedef enum _MetaWaylandImageDescriptionFlags +{ + META_WAYLAND_IMAGE_DESCRIPTION_FLAGS_DEFAULT = 0, + META_WAYLAND_IMAGE_DESCRIPTION_FLAGS_ALLOW_INFO = (1 << 0), +} MetaWaylandImageDescriptionFlags; + +typedef struct _MetaWaylandImageDescription +{ + MetaWaylandColorManager *color_manager; + struct wl_resource *resource; + MetaWaylandImageDescriptionState state; + gboolean has_info; + ClutterColorState *color_state; +} MetaWaylandImageDescription; + +typedef struct _MetaWaylandCreatorParams +{ + MetaWaylandColorManager *color_manager; + struct wl_resource *resource; + + ClutterColorspace colorspace; + ClutterTransferFunction transfer_function; +} MetaWaylandCreatorParams; + +static void meta_wayland_color_management_surface_free (MetaWaylandColorManagementSurface *cm_surface); + +static void meta_wayland_color_management_output_free (MetaWaylandColorManagementOutput *cm_output); + +static MetaMonitorManager * +get_monitor_manager (MetaWaylandColorManager *color_manager) +{ + MetaWaylandCompositor *compositor = color_manager->compositor; + MetaBackend *backend = meta_context_get_backend (compositor->context); + + return meta_backend_get_monitor_manager (backend); +} + +static ClutterContext * +get_clutter_context (MetaWaylandColorManager *color_manager) +{ + MetaWaylandCompositor *compositor = color_manager->compositor; + MetaBackend *backend = meta_context_get_backend (compositor->context); + + return meta_backend_get_clutter_context (backend); +} + +static MetaColorManager * +get_meta_color_manager (MetaWaylandColorManager *color_manager) +{ + MetaWaylandCompositor *compositor = color_manager->compositor; + MetaBackend *backend = meta_context_get_backend (compositor->context); + + return meta_backend_get_color_manager (backend); +} + +static ClutterColorManager * +get_clutter_color_manager (MetaWaylandColorManager *color_manager) +{ + ClutterContext *clutter_context = get_clutter_context (color_manager); + + return clutter_context_get_color_manager (clutter_context); +} + +static gboolean +wayland_tf_to_clutter (enum xx_color_manager_v4_transfer_function tf, + ClutterTransferFunction *tf_out) +{ + switch (tf) + { + case XX_COLOR_MANAGER_V4_TRANSFER_FUNCTION_SRGB: + *tf_out = CLUTTER_TRANSFER_FUNCTION_SRGB; + return TRUE; + case XX_COLOR_MANAGER_V4_TRANSFER_FUNCTION_ST2084_PQ: + *tf_out = CLUTTER_TRANSFER_FUNCTION_PQ; + return TRUE; + default: + return FALSE; + } +} + +static enum xx_color_manager_v4_transfer_function +clutter_tf_to_wayland (ClutterTransferFunction tf) +{ + switch (tf) + { + case CLUTTER_TRANSFER_FUNCTION_DEFAULT: + case CLUTTER_TRANSFER_FUNCTION_SRGB: + return XX_COLOR_MANAGER_V4_TRANSFER_FUNCTION_SRGB; + case CLUTTER_TRANSFER_FUNCTION_PQ: + return XX_COLOR_MANAGER_V4_TRANSFER_FUNCTION_ST2084_PQ; + case CLUTTER_TRANSFER_FUNCTION_LINEAR: + return XX_COLOR_MANAGER_V4_TRANSFER_FUNCTION_LINEAR; + } + g_assert_not_reached (); +} + +static gboolean +wayland_primaries_to_clutter (enum xx_color_manager_v4_primaries primaries, + ClutterColorspace *primaries_out) +{ + switch (primaries) + { + case XX_COLOR_MANAGER_V4_PRIMARIES_SRGB: + *primaries_out = CLUTTER_COLORSPACE_SRGB; + return TRUE; + case XX_COLOR_MANAGER_V4_PRIMARIES_BT2020: + *primaries_out = CLUTTER_COLORSPACE_BT2020; + return TRUE; + default: + return FALSE; + } +} + +static enum xx_color_manager_v4_primaries +clutter_primaries_to_wayland (ClutterColorspace primaries) +{ + switch (primaries) + { + case CLUTTER_COLORSPACE_DEFAULT: + case CLUTTER_COLORSPACE_SRGB: + return XX_COLOR_MANAGER_V4_PRIMARIES_SRGB; + case CLUTTER_COLORSPACE_BT2020: + return XX_COLOR_MANAGER_V4_PRIMARIES_BT2020; + } + g_assert_not_reached (); +} + +static ClutterColorState * +get_default_color_state (MetaWaylandColorManager *color_manager) +{ + ClutterColorManager *clutter_color_manager = + get_clutter_color_manager (color_manager); + + return clutter_color_manager_get_default_color_state (clutter_color_manager); +} + +static ClutterColorState * +get_output_color_state (MetaWaylandColorManager *color_manager, + MetaMonitor *monitor) +{ + MetaColorManager *meta_color_manager = get_meta_color_manager (color_manager); + MetaColorDevice *color_device = + meta_color_manager_get_color_device (meta_color_manager, monitor); + ClutterColorState *color_state = NULL; + + if (color_device) + color_state = meta_color_device_get_color_state (color_device); + + if (!color_state) + color_state = get_default_color_state (color_manager); + + return color_state; +} + +static MetaWaylandImageDescription * +meta_wayland_image_description_new (MetaWaylandColorManager *color_manager, + struct wl_resource *resource) +{ + MetaWaylandImageDescription *image_desc; + + image_desc = g_new0 (MetaWaylandImageDescription, 1); + image_desc->color_manager = color_manager; + image_desc->resource = resource; + + return image_desc; +} + +static MetaWaylandImageDescription * +meta_wayland_image_description_new_failed (MetaWaylandColorManager *color_manager, + struct wl_resource *resource, + enum xx_image_description_v4_cause cause, + const char *message) +{ + MetaWaylandImageDescription *image_desc; + + image_desc = meta_wayland_image_description_new (color_manager, resource); + image_desc->state = META_WAYLAND_IMAGE_DESCRIPTION_STATE_FAILED; + image_desc->has_info = FALSE; + xx_image_description_v4_send_failed (resource, cause, message); + + return image_desc; +} + +static MetaWaylandImageDescription * +meta_wayland_image_description_new_color_state (MetaWaylandColorManager *color_manager, + struct wl_resource *resource, + ClutterColorState *color_state, + MetaWaylandImageDescriptionFlags flags) +{ + MetaWaylandImageDescription *image_desc; + + image_desc = meta_wayland_image_description_new (color_manager, resource); + image_desc->state = META_WAYLAND_IMAGE_DESCRIPTION_STATE_READY; + image_desc->has_info = !!(flags & META_WAYLAND_IMAGE_DESCRIPTION_FLAGS_ALLOW_INFO); + image_desc->color_state = g_object_ref (color_state); + xx_image_description_v4_send_ready (resource, + clutter_color_state_get_id (color_state)); + + return image_desc; +} + +static void +meta_wayland_image_description_free (MetaWaylandImageDescription *image_desc) +{ + g_clear_object (&image_desc->color_state); + + free (image_desc); +} + +static void +image_description_destructor (struct wl_resource *resource) +{ + MetaWaylandImageDescription *image_desc = wl_resource_get_user_data (resource); + + meta_wayland_image_description_free (image_desc); +} + +static void +image_description_destroy (struct wl_client *client, + struct wl_resource *resource) +{ + wl_resource_destroy (resource); +} + +static void +send_information (struct wl_resource *info_resource, + ClutterColorState *color_state) +{ + ClutterColorspace clutter_colorspace = + clutter_color_state_get_colorspace (color_state); + ClutterTransferFunction clutter_tf = + clutter_color_state_get_transfer_function (color_state); + enum xx_color_manager_v4_primaries primaries = + clutter_primaries_to_wayland (clutter_colorspace); + enum xx_color_manager_v4_transfer_function tf = + clutter_tf_to_wayland (clutter_tf); + + xx_image_description_info_v4_send_primaries_named (info_resource, primaries); + xx_image_description_info_v4_send_tf_named (info_resource, tf); +} + +static void +image_description_get_information (struct wl_client *client, + struct wl_resource *resource, + uint32_t id) +{ + MetaWaylandImageDescription *image_desc = wl_resource_get_user_data (resource); + struct wl_resource *info_resource; + + if (image_desc->state != META_WAYLAND_IMAGE_DESCRIPTION_STATE_READY) + { + wl_resource_post_error (resource, + XX_IMAGE_DESCRIPTION_V4_ERROR_NOT_READY, + "The image description is not ready"); + return; + } + + if (!image_desc->has_info) + { + wl_resource_post_error (resource, + XX_IMAGE_DESCRIPTION_V4_ERROR_NO_INFORMATION, + "The image description has no information"); + return; + } + + g_return_if_fail (image_desc->color_state); + + info_resource = + wl_resource_create (client, + &xx_image_description_info_v4_interface, + wl_resource_get_version (resource), + id); + + send_information (info_resource, image_desc->color_state); + + xx_image_description_info_v4_send_done (info_resource); + wl_resource_destroy (info_resource); +} + +static const struct xx_image_description_v4_interface + meta_wayland_image_description_interface = +{ + image_description_destroy, + image_description_get_information, +}; + +static void +update_preferred_color_state (MetaWaylandColorManagementSurface *cm_surface) +{ + MetaWaylandColorManager *color_manager = cm_surface->color_manager; + MetaMonitorManager *monitor_manager = get_monitor_manager (color_manager); + MetaWaylandSurface *surface = cm_surface->surface; + MetaLogicalMonitor *logical_monitor; + ClutterColorState *color_state = NULL; + GList *l; + gboolean initial = !cm_surface->preferred_color_state; + + g_return_if_fail (surface != NULL); + + logical_monitor = meta_wayland_surface_get_main_monitor (surface); + if (!logical_monitor) + { + logical_monitor = + meta_monitor_manager_get_primary_logical_monitor (monitor_manager); + } + + if (logical_monitor) + { + GList *monitors = meta_logical_monitor_get_monitors (logical_monitor); + + g_return_if_fail (monitors != NULL); + + color_state = get_output_color_state (color_manager, monitors->data); + } + + if (!color_state) + color_state = get_default_color_state (color_manager); + + if (cm_surface->preferred_color_state && + clutter_color_state_equals (color_state, + cm_surface->preferred_color_state)) + return; + + g_set_object (&cm_surface->preferred_color_state, color_state); + + if (initial) + return; + + for (l = cm_surface->feedback_resources; l; l = l->next) + { + struct wl_resource *resource = l->data; + + xx_color_management_feedback_surface_v4_send_preferred_changed (resource); + } +} + +static void +on_surface_destroy (MetaWaylandSurface *surface, + gpointer user_data) +{ + MetaWaylandColorManagementSurface *cm_surface = user_data; + + meta_wayland_color_management_surface_free (cm_surface); +} + +static void +on_main_monitor_changed (MetaWaylandSurface *surface, + GParamSpec *pspec, + gpointer user_data) +{ + MetaWaylandColorManagementSurface *cm_surface = user_data; + + update_preferred_color_state (cm_surface); +} + +static MetaWaylandColorManagementSurface * +meta_wayland_color_management_surface_new (MetaWaylandColorManager *color_manager, + MetaWaylandSurface *surface) +{ + MetaWaylandColorManagementSurface *cm_surface; + + cm_surface = g_new0 (MetaWaylandColorManagementSurface, 1); + cm_surface->color_manager = color_manager; + cm_surface->surface = surface; + + cm_surface->surface_destroyed_handler_id = + g_signal_connect (surface, "destroy", + G_CALLBACK (on_surface_destroy), + cm_surface); + cm_surface->surface_main_monitor_handler_id = + g_signal_connect (surface, "notify::main-monitor", + G_CALLBACK (on_main_monitor_changed), + cm_surface); + + g_hash_table_insert (color_manager->surfaces, surface, cm_surface); + + return cm_surface; +} + +static void +meta_wayland_color_management_surface_free (MetaWaylandColorManagementSurface *cm_surface) +{ + GList *l; + + for (l = cm_surface->feedback_resources; l; l = l->next) + { + struct wl_resource *resource = l->data; + + wl_resource_set_user_data (resource, NULL); + } + + g_clear_list (&cm_surface->feedback_resources, NULL); + + if (cm_surface->resource) + wl_resource_set_user_data (cm_surface->resource, NULL); + + g_clear_signal_handler (&cm_surface->surface_destroyed_handler_id, + cm_surface->surface); + g_clear_signal_handler (&cm_surface->surface_main_monitor_handler_id, + cm_surface->surface); + + g_hash_table_remove (cm_surface->color_manager->surfaces, + cm_surface->surface); + + free (cm_surface); +} + +static MetaWaylandColorManagementSurface * +ensure_color_management_surface (MetaWaylandColorManager *color_manager, + MetaWaylandSurface *surface) +{ + MetaWaylandColorManagementSurface *cm_surface; + + cm_surface = g_hash_table_lookup (color_manager->surfaces, surface); + if (cm_surface) + return cm_surface; + + return meta_wayland_color_management_surface_new (color_manager, surface); +} + +static void +set_image_description (MetaWaylandColorManagementSurface *cm_surface, + ClutterColorState *color_state) +{ + MetaWaylandColorManager *color_manager = cm_surface->color_manager; + MetaWaylandSurface *surface = cm_surface->surface; + MetaWaylandSurfaceState *pending = + meta_wayland_surface_get_pending_state (surface); + ClutterColorState *new_color_state; + + if (color_state) + new_color_state = color_state; + else + new_color_state = get_default_color_state (color_manager); + + g_assert (new_color_state); + + pending->has_new_color_state = TRUE; + g_set_object (&pending->color_state, new_color_state); +} + +static void +color_management_surface_destructor (struct wl_resource *resource) +{ + MetaWaylandColorManagementSurface *cm_surface = + wl_resource_get_user_data (resource); + + if (!cm_surface) + return; + + set_image_description (cm_surface, NULL); + + cm_surface->resource = NULL; +} + +static void +color_management_surface_destroy (struct wl_client *client, + struct wl_resource *resource) +{ + wl_resource_destroy (resource); +} + +static void +color_management_surface_set_image_description (struct wl_client *client, + struct wl_resource *resource, + struct wl_resource *image_desc_resource, + uint32_t render_intent) +{ + MetaWaylandColorManagementSurface *cm_surface = + wl_resource_get_user_data (resource); + MetaWaylandImageDescription *image_desc = + wl_resource_get_user_data (image_desc_resource); + + if (!cm_surface) + { + /* FIXME: the next version will have an ERROR_INERT */ + wl_resource_post_error (resource, + XX_COLOR_MANAGEMENT_SURFACE_V4_ERROR_IMAGE_DESCRIPTION, + "Underlying surface object has been destroyed"); + return; + } + + if (!image_desc->color_state || + image_desc->state != META_WAYLAND_IMAGE_DESCRIPTION_STATE_READY) + { + wl_resource_post_error (resource, + XX_COLOR_MANAGEMENT_SURFACE_V4_ERROR_IMAGE_DESCRIPTION, + "Trying to set an image description which is not ready"); + return; + } + + switch (render_intent) + { + case XX_COLOR_MANAGER_V4_RENDER_INTENT_PERCEPTUAL: + break; + default: + wl_resource_post_error (resource, + XX_COLOR_MANAGEMENT_SURFACE_V4_ERROR_RENDER_INTENT, + "Trying to use an unsupported rendering intent"); + return; + } + + set_image_description (cm_surface, image_desc->color_state); +} + +static void +color_management_surface_unset_image_description (struct wl_client *client, + struct wl_resource *resource) +{ + MetaWaylandColorManagementSurface *cm_surface = + wl_resource_get_user_data (resource); + + if (!cm_surface) + { + /* FIXME: the next version will have an ERROR_INERT */ + wl_resource_post_error (resource, + XX_COLOR_MANAGEMENT_SURFACE_V4_ERROR_IMAGE_DESCRIPTION, + "Underlying surface object has been destroyed"); + return; + } + + set_image_description (cm_surface, NULL); +} + +static const struct xx_color_management_surface_v4_interface + meta_wayland_color_management_surface_interface = +{ + color_management_surface_destroy, + color_management_surface_set_image_description, + color_management_surface_unset_image_description, +}; + +static void +on_output_destroyed (MetaWaylandOutput *wayland_output, + gpointer user_data) +{ + MetaWaylandColorManagementOutput *cm_output = user_data; + + meta_wayland_color_management_output_free (cm_output); +} + +static MetaWaylandColorManagementOutput * +meta_wayland_color_management_output_new (MetaWaylandColorManager *color_manager, + MetaWaylandOutput *output) +{ + MetaWaylandColorManagementOutput *cm_output; + + cm_output = g_new0 (MetaWaylandColorManagementOutput, 1); + cm_output->color_manager = color_manager; + cm_output->output = output; + + cm_output->output_destroyed_handler_id = + g_signal_connect (output, "output-destroyed", + G_CALLBACK (on_output_destroyed), + cm_output); + + g_hash_table_insert (color_manager->outputs, + meta_wayland_output_get_monitor (output), + cm_output); + + return cm_output; +} + +static void +meta_wayland_color_management_output_free (MetaWaylandColorManagementOutput *cm_output) +{ + GList *l; + + for (l = cm_output->resources; l; l = l->next) + { + struct wl_resource *resource = l->data; + + wl_resource_set_user_data (resource, NULL); + } + + g_clear_list (&cm_output->resources, NULL); + + g_clear_signal_handler (&cm_output->output_destroyed_handler_id, + cm_output->output); + + g_hash_table_remove (cm_output->color_manager->outputs, + meta_wayland_output_get_monitor (cm_output->output)); + + free (cm_output); +} + +static MetaWaylandColorManagementOutput * +ensure_color_management_output (MetaWaylandColorManager *color_manager, + MetaWaylandOutput *output) +{ + MetaWaylandColorManagementOutput *cm_output; + + cm_output = g_hash_table_lookup (color_manager->outputs, + meta_wayland_output_get_monitor (output)); + if (cm_output) + return cm_output; + + return meta_wayland_color_management_output_new (color_manager, output); +} + +static void +color_management_output_destructor (struct wl_resource *resource) +{ + MetaWaylandColorManagementOutput *cm_output = + wl_resource_get_user_data (resource); + + if (!cm_output) + return; + + cm_output->resources = g_list_remove (cm_output->resources, resource); +} + +static void +color_management_output_destroy (struct wl_client *client, + struct wl_resource *resource) +{ + wl_resource_destroy (resource); +} + +static void +color_management_output_get_image_description (struct wl_client *client, + struct wl_resource *resource, + uint32_t id) +{ + MetaWaylandColorManagementOutput *cm_output = + wl_resource_get_user_data (resource); + MetaWaylandCompositor *compositor = wl_client_get_user_data (client); + MetaWaylandColorManager *color_manager = + g_object_get_data (G_OBJECT (compositor), "-meta-wayland-color-manager"); + struct wl_resource *image_desc_resource; + MetaWaylandImageDescription *image_desc; + + image_desc_resource = + wl_resource_create (client, + &xx_image_description_v4_interface, + wl_resource_get_version (resource), + id); + + if (cm_output) + { + MetaMonitor *monitor = meta_wayland_output_get_monitor (cm_output->output); + ClutterColorState *color_state = + get_output_color_state (color_manager, monitor); + + image_desc = + meta_wayland_image_description_new_color_state (color_manager, + image_desc_resource, + color_state, + META_WAYLAND_IMAGE_DESCRIPTION_FLAGS_DEFAULT | + META_WAYLAND_IMAGE_DESCRIPTION_FLAGS_ALLOW_INFO); + } + else + { + image_desc = + meta_wayland_image_description_new_failed (color_manager, + image_desc_resource, + XX_IMAGE_DESCRIPTION_V4_CAUSE_NO_OUTPUT, + "Underlying output object has been destroyed"); + } + + wl_resource_set_implementation (image_desc_resource, + &meta_wayland_image_description_interface, + image_desc, + image_description_destructor); +} + +static const struct xx_color_management_output_v4_interface + meta_wayland_color_management_output_interface = +{ + color_management_output_destroy, + color_management_output_get_image_description, +}; + +static MetaWaylandCreatorParams * +meta_wayland_creator_params_new (MetaWaylandColorManager *color_manager, + struct wl_resource *resource) +{ + MetaWaylandCreatorParams *creator_params; + + creator_params = g_new0 (MetaWaylandCreatorParams, 1); + creator_params->color_manager = color_manager; + creator_params->resource = resource; + + creator_params->colorspace = CLUTTER_COLORSPACE_DEFAULT; + creator_params->transfer_function = CLUTTER_TRANSFER_FUNCTION_DEFAULT; + + return creator_params; +} + +static void +meta_wayland_creator_params_free (MetaWaylandCreatorParams *creator_params) +{ + free (creator_params); +} + +static void +creator_params_destructor (struct wl_resource *resource) +{ + MetaWaylandCreatorParams *creator_params = wl_resource_get_user_data (resource); + + meta_wayland_creator_params_free (creator_params); +} + +static void +creator_params_create (struct wl_client *client, + struct wl_resource *resource, + uint32_t id) +{ + MetaWaylandCreatorParams *creator_params = + wl_resource_get_user_data (resource); + MetaWaylandColorManager *color_manager = creator_params->color_manager; + ClutterContext *clutter_context = get_clutter_context (color_manager); + struct wl_resource *image_desc_resource; + g_autoptr (ClutterColorState) color_state = NULL; + MetaWaylandImageDescription *image_desc; + + if (creator_params->colorspace == CLUTTER_COLORSPACE_DEFAULT || + creator_params->transfer_function == CLUTTER_TRANSFER_FUNCTION_DEFAULT) + { + wl_resource_post_error (resource, + XX_IMAGE_DESCRIPTION_CREATOR_PARAMS_V4_ERROR_INCOMPLETE_SET, + "Not all required parameters were set"); + return; + } + + image_desc_resource = + wl_resource_create (client, + &xx_image_description_v4_interface, + wl_resource_get_version (resource), + id); + + color_state = clutter_color_state_new (clutter_context, + creator_params->colorspace, + creator_params->transfer_function); + + image_desc = + meta_wayland_image_description_new_color_state (color_manager, + image_desc_resource, + color_state, + META_WAYLAND_IMAGE_DESCRIPTION_FLAGS_DEFAULT); + + wl_resource_set_implementation (image_desc_resource, + &meta_wayland_image_description_interface, + image_desc, + image_description_destructor); + + wl_resource_destroy (resource); +} + +static void +creator_params_set_tf_named (struct wl_client *client, + struct wl_resource *resource, + uint32_t tf) +{ + MetaWaylandCreatorParams *creator_params = + wl_resource_get_user_data (resource); + ClutterTransferFunction clutter_tf; + + if (creator_params->transfer_function != CLUTTER_TRANSFER_FUNCTION_DEFAULT) + { + wl_resource_post_error (resource, + XX_IMAGE_DESCRIPTION_CREATOR_PARAMS_V4_ERROR_ALREADY_SET, + "The transfer characteristics were already set"); + return; + } + + if (!wayland_tf_to_clutter (tf, &clutter_tf)) + { + wl_resource_post_error (resource, + XX_IMAGE_DESCRIPTION_CREATOR_PARAMS_V4_ERROR_INVALID_TF, + "The named transfer function is not supported"); + return; + } + + creator_params->transfer_function = clutter_tf; +} + +static void +creator_params_set_tf_power (struct wl_client *client, + struct wl_resource *resource, + uint32_t eexp) +{ + wl_resource_post_error (resource, + XX_IMAGE_DESCRIPTION_CREATOR_PARAMS_V4_ERROR_INVALID_TF, + "Setting power based transfer characteristics is not supported"); +} + +static void +creator_params_set_primaries_named (struct wl_client *client, + struct wl_resource *resource, + uint32_t primaries) +{ + MetaWaylandCreatorParams *creator_params = + wl_resource_get_user_data (resource); + ClutterColorspace colorspace; + + if (creator_params->colorspace != CLUTTER_COLORSPACE_DEFAULT) + { + wl_resource_post_error (resource, + XX_IMAGE_DESCRIPTION_CREATOR_PARAMS_V4_ERROR_ALREADY_SET, + "The primaries were already set"); + return; + } + + if (!wayland_primaries_to_clutter (primaries, &colorspace)) + { + wl_resource_post_error (resource, + XX_IMAGE_DESCRIPTION_CREATOR_PARAMS_V4_ERROR_INVALID_PRIMARIES, + "The named primaries are not supported"); + return; + } + + creator_params->colorspace = colorspace; +} + +static void +creator_params_set_primaries (struct wl_client *client, + struct wl_resource *resource, + int32_t r_x, + int32_t r_y, + int32_t g_x, + int32_t g_y, + int32_t b_x, + int32_t b_y, + int32_t w_x, + int32_t w_y) +{ + wl_resource_post_error (resource, + XX_IMAGE_DESCRIPTION_CREATOR_PARAMS_V4_ERROR_INVALID_PRIMARIES, + "Setting arbitrary primaries is not supported"); +} + +static void +creator_params_set_luminance (struct wl_client *client, + struct wl_resource *resource, + uint32_t min_lum, + uint32_t max_lum, + uint32_t reference_lum) +{ + wl_resource_post_error (resource, + XX_IMAGE_DESCRIPTION_CREATOR_PARAMS_V4_ERROR_INVALID_LUMINANCE, + "Setting luminance is not supported"); +} + +static void +creator_params_set_mastering_display_primaries (struct wl_client *client, + struct wl_resource *resource, + int32_t r_x, + int32_t r_y, + int32_t g_x, + int32_t g_y, + int32_t b_x, + int32_t b_y, + int32_t w_x, + int32_t w_y) +{ + wl_resource_post_error (resource, + XX_IMAGE_DESCRIPTION_CREATOR_PARAMS_V4_ERROR_INVALID_MASTERING, + "Setting mastering display primaries is not supported"); +} + +static void +creator_params_set_mastering_luminance (struct wl_client *client, + struct wl_resource *resource, + uint32_t min_lum, + uint32_t max_lum) +{ + wl_resource_post_error (resource, + XX_IMAGE_DESCRIPTION_CREATOR_PARAMS_V4_ERROR_INVALID_MASTERING, + "Setting mastering display luminances is not supported"); +} + +static void +creator_params_set_max_cll (struct wl_client *client, + struct wl_resource *resource, + uint32_t max_cll) +{ + /* ignoring for now */ + /* FIXME: technically we must send errors in some cases */ +} + +static void +creator_params_set_max_fall (struct wl_client *client, + struct wl_resource *resource, + uint32_t max_fall) +{ + /* ignoring for now */ + /* FIXME: technically we must send errors in some cases */ +} + +static const struct xx_image_description_creator_params_v4_interface + meta_wayland_image_description_creator_params_interface = +{ + creator_params_create, + creator_params_set_tf_named, + creator_params_set_tf_power, + creator_params_set_primaries_named, + creator_params_set_primaries, + creator_params_set_luminance, + creator_params_set_mastering_display_primaries, + creator_params_set_mastering_luminance, + creator_params_set_max_cll, + creator_params_set_max_fall, +}; + +static void +color_manager_destructor (struct wl_resource *resource) +{ + MetaWaylandColorManager *color_manager = wl_resource_get_user_data (resource); + + color_manager->resources = g_list_remove (color_manager->resources, resource); +} + +static void +color_manager_destroy (struct wl_client *client, + struct wl_resource *resource) +{ + wl_resource_destroy (resource); +} + +static void +color_manager_get_output (struct wl_client *client, + struct wl_resource *resource, + uint32_t id, + struct wl_resource *output_resource) +{ + MetaWaylandColorManager *color_manager = wl_resource_get_user_data (resource); + MetaWaylandOutput *output = wl_resource_get_user_data (output_resource); + MetaWaylandColorManagementOutput *cm_output = NULL; + struct wl_resource *cm_output_resource; + + cm_output_resource = + wl_resource_create (client, + &xx_color_management_output_v4_interface, + wl_resource_get_version (resource), + id); + + if (output) + { + cm_output = ensure_color_management_output (color_manager, output); + + cm_output->resources = g_list_prepend (cm_output->resources, + cm_output_resource); + } + + wl_resource_set_implementation (cm_output_resource, + &meta_wayland_color_management_output_interface, + cm_output, + color_management_output_destructor); +} + +static void +color_manager_get_surface (struct wl_client *client, + struct wl_resource *resource, + uint32_t id, + struct wl_resource *surface_resource) +{ + MetaWaylandColorManager *color_manager = wl_resource_get_user_data (resource); + MetaWaylandSurface *surface = wl_resource_get_user_data (surface_resource); + MetaWaylandColorManagementSurface *cm_surface; + + cm_surface = ensure_color_management_surface (color_manager, surface); + + if (cm_surface->resource) + { + wl_resource_post_error (resource, + XX_COLOR_MANAGER_V4_ERROR_SURFACE_EXISTS, + "surface already requested"); + return; + } + + cm_surface->resource = + wl_resource_create (client, + &xx_color_management_surface_v4_interface, + wl_resource_get_version (resource), + id); + + wl_resource_set_implementation (cm_surface->resource, + &meta_wayland_color_management_surface_interface, + cm_surface, + color_management_surface_destructor); +} + +static void +color_management_feedback_surface_destroy (struct wl_client *client, + struct wl_resource *resource) +{ + wl_resource_destroy (resource); +} + +static void +color_management_feedback_surface_get_preferred (struct wl_client *client, + struct wl_resource *resource, + uint32_t id) +{ + MetaWaylandColorManagementSurface *cm_surface = + wl_resource_get_user_data (resource); + MetaWaylandColorManager *color_manager = cm_surface->color_manager; + MetaWaylandSurface *surface = cm_surface->surface; + struct wl_resource *image_desc_resource; + MetaWaylandImageDescription *image_desc; + + if (!surface) + { + wl_resource_post_error (resource, + XX_COLOR_MANAGEMENT_FEEDBACK_SURFACE_V4_ERROR_INERT, + "Underlying surface object has been destroyed"); + return; + } + + image_desc_resource = + wl_resource_create (client, + &xx_image_description_v4_interface, + wl_resource_get_version (resource), + id); + + image_desc = + meta_wayland_image_description_new_color_state (color_manager, + image_desc_resource, + cm_surface->preferred_color_state, + META_WAYLAND_IMAGE_DESCRIPTION_FLAGS_DEFAULT | + META_WAYLAND_IMAGE_DESCRIPTION_FLAGS_ALLOW_INFO); + + wl_resource_set_implementation (image_desc_resource, + &meta_wayland_image_description_interface, + image_desc, + image_description_destructor); +} + +static const struct xx_color_management_feedback_surface_v4_interface + meta_wayland_color_management_feedback_surface_interface = +{ + color_management_feedback_surface_destroy, + color_management_feedback_surface_get_preferred, +}; + +static void +color_management_feedback_surface_destructor (struct wl_resource *resource) +{ + MetaWaylandColorManagementSurface *cm_surface = + wl_resource_get_user_data (resource); + + cm_surface->feedback_resources = + g_list_remove (cm_surface->feedback_resources, resource); +} + +static void +color_manager_get_feedback_surface (struct wl_client *client, + struct wl_resource *resource, + uint32_t id, + struct wl_resource *surface_resource) +{ + MetaWaylandColorManager *color_manager = wl_resource_get_user_data (resource); + MetaWaylandSurface *surface = wl_resource_get_user_data (surface_resource); + MetaWaylandColorManagementSurface *cm_surface; + struct wl_resource *cm_feedback_surface_resource; + + cm_surface = ensure_color_management_surface (color_manager, surface); + + cm_feedback_surface_resource = + wl_resource_create (client, + &xx_color_management_feedback_surface_v4_interface, + wl_resource_get_version (resource), + id); + + wl_resource_set_implementation (cm_feedback_surface_resource, + &meta_wayland_color_management_feedback_surface_interface, + cm_surface, + color_management_feedback_surface_destructor); + + cm_surface->feedback_resources = + g_list_prepend (cm_surface->feedback_resources, + cm_feedback_surface_resource); + + update_preferred_color_state (cm_surface); +} + +static void +color_manager_new_icc_creator (struct wl_client *client, + struct wl_resource *resource, + uint32_t id) +{ + wl_resource_post_error (resource, + XX_COLOR_MANAGER_V4_ERROR_UNSUPPORTED_FEATURE, + "ICC-based image description creator is unsupported"); +} + +static void +color_manager_new_parametric_creator (struct wl_client *client, + struct wl_resource *resource, + uint32_t id) +{ + MetaWaylandColorManager *color_manager = wl_resource_get_user_data (resource); + MetaWaylandCreatorParams *creator_params; + struct wl_resource *creator_resource; + + creator_resource = + wl_resource_create (client, + &xx_image_description_creator_params_v4_interface, + wl_resource_get_version (resource), + id); + + creator_params = meta_wayland_creator_params_new (color_manager, + creator_resource); + + wl_resource_set_implementation (creator_resource, + &meta_wayland_image_description_creator_params_interface, + creator_params, + creator_params_destructor); +} + +static void +color_manager_send_supported_events (struct wl_resource *resource) +{ + xx_color_manager_v4_send_supported_intent (resource, + XX_COLOR_MANAGER_V4_RENDER_INTENT_PERCEPTUAL); + xx_color_manager_v4_send_supported_feature (resource, + XX_COLOR_MANAGER_V4_FEATURE_PARAMETRIC); + xx_color_manager_v4_send_supported_tf_named (resource, + XX_COLOR_MANAGER_V4_TRANSFER_FUNCTION_SRGB); + xx_color_manager_v4_send_supported_tf_named (resource, + XX_COLOR_MANAGER_V4_TRANSFER_FUNCTION_ST2084_PQ); + xx_color_manager_v4_send_supported_primaries_named (resource, + XX_COLOR_MANAGER_V4_PRIMARIES_SRGB); + xx_color_manager_v4_send_supported_primaries_named (resource, + XX_COLOR_MANAGER_V4_PRIMARIES_BT2020); +} + +static const struct xx_color_manager_v4_interface + meta_wayland_color_manager_interface = +{ + color_manager_destroy, + color_manager_get_output, + color_manager_get_surface, + color_manager_get_feedback_surface, + color_manager_new_icc_creator, + color_manager_new_parametric_creator, +}; + +static void +color_management_bind (struct wl_client *client, + void *data, + uint32_t version, + uint32_t id) +{ + MetaWaylandColorManager *color_manager = data; + struct wl_resource *resource; + + resource = wl_resource_create (client, + &xx_color_manager_v4_interface, + version, + id); + + wl_resource_set_implementation (resource, + &meta_wayland_color_manager_interface, + color_manager, + color_manager_destructor); + + color_manager->resources = g_list_prepend (color_manager->resources, + resource); + + color_manager_send_supported_events (resource); +} + +static void +update_output_color_state (MetaWaylandColorManager *color_manager, + MetaMonitor *monitor) +{ + MetaWaylandColorManagementOutput *cm_output; + GHashTableIter iter_surfaces; + MetaWaylandColorManagementSurface *cm_surface; + MetaWaylandOutput *wayland_output; + + cm_output = g_hash_table_lookup (color_manager->outputs, monitor); + + if (cm_output) + { + GList *l; + + for (l = cm_output->resources; l; l = l->next) + { + struct wl_resource *resource = l->data; + + xx_color_management_output_v4_send_image_description_changed (resource); + } + } + + wayland_output = g_hash_table_lookup (color_manager->compositor->outputs, + meta_monitor_get_spec (monitor)); + + g_hash_table_iter_init (&iter_surfaces, color_manager->surfaces); + while (g_hash_table_iter_next (&iter_surfaces, NULL, (gpointer *)&cm_surface)) + { + MetaWaylandSurface *surface = cm_surface->surface; + + if (g_hash_table_contains (surface->outputs, wayland_output)) + update_preferred_color_state (cm_surface); + } +} + +static void +on_device_color_state_changed (MetaColorManager *meta_color_manager, + MetaColorDevice *color_device, + MetaWaylandColorManager *color_manager) +{ + MetaMonitor *monitor = meta_color_device_get_monitor (color_device); + + update_output_color_state (color_manager, monitor); +} + +static void +meta_wayland_color_manager_dispose (GObject *object) +{ + MetaWaylandColorManager *color_manager = META_WAYLAND_COLOR_MANAGER (object); + MetaColorManager *meta_color_manager = get_meta_color_manager (color_manager); + + g_clear_signal_handler (&color_manager->color_state_changed_handler_id, + meta_color_manager); + + g_clear_pointer (&color_manager->outputs, g_hash_table_destroy); + g_clear_pointer (&color_manager->surfaces, g_hash_table_destroy); + + g_clear_pointer (&color_manager->global, wl_global_remove); +} + +static void +meta_wayland_color_manager_init (MetaWaylandColorManager *color_manager) +{ + color_manager->outputs = g_hash_table_new (NULL, NULL); + color_manager->surfaces = g_hash_table_new (NULL, NULL); +} + +static void +meta_wayland_color_manager_class_init (MetaWaylandColorManagerClass *klass) +{ + GObjectClass *object_class = G_OBJECT_CLASS (klass); + + object_class->dispose = meta_wayland_color_manager_dispose; +} + +static MetaWaylandColorManager * +meta_wayland_color_manager_new (MetaWaylandCompositor *compositor) +{ + MetaWaylandColorManager *color_manager; + MetaColorManager *meta_color_manager; + + color_manager = g_object_new (META_TYPE_WAYLAND_COLOR_MANAGER, NULL); + color_manager->compositor = compositor; + + meta_color_manager = get_meta_color_manager (color_manager); + color_manager->color_state_changed_handler_id = + g_signal_connect_object (meta_color_manager, "device-color-state-changed", + G_CALLBACK (on_device_color_state_changed), + color_manager, 0); + + return color_manager; +} + +static void +update_enabled (MetaWaylandColorManager *color_manager) +{ + MetaWaylandCompositor *compositor = color_manager->compositor; + MetaDebugControl *debug_control = + meta_context_get_debug_control (compositor->context); + gboolean is_enabled = + meta_debug_control_is_color_management_protocol_enabled (debug_control); + + if (is_enabled && color_manager->global == NULL) + { + color_manager->global = + wl_global_create (compositor->wayland_display, + &xx_color_manager_v4_interface, + META_XX_COLOR_MANAGEMENT_VERSION, + color_manager, + color_management_bind); + + if (color_manager->global == NULL) + g_error ("Failed to register a global wp_color_management object"); + } + else if (!is_enabled) + { + g_clear_pointer (&color_manager->global, wl_global_destroy); + } +} + +void +meta_wayland_init_color_management (MetaWaylandCompositor *compositor) +{ + MetaDebugControl *debug_control = + meta_context_get_debug_control (compositor->context); + g_autoptr (MetaWaylandColorManager) color_manager = NULL; + + color_manager = meta_wayland_color_manager_new (compositor); + + g_signal_connect_data (debug_control, "notify::color-management-protocol", + G_CALLBACK (update_enabled), + color_manager, NULL, + G_CONNECT_SWAPPED | G_CONNECT_AFTER); + + update_enabled (color_manager); + + g_object_set_data_full (G_OBJECT (compositor), "-meta-wayland-color-manager", + g_steal_pointer (&color_manager), + g_object_unref); +} diff --git a/src/wayland/meta-wayland-color-management.h b/src/wayland/meta-wayland-color-management.h new file mode 100644 index 000000000..07cbbf2ff --- /dev/null +++ b/src/wayland/meta-wayland-color-management.h @@ -0,0 +1,25 @@ +/* + * Copyright (C) 2024 SUSE Software Solutions Germany GmbH + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License as + * published by the Free Software Foundation; either version 2 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, see . + * + * Written by: + * Joan Torres + */ + +#pragma once + +#include "wayland/meta-wayland-types.h" + +void meta_wayland_init_color_management (MetaWaylandCompositor *compositor); diff --git a/src/wayland/meta-wayland-versions.h b/src/wayland/meta-wayland-versions.h index 1f8376236..897bd3cc3 100644 --- a/src/wayland/meta-wayland-versions.h +++ b/src/wayland/meta-wayland-versions.h @@ -57,5 +57,6 @@ #define META_WP_SINGLE_PIXEL_BUFFER_V1_VERSION 1 #define META_MUTTER_X11_INTEROP_VERSION 1 #define META_WP_FRACTIONAL_SCALE_VERSION 1 +#define META_XX_COLOR_MANAGEMENT_VERSION 1 #define META_XDG_DIALOG_VERSION 1 #define META_WP_DRM_LEASE_DEVICE_V1_VERSION 1 diff --git a/src/wayland/meta-wayland.c b/src/wayland/meta-wayland.c index a0d390fdc..d38efd178 100644 --- a/src/wayland/meta-wayland.c +++ b/src/wayland/meta-wayland.c @@ -39,6 +39,7 @@ #include "core/meta-context-private.h" #include "wayland/meta-wayland-activation.h" #include "wayland/meta-wayland-buffer.h" +#include "wayland/meta-wayland-color-management.h" #include "wayland/meta-wayland-data-device.h" #include "wayland/meta-wayland-dma-buf.h" #include "wayland/meta-wayland-egl-stream.h" @@ -890,6 +891,7 @@ meta_wayland_compositor_new (MetaContext *context) meta_wayland_idle_inhibit_init (compositor); meta_wayland_drm_syncobj_init (compositor); meta_wayland_init_xdg_wm_dialog (compositor); + meta_wayland_init_color_management (compositor); #ifdef HAVE_NATIVE_BACKEND meta_wayland_drm_lease_manager_init (compositor); diff --git a/src/wayland/protocol/color-management-v1.xml b/src/wayland/protocol/color-management-v1.xml new file mode 100644 index 000000000..17f217cee --- /dev/null +++ b/src/wayland/protocol/color-management-v1.xml @@ -0,0 +1,1453 @@ + + + + Copyright 2019 Sebastian Wick + Copyright 2019 Erwin Burema + Copyright 2020 AMD + Copyright 2020-2024 Collabora, Ltd. + Copyright 2024 Xaver Hugl + + 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. + + + + The aim of the color management extension is to allow clients to know + the color properties of outputs, and to tell the compositor about the color + properties of their content on surfaces. Doing this enables a compositor + to perform automatic color management of content for different outputs + according to how content is intended to look like. + + The color properties are represented as an image description object which + is immutable after it has been created. A wl_output always has an + associated image description that clients can observe. A wl_surface + always has an associated preferred image description as a hint chosen by + the compositor that clients can also observe. Clients can set an image + description on a wl_surface to denote the color characteristics of the + surface contents. + + An image description includes SDR and HDR colorimetry and encoding, HDR + metadata, and viewing environment parameters. An image description does + not include the properties set through color-representation extension. + It is expected that the color-representation extension is used in + conjunction with the color management extension when necessary, + particularly with the YUV family of pixel formats. + + Recommendation ITU-T H.273 + "Coding-independent code points for video signal type identification" + shall be referred to as simply H.273 here. + + The color-and-hdr repository + (https://gitlab.freedesktop.org/pq/color-and-hdr) contains + background information on the protocol design and legacy color management. + It also contains a glossary, learning resources for digital color, tools, + samples and more. + + The terminology used in this protocol is based on common color science and + color encoding terminology where possible. The glossary in the color-and-hdr + repository shall be the authority on the definition of terms in this + protocol. + + + + + A global interface used for getting color management extensions for + wl_surface and wl_output objects, and for creating client defined image + description objects. The extension interfaces allow + getting the image description of outputs and setting the image + description of surfaces. + + + + + Destroy the xx_color_manager_v4 object. This does not affect any other + objects in any way. + + + + + + + + + + + See the ICC.1:2022 specification from the International Color Consortium + for more details about rendering intents. + + The principles of ICC defined rendering intents apply with all types of + image descriptions, not only those with ICC file profiles. + + Compositors must support the perceptual rendering intent. Other + rendering intents are optional. + + + + + + + + + + + + + + + + + + + + The compositor supports set_mastering_display_primaries request with a + target color volume fully contained inside the primary color volume. + + + + + The compositor additionally supports target color volumes that + extend outside of the primary color volume. + + This can only be advertised if feature set_mastering_display_primaries + is supported as well. + + + + + + + Named color primaries used to encode well-known sets of primaries. H.273 + is the authority, when it comes to the exact values of primaries and + authoritative specifications, where an equivalent code point exists. + + Descriptions do list the specifications for convenience. + + + + + Color primaries as defined by + - Rec. ITU-R BT.709-6 + - Rec. ITU-R BT.1361-0 conventional colour gamut system and extended + colour gamut system (historical) + - IEC 61966-2-1 sRGB or sYCC + - IEC 61966-2-4 + - Society of Motion Picture and Television Engineers (SMPTE) RP 177 + (1993) Annex B + Equivalent to H.273 ColourPrimaries code point 1. + + + + + Color primaries as defined by + - Rec. ITU-R BT.470-6 System M (historical) + - United States National Television System Committee 1953 + Recommendation for transmission standards for color television + - United States Federal Communications Commission (2003) Title 47 Code + of Federal Regulations 73.682 (a)(20) + Equivalent to H.273 ColourPrimaries code point 4. + + + + + Color primaries as defined by + - Rec. ITU-R BT.470-6 System B, G (historical) + - Rec. ITU-R BT.601-7 625 + - Rec. ITU-R BT.1358-0 625 (historical) + - Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM + Equivalent to H.273 ColourPrimaries code point 5. + + + + + Color primaries as defined by + - Rec. ITU-R BT.601-7 525 + - Rec. ITU-R BT.1358-1 525 or 625 (historical) + - Rec. ITU-R BT.1700-0 NTSC + - SMPTE 170M (2004) + - SMPTE 240M (1999) (historical) + Equivalent to H.273 ColourPrimaries code point 6 and 7. + + + + + Color primaries as defined by H.273 for generic film. + Equivalent to H.273 ColourPrimaries code point 8. + + + + + Color primaries as defined by + - Rec. ITU-R BT.2020-2 + - Rec. ITU-R BT.2100-0 + Equivalent to H.273 ColourPrimaries code point 9. + + + + + Color primaries as defined as the maximum of the CIE 1931 XYZ color + space by + - SMPTE ST 428-1 + - (CIE 1931 XYZ as in ISO 11664-1) + Equivalent to H.273 ColourPrimaries code point 10. + + + + + Color primaries as defined by Digital Cinema System and published in + SMPTE RP 431-2 (2011). Equivalent to H.273 ColourPrimaries code point + 11. + + + + + Color primaries as defined by Digital Cinema System and published in + SMPTE EG 432-1 (2010). + Equivalent to H.273 ColourPrimaries code point 12. + + + + + Color primaries as defined by Adobe as "Adobe RGB" and later published + by ISO 12640-4 (2011). + + + + + + + Named transfer functions used to encode well-known transfer + characteristics. H.273 is the authority, when it comes to the exact + formulas and authoritative specifications, where an equivalent code + point exists. + + Descriptions do list the specifications for convenience. + + + + + Transfer characteristics as defined by + - Rec. ITU-R BT.709-6 + - Rec. ITU-R BT.1361-0 conventional colour gamut system (historical) + Equivalent to H.273 TransferCharacteristics code point 1, 6, 14, 15. + + + + + Transfer characteristics as defined by + - Rec. ITU-R BT.470-6 System M (historical) + - United States National Television System Committee 1953 + Recommendation for transmission standards for color television + - United States Federal Communications Commission (2003) Title 47 Code + of Federal Regulations 73.682 (a) (20) + - Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM + Equivalent to H.273 TransferCharacteristics code point 4. + + + + + Transfer characteristics as defined by + - Rec. ITU-R BT.470-6 System B, G (historical) + Equivalent to H.273 TransferCharacteristics code point 5. + + + + + Transfer characteristics as defined by + - SMPTE ST 240 (1999) + Equivalent to H.273 TransferCharacteristics code point 7. + + + + + Linear transfer characteristics. + Equivalent to H.273 TransferCharacteristics code point 8. + + + + + Logarithmic transfer characteristic (100:1 range). + Equivalent to H.273 TransferCharacteristics code point 9. + + + + + Logarithmic transfer characteristic (100 * Sqrt(10) : 1 range). + Equivalent to H.273 TransferCharacteristics code point 10. + + + + + Transfer characteristics as defined by + - IEC 61966-2-4 + Equivalent to H.273 TransferCharacteristics code point 11. + + + + + Transfer characteristics as defined by + - Rec. ITU-R BT.1361-0 extended colour gamut system (historical) + Equivalent to H.273 TransferCharacteristics code point 12. + + + + + Transfer characteristics as defined by + - IEC 61966-2-1 sRGB + Equivalent to H.273 TransferCharacteristics code point 13 with + MatrixCoefficients set to 0. + + + + + Transfer characteristics as defined by + - IEC 61966-2-1 sYCC + Equivalent to H.273 TransferCharacteristics code point 13 with + MatrixCoefficients set to anything but 0. + + + + + Transfer characteristics as defined by + - SMPTE ST 2084 (2014) for 10-, 12-, 14- and 16-bit systems + - Rec. ITU-R BT.2100-2 perceptual quantization (PQ) system + Equivalent to H.273 TransferCharacteristics code point 16. + + This TF implies these default luminances + - primary color volume minimum: 0.005 cd/m² + - primary color volume maximum: 10000 cd/m² + - reference white: 203 cd/m² + + + + + Transfer characteristics as defined by + - SMPTE ST 428-1 (2019) + Equivalent to H.273 TransferCharacteristics code point 17. + + + + + Transfer characteristics as defined by + - ARIB STD-B67 (2015) + - Rec. ITU-R BT.2100-2 hybrid log-gamma (HLG) system + Equivalent to H.273 TransferCharacteristics code point 18. + + This TF implies these default luminances + - primary color volume minimum: 0.005 cd/m² + - primary color volume maximum: 1000 cd/m² + - reference white: 203 cd/m² + Note: HLG is a scene referred signal. All absolute luminance values + used here for HLG assume a 1000 cd/m² display. + + + + + + + This creates a new xx_color_management_output_v4 object for the + given wl_output. + + See the xx_color_management_output_v4 interface for more details. + + + + + + + + + If a xx_color_management_surface_v4 object already exists for the given + wl_surface, the protocol error surface_exists is raised. + + This creates a new color xx_color_management_surface_v4 object for the + given wl_surface. + + See the xx_color_management_surface_v4 interface for more details. + + + + + + + + + This creates a new color xx_color_management_feedback_surface_v4 object + for the given wl_surface. + + See the xx_color_management_feedback_surface_v4 interface for more + details. + + + + + + + + + Makes a new ICC-based image description creator object with all + properties initially unset. The client can then use the object's + interface to define all the required properties for an image description + and finally create a xx_image_description_v4 object. + + This request can be used when the compositor advertises + xx_color_manager_v4.feature.icc_v2_v4. + Otherwise this request raises the protocol error unsupported_feature. + + + + + + + + Makes a new parametric image description creator object with all + properties initially unset. The client can then use the object's + interface to define all the required properties for an image description + and finally create a xx_image_description_v4 object. + + This request can be used when the compositor advertises + xx_color_manager_v4.feature.parametric. + Otherwise this request raises the protocol error unsupported_feature. + + + + + + + + When this object is created, it shall immediately send this event once + for each rendering intent the compositor supports. + + + + + + + + When this object is created, it shall immediately send this event once + for each compositor supported feature listed in the enumeration. + + + + + + + + When this object is created, it shall immediately send this event once + for each named transfer function the compositor supports with the + parametric image description creator. + + + + + + + + When this object is created, it shall immediately send this event once + for each named set of primaries the compositor supports with the + parametric image description creator. + + + + + + + + + A xx_color_management_output_v4 describes the color properties of an + output. + + The xx_color_management_output_v4 is associated with the wl_output global + underlying the wl_output object. Therefore the client destroying the + wl_output object has no impact, but the compositor removing the output + global makes the xx_color_management_output_v4 object inert. + + + + + Destroy the color xx_color_management_output_v4 object. This does not + affect any remaining protocol objects. + + + + + + This event is sent whenever the image description of the output changed, + followed by one wl_output.done event common to output events across all + extensions. + + If the client wants to use the updated image description, it needs to do + get_image_description again, because image description objects are + immutable. + + + + + + This creates a new xx_image_description_v4 object for the current image + description of the output. There always is exactly one image description + active for an output so the client should destroy the image description + created by earlier invocations of this request. This request is usually + sent as a reaction to the image_description_changed event or when + creating a xx_color_management_output_v4 object. + + The image description of an output represents the color encoding the + output expects. There might be performance and power advantages, as well + as improved color reproduction, if a content update matches the image + description of the output it is being shown on. If a content update is + shown on any other output than the one it matches the image description + of, then the color reproduction on those outputs might be considerably + worse. + + The created xx_image_description_v4 object preserves the image + description of the output from the time the object was created. + + The resulting image description object allows get_information request. + + If this protocol object is inert, the resulting image description object + shall immediately deliver the xx_image_description_v4.failed event with + the no_output cause. + + If the interface version is inadequate for the output's image + description, meaning that the client does not support all the events + needed to deliver the crucial information, the resulting image + description object shall immediately deliver the + xx_image_description_v4.failed event with the low_version cause. + + Otherwise the object shall immediately deliver the ready event. + + + + + + + + + A xx_color_management_surface_v4 allows the client to set the color + space and HDR properties of a surface. + + If the wl_surface associated with the xx_color_management_surface_v4 is + destroyed, the xx_color_management_surface_v4 object becomes inert. + + + + + Destroy the xx_color_management_surface_v4 object and do the same as + unset_image_description. + + + + + + + + + + + + Set the image description of the underlying surface. The image + description and rendering intent are double-buffered state, see + wl_surface.commit. + + It is the client's responsibility to understand the image description + it sets on a surface, and to provide content that matches that image + description. Compositors might convert images to match their own or any + other image descriptions. + + Image description whose creation gracefully failed (received + xx_image_description_v4.failed) are forbidden in this request, and in + such case the protocol error image_description is raised. + + All image descriptions whose creation succeeded (received + xx_image_description_v4.ready) are allowed and must always be accepted + by the compositor. + + A rendering intent provides the client's preference on how content + colors should be mapped to each output. The render_intent value must + be one advertised by the compositor with + xx_color_manager_v4.render_intent event, otherwise the protocol error + render_intent is raised. + + By default, a surface does not have an associated image description + nor a rendering intent. The handling of color on such surfaces is + compositor implementation defined. Compositors should handle such + surfaces as sRGB but may handle them differently if they have specific + requirements. + + + + + + + + + This request removes any image description from the surface. See + set_image_description for how a compositor handles a surface without + an image description. This is double-buffered state, see + wl_surface.commit. + + + + + + + A xx_color_management_feedback_surface_v4 allows the client to get the + preferred color description of a surface. + + If the wl_surface associated with this object is destroyed, the + xx_color_management_feedback_surface_v4 object becomes inert. + + + + + Destroy the xx_color_management_feedback_surface_v4 object. + + + + + + + + + + + The preferred image description is the one which likely has the most + performance and/or quality benefits for the compositor if used by the + client for its wl_surface contents. This event is sent whenever the + compositor changes the wl_surface's preferred image description. + + This event is merely a notification. When the client wants to know + what the preferred image description is, it shall use the get_preferred + request. + + The preferred image description is not automatically used for anything. + It is only a hint, and clients may set any valid image description with + set_image_description but there might be performance and color accuracy + improvements by providing the wl_surface contents in the preferred + image description. Therefore clients that can, should render according + to the preferred image description + + + + + + If this protocol object is inert, the protocol error inert is raised. + + The preferred image description represents the compositor's preferred + color encoding for this wl_surface at the current time. There might be + performance and power advantages, as well as improved color + reproduction, if the image description of a content update matches the + preferred image description. + + This creates a new xx_image_description_v4 object for the currently + preferred image description for the wl_surface. The client should + stop using and destroy the image descriptions created by earlier + invocations of this request for the associated wl_surface. + This request is usually sent as a reaction to the preferred_changed + event or when creating a xx_color_management_feedback_surface_v4 object + if the client is capable of adapting to image descriptions. + + The created xx_image_description_v4 object preserves the preferred image + description of the wl_surface from the time the object was created. + + The resulting image description object allows get_information request. + + If the interface version is inadequate for the preferred image + description, meaning that the client does not support all the + events needed to deliver the crucial information, the resulting image + description object shall immediately deliver the + xx_image_description_v4.failed event with the low_version cause, + otherwise the object shall immediately deliver the ready event. + + + + + + + + + This type of object is used for collecting all the information required + to create a xx_image_description_v4 object from an ICC file. A complete + set of required parameters consists of these properties: + - ICC file + + Each required property must be set exactly once if the client is to create + an image description. The set requests verify that a property was not + already set. The create request verifies that all required properties are + set. There may be several alternative requests for setting each property, + and in that case the client must choose one of them. + + Once all properties have been set, the create request must be used to + create the image description object, destroying the creator in the + process. + + + + + + + + + + + + + + + Create an image description object based on the ICC information + previously set on this object. A compositor must parse the ICC data in + some undefined but finite amount of time. + + The completeness of the parameter set is verified. If the set is not + complete, the protocol error incomplete_set is raised. For the + definition of a complete set, see the description of this interface. + + If the particular combination of the information is not supported + by the compositor, the resulting image description object shall + immediately deliver the xx_image_description_v4.failed event with the + 'unsupported' cause. If a valid image description was created from the + information, the xx_image_description_v4.ready event will eventually + be sent instead. + + This request destroys the xx_image_description_creator_icc_v4 object. + + The resulting image description object does not allow get_information + request. + + + + + + + + Sets the ICC profile file to be used as the basis of the image + description. + + The data shall be found through the given fd at the given offset, having + the given length. The fd must seekable and readable. Violating these + requirements raises the bad_fd protocol error. + + If reading the data fails due to an error independent of the client, the + compositor shall send the xx_image_description_v4.failed event on the + created xx_image_description_v4 with the 'operating_system' cause. + + The maximum size of the ICC profile is 4 MB. If length is greater than + that or zero, the protocol error bad_size is raised. If offset + length + exceeds the file size, the protocol error out_of_file is raised. + + A compositor may read the file at any time starting from this request + and only until whichever happens first: + - If create request was issued, the xx_image_description_v4 object + delivers either failed or ready event; or + - if create request was not issued, this + xx_image_description_creator_icc_v4 object is destroyed. + + A compositor shall not modify the contents of the file, and the fd may + be sealed for writes and size changes. The client must ensure to its + best ability that the data does not change while the compositor is + reading it. + + The data must represent a valid ICC profile. The ICC profile version + must be 2 or 4, it must be a 3 channel profile and the class must be + Display or ColorSpace. Violating these requirements will not result in a + protocol error but will eventually send the + xx_image_description_v4.failed event on the created + xx_image_description_v4 with the 'unsupported' cause. + + See the International Color Consortium specification ICC.1:2022 for more + details about ICC profiles. + + If ICC file has already been set on this object, the protocol error + already_set is raised. + + + + + + + + + + + This type of object is used for collecting all the parameters required + to create a xx_image_description_v4 object. A complete set of required + parameters consists of these properties: + - transfer characteristic function (tf) + - chromaticities of primaries and white point (primary color volume) + + The following properties are optional and have a well-defined default + if not explicitly set: + - primary color volume luminance range + - reference white luminance level + - mastering display primaries and white point (target color volume) + - mastering luminance range + - maximum content light level + - maximum frame-average light level + + Each required property must be set exactly once if the client is to create + an image description. The set requests verify that a property was not + already set. The create request verifies that all required properties are + set. There may be several alternative requests for setting each property, + and in that case the client must choose one of them. + + Once all properties have been set, the create request must be used to + create the image description object, destroying the creator in the + process. + + + + + + + + + + + + + + + + + + Create an image description object based on the parameters previously + set on this object. + + The completeness of the parameter set is verified. If the set is not + complete, the protocol error incomplete_set is raised. For the + definition of a complete set, see the description of this interface. + + Also, the combination of the parameter set is verified. If the set is + not consistent, the protocol error inconsistent_set is raised. + + If the particular combination of the parameter set is not supported + by the compositor, the resulting image description object shall + immediately deliver the xx_image_description_v4.failed event with the + 'unsupported' cause. If a valid image description was created from the + parameter set, the xx_image_description_v4.ready event will eventually + be sent instead. + + This request destroys the xx_image_description_creator_params_v4 + object. + + The resulting image description object does not allow get_information + request. + + + + + + + + Sets the transfer characteristic using explicitly enumerated named + functions. + + When the resulting image description is attached to an image, the + content should be encoded and decoded according to the industry standard + practices for the transfer characteristic. + + Only names advertised with xx_color_manager_v4 event supported_tf_named + are allowed. Other values shall raise the protocol error invalid_tf. + + If transfer characteristic has already been set on this object, the + protocol error already_set is raised. + + + + + + + + Sets the color component transfer characteristic to a power curve with + the given exponent. This curve represents the conversion from electrical + to optical pixel or color values. + + When the resulting image description is attached to an image, the + content should be encoded with the inverse of the power curve. + + The curve exponent shall be multiplied by 10000 to get the argument eexp + value to carry the precision of 4 decimals. + + The curve exponent must be at least 1.0 and at most 10.0. Otherwise the + protocol error invalid_tf is raised. + + If transfer characteristic has already been set on this object, the + protocol error already_set is raised. + + This request can be used when the compositor advertises + xx_color_manager_v4.feature.set_tf_power. Otherwise this request raises + the protocol error unsupported_feature. + + + + + + + + Sets the color primaries and white point using explicitly named sets. + This describes the primary color volume which is the basis for color + value encoding. + + Only names advertised with xx_color_manager_v4 event + supported_primaries_named are allowed. Other values shall raise the + protocol error invalid_primaries. + + If primaries have already been set on this object, the protocol error + already_set is raised. + + + + + + + + Sets the color primaries and white point using CIE 1931 xy chromaticity + coordinates. This describes the primary color volume which is the basis + for color value encoding. + + Each coordinate value is multiplied by 10000 to get the argument value + to carry precision of 4 decimals. + + If primaries have already been set on this object, the protocol error + already_set is raised. + + This request can be used if the compositor advertises + xx_color_manager_v4.feature.set_primaries. Otherwise this request raises + the protocol error unsupported_feature. + + + + + + + + + + + + + + + Sets the primary color volume luminance range and the reference white + luminance level. + + The default luminances are + - primary color volume minimum: 0.2 cd/m² + - primary color volume maximum: 80 cd/m² + - reference white: 80 cd/m² + + Setting a named transfer characteristic can imply other default + luminances. + + The default luminances get overwritten when this request is used. + + 'min_lum' and 'max_lum' specify the minimum and maximum luminances of + the primary color volume as reproduced by the targeted display. + + 'reference_lum' specifies the luminance of the reference white as + reproduced by the targeted display, and reflects the targeted viewing + environment. + + Compositors should make sure that all content is anchored, meaning that + an input signal level of 'reference_lum' on one image description and + another input signal level of 'reference_lum' on another image + description should produce the same output level, even though the + 'reference_lum' on both image representations can be different. + + If 'max_lum' is less than the 'reference_lum', or 'reference_lum' is + less than or equal to 'min_lum', the protocol error invalid_luminance is + raised. + + The minimum luminance is multiplied by 10000 to get the argument + 'min_lum' value and carries precision of 4 decimals. The maximum + luminance and reference white luminance values are unscaled. + + If the primary color volume luminance range and the reference white + luminance level have already been set on this object, the protocol error + already_set is raised. + + This request can be used if the compositor advertises + xx_color_manager_v4.feature.set_luminances. Otherwise this request + raises the protocol error unsupported_feature. + + + + + + + + + + Provides the color primaries and white point of the mastering display + using CIE 1931 xy chromaticity coordinates. This is compatible with the + SMPTE ST 2086 definition of HDR static metadata. + + The mastering display primaries define the target color volume. + + If mastering display primaries are not explicitly set, the target color + volume is assumed to be equal to the primary color volume. + + The target color volume is defined by all tristimulus values between 0.0 + and 1.0 (inclusive) of the color space defined by the given mastering + display primaries and white point. The colorimetry is identical between + the container color space and the mastering display color space, + including that no chromatic adaptation is applied even if the white + points differ. + + The target color volume can exceed the primary color volume to allow for + a greater color volume with an existing color space definition (for + example scRGB). It can be smaller than the primary color volume to + minimize gamut and tone mapping distances for big color spaces (HDR + metadata). + + To make use of the entire target color volume a suitable pixel format + has to be chosen (e.g. floating point to exceed the primary color + volume, or abusing limited quantization range as with xvYCC). + + Each coordinate value is multiplied by 10000 to get the argument value + to carry precision of 4 decimals. + + If mastering display primaries have already been set on this object, the + protocol error already_set is raised. + + This request can be used if the compositor advertises + xx_color_manager_v4.feature.set_mastering_display_primaries. Otherwise + this request raises the protocol error unsupported_feature. The + advertisement implies support only for target color volumes fully + contained within the primary color volume. + + If a compositor additionally supports target color volume exceeding the + primary color volume, it must advertise + xx_color_manager_v4.feature.extended_target_volume. If a client uses + target color volume exceeding the primary color volume and the + compositor does not support it, the result is implementation defined. + Compositors are recommended to detect this case and fail the image + description gracefully, but it may as well result in color artifacts. + + + + + + + + + + + + + + + Sets the luminance range that was used during the content mastering + process as the minimum and maximum absolute luminance L. This is + compatible with the SMPTE ST 2086 definition of HDR static metadata. + + The mastering luminance range is undefined by default. + + If max L is less than or equal to min L, the protocol error + invalid_luminance is raised. + + Min L value is multiplied by 10000 to get the argument min_lum value + and carry precision of 4 decimals. Max L value is unscaled for max_lum. + + + + + + + + + Sets the maximum content light level (max_cll) as defined by CTA-861-H. + + This can only be set when set_tf_cicp is used to set the transfer + characteristic to Rec. ITU-R BT.2100-2 perceptual quantization system. + Otherwise, 'create' request shall raise inconsistent_set protocol + error. + + max_cll is undefined by default. + + + + + + + + Sets the maximum frame-average light level (max_fall) as defined by + CTA-861-H. + + This can only be set when set_tf_cicp is used to set the transfer + characteristic to Rec. ITU-R BT.2100-2 perceptual quantization system. + Otherwise, 'create' request shall raise inconsistent_set protocol error. + + max_fall is undefined by default. + + + + + + + + + An image description carries information about the color encoding used on + a surface when attached to a wl_surface via + xx_color_management_surface_v4.set_image_description. A compositor can use + this information to decode pixel values into colorimetrically meaningful + quantities. + + Note, that the xx_image_description_v4 object is not ready to be used + immediately after creation. The object eventually delivers either the + 'ready' or the 'failed' event, specified in all requests creating it. The + object is deemed "ready" after receiving the 'ready' event. + + An object which is not ready is illegal to use, it can only be destroyed. + Any other request in this interface shall result in the 'not_ready' + protocol error. Attempts to use an object which is not ready through other + interfaces shall raise protocol errors defined there. + + Once created and regardless of how it was created, a + xx_image_description_v4 object always refers to one fixed image + description. It cannot change after creation. + + + + + Destroy this object. It is safe to destroy an object which is not ready. + + Destroying a xx_image_description_v4 object has no side-effects, not + even if a xx_color_management_surface_v4.set_image_description has not + yet been followed by a wl_surface.commit. + + + + + + + + + + + + + + + + + + + + + + If creating a xx_image_description_v4 object fails for a reason that is + not defined as a protocol error, this event is sent. + + The requests that create image description objects define whether and + when this can occur. Only such creation requests can trigger this event. + This event cannot be triggered after the image description was + successfully formed. + + Once this event has been sent, the xx_image_description_v4 object will + never become ready and it can only be destroyed. + + + + + + + + + Once this event has been sent, the xx_image_description_v4 object is + deemed "ready". Ready objects can be used to send requests and can be + used through other interfaces. + + Every ready xx_image_description_v4 protocol object refers to an + underlying image description record in the compositor. Multiple protocol + objects may end up referring to the same record. Clients may identify + these "copies" by comparing their id numbers: if the numbers from two + protocol objects are identical, the protocol objects refer to the same + image description record. Two different image description records + cannot have the same id number simultaneously. The id number does not + change during the lifetime of the image description record. + + The id number is valid only as long as the protocol object is alive. If + all protocol objects referring to the same image description record are + destroyed, the id number may be recycled for a different image + description record. + + Image description id number is not a protocol object id. Zero is + reserved as an invalid id number. It shall not be possible for a client + to refer to an image description by its id number in protocol. The id + numbers might not be portable between Wayland connections. + + This identity allows clients to de-duplicate image description records + and avoid get_information request if they already have the image + description information. + + + + + + + + Creates a xx_image_description_info_v4 object which delivers the + information that makes up the image description. + + Not all image description protocol objects allow get_information + request. Whether it is allowed or not is defined by the request that + created the object. If get_information is not allowed, the protocol + error no_information is raised. + + + + + + + + + Sends all matching events describing an image description object exactly + once and finally sends the 'done' event. + + Once a xx_image_description_info_v4 object has delivered a 'done' event it + is automatically destroyed. + + Every xx_image_description_info_v4 created from the same + xx_image_description_v4 shall always return the exact same data. + + + + + Signals the end of information events and destroys the object. + + + + + + The icc argument provides a file descriptor to the client which may be + memory-mapped to provide the ICC profile matching the image description. + The fd is read-only, and if mapped then it must be mapped with + MAP_PRIVATE by the client. + + The ICC profile version and other details are determined by the + compositor. There is no provision for a client to ask for a specific + kind of a profile. + + + + + + + + + + Delivers the primary color volume primaries and white point using CIE + 1931 xy chromaticity coordinates. + + Each coordinate value is multiplied by 10000 to get the argument value + to carry precision of 4 decimals. + + + + + + + + + + + + + + + Delivers the primary color volume primaries and white point using an + explicitly enumerated named set. + + + + + + + + The color component transfer characteristic of this image description is + a pure power curve. This event provides the exponent of the power + function. This curve represents the conversion from electrical to + optical pixel or color values. + + The curve exponent has been multiplied by 10000 to get the argument eexp + value to carry the precision of 4 decimals. + + + + + + + + Delivers the transfer characteristic using an explicitly enumerated + named function. + + + + + + + + Delivers the primary color volume luminance range and the reference + white luminance level. + + The minimum luminance is multiplied by 10000 to get the argument + 'min_lum' value and carries precision of 4 decimals. The maximum + luminance and reference white luminance values are unscaled. + + + + + + + + + + Provides the color primaries and white point of the target color volume + using CIE 1931 xy chromaticity coordinates. This is compatible with the + SMPTE ST 2086 definition of HDR static metadata for mastering displays. + + While primary color volume is about how color is encoded, the target + color volume is the actually displayable color volume. If target color + volume is equal to the primary color volume, then this event is not + sent. + + Each coordinate value is multiplied by 10000 to get the argument value + to carry precision of 4 decimals. + + + + + + + + + + + + + + + Provides the luminance range that the image description is targeting as + the minimum and maximum absolute luminance L. This is compatible with + the SMPTE ST 2086 definition of HDR static metadata. + + This luminance range is only theoretical and may not correspond to the + luminance of light emitted on an actual display. + + Min L value is multiplied by 10000 to get the argument min_lum value and + carry precision of 4 decimals. Max L value is unscaled for max_lum. + + + + + + + + + Provides the targeted max_cll of the image description. max_cll is + defined by CTA-861-H. + + This luminance is only theoretical and may not correspond to the + luminance of light emitted on an actual display. + + + + + + + + Provides the targeted max_fall of the image description. max_fall is + defined by CTA-861-H. + + This luminance is only theoretical and may not correspond to the + luminance of light emitted on an actual display. + + + + + +