1
@comment $Id: conversion.texi,v 1.3.2.1 2001/12/23 15:21:43 nold Exp $
3
@node Conversion Layer, Swapfile API, Filter Tutorial, Top
4
@chapter Conversion Layer
6
The GLAME conversion layer is meant to provide a uniform and efficient
7
API for conversion of audio data between different formats. It will mainly
8
be useful to the various i/o plugins, i.e. plugins doing audio i/o, file
9
i/o, swapfile i/o and the like. The conversion layer is capable of
10
interleaving and de-interleaving audio streams. It also performs endianness
11
and type conversions of individual samples. The user has to supply
12
information on the layout of source and destination data, and the conversion
13
layer will internally try to find the most optimized conversion path. Use
14
of extended features of current hardware like 3Dnow, ISSE, or AltiVec is
15
completely hidden from the caller.
17
This documentation describes the externally visible API the conversion layer
18
presents to its callers. If you are about to write a new i/o plugin for
19
GLAME, you should probably go on reading. If you want to hack up another
20
optimised conversion routine for the processor of your choice, have a look
21
at the source instead.
25
This is the rare case of a design preceeding its implementation. This
26
documentation is provided here for discussion among developers. The
27
API cannot actually be used yet.
30
Send comments on the conversion layer or this documentation to
31
@email{glame-devel@@glame.sourceforge.net} (c/o nold).
36
* Describing the data layout::
37
* Getting your custom-tailored conversion routine::
38
* Invoking data conversions::
41
@node Prototypes, Versioning, , Conversion Layer
44
All types and methods used by the GLAME conversion layer are prefixed
45
by @code{gcv_}. Prototypes can be obtained via
49
#include <glame_conv.h>
53
@node Versioning, Describing the data layout, Prototypes, Conversion Layer
56
As the GLAME conversion layer de facto presents an ABI to third-party
57
plugins, it uses its own version scheme to denote changes in its
58
interface structure. The version comprises of two numbers, generation and
59
revision. The revision is incremented whenever an additional feature
60
is added that doesn't break existing users. Incrementing the generation
61
count indicates a change in interface layout that is not backward-compatible.
63
To obtain the version numbers of the conversion layer, call
65
@findex gcv_get_generation
66
@findex gcv_get_revision
68
@deftypefun unsigned int gcv_get_generation (gcv_version_t @var{ver})
69
@deftypefunx unsigned int gcv_get_revision (gcv_version_t @var{ver})
70
to get generation and revision respectively.
73
This documentation describes the GLAME conversion layer interface generation
76
@node Describing the data layout, Getting your custom-tailored conversion routine, Versioning, Conversion Layer
77
@section Describing the data layout
79
The GLAME conversion layer so far only handles tightly packed streams of audio
80
data, i.e. padding is not supported yet. Furthermore, if there are multiple
81
streams of audio data, each stream must carry the same number of interleave
82
channels. Sample properties have to be equal among all data as well.
83
Therefore a chunk of audio data is described by the following
87
@item Number of separate audio streams.
88
@item Number of interleaved channels per audio stream.
89
@item Width of a sample in bits.
90
@item Type of a sample.
91
@item Endianness of a sample.
94
For example, a typical stereo chunk of the form ABABABAB... is described
95
as one stream, two channels interleaved. Sample properties might
96
be width 16 bit, type unsigned integer, little endian. (That's the most
97
common layout of Wave/PCM files actually.)
99
Users of the conversion layer have to specify the layout of the source data,
100
as well as the desired target layout. This is done using the following
103
@findex gcv_get_layout
104
@findex gcv_drop_layout
106
@deftypefun gcv_layout_t gcv_get_layout (void)
107
@deftypefunx void gcv_drop_layout (gcv_layout_t @var{layout})
108
Gets an uninitialised layout handle, or drops all ressources associated to
109
a valid layout handle, respectively.
112
@findex gcv_set_streams
114
@deftypefun int gcv_set_streams (gcv_layout_t @var{layout}, unsigned int @var{num_stream})
115
Sets the number of individual audio streams on @var{layout} to
116
@var{num_stream}. @var{layout} needs to be a valid layout handle returned
117
by @code{gcv_get_layout()}. -1 is returned on error, 0 on success.
120
@findex gcv_set_channels
122
@deftypefun int gcv_set_channels (gcv_layout_t @var{layout}, unsigned int @var{num_ch})
123
Sets the number of interleaved audio channels per stream. @var{layout} needs
124
to be a valid layout handle returned by @code{gcv_get_layout()}. -1 is
125
returned on error, 0 on success.
128
@findex gcv_set_width
130
@deftypefun int gcv_set_width (gcv_layout_t @var{layout}, unsigned int @var{width})
131
Sets the width of a single audio sample on @var{layout} to @var{width} bits.
132
@var{layout} needs to be a valid layout handle returned by
133
@code{gcv_get_layout()}. -1 is returned on error, 0 on success.
139
@deftypefun int gcv_set_type (gcv_layout_t @var{layout}, gcv_type_t @var{type})
140
Sets the type of a single audio sample on @var{layout} to @var{type}.
141
@var{layout} needs to be a valid layout handle returned by
142
@code{gcv_get_layout()}. -1 is returned on error, 0 on success.
143
@code{gcv_type_t} is defined in @file{glame_conv.h} and may be one of
149
for unsigned integer values;
151
for (signed) floating point values.
155
@findex gcv_set_endian
158
@deftypefun int gcv_set_endian ( gcv_layout_t @var{layout}, gcv_endian_t @var{endian})
159
Sets the endianness of a single audio sample on @var{layout} to @var{endian}.
160
@var{layout} needs to be a valid layout handle returned by
161
@code{gcv_get_layout()}. -1 is returned on error, 0 on success.
162
@code{gcv_endian_t} is defined in @file{glame_conv.h} and may be one of
166
@item GCV_LITTLE_ENDIAN
167
@item GCV_NATIVE_ENDIAN
170
The latter describing that the data is formatted in a machine's native
171
endianness, which is determined at compile time.
174
@node Getting your custom-tailored conversion routine, Invoking data conversions, Describing the data layout, Conversion Layer
175
@section Getting your custom-tailored conversion routine
177
Once layout of source and target data are set up, a set of conversions
178
between the two of them has to be found. This step is performed transparently
179
to the user when the layouts are registered with the conversion layer.
181
@findex gcv_get_conversion
182
@findex gcv_drop_conversion
185
@deftypefun gcv_conv_t gcv_get_conversion (gcv_layout_t @var{source}, gcv_layout_t @var{target})
186
@deftypefunx void gcv_drop_conversion (gcv_conv_t @var{cv})
187
Gets a new handle on a conversion from @var{source} to @var{target}, or
188
drops all associated ressources respectively. @code{gcv_get_conversion}
189
returns a valid handle on success, or @code{NULL} on error.
194
We need another option to tell whether the conversion may be
195
destructive. Ought not to scribble on an mmap()ed soundfile! Requiring the
196
caller to copy to a safe buffer probably ain't the best calling convention
200
@node Invoking data conversions, , Getting your custom-tailored conversion routine, Conversion Layer
201
@section Invoking data conversions
203
The conversion layer operates from memory to memory only. Writing to or
204
reading directly from files may be achieved via @code{mmap()}. Sockets are
205
currently unsupported and must be handled via bounce buffers. This limitation
206
might be dropped in future versions. Internally, bounce buffers are only
207
allocated when necessary, i.e. if source and target layout match, the input
208
buffer is passed on unmodified, so there's no need to special case in
211
@findex gcv_do_conversion
213
@deftypefun (char **) gcv_do_conversion (char **@var{out}, char **@var{in}, unsigned int @var{spc}, gcv_conv_t @var{cv})
214
Converts data from @var{in} to @var{out} according to previously registered
215
layout settings defined via @var{cv}. @var{spc} is the number of samples per
216
channel to be converted. @var{in} is an array of pointers to the input data
217
streams. The array's size has to match the number of streams given in the
218
source layout. @var{out} is an array of pointers to memory locations that
219
shall be filled with the converted data. The array's size has to match the
220
number of streams given in the target layout. If @var{out} is @code{NULL}, the
221
target buffers will be allocated internally by @code{gcv_do_conversion}, and
222
a pointer to a @code{NULL}-terminated array of pointers to the target buffers is
223
returned. Calling code is responsible to free all buffers and the array itself
224
in this case. @code{gcv_do_conversion} returns @code{NULL} if an error was
225
encountered, or a pointer to the array of pointers to the target buffers on
added
removed
doc/conversion.texi
