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 10 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 GstFlowReturn (*parse) (GstAudioDecoder *dec, 276 GstAdapter *adapter, 277 gint *offset, gint *length); 278 279 GstFlowReturn (*handle_frame) (GstAudioDecoder *dec, 280 GstBuffer *buffer); 281 282 void (*flush) (GstAudioDecoder *dec, gboolean hard); 283 284 GstFlowReturn (*pre_push) (GstAudioDecoder *dec, 285 GstBuffer **buffer); 286 287 gboolean (*sink_event) (GstAudioDecoder *dec, 288 GstEvent *event); 289 gboolean (*src_event) (GstAudioDecoder *dec, 290 GstEvent *event); 291 292 gboolean (*open) (GstAudioDecoder *dec); 293 294 gboolean (*close) (GstAudioDecoder *dec); 295 296 gboolean (*negotiate) (GstAudioDecoder *dec); 297 298 gboolean (*decide_allocation) (GstAudioDecoder *dec, GstQuery *query); 299 300 gboolean (*propose_allocation) (GstAudioDecoder *dec, 301 GstQuery * query); 302 303 gboolean (*sink_query) (GstAudioDecoder *dec, GstQuery *query); 304 305 gboolean (*src_query) (GstAudioDecoder *dec, GstQuery *query); 306 307 GstCaps * (*getcaps) (GstAudioDecoder * dec, 308 GstCaps * filter); 309 310 gboolean (*transform_meta) (GstAudioDecoder *enc, GstBuffer *outbuf, 311 GstMeta *meta, GstBuffer *inbuf); 312 313 /*< private >*/ 314 gpointer _gst_reserved[GST_PADDING_LARGE - 4]; 315 }; 316 317 GST_AUDIO_API 318 GType gst_audio_decoder_get_type (void); 319 320 GST_AUDIO_API 321 gboolean gst_audio_decoder_set_output_format (GstAudioDecoder * dec, 322 const GstAudioInfo * info); 323 324 GST_AUDIO_API 325 gboolean gst_audio_decoder_set_output_caps (GstAudioDecoder * dec, 326 GstCaps * caps); 327 GST_AUDIO_API 328 GstCaps * gst_audio_decoder_proxy_getcaps (GstAudioDecoder * decoder, 329 GstCaps * caps, 330 GstCaps * filter); 331 332 GST_AUDIO_API 333 gboolean gst_audio_decoder_negotiate (GstAudioDecoder * dec); 334 335 GST_AUDIO_API 336 GstFlowReturn gst_audio_decoder_finish_subframe (GstAudioDecoder * dec, 337 GstBuffer * buf); 338 339 GST_AUDIO_API 340 GstFlowReturn gst_audio_decoder_finish_frame (GstAudioDecoder * dec, 341 GstBuffer * buf, gint frames); 342 343 GST_AUDIO_API 344 GstBuffer * gst_audio_decoder_allocate_output_buffer (GstAudioDecoder * dec, 345 gsize size); 346 347 /* context parameters */ 348 349 GST_AUDIO_API 350 GstAudioInfo * gst_audio_decoder_get_audio_info (GstAudioDecoder * dec); 351 352 GST_AUDIO_API 353 void gst_audio_decoder_set_plc_aware (GstAudioDecoder * dec, 354 gboolean plc); 355 356 GST_AUDIO_API 357 gint gst_audio_decoder_get_plc_aware (GstAudioDecoder * dec); 358 359 GST_AUDIO_API 360 void gst_audio_decoder_set_estimate_rate (GstAudioDecoder * dec, 361 gboolean enabled); 362 363 GST_AUDIO_API 364 gint gst_audio_decoder_get_estimate_rate (GstAudioDecoder * dec); 365 366 GST_AUDIO_API 367 gint gst_audio_decoder_get_delay (GstAudioDecoder * dec); 368 369 GST_AUDIO_API 370 void gst_audio_decoder_set_max_errors (GstAudioDecoder * dec, 371 gint num); 372 373 GST_AUDIO_API 374 gint gst_audio_decoder_get_max_errors (GstAudioDecoder * dec); 375 376 GST_AUDIO_API 377 void gst_audio_decoder_set_latency (GstAudioDecoder * dec, 378 GstClockTime min, 379 GstClockTime max); 380 381 GST_AUDIO_API 382 void gst_audio_decoder_get_latency (GstAudioDecoder * dec, 383 GstClockTime * min, 384 GstClockTime * max); 385 386 GST_AUDIO_API 387 void gst_audio_decoder_get_parse_state (GstAudioDecoder * dec, 388 gboolean * sync, 389 gboolean * eos); 390 391 GST_AUDIO_API 392 void gst_audio_decoder_set_allocation_caps (GstAudioDecoder * dec, 393 GstCaps * allocation_caps); 394 395 /* object properties */ 396 397 GST_AUDIO_API 398 void gst_audio_decoder_set_plc (GstAudioDecoder * dec, 399 gboolean enabled); 400 401 GST_AUDIO_API 402 gboolean gst_audio_decoder_get_plc (GstAudioDecoder * dec); 403 404 GST_AUDIO_API 405 void gst_audio_decoder_set_min_latency (GstAudioDecoder * dec, 406 GstClockTime num); 407 408 GST_AUDIO_API 409 GstClockTime gst_audio_decoder_get_min_latency (GstAudioDecoder * dec); 410 411 GST_AUDIO_API 412 void gst_audio_decoder_set_tolerance (GstAudioDecoder * dec, 413 GstClockTime tolerance); 414 415 GST_AUDIO_API 416 GstClockTime gst_audio_decoder_get_tolerance (GstAudioDecoder * dec); 417 418 GST_AUDIO_API 419 void gst_audio_decoder_set_drainable (GstAudioDecoder * dec, 420 gboolean enabled); 421 422 GST_AUDIO_API 423 gboolean gst_audio_decoder_get_drainable (GstAudioDecoder * dec); 424 425 GST_AUDIO_API 426 void gst_audio_decoder_set_needs_format (GstAudioDecoder * dec, 427 gboolean enabled); 428 429 GST_AUDIO_API 430 gboolean gst_audio_decoder_get_needs_format (GstAudioDecoder * dec); 431 432 GST_AUDIO_API 433 void gst_audio_decoder_get_allocator (GstAudioDecoder * dec, 434 GstAllocator ** allocator, 435 GstAllocationParams * params); 436 437 GST_AUDIO_API 438 void gst_audio_decoder_merge_tags (GstAudioDecoder * dec, 439 const GstTagList * tags, GstTagMergeMode mode); 440 441 GST_AUDIO_API 442 void gst_audio_decoder_set_use_default_pad_acceptcaps (GstAudioDecoder * decoder, 443 gboolean use); 444 445 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC 446 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstAudioDecoder, gst_object_unref) 447 #endif 448 449 G_END_DECLS 450 451 #endif /* _GST_AUDIO_DECODER_H_ */ 452