132
128
* It is easiest to just describe the dependencies:
134
130
* - All modules depend on the \link flac_format Format \endlink module.
135
* - The decoders and encoders are independent of each other.
136
* - The metadata interface requires the file decoder.
137
* - The decoder and encoder layers depend on the layers below them, but
138
* not above them; e.g. the seekable stream decoder depends on the stream
139
* decoder but not the file decoder
131
* - The decoders and encoders depend on the bitbuffer.
132
* - The decoder is independent of the encoder. The encoder uses the
133
* decoder because of the verify feature, but this can be removed if
135
* - Parts of the metadata interface require the stream decoder (but not
137
* - Ogg support is selectable through the compile time macro
141
140
* For example, if your application only requires the stream decoder, no
142
* encoders, and no metadata interface, you can remove the seekable stream
143
* decoder, file decoder, all encoders, and the metadata interface, which
144
* will greatly reduce the size of the library.
141
* encoder, and no metadata interface, you can remove the stream encoder
142
* and the metadata interface, which will greatly reduce the size of the
146
/** \defgroup porting Porting Guide for New Versions
148
* This module describes differences in the library interfaces from
149
* version to version. It assists in the porting of code that uses
150
* the libraries to newer versions of FLAC.
152
* One simple facility for making porting easier that has been added
153
* in FLAC 1.1.3 is a set of \c #defines in \c export.h of each
154
* library's includes (e.g. \c include/FLAC/export.h). The
155
* \c #defines mirror the libraries'
156
* <A HREF="http://www.gnu.org/software/libtool/manual.html#Libtool-versioning">libtool version numbers</A>,
157
* e.g. in libFLAC there are \c FLAC_API_VERSION_CURRENT,
158
* \c FLAC_API_VERSION_REVISION, and \c FLAC_API_VERSION_AGE.
159
* These can be used to support multiple versions of an API during the
160
* transition phase, e.g.
163
* #if !defined(FLAC_API_VERSION_CURRENT) || FLAC_API_VERSION_CURRENT <= 7
170
* The the source will work for multiple versions and the legacy code can
171
* easily be removed when the transition is complete.
173
* Another available symbol is FLAC_API_SUPPORTS_OGG_FLAC (defined in
174
* include/FLAC/export.h), which can be used to determine whether or not
175
* the library has been compiled with support for Ogg FLAC. This is
176
* simpler than trying to call an Ogg init function and catching the
180
/** \defgroup porting_1_1_2_to_1_1_3 Porting from FLAC 1.1.2 to 1.1.3
184
* This module describes porting from FLAC 1.1.2 to FLAC 1.1.3.
186
* The main change between the APIs in 1.1.2 and 1.1.3 is that they have
187
* been simplified. First, libOggFLAC has been merged into libFLAC and
188
* libOggFLAC++ has been merged into libFLAC++. Second, both the three
189
* decoding layers and three encoding layers have been merged into a
190
* single stream decoder and stream encoder. That is, the functionality
191
* of FLAC__SeekableStreamDecoder and FLAC__FileDecoder has been merged
192
* into FLAC__StreamDecoder, and FLAC__SeekableStreamEncoder and
193
* FLAC__FileEncoder into FLAC__StreamEncoder. Only the
194
* FLAC__StreamDecoder and FLAC__StreamEncoder remain. What this means
195
* is there is now a single API that can be used to encode or decode
196
* streams to/from native FLAC or Ogg FLAC and the single API can work
197
* on both seekable and non-seekable streams.
199
* Instead of creating an encoder or decoder of a certain layer, now the
200
* client will always create a FLAC__StreamEncoder or
201
* FLAC__StreamDecoder. The old layers are now differentiated by the
202
* initialization function. For example, for the decoder,
203
* FLAC__stream_decoder_init() has been replaced by
204
* FLAC__stream_decoder_init_stream(). This init function takes
205
* callbacks for the I/O, and the seeking callbacks are optional. This
206
* allows the client to use the same object for seekable and
207
* non-seekable streams. For decoding a FLAC file directly, the client
208
* can use FLAC__stream_decoder_init_file() and pass just a filename
209
* and fewer callbacks; most of the other callbacks are supplied
210
* internally. For situations where fopen()ing by filename is not
211
* possible (e.g. Unicode filenames on Windows) the client can instead
212
* open the file itself and supply the FILE* to
213
* FLAC__stream_decoder_init_FILE(). The init functions now returns a
214
* FLAC__StreamDecoderInitStatus instead of FLAC__StreamDecoderState.
215
* Since the callbacks and client data are now passed to the init
216
* function, the FLAC__stream_decoder_set_*_callback() functions and
217
* FLAC__stream_decoder_set_client_data() are no longer needed. The
218
* rest of the calls to the decoder are the same as before.
220
* There are counterpart init functions for Ogg FLAC, e.g.
221
* FLAC__stream_decoder_init_ogg_stream(). All the rest of the calls
222
* and callbacks are the same as for native FLAC.
224
* As an example, in FLAC 1.1.2 a seekable stream decoder would have
225
* been set up like so:
228
* FLAC__SeekableStreamDecoder *decoder = FLAC__seekable_stream_decoder_new();
229
* if(decoder == NULL) do_something;
230
* FLAC__seekable_stream_decoder_set_md5_checking(decoder, true);
231
* [... other settings ...]
232
* FLAC__seekable_stream_decoder_set_read_callback(decoder, my_read_callback);
233
* FLAC__seekable_stream_decoder_set_seek_callback(decoder, my_seek_callback);
234
* FLAC__seekable_stream_decoder_set_tell_callback(decoder, my_tell_callback);
235
* FLAC__seekable_stream_decoder_set_length_callback(decoder, my_length_callback);
236
* FLAC__seekable_stream_decoder_set_eof_callback(decoder, my_eof_callback);
237
* FLAC__seekable_stream_decoder_set_write_callback(decoder, my_write_callback);
238
* FLAC__seekable_stream_decoder_set_metadata_callback(decoder, my_metadata_callback);
239
* FLAC__seekable_stream_decoder_set_error_callback(decoder, my_error_callback);
240
* FLAC__seekable_stream_decoder_set_client_data(decoder, my_client_data);
241
* if(FLAC__seekable_stream_decoder_init(decoder) != FLAC__SEEKABLE_STREAM_DECODER_OK) do_something;
244
* In FLAC 1.1.3 it is like this:
247
* FLAC__StreamDecoder *decoder = FLAC__stream_decoder_new();
248
* if(decoder == NULL) do_something;
249
* FLAC__stream_decoder_set_md5_checking(decoder, true);
250
* [... other settings ...]
251
* if(FLAC__stream_decoder_init_stream(
254
* my_seek_callback, // or NULL
255
* my_tell_callback, // or NULL
256
* my_length_callback, // or NULL
257
* my_eof_callback, // or NULL
259
* my_metadata_callback, // or NULL
262
* ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
269
* FILE *file = fopen("somefile.flac","rb");
270
* if(file == NULL) do_somthing;
271
* if(FLAC__stream_decoder_init_FILE(
275
* my_metadata_callback, // or NULL
278
* ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
285
* if(FLAC__stream_decoder_init_file(
289
* my_metadata_callback, // or NULL
292
* ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
295
* Another small change to the decoder is in how it handles unparseable
296
* streams. Before, when the decoder found an unparseable stream
297
* (reserved for when the decoder encounters a stream from a future
298
* encoder that it can't parse), it changed the state to
299
* \c FLAC__STREAM_DECODER_UNPARSEABLE_STREAM. Now the decoder instead
300
* drops sync and calls the error callback with a new error code
301
* \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM. This is
302
* more robust. If your error callback does not discriminate on the the
303
* error state, your code does not need to be changed.
305
* The encoder now has a new setting:
306
* FLAC__stream_encoder_set_apodization(). This is for setting the
307
* method used to window the data before LPC analysis. You only need to
308
* add a call to this function if the default is not suitable. There
309
* are also two new convenience functions that may be useful:
310
* FLAC__metadata_object_cuesheet_calculate_cddb_id() and
311
* FLAC__metadata_get_cuesheet().
313
* The \a bytes parameter to FLAC__StreamDecoderReadCallback,
314
* FLAC__StreamEncoderReadCallback, and FLAC__StreamEncoderWriteCallback
315
* is now \c size_t instead of \c unsigned.
318
/** \defgroup porting_1_1_3_to_1_1_4 Porting from FLAC 1.1.3 to 1.1.4
322
* This module describes porting from FLAC 1.1.3 to FLAC 1.1.4.
324
* There were no changes to any of the interfaces from 1.1.3 to 1.1.4.
325
* There was a slight change in the implementation of
326
* FLAC__stream_encoder_set_metadata(); the function now makes a copy
327
* of the \a metadata array of pointers so the client no longer needs
328
* to maintain it after the call. The objects themselves that are
329
* pointed to by the array are still not copied though and must be
330
* maintained until the call to FLAC__stream_encoder_finish().
147
333
/** \defgroup flac FLAC C API
added
removed
include/FLAC/all.h
