VisualC/flac/include/FLAC/all.h
changeset 556 2686e67b59fd
parent 555 b92bfb451700
child 557 a55168d8babe
     1.1 --- a/VisualC/flac/include/FLAC/all.h	Mon Jan 09 01:58:40 2012 -0500
     1.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.3 @@ -1,370 +0,0 @@
     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