gst-libs/gst/video/video-info.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_INFO_H__
  21 #define __GST_VIDEO_INFO_H__
  22
  23 #include <gst/gst.h>
  24 #include <gst/video/video-format.h>
  25 #include <gst/video/video-color.h>
  26
  27 G_BEGIN_DECLS
  28
  29 #include <gst/video/video-enumtypes.h>
  30
  31 typedef struct _GstVideoInfo GstVideoInfo;
  32
  33 /**
  34  * GstVideoInterlaceMode:
  35  * @GST_VIDEO_INTERLACE_MODE_PROGRESSIVE: all frames are progressive
  36  * @GST_VIDEO_INTERLACE_MODE_INTERLEAVED: 2 fields are interleaved in one video
  37  *     frame. Extra buffer flags describe the field order.
  38  * @GST_VIDEO_INTERLACE_MODE_MIXED: frames contains both interlaced and
  39  *     progressive video, the buffer flags describe the frame and fields.
  40  * @GST_VIDEO_INTERLACE_MODE_FIELDS: 2 fields are stored in one buffer, use the
  41  *     frame ID to get access to the required field. For multiview (the
  42  *     'views' property > 1) the fields of view N can be found at frame ID
  43  *     (N * 2) and (N * 2) + 1.
  44  *     Each field has only half the amount of lines as noted in the
  45  *     height property. This mode requires multiple GstVideoMeta metadata
  46  *     to describe the fields.
  47  *
  48  * The possible values of the #GstVideoInterlaceMode describing the interlace
  49  * mode of the stream.
  50  */
  51 typedef enum {
  52   GST_VIDEO_INTERLACE_MODE_PROGRESSIVE = 0,
  53   GST_VIDEO_INTERLACE_MODE_INTERLEAVED,
  54   GST_VIDEO_INTERLACE_MODE_MIXED,
  55   GST_VIDEO_INTERLACE_MODE_FIELDS
  56 } GstVideoInterlaceMode;
  57
  58 const gchar *          gst_video_interlace_mode_to_string    (GstVideoInterlaceMode mode);
  59 GstVideoInterlaceMode  gst_video_interlace_mode_from_string  (const gchar * mode);
  60
  61 /**
  62  * GstVideoMultiviewMode:
  63  * @GST_VIDEO_MULTIVIEW_MODE_NONE: A special value indicating
  64  * no multiview information. Used in GstVideoInfo and other places to
  65  * indicate that no specific multiview handling has been requested or
  66  * provided. This value is never carried on caps.
  67  * @GST_VIDEO_MULTIVIEW_MODE_MONO: All frames are monoscopic.
  68  * @GST_VIDEO_MULTIVIEW_MODE_LEFT: All frames represent a left-eye view.
  69  * @GST_VIDEO_MULTIVIEW_MODE_RIGHT: All frames represent a right-eye view.
  70  * @GST_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE: Left and right eye views are
  71  * provided in the left and right half of the frame respectively.
  72  * @GST_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE_QUINCUNX: Left and right eye
  73  * views are provided in the left and right half of the frame, but
  74  * have been sampled using quincunx method, with half-pixel offset
  75  * between the 2 views.
  76  * @GST_VIDEO_MULTIVIEW_MODE_COLUMN_INTERLEAVED: Alternating vertical
  77  * columns of pixels represent the left and right eye view respectively.
  78  * @GST_VIDEO_MULTIVIEW_MODE_ROW_INTERLEAVED: Alternating horizontal
  79  * rows of pixels represent the left and right eye view respectively.
  80  * @GST_VIDEO_MULTIVIEW_MODE_TOP_BOTTOM: The top half of the frame
  81  * contains the left eye, and the bottom half the right eye.
  82  * @GST_VIDEO_MULTIVIEW_MODE_CHECKERBOARD: Pixels are arranged with
  83  * alternating pixels representing left and right eye views in a
  84  * checkerboard fashion.
  85  * @GST_VIDEO_MULTIVIEW_MODE_FRAME_BY_FRAME: Left and right eye views
  86  * are provided in separate frames alternately.
  87  * @GST_VIDEO_MULTIVIEW_MODE_MULTIVIEW_FRAME_BY_FRAME: Multiple
  88  * independent views are provided in separate frames in sequence.
  89  * This method only applies to raw video buffers at the moment.
  90  * Specific view identification is via the #GstVideoMultiviewMeta
  91  * and #GstVideoMeta(s) on raw video buffers.
  92  * @GST_VIDEO_MULTIVIEW_MODE_SEPARATED: Multiple views are
  93  * provided as separate #GstMemory framebuffers attached to each
  94  * #GstBuffer, described by the #GstVideoMultiviewMeta
  95  * and #GstVideoMeta(s)
  96  *
  97  * All possible stereoscopic 3D and multiview representations.
  98  * In conjunction with #GstVideoMultiviewFlags, describes how
  99  * multiview content is being transported in the stream.
 100  */
 101 typedef enum {
 102   GST_VIDEO_MULTIVIEW_MODE_NONE = -1,
 103   GST_VIDEO_MULTIVIEW_MODE_MONO = 0,
 104   /* Single view modes */
 105   GST_VIDEO_MULTIVIEW_MODE_LEFT,
 106   GST_VIDEO_MULTIVIEW_MODE_RIGHT,
 107   /* Stereo view modes */
 108   GST_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE,
 109   GST_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE_QUINCUNX,
 110   GST_VIDEO_MULTIVIEW_MODE_COLUMN_INTERLEAVED,
 111   GST_VIDEO_MULTIVIEW_MODE_ROW_INTERLEAVED,
 112   GST_VIDEO_MULTIVIEW_MODE_TOP_BOTTOM,
 113   GST_VIDEO_MULTIVIEW_MODE_CHECKERBOARD,
 114   /* Padding for new frame packing modes */
 115
 116   GST_VIDEO_MULTIVIEW_MODE_FRAME_BY_FRAME = 32,
 117   /* Multivew mode(s) */
 118   GST_VIDEO_MULTIVIEW_MODE_MULTIVIEW_FRAME_BY_FRAME,
 119   GST_VIDEO_MULTIVIEW_MODE_SEPARATED
 120   /* future expansion for annotated modes */
 121 } GstVideoMultiviewMode;
 122
 123 /**
 124  * GstVideoMultiviewFramePacking:
 125  * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_NONE: A special value indicating
 126  * no frame packing info.
 127  * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_MONO: All frames are monoscopic.
 128  * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_LEFT: All frames represent a left-eye view.
 129  * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_RIGHT: All frames represent a right-eye view.
 130  * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_SIDE_BY_SIDE: Left and right eye views are
 131  * provided in the left and right half of the frame respectively.
 132  * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_SIDE_BY_SIDE_QUINCUNX: Left and right eye
 133  * views are provided in the left and right half of the frame, but
 134  * have been sampled using quincunx method, with half-pixel offset
 135  * between the 2 views.
 136  * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_COLUMN_INTERLEAVED: Alternating vertical
 137  * columns of pixels represent the left and right eye view respectively.
 138  * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_ROW_INTERLEAVED: Alternating horizontal
 139  * rows of pixels represent the left and right eye view respectively.
 140  * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_TOP_BOTTOM: The top half of the frame
 141  * contains the left eye, and the bottom half the right eye.
 142  * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_CHECKERBOARD: Pixels are arranged with
 143  * alternating pixels representing left and right eye views in a
 144  * checkerboard fashion.
 145  *
 146  * #GstVideoMultiviewFramePacking represents the subset of #GstVideoMultiviewMode
 147  * values that can be applied to any video frame without needing extra metadata.
 148  * It can be used by elements that provide a property to override the
 149  * multiview interpretation of a video stream when the video doesn't contain
 150  * any markers.
 151  *
 152  * This enum is used (for example) on playbin, to re-interpret a played
 153  * video stream as a stereoscopic video. The individual enum values are
 154  * equivalent to and have the same value as the matching #GstVideoMultiviewMode.
 155  *
 156  */
 157 typedef enum {
 158   GST_VIDEO_MULTIVIEW_FRAME_PACKING_NONE = GST_VIDEO_MULTIVIEW_MODE_NONE,
 159   GST_VIDEO_MULTIVIEW_FRAME_PACKING_MONO = GST_VIDEO_MULTIVIEW_MODE_MONO,
 160   GST_VIDEO_MULTIVIEW_FRAME_PACKING_LEFT = GST_VIDEO_MULTIVIEW_MODE_LEFT,
 161   GST_VIDEO_MULTIVIEW_FRAME_PACKING_RIGHT = GST_VIDEO_MULTIVIEW_MODE_RIGHT,
 162   GST_VIDEO_MULTIVIEW_FRAME_PACKING_SIDE_BY_SIDE = GST_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE,
 163   GST_VIDEO_MULTIVIEW_FRAME_PACKING_SIDE_BY_SIDE_QUINCUNX = GST_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE_QUINCUNX,
 164   GST_VIDEO_MULTIVIEW_FRAME_PACKING_COLUMN_INTERLEAVED = GST_VIDEO_MULTIVIEW_MODE_COLUMN_INTERLEAVED,
 165   GST_VIDEO_MULTIVIEW_FRAME_PACKING_ROW_INTERLEAVED = GST_VIDEO_MULTIVIEW_MODE_ROW_INTERLEAVED,
 166   GST_VIDEO_MULTIVIEW_FRAME_PACKING_TOP_BOTTOM = GST_VIDEO_MULTIVIEW_MODE_TOP_BOTTOM,
 167   GST_VIDEO_MULTIVIEW_FRAME_PACKING_CHECKERBOARD = GST_VIDEO_MULTIVIEW_MODE_CHECKERBOARD
 168 } GstVideoMultiviewFramePacking;
 169
 170 #define GST_VIDEO_MULTIVIEW_MAX_FRAME_PACKING GST_VIDEO_MULTIVIEW_FRAME_PACKING_CHECKERBOARD
 171
 172 /**
 173  * GstVideoMultiviewFlags:
 174  * @GST_VIDEO_MULTIVIEW_FLAGS_NONE: No flags
 175  * @GST_VIDEO_MULTIVIEW_FLAGS_RIGHT_VIEW_FIRST: For stereo streams, the
 176  *     normal arrangement of left and right views is reversed.
 177  * @GST_VIDEO_MULTIVIEW_FLAGS_LEFT_FLIPPED: The left view is vertically
 178  *     mirrored.
 179  * @GST_VIDEO_MULTIVIEW_FLAGS_LEFT_FLOPPED: The left view is horizontally
 180  *     mirrored.
 181  * @GST_VIDEO_MULTIVIEW_FLAGS_RIGHT_FLIPPED: The right view is
 182  *     vertically mirrored.
 183  * @GST_VIDEO_MULTIVIEW_FLAGS_RIGHT_FLOPPED: The right view is
 184  *     horizontally mirrored.
 185  * @GST_VIDEO_MULTIVIEW_FLAGS_HALF_ASPECT: For frame-packed
 186  *     multiview modes, indicates that the individual
 187  *     views have been encoded with half the true width or height
 188  *     and should be scaled back up for display. This flag
 189  *     is used for overriding input layout interpretation
 190  *     by adjusting pixel-aspect-ratio.
 191  *     For side-by-side, column interleaved or checkerboard packings, the
 192  *     pixel width will be doubled. For row interleaved and top-bottom
 193  *     encodings, pixel height will be doubled.
 194  * @GST_VIDEO_MULTIVIEW_FLAGS_MIXED_MONO: The video stream contains both
 195  *     mono and multiview portions, signalled on each buffer by the
 196  *     absence or presence of the @GST_VIDEO_BUFFER_FLAG_MULTIPLE_VIEW
 197  *     buffer flag.
 198  *
 199  * GstVideoMultiviewFlags are used to indicate extra properties of a
 200  * stereo/multiview stream beyond the frame layout and buffer mapping
 201  * that is conveyed in the #GstMultiviewMode.
 202  */
 203 typedef enum {
 204   GST_VIDEO_MULTIVIEW_FLAGS_NONE             = 0,
 205   GST_VIDEO_MULTIVIEW_FLAGS_RIGHT_VIEW_FIRST = (1 << 0),
 206   GST_VIDEO_MULTIVIEW_FLAGS_LEFT_FLIPPED     = (1 << 1),
 207   GST_VIDEO_MULTIVIEW_FLAGS_LEFT_FLOPPED     = (1 << 2),
 208   GST_VIDEO_MULTIVIEW_FLAGS_RIGHT_FLIPPED    = (1 << 3),
 209   GST_VIDEO_MULTIVIEW_FLAGS_RIGHT_FLOPPED    = (1 << 4),
 210   GST_VIDEO_MULTIVIEW_FLAGS_HALF_ASPECT      = (1 << 14),
 211   GST_VIDEO_MULTIVIEW_FLAGS_MIXED_MONO       = (1 << 15)
 212 } GstVideoMultiviewFlags;
 213
 214 /**
 215  * GstVideoFlags:
 216  * @GST_VIDEO_FLAG_NONE: no flags
 217  * @GST_VIDEO_FLAG_VARIABLE_FPS: a variable fps is selected, fps_n and fps_d
 218  *     denote the maximum fps of the video
 219  * @GST_VIDEO_FLAG_PREMULTIPLIED_ALPHA: Each color has been scaled by the alpha
 220  *     value.
 221  *
 222  * Extra video flags
 223  */
 224 typedef enum {
 225   GST_VIDEO_FLAG_NONE                = 0,
 226   GST_VIDEO_FLAG_VARIABLE_FPS        = (1 << 0),
 227   GST_VIDEO_FLAG_PREMULTIPLIED_ALPHA = (1 << 1)
 228 } GstVideoFlags;
 229
 230 /**
 231  * GstVideoInfo:
 232  * @finfo: the format info of the video
 233  * @interlace_mode: the interlace mode
 234  * @flags: additional video flags
 235  * @width: the width of the video
 236  * @height: the height of the video
 237  * @views: the number of views for multiview video
 238  * @size: the default size of one frame
 239  * @chroma_site: a #GstVideoChromaSite.
 240  * @colorimetry: the colorimetry info
 241  * @par_n: the pixel-aspect-ratio numerator
 242  * @par_d: the pixel-aspect-ratio demnominator
 243  * @fps_n: the framerate numerator
 244  * @fps_d: the framerate demnominator
 245  * @offset: offsets of the planes
 246  * @stride: strides of the planes
 247  * @multiview_mode: delivery mode for multiple views. (Since 1.6)
 248  * @multiview_flags: flags for multiple views configuration (Since 1.6)
 249  *
 250  * Information describing image properties. This information can be filled
 251  * in from GstCaps with gst_video_info_from_caps(). The information is also used
 252  * to store the specific video info when mapping a video frame with
 253  * gst_video_frame_map().
 254  *
 255  * Use the provided macros to access the info in this structure.
 256  */
 257 struct _GstVideoInfo {
 258   const GstVideoFormatInfo *finfo;
 259
 260   GstVideoInterlaceMode     interlace_mode;
 261   GstVideoFlags             flags;
 262   gint                      width;
 263   gint                      height;
 264   gsize                     size;
 265   gint                      views;
 266
 267   GstVideoChromaSite        chroma_site;
 268   GstVideoColorimetry       colorimetry;
 269
 270   gint                      par_n;
 271   gint                      par_d;
 272   gint                      fps_n;
 273   gint                      fps_d;
 274
 275   gsize                     offset[GST_VIDEO_MAX_PLANES];
 276   gint                      stride[GST_VIDEO_MAX_PLANES];
 277
 278   /* Union preserves padded struct size for backwards compat
 279    * Consumer code should use the accessor macros for fields */
 280   union {
 281     struct {
 282       GstVideoMultiviewMode     multiview_mode;
 283       GstVideoMultiviewFlags    multiview_flags;
 284     } abi;
 285     /*< private >*/
 286     gpointer _gst_reserved[GST_PADDING];
 287   } ABI;
 288 };
 289
 290 GType gst_video_info_get_type            (void);
 291
 292 /* general info */
 293 #define GST_VIDEO_INFO_FORMAT(i)         (GST_VIDEO_FORMAT_INFO_FORMAT((i)->finfo))
 294 #define GST_VIDEO_INFO_NAME(i)           (GST_VIDEO_FORMAT_INFO_NAME((i)->finfo))
 295 #define GST_VIDEO_INFO_IS_YUV(i)         (GST_VIDEO_FORMAT_INFO_IS_YUV((i)->finfo))
 296 #define GST_VIDEO_INFO_IS_RGB(i)         (GST_VIDEO_FORMAT_INFO_IS_RGB((i)->finfo))
 297 #define GST_VIDEO_INFO_IS_GRAY(i)        (GST_VIDEO_FORMAT_INFO_IS_GRAY((i)->finfo))
 298 #define GST_VIDEO_INFO_HAS_ALPHA(i)      (GST_VIDEO_FORMAT_INFO_HAS_ALPHA((i)->finfo))
 299
 300 #define GST_VIDEO_INFO_INTERLACE_MODE(i) ((i)->interlace_mode)
 301 #define GST_VIDEO_INFO_IS_INTERLACED(i)  ((i)->interlace_mode != GST_VIDEO_INTERLACE_MODE_PROGRESSIVE)
 302 #define GST_VIDEO_INFO_FLAGS(i)          ((i)->flags)
 303 #define GST_VIDEO_INFO_WIDTH(i)          ((i)->width)
 304 #define GST_VIDEO_INFO_HEIGHT(i)         ((i)->height)
 305 #define GST_VIDEO_INFO_SIZE(i)           ((i)->size)
 306 #define GST_VIDEO_INFO_VIEWS(i)          ((i)->views)
 307 #define GST_VIDEO_INFO_PAR_N(i)          ((i)->par_n)
 308 #define GST_VIDEO_INFO_PAR_D(i)          ((i)->par_d)
 309 #define GST_VIDEO_INFO_FPS_N(i)          ((i)->fps_n)
 310 #define GST_VIDEO_INFO_FPS_D(i)          ((i)->fps_d)
 311
 312 #define GST_VIDEO_INFO_COLORIMETRY(i) ((i)->colorimetry)
 313 #define GST_VIDEO_INFO_CHROMA_SITE(i) ((i)->chroma_site)
 314
 315 #define GST_VIDEO_INFO_MULTIVIEW_MODE(i)          ((i)->ABI.abi.multiview_mode)
 316 #define GST_VIDEO_INFO_MULTIVIEW_FLAGS(i)          ((i)->ABI.abi.multiview_flags)
 317
 318 /* dealing with GstVideoInfo flags */
 319 #define GST_VIDEO_INFO_FLAG_IS_SET(i,flag) ((GST_VIDEO_INFO_FLAGS(i) & (flag)) == (flag))
 320 #define GST_VIDEO_INFO_FLAG_SET(i,flag)    (GST_VIDEO_INFO_FLAGS(i) |= (flag))
 321 #define GST_VIDEO_INFO_FLAG_UNSET(i,flag)  (GST_VIDEO_INFO_FLAGS(i) &= ~(flag))
 322
 323 /* dealing with planes */
 324 #define GST_VIDEO_INFO_N_PLANES(i)       (GST_VIDEO_FORMAT_INFO_N_PLANES((i)->finfo))
 325 #define GST_VIDEO_INFO_PLANE_OFFSET(i,p) ((i)->offset[p])
 326 #define GST_VIDEO_INFO_PLANE_STRIDE(i,p) ((i)->stride[p])
 327
 328 /* dealing with components */
 329 #define GST_VIDEO_INFO_N_COMPONENTS(i)   GST_VIDEO_FORMAT_INFO_N_COMPONENTS((i)->finfo)
 330 #define GST_VIDEO_INFO_COMP_DEPTH(i,c)   GST_VIDEO_FORMAT_INFO_DEPTH((i)->finfo,(c))
 331 #define GST_VIDEO_INFO_COMP_DATA(i,d,c)  GST_VIDEO_FORMAT_INFO_DATA((i)->finfo,d,(c))
 332 #define GST_VIDEO_INFO_COMP_OFFSET(i,c)  GST_VIDEO_FORMAT_INFO_OFFSET((i)->finfo,(i)->offset,(c))
 333 #define GST_VIDEO_INFO_COMP_STRIDE(i,c)  GST_VIDEO_FORMAT_INFO_STRIDE((i)->finfo,(i)->stride,(c))
 334 #define GST_VIDEO_INFO_COMP_WIDTH(i,c)   GST_VIDEO_FORMAT_INFO_SCALE_WIDTH((i)->finfo,(c),(i)->width)
 335 #define GST_VIDEO_INFO_COMP_HEIGHT(i,c)  GST_VIDEO_FORMAT_INFO_SCALE_HEIGHT((i)->finfo,(c),(i)->height)
 336 #define GST_VIDEO_INFO_COMP_PLANE(i,c)   GST_VIDEO_FORMAT_INFO_PLANE((i)->finfo,(c))
 337 #define GST_VIDEO_INFO_COMP_PSTRIDE(i,c) GST_VIDEO_FORMAT_INFO_PSTRIDE((i)->finfo,(c))
 338 #define GST_VIDEO_INFO_COMP_POFFSET(i,c) GST_VIDEO_FORMAT_INFO_POFFSET((i)->finfo,(c))
 339
 340 GstVideoInfo * gst_video_info_new         (void);
 341 void           gst_video_info_init        (GstVideoInfo *info);
 342 GstVideoInfo * gst_video_info_copy        (const GstVideoInfo *info);
 343 void           gst_video_info_free        (GstVideoInfo *info);
 344
 345 void           gst_video_info_set_format  (GstVideoInfo *info, GstVideoFormat format,
 346                                            guint width, guint height);
 347
 348 gboolean       gst_video_info_from_caps   (GstVideoInfo *info, const GstCaps  * caps);
 349
 350 GstCaps *      gst_video_info_to_caps     (GstVideoInfo *info);
 351
 352 gboolean       gst_video_info_convert     (GstVideoInfo *info,
 353                                            GstFormat     src_format,
 354                                            gint64        src_value,
 355                                            GstFormat     dest_format,
 356                                            gint64       *dest_value);
 357 gboolean       gst_video_info_is_equal    (const GstVideoInfo *info,
 358                                            const GstVideoInfo *other);
 359
 360 #include <gst/video/video.h>
 361
 362 void           gst_video_info_align       (GstVideoInfo * info, GstVideoAlignment * align);
 363
 364
 365 G_END_DECLS
 366
 367 #endif /* __GST_VIDEO_INFO_H__ */