subprojects/gst-plugins-base/gst-libs/gst/audio/gstaudiodecoder.h

   1 /* GStreamer
   2  * Copyright (C) 2009 Igalia S.L.
   3  * Author: Iago Toral Quiroga <itoral@igalia.com>
   4  * Copyright (C) 2011 Mark Nauwelaerts <mark.nauwelaerts@collabora.co.uk>.
   5  * Copyright (C) 2011 Nokia Corporation. All rights reserved.
   6  *   Contact: Stefan Kost <stefan.kost@nokia.com>
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  21  * Boston, MA 02110-1301, USA.
  22  */
  23
  24 #ifndef __GST_AUDIO_AUDIO_H__
  25 #include <gst/audio/audio.h>
  26 #endif
  27
  28 #ifndef _GST_AUDIO_DECODER_H_
  29 #define _GST_AUDIO_DECODER_H_
  30
  31 #include <gst/gst.h>
  32 #include <gst/base/gstadapter.h>
  33
  34 G_BEGIN_DECLS
  35
  36 #define GST_TYPE_AUDIO_DECODER \
  37   (gst_audio_decoder_get_type())
  38 #define GST_AUDIO_DECODER(obj) \
  39   (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_AUDIO_DECODER,GstAudioDecoder))
  40 #define GST_AUDIO_DECODER_CLASS(klass) \
  41   (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_AUDIO_DECODER,GstAudioDecoderClass))
  42 #define GST_AUDIO_DECODER_GET_CLASS(obj) \
  43   (G_TYPE_INSTANCE_GET_CLASS((obj),GST_TYPE_AUDIO_DECODER,GstAudioDecoderClass))
  44 #define GST_IS_AUDIO_DECODER(obj) \
  45   (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_AUDIO_DECODER))
  46 #define GST_IS_AUDIO_DECODER_CLASS(obj) \
  47   (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_AUDIO_DECODER))
  48 #define GST_AUDIO_DECODER_CAST(obj) \
  49   ((GstAudioDecoder *)(obj))
  50
  51 /**
  52  * GST_AUDIO_DECODER_SINK_NAME:
  53  *
  54  * The name of the templates for the sink pad.
  55  */
  56 #define GST_AUDIO_DECODER_SINK_NAME    "sink"
  57 /**
  58  * GST_AUDIO_DECODER_SRC_NAME:
  59  *
  60  * The name of the templates for the source pad.
  61  */
  62 #define GST_AUDIO_DECODER_SRC_NAME     "src"
  63
  64 /**
  65  * GST_AUDIO_DECODER_SRC_PAD:
  66  * @obj: base audio codec instance
  67  *
  68  * Gives the pointer to the source #GstPad object of the element.
  69  */
  70 #define GST_AUDIO_DECODER_SRC_PAD(obj)         (((GstAudioDecoder *) (obj))->srcpad)
  71
  72 /**
  73  * GST_AUDIO_DECODER_SINK_PAD:
  74  * @obj: base audio codec instance
  75  *
  76  * Gives the pointer to the sink #GstPad object of the element.
  77  */
  78 #define GST_AUDIO_DECODER_SINK_PAD(obj)        (((GstAudioDecoder *) (obj))->sinkpad)
  79
  80 #define GST_AUDIO_DECODER_STREAM_LOCK(dec)   g_rec_mutex_lock (&GST_AUDIO_DECODER (dec)->stream_lock)
  81 #define GST_AUDIO_DECODER_STREAM_UNLOCK(dec) g_rec_mutex_unlock (&GST_AUDIO_DECODER (dec)->stream_lock)
  82
  83 /**
  84  * GST_AUDIO_DECODER_INPUT_SEGMENT:
  85  * @obj: audio decoder instance
  86  *
  87  * Gives the input segment of the element.
  88  */
  89 #define GST_AUDIO_DECODER_INPUT_SEGMENT(obj)   (GST_AUDIO_DECODER_CAST (obj)->input_segment)
  90
  91 /**
  92  * GST_AUDIO_DECODER_OUTPUT_SEGMENT:
  93  * @obj: audio decoder instance
  94  *
  95  * Gives the output segment of the element.
  96  */
  97 #define GST_AUDIO_DECODER_OUTPUT_SEGMENT(obj)   (GST_AUDIO_DECODER_CAST (obj)->output_segment)
  98
  99 typedef struct _GstAudioDecoder GstAudioDecoder;
 100 typedef struct _GstAudioDecoderClass GstAudioDecoderClass;
 101
 102 typedef struct _GstAudioDecoderPrivate GstAudioDecoderPrivate;
 103
 104 /* do not use this one, use macro below */
 105
 106 GST_AUDIO_API
 107 GstFlowReturn _gst_audio_decoder_error (GstAudioDecoder *dec, gint weight,
 108                                         GQuark domain, gint code,
 109                                         gchar *txt, gchar *debug,
 110                                         const gchar *file, const gchar *function,
 111                                         gint line);
 112
 113 /**
 114  * GST_AUDIO_DECODER_ERROR:
 115  * @el:     the base audio decoder element that generates the error
 116  * @weight: element defined weight of the error, added to error count
 117  * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #gstreamer-GstGError)
 118  * @code:   error code defined for that domain (see #gstreamer-GstGError)
 119  * @text:   the message to display (format string and args enclosed in
 120  *          parentheses)
 121  * @debug:  debugging information for the message (format string and args
 122  *          enclosed in parentheses)
 123  * @ret:    variable to receive return value
 124  *
 125  * Utility function that audio decoder elements can use in case they encountered
 126  * a data processing error that may be fatal for the current "data unit" but
 127  * need not prevent subsequent decoding.  Such errors are counted and if there
 128  * are too many, as configured in the context's max_errors, the pipeline will
 129  * post an error message and the application will be requested to stop further
 130  * media processing.  Otherwise, it is considered a "glitch" and only a warning
 131  * is logged. In either case, @ret is set to the proper value to
 132  * return to upstream/caller (indicating either GST_FLOW_ERROR or GST_FLOW_OK).
 133  */
 134 #define GST_AUDIO_DECODER_ERROR(el, weight, domain, code, text, debug, ret) \
 135 G_STMT_START {                                                              \
 136   gchar *__txt = _gst_element_error_printf text;                            \
 137   gchar *__dbg = _gst_element_error_printf debug;                           \
 138   GstAudioDecoder *__dec = GST_AUDIO_DECODER (el);                   \
 139   ret = _gst_audio_decoder_error (__dec, weight, GST_ ## domain ## _ERROR,    \
 140       GST_ ## domain ## _ERROR_ ## code, __txt, __dbg, __FILE__,            \
 141       GST_FUNCTION, __LINE__);                                              \
 142 } G_STMT_END
 143
 144
 145 /**
 146  * GST_AUDIO_DECODER_MAX_ERRORS:
 147  *
 148  * Default maximum number of errors tolerated before signaling error.
 149  */
 150 #define GST_AUDIO_DECODER_MAX_ERRORS     -1
 151
 152 /**
 153  * GstAudioDecoder:
 154  *
 155  * The opaque #GstAudioDecoder data structure.
 156  */
 157 struct _GstAudioDecoder
 158 {
 159   GstElement element;
 160
 161   /*< protected >*/
 162   /* source and sink pads */
 163   GstPad         *sinkpad;
 164   GstPad         *srcpad;
 165
 166   /* protects all data processing, i.e. is locked
 167    * in the chain function, finish_frame and when
 168    * processing serialized events */
 169   GRecMutex       stream_lock;
 170
 171   /* MT-protected (with STREAM_LOCK) */
 172   GstSegment      input_segment;
 173   GstSegment      output_segment;
 174
 175   /*< private >*/
 176   GstAudioDecoderPrivate *priv;
 177
 178   gpointer       _gst_reserved[GST_PADDING_LARGE];
 179 };
 180
 181 /**
 182  * GstAudioDecoderClass:
 183  * @element_class:  The parent class structure
 184  * @start:          Optional.
 185  *                  Called when the element starts processing.
 186  *                  Allows opening external resources.
 187  * @stop:           Optional.
 188  *                  Called when the element stops processing.
 189  *                  Allows closing external resources.
 190  * @set_format:     Notifies subclass of incoming data format (caps).
 191  * @parse:          Optional.
 192  *                  Allows chopping incoming data into manageable units (frames)
 193  *                  for subsequent decoding.  This division is at subclass
 194  *                  discretion and may or may not correspond to 1 (or more)
 195  *                  frames as defined by audio format.
 196  * @handle_frame:   Provides input data (or NULL to clear any remaining data)
 197  *                  to subclass.  Input data ref management is performed by
 198  *                  base class, subclass should not care or intervene,
 199  *                  and input data is only valid until next call to base class,
 200  *                  most notably a call to gst_audio_decoder_finish_frame().
 201  * @flush:          Optional.
 202  *                  Instructs subclass to clear any codec caches and discard
 203  *                  any pending samples and not yet returned decoded data.
 204  *                  @hard indicates whether a FLUSH is being processed,
 205  *                  or otherwise a DISCONT (or conceptually similar).
 206  * @sink_event:     Optional.
 207  *                  Event handler on the sink pad. Subclasses should chain up to
 208  *                  the parent implementation to invoke the default handler.
 209  * @src_event:      Optional.
 210  *                  Event handler on the src pad. Subclasses should chain up to
 211  *                  the parent implementation to invoke the default handler.
 212  * @pre_push:       Optional.
 213  *                  Called just prior to pushing (encoded data) buffer downstream.
 214  *                  Subclass has full discretionary access to buffer,
 215  *                  and a not OK flow return will abort downstream pushing.
 216  * @open:           Optional.
 217  *                  Called when the element changes to GST_STATE_READY.
 218  *                  Allows opening external resources.
 219  * @close:          Optional.
 220  *                  Called when the element changes to GST_STATE_NULL.
 221  *                  Allows closing external resources.
 222  * @negotiate:      Optional.
 223  *                  Negotiate with downstream and configure buffer pools, etc.
 224  *                  Subclasses should chain up to the parent implementation to
 225  *                  invoke the default handler.
 226  * @decide_allocation: Optional.
 227  *                     Setup the allocation parameters for allocating output
 228  *                     buffers. The passed in query contains the result of the
 229  *                     downstream allocation query.
 230  *                     Subclasses should chain up to the parent implementation to
 231  *                     invoke the default handler.
 232  * @propose_allocation: Optional.
 233  *                      Propose buffer allocation parameters for upstream elements.
 234  *                      Subclasses should chain up to the parent implementation to
 235  *                      invoke the default handler.
 236  * @sink_query:     Optional.
 237  *                  Query handler on the sink pad. This function should
 238  *                  return TRUE if the query could be performed. Subclasses
 239  *                  should chain up to the parent implementation to invoke the
 240  *                  default handler. Since: 1.6
 241  * @src_query:      Optional.
 242  *                  Query handler on the source pad. This function should
 243  *                  return TRUE if the query could be performed. Subclasses
 244  *                  should chain up to the parent implementation to invoke the
 245  *                  default handler. Since: 1.6
 246  * @getcaps:        Optional.
 247  *                  Allows for a custom sink getcaps implementation.
 248  *                  If not implemented,
 249  *                  default returns gst_audio_decoder_proxy_getcaps
 250  *                  applied to sink template caps.
 251  * @transform_meta: Optional. Transform the metadata on the input buffer to the
 252  *                  output buffer. By default this method copies all meta without
 253  *                  tags and meta with only the "audio" tag. subclasses can
 254  *                  implement this method and return %TRUE if the metadata is to be
 255  *                  copied. Since: 1.6
 256  *
 257  * Subclasses can override any of the available virtual methods or not, as
 258  * needed. At minimum @handle_frame (and likely @set_format) needs to be
 259  * overridden.
 260  */
 261 struct _GstAudioDecoderClass
 262 {
 263   GstElementClass element_class;
 264
 265   /*< public >*/
 266   /* virtual methods for subclasses */
 267
 268   gboolean      (*start)              (GstAudioDecoder *dec);
 269
 270   gboolean      (*stop)               (GstAudioDecoder *dec);
 271
 272   gboolean      (*set_format)         (GstAudioDecoder *dec,
 273                                        GstCaps *caps);
 274
 275   /**
 276    * GstAudioDecoderClass::parse:
 277    * @offset: (out):
 278    * @length: (out):
 279    */
 280   GstFlowReturn (*parse)              (GstAudioDecoder *dec,
 281                                        GstAdapter *adapter,
 282                                        gint *offset, gint *length);
 283
 284   GstFlowReturn (*handle_frame)       (GstAudioDecoder *dec,
 285                                        GstBuffer *buffer);
 286
 287   void          (*flush)              (GstAudioDecoder *dec, gboolean hard);
 288
 289   GstFlowReturn (*pre_push)           (GstAudioDecoder *dec,
 290                                        GstBuffer **buffer);
 291
 292   gboolean      (*sink_event)         (GstAudioDecoder *dec,
 293                                        GstEvent *event);
 294   gboolean      (*src_event)          (GstAudioDecoder *dec,
 295                                        GstEvent *event);
 296
 297   gboolean      (*open)               (GstAudioDecoder *dec);
 298
 299   gboolean      (*close)              (GstAudioDecoder *dec);
 300
 301   gboolean      (*negotiate)          (GstAudioDecoder *dec);
 302
 303   gboolean      (*decide_allocation)  (GstAudioDecoder *dec, GstQuery *query);
 304
 305   gboolean      (*propose_allocation) (GstAudioDecoder *dec,
 306                                        GstQuery * query);
 307
 308   gboolean      (*sink_query)         (GstAudioDecoder *dec, GstQuery *query);
 309
 310   gboolean      (*src_query)          (GstAudioDecoder *dec, GstQuery *query);
 311
 312   GstCaps *     (*getcaps)            (GstAudioDecoder * dec,
 313                                        GstCaps * filter);
 314
 315   gboolean      (*transform_meta)     (GstAudioDecoder *enc, GstBuffer *outbuf,
 316                                        GstMeta *meta, GstBuffer *inbuf);
 317
 318   /*< private >*/
 319   gpointer       _gst_reserved[GST_PADDING_LARGE - 4];
 320 };
 321
 322 GST_AUDIO_API
 323 GType             gst_audio_decoder_get_type (void);
 324
 325 GST_AUDIO_API
 326 gboolean          gst_audio_decoder_set_output_format  (GstAudioDecoder    * dec,
 327                                                         const GstAudioInfo * info);
 328
 329 GST_AUDIO_API
 330 gboolean          gst_audio_decoder_set_output_caps  (GstAudioDecoder * dec,
 331                                                       GstCaps         * caps);
 332 GST_AUDIO_API
 333 GstCaps *         gst_audio_decoder_proxy_getcaps (GstAudioDecoder * decoder,
 334                                                    GstCaps         * caps,
 335                                                    GstCaps         * filter);
 336
 337 GST_AUDIO_API
 338 gboolean          gst_audio_decoder_negotiate (GstAudioDecoder * dec);
 339
 340 GST_AUDIO_API
 341 GstFlowReturn     gst_audio_decoder_finish_subframe (GstAudioDecoder * dec,
 342                                                      GstBuffer       * buf);
 343
 344 GST_AUDIO_API
 345 GstFlowReturn     gst_audio_decoder_finish_frame (GstAudioDecoder * dec,
 346                                                   GstBuffer * buf, gint frames);
 347
 348 GST_AUDIO_API
 349 GstBuffer *       gst_audio_decoder_allocate_output_buffer (GstAudioDecoder * dec,
 350                                                             gsize              size);
 351
 352 /* context parameters */
 353
 354 GST_AUDIO_API
 355 GstAudioInfo    * gst_audio_decoder_get_audio_info (GstAudioDecoder * dec);
 356
 357 GST_AUDIO_API
 358 void              gst_audio_decoder_set_plc_aware  (GstAudioDecoder * dec,
 359                                                     gboolean          plc);
 360
 361 GST_AUDIO_API
 362 gint              gst_audio_decoder_get_plc_aware  (GstAudioDecoder * dec);
 363
 364 GST_AUDIO_API
 365 void              gst_audio_decoder_set_estimate_rate  (GstAudioDecoder * dec,
 366                                                     gboolean          enabled);
 367
 368 GST_AUDIO_API
 369 gint              gst_audio_decoder_get_estimate_rate  (GstAudioDecoder * dec);
 370
 371 GST_AUDIO_API
 372 gint              gst_audio_decoder_get_delay      (GstAudioDecoder * dec);
 373
 374 GST_AUDIO_API
 375 void              gst_audio_decoder_set_max_errors (GstAudioDecoder * dec,
 376                                                    gint               num);
 377
 378 GST_AUDIO_API
 379 gint              gst_audio_decoder_get_max_errors (GstAudioDecoder * dec);
 380
 381 GST_AUDIO_API
 382 void              gst_audio_decoder_set_latency (GstAudioDecoder * dec,
 383                                                  GstClockTime      min,
 384                                                  GstClockTime      max);
 385
 386 GST_AUDIO_API
 387 void              gst_audio_decoder_get_latency (GstAudioDecoder * dec,
 388                                                  GstClockTime    * min,
 389                                                  GstClockTime    * max);
 390
 391 GST_AUDIO_API
 392 void              gst_audio_decoder_get_parse_state (GstAudioDecoder * dec,
 393                                                      gboolean        * sync,
 394                                                      gboolean        * eos);
 395
 396 GST_AUDIO_API
 397 void              gst_audio_decoder_set_allocation_caps (GstAudioDecoder * dec,
 398                                                          GstCaps         * allocation_caps);
 399
 400 /* object properties */
 401
 402 GST_AUDIO_API
 403 void              gst_audio_decoder_set_plc (GstAudioDecoder * dec,
 404                                              gboolean          enabled);
 405
 406 GST_AUDIO_API
 407 gboolean          gst_audio_decoder_get_plc (GstAudioDecoder * dec);
 408
 409 GST_AUDIO_API
 410 void              gst_audio_decoder_set_min_latency (GstAudioDecoder * dec,
 411                                                      GstClockTime      num);
 412
 413 GST_AUDIO_API
 414 GstClockTime      gst_audio_decoder_get_min_latency (GstAudioDecoder * dec);
 415
 416 GST_AUDIO_API
 417 void              gst_audio_decoder_set_tolerance   (GstAudioDecoder * dec,
 418                                                      GstClockTime      tolerance);
 419
 420 GST_AUDIO_API
 421 GstClockTime      gst_audio_decoder_get_tolerance   (GstAudioDecoder * dec);
 422
 423 GST_AUDIO_API
 424 void              gst_audio_decoder_set_drainable (GstAudioDecoder * dec,
 425                                                    gboolean enabled);
 426
 427 GST_AUDIO_API
 428 gboolean          gst_audio_decoder_get_drainable (GstAudioDecoder * dec);
 429
 430 GST_AUDIO_API
 431 void              gst_audio_decoder_set_needs_format (GstAudioDecoder * dec,
 432                                                       gboolean enabled);
 433
 434 GST_AUDIO_API
 435 gboolean          gst_audio_decoder_get_needs_format (GstAudioDecoder * dec);
 436
 437 GST_AUDIO_API
 438 void              gst_audio_decoder_get_allocator (GstAudioDecoder * dec,
 439                                                    GstAllocator ** allocator,
 440                                                    GstAllocationParams * params);
 441
 442 GST_AUDIO_API
 443 void              gst_audio_decoder_merge_tags (GstAudioDecoder * dec,
 444                                                 const GstTagList * tags, GstTagMergeMode mode);
 445
 446 GST_AUDIO_API
 447 void              gst_audio_decoder_set_use_default_pad_acceptcaps (GstAudioDecoder * decoder,
 448                                                                    gboolean use);
 449
 450 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstAudioDecoder, gst_object_unref)
 451
 452 G_END_DECLS
 453
 454 #endif /* _GST_AUDIO_DECODER_H_ */