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 | G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstAudioDecoder, gst_object_unref) |
446 | |
447 | G_END_DECLS |
448 | |
449 | #endif /* _GST_AUDIO_DECODER_H_ */ |
450 | |