gst-libs/gst/video/gstvideoutils.h

   1 /* GStreamer
   2  * Copyright (C) 2008 David Schleef <ds@schleef.org>
   3  * Copyright (C) 2012 Collabora Ltd.
   4  *      Author : Edward Hervey <edward@collabora.com>
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  19  * Boston, MA 02110-1301, USA.
  20  */
  21
  22 #ifndef __GST_VIDEO_H__
  23 #include <gst/video/video.h>
  24 #endif
  25
  26 #ifndef _GST_VIDEO_UTILS_H_
  27 #define _GST_VIDEO_UTILS_H_
  28
  29 #include <gst/gst.h>
  30 #include <gst/video/video-prelude.h>
  31
  32 G_BEGIN_DECLS
  33 #define GST_TYPE_VIDEO_CODEC_STATE \
  34   (gst_video_codec_state_get_type())
  35
  36 #define GST_TYPE_VIDEO_CODEC_FRAME \
  37   (gst_video_codec_frame_get_type())
  38
  39 typedef struct _GstVideoCodecState GstVideoCodecState;
  40 typedef struct _GstVideoCodecFrame GstVideoCodecFrame;
  41
  42 /**
  43  * GstVideoCodecState:
  44  * @info: The #GstVideoInfo describing the stream
  45  * @caps: The #GstCaps used in the caps negotiation of the pad.
  46  * @codec_data: a #GstBuffer corresponding to the
  47  *     'codec_data' field of a stream, or NULL.
  48  * @allocation_caps: The #GstCaps for allocation query and pool
  49  *     negotiation. Since: 1.10
  50  *
  51  * Structure representing the state of an incoming or outgoing video
  52  * stream for encoders and decoders.
  53  *
  54  * Decoders and encoders will receive such a state through their
  55  * respective @set_format vmethods.
  56  *
  57  * Decoders and encoders can set the downstream state, by using the
  58  * gst_video_decoder_set_output_state() or
  59  * gst_video_encoder_set_output_state() methods.
  60  */
  61 struct _GstVideoCodecState
  62 {
  63   /*< private >*/
  64   gint ref_count;
  65
  66   /*< public >*/
  67   GstVideoInfo info;
  68
  69   GstCaps *caps;
  70
  71   GstBuffer *codec_data;
  72
  73   GstCaps *allocation_caps;
  74
  75   /*< private >*/
  76   gpointer padding[GST_PADDING_LARGE - 1];
  77 };
  78
  79 /**
  80  * GstVideoCodecFrameFlags:
  81  * @GST_VIDEO_CODEC_FRAME_FLAG_DECODE_ONLY: is the frame only meant to be decoded
  82  * @GST_VIDEO_CODEC_FRAME_FLAG_SYNC_POINT: is the frame a synchronization point (keyframe)
  83  * @GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME: should the output frame be made a keyframe
  84  * @GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME_HEADERS: should the encoder output stream headers
  85  * @GST_VIDEO_CODEC_FRAME_FLAG_CORRUPTED: the buffer data is corrupted (Since: 1.20)
  86  *
  87  * Flags for #GstVideoCodecFrame
  88  */
  89 typedef enum
  90 {
  91   GST_VIDEO_CODEC_FRAME_FLAG_DECODE_ONLY            = (1<<0),
  92   GST_VIDEO_CODEC_FRAME_FLAG_SYNC_POINT             = (1<<1),
  93   GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME         = (1<<2),
  94   GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME_HEADERS = (1<<3),
  95   /**
  96    * GST_VIDEO_CODEC_FRAME_FLAG_CORRUPTED:
  97    *
  98    * The buffer data is corrupted.
  99    *
 100    * Since: 1.20
 101    */
 102   GST_VIDEO_CODEC_FRAME_FLAG_CORRUPTED = (1<<4),
 103 } GstVideoCodecFrameFlags;
 104
 105 /**
 106  * GST_VIDEO_CODEC_FRAME_FLAGS:
 107  * @frame: a #GstVideoCodecFrame
 108  *
 109  * The entire set of flags for the @frame
 110  */
 111 #define GST_VIDEO_CODEC_FRAME_FLAGS(frame) ((frame)->flags)
 112
 113 /**
 114  * GST_VIDEO_CODEC_FRAME_FLAG_IS_SET:
 115  * @frame: a #GstVideoCodecFrame
 116  * @flag: a flag to check for
 117  *
 118  * Checks whether the given @flag is set
 119  */
 120 #define GST_VIDEO_CODEC_FRAME_FLAG_IS_SET(frame,flag)   !!(GST_VIDEO_CODEC_FRAME_FLAGS(frame) & (flag))
 121
 122 /**
 123  * GST_VIDEO_CODEC_FRAME_FLAG_SET:
 124  * @frame: a #GstVideoCodecFrame
 125  * @flag: Flag to set, can be any number of bits in guint32.
 126  *
 127  * This macro sets the given bits
 128  */
 129 #define GST_VIDEO_CODEC_FRAME_FLAG_SET(frame,flag)     (GST_VIDEO_CODEC_FRAME_FLAGS(frame) |= (flag))
 130
 131 /**
 132  * GST_VIDEO_CODEC_FRAME_FLAG_UNSET:
 133  * @frame: a #GstVideoCodecFrame
 134  * @flag: Flag to unset
 135  *
 136  * This macro usets the given bits.
 137  */
 138 #define GST_VIDEO_CODEC_FRAME_FLAG_UNSET(frame,flag)   (GST_VIDEO_CODEC_FRAME_FLAGS(frame) &= ~(flag))
 139
 140 /**
 141  * GST_VIDEO_CODEC_FRAME_IS_DECODE_ONLY:
 142  * @frame: a #GstVideoCodecFrame
 143  *
 144  * Tests if the buffer should only be decoded but not sent downstream.
 145  */
 146 #define GST_VIDEO_CODEC_FRAME_IS_DECODE_ONLY(frame)     (GST_VIDEO_CODEC_FRAME_FLAG_IS_SET(frame, GST_VIDEO_CODEC_FRAME_FLAG_DECODE_ONLY))
 147
 148 /**
 149  * GST_VIDEO_CODEC_FRAME_SET_DECODE_ONLY:
 150  * @frame: a #GstVideoCodecFrame
 151  *
 152  * Sets the buffer to not be sent downstream.
 153  *
 154  * Decoder implementation can use this if they have frames that
 155  * are not meant to be displayed.
 156  *
 157  * Encoder implementation can safely ignore this field.
 158  */
 159 #define GST_VIDEO_CODEC_FRAME_SET_DECODE_ONLY(frame)    (GST_VIDEO_CODEC_FRAME_FLAG_SET(frame, GST_VIDEO_CODEC_FRAME_FLAG_DECODE_ONLY))
 160
 161 /**
 162  * GST_VIDEO_CODEC_FRAME_IS_SYNC_POINT:
 163  * @frame: a #GstVideoCodecFrame
 164  *
 165  * Tests if the frame is a synchronization point (like a keyframe).
 166  *
 167  * Decoder implementations can use this to detect keyframes.
 168  */
 169 #define GST_VIDEO_CODEC_FRAME_IS_SYNC_POINT(frame)      (GST_VIDEO_CODEC_FRAME_FLAG_IS_SET(frame, GST_VIDEO_CODEC_FRAME_FLAG_SYNC_POINT))
 170
 171 /**
 172  * GST_VIDEO_CODEC_FRAME_SET_SYNC_POINT:
 173  * @frame: a #GstVideoCodecFrame
 174  *
 175  * Sets the frame to be a synchronization point (like a keyframe).
 176  *
 177  * Encoder implementations should set this accordingly.
 178  *
 179  * Decoder implementing parsing features should set this when they
 180  * detect such a synchronization point.
 181  */
 182 #define GST_VIDEO_CODEC_FRAME_SET_SYNC_POINT(frame)     (GST_VIDEO_CODEC_FRAME_FLAG_SET(frame, GST_VIDEO_CODEC_FRAME_FLAG_SYNC_POINT))
 183 #define GST_VIDEO_CODEC_FRAME_UNSET_SYNC_POINT(frame)   (GST_VIDEO_CODEC_FRAME_FLAG_UNSET(frame, GST_VIDEO_CODEC_FRAME_FLAG_SYNC_POINT))
 184
 185
 186 /**
 187  * GST_VIDEO_CODEC_FRAME_IS_FORCE_KEYFRAME:
 188  * @frame: a #GstVideoCodecFrame
 189  *
 190  * Tests if the frame must be encoded as a keyframe. Applies only to
 191  * frames provided to encoders. Decoders can safely ignore this field.
 192  */
 193 #define GST_VIDEO_CODEC_FRAME_IS_FORCE_KEYFRAME(frame)      (GST_VIDEO_CODEC_FRAME_FLAG_IS_SET(frame, GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME))
 194 #define GST_VIDEO_CODEC_FRAME_SET_FORCE_KEYFRAME(frame)     (GST_VIDEO_CODEC_FRAME_FLAG_SET(frame, GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME))
 195 #define GST_VIDEO_CODEC_FRAME_UNSET_FORCE_KEYFRAME(frame)   (GST_VIDEO_CODEC_FRAME_FLAG_UNSET(frame, GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME))
 196
 197 /**
 198  * GST_VIDEO_CODEC_FRAME_IS_FORCE_KEYFRAME_HEADERS:
 199  * @frame: a #GstVideoCodecFrame
 200  *
 201  * Tests if encoder should output stream headers before outputting the
 202  * resulting encoded buffer for the given frame.
 203  *
 204  * Applies only to frames provided to encoders. Decoders can safely
 205  * ignore this field.
 206  */
 207 #define GST_VIDEO_CODEC_FRAME_IS_FORCE_KEYFRAME_HEADERS(frame)      (GST_VIDEO_CODEC_FRAME_FLAG_IS_SET(frame, GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME_HEADERS))
 208 #define GST_VIDEO_CODEC_FRAME_SET_FORCE_KEYFRAME_HEADERS(frame)     (GST_VIDEO_CODEC_FRAME_FLAG_SET(frame, GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME_HEADERS))
 209 #define GST_VIDEO_CODEC_FRAME_UNSET_FORCE_KEYFRAME_HEADERS(frame)   (GST_VIDEO_CODEC_FRAME_FLAG_UNSET(frame, GST_VIDEO_CODEC_FRAME_FLAG_FORCE_KEYFRAME_HEADERS))
 210
 211 /**
 212  * GstVideoCodecFrame:
 213  * @pts: Presentation timestamp
 214  * @dts: Decoding timestamp
 215  * @duration: Duration of the frame
 216  * @system_frame_number: Unique identifier for the frame. Use this if you need
 217  *       to get hold of the frame later (like when data is being decoded).
 218  *       Typical usage in decoders is to set this on the opaque value provided
 219  *       to the library and get back the frame using gst_video_decoder_get_frame()
 220  * @distance_from_sync: Distance in frames from the last synchronization point.
 221  * @input_buffer: the input #GstBuffer that created this frame. The buffer is owned
 222  *           by the frame and references to the frame instead of the buffer should
 223  *           be kept.
 224  * @output_buffer: the output #GstBuffer. Implementations should set this either
 225  *           directly, or by using the
 226  *           gst_video_decoder_allocate_output_frame() or
 227  *           gst_video_decoder_allocate_output_buffer() methods. The buffer is
 228  *           owned by the frame and references to the frame instead of the
 229  *           buffer should be kept.
 230  * @deadline: Running time when the frame will be used.
 231  *
 232  * A #GstVideoCodecFrame represents a video frame both in raw and
 233  * encoded form.
 234  */
 235 struct _GstVideoCodecFrame
 236 {
 237   /*< private >*/
 238   gint ref_count;
 239   guint32 flags;
 240
 241   /*< public >*/
 242   guint32 system_frame_number;  /* ED */
 243
 244   /*< private >*/
 245   guint32 decode_frame_number;  /* ED */
 246   guint32 presentation_frame_number; /* ED */
 247
 248   /*< public >*/
 249   GstClockTime dts;       /* ED */
 250   GstClockTime pts;       /* ED */
 251   GstClockTime duration;  /* ED */
 252
 253   int distance_from_sync;       /* ED */
 254
 255   GstBuffer *input_buffer;      /* ED */
 256   GstBuffer *output_buffer;     /* ED */
 257
 258   GstClockTime deadline;        /* D */
 259
 260   /*< private >*/
 261
 262   /* Events that should be pushed downstream *before*
 263    * the next output_buffer */
 264   /* FIXME 2.0: Use a GQueue or similar */
 265   GList *events;                /* ED */
 266
 267   gpointer       user_data;
 268   GDestroyNotify user_data_destroy_notify;
 269
 270   union {
 271     struct {
 272       /*< private >*/
 273       GstClockTime ts;
 274       GstClockTime ts2;
 275       guint num_subframes;
 276       guint subframes_processed;
 277     } ABI;
 278     gpointer padding[GST_PADDING_LARGE];
 279   } abidata;
 280 };
 281
 282 /* GstVideoCodecState */
 283
 284 GST_VIDEO_API
 285 GType           gst_video_codec_state_get_type (void);
 286
 287 GST_VIDEO_API
 288 GstVideoCodecState *gst_video_codec_state_ref (GstVideoCodecState * state);
 289
 290 GST_VIDEO_API
 291 void                gst_video_codec_state_unref (GstVideoCodecState * state);
 292
 293
 294 /* GstVideoCodecFrame */
 295
 296 GST_VIDEO_API
 297 GType                gst_video_codec_frame_get_type (void);
 298
 299 GST_VIDEO_API
 300 GstVideoCodecFrame  *gst_video_codec_frame_ref (GstVideoCodecFrame * frame);
 301
 302 GST_VIDEO_API
 303 void                 gst_video_codec_frame_unref (GstVideoCodecFrame * frame);
 304
 305 GST_VIDEO_API
 306 void                 gst_video_codec_frame_set_user_data (GstVideoCodecFrame *frame,
 307                                                           gpointer user_data,
 308                                                           GDestroyNotify notify);
 309
 310 GST_VIDEO_API
 311 gpointer             gst_video_codec_frame_get_user_data (GstVideoCodecFrame *frame);
 312
 313 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstVideoCodecFrame, gst_video_codec_frame_unref)
 314
 315 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstVideoCodecState, gst_video_codec_state_unref)
 316
 317 G_END_DECLS
 318
 319 #endif