gst-libs/gst/video/gstvideodecoder.h

   1 /* GStreamer
   2  * Copyright (C) 2008 David Schleef <ds@schleef.org>
   3  * Copyright (C) 2011 Mark Nauwelaerts <mark.nauwelaerts@collabora.co.uk>.
   4  * Copyright (C) 2011 Nokia Corporation. All rights reserved.
   5  *   Contact: Stefan Kost <stefan.kost@nokia.com>
   6  * Copyright (C) 2012 Collabora Ltd.
   7  *      Author : Edward Hervey <edward@collabora.com>
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Library General Public
  11  * License as published by the Free Software Foundation; either
  12  * version 2 of the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Library General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Library General Public
  20  * License along with this library; if not, write to the
  21  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  22  * Boston, MA 02111-1307, USA.
  23  */
  24
  25 #ifndef _GST_VIDEO_DECODER_H_
  26 #define _GST_VIDEO_DECODER_H_
  27
  28 #include <gst/base/gstadapter.h>
  29 #include <gst/video/video.h>
  30 #include <gst/video/gstvideoutils.h>
  31
  32 G_BEGIN_DECLS
  33
  34 #define GST_TYPE_VIDEO_DECODER \
  35   (gst_video_decoder_get_type())
  36 #define GST_VIDEO_DECODER(obj) \
  37   (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_VIDEO_DECODER,GstVideoDecoder))
  38 #define GST_VIDEO_DECODER_CLASS(klass) \
  39   (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_VIDEO_DECODER,GstVideoDecoderClass))
  40 #define GST_VIDEO_DECODER_GET_CLASS(obj) \
  41   (G_TYPE_INSTANCE_GET_CLASS((obj),GST_TYPE_VIDEO_DECODER,GstVideoDecoderClass))
  42 #define GST_IS_VIDEO_DECODER(obj) \
  43   (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_VIDEO_DECODER))
  44 #define GST_IS_VIDEO_DECODER_CLASS(obj) \
  45   (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_VIDEO_DECODER))
  46
  47 /**
  48  * GST_VIDEO_DECODER_SINK_NAME:
  49  *
  50  * The name of the templates for the sink pad.
  51  *
  52  * Since: 0.10.36
  53  */
  54 #define GST_VIDEO_DECODER_SINK_NAME    "sink"
  55 /**
  56  * GST_VIDEO_DECODER_SRC_NAME:
  57  *
  58  * The name of the templates for the source pad.
  59  *
  60  * Since: 0.10.36
  61  */
  62 #define GST_VIDEO_DECODER_SRC_NAME     "src"
  63
  64 /**
  65  * GST_VIDEO_DECODER_SRC_PAD:
  66  * @obj: a #GstVideoDecoder
  67  *
  68  * Gives the pointer to the source #GstPad object of the element.
  69  *
  70  * Since: 0.10.36
  71  */
  72 #define GST_VIDEO_DECODER_SRC_PAD(obj)         (((GstVideoDecoder *) (obj))->srcpad)
  73
  74 /**
  75  * GST_VIDEO_DECODER_SINK_PAD:
  76  * @obj: a #GstVideoDecoder
  77  *
  78  * Gives the pointer to the sink #GstPad object of the element.
  79  *
  80  * Since: 0.10.36
  81  */
  82 #define GST_VIDEO_DECODER_SINK_PAD(obj)        (((GstVideoDecoder *) (obj))->sinkpad)
  83 /**
  84  * GST_VIDEO_DECODER_FLOW_NEED_DATA:
  85  *
  86  * Returned while parsing to indicate more data is needed.
  87  *
  88  * Since: 0.10.36
  89  **/
  90 #define GST_VIDEO_DECODER_FLOW_NEED_DATA GST_FLOW_CUSTOM_SUCCESS
  91
  92 /**
  93  * GST_VIDEO_DECODER_INPUT_SEGMENT:
  94  * @obj: base decoder instance
  95  *
  96  * Gives the segment of the element.
  97  *
  98  * Since: 0.10.36
  99  */
 100 #define GST_VIDEO_DECODER_INPUT_SEGMENT(obj)     (GST_VIDEO_DECODER_CAST (obj)->input_segment)
 101
 102 /**
 103  * GST_VIDEO_DECODER_OUTPUT_SEGMENT:
 104  * @obj: base decoder instance
 105  *
 106  * Gives the segment of the element.
 107  *
 108  * Since: 0.10.36
 109  */
 110 #define GST_VIDEO_DECODER_OUTPUT_SEGMENT(obj)     (GST_VIDEO_DECODER_CAST (obj)->output_segment)
 111
 112 /**
 113  * GST_VIDEO_DECODER_STREAM_LOCK:
 114  * @decoder: video decoder instance
 115  *
 116  * Obtain a lock to protect the decoder function from concurrent access.
 117  *
 118  * Since: 0.10.36
 119  */
 120 #define GST_VIDEO_DECODER_STREAM_LOCK(decoder) g_rec_mutex_lock (&GST_VIDEO_DECODER (decoder)->stream_lock)
 121
 122 /**
 123  * GST_VIDEO_DECODER_STREAM_UNLOCK:
 124  * @decoder: video decoder instance
 125  *
 126  * Release the lock that protects the decoder function from concurrent access.
 127  *
 128  * Since: 0.10.36
 129  */
 130 #define GST_VIDEO_DECODER_STREAM_UNLOCK(decoder) g_rec_mutex_unlock (&GST_VIDEO_DECODER (decoder)->stream_lock)
 131
 132 typedef struct _GstVideoDecoder GstVideoDecoder;
 133 typedef struct _GstVideoDecoderClass GstVideoDecoderClass;
 134 typedef struct _GstVideoDecoderPrivate GstVideoDecoderPrivate;
 135
 136
 137 /* do not use this one, use macro below */
 138 GstFlowReturn _gst_video_decoder_error (GstVideoDecoder *dec, gint weight,
 139                                              GQuark domain, gint code,
 140                                              gchar *txt, gchar *debug,
 141                                              const gchar *file, const gchar *function,
 142                                              gint line);
 143
 144 /**
 145  * GST_VIDEO_DECODER_ERROR:
 146  * @el:     the base video decoder element that generates the error
 147  * @weight: element defined weight of the error, added to error count
 148  * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #gstreamer-GstGError)
 149  * @code:   error code defined for that domain (see #gstreamer-GstGError)
 150  * @text:   the message to display (format string and args enclosed in
 151  *          parentheses)
 152  * @debug:  debugging information for the message (format string and args
 153  *          enclosed in parentheses)
 154  * @ret:    variable to receive return value
 155  *
 156  * Utility function that video decoder elements can use in case they encountered
 157  * a data processing error that may be fatal for the current "data unit" but
 158  * need not prevent subsequent decoding.  Such errors are counted and if there
 159  * are too many, as configured in the context's max_errors, the pipeline will
 160  * post an error message and the application will be requested to stop further
 161  * media processing.  Otherwise, it is considered a "glitch" and only a warning
 162  * is logged. In either case, @ret is set to the proper value to
 163  * return to upstream/caller (indicating either GST_FLOW_ERROR or GST_FLOW_OK).
 164  *
 165  * Since: 0.10.36
 166  */
 167 #define GST_VIDEO_DECODER_ERROR(el, w, domain, code, text, debug, ret) \
 168 G_STMT_START {                                                              \
 169   gchar *__txt = _gst_element_error_printf text;                            \
 170   gchar *__dbg = _gst_element_error_printf debug;                           \
 171   GstVideoDecoder *dec = GST_VIDEO_DECODER (el);                   \
 172   ret = _gst_video_decoder_error (dec, w, GST_ ## domain ## _ERROR,    \
 173       GST_ ## domain ## _ERROR_ ## code, __txt, __dbg, __FILE__,            \
 174       GST_FUNCTION, __LINE__);                                              \
 175 } G_STMT_END
 176
 177 /**
 178  * GST_VIDEO_DECODER_MAX_ERRORS:
 179  *
 180  * Default maximum number of errors tolerated before signaling error.
 181  *
 182  * Since: 0.10.36
 183  */
 184 #define GST_VIDEO_DECODER_MAX_ERRORS     10
 185
 186
 187 /**
 188  * GstVideoDecoder:
 189  *
 190  * The opaque #GstVideoDecoder data structure.
 191  *
 192  * Since: 0.10.36
 193  */
 194 struct _GstVideoDecoder
 195 {
 196   /*< private >*/
 197   GstElement     element;
 198
 199   /*< protected >*/
 200   GstPad         *sinkpad;
 201   GstPad         *srcpad;
 202
 203   /* protects all data processing, i.e. is locked
 204    * in the chain function, finish_frame and when
 205    * processing serialized events */
 206   GRecMutex stream_lock;
 207
 208   /* MT-protected (with STREAM_LOCK) */
 209   GstSegment      input_segment;
 210   GstSegment      output_segment;
 211
 212   GstVideoDecoderPrivate *priv;
 213
 214   /* FIXME before moving to base */
 215   void             *padding[GST_PADDING_LARGE];
 216 };
 217
 218 /**
 219  * GstVideoDecoderClass:
 220  * @open:           Optional.
 221  *                  Called when the element changes to GST_STATE_READY.
 222  *                  Allows opening external resources.
 223  * @close:          Optional.
 224  *                  Called when the element changes to GST_STATE_NULL.
 225  *                  Allows closing external resources.
 226  * @start:          Optional.
 227  *                  Called when the element starts processing.
 228  *                  Allows opening external resources.
 229  * @stop:           Optional.
 230  *                  Called when the element stops processing.
 231  *                  Allows closing external resources.
 232  * @set_format:     Notifies subclass of incoming data format (caps).
 233  * @parse:          Required for non-packetized input.
 234  *                  Allows chopping incoming data into manageable units (frames)
 235  *                  for subsequent decoding.
 236  * @reset:          Optional.
 237  *                  Allows subclass (decoder) to perform post-seek semantics reset.
 238  * @handle_frame:   Provides input data frame to subclass.
 239  * @finish:         Optional.
 240  *                  Called to request subclass to dispatch any pending remaining
 241  *                  data (e.g. at EOS).
 242  * @sink_event:     Optional.
 243  *                  Event handler on the sink pad. This function should return
 244  *                  TRUE if the event was handled and should be discarded
 245  *                  (i.e. not unref'ed).
 246  * @src_event:      Optional.
 247  *                  Event handler on the source pad. This function should return
 248  *                  TRUE if the event was handled and should be discarded
 249  *                  (i.e. not unref'ed).
 250  * @configure_buffer_pool: Optional.
 251  *                  Configure the buffer that is used for allocation of output
 252  *                  buffers. The passed query contains the result of the allocation
 253  *                  query. The default implementation will add the VIDEO_META if
 254  *                  supported by the buffer pool.
 255  * Subclasses can override any of the available virtual methods or not, as
 256  * needed. At minimum @handle_frame needs to be overridden, and @set_format
 257  * and likely as well.  If non-packetized input is supported or expected,
 258  * @parse needs to be overridden as well.
 259  *
 260  * Since: 0.10.36
 261  */
 262 struct _GstVideoDecoderClass
 263 {
 264   /*< private >*/
 265   GstElementClass element_class;
 266
 267   /*< public >*/
 268   gboolean      (*open)           (GstVideoDecoder *decoder);
 269
 270   gboolean      (*close)          (GstVideoDecoder *decoder);
 271
 272   gboolean      (*start)          (GstVideoDecoder *decoder);
 273
 274   gboolean      (*stop)           (GstVideoDecoder *decoder);
 275
 276   GstFlowReturn (*parse)          (GstVideoDecoder *decoder,
 277                                    GstVideoCodecFrame *frame,
 278                                    GstAdapter *adapter,
 279                                    gboolean at_eos);
 280
 281   gboolean      (*set_format)     (GstVideoDecoder *decoder,
 282                                    GstVideoCodecState * state);
 283
 284   gboolean      (*reset)          (GstVideoDecoder *decoder,
 285                                    gboolean hard);
 286
 287   GstFlowReturn (*finish)         (GstVideoDecoder *decoder);
 288
 289   GstFlowReturn (*handle_frame)   (GstVideoDecoder *decoder,
 290                                    GstVideoCodecFrame *frame);
 291
 292   gboolean      (*sink_event)     (GstVideoDecoder *decoder,
 293                                    GstEvent *event);
 294
 295   gboolean      (*src_event)      (GstVideoDecoder *decoder,
 296                                    GstEvent *event);
 297
 298   gboolean      (*configure_buffer_pool)  (GstVideoDecoder *decoder, GstQuery *query, GstBufferPool *pool);
 299
 300
 301   /*< private >*/
 302   /* FIXME before moving to base */
 303   void         *padding[GST_PADDING_LARGE];
 304 };
 305
 306 GType    gst_video_decoder_get_type (void);
 307
 308 /* Context parameters */
 309 void     gst_video_decoder_set_packetized (GstVideoDecoder * decoder,
 310                                            gboolean packetized);
 311
 312 gboolean gst_video_decoder_get_packetized (GstVideoDecoder * decoder);
 313
 314 void     gst_video_decoder_set_estimate_rate (GstVideoDecoder * dec,
 315                                               gboolean          enabled);
 316
 317 gint     gst_video_decoder_get_estimate_rate (GstVideoDecoder * dec);
 318
 319 void     gst_video_decoder_set_max_errors (GstVideoDecoder * dec,
 320                                            gint              num);
 321
 322 gint     gst_video_decoder_get_max_errors (GstVideoDecoder * dec);
 323
 324 void     gst_video_decoder_set_latency (GstVideoDecoder *decoder,
 325                                         GstClockTime min_latency,
 326                                         GstClockTime max_latency);
 327 void     gst_video_decoder_get_latency (GstVideoDecoder *decoder,
 328                                         GstClockTime *min_latency,
 329                                         GstClockTime *max_latency);
 330
 331
 332 /* Object methods */
 333
 334 GstVideoCodecFrame *gst_video_decoder_get_frame       (GstVideoDecoder *decoder,
 335                                                        int frame_number);
 336
 337 GstVideoCodecFrame *gst_video_decoder_get_oldest_frame (GstVideoDecoder *decoder);
 338
 339 /* Parsing related methods */
 340 void           gst_video_decoder_add_to_frame     (GstVideoDecoder *decoder,
 341                                                    int n_bytes);
 342 GstFlowReturn  gst_video_decoder_have_frame       (GstVideoDecoder *decoder);
 343
 344 GstBuffer     *gst_video_decoder_alloc_output_buffer (GstVideoDecoder * decoder);
 345
 346 GstFlowReturn  gst_video_decoder_alloc_output_frame  (GstVideoDecoder *decoder,
 347                                                       GstVideoCodecFrame *frame);
 348
 349 GstVideoCodecState *gst_video_decoder_set_output_state (GstVideoDecoder *decoder,
 350                                                         GstVideoFormat fmt, guint width, guint height,
 351                                                         GstVideoCodecState *reference);
 352
 353 GstVideoCodecState *gst_video_decoder_get_output_state (GstVideoDecoder *decoder);
 354
 355 GstClockTimeDiff gst_video_decoder_get_max_decode_time (GstVideoDecoder *decoder,
 356                                                         GstVideoCodecFrame *frame);
 357
 358 GstFlowReturn    gst_video_decoder_finish_frame (GstVideoDecoder *decoder,
 359                                                  GstVideoCodecFrame *frame);
 360
 361 GstFlowReturn    gst_video_decoder_drop_frame (GstVideoDecoder *dec,
 362                                                GstVideoCodecFrame *frame);
 363
 364 G_END_DECLS
 365
 366 #endif
 367