From 98f27dcf24d4a75f21fe2931b3adce40c198f4c5 Mon Sep 17 00:00:00 2001
From: Pekka Paalanen <pekka.paalanen@collabora.com>
Date: Thu, 18 Sep 2025 13:45:48 +0300
Subject: [PATCH] staging/color-management: add normative appendix

It is not possible to write equations nicely in the XML, so we need an
appendix.

First, the appendix explicitly defines the transfer functions that the
protocol enumeration refers to. Leaving them to be inferred from the
ITU-R and other specifications was too confusing.

Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
---
 staging/color-management/appendix.md          | 127 ++++++++++++++++++
 .../color-management/color-management-v1.xml  |   5 +
 2 files changed, 132 insertions(+)
 create mode 100644 staging/color-management/appendix.md

diff --git a/staging/color-management/appendix.md b/staging/color-management/appendix.md
new file mode 100644
index 0000000..8bd6141
--- /dev/null
+++ b/staging/color-management/appendix.md
@@ -0,0 +1,127 @@
+---
+SPDX-FileCopyrightText: 2025 Collabora, Ltd.
+SPDX-License-Identifier: MIT
+---
+
+Contents
+
+[TOC]
+
+# Wayland Color-Management Protocol
+
+This document is an appendix to the [color-management][cm-spec]
+protocol specification.
+
+## Transfer functions (normative)
+
+`wp_color_manager_v1` enumeration `transfer_function` lists a selection
+of transfer functions describing display-referred image encoding between
+normalized [electrical] $`E`$ and [optical] $`L`$ values. The function
+definitions are as follows.
+
+$`L`$
+: Screen luminance in cd/m² in the assumed viewing environment.
+Since the protocol uses the reference luminance level as a proxy for the
+environment, these values must be interpreted in the context of the
+reference luminance level.
+
+$`L_W`$
+: Screen luminance for peak white; the primary color volume maximum luminance.
+
+$`L_B`$
+: Screen luminance for black; the primary color volume minimum luminance.
+
+
+### `bt1886`
+
+```math
+L = a\left(\max\left(E + b,0\right)\right)^\gamma
+```
+
+where $`\gamma = 2.4`$ and the parameters
+
+```math
+a = \left(L_W^{1/\gamma} - L_B^{1/\gamma}\right)^\gamma,
+```
+
+```math
+b = \frac{L_B^{1/\gamma}}{L_W^{1/\gamma} - L_B^{1/\gamma}}.
+```
+
+The above are specified by [ITU-R BT.1886].
+
+Note, that $`E < 0`$ and $`E > 1`$ are possible with limited range
+quantization, as required by e.g. the calibration method in [ITU-R BT.814].
+
+
+### `gamma22`
+
+```math
+O = E^{2.2}, \quad 0 \leq E \leq 1
+```
+
+```math
+L = (L_W - L_B)O + L_B
+```
+
+### `gamma28`
+
+```math
+O = E^{2.8}, \quad 0 \leq E \leq 1
+```
+
+```math
+L = (L_W - L_B)O + L_B
+```
+
+### `ext_linear`
+
+```math
+O = E, \quad \forall E \in \Reals
+```
+
+```math
+L = (L_W - L_B)O + L_B
+```
+
+### `st2084_pq`
+
+```math
+\begin{align*}
+m_1 &=& \vphantom{\Bigg(} \frac{2610}{16384} &= 0.1593017578125\\
+m_2 &=& \vphantom{\Bigg(} 128\left(\frac{2523}{4096}\right) &= 78.84375\\
+c_1 = c_3 − c_2 + 1 &=& \vphantom{\Bigg(} \frac{3424}{4096} &= 0.8359375\\
+c_2 &=& \vphantom{\Bigg(} 32\left(\frac{2413}{4096}\right) &= 18.8515625\\
+c_3 &=& \vphantom{\Bigg(} 32\left(\frac{2392}{4096}\right) &= 18.6875
+\end{align*}
+```
+
+```math
+O = \left(
+  \frac{\max\left[
+    \left(E^\frac{1}{m_2} - c_1\right), 0
+  \right]}{c_2 - c_3 E^\frac{1}{m_2}}
+\right)^\frac{1}{m_1},
+\quad 0 \leq E \leq 1
+```
+
+And the inverse
+
+```math
+E = \left( \frac{c_1 + c_2 O^{m_1}}{1 + c_3 O^{m_1}} \right)^{m_2},
+\quad 0 \leq O \leq 1
+```
+
+The above are specified by [ITU-R BT.2100].
+
+```math
+L = 10'000\ \mathrm{cd/m²} \cdot O + L_B
+```
+
+
+[cm-spec]: https://gitlab.freedesktop.org/wayland/wayland-protocols/-/tree/main/staging/color-management
+[electrical]: https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/glossary.md#electrical-color-value
+[optical]: https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/glossary.md#optical-color-value
+[ITU-R BT.814]: https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/specs.md#itu-r-bt814
+[ITU-R BT.1886]: https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/specs.md#itu-r-bt1886
+[ITU-R BT.2100]: https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/specs.md#itu-r-bt2100
diff --git a/staging/color-management/color-management-v1.xml b/staging/color-management/color-management-v1.xml
index 2958a19..96a063e 100644
--- a/staging/color-management/color-management-v1.xml
+++ b/staging/color-management/color-management-v1.xml
@@ -57,6 +57,9 @@
     color-management extension when necessary, particularly with the YUV family
     of pixel formats.
 
+    The normative appendix for this protocol is in the appendix.md file beside
+    this XML file.
+
     The color-and-hdr repository
     (https://gitlab.freedesktop.org/pq/color-and-hdr) contains
     background information on the protocol design and legacy color management.
@@ -251,6 +254,8 @@
         characteristics of displays.
 
         A value of 0 is invalid and will never be present in the list of enums.
+
+        See appendix.md for the formulae.
       </description>
 
       <entry name="bt1886" value="1">