subprojects/gst-plugins-base/gst-libs/gst/video/video-color.h

   1 /* GStreamer
   2  * Copyright (C) <2011> Wim Taymans <wim.taymans@gmail.com>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  17  * Boston, MA 02110-1301, USA.
  18  */
  19
  20 #ifndef __GST_VIDEO_COLOR_H__
  21 #define __GST_VIDEO_COLOR_H__
  22
  23 #include <gst/gst.h>
  24
  25 #include <gst/video/video-format.h>
  26
  27 G_BEGIN_DECLS
  28
  29 /**
  30  * GstVideoColorRange:
  31  * @GST_VIDEO_COLOR_RANGE_UNKNOWN: unknown range
  32  * @GST_VIDEO_COLOR_RANGE_0_255: [0..255] for 8 bit components
  33  * @GST_VIDEO_COLOR_RANGE_16_235: [16..235] for 8 bit components. Chroma has
  34  *                 [16..240] range.
  35  *
  36  * Possible color range values. These constants are defined for 8 bit color
  37  * values and can be scaled for other bit depths.
  38  */
  39 typedef enum {
  40   GST_VIDEO_COLOR_RANGE_UNKNOWN = 0,
  41   GST_VIDEO_COLOR_RANGE_0_255,
  42   GST_VIDEO_COLOR_RANGE_16_235
  43 } GstVideoColorRange;
  44
  45 /**
  46  * GstVideoColorMatrix:
  47  * @GST_VIDEO_COLOR_MATRIX_UNKNOWN: unknown matrix
  48  * @GST_VIDEO_COLOR_MATRIX_RGB: identity matrix. Order of coefficients is
  49  * actually GBR, also IEC 61966-2-1 (sRGB)
  50  * @GST_VIDEO_COLOR_MATRIX_FCC: FCC Title 47 Code of Federal Regulations 73.682 (a)(20)
  51  * @GST_VIDEO_COLOR_MATRIX_BT709: ITU-R BT.709 color matrix, also ITU-R BT1361
  52  * / IEC 61966-2-4 xvYCC709 / SMPTE RP177 Annex B
  53  * @GST_VIDEO_COLOR_MATRIX_BT601: ITU-R BT.601 color matrix, also SMPTE170M / ITU-R BT1358 525 / ITU-R BT1700 NTSC
  54  * @GST_VIDEO_COLOR_MATRIX_SMPTE240M: SMPTE 240M color matrix
  55  * @GST_VIDEO_COLOR_MATRIX_BT2020: ITU-R BT.2020 color matrix. Since: 1.6
  56  *
  57  * The color matrix is used to convert between Y'PbPr and
  58  * non-linear RGB (R'G'B')
  59  */
  60 typedef enum {
  61   GST_VIDEO_COLOR_MATRIX_UNKNOWN = 0,
  62   GST_VIDEO_COLOR_MATRIX_RGB,
  63   GST_VIDEO_COLOR_MATRIX_FCC,
  64   GST_VIDEO_COLOR_MATRIX_BT709,
  65   GST_VIDEO_COLOR_MATRIX_BT601,
  66   GST_VIDEO_COLOR_MATRIX_SMPTE240M,
  67   GST_VIDEO_COLOR_MATRIX_BT2020
  68 } GstVideoColorMatrix;
  69
  70 GST_VIDEO_API
  71 gboolean gst_video_color_matrix_get_Kr_Kb (GstVideoColorMatrix matrix, gdouble * Kr, gdouble * Kb);
  72
  73 /**
  74  * GstVideoTransferFunction:
  75  * @GST_VIDEO_TRANSFER_UNKNOWN: unknown transfer function
  76  * @GST_VIDEO_TRANSFER_GAMMA10: linear RGB, gamma 1.0 curve
  77  * @GST_VIDEO_TRANSFER_GAMMA18: Gamma 1.8 curve
  78  * @GST_VIDEO_TRANSFER_GAMMA20: Gamma 2.0 curve
  79  * @GST_VIDEO_TRANSFER_GAMMA22: Gamma 2.2 curve
  80  * @GST_VIDEO_TRANSFER_BT709: Gamma 2.2 curve with a linear segment in the lower
  81  *                           range, also ITU-R BT470M / ITU-R BT1700 625 PAL &
  82  *                           SECAM / ITU-R BT1361
  83  * @GST_VIDEO_TRANSFER_SMPTE240M: Gamma 2.2 curve with a linear segment in the
  84  *                               lower range
  85  * @GST_VIDEO_TRANSFER_SRGB: Gamma 2.4 curve with a linear segment in the lower
  86  *                          range. IEC 61966-2-1 (sRGB or sYCC)
  87  * @GST_VIDEO_TRANSFER_GAMMA28: Gamma 2.8 curve, also ITU-R BT470BG
  88  * @GST_VIDEO_TRANSFER_LOG100: Logarithmic transfer characteristic
  89  *                             100:1 range
  90  * @GST_VIDEO_TRANSFER_LOG316: Logarithmic transfer characteristic
  91  *                             316.22777:1 range (100 * sqrt(10) : 1)
  92  * @GST_VIDEO_TRANSFER_BT2020_12: Gamma 2.2 curve with a linear segment in the lower
  93  *                                range. Used for BT.2020 with 12 bits per
  94  *                                component. Since: 1.6
  95  * @GST_VIDEO_TRANSFER_ADOBERGB: Gamma 2.19921875. Since: 1.8
  96  * @GST_VIDEO_TRANSFER_BT2020_10: Rec. ITU-R BT.2020-2 with 10 bits per component.
  97  *                                (functionally the same as the values
  98  *                                GST_VIDEO_TRANSFER_BT709 and GST_VIDEO_TRANSFER_BT601).
  99  *                                Since: 1.18
 100  * @GST_VIDEO_TRANSFER_SMPTE2084: SMPTE ST 2084 for 10, 12, 14, and 16-bit systems.
 101  *                                Known as perceptual quantization (PQ)
 102  *                                Since: 1.18
 103  * @GST_VIDEO_TRANSFER_ARIB_STD_B67: Association of Radio Industries and Businesses (ARIB)
 104  *                                   STD-B67 and Rec. ITU-R BT.2100-1 hybrid loggamma (HLG) system
 105  *                                   Since: 1.18
 106  * @GST_VIDEO_TRANSFER_BT601: also known as SMPTE170M / ITU-R BT1358 525 or 625 / ITU-R BT1700 NTSC
 107  *                            Functionally the same as the values
 108  *                            GST_VIDEO_TRANSFER_BT709, and GST_VIDEO_TRANSFER_BT2020_10.
 109  *                            Since: 1.18
 110  *
 111  * The video transfer function defines the formula for converting between
 112  * non-linear RGB (R'G'B') and linear RGB
 113  */
 114 typedef enum {
 115   GST_VIDEO_TRANSFER_UNKNOWN = 0,
 116   GST_VIDEO_TRANSFER_GAMMA10,
 117   GST_VIDEO_TRANSFER_GAMMA18,
 118   GST_VIDEO_TRANSFER_GAMMA20,
 119   GST_VIDEO_TRANSFER_GAMMA22,
 120   GST_VIDEO_TRANSFER_BT709,
 121   GST_VIDEO_TRANSFER_SMPTE240M,
 122   GST_VIDEO_TRANSFER_SRGB,
 123   GST_VIDEO_TRANSFER_GAMMA28,
 124   GST_VIDEO_TRANSFER_LOG100,
 125   GST_VIDEO_TRANSFER_LOG316,
 126   GST_VIDEO_TRANSFER_BT2020_12,
 127   GST_VIDEO_TRANSFER_ADOBERGB,
 128   GST_VIDEO_TRANSFER_BT2020_10,
 129   GST_VIDEO_TRANSFER_SMPTE2084,
 130   GST_VIDEO_TRANSFER_ARIB_STD_B67,
 131   /**
 132    * GST_VIDEO_TRANSFER_BT601:
 133    *
 134    * also known as SMPTE170M / ITU-R BT1358 525 or 625 / ITU-R BT1700 NTSC
 135    *
 136    * Since: 1.18
 137    */
 138   GST_VIDEO_TRANSFER_BT601
 139 } GstVideoTransferFunction;
 140
 141 GST_VIDEO_DEPRECATED_FOR(gst_video_transfer_function_encode)
 142 gdouble      gst_video_color_transfer_encode    (GstVideoTransferFunction func, gdouble val);
 143 GST_VIDEO_API
 144 gdouble      gst_video_transfer_function_encode (GstVideoTransferFunction func, gdouble val);
 145
 146 GST_VIDEO_DEPRECATED_FOR(gst_video_transfer_function_decode)
 147 gdouble      gst_video_color_transfer_decode    (GstVideoTransferFunction func, gdouble val);
 148 GST_VIDEO_API
 149 gdouble      gst_video_transfer_function_decode (GstVideoTransferFunction func, gdouble val);
 150
 151 /**
 152  * GstVideoColorPrimaries:
 153  * @GST_VIDEO_COLOR_PRIMARIES_UNKNOWN: unknown color primaries
 154  * @GST_VIDEO_COLOR_PRIMARIES_BT709: BT709 primaries, also ITU-R BT1361 / IEC
 155  * 61966-2-4 / SMPTE RP177 Annex B
 156  * @GST_VIDEO_COLOR_PRIMARIES_BT470M: BT470M primaries, also FCC Title 47 Code
 157  * of Federal Regulations 73.682 (a)(20)
 158  * @GST_VIDEO_COLOR_PRIMARIES_BT470BG: BT470BG primaries, also ITU-R BT601-6
 159  * 625 / ITU-R BT1358 625 / ITU-R BT1700 625 PAL & SECAM
 160  * @GST_VIDEO_COLOR_PRIMARIES_SMPTE170M: SMPTE170M primaries, also ITU-R
 161  * BT601-6 525 / ITU-R BT1358 525 / ITU-R BT1700 NTSC
 162  * @GST_VIDEO_COLOR_PRIMARIES_SMPTE240M: SMPTE240M primaries
 163  * @GST_VIDEO_COLOR_PRIMARIES_FILM: Generic film (colour filters using
 164  * Illuminant C)
 165  * @GST_VIDEO_COLOR_PRIMARIES_BT2020: ITU-R BT2020 primaries. Since: 1.6
 166  * @GST_VIDEO_COLOR_PRIMARIES_ADOBERGB: Adobe RGB primaries. Since: 1.8
 167  * @GST_VIDEO_COLOR_PRIMARIES_SMPTEST428: SMPTE ST 428 primaries (CIE 1931
 168  * XYZ). Since: 1.16
 169  * @GST_VIDEO_COLOR_PRIMARIES_SMPTERP431: SMPTE RP 431 primaries (ST 431-2
 170  * (2011) / DCI P3). Since: 1.16
 171  * @GST_VIDEO_COLOR_PRIMARIES_SMPTEEG432: SMPTE EG 432 primaries (ST 432-1
 172  * (2010) / P3 D65). Since: 1.16
 173  * @GST_VIDEO_COLOR_PRIMARIES_EBU3213: EBU 3213 primaries (JEDEC P22
 174  * phosphors). Since: 1.16
 175  *
 176  * The color primaries define the how to transform linear RGB values to and from
 177  * the CIE XYZ colorspace.
 178  */
 179 typedef enum {
 180   GST_VIDEO_COLOR_PRIMARIES_UNKNOWN = 0,
 181   GST_VIDEO_COLOR_PRIMARIES_BT709,
 182   GST_VIDEO_COLOR_PRIMARIES_BT470M,
 183   GST_VIDEO_COLOR_PRIMARIES_BT470BG,
 184   GST_VIDEO_COLOR_PRIMARIES_SMPTE170M,
 185   GST_VIDEO_COLOR_PRIMARIES_SMPTE240M,
 186   GST_VIDEO_COLOR_PRIMARIES_FILM,
 187   GST_VIDEO_COLOR_PRIMARIES_BT2020,
 188   GST_VIDEO_COLOR_PRIMARIES_ADOBERGB,
 189   GST_VIDEO_COLOR_PRIMARIES_SMPTEST428,
 190   GST_VIDEO_COLOR_PRIMARIES_SMPTERP431,
 191   GST_VIDEO_COLOR_PRIMARIES_SMPTEEG432,
 192   GST_VIDEO_COLOR_PRIMARIES_EBU3213,
 193 } GstVideoColorPrimaries;
 194
 195 /**
 196  * GstVideoColorPrimariesInfo:
 197  * @primaries: a #GstVideoColorPrimaries
 198  * @Wx: reference white x coordinate
 199  * @Wy: reference white y coordinate
 200  * @Rx: red x coordinate
 201  * @Ry: red y coordinate
 202  * @Gx: green x coordinate
 203  * @Gy: green y coordinate
 204  * @Bx: blue x coordinate
 205  * @By: blue y coordinate
 206  *
 207  * Structure describing the chromaticity coordinates of an RGB system. These
 208  * values can be used to construct a matrix to transform RGB to and from the
 209  * XYZ colorspace.
 210  *
 211  * Since: 1.6
 212  */
 213 typedef struct {
 214   GstVideoColorPrimaries primaries;
 215   gdouble Wx, Wy;
 216   gdouble Rx, Ry;
 217   gdouble Gx, Gy;
 218   gdouble Bx, By;
 219 } GstVideoColorPrimariesInfo;
 220
 221 GST_VIDEO_API
 222 const GstVideoColorPrimariesInfo *
 223                 gst_video_color_primaries_get_info     (GstVideoColorPrimaries primaries);
 224
 225 /**
 226  * GstVideoColorimetry:
 227  * @range: the color range. This is the valid range for the samples.
 228  *         It is used to convert the samples to Y'PbPr values.
 229  * @matrix: the color matrix. Used to convert between Y'PbPr and
 230  *          non-linear RGB (R'G'B')
 231  * @transfer: the transfer function. used to convert between R'G'B' and RGB
 232  * @primaries: color primaries. used to convert between R'G'B' and CIE XYZ
 233  *
 234  * Structure describing the color info.
 235  */
 236 typedef struct {
 237   GstVideoColorRange        range;
 238   GstVideoColorMatrix       matrix;
 239   GstVideoTransferFunction  transfer;
 240   GstVideoColorPrimaries    primaries;
 241 } GstVideoColorimetry;
 242
 243 /* predefined colorimetry */
 244 #define GST_VIDEO_COLORIMETRY_BT601       "bt601"
 245 #define GST_VIDEO_COLORIMETRY_BT709       "bt709"
 246 #define GST_VIDEO_COLORIMETRY_SMPTE240M   "smpte240m"
 247 #define GST_VIDEO_COLORIMETRY_SRGB        "sRGB"
 248 #define GST_VIDEO_COLORIMETRY_BT2020      "bt2020"
 249 #define GST_VIDEO_COLORIMETRY_BT2020_10   "bt2020-10"
 250 #define GST_VIDEO_COLORIMETRY_BT2100_PQ   "bt2100-pq"
 251 #define GST_VIDEO_COLORIMETRY_BT2100_HLG  "bt2100-hlg"
 252
 253 GST_VIDEO_API
 254 gboolean     gst_video_colorimetry_matches     (const GstVideoColorimetry *cinfo, const gchar *color);
 255
 256 GST_VIDEO_API
 257 gboolean     gst_video_colorimetry_from_string (GstVideoColorimetry *cinfo, const gchar *color);
 258
 259 GST_VIDEO_API
 260 gchar *      gst_video_colorimetry_to_string   (const GstVideoColorimetry *cinfo);
 261
 262 GST_VIDEO_API
 263 gboolean     gst_video_colorimetry_is_equal    (const GstVideoColorimetry *cinfo, const GstVideoColorimetry *other);
 264
 265 /* compute offset and scale */
 266
 267 GST_VIDEO_API
 268 void         gst_video_color_range_offsets     (GstVideoColorRange range,
 269                                                 const GstVideoFormatInfo *info,
 270                                                 gint offset[GST_VIDEO_MAX_COMPONENTS],
 271                                                 gint scale[GST_VIDEO_MAX_COMPONENTS]);
 272
 273 /* conversion between GStreamer color{matrix,transfer,primaries} enum and
 274  * values defined by ISO/IEC 23001-8 and ITU-T H.273 specification.
 275  * Also H264 and H265 specifications follow the color{matrix,transfer,primaries}
 276  * values */
 277
 278 GST_VIDEO_API
 279 guint                     gst_video_color_matrix_to_iso      (GstVideoColorMatrix matrix);
 280
 281 GST_VIDEO_API
 282 guint                     gst_video_transfer_function_to_iso    (GstVideoTransferFunction func);
 283
 284 GST_VIDEO_API
 285 guint                     gst_video_color_primaries_to_iso   (GstVideoColorPrimaries primaries);
 286
 287 GST_VIDEO_API
 288 GstVideoColorMatrix       gst_video_color_matrix_from_iso    (guint value);
 289
 290 GST_VIDEO_API
 291 GstVideoTransferFunction  gst_video_transfer_function_from_iso  (guint value);
 292
 293 GST_VIDEO_API
 294 GstVideoColorPrimaries    gst_video_color_primaries_from_iso (guint value);
 295
 296 GST_VIDEO_API
 297 gboolean                  gst_video_transfer_function_is_equivalent (GstVideoTransferFunction from_func,
 298                                                                     guint from_bpp,
 299                                                                     GstVideoTransferFunction to_func,
 300                                                                     guint to_bpp);
 301
 302 G_END_DECLS
 303
 304 #endif /* __GST_VIDEO_COLOR_H__ */