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
29G_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 */
90typedef 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
149typedef 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 */
162typedef 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 */
182typedef 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 */
201typedef 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 */
217typedef 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 */
237struct _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
256GST_AUDIO_API
257GType gst_audio_format_info_get_type (void);
258
259/**
260 * GST_AUDIO_FORMAT_INFO_IS_VALID_RAW:
261 *
262 * Tests that the given #GstAudioFormatInfo represents a valid un-encoded
263 * format.
264 *
265 * Since: 1.22
266 */
267#define GST_AUDIO_FORMAT_INFO_IS_VALID_RAW(info) \
268 (info != NULL && (info)->format > GST_AUDIO_FORMAT_ENCODED && \
269 (info)->width > 0 && (info)->depth > 0)
270
271#define GST_AUDIO_FORMAT_INFO_FORMAT(info) ((info)->format)
272#define GST_AUDIO_FORMAT_INFO_NAME(info) ((info)->name)
273#define GST_AUDIO_FORMAT_INFO_FLAGS(info) ((info)->flags)
274
275#define GST_AUDIO_FORMAT_INFO_IS_INTEGER(info) !!((info)->flags & GST_AUDIO_FORMAT_FLAG_INTEGER)
276#define GST_AUDIO_FORMAT_INFO_IS_FLOAT(info) !!((info)->flags & GST_AUDIO_FORMAT_FLAG_FLOAT)
277#define GST_AUDIO_FORMAT_INFO_IS_SIGNED(info) !!((info)->flags & GST_AUDIO_FORMAT_FLAG_SIGNED)
278
279#define GST_AUDIO_FORMAT_INFO_ENDIANNESS(info) ((info)->endianness)
280#define GST_AUDIO_FORMAT_INFO_IS_LITTLE_ENDIAN(info) ((info)->endianness == G_LITTLE_ENDIAN)
281#define GST_AUDIO_FORMAT_INFO_IS_BIG_ENDIAN(info) ((info)->endianness == G_BIG_ENDIAN)
282#define GST_AUDIO_FORMAT_INFO_WIDTH(info) ((info)->width)
283#define GST_AUDIO_FORMAT_INFO_DEPTH(info) ((info)->depth)
284
285
286GST_AUDIO_API
287GstAudioFormat gst_audio_format_build_integer (gboolean sign, gint endianness,
288 gint width, gint depth) G_GNUC_CONST;
289
290GST_AUDIO_API
291GstAudioFormat gst_audio_format_from_string (const gchar *format) G_GNUC_CONST;
292
293GST_AUDIO_API
294const gchar * gst_audio_format_to_string (GstAudioFormat format) G_GNUC_CONST;
295
296GST_AUDIO_API
297const GstAudioFormatInfo *
298 gst_audio_format_get_info (GstAudioFormat format) G_GNUC_CONST;
299
300GST_AUDIO_API
301void gst_audio_format_info_fill_silence (const GstAudioFormatInfo *info,
302 gpointer dest, gsize length);
303GST_AUDIO_API G_DEPRECATED_FOR(gst_audio_format_info_fill_silence)
304void gst_audio_format_fill_silence (const GstAudioFormatInfo *info,
305 gpointer dest, gsize length);
306
307/**
308 * GST_AUDIO_RATE_RANGE:
309 *
310 * Maximum range of allowed sample rates, for use in template caps strings.
311 */
312#define GST_AUDIO_RATE_RANGE "(int) [ 1, max ]"
313/**
314 * GST_AUDIO_CHANNELS_RANGE:
315 *
316 * Maximum range of allowed channels, for use in template caps strings.
317 */
318#define GST_AUDIO_CHANNELS_RANGE "(int) [ 1, max ]"
319
320/**
321 * GST_AUDIO_NE:
322 * @s: format string without endianness marker
323 *
324 * Turns audio format string @s into the format string for native endianness.
325 */
326/**
327 * GST_AUDIO_OE:
328 * @s: format string without endianness marker
329 *
330 * Turns audio format string @s into the format string for other endianness.
331 */
332#if G_BYTE_ORDER == G_LITTLE_ENDIAN
333# define GST_AUDIO_NE(s) G_STRINGIFY(s)"LE"
334# define GST_AUDIO_OE(s) G_STRINGIFY(s)"BE"
335#else
336# define GST_AUDIO_NE(s) G_STRINGIFY(s)"BE"
337# define GST_AUDIO_OE(s) G_STRINGIFY(s)"LE"
338#endif
339
340/**
341 * GST_AUDIO_FORMATS_ALL:
342 *
343 * List of all audio formats, for use in template caps strings.
344 *
345 * Formats are sorted by decreasing "quality", using these criteria by priority:
346 * - depth
347 * - width
348 * - Float > Signed > Unsigned
349 * - native endianness preferred
350 */
351#if G_BYTE_ORDER == G_BIG_ENDIAN
352#define GST_AUDIO_FORMATS_ALL "{ F64BE, F64LE, " \
353 "F32BE, F32LE, S32BE, S32LE, U32BE, U32LE, " \
354 "S24_32BE, S24_32LE, U24_32BE, U24_32LE, " \
355 "S24BE, S24LE, U24BE, U24LE, " \
356 "S20BE, S20LE, U20BE, U20LE, " \
357 "S18BE, S18LE, U18BE, U18LE, " \
358 "S16BE, S16LE, U16BE, U16LE, " \
359 "S8, U8 }"
360#elif G_BYTE_ORDER == G_LITTLE_ENDIAN
361#define GST_AUDIO_FORMATS_ALL "{ F64LE, F64BE, " \
362 "F32LE, F32BE, S32LE, S32BE, U32LE, U32BE, " \
363 "S24_32LE, S24_32BE, U24_32LE, U24_32BE, " \
364 "S24LE, S24BE, U24LE, U24BE, " \
365 "S20LE, S20BE, U20LE, U20BE, " \
366 "S18LE, S18BE, U18LE, U18BE, " \
367 "S16LE, S16BE, U16LE, U16BE, " \
368 "S8, U8 }"
369#endif
370
371GST_AUDIO_API
372const GstAudioFormat * gst_audio_formats_raw (guint * len);
373
374/**
375 * GST_AUDIO_CAPS_MAKE:
376 * @format: string format that describes the sample layout, as string
377 * (e.g. "S16LE", "S8", etc.)
378 *
379 * Generic caps string for audio, for use in pad templates.
380 */
381#define GST_AUDIO_CAPS_MAKE(format) \
382 "audio/x-raw, " \
383 "format = (string) " format ", " \
384 "rate = " GST_AUDIO_RATE_RANGE ", " \
385 "channels = " GST_AUDIO_CHANNELS_RANGE
386
387/**
388 * GST_AUDIO_DEF_RATE:
389 *
390 * Standard sampling rate used in consumer audio.
391 */
392#define GST_AUDIO_DEF_RATE 44100
393/**
394 * GST_AUDIO_DEF_CHANNELS:
395 *
396 * Standard number of channels used in consumer audio.
397 */
398#define GST_AUDIO_DEF_CHANNELS 2
399/**
400 * GST_AUDIO_DEF_FORMAT:
401 *
402 * Standard format used in consumer audio.
403 */
404#define GST_AUDIO_DEF_FORMAT "S16LE"
405
406/**
407 * GstAudioLayout:
408 * @GST_AUDIO_LAYOUT_INTERLEAVED: interleaved audio
409 * @GST_AUDIO_LAYOUT_NON_INTERLEAVED: non-interleaved audio
410 *
411 * Layout of the audio samples for the different channels.
412 */
413typedef enum {
414 GST_AUDIO_LAYOUT_INTERLEAVED = 0,
415 GST_AUDIO_LAYOUT_NON_INTERLEAVED
416} GstAudioLayout;
417
418GST_AUDIO_API
419GstCaps * gst_audio_make_raw_caps (const GstAudioFormat formats[], guint len,
420 GstAudioLayout layout);
421
422G_END_DECLS
423
424#endif /* __GST_AUDIO_FORMAT_H__ */
425

source code of include/gstreamer-1.0/gst/audio/audio-format.h