1 | /* GStreamer |
2 | * Copyright (C) <1999> Erik Walthinsen <omega@cse.ogi.edu> |
3 | * Library <2001> Thomas Vander Stichele <thomas@apestaart.org> |
4 | * <2011> Wim Taymans <wim.taymans@gmail.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_AUDIO_AUDIO_H__ |
23 | #include <gst/audio/audio.h> |
24 | #endif |
25 | |
26 | #ifndef __GST_AUDIO_FORMAT_H__ |
27 | #define __GST_AUDIO_FORMAT_H__ |
28 | |
29 | G_BEGIN_DECLS |
30 | |
31 | #if G_BYTE_ORDER == G_BIG_ENDIAN |
32 | #define _GST_AUDIO_FORMAT_NE(fmt) GST_AUDIO_FORMAT_ ## fmt ## BE |
33 | #define _GST_AUDIO_FORMAT_OE(fmt) GST_AUDIO_FORMAT_ ## fmt ## LE |
34 | #elif G_BYTE_ORDER == G_LITTLE_ENDIAN |
35 | #define _GST_AUDIO_FORMAT_NE(fmt) GST_AUDIO_FORMAT_ ## fmt ## LE |
36 | #define _GST_AUDIO_FORMAT_OE(fmt) GST_AUDIO_FORMAT_ ## fmt ## BE |
37 | #endif |
38 | |
39 | /** |
40 | * GstAudioFormat: |
41 | * @GST_AUDIO_FORMAT_UNKNOWN: unknown or unset audio format |
42 | * @GST_AUDIO_FORMAT_ENCODED: encoded audio format |
43 | * @GST_AUDIO_FORMAT_S8: 8 bits in 8 bits, signed |
44 | * @GST_AUDIO_FORMAT_U8: 8 bits in 8 bits, unsigned |
45 | * @GST_AUDIO_FORMAT_S16LE: 16 bits in 16 bits, signed, little endian |
46 | * @GST_AUDIO_FORMAT_S16BE: 16 bits in 16 bits, signed, big endian |
47 | * @GST_AUDIO_FORMAT_U16LE: 16 bits in 16 bits, unsigned, little endian |
48 | * @GST_AUDIO_FORMAT_U16BE: 16 bits in 16 bits, unsigned, big endian |
49 | * @GST_AUDIO_FORMAT_S24_32LE: 24 bits in 32 bits, signed, little endian |
50 | * @GST_AUDIO_FORMAT_S24_32BE: 24 bits in 32 bits, signed, big endian |
51 | * @GST_AUDIO_FORMAT_U24_32LE: 24 bits in 32 bits, unsigned, little endian |
52 | * @GST_AUDIO_FORMAT_U24_32BE: 24 bits in 32 bits, unsigned, big endian |
53 | * @GST_AUDIO_FORMAT_S32LE: 32 bits in 32 bits, signed, little endian |
54 | * @GST_AUDIO_FORMAT_S32BE: 32 bits in 32 bits, signed, big endian |
55 | * @GST_AUDIO_FORMAT_U32LE: 32 bits in 32 bits, unsigned, little endian |
56 | * @GST_AUDIO_FORMAT_U32BE: 32 bits in 32 bits, unsigned, big endian |
57 | * @GST_AUDIO_FORMAT_S24LE: 24 bits in 24 bits, signed, little endian |
58 | * @GST_AUDIO_FORMAT_S24BE: 24 bits in 24 bits, signed, big endian |
59 | * @GST_AUDIO_FORMAT_U24LE: 24 bits in 24 bits, unsigned, little endian |
60 | * @GST_AUDIO_FORMAT_U24BE: 24 bits in 24 bits, unsigned, big endian |
61 | * @GST_AUDIO_FORMAT_S20LE: 20 bits in 24 bits, signed, little endian |
62 | * @GST_AUDIO_FORMAT_S20BE: 20 bits in 24 bits, signed, big endian |
63 | * @GST_AUDIO_FORMAT_U20LE: 20 bits in 24 bits, unsigned, little endian |
64 | * @GST_AUDIO_FORMAT_U20BE: 20 bits in 24 bits, unsigned, big endian |
65 | * @GST_AUDIO_FORMAT_S18LE: 18 bits in 24 bits, signed, little endian |
66 | * @GST_AUDIO_FORMAT_S18BE: 18 bits in 24 bits, signed, big endian |
67 | * @GST_AUDIO_FORMAT_U18LE: 18 bits in 24 bits, unsigned, little endian |
68 | * @GST_AUDIO_FORMAT_U18BE: 18 bits in 24 bits, unsigned, big endian |
69 | * @GST_AUDIO_FORMAT_F32LE: 32-bit floating point samples, little endian |
70 | * @GST_AUDIO_FORMAT_F32BE: 32-bit floating point samples, big endian |
71 | * @GST_AUDIO_FORMAT_F64LE: 64-bit floating point samples, little endian |
72 | * @GST_AUDIO_FORMAT_F64BE: 64-bit floating point samples, big endian |
73 | * @GST_AUDIO_FORMAT_S16: 16 bits in 16 bits, signed, native endianness |
74 | * @GST_AUDIO_FORMAT_U16: 16 bits in 16 bits, unsigned, native endianness |
75 | * @GST_AUDIO_FORMAT_S24_32: 24 bits in 32 bits, signed, native endianness |
76 | * @GST_AUDIO_FORMAT_U24_32: 24 bits in 32 bits, unsigned, native endianness |
77 | * @GST_AUDIO_FORMAT_S32: 32 bits in 32 bits, signed, native endianness |
78 | * @GST_AUDIO_FORMAT_U32: 32 bits in 32 bits, unsigned, native endianness |
79 | * @GST_AUDIO_FORMAT_S24: 24 bits in 24 bits, signed, native endianness |
80 | * @GST_AUDIO_FORMAT_U24: 24 bits in 24 bits, unsigned, native endianness |
81 | * @GST_AUDIO_FORMAT_S20: 20 bits in 24 bits, signed, native endianness |
82 | * @GST_AUDIO_FORMAT_U20: 20 bits in 24 bits, unsigned, native endianness |
83 | * @GST_AUDIO_FORMAT_S18: 18 bits in 24 bits, signed, native endianness |
84 | * @GST_AUDIO_FORMAT_U18: 18 bits in 24 bits, unsigned, native endianness |
85 | * @GST_AUDIO_FORMAT_F32: 32-bit floating point samples, native endianness |
86 | * @GST_AUDIO_FORMAT_F64: 64-bit floating point samples, native endianness |
87 | * |
88 | * Enum value describing the most common audio formats. |
89 | */ |
90 | typedef enum { |
91 | GST_AUDIO_FORMAT_UNKNOWN, |
92 | GST_AUDIO_FORMAT_ENCODED, |
93 | /* 8 bit */ |
94 | GST_AUDIO_FORMAT_S8, |
95 | GST_AUDIO_FORMAT_U8, |
96 | /* 16 bit */ |
97 | GST_AUDIO_FORMAT_S16LE, |
98 | GST_AUDIO_FORMAT_S16BE, |
99 | GST_AUDIO_FORMAT_U16LE, |
100 | GST_AUDIO_FORMAT_U16BE, |
101 | /* 24 bit in low 3 bytes of 32 bits*/ |
102 | GST_AUDIO_FORMAT_S24_32LE, |
103 | GST_AUDIO_FORMAT_S24_32BE, |
104 | GST_AUDIO_FORMAT_U24_32LE, |
105 | GST_AUDIO_FORMAT_U24_32BE, |
106 | /* 32 bit */ |
107 | GST_AUDIO_FORMAT_S32LE, |
108 | GST_AUDIO_FORMAT_S32BE, |
109 | GST_AUDIO_FORMAT_U32LE, |
110 | GST_AUDIO_FORMAT_U32BE, |
111 | /* 24 bit in 3 bytes*/ |
112 | GST_AUDIO_FORMAT_S24LE, |
113 | GST_AUDIO_FORMAT_S24BE, |
114 | GST_AUDIO_FORMAT_U24LE, |
115 | GST_AUDIO_FORMAT_U24BE, |
116 | /* 20 bit in 3 bytes*/ |
117 | GST_AUDIO_FORMAT_S20LE, |
118 | GST_AUDIO_FORMAT_S20BE, |
119 | GST_AUDIO_FORMAT_U20LE, |
120 | GST_AUDIO_FORMAT_U20BE, |
121 | /* 18 bit in 3 bytes*/ |
122 | GST_AUDIO_FORMAT_S18LE, |
123 | GST_AUDIO_FORMAT_S18BE, |
124 | GST_AUDIO_FORMAT_U18LE, |
125 | GST_AUDIO_FORMAT_U18BE, |
126 | /* float */ |
127 | GST_AUDIO_FORMAT_F32LE, |
128 | GST_AUDIO_FORMAT_F32BE, |
129 | GST_AUDIO_FORMAT_F64LE, |
130 | GST_AUDIO_FORMAT_F64BE, |
131 | /* native endianness equivalents */ |
132 | GST_AUDIO_FORMAT_S16 = _GST_AUDIO_FORMAT_NE(S16), |
133 | GST_AUDIO_FORMAT_U16 = _GST_AUDIO_FORMAT_NE(U16), |
134 | GST_AUDIO_FORMAT_S24_32 = _GST_AUDIO_FORMAT_NE(S24_32), |
135 | GST_AUDIO_FORMAT_U24_32 = _GST_AUDIO_FORMAT_NE(U24_32), |
136 | GST_AUDIO_FORMAT_S32 = _GST_AUDIO_FORMAT_NE(S32), |
137 | GST_AUDIO_FORMAT_U32 = _GST_AUDIO_FORMAT_NE(U32), |
138 | GST_AUDIO_FORMAT_S24 = _GST_AUDIO_FORMAT_NE(S24), |
139 | GST_AUDIO_FORMAT_U24 = _GST_AUDIO_FORMAT_NE(U24), |
140 | GST_AUDIO_FORMAT_S20 = _GST_AUDIO_FORMAT_NE(S20), |
141 | GST_AUDIO_FORMAT_U20 = _GST_AUDIO_FORMAT_NE(U20), |
142 | GST_AUDIO_FORMAT_S18 = _GST_AUDIO_FORMAT_NE(S18), |
143 | GST_AUDIO_FORMAT_U18 = _GST_AUDIO_FORMAT_NE(U18), |
144 | GST_AUDIO_FORMAT_F32 = _GST_AUDIO_FORMAT_NE(F32), |
145 | GST_AUDIO_FORMAT_F64 = _GST_AUDIO_FORMAT_NE(F64) |
146 | } GstAudioFormat; |
147 | |
148 | |
149 | typedef struct _GstAudioFormatInfo GstAudioFormatInfo; |
150 | |
151 | /** |
152 | * GstAudioFormatFlags: |
153 | * @GST_AUDIO_FORMAT_FLAG_INTEGER: integer samples |
154 | * @GST_AUDIO_FORMAT_FLAG_FLOAT: float samples |
155 | * @GST_AUDIO_FORMAT_FLAG_SIGNED: signed samples |
156 | * @GST_AUDIO_FORMAT_FLAG_COMPLEX: complex layout |
157 | * @GST_AUDIO_FORMAT_FLAG_UNPACK: the format can be used in |
158 | * #GstAudioFormatUnpack and #GstAudioFormatPack functions |
159 | * |
160 | * The different audio flags that a format info can have. |
161 | */ |
162 | typedef enum |
163 | { |
164 | GST_AUDIO_FORMAT_FLAG_INTEGER = (1 << 0), |
165 | GST_AUDIO_FORMAT_FLAG_FLOAT = (1 << 1), |
166 | GST_AUDIO_FORMAT_FLAG_SIGNED = (1 << 2), |
167 | GST_AUDIO_FORMAT_FLAG_COMPLEX = (1 << 4), |
168 | GST_AUDIO_FORMAT_FLAG_UNPACK = (1 << 5) |
169 | } GstAudioFormatFlags; |
170 | |
171 | /** |
172 | * GstAudioPackFlags: |
173 | * @GST_AUDIO_PACK_FLAG_NONE: No flag |
174 | * @GST_AUDIO_PACK_FLAG_TRUNCATE_RANGE: When the source has a smaller depth |
175 | * than the target format, set the least significant bits of the target |
176 | * to 0. This is likely slightly faster but less accurate. When this flag |
177 | * is not specified, the most significant bits of the source are duplicated |
178 | * in the least significant bits of the destination. |
179 | * |
180 | * The different flags that can be used when packing and unpacking. |
181 | */ |
182 | typedef enum |
183 | { |
184 | GST_AUDIO_PACK_FLAG_NONE = 0, |
185 | GST_AUDIO_PACK_FLAG_TRUNCATE_RANGE = (1 << 0) |
186 | } GstAudioPackFlags; |
187 | |
188 | /** |
189 | * GstAudioFormatUnpack: |
190 | * @info: a #GstAudioFormatInfo |
191 | * @flags: #GstAudioPackFlags |
192 | * @dest: (array) (element-type guint8): a destination array |
193 | * @data: (array) (element-type guint8): pointer to the audio data |
194 | * @length: the amount of samples to unpack. |
195 | * |
196 | * Unpacks @length samples from the given data of format @info. |
197 | * The samples will be unpacked into @dest which each channel |
198 | * interleaved. @dest should at least be big enough to hold @length * |
199 | * channels * size(unpack_format) bytes. |
200 | */ |
201 | typedef void (*GstAudioFormatUnpack) (const GstAudioFormatInfo *info, |
202 | GstAudioPackFlags flags, gpointer dest, |
203 | gconstpointer data, gint length); |
204 | /** |
205 | * GstAudioFormatPack: |
206 | * @info: a #GstAudioFormatInfo |
207 | * @flags: #GstAudioPackFlags |
208 | * @src: (array) (element-type guint8): a source array |
209 | * @data: (array) (element-type guint8): pointer to the destination |
210 | * data |
211 | * @length: the amount of samples to pack. |
212 | * |
213 | * Packs @length samples from @src to the data array in format @info. |
214 | * The samples from source have each channel interleaved |
215 | * and will be packed into @data. |
216 | */ |
217 | typedef void (*GstAudioFormatPack) (const GstAudioFormatInfo *info, |
218 | GstAudioPackFlags flags, gconstpointer src, |
219 | gpointer data, gint length); |
220 | |
221 | /** |
222 | * GstAudioFormatInfo: |
223 | * @format: #GstAudioFormat |
224 | * @name: string representation of the format |
225 | * @description: user readable description of the format |
226 | * @flags: #GstAudioFormatFlags |
227 | * @endianness: the endianness |
228 | * @width: amount of bits used for one sample |
229 | * @depth: amount of valid bits in @width |
230 | * @silence: @width/8 bytes with 1 silent sample |
231 | * @unpack_format: the format of the unpacked samples |
232 | * @unpack_func: function to unpack samples |
233 | * @pack_func: function to pack samples |
234 | * |
235 | * Information for an audio format. |
236 | */ |
237 | struct _GstAudioFormatInfo { |
238 | /*< public >*/ |
239 | GstAudioFormat format; |
240 | const gchar *name; |
241 | const gchar *description; |
242 | GstAudioFormatFlags flags; |
243 | gint endianness; |
244 | gint width; |
245 | gint depth; |
246 | guint8 silence[8]; |
247 | |
248 | GstAudioFormat unpack_format; |
249 | GstAudioFormatUnpack unpack_func; |
250 | GstAudioFormatPack pack_func; |
251 | |
252 | /*< private >*/ |
253 | gpointer _gst_reserved[GST_PADDING]; |
254 | }; |
255 | |
256 | GST_AUDIO_API |
257 | GType gst_audio_format_info_get_type (void); |
258 | |
259 | #define GST_AUDIO_FORMAT_INFO_FORMAT(info) ((info)->format) |
260 | #define GST_AUDIO_FORMAT_INFO_NAME(info) ((info)->name) |
261 | #define GST_AUDIO_FORMAT_INFO_FLAGS(info) ((info)->flags) |
262 | |
263 | #define GST_AUDIO_FORMAT_INFO_IS_INTEGER(info) !!((info)->flags & GST_AUDIO_FORMAT_FLAG_INTEGER) |
264 | #define GST_AUDIO_FORMAT_INFO_IS_FLOAT(info) !!((info)->flags & GST_AUDIO_FORMAT_FLAG_FLOAT) |
265 | #define GST_AUDIO_FORMAT_INFO_IS_SIGNED(info) !!((info)->flags & GST_AUDIO_FORMAT_FLAG_SIGNED) |
266 | |
267 | #define GST_AUDIO_FORMAT_INFO_ENDIANNESS(info) ((info)->endianness) |
268 | #define GST_AUDIO_FORMAT_INFO_IS_LITTLE_ENDIAN(info) ((info)->endianness == G_LITTLE_ENDIAN) |
269 | #define GST_AUDIO_FORMAT_INFO_IS_BIG_ENDIAN(info) ((info)->endianness == G_BIG_ENDIAN) |
270 | #define GST_AUDIO_FORMAT_INFO_WIDTH(info) ((info)->width) |
271 | #define GST_AUDIO_FORMAT_INFO_DEPTH(info) ((info)->depth) |
272 | |
273 | |
274 | GST_AUDIO_API |
275 | GstAudioFormat gst_audio_format_build_integer (gboolean sign, gint endianness, |
276 | gint width, gint depth) G_GNUC_CONST; |
277 | |
278 | GST_AUDIO_API |
279 | GstAudioFormat gst_audio_format_from_string (const gchar *format) G_GNUC_CONST; |
280 | |
281 | GST_AUDIO_API |
282 | const gchar * gst_audio_format_to_string (GstAudioFormat format) G_GNUC_CONST; |
283 | |
284 | GST_AUDIO_API |
285 | const GstAudioFormatInfo * |
286 | gst_audio_format_get_info (GstAudioFormat format) G_GNUC_CONST; |
287 | |
288 | GST_AUDIO_API |
289 | void gst_audio_format_info_fill_silence (const GstAudioFormatInfo *info, |
290 | gpointer dest, gsize length); |
291 | GST_AUDIO_API G_DEPRECATED_FOR(gst_audio_format_info_fill_silence) |
292 | void gst_audio_format_fill_silence (const GstAudioFormatInfo *info, |
293 | gpointer dest, gsize length); |
294 | |
295 | /** |
296 | * GST_AUDIO_RATE_RANGE: |
297 | * |
298 | * Maximum range of allowed sample rates, for use in template caps strings. |
299 | */ |
300 | #define GST_AUDIO_RATE_RANGE "(int) [ 1, max ]" |
301 | /** |
302 | * GST_AUDIO_CHANNELS_RANGE: |
303 | * |
304 | * Maximum range of allowed channels, for use in template caps strings. |
305 | */ |
306 | #define GST_AUDIO_CHANNELS_RANGE "(int) [ 1, max ]" |
307 | |
308 | /** |
309 | * GST_AUDIO_NE: |
310 | * @s: format string without endianness marker |
311 | * |
312 | * Turns audio format string @s into the format string for native endianness. |
313 | */ |
314 | /** |
315 | * GST_AUDIO_OE: |
316 | * @s: format string without endianness marker |
317 | * |
318 | * Turns audio format string @s into the format string for other endianness. |
319 | */ |
320 | #if G_BYTE_ORDER == G_LITTLE_ENDIAN |
321 | # define GST_AUDIO_NE(s) G_STRINGIFY(s)"LE" |
322 | # define GST_AUDIO_OE(s) G_STRINGIFY(s)"BE" |
323 | #else |
324 | # define GST_AUDIO_NE(s) G_STRINGIFY(s)"BE" |
325 | # define GST_AUDIO_OE(s) G_STRINGIFY(s)"LE" |
326 | #endif |
327 | |
328 | /** |
329 | * GST_AUDIO_FORMATS_ALL: |
330 | * |
331 | * List of all audio formats, for use in template caps strings. |
332 | * |
333 | * Formats are sorted by decreasing "quality", using these criteria by priority: |
334 | * - depth |
335 | * - width |
336 | * - Float > Signed > Unsigned |
337 | * - native endianness preferred |
338 | */ |
339 | #if G_BYTE_ORDER == G_BIG_ENDIAN |
340 | #define GST_AUDIO_FORMATS_ALL "{ F64BE, F64LE, " \ |
341 | "F32BE, F32LE, S32BE, S32LE, U32BE, U32LE, " \ |
342 | "S24_32BE, S24_32LE, U24_32BE, U24_32LE, " \ |
343 | "S24BE, S24LE, U24BE, U24LE, " \ |
344 | "S20BE, S20LE, U20BE, U20LE, " \ |
345 | "S18BE, S18LE, U18BE, U18LE, " \ |
346 | "S16BE, S16LE, U16BE, U16LE, " \ |
347 | "S8, U8 }" |
348 | #elif G_BYTE_ORDER == G_LITTLE_ENDIAN |
349 | #define GST_AUDIO_FORMATS_ALL "{ F64LE, F64BE, " \ |
350 | "F32LE, F32BE, S32LE, S32BE, U32LE, U32BE, " \ |
351 | "S24_32LE, S24_32BE, U24_32LE, U24_32BE, " \ |
352 | "S24LE, S24BE, U24LE, U24BE, " \ |
353 | "S20LE, S20BE, U20LE, U20BE, " \ |
354 | "S18LE, S18BE, U18LE, U18BE, " \ |
355 | "S16LE, S16BE, U16LE, U16BE, " \ |
356 | "S8, U8 }" |
357 | #endif |
358 | |
359 | GST_AUDIO_API |
360 | const GstAudioFormat * gst_audio_formats_raw (guint * len); |
361 | |
362 | /** |
363 | * GST_AUDIO_CAPS_MAKE: |
364 | * @format: string format that describes the sample layout, as string |
365 | * (e.g. "S16LE", "S8", etc.) |
366 | * |
367 | * Generic caps string for audio, for use in pad templates. |
368 | */ |
369 | #define GST_AUDIO_CAPS_MAKE(format) \ |
370 | "audio/x-raw, " \ |
371 | "format = (string) " format ", " \ |
372 | "rate = " GST_AUDIO_RATE_RANGE ", " \ |
373 | "channels = " GST_AUDIO_CHANNELS_RANGE |
374 | |
375 | /** |
376 | * GST_AUDIO_DEF_RATE: |
377 | * |
378 | * Standard sampling rate used in consumer audio. |
379 | */ |
380 | #define GST_AUDIO_DEF_RATE 44100 |
381 | /** |
382 | * GST_AUDIO_DEF_CHANNELS: |
383 | * |
384 | * Standard number of channels used in consumer audio. |
385 | */ |
386 | #define GST_AUDIO_DEF_CHANNELS 2 |
387 | /** |
388 | * GST_AUDIO_DEF_FORMAT: |
389 | * |
390 | * Standard format used in consumer audio. |
391 | */ |
392 | #define GST_AUDIO_DEF_FORMAT "S16LE" |
393 | |
394 | /** |
395 | * GstAudioLayout: |
396 | * @GST_AUDIO_LAYOUT_INTERLEAVED: interleaved audio |
397 | * @GST_AUDIO_LAYOUT_NON_INTERLEAVED: non-interleaved audio |
398 | * |
399 | * Layout of the audio samples for the different channels. |
400 | */ |
401 | typedef enum { |
402 | GST_AUDIO_LAYOUT_INTERLEAVED = 0, |
403 | GST_AUDIO_LAYOUT_NON_INTERLEAVED |
404 | } GstAudioLayout; |
405 | |
406 | GST_AUDIO_API |
407 | GstCaps * gst_audio_make_raw_caps (const GstAudioFormat formats[], guint len, |
408 | GstAudioLayout layout); |
409 | |
410 | G_END_DECLS |
411 | |
412 | #endif /* __GST_AUDIO_FORMAT_H__ */ |
413 | |