csp.h (4927B)
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 performs 85 * an EOTF transfer inversion. This function outputs linear light. 86 */ 87 typedef double (*av_csp_trc_function)(double); 88 89 /** 90 * Retrieves the Luma coefficients necessary to construct a conversion matrix 91 * from an enum constant describing the colorspace. 92 * @param csp An enum constant indicating YUV or similar colorspace. 93 * @return The Luma coefficients associated with that colorspace, or NULL 94 * if the constant is unknown to libavutil. 95 */ 96 const AVLumaCoefficients *av_csp_luma_coeffs_from_avcsp(enum AVColorSpace csp); 97 98 /** 99 * Retrieves a complete gamut description from an enum constant describing the 100 * color primaries. 101 * @param prm An enum constant indicating primaries 102 * @return A description of the colorspace gamut associated with that enum 103 * constant, or NULL if the constant is unknown to libavutil. 104 */ 105 const AVColorPrimariesDesc *av_csp_primaries_desc_from_id(enum AVColorPrimaries prm); 106 107 /** 108 * Detects which enum AVColorPrimaries constant corresponds to the given complete 109 * gamut description. 110 * @see enum AVColorPrimaries 111 * @param prm A description of the colorspace gamut 112 * @return The enum constant associated with this gamut, or 113 * AVCOL_PRI_UNSPECIFIED if no clear match can be idenitified. 114 */ 115 enum AVColorPrimaries av_csp_primaries_id_from_desc(const AVColorPrimariesDesc *prm); 116 117 /** 118 * Determine a suitable 'gamma' value to match the supplied 119 * AVColorTransferCharacteristic. 120 * 121 * See Apple Technical Note TN2257 (https://developer.apple.com/library/mac/technotes/tn2257/_index.html) 122 * 123 * This function returns the gamma exponent for the OETF. For example, sRGB is approximated 124 * by gamma 2.2, not by gamma 0.45455. 125 * 126 * @return Will return an approximation to the simple gamma function matching 127 * the supplied Transfer Characteristic, Will return 0.0 for any 128 * we cannot reasonably match against. 129 */ 130 double av_csp_approximate_trc_gamma(enum AVColorTransferCharacteristic trc); 131 132 /** 133 * Determine the function needed to apply the given 134 * AVColorTransferCharacteristic to linear input. 135 * 136 * The function returned should expect a nominal domain and range of [0.0-1.0] 137 * values outside of this range maybe valid depending on the chosen 138 * characteristic function. 139 * 140 * @return Will return pointer to the function matching the 141 * supplied Transfer Characteristic. If unspecified will 142 * return NULL: 143 */ 144 av_csp_trc_function av_csp_trc_func_from_id(enum AVColorTransferCharacteristic trc); 145 146 /** 147 * @} 148 */ 149 150 #endif /* AVUTIL_CSP_H */