VisualC/external/include/FLAC/all.h
changeset 556 2686e67b59fd
parent 532 b8e8ae4852b2
child 748 5515b36f95ed
child 937 3797c39725bf
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/VisualC/external/include/FLAC/all.h	Mon Jan 09 04:20:54 2012 -0500
     1.3 @@ -0,0 +1,370 @@
     1.4 +/* libFLAC - Free Lossless Audio Codec library
     1.5 + * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
     1.6 + *
     1.7 + * Redistribution and use in source and binary forms, with or without
     1.8 + * modification, are permitted provided that the following conditions
     1.9 + * are met:
    1.10 + *
    1.11 + * - Redistributions of source code must retain the above copyright
    1.12 + * notice, this list of conditions and the following disclaimer.
    1.13 + *
    1.14 + * - Redistributions in binary form must reproduce the above copyright
    1.15 + * notice, this list of conditions and the following disclaimer in the
    1.16 + * documentation and/or other materials provided with the distribution.
    1.17 + *
    1.18 + * - Neither the name of the Xiph.org Foundation nor the names of its
    1.19 + * contributors may be used to endorse or promote products derived from
    1.20 + * this software without specific prior written permission.
    1.21 + *
    1.22 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    1.23 + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    1.24 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    1.25 + * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    1.26 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    1.27 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    1.28 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    1.29 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    1.30 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    1.31 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    1.32 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    1.33 + */
    1.34 +
    1.35 +#ifndef FLAC__ALL_H
    1.36 +#define FLAC__ALL_H
    1.37 +
    1.38 +#include "export.h"
    1.39 +
    1.40 +#include "assert.h"
    1.41 +#include "callback.h"
    1.42 +#include "format.h"
    1.43 +#include "metadata.h"
    1.44 +#include "ordinals.h"
    1.45 +#include "stream_decoder.h"
    1.46 +#include "stream_encoder.h"
    1.47 +
    1.48 +/** \mainpage
    1.49 + *
    1.50 + * \section intro Introduction
    1.51 + *
    1.52 + * This is the documentation for the FLAC C and C++ APIs.  It is
    1.53 + * highly interconnected; this introduction should give you a top
    1.54 + * level idea of the structure and how to find the information you
    1.55 + * need.  As a prerequisite you should have at least a basic
    1.56 + * knowledge of the FLAC format, documented
    1.57 + * <A HREF="../format.html">here</A>.
    1.58 + *
    1.59 + * \section c_api FLAC C API
    1.60 + *
    1.61 + * The FLAC C API is the interface to libFLAC, a set of structures
    1.62 + * describing the components of FLAC streams, and functions for
    1.63 + * encoding and decoding streams, as well as manipulating FLAC
    1.64 + * metadata in files.  The public include files will be installed
    1.65 + * in your include area (for example /usr/include/FLAC/...).
    1.66 + *
    1.67 + * By writing a little code and linking against libFLAC, it is
    1.68 + * relatively easy to add FLAC support to another program.  The
    1.69 + * library is licensed under <A HREF="../license.html">Xiph's BSD license</A>.
    1.70 + * Complete source code of libFLAC as well as the command-line
    1.71 + * encoder and plugins is available and is a useful source of
    1.72 + * examples.
    1.73 + *
    1.74 + * Aside from encoders and decoders, libFLAC provides a powerful
    1.75 + * metadata interface for manipulating metadata in FLAC files.  It
    1.76 + * allows the user to add, delete, and modify FLAC metadata blocks
    1.77 + * and it can automatically take advantage of PADDING blocks to avoid
    1.78 + * rewriting the entire FLAC file when changing the size of the
    1.79 + * metadata.
    1.80 + *
    1.81 + * libFLAC usually only requires the standard C library and C math
    1.82 + * library. In particular, threading is not used so there is no
    1.83 + * dependency on a thread library. However, libFLAC does not use
    1.84 + * global variables and should be thread-safe.
    1.85 + *
    1.86 + * libFLAC also supports encoding to and decoding from Ogg FLAC.
    1.87 + * However the metadata editing interfaces currently have limited
    1.88 + * read-only support for Ogg FLAC files.
    1.89 + *
    1.90 + * \section cpp_api FLAC C++ API
    1.91 + *
    1.92 + * The FLAC C++ API is a set of classes that encapsulate the
    1.93 + * structures and functions in libFLAC.  They provide slightly more
    1.94 + * functionality with respect to metadata but are otherwise
    1.95 + * equivalent.  For the most part, they share the same usage as
    1.96 + * their counterparts in libFLAC, and the FLAC C API documentation
    1.97 + * can be used as a supplement.  The public include files
    1.98 + * for the C++ API will be installed in your include area (for
    1.99 + * example /usr/include/FLAC++/...).
   1.100 + *
   1.101 + * libFLAC++ is also licensed under
   1.102 + * <A HREF="../license.html">Xiph's BSD license</A>.
   1.103 + *
   1.104 + * \section getting_started Getting Started
   1.105 + *
   1.106 + * A good starting point for learning the API is to browse through
   1.107 + * the <A HREF="modules.html">modules</A>.  Modules are logical
   1.108 + * groupings of related functions or classes, which correspond roughly
   1.109 + * to header files or sections of header files.  Each module includes a
   1.110 + * detailed description of the general usage of its functions or
   1.111 + * classes.
   1.112 + *
   1.113 + * From there you can go on to look at the documentation of
   1.114 + * individual functions.  You can see different views of the individual
   1.115 + * functions through the links in top bar across this page.
   1.116 + *
   1.117 + * If you prefer a more hands-on approach, you can jump right to some
   1.118 + * <A HREF="../documentation_example_code.html">example code</A>.
   1.119 + *
   1.120 + * \section porting_guide Porting Guide
   1.121 + *
   1.122 + * Starting with FLAC 1.1.3 a \link porting Porting Guide \endlink
   1.123 + * has been introduced which gives detailed instructions on how to
   1.124 + * port your code to newer versions of FLAC.
   1.125 + *
   1.126 + * \section embedded_developers Embedded Developers
   1.127 + *
   1.128 + * libFLAC has grown larger over time as more functionality has been
   1.129 + * included, but much of it may be unnecessary for a particular embedded
   1.130 + * implementation.  Unused parts may be pruned by some simple editing of
   1.131 + * src/libFLAC/Makefile.am.  In general, the decoders, encoders, and
   1.132 + * metadata interface are all independent from each other.
   1.133 + *
   1.134 + * It is easiest to just describe the dependencies:
   1.135 + *
   1.136 + * - All modules depend on the \link flac_format Format \endlink module.
   1.137 + * - The decoders and encoders depend on the bitbuffer.
   1.138 + * - The decoder is independent of the encoder.  The encoder uses the
   1.139 + *   decoder because of the verify feature, but this can be removed if
   1.140 + *   not needed.
   1.141 + * - Parts of the metadata interface require the stream decoder (but not
   1.142 + *   the encoder).
   1.143 + * - Ogg support is selectable through the compile time macro
   1.144 + *   \c FLAC__HAS_OGG.
   1.145 + *
   1.146 + * For example, if your application only requires the stream decoder, no
   1.147 + * encoder, and no metadata interface, you can remove the stream encoder
   1.148 + * and the metadata interface, which will greatly reduce the size of the
   1.149 + * library.
   1.150 + *
   1.151 + * Also, there are several places in the libFLAC code with comments marked
   1.152 + * with "OPT:" where a #define can be changed to enable code that might be
   1.153 + * faster on a specific platform.  Experimenting with these can yield faster
   1.154 + * binaries.
   1.155 + */
   1.156 +
   1.157 +/** \defgroup porting Porting Guide for New Versions
   1.158 + *
   1.159 + * This module describes differences in the library interfaces from
   1.160 + * version to version.  It assists in the porting of code that uses
   1.161 + * the libraries to newer versions of FLAC.
   1.162 + *
   1.163 + * One simple facility for making porting easier that has been added
   1.164 + * in FLAC 1.1.3 is a set of \c #defines in \c export.h of each
   1.165 + * library's includes (e.g. \c include/FLAC/export.h).  The
   1.166 + * \c #defines mirror the libraries'
   1.167 + * <A HREF="http://www.gnu.org/software/libtool/manual.html#Libtool-versioning">libtool version numbers</A>,
   1.168 + * e.g. in libFLAC there are \c FLAC_API_VERSION_CURRENT,
   1.169 + * \c FLAC_API_VERSION_REVISION, and \c FLAC_API_VERSION_AGE.
   1.170 + * These can be used to support multiple versions of an API during the
   1.171 + * transition phase, e.g.
   1.172 + *
   1.173 + * \code
   1.174 + * #if !defined(FLAC_API_VERSION_CURRENT) || FLAC_API_VERSION_CURRENT <= 7
   1.175 + *   legacy code
   1.176 + * #else
   1.177 + *   new code
   1.178 + * #endif
   1.179 + * \endcode
   1.180 + *
   1.181 + * The the source will work for multiple versions and the legacy code can
   1.182 + * easily be removed when the transition is complete.
   1.183 + *
   1.184 + * Another available symbol is FLAC_API_SUPPORTS_OGG_FLAC (defined in
   1.185 + * include/FLAC/export.h), which can be used to determine whether or not
   1.186 + * the library has been compiled with support for Ogg FLAC.  This is
   1.187 + * simpler than trying to call an Ogg init function and catching the
   1.188 + * error.
   1.189 + */
   1.190 +
   1.191 +/** \defgroup porting_1_1_2_to_1_1_3 Porting from FLAC 1.1.2 to 1.1.3
   1.192 + *  \ingroup porting
   1.193 + *
   1.194 + *  \brief
   1.195 + *  This module describes porting from FLAC 1.1.2 to FLAC 1.1.3.
   1.196 + *
   1.197 + * The main change between the APIs in 1.1.2 and 1.1.3 is that they have
   1.198 + * been simplified.  First, libOggFLAC has been merged into libFLAC and
   1.199 + * libOggFLAC++ has been merged into libFLAC++.  Second, both the three
   1.200 + * decoding layers and three encoding layers have been merged into a
   1.201 + * single stream decoder and stream encoder.  That is, the functionality
   1.202 + * of FLAC__SeekableStreamDecoder and FLAC__FileDecoder has been merged
   1.203 + * into FLAC__StreamDecoder, and FLAC__SeekableStreamEncoder and
   1.204 + * FLAC__FileEncoder into FLAC__StreamEncoder.  Only the
   1.205 + * FLAC__StreamDecoder and FLAC__StreamEncoder remain.  What this means
   1.206 + * is there is now a single API that can be used to encode or decode
   1.207 + * streams to/from native FLAC or Ogg FLAC and the single API can work
   1.208 + * on both seekable and non-seekable streams.
   1.209 + *
   1.210 + * Instead of creating an encoder or decoder of a certain layer, now the
   1.211 + * client will always create a FLAC__StreamEncoder or
   1.212 + * FLAC__StreamDecoder.  The old layers are now differentiated by the
   1.213 + * initialization function.  For example, for the decoder,
   1.214 + * FLAC__stream_decoder_init() has been replaced by
   1.215 + * FLAC__stream_decoder_init_stream().  This init function takes
   1.216 + * callbacks for the I/O, and the seeking callbacks are optional.  This
   1.217 + * allows the client to use the same object for seekable and
   1.218 + * non-seekable streams.  For decoding a FLAC file directly, the client
   1.219 + * can use FLAC__stream_decoder_init_file() and pass just a filename
   1.220 + * and fewer callbacks; most of the other callbacks are supplied
   1.221 + * internally.  For situations where fopen()ing by filename is not
   1.222 + * possible (e.g. Unicode filenames on Windows) the client can instead
   1.223 + * open the file itself and supply the FILE* to
   1.224 + * FLAC__stream_decoder_init_FILE().  The init functions now returns a
   1.225 + * FLAC__StreamDecoderInitStatus instead of FLAC__StreamDecoderState.
   1.226 + * Since the callbacks and client data are now passed to the init
   1.227 + * function, the FLAC__stream_decoder_set_*_callback() functions and
   1.228 + * FLAC__stream_decoder_set_client_data() are no longer needed.  The
   1.229 + * rest of the calls to the decoder are the same as before.
   1.230 + *
   1.231 + * There are counterpart init functions for Ogg FLAC, e.g.
   1.232 + * FLAC__stream_decoder_init_ogg_stream().  All the rest of the calls
   1.233 + * and callbacks are the same as for native FLAC.
   1.234 + *
   1.235 + * As an example, in FLAC 1.1.2 a seekable stream decoder would have
   1.236 + * been set up like so:
   1.237 + *
   1.238 + * \code
   1.239 + * FLAC__SeekableStreamDecoder *decoder = FLAC__seekable_stream_decoder_new();
   1.240 + * if(decoder == NULL) do_something;
   1.241 + * FLAC__seekable_stream_decoder_set_md5_checking(decoder, true);
   1.242 + * [... other settings ...]
   1.243 + * FLAC__seekable_stream_decoder_set_read_callback(decoder, my_read_callback);
   1.244 + * FLAC__seekable_stream_decoder_set_seek_callback(decoder, my_seek_callback);
   1.245 + * FLAC__seekable_stream_decoder_set_tell_callback(decoder, my_tell_callback);
   1.246 + * FLAC__seekable_stream_decoder_set_length_callback(decoder, my_length_callback);
   1.247 + * FLAC__seekable_stream_decoder_set_eof_callback(decoder, my_eof_callback);
   1.248 + * FLAC__seekable_stream_decoder_set_write_callback(decoder, my_write_callback);
   1.249 + * FLAC__seekable_stream_decoder_set_metadata_callback(decoder, my_metadata_callback);
   1.250 + * FLAC__seekable_stream_decoder_set_error_callback(decoder, my_error_callback);
   1.251 + * FLAC__seekable_stream_decoder_set_client_data(decoder, my_client_data);
   1.252 + * if(FLAC__seekable_stream_decoder_init(decoder) != FLAC__SEEKABLE_STREAM_DECODER_OK) do_something;
   1.253 + * \endcode
   1.254 + *
   1.255 + * In FLAC 1.1.3 it is like this:
   1.256 + *
   1.257 + * \code
   1.258 + * FLAC__StreamDecoder *decoder = FLAC__stream_decoder_new();
   1.259 + * if(decoder == NULL) do_something;
   1.260 + * FLAC__stream_decoder_set_md5_checking(decoder, true);
   1.261 + * [... other settings ...]
   1.262 + * if(FLAC__stream_decoder_init_stream(
   1.263 + *   decoder,
   1.264 + *   my_read_callback,
   1.265 + *   my_seek_callback,      // or NULL
   1.266 + *   my_tell_callback,      // or NULL
   1.267 + *   my_length_callback,    // or NULL
   1.268 + *   my_eof_callback,       // or NULL
   1.269 + *   my_write_callback,
   1.270 + *   my_metadata_callback,  // or NULL
   1.271 + *   my_error_callback,
   1.272 + *   my_client_data
   1.273 + * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
   1.274 + * \endcode
   1.275 + *
   1.276 + * or you could do;
   1.277 + *
   1.278 + * \code
   1.279 + * [...]
   1.280 + * FILE *file = fopen("somefile.flac","rb");
   1.281 + * if(file == NULL) do_somthing;
   1.282 + * if(FLAC__stream_decoder_init_FILE(
   1.283 + *   decoder,
   1.284 + *   file,
   1.285 + *   my_write_callback,
   1.286 + *   my_metadata_callback,  // or NULL
   1.287 + *   my_error_callback,
   1.288 + *   my_client_data
   1.289 + * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
   1.290 + * \endcode
   1.291 + *
   1.292 + * or just:
   1.293 + *
   1.294 + * \code
   1.295 + * [...]
   1.296 + * if(FLAC__stream_decoder_init_file(
   1.297 + *   decoder,
   1.298 + *   "somefile.flac",
   1.299 + *   my_write_callback,
   1.300 + *   my_metadata_callback,  // or NULL
   1.301 + *   my_error_callback,
   1.302 + *   my_client_data
   1.303 + * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
   1.304 + * \endcode
   1.305 + *
   1.306 + * Another small change to the decoder is in how it handles unparseable
   1.307 + * streams.  Before, when the decoder found an unparseable stream
   1.308 + * (reserved for when the decoder encounters a stream from a future
   1.309 + * encoder that it can't parse), it changed the state to
   1.310 + * \c FLAC__STREAM_DECODER_UNPARSEABLE_STREAM.  Now the decoder instead
   1.311 + * drops sync and calls the error callback with a new error code
   1.312 + * \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM.  This is
   1.313 + * more robust.  If your error callback does not discriminate on the the
   1.314 + * error state, your code does not need to be changed.
   1.315 + *
   1.316 + * The encoder now has a new setting:
   1.317 + * FLAC__stream_encoder_set_apodization().  This is for setting the
   1.318 + * method used to window the data before LPC analysis.  You only need to
   1.319 + * add a call to this function if the default is not suitable.   There
   1.320 + * are also two new convenience functions that may be useful:
   1.321 + * FLAC__metadata_object_cuesheet_calculate_cddb_id() and
   1.322 + * FLAC__metadata_get_cuesheet().
   1.323 + *
   1.324 + * The \a bytes parameter to FLAC__StreamDecoderReadCallback,
   1.325 + * FLAC__StreamEncoderReadCallback, and FLAC__StreamEncoderWriteCallback
   1.326 + * is now \c size_t instead of \c unsigned.
   1.327 + */
   1.328 +
   1.329 +/** \defgroup porting_1_1_3_to_1_1_4 Porting from FLAC 1.1.3 to 1.1.4
   1.330 + *  \ingroup porting
   1.331 + *
   1.332 + *  \brief
   1.333 + *  This module describes porting from FLAC 1.1.3 to FLAC 1.1.4.
   1.334 + *
   1.335 + * There were no changes to any of the interfaces from 1.1.3 to 1.1.4.
   1.336 + * There was a slight change in the implementation of
   1.337 + * FLAC__stream_encoder_set_metadata(); the function now makes a copy
   1.338 + * of the \a metadata array of pointers so the client no longer needs
   1.339 + * to maintain it after the call.  The objects themselves that are
   1.340 + * pointed to by the array are still not copied though and must be
   1.341 + * maintained until the call to FLAC__stream_encoder_finish().
   1.342 + */
   1.343 +
   1.344 +/** \defgroup porting_1_1_4_to_1_2_0 Porting from FLAC 1.1.4 to 1.2.0
   1.345 + *  \ingroup porting
   1.346 + *
   1.347 + *  \brief
   1.348 + *  This module describes porting from FLAC 1.1.4 to FLAC 1.2.0.
   1.349 + *
   1.350 + * There were only very minor changes to the interfaces from 1.1.4 to 1.2.0.
   1.351 + * In libFLAC, \c FLAC__format_sample_rate_is_subset() was added.
   1.352 + * In libFLAC++, \c FLAC::Decoder::Stream::get_decode_position() was added.
   1.353 + *
   1.354 + * Finally, value of the constant \c FLAC__FRAME_HEADER_RESERVED_LEN
   1.355 + * has changed to reflect the conversion of one of the reserved bits
   1.356 + * into active use.  It used to be \c 2 and now is \c 1.  However the
   1.357 + * FLAC frame header length has not changed, so to skip the proper
   1.358 + * number of bits, use \c FLAC__FRAME_HEADER_RESERVED_LEN +
   1.359 + * \c FLAC__FRAME_HEADER_BLOCKING_STRATEGY_LEN
   1.360 + */
   1.361 +
   1.362 +/** \defgroup flac FLAC C API
   1.363 + *
   1.364 + * The FLAC C API is the interface to libFLAC, a set of structures
   1.365 + * describing the components of FLAC streams, and functions for
   1.366 + * encoding and decoding streams, as well as manipulating FLAC
   1.367 + * metadata in files.
   1.368 + *
   1.369 + * You should start with the format components as all other modules
   1.370 + * are dependent on it.
   1.371 + */
   1.372 +
   1.373 +#endif