avutil/{color_utils, csp}: merge color_utils into csp and expose API

libavutil/color_utils contains some avpriv_ symbols that map
enum AVTransferCharacteristic values to gamma-curve approximations and
to the actual transfer functions to invert them (i.e. -> linear).

There's two issues with this:
(1) avpriv is evil and should be avoided whenever possible
(2) libavutil/csp.h exposes a public API for handling color that
    already handles primaries and matricies

I don't see any reason this API has to be private, so this commit takes
the functionality from avutil/color_utils and merges it into avutil/csp
with an exposed av_ API rather than the previous avpriv_ API.

Every reference to the previous API has been updated to point to the
new one. color_utils.h has been deleted as well. This should not break
any applications as it only contained avpriv_ symbols in the first
place, so nothing in that header could be referenced by other
applications.

Signed-off-by: Leo Izen <leo.izen@gmail.com>
Signed-off-by: Anton Khirnov <anton@khirnov.net>

1 files changed, 39 insertions, 0 deletions

diff --git a/libavutil/csp.h b/libavutil/csp.h
index 18ef208adf..73bce52bc0 100644
--- a/libavutil/csp.h
+++ b/libavutil/csp.h
@@ -1,5 +1,8 @@
 /*
+ * Copyright (c) 2015 Kevin Wheatley <kevin.j.wheatley@gmail.com>
  * Copyright (c) 2016 Ronald S. Bultje <rsbultje@gmail.com>
+ * Copyright (c) 2023 Leo Izen <leo.izen@gmail.com>
+ *
  * This file is part of FFmpeg.
  *
  * FFmpeg is free software; you can redistribute it and/or
@@ -29,6 +32,7 @@
  * @ingroup lavu_math_csp
  * @author Ronald S. Bultje <rsbultje@gmail.com>
  * @author Leo Izen <leo.izen@gmail.com>
+ * @author Kevin Wheatley <kevin.j.wheatley@gmail.com>
  */
 
 /**
@@ -77,6 +81,12 @@ typedef struct AVColorPrimariesDesc {
 } AVColorPrimariesDesc;
 
 /**
+ * Function pointer representing a double -> double transfer function that performs
+ * an EOTF transfer inversion. This function outputs linear light.
+ */
+typedef double (*av_csp_trc_function)(double);
+
+/**
  * Retrieves the Luma coefficients necessary to construct a conversion matrix
  * from an enum constant describing the colorspace.
  * @param csp An enum constant indicating YUV or similar colorspace.
@@ -105,6 +115,35 @@ const AVColorPrimariesDesc *av_csp_primaries_desc_from_id(enum AVColorPrimaries
 enum AVColorPrimaries av_csp_primaries_id_from_desc(const AVColorPrimariesDesc *prm);
 
 /**
+ * Determine a suitable 'gamma' value to match the supplied
+ * AVColorTransferCharacteristic.
+ *
+ * See Apple Technical Note TN2257 (https://developer.apple.com/library/mac/technotes/tn2257/_index.html)
+ *
+ * This function returns the gamma exponent for the OETF. For example, sRGB is approximated
+ * by gamma 2.2, not by gamma 0.45455.
+ *
+ * @return Will return an approximation to the simple gamma function matching
+ *         the supplied Transfer Characteristic, Will return 0.0 for any
+ *         we cannot reasonably match against.
+ */
+double av_csp_approximate_trc_gamma(enum AVColorTransferCharacteristic trc);
+
+/**
+ * Determine the function needed to apply the given
+ * AVColorTransferCharacteristic to linear input.
+ *
+ * The function returned should expect a nominal domain and range of [0.0-1.0]
+ * values outside of this range maybe valid depending on the chosen
+ * characteristic function.
+ *
+ * @return Will return pointer to the function matching the
+ *         supplied Transfer Characteristic. If unspecified will
+ *         return NULL:
+ */
+av_csp_trc_function av_csp_trc_func_from_id(enum AVColorTransferCharacteristic trc);
+
+/**
  * @}
  */