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