gst-libs/gst/video/video.h

   1 /* GStreamer
   2  * Copyright (C) <1999> Erik Walthinsen <omega@cse.ogi.edu>
   3  * Library       <2002> Ronald Bultje <rbultje@ronald.bitfreak.net>
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Library General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Library General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Library General Public
  16  * License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  */
  20
  21 #ifndef __GST_VIDEO_H__
  22 #define __GST_VIDEO_H__
  23
  24 #include <gst/gst.h>
  25
  26 G_BEGIN_DECLS
  27
  28 #include <gst/video/video-enumtypes.h>
  29
  30 /**
  31  * GstVideoFormat:
  32  * @GST_VIDEO_FORMAT_UNKNOWN: Unknown or unset video format id
  33  * @GST_VIDEO_FORMAT_I420: planar 4:2:0 YUV
  34  * @GST_VIDEO_FORMAT_YV12: planar 4:2:0 YVU (like I420 but UV planes swapped)
  35  * @GST_VIDEO_FORMAT_YUY2: packed 4:2:2 YUV (Y0-U0-Y1-V0 Y2-U2-Y3-V2 Y4 ...)
  36  * @GST_VIDEO_FORMAT_UYVY: packed 4:2:2 YUV (U0-Y0-V0-Y1 U2-Y2-V2-Y3 U4 ...)
  37  * @GST_VIDEO_FORMAT_AYUV: packed 4:4:4 YUV with alpha channel (A0-Y0-U0-V0 ...)
  38  * @GST_VIDEO_FORMAT_RGBx: sparse rgb packed into 32 bit, space last
  39  * @GST_VIDEO_FORMAT_BGRx: sparse reverse rgb packed into 32 bit, space last
  40  * @GST_VIDEO_FORMAT_xRGB: sparse rgb packed into 32 bit, space first
  41  * @GST_VIDEO_FORMAT_xBGR: sparse reverse rgb packed into 32 bit, space first
  42  * @GST_VIDEO_FORMAT_RGBA: rgb with alpha channel last
  43  * @GST_VIDEO_FORMAT_BGRA: reverse rgb with alpha channel last
  44  * @GST_VIDEO_FORMAT_ARGB: rgb with alpha channel first
  45  * @GST_VIDEO_FORMAT_ABGR: reverse rgb with alpha channel first
  46  * @GST_VIDEO_FORMAT_RGB: rgb
  47  * @GST_VIDEO_FORMAT_BGR: reverse rgb
  48  * @GST_VIDEO_FORMAT_Y41B: planar 4:1:1 YUV (Since: 0.10.18)
  49  * @GST_VIDEO_FORMAT_Y42B: planar 4:2:2 YUV (Since: 0.10.18)
  50  * @GST_VIDEO_FORMAT_YVYU: packed 4:2:2 YUV (Y0-V0-Y1-U0 Y2-V2-Y3-U2 Y4 ...) (Since: 0.10.23)
  51  * @GST_VIDEO_FORMAT_Y444: planar 4:4:4 YUV (Since: 0.10.24)
  52  * @GST_VIDEO_FORMAT_v210: packed 4:2:2 10-bit YUV, complex format (Since: 0.10.24)
  53  * @GST_VIDEO_FORMAT_v216: packed 4:2:2 16-bit YUV, Y0-U0-Y1-V1 order (Since: 0.10.24)
  54  * @GST_VIDEO_FORMAT_NV12: planar 4:2:0 YUV with interleaved UV plane (Since: 0.10.26)
  55  * @GST_VIDEO_FORMAT_NV21: planar 4:2:0 YUV with interleaved VU plane (Since: 0.10.26)
  56  * @GST_VIDEO_FORMAT_GRAY8: 8-bit grayscale (Since: 0.10.29)
  57  * @GST_VIDEO_FORMAT_GRAY16_BE: 16-bit grayscale, most significant byte first (Since: 0.10.29)
  58  * @GST_VIDEO_FORMAT_GRAY16_LE: 16-bit grayscale, least significant byte first (Since: 0.10.29)
  59  * @GST_VIDEO_FORMAT_v308: packed 4:4:4 YUV (Since: 0.10.29)
  60  * @GST_VIDEO_FORMAT_Y800: same as GST_VIDEO_FORMAT_GRAY8 (Since: 0.10.30)
  61  * @GST_VIDEO_FORMAT_Y16: same as GST_VIDEO_FORMAT_GRAY16_LE (Since: 0.10.30)
  62  * @GST_VIDEO_FORMAT_RGB16: rgb 5-6-5 bits per component (Since: 0.10.30)
  63  * @GST_VIDEO_FORMAT_BGR16: reverse rgb 5-6-5 bits per component (Since: 0.10.30)
  64  * @GST_VIDEO_FORMAT_RGB15: rgb 5-5-5 bits per component (Since: 0.10.30)
  65  * @GST_VIDEO_FORMAT_BGR15: reverse rgb 5-5-5 bits per component (Since: 0.10.30)
  66  * @GST_VIDEO_FORMAT_UYVP: packed 10-bit 4:2:2 YUV (U0-Y0-V0-Y1 U2-Y2-V2-Y3 U4 ...) (Since: 0.10.31)
  67  * @GST_VIDEO_FORMAT_A420: planar 4:4:2:0 AYUV (Since: 0.10.31)
  68  * @GST_VIDEO_FORMAT_RGB8_PALETTED: 8-bit paletted RGB (Since: 0.10.32)
  69  * @GST_VIDEO_FORMAT_YUV9: planar 4:1:0 YUV (Since: 0.10.32)
  70  * @GST_VIDEO_FORMAT_YVU9: planar 4:1:0 YUV (like YUV9 but UV planes swapped) (Since: 0.10.32)
  71  * @GST_VIDEO_FORMAT_IYU1: packed 4:1:1 YUV (Cb-Y0-Y1-Cr-Y2-Y3 ...) (Since: 0.10.32)
  72  * @GST_VIDEO_FORMAT_ARGB64: rgb with alpha channel first, 16 bits per channel (Since: 0.10.33)
  73  * @GST_VIDEO_FORMAT_AYUV64: packed 4:4:4 YUV with alpha channel, 16 bits per channel (A0-Y0-U0-V0 ...) (Since: 0.10.33)
  74  * @GST_VIDEO_FORMAT_r210: packed 4:4:4 RGB, 10 bits per channel (Since: 0.10.33)
  75  *
  76  * Enum value describing the most common video formats.
  77  */
  78 typedef enum {
  79   GST_VIDEO_FORMAT_UNKNOWN,
  80   GST_VIDEO_FORMAT_I420,
  81   GST_VIDEO_FORMAT_YV12,
  82   GST_VIDEO_FORMAT_YUY2,
  83   GST_VIDEO_FORMAT_UYVY,
  84   GST_VIDEO_FORMAT_AYUV,
  85   GST_VIDEO_FORMAT_RGBx,
  86   GST_VIDEO_FORMAT_BGRx,
  87   GST_VIDEO_FORMAT_xRGB,
  88   GST_VIDEO_FORMAT_xBGR,
  89   GST_VIDEO_FORMAT_RGBA,
  90   GST_VIDEO_FORMAT_BGRA,
  91   GST_VIDEO_FORMAT_ARGB,
  92   GST_VIDEO_FORMAT_ABGR,
  93   GST_VIDEO_FORMAT_RGB,
  94   GST_VIDEO_FORMAT_BGR,
  95   GST_VIDEO_FORMAT_Y41B,
  96   GST_VIDEO_FORMAT_Y42B,
  97   GST_VIDEO_FORMAT_YVYU,
  98   GST_VIDEO_FORMAT_Y444,
  99   GST_VIDEO_FORMAT_v210,
 100   GST_VIDEO_FORMAT_v216,
 101   GST_VIDEO_FORMAT_NV12,
 102   GST_VIDEO_FORMAT_NV21,
 103   GST_VIDEO_FORMAT_GRAY8,
 104   GST_VIDEO_FORMAT_GRAY16_BE,
 105   GST_VIDEO_FORMAT_GRAY16_LE,
 106   GST_VIDEO_FORMAT_v308,
 107   GST_VIDEO_FORMAT_Y800,
 108   GST_VIDEO_FORMAT_Y16,
 109   GST_VIDEO_FORMAT_RGB16,
 110   GST_VIDEO_FORMAT_BGR16,
 111   GST_VIDEO_FORMAT_RGB15,
 112   GST_VIDEO_FORMAT_BGR15,
 113   GST_VIDEO_FORMAT_UYVP,
 114   GST_VIDEO_FORMAT_A420,
 115   GST_VIDEO_FORMAT_RGB8_PALETTED,
 116   GST_VIDEO_FORMAT_YUV9,
 117   GST_VIDEO_FORMAT_YVU9,
 118   GST_VIDEO_FORMAT_IYU1,
 119   GST_VIDEO_FORMAT_ARGB64,
 120   GST_VIDEO_FORMAT_AYUV64,
 121   GST_VIDEO_FORMAT_r210
 122 } GstVideoFormat;
 123
 124 /* format properties */
 125 GstVideoFormat gst_video_format_from_masks           (gint depth, gint bpp, gint endianness,
 126                                                       gint red_mask, gint green_mask,
 127                                                       gint blue_mask, gint alpha_mask) G_GNUC_CONST;
 128
 129 GstVideoFormat gst_video_format_from_fourcc          (guint32 fourcc) G_GNUC_CONST;
 130 GstVideoFormat gst_video_format_from_string          (const gchar *format) G_GNUC_CONST;
 131
 132 guint32        gst_video_format_to_fourcc            (GstVideoFormat format) G_GNUC_CONST;
 133 const gchar *  gst_video_format_to_string            (GstVideoFormat format) G_GNUC_CONST;
 134
 135 gboolean       gst_video_format_is_rgb               (GstVideoFormat format) G_GNUC_CONST;
 136 gboolean       gst_video_format_is_yuv               (GstVideoFormat format) G_GNUC_CONST;
 137 gboolean       gst_video_format_is_gray              (GstVideoFormat format) G_GNUC_CONST;
 138 gboolean       gst_video_format_has_alpha            (GstVideoFormat format) G_GNUC_CONST;
 139
 140 int            gst_video_format_get_n_components     (GstVideoFormat format) G_GNUC_CONST;
 141 int            gst_video_format_get_component_depth  (GstVideoFormat format,
 142                                                       int            component) G_GNUC_CONST;
 143 int            gst_video_format_get_pixel_stride     (GstVideoFormat format,
 144                                                       int            component) G_GNUC_CONST;
 145
 146 typedef struct _GstVideoPlane GstVideoPlane;
 147 typedef struct _GstVideoInfo GstVideoInfo;
 148
 149 /**
 150  * GstVideoFlags:
 151  * @GST_META_VIDEO_FLAG_NONE: no flags
 152  * @GST_META_VIDEO_FLAG_INTERLACED:
 153  * @GST_META_VIDEO_FLAG_TTF:
 154  * @GST_META_VIDEO_FLAG_RFF:
 155  * @GST_META_VIDEO_FLAG_ONEFIELD:
 156  * @GST_META_VIDEO_FLAG_TELECINE:
 157  * @GST_META_VIDEO_FLAG_PROGRESSIVE:
 158  *
 159  * Extra video flags
 160  */
 161 typedef enum {
 162   GST_VIDEO_FLAG_NONE        = 0,
 163   GST_VIDEO_FLAG_INTERLACED  = (1 << 0),
 164   GST_VIDEO_FLAG_TTF         = (1 << 1),
 165   GST_VIDEO_FLAG_RFF         = (1 << 2),
 166   GST_VIDEO_FLAG_ONEFIELD    = (1 << 3),
 167   GST_VIDEO_FLAG_TELECINE    = (1 << 4),
 168   GST_VIDEO_FLAG_PROGRESSIVE = (1 << 5)
 169 } GstVideoFlags;
 170
 171 #define GST_VIDEO_MAX_PLANES 4
 172
 173 /**
 174  * GstVideoPlane:
 175  * @offset: offset of the first pixel in the buffer memory region
 176  * @stride: stride of the image lines. Can be negative when the image is
 177  *    upside-down
 178  *
 179  * Information for one video plane.
 180  */
 181 struct _GstVideoPlane {
 182   gsize           offset;
 183   gint            stride;
 184 };
 185
 186 /**
 187  * GstVideoInfo:
 188  * @flags: additional video flags
 189  * @format: the format of the video
 190  * @width: the width of the video
 191  * @height: the height of the video
 192  * @size: the size of one frame
 193  * @color_matrix: the color matrix.  Possible values are
 194  *   "sdtv" for the standard definition color matrix (as specified in
 195  *   Rec. ITU-R BT.470-6) or "hdtv" for the high definition color
 196  *   matrix (as specified in Rec. ITU-R BT.709)
 197  * @chroma_site: the chroma siting. Possible values are
 198  *   "mpeg2" for MPEG-2 style chroma siting (co-sited horizontally,
 199  *   halfway-sited vertically), "jpeg" for JPEG and Theora style
 200  *   chroma siting (halfway-sited both horizontally and vertically).
 201  *   Other chroma site values are possible, but uncommon.
 202  * @par_n: the pixel-aspect-ratio numerator
 203  * @par_d: the pixel-aspect-ratio demnominator
 204  * @fps_n: the framerate numerator
 205  * @fps_d: the framerate demnominator
 206  * @n_planes: the number of planes in the image
 207  * @plane: array of #GstMetaVideoPlane
 208  *
 209  * Extra buffer metadata describing image properties
 210  */
 211 struct _GstVideoInfo {
 212   GstVideoFormat format;
 213   GstVideoFlags  flags;
 214   guint          width;
 215   guint          height;
 216   guint          size;
 217
 218   const gchar   *color_matrix;
 219   const gchar   *chroma_site;
 220
 221   guint          par_n;
 222   guint          par_d;
 223   guint          fps_n;
 224   guint          fps_d;
 225
 226   guint          n_planes;
 227   GstVideoPlane  plane[GST_VIDEO_MAX_PLANES];
 228 };
 229
 230
 231 void         gst_video_info_init        (GstVideoInfo *info);
 232
 233 void         gst_video_info_set_format  (GstVideoInfo *info, GstVideoFormat format,
 234                                          guint width, guint height);
 235
 236 gboolean     gst_video_info_from_caps   (GstVideoInfo *info, const GstCaps  * caps);
 237
 238 GstCaps *    gst_video_info_to_caps     (GstVideoInfo *info);
 239
 240 gboolean     gst_video_info_convert     (GstVideoInfo *info,
 241                                          GstFormat     src_format,
 242                                          gint64        src_value,
 243                                          GstFormat     dest_format,
 244                                          gint64       *dest_value);
 245
 246 #define GST_VIDEO_SIZE_RANGE "(int) [ 1, max ]"
 247 #define GST_VIDEO_FPS_RANGE "(fraction) [ 0, max ]"
 248
 249 #define GST_VIDEO_FORMATS_ALL "{ \"I420\"," "\"YV12\"," "\"YUY2\"," "\"UYVY\"," "\"AYUV\"," "\"RGBx\"," \
 250     "\"BGRx\"," "\"xRGB\"," "\"xBGR\"," "\"RGBA\"," "\"BGRA\"," "\"ARGB\"," "\"ABGR\"," "\"RGB\"," \
 251     "\"BGR\"," "\"Y41B\"," "\"Y42B\"," "\"YVYU\"," "\"Y444\"," "\"v210\"," "\"v216\"," "\"NV12\"," \
 252     "\"NV21\"," "\"GRAY8\"," "\"GRAY16_BE\"," "\"GRAY16_LE\"," "\"v308\"," "\"Y800\"," "\"Y16\"," \
 253     "\"RGB16\"," "\"BGR16\"," "\"RGB15\"," "\"BGR15\"," "\"UYVP\"," "\"A420\"," "\"RGB8_PALETTED\"," \
 254     "\"YUV9\"," "\"YVU9\"," "\"IYU1\"," "\"ARGB64\"," "\"AYUV64\"," "\"r210\" } "
 255
 256 /**
 257  * GST_VIDEO_CAPS_MAKE:
 258  * @format: string format that describes the pixel layout, as string
 259  *     (e.g. "I420", "RGB", "YV12", "YUY2", "AYUV", etc.)
 260  *
 261  * Generic caps string for video, for use in pad templates.
 262  */
 263 #define GST_VIDEO_CAPS_MAKE(format)                                     \
 264     "video/x-raw, "                                                     \
 265     "format = (string) " format ", "                                    \
 266     "width = " GST_VIDEO_SIZE_RANGE ", "                                \
 267     "height = " GST_VIDEO_SIZE_RANGE ", "                               \
 268     "framerate = " GST_VIDEO_FPS_RANGE
 269
 270 /* buffer flags */
 271
 272 /**
 273  * GST_VIDEO_BUFFER_TFF:
 274  *
 275  * If the #GstBuffer is interlaced, then the first field in the video frame is
 276  * the top field.  If unset, the bottom field is first.
 277  *
 278  * Since: 0.10.23
 279  */
 280 #define GST_VIDEO_BUFFER_TFF GST_BUFFER_FLAG_MEDIA1
 281
 282 /**
 283  * GST_VIDEO_BUFFER_RFF:
 284  *
 285  * If the #GstBuffer is interlaced, then the first field (as defined by the
 286  * %GST_VIDEO_BUFFER_TFF flag setting) is repeated.
 287  *
 288  * Since: 0.10.23
 289  */
 290 #define GST_VIDEO_BUFFER_RFF GST_BUFFER_FLAG_MEDIA2
 291
 292 /**
 293  * GST_VIDEO_BUFFER_ONEFIELD:
 294  *
 295  * If the #GstBuffer is interlaced, then only the first field (as defined by the
 296  * %GST_VIDEO_BUFFER_TFF flag setting) is to be displayed.
 297  *
 298  * Since: 0.10.23
 299  */
 300 #define GST_VIDEO_BUFFER_ONEFIELD GST_BUFFER_FLAG_MEDIA3
 301
 302 /**
 303  * GST_VIDEO_BUFFER_PROGRESSIVE:
 304  *
 305  * If the #GstBuffer is telecined, then the buffer is progressive if the
 306  * %GST_VIDEO_BUFFER_PROGRESSIVE flag is set, else it is telecine mixed.
 307  *
 308  * Since: 0.10.33
 309  */
 310 #define GST_VIDEO_BUFFER_PROGRESSIVE GST_BUFFER_FLAG_MEDIA4
 311
 312 /* functions */
 313 gboolean       gst_video_calculate_display_ratio (guint * dar_n,
 314                                                   guint * dar_d,
 315                                                   guint   video_width,
 316                                                   guint   video_height,
 317                                                   guint   video_par_n,
 318                                                   guint   video_par_d,
 319                                                   guint   display_par_n,
 320                                                   guint   display_par_d);
 321
 322 #if 0
 323 int            gst_video_format_get_component_width  (GstVideoFormat format,
 324                                                       int            component,
 325                                                       int            width) G_GNUC_CONST;
 326
 327 int            gst_video_format_get_component_height (GstVideoFormat format,
 328                                                       int            component,
 329                                                       int            height) G_GNUC_CONST;
 330
 331 int            gst_video_format_get_component_offset (GstVideoFormat format,
 332                                                       int            component,
 333                                                       int            width,
 334                                                       int            height) G_GNUC_CONST;
 335
 336 int            gst_video_format_get_size             (GstVideoFormat format,
 337                                                       int            width,
 338                                                       int            height) G_GNUC_CONST;
 339
 340 gboolean       gst_video_get_size_from_caps (const GstCaps * caps, gint * size);
 341 #endif
 342
 343
 344 /* video still frame event creation and parsing */
 345
 346 GstEvent *     gst_video_event_new_still_frame   (gboolean in_still);
 347
 348 gboolean       gst_video_event_parse_still_frame (GstEvent * event, gboolean * in_still);
 349
 350
 351 /* convert/encode video frame from one format to another */
 352
 353 typedef void (*GstVideoConvertFrameCallback) (GstBuffer * buf, GError *error, gpointer user_data);
 354
 355 void           gst_video_convert_frame_async (GstBuffer                    * buf,
 356                                               GstCaps                      * from_caps,
 357                                               const GstCaps                * to_caps,
 358                                               GstClockTime                   timeout,
 359                                               GstVideoConvertFrameCallback   callback,
 360                                               gpointer                       user_data,
 361                                               GDestroyNotify                 destroy_notify);
 362
 363 GstBuffer *    gst_video_convert_frame       (GstBuffer     * buf,
 364                                               GstCaps       * from_caps,
 365                                               const GstCaps * to_caps,
 366                                               GstClockTime    timeout,
 367                                               GError       ** error);
 368 G_END_DECLS
 369
 370 #endif /* __GST_VIDEO_H__ */