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 performs
85  * an EOTF transfer inversion. This function outputs linear light.
86  */
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  */
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  */
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  */
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  */
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  */
145 
146 /**
147  * @}
148  */
149 
150 #endif /* AVUTIL_CSP_H */
AVLumaCoefficients::cr
AVRational cr
Definition: csp.h:49
AVColorTransferCharacteristic
AVColorTransferCharacteristic
Color Transfer Characteristic.
Definition: pixfmt.h:584
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
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:559
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:291
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:131
AVCIExy
Struct containing chromaticity x and y values for the standard CIE 1931 chromaticity definition.
Definition: csp.h:56
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 an EOTF transfer inv...
Definition: csp.h:87
AVColorSpace
AVColorSpace
YUV colorspace type.
Definition: pixfmt.h:613
pixfmt.h
AVCIExy::y
AVRational y
Definition: csp.h:57
AVColorPrimariesDesc::prim
AVPrimaryCoefficients prim
Definition: csp.h:80
AVLumaCoefficients::cb
AVRational cb
Definition: csp.h:49