gst-libs/gst/video/video-frame.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_FRAME_H__
  21 #define __GST_VIDEO_FRAME_H__
  22
  23 #include <gst/video/video-enumtypes.h>
  24
  25 G_BEGIN_DECLS
  26
  27 typedef struct _GstVideoFrame GstVideoFrame;
  28
  29 /**
  30  * GstVideoFrameFlags:
  31  * @GST_VIDEO_FRAME_FLAG_NONE: no flags
  32  * @GST_VIDEO_FRAME_FLAG_INTERLACED: The video frame is interlaced. In mixed
  33  *           interlace-mode, this flag specifies if the frame is interlaced or
  34  *           progressive.
  35  * @GST_VIDEO_FRAME_FLAG_TFF: The video frame has the top field first
  36  * @GST_VIDEO_FRAME_FLAG_RFF: The video frame has the repeat flag
  37  * @GST_VIDEO_FRAME_FLAG_ONEFIELD: The video frame has one field
  38  * @GST_VIDEO_FRAME_FLAG_MULTIPLE_VIEW: The video contains one or
  39  *     more non-mono views
  40  * @GST_VIDEO_FRAME_FLAG_FIRST_IN_BUNDLE: The video frame is the first
  41  *     in a set of corresponding views provided as sequential frames.
  42  *
  43  * Extra video frame flags
  44  */
  45 typedef enum {
  46   GST_VIDEO_FRAME_FLAG_NONE         = 0,
  47   GST_VIDEO_FRAME_FLAG_INTERLACED   = (1 << 0),
  48   GST_VIDEO_FRAME_FLAG_TFF          = (1 << 1),
  49   GST_VIDEO_FRAME_FLAG_RFF          = (1 << 2),
  50   GST_VIDEO_FRAME_FLAG_ONEFIELD     = (1 << 3),
  51   GST_VIDEO_FRAME_FLAG_MULTIPLE_VIEW = (1 << 4),
  52   GST_VIDEO_FRAME_FLAG_FIRST_IN_BUNDLE = (1 << 5)
  53 } GstVideoFrameFlags;
  54
  55 /* circular dependency, need to include this after defining the enums */
  56 #include <gst/video/video-format.h>
  57 #include <gst/video/video-info.h>
  58
  59 /**
  60  * GstVideoFrame:
  61  * @info: the #GstVideoInfo
  62  * @flags: #GstVideoFrameFlags for the frame
  63  * @buffer: the mapped buffer
  64  * @meta: pointer to metadata if any
  65  * @id: id of the mapped frame. the id can for example be used to
  66  *   indentify the frame in case of multiview video.
  67  * @data: pointers to the plane data
  68  * @map: mappings of the planes
  69  *
  70  * A video frame obtained from gst_video_frame_map()
  71  */
  72 struct _GstVideoFrame {
  73   GstVideoInfo info;
  74   GstVideoFrameFlags flags;
  75
  76   GstBuffer *buffer;
  77   gpointer   meta;
  78   gint       id;
  79
  80   gpointer   data[GST_VIDEO_MAX_PLANES];
  81   GstMapInfo map[GST_VIDEO_MAX_PLANES];
  82
  83   /*< private >*/
  84   gpointer _gst_reserved[GST_PADDING];
  85 };
  86
  87 GST_VIDEO_API
  88 gboolean    gst_video_frame_map           (GstVideoFrame *frame, GstVideoInfo *info,
  89                                            GstBuffer *buffer, GstMapFlags flags);
  90
  91 GST_VIDEO_API
  92 gboolean    gst_video_frame_map_id        (GstVideoFrame *frame, GstVideoInfo *info,
  93                                            GstBuffer *buffer, gint id, GstMapFlags flags);
  94
  95 GST_VIDEO_API
  96 void        gst_video_frame_unmap         (GstVideoFrame *frame);
  97
  98 GST_VIDEO_API
  99 gboolean    gst_video_frame_copy          (GstVideoFrame *dest, const GstVideoFrame *src);
 100
 101 GST_VIDEO_API
 102 gboolean    gst_video_frame_copy_plane    (GstVideoFrame *dest, const GstVideoFrame *src,
 103                                            guint plane);
 104
 105 /* general info */
 106 #define GST_VIDEO_FRAME_FORMAT(f)         (GST_VIDEO_INFO_FORMAT(&(f)->info))
 107 #define GST_VIDEO_FRAME_WIDTH(f)          (GST_VIDEO_INFO_WIDTH(&(f)->info))
 108 #define GST_VIDEO_FRAME_HEIGHT(f)         (GST_VIDEO_INFO_HEIGHT(&(f)->info))
 109 #define GST_VIDEO_FRAME_SIZE(f)           (GST_VIDEO_INFO_SIZE(&(f)->info))
 110
 111 /* flags */
 112 #define GST_VIDEO_FRAME_FLAGS(f)          ((f)->flags)
 113 #define GST_VIDEO_FRAME_FLAG_IS_SET(f,fl) ((GST_VIDEO_FRAME_FLAGS(f) & (fl)) == (fl))
 114 #define GST_VIDEO_FRAME_IS_INTERLACED(f)  (GST_VIDEO_FRAME_FLAG_IS_SET(f, GST_VIDEO_FRAME_FLAG_INTERLACED))
 115 #define GST_VIDEO_FRAME_IS_TFF(f)         (GST_VIDEO_FRAME_FLAG_IS_SET(f, GST_VIDEO_FRAME_FLAG_TFF))
 116 #define GST_VIDEO_FRAME_IS_RFF(f)         (GST_VIDEO_FRAME_FLAG_IS_SET(f, GST_VIDEO_FRAME_FLAG_RFF))
 117 #define GST_VIDEO_FRAME_IS_ONEFIELD(f)    (GST_VIDEO_FRAME_FLAG_IS_SET(f, GST_VIDEO_FRAME_FLAG_ONEFIELD))
 118
 119 /* dealing with planes */
 120 #define GST_VIDEO_FRAME_N_PLANES(f)       (GST_VIDEO_INFO_N_PLANES(&(f)->info))
 121 #define GST_VIDEO_FRAME_PLANE_DATA(f,p)   ((f)->data[p])
 122 #define GST_VIDEO_FRAME_PLANE_OFFSET(f,p) (GST_VIDEO_INFO_PLANE_OFFSET(&(f)->info,(p)))
 123 #define GST_VIDEO_FRAME_PLANE_STRIDE(f,p) (GST_VIDEO_INFO_PLANE_STRIDE(&(f)->info,(p)))
 124
 125 /* dealing with components */
 126 #define GST_VIDEO_FRAME_N_COMPONENTS(f)   GST_VIDEO_INFO_N_COMPONENTS(&(f)->info)
 127 #define GST_VIDEO_FRAME_COMP_DEPTH(f,c)   GST_VIDEO_INFO_COMP_DEPTH(&(f)->info,(c))
 128 #define GST_VIDEO_FRAME_COMP_DATA(f,c)    GST_VIDEO_INFO_COMP_DATA(&(f)->info,(f)->data,(c))
 129 #define GST_VIDEO_FRAME_COMP_STRIDE(f,c)  GST_VIDEO_INFO_COMP_STRIDE(&(f)->info,(c))
 130 #define GST_VIDEO_FRAME_COMP_OFFSET(f,c)  GST_VIDEO_INFO_COMP_OFFSET(&(f)->info,(c))
 131 #define GST_VIDEO_FRAME_COMP_WIDTH(f,c)   GST_VIDEO_INFO_COMP_WIDTH(&(f)->info,(c))
 132 #define GST_VIDEO_FRAME_COMP_HEIGHT(f,c)  GST_VIDEO_INFO_COMP_HEIGHT(&(f)->info,(c))
 133 #define GST_VIDEO_FRAME_COMP_PLANE(f,c)   GST_VIDEO_INFO_COMP_PLANE(&(f)->info,(c))
 134 #define GST_VIDEO_FRAME_COMP_PSTRIDE(f,c) GST_VIDEO_INFO_COMP_PSTRIDE(&(f)->info,(c))
 135 #define GST_VIDEO_FRAME_COMP_POFFSET(f,c) GST_VIDEO_INFO_COMP_POFFSET(&(f)->info,(c))
 136
 137 /* buffer flags */
 138
 139 /**
 140  * GstVideoBufferFlags:
 141  * @GST_VIDEO_BUFFER_FLAG_INTERLACED:  If the #GstBuffer is interlaced. In mixed
 142  *                                     interlace-mode, this flags specifies if the frame is
 143  *                                     interlaced or progressive.
 144  * @GST_VIDEO_BUFFER_FLAG_TFF:         If the #GstBuffer is interlaced, then the first field
 145  *                                     in the video frame is the top field.  If unset, the
 146  *                                     bottom field is first.
 147  * @GST_VIDEO_BUFFER_FLAG_RFF:         If the #GstBuffer is interlaced, then the first field
 148  *                                     (as defined by the %GST_VIDEO_BUFFER_TFF flag setting)
 149  *                                     is repeated.
 150  * @GST_VIDEO_BUFFER_FLAG_ONEFIELD:    If the #GstBuffer is interlaced, then only the
 151  *                                     first field (as defined by the %GST_VIDEO_BUFFER_TFF
 152  *                                     flag setting) is to be displayed.
 153  * @GST_VIDEO_BUFFER_FLAG_MULTIPLE_VIEW: The #GstBuffer contains one or more specific views,
 154  *                                     such as left or right eye view. This flags is set on
 155  *                                     any buffer that contains non-mono content - even for
 156  *                                     streams that contain only a single viewpoint. In mixed
 157  *                                     mono / non-mono streams, the absense of the flag marks
 158  *                                     mono buffers.
 159  * @GST_VIDEO_BUFFER_FLAG_FIRST_IN_BUNDLE: When conveying stereo/multiview content with
 160  *                                     frame-by-frame methods, this flag marks the first buffer
 161  *                                      in a bundle of frames that belong together.
 162  * @GST_VIDEO_BUFFER_FLAG_LAST:        Offset to define more flags
 163  *
 164  * Additional video buffer flags. These flags can potentially be used on any
 165  * buffers carrying video data - even encoded data.
 166  *
 167  * Note that these are only valid for #GstCaps of type: video/...
 168  * They can conflict with other extended buffer flags.
 169  */
 170 typedef enum {
 171   GST_VIDEO_BUFFER_FLAG_INTERLACED  = (GST_BUFFER_FLAG_LAST << 0),
 172   GST_VIDEO_BUFFER_FLAG_TFF         = (GST_BUFFER_FLAG_LAST << 1),
 173   GST_VIDEO_BUFFER_FLAG_RFF         = (GST_BUFFER_FLAG_LAST << 2),
 174   GST_VIDEO_BUFFER_FLAG_ONEFIELD    = (GST_BUFFER_FLAG_LAST << 3),
 175
 176   GST_VIDEO_BUFFER_FLAG_MULTIPLE_VIEW = (GST_BUFFER_FLAG_LAST << 4),
 177   GST_VIDEO_BUFFER_FLAG_FIRST_IN_BUNDLE = (GST_BUFFER_FLAG_LAST << 5),
 178
 179   GST_VIDEO_BUFFER_FLAG_LAST        = (GST_BUFFER_FLAG_LAST << 8)
 180 } GstVideoBufferFlags;
 181
 182 /**
 183  * GstVideoFrameMapFlags:
 184  * @GST_VIDEO_FRAME_MAP_FLAG_NO_REF:  Don't take another reference of the buffer and store it in
 185  *                                    the GstVideoFrame. This makes sure that the buffer stays
 186  *                                    writable while the frame is mapped, but requires that the
 187  *                                    buffer reference stays valid until the frame is unmapped again.
 188  * @GST_VIDEO_FRAME_MAP_FLAG_LAST:    Offset to define more flags
 189  *
 190  * Additional mapping flags for gst_video_frame_map().
 191  *
 192  * Since: 1.6
 193  */
 194 typedef enum {
 195   GST_VIDEO_FRAME_MAP_FLAG_NO_REF   = (GST_MAP_FLAG_LAST << 0),
 196   GST_VIDEO_FRAME_MAP_FLAG_LAST     = (GST_MAP_FLAG_LAST << 8)
 197   /* 8 more flags possible afterwards */
 198 } GstVideoFrameMapFlags;
 199
 200 G_END_DECLS
 201
 202 #endif /* __GST_VIDEO_FRAME_H__ */