libweston: add basic output color characteristics API

This adds color_chracteristics field in weston_output. This field is
intended to be set by compositor frontends and read by color managers.
Color managers can use this information when choosing the output color
space and dynamic range, particularly when no ICC profile has been set.

This is most useful for HDR outputs, where the HDR static metadata for
PQ mode or the display luminance parameters for HLG mode can be based on
color_characteristics.

The fields of weston_color_characteristics mirror the information
available in EDID. However, using EDID information as-is has several
caveats, so the decision to use EDID for this is left for the frontend
and ultimately to the end user.

There are no defined ranges or validity checks for this data. The color
manager will have to validate the values against whatever it is using
them for.

Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>

include/libweston/libweston.h

@@ -241,6 +241,63 @@ enum weston_eotf_mode {
 	((uint32_t)(WESTON_EOTF_MODE_SDR | WESTON_EOTF_MODE_TRADITIONAL_HDR | \
 		    WESTON_EOTF_MODE_ST2084 | WESTON_EOTF_MODE_HLG))
 
+/** CIE 1931 xy chromaticity coordinates */
+struct weston_CIExy {
+	float x;
+	float y;
+};
+
+enum weston_color_characteristics_groups {
+	/** weston_color_characteristics::primary is set */
+	WESTON_COLOR_CHARACTERISTICS_GROUP_PRIMARIES	= 0x01,
+
+	/** weston_color_characteristics::white is set */
+	WESTON_COLOR_CHARACTERISTICS_GROUP_WHITE	= 0x02,
+
+	/** weston_color_characteristics::max_luminance is set */
+	WESTON_COLOR_CHARACTERISTICS_GROUP_MAXL		= 0x04,
+
+	/** weston_color_characteristics::min_luminance is set */
+	WESTON_COLOR_CHARACTERISTICS_GROUP_MINL		= 0x08,
+
+	/** weston_color_characteristics::maxFALL is set */
+	WESTON_COLOR_CHARACTERISTICS_GROUP_MAXFALL	= 0x10,
+
+	/** all valid bits */
+	WESTON_COLOR_CHARACTERISTICS_GROUP_ALL_MASK	= 0x1f
+};
+
+/** Basic display color characteristics
+ *
+ * This is a simple description of a display or output (monitor) color
+ * characteristics. The parameters can be found in EDID, with caveats. They
+ * are particularly useful with HDR monitors.
+ */
+struct weston_color_characteristics {
+	/** Which fields are valid
+	 *
+	 * A bitmask of values from enum weston_color_characteristics_groups.
+	 */
+	uint32_t group_mask;
+
+	/* EOTF is tracked externally with enum weston_eotf_mode */
+
+	/** Chromaticities of the primaries */
+	struct weston_CIExy primary[3];
+
+	/** White point chromaticity */
+	struct weston_CIExy white;
+
+	/** Display's desired maximum content peak luminance, cd/m² */
+	float max_luminance;
+
+	/** Display's desired minimum content luminance, cd/m² */
+	float min_luminance;
+
+	/** Display's desired maximum frame-average light level, cd/m² */
+	float maxFALL;
+};
+
 /** Represents a head, usually a display connector
  *
  * \rst
@@ -414,6 +471,7 @@ struct weston_output {
 	struct weston_color_profile *color_profile;
 	bool from_blend_to_output_by_backend;
 	enum weston_eotf_mode eotf_mode;
+	struct weston_color_characteristics color_characteristics;
 
 	struct weston_output_color_outcome *color_outcome;
 
@@ -2142,6 +2200,13 @@ weston_output_set_eotf_mode(struct weston_output *output,
 enum weston_eotf_mode
 weston_output_get_eotf_mode(const struct weston_output *output);
 
+void
+weston_output_set_color_characteristics(struct weston_output *output,
+					const struct weston_color_characteristics *cc);
+
+const struct weston_color_characteristics *
+weston_output_get_color_characteristics(struct weston_output *output);
+
 void
 weston_output_init(struct weston_output *output,
 		   struct weston_compositor *compositor,

libweston/compositor.c

@@ -6764,6 +6764,50 @@ weston_output_get_eotf_mode(const struct weston_output *output)
 	return output->eotf_mode;
 }
 
+/** Set display or monitor basic color characteristics
+ *
+ * \param output The output to modify, must be in disabled state.
+ * \param cc The new characteristics to set, or NULL to unset everything.
+ *
+ * This sets the metadata that describes the color characteristics of the
+ * output in a very simple manner. If a non-NULL color profile is set for the
+ * output, that will always take precedence.
+ *
+ * The initial value has everything unset.
+ *
+ * This function is meant to be used by compositor frontends.
+ *
+ * \ingroup output
+ * \sa weston_output_set_color_profile
+ */
+WL_EXPORT void
+weston_output_set_color_characteristics(struct weston_output *output,
+					const struct weston_color_characteristics *cc)
+{
+	assert(!output->enabled);
+
+	if (cc)
+		output->color_characteristics = *cc;
+	else
+		output->color_characteristics.group_mask = 0;
+}
+
+/** Get display or monitor basic color characteristics
+ *
+ * \param output The output to query.
+ * \return Pointer to the metadata stored in weston_output.
+ *
+ * This function is meant to be used by color manager modules.
+ *
+ * \ingroup output
+ * \sa weston_output_set_color_characteristics
+ */
+WL_EXPORT const struct weston_color_characteristics *
+weston_output_get_color_characteristics(struct weston_output *output)
+{
+	return &output->color_characteristics;
+}
+
 /** Initializes a weston_output object with enough data so
  ** an output can be configured.
  *