FFmpeg
csp.h
Go to the documentation of this file.
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 {
51 
52 /**
53  * Struct containing chromaticity x and y values for the standard CIE 1931
54  * chromaticity definition.
55  */
56 typedef struct AVCIExy {
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;
67 
68 /**
69  * Struct defining white point location in terms of CIE 1931 chromaticity x
70  * and y.
71  */
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 {
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  */
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  */
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  */
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  */
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  */
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  */
149 
150 /**
151  * Returns the mathematical inverse of the corresponding TRC function.
152  */
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  */
182 
183 /**
184  * Returns the mathematical inverse of the corresponding EOTF.
185  */
187 
188 /**
189  * @}
190  */
191 
192 #endif /* AVUTIL_CSP_H */
AVLumaCoefficients::cr
AVRational cr
Definition: csp.h:49
AVColorTransferCharacteristic
AVColorTransferCharacteristic
Color Transfer Characteristic.
Definition: pixfmt.h:611
AVColorPrimariesDesc::wp
AVWhitepointCoefficients wp
Definition: csp.h:79
AVColorPrimariesDesc
Struct that contains both white point location and primaries location, providing the complete descrip...
Definition: csp.h:78
av_csp_trc_func_inv_from_id
av_csp_trc_function av_csp_trc_func_inv_from_id(enum AVColorTransferCharacteristic trc)
Returns the mathematical inverse of the corresponding TRC function.
Definition: csp.c:426
rational.h
av_csp_luma_coeffs_from_avcsp
const AVLumaCoefficients * av_csp_luma_coeffs_from_avcsp(enum AVColorSpace csp)
Retrieves the Luma coefficients necessary to construct a conversion matrix from an enum constant desc...
Definition: csp.c:58
AVLumaCoefficients
Struct containing luma coefficients to be used for RGB to YUV/YCoCg, or similar calculations.
Definition: csp.h:48
AVColorPrimaries
AVColorPrimaries
Chromaticity coordinates of the source primaries.
Definition: pixfmt.h:586
av_csp_trc_func_from_id
av_csp_trc_function av_csp_trc_func_from_id(enum AVColorTransferCharacteristic trc)
Determine the function needed to apply the given AVColorTransferCharacteristic to linear input.
Definition: csp.c:400
AVPrimaryCoefficients
Struct defining the red, green, and blue primary locations in terms of CIE 1931 chromaticity x and y.
Definition: csp.h:64
av_csp_primaries_desc_from_id
const AVColorPrimariesDesc * av_csp_primaries_desc_from_id(enum AVColorPrimaries prm)
Retrieves a complete gamut description from an enum constant describing the color primaries.
Definition: csp.c:90
av_csp_primaries_id_from_desc
enum AVColorPrimaries av_csp_primaries_id_from_desc(const AVColorPrimariesDesc *prm)
Detects which enum AVColorPrimaries constant corresponds to the given complete gamut description.
Definition: csp.c:110
AVLumaCoefficients::cg
AVRational cg
Definition: csp.h:49
AVRational
Rational number (pair of numerator and denominator).
Definition: rational.h:58
double
double
Definition: af_crystalizer.c:132
AVCIExy
Struct containing chromaticity x and y values for the standard CIE 1931 chromaticity definition.
Definition: csp.h:56
c
Undefined Behavior In the C some operations are like signed integer dereferencing freed accessing outside allocated Undefined Behavior must not occur in a C it is not safe even if the output of undefined operations is unused The unsafety may seem nit picking but Optimizing compilers have in fact optimized code on the assumption that no undefined Behavior occurs Optimizing code based on wrong assumptions can and has in some cases lead to effects beyond the output of computations The signed integer overflow problem in speed critical code Code which is highly optimized and works with signed integers sometimes has the problem that often the output of the computation does not c
Definition: undefined.txt:32
AVWhitepointCoefficients
AVCIExy AVWhitepointCoefficients
Struct defining white point location in terms of CIE 1931 chromaticity x and y.
Definition: csp.h:72
AVCIExy::x
AVRational x
Definition: csp.h:57
AVPrimaryCoefficients::b
AVCIExy b
Definition: csp.h:65
AVPrimaryCoefficients::r
AVCIExy r
Definition: csp.h:65
av_csp_approximate_trc_gamma
double av_csp_approximate_trc_gamma(enum AVColorTransferCharacteristic trc)
Determine a suitable 'gamma' value to match the supplied AVColorTransferCharacteristic.
Definition: csp.c:149
AVPrimaryCoefficients::g
AVCIExy g
Definition: csp.h:65
av_csp_trc_function
double(* av_csp_trc_function)(double)
Function pointer representing a double -> double transfer function that performs either an OETF trans...
Definition: csp.h:91
AVColorSpace
AVColorSpace
YUV colorspace type.
Definition: pixfmt.h:640
av_csp_eotf_function
void(* av_csp_eotf_function)(double Lw, double Lb, double c[3])
Function pointer representing an ITU EOTF transfer for a given reference display configuration.
Definition: csp.h:162
pixfmt.h
AVCIExy::y
AVRational y
Definition: csp.h:57
AVColorPrimariesDesc::prim
AVPrimaryCoefficients prim
Definition: csp.h:80
av_csp_itu_eotf
av_csp_eotf_function av_csp_itu_eotf(enum AVColorTransferCharacteristic trc)
Returns the ITU EOTF corresponding to a given TRC.
Definition: csp.c:605
AVLumaCoefficients::cb
AVRational cb
Definition: csp.h:49
av_csp_itu_eotf_inv
av_csp_eotf_function av_csp_itu_eotf_inv(enum AVColorTransferCharacteristic trc)
Returns the mathematical inverse of the corresponding EOTF.
Definition: csp.c:631