csp.h (6669B)
1 /* 2 * Copyright (c) 2015 Kevin Wheatley <kevin.j.wheatley@gmail.com> 3 * Copyright (c) 2016 Ronald S. Bultje <rsbultje@gmail.com> 4 * Copyright (c) 2023 Leo Izen <leo.izen@gmail.com> 5 * 6 * This file is part of FFmpeg. 7 * 8 * FFmpeg is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public 10 * License as published by the Free Software Foundation; either 11 * version 2.1 of the License, or (at your option) any later version. 12 * 13 * FFmpeg is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public 19 * License along with FFmpeg; if not, write to the Free Software 20 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 21 */ 22 23 #ifndef AVUTIL_CSP_H 24 #define AVUTIL_CSP_H 25 26 #include "pixfmt.h" 27 #include "rational.h" 28 29 /** 30 * @file 31 * Colorspace value utility functions for libavutil. 32 * @ingroup lavu_math_csp 33 * @author Ronald S. Bultje <rsbultje@gmail.com> 34 * @author Leo Izen <leo.izen@gmail.com> 35 * @author Kevin Wheatley <kevin.j.wheatley@gmail.com> 36 */ 37 38 /** 39 * @defgroup lavu_math_csp Colorspace Utility 40 * @ingroup lavu_math 41 * @{ 42 */ 43 44 /** 45 * Struct containing luma coefficients to be used for RGB to YUV/YCoCg, or similar 46 * calculations. 47 */ 48 typedef struct AVLumaCoefficients { 49 AVRational cr, cg, cb; 50 } AVLumaCoefficients; 51 52 /** 53 * Struct containing chromaticity x and y values for the standard CIE 1931 54 * chromaticity definition. 55 */ 56 typedef struct AVCIExy { 57 AVRational x, y; 58 } AVCIExy; 59 60 /** 61 * Struct defining the red, green, and blue primary locations in terms of CIE 62 * 1931 chromaticity x and y. 63 */ 64 typedef struct AVPrimaryCoefficients { 65 AVCIExy r, g, b; 66 } AVPrimaryCoefficients; 67 68 /** 69 * Struct defining white point location in terms of CIE 1931 chromaticity x 70 * and y. 71 */ 72 typedef AVCIExy AVWhitepointCoefficients; 73 74 /** 75 * Struct that contains both white point location and primaries location, providing 76 * the complete description of a color gamut. 77 */ 78 typedef struct AVColorPrimariesDesc { 79 AVWhitepointCoefficients wp; 80 AVPrimaryCoefficients prim; 81 } AVColorPrimariesDesc; 82 83 /** 84 * Function pointer representing a double -> double transfer function that 85 * performs either an OETF transfer function, or alternatively an inverse EOTF 86 * function (in particular, for SMPTE ST 2084 / PQ). This function inputs 87 * linear light, and outputs gamma encoded light. 88 * 89 * See ITU-T H.273 for more information. 90 */ 91 typedef double (*av_csp_trc_function)(double); 92 93 /** 94 * Retrieves the Luma coefficients necessary to construct a conversion matrix 95 * from an enum constant describing the colorspace. 96 * @param csp An enum constant indicating YUV or similar colorspace. 97 * @return The Luma coefficients associated with that colorspace, or NULL 98 * if the constant is unknown to libavutil. 99 */ 100 const AVLumaCoefficients *av_csp_luma_coeffs_from_avcsp(enum AVColorSpace csp); 101 102 /** 103 * Retrieves a complete gamut description from an enum constant describing the 104 * color primaries. 105 * @param prm An enum constant indicating primaries 106 * @return A description of the colorspace gamut associated with that enum 107 * constant, or NULL if the constant is unknown to libavutil. 108 */ 109 const AVColorPrimariesDesc *av_csp_primaries_desc_from_id(enum AVColorPrimaries prm); 110 111 /** 112 * Detects which enum AVColorPrimaries constant corresponds to the given complete 113 * gamut description. 114 * @see enum AVColorPrimaries 115 * @param prm A description of the colorspace gamut 116 * @return The enum constant associated with this gamut, or 117 * AVCOL_PRI_UNSPECIFIED if no clear match can be idenitified. 118 */ 119 enum AVColorPrimaries av_csp_primaries_id_from_desc(const AVColorPrimariesDesc *prm); 120 121 /** 122 * Determine a suitable 'gamma' value to match the supplied 123 * AVColorTransferCharacteristic. 124 * 125 * See Apple Technical Note TN2257 (https://developer.apple.com/library/mac/technotes/tn2257/_index.html) 126 * 127 * This function returns the gamma exponent for the OETF. For example, sRGB is approximated 128 * by gamma 2.2, not by gamma 0.45455. 129 * 130 * @return Will return an approximation to the simple gamma function matching 131 * the supplied Transfer Characteristic, Will return 0.0 for any 132 * we cannot reasonably match against. 133 */ 134 double av_csp_approximate_trc_gamma(enum AVColorTransferCharacteristic trc); 135 136 /** 137 * Determine the function needed to apply the given 138 * AVColorTransferCharacteristic to linear input. 139 * 140 * The function returned should expect a nominal domain and range of [0.0-1.0] 141 * values outside of this range maybe valid depending on the chosen 142 * characteristic function. 143 * 144 * @return Will return pointer to the function matching the 145 * supplied Transfer Characteristic. If unspecified will 146 * return NULL: 147 */ 148 av_csp_trc_function av_csp_trc_func_from_id(enum AVColorTransferCharacteristic trc); 149 150 /** 151 * Returns the mathematical inverse of the corresponding TRC function. 152 */ 153 av_csp_trc_function av_csp_trc_func_inv_from_id(enum AVColorTransferCharacteristic trc); 154 155 /** 156 * Function pointer representing an ITU EOTF transfer for a given reference 157 * display configuration. 158 * 159 * @param Lw The white point luminance of the display, in nits (cd/m^2). 160 * @param Lb The black point luminance of the display, in nits (cd/m^2). 161 */ 162 typedef void (*av_csp_eotf_function)(double Lw, double Lb, double c[3]); 163 164 /** 165 * Returns the ITU EOTF corresponding to a given TRC. This converts from the 166 * signal level [0,1] to the raw output display luminance in nits (cd/m^2). 167 * This is done per channel in RGB space, except for AVCOL_TRC_SMPTE428, which 168 * assumes CIE XYZ in- and output. 169 * 170 * @return A pointer to the function implementing the given TRC, or NULL if no 171 * such function is defined. 172 * 173 * @note In general, the resulting function is defined (wherever possible) for 174 * out-of-range values, even though these values do not have a physical 175 * meaning on the given display. Users should clamp inputs (or outputs) 176 * if this behavior is not desired. 177 * 178 * This is also the case for functions like PQ, which are defined over an 179 * absolute signal range independent of the target display capabilities. 180 */ 181 av_csp_eotf_function av_csp_itu_eotf(enum AVColorTransferCharacteristic trc); 182 183 /** 184 * Returns the mathematical inverse of the corresponding EOTF. 185 */ 186 av_csp_eotf_function av_csp_itu_eotf_inv(enum AVColorTransferCharacteristic trc); 187 188 /** 189 * @} 190 */ 191 192 #endif /* AVUTIL_CSP_H */