home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / FLAC / all.h next >
Encoding:
C/C++ Source or Header  |  2008-09-10  |  15.6 KB  |  371 lines
  1. /* libFLAC - Free Lossless Audio Codec library
  2.  * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007  Josh Coalson
  3.  *
  4.  * Redistribution and use in source and binary forms, with or without
  5.  * modification, are permitted provided that the following conditions
  6.  * are met:
  7.  *
  8.  * - Redistributions of source code must retain the above copyright
  9.  * notice, this list of conditions and the following disclaimer.
  10.  *
  11.  * - Redistributions in binary form must reproduce the above copyright
  12.  * notice, this list of conditions and the following disclaimer in the
  13.  * documentation and/or other materials provided with the distribution.
  14.  *
  15.  * - Neither the name of the Xiph.org Foundation nor the names of its
  16.  * contributors may be used to endorse or promote products derived from
  17.  * this software without specific prior written permission.
  18.  *
  19.  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20.  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21.  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22.  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
  23.  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  24.  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  25.  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  26.  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  27.  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  28.  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  29.  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30.  */
  31.  
  32. #ifndef FLAC__ALL_H
  33. #define FLAC__ALL_H
  34.  
  35. #include "export.h"
  36.  
  37. #include "assert.h"
  38. #include "callback.h"
  39. #include "format.h"
  40. #include "metadata.h"
  41. #include "ordinals.h"
  42. #include "stream_decoder.h"
  43. #include "stream_encoder.h"
  44.  
  45. /** \mainpage
  46.  *
  47.  * \section intro Introduction
  48.  *
  49.  * This is the documentation for the FLAC C and C++ APIs.  It is
  50.  * highly interconnected; this introduction should give you a top
  51.  * level idea of the structure and how to find the information you
  52.  * need.  As a prerequisite you should have at least a basic
  53.  * knowledge of the FLAC format, documented
  54.  * <A HREF="../format.html">here</A>.
  55.  *
  56.  * \section c_api FLAC C API
  57.  *
  58.  * The FLAC C API is the interface to libFLAC, a set of structures
  59.  * describing the components of FLAC streams, and functions for
  60.  * encoding and decoding streams, as well as manipulating FLAC
  61.  * metadata in files.  The public include files will be installed
  62.  * in your include area (for example /usr/include/FLAC/...).
  63.  *
  64.  * By writing a little code and linking against libFLAC, it is
  65.  * relatively easy to add FLAC support to another program.  The
  66.  * library is licensed under <A HREF="../license.html">Xiph's BSD license</A>.
  67.  * Complete source code of libFLAC as well as the command-line
  68.  * encoder and plugins is available and is a useful source of
  69.  * examples.
  70.  *
  71.  * Aside from encoders and decoders, libFLAC provides a powerful
  72.  * metadata interface for manipulating metadata in FLAC files.  It
  73.  * allows the user to add, delete, and modify FLAC metadata blocks
  74.  * and it can automatically take advantage of PADDING blocks to avoid
  75.  * rewriting the entire FLAC file when changing the size of the
  76.  * metadata.
  77.  *
  78.  * libFLAC usually only requires the standard C library and C math
  79.  * library. In particular, threading is not used so there is no
  80.  * dependency on a thread library. However, libFLAC does not use
  81.  * global variables and should be thread-safe.
  82.  *
  83.  * libFLAC also supports encoding to and decoding from Ogg FLAC.
  84.  * However the metadata editing interfaces currently have limited
  85.  * read-only support for Ogg FLAC files.
  86.  *
  87.  * \section cpp_api FLAC C++ API
  88.  *
  89.  * The FLAC C++ API is a set of classes that encapsulate the
  90.  * structures and functions in libFLAC.  They provide slightly more
  91.  * functionality with respect to metadata but are otherwise
  92.  * equivalent.  For the most part, they share the same usage as
  93.  * their counterparts in libFLAC, and the FLAC C API documentation
  94.  * can be used as a supplement.  The public include files
  95.  * for the C++ API will be installed in your include area (for
  96.  * example /usr/include/FLAC++/...).
  97.  *
  98.  * libFLAC++ is also licensed under
  99.  * <A HREF="../license.html">Xiph's BSD license</A>.
  100.  *
  101.  * \section getting_started Getting Started
  102.  *
  103.  * A good starting point for learning the API is to browse through
  104.  * the <A HREF="modules.html">modules</A>.  Modules are logical
  105.  * groupings of related functions or classes, which correspond roughly
  106.  * to header files or sections of header files.  Each module includes a
  107.  * detailed description of the general usage of its functions or
  108.  * classes.
  109.  *
  110.  * From there you can go on to look at the documentation of
  111.  * individual functions.  You can see different views of the individual
  112.  * functions through the links in top bar across this page.
  113.  *
  114.  * If you prefer a more hands-on approach, you can jump right to some
  115.  * <A HREF="../documentation_example_code.html">example code</A>.
  116.  *
  117.  * \section porting_guide Porting Guide
  118.  *
  119.  * Starting with FLAC 1.1.3 a \link porting Porting Guide \endlink
  120.  * has been introduced which gives detailed instructions on how to
  121.  * port your code to newer versions of FLAC.
  122.  *
  123.  * \section embedded_developers Embedded Developers
  124.  *
  125.  * libFLAC has grown larger over time as more functionality has been
  126.  * included, but much of it may be unnecessary for a particular embedded
  127.  * implementation.  Unused parts may be pruned by some simple editing of
  128.  * src/libFLAC/Makefile.am.  In general, the decoders, encoders, and
  129.  * metadata interface are all independent from each other.
  130.  *
  131.  * It is easiest to just describe the dependencies:
  132.  *
  133.  * - All modules depend on the \link flac_format Format \endlink module.
  134.  * - The decoders and encoders depend on the bitbuffer.
  135.  * - The decoder is independent of the encoder.  The encoder uses the
  136.  *   decoder because of the verify feature, but this can be removed if
  137.  *   not needed.
  138.  * - Parts of the metadata interface require the stream decoder (but not
  139.  *   the encoder).
  140.  * - Ogg support is selectable through the compile time macro
  141.  *   \c FLAC__HAS_OGG.
  142.  *
  143.  * For example, if your application only requires the stream decoder, no
  144.  * encoder, and no metadata interface, you can remove the stream encoder
  145.  * and the metadata interface, which will greatly reduce the size of the
  146.  * library.
  147.  *
  148.  * Also, there are several places in the libFLAC code with comments marked
  149.  * with "OPT:" where a #define can be changed to enable code that might be
  150.  * faster on a specific platform.  Experimenting with these can yield faster
  151.  * binaries.
  152.  */
  153.  
  154. /** \defgroup porting Porting Guide for New Versions
  155.  *
  156.  * This module describes differences in the library interfaces from
  157.  * version to version.  It assists in the porting of code that uses
  158.  * the libraries to newer versions of FLAC.
  159.  *
  160.  * One simple facility for making porting easier that has been added
  161.  * in FLAC 1.1.3 is a set of \c #defines in \c export.h of each
  162.  * library's includes (e.g. \c include/FLAC/export.h).  The
  163.  * \c #defines mirror the libraries'
  164.  * <A HREF="http://www.gnu.org/software/libtool/manual.html#Libtool-versioning">libtool version numbers</A>,
  165.  * e.g. in libFLAC there are \c FLAC_API_VERSION_CURRENT,
  166.  * \c FLAC_API_VERSION_REVISION, and \c FLAC_API_VERSION_AGE.
  167.  * These can be used to support multiple versions of an API during the
  168.  * transition phase, e.g.
  169.  *
  170.  * \code
  171.  * #if !defined(FLAC_API_VERSION_CURRENT) || FLAC_API_VERSION_CURRENT <= 7
  172.  *   legacy code
  173.  * #else
  174.  *   new code
  175.  * #endif
  176.  * \endcode
  177.  *
  178.  * The the source will work for multiple versions and the legacy code can
  179.  * easily be removed when the transition is complete.
  180.  *
  181.  * Another available symbol is FLAC_API_SUPPORTS_OGG_FLAC (defined in
  182.  * include/FLAC/export.h), which can be used to determine whether or not
  183.  * the library has been compiled with support for Ogg FLAC.  This is
  184.  * simpler than trying to call an Ogg init function and catching the
  185.  * error.
  186.  */
  187.  
  188. /** \defgroup porting_1_1_2_to_1_1_3 Porting from FLAC 1.1.2 to 1.1.3
  189.  *  \ingroup porting
  190.  *
  191.  *  \brief
  192.  *  This module describes porting from FLAC 1.1.2 to FLAC 1.1.3.
  193.  *
  194.  * The main change between the APIs in 1.1.2 and 1.1.3 is that they have
  195.  * been simplified.  First, libOggFLAC has been merged into libFLAC and
  196.  * libOggFLAC++ has been merged into libFLAC++.  Second, both the three
  197.  * decoding layers and three encoding layers have been merged into a
  198.  * single stream decoder and stream encoder.  That is, the functionality
  199.  * of FLAC__SeekableStreamDecoder and FLAC__FileDecoder has been merged
  200.  * into FLAC__StreamDecoder, and FLAC__SeekableStreamEncoder and
  201.  * FLAC__FileEncoder into FLAC__StreamEncoder.  Only the
  202.  * FLAC__StreamDecoder and FLAC__StreamEncoder remain.  What this means
  203.  * is there is now a single API that can be used to encode or decode
  204.  * streams to/from native FLAC or Ogg FLAC and the single API can work
  205.  * on both seekable and non-seekable streams.
  206.  *
  207.  * Instead of creating an encoder or decoder of a certain layer, now the
  208.  * client will always create a FLAC__StreamEncoder or
  209.  * FLAC__StreamDecoder.  The old layers are now differentiated by the
  210.  * initialization function.  For example, for the decoder,
  211.  * FLAC__stream_decoder_init() has been replaced by
  212.  * FLAC__stream_decoder_init_stream().  This init function takes
  213.  * callbacks for the I/O, and the seeking callbacks are optional.  This
  214.  * allows the client to use the same object for seekable and
  215.  * non-seekable streams.  For decoding a FLAC file directly, the client
  216.  * can use FLAC__stream_decoder_init_file() and pass just a filename
  217.  * and fewer callbacks; most of the other callbacks are supplied
  218.  * internally.  For situations where fopen()ing by filename is not
  219.  * possible (e.g. Unicode filenames on Windows) the client can instead
  220.  * open the file itself and supply the FILE* to
  221.  * FLAC__stream_decoder_init_FILE().  The init functions now returns a
  222.  * FLAC__StreamDecoderInitStatus instead of FLAC__StreamDecoderState.
  223.  * Since the callbacks and client data are now passed to the init
  224.  * function, the FLAC__stream_decoder_set_*_callback() functions and
  225.  * FLAC__stream_decoder_set_client_data() are no longer needed.  The
  226.  * rest of the calls to the decoder are the same as before.
  227.  *
  228.  * There are counterpart init functions for Ogg FLAC, e.g.
  229.  * FLAC__stream_decoder_init_ogg_stream().  All the rest of the calls
  230.  * and callbacks are the same as for native FLAC.
  231.  *
  232.  * As an example, in FLAC 1.1.2 a seekable stream decoder would have
  233.  * been set up like so:
  234.  *
  235.  * \code
  236.  * FLAC__SeekableStreamDecoder *decoder = FLAC__seekable_stream_decoder_new();
  237.  * if(decoder == NULL) do_something;
  238.  * FLAC__seekable_stream_decoder_set_md5_checking(decoder, true);
  239.  * [... other settings ...]
  240.  * FLAC__seekable_stream_decoder_set_read_callback(decoder, my_read_callback);
  241.  * FLAC__seekable_stream_decoder_set_seek_callback(decoder, my_seek_callback);
  242.  * FLAC__seekable_stream_decoder_set_tell_callback(decoder, my_tell_callback);
  243.  * FLAC__seekable_stream_decoder_set_length_callback(decoder, my_length_callback);
  244.  * FLAC__seekable_stream_decoder_set_eof_callback(decoder, my_eof_callback);
  245.  * FLAC__seekable_stream_decoder_set_write_callback(decoder, my_write_callback);
  246.  * FLAC__seekable_stream_decoder_set_metadata_callback(decoder, my_metadata_callback);
  247.  * FLAC__seekable_stream_decoder_set_error_callback(decoder, my_error_callback);
  248.  * FLAC__seekable_stream_decoder_set_client_data(decoder, my_client_data);
  249.  * if(FLAC__seekable_stream_decoder_init(decoder) != FLAC__SEEKABLE_STREAM_DECODER_OK) do_something;
  250.  * \endcode
  251.  *
  252.  * In FLAC 1.1.3 it is like this:
  253.  *
  254.  * \code
  255.  * FLAC__StreamDecoder *decoder = FLAC__stream_decoder_new();
  256.  * if(decoder == NULL) do_something;
  257.  * FLAC__stream_decoder_set_md5_checking(decoder, true);
  258.  * [... other settings ...]
  259.  * if(FLAC__stream_decoder_init_stream(
  260.  *   decoder,
  261.  *   my_read_callback,
  262.  *   my_seek_callback,      // or NULL
  263.  *   my_tell_callback,      // or NULL
  264.  *   my_length_callback,    // or NULL
  265.  *   my_eof_callback,       // or NULL
  266.  *   my_write_callback,
  267.  *   my_metadata_callback,  // or NULL
  268.  *   my_error_callback,
  269.  *   my_client_data
  270.  * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
  271.  * \endcode
  272.  *
  273.  * or you could do;
  274.  *
  275.  * \code
  276.  * [...]
  277.  * FILE *file = fopen("somefile.flac","rb");
  278.  * if(file == NULL) do_somthing;
  279.  * if(FLAC__stream_decoder_init_FILE(
  280.  *   decoder,
  281.  *   file,
  282.  *   my_write_callback,
  283.  *   my_metadata_callback,  // or NULL
  284.  *   my_error_callback,
  285.  *   my_client_data
  286.  * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
  287.  * \endcode
  288.  *
  289.  * or just:
  290.  *
  291.  * \code
  292.  * [...]
  293.  * if(FLAC__stream_decoder_init_file(
  294.  *   decoder,
  295.  *   "somefile.flac",
  296.  *   my_write_callback,
  297.  *   my_metadata_callback,  // or NULL
  298.  *   my_error_callback,
  299.  *   my_client_data
  300.  * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something;
  301.  * \endcode
  302.  *
  303.  * Another small change to the decoder is in how it handles unparseable
  304.  * streams.  Before, when the decoder found an unparseable stream
  305.  * (reserved for when the decoder encounters a stream from a future
  306.  * encoder that it can't parse), it changed the state to
  307.  * \c FLAC__STREAM_DECODER_UNPARSEABLE_STREAM.  Now the decoder instead
  308.  * drops sync and calls the error callback with a new error code
  309.  * \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM.  This is
  310.  * more robust.  If your error callback does not discriminate on the the
  311.  * error state, your code does not need to be changed.
  312.  *
  313.  * The encoder now has a new setting:
  314.  * FLAC__stream_encoder_set_apodization().  This is for setting the
  315.  * method used to window the data before LPC analysis.  You only need to
  316.  * add a call to this function if the default is not suitable.   There
  317.  * are also two new convenience functions that may be useful:
  318.  * FLAC__metadata_object_cuesheet_calculate_cddb_id() and
  319.  * FLAC__metadata_get_cuesheet().
  320.  *
  321.  * The \a bytes parameter to FLAC__StreamDecoderReadCallback,
  322.  * FLAC__StreamEncoderReadCallback, and FLAC__StreamEncoderWriteCallback
  323.  * is now \c size_t instead of \c unsigned.
  324.  */
  325.  
  326. /** \defgroup porting_1_1_3_to_1_1_4 Porting from FLAC 1.1.3 to 1.1.4
  327.  *  \ingroup porting
  328.  *
  329.  *  \brief
  330.  *  This module describes porting from FLAC 1.1.3 to FLAC 1.1.4.
  331.  *
  332.  * There were no changes to any of the interfaces from 1.1.3 to 1.1.4.
  333.  * There was a slight change in the implementation of
  334.  * FLAC__stream_encoder_set_metadata(); the function now makes a copy
  335.  * of the \a metadata array of pointers so the client no longer needs
  336.  * to maintain it after the call.  The objects themselves that are
  337.  * pointed to by the array are still not copied though and must be
  338.  * maintained until the call to FLAC__stream_encoder_finish().
  339.  */
  340.  
  341. /** \defgroup porting_1_1_4_to_1_2_0 Porting from FLAC 1.1.4 to 1.2.0
  342.  *  \ingroup porting
  343.  *
  344.  *  \brief
  345.  *  This module describes porting from FLAC 1.1.4 to FLAC 1.2.0.
  346.  *
  347.  * There were only very minor changes to the interfaces from 1.1.4 to 1.2.0.
  348.  * In libFLAC, \c FLAC__format_sample_rate_is_subset() was added.
  349.  * In libFLAC++, \c FLAC::Decoder::Stream::get_decode_position() was added.
  350.  *
  351.  * Finally, value of the constant \c FLAC__FRAME_HEADER_RESERVED_LEN
  352.  * has changed to reflect the conversion of one of the reserved bits
  353.  * into active use.  It used to be \c 2 and now is \c 1.  However the
  354.  * FLAC frame header length has not changed, so to skip the proper
  355.  * number of bits, use \c FLAC__FRAME_HEADER_RESERVED_LEN +
  356.  * \c FLAC__FRAME_HEADER_BLOCKING_STRATEGY_LEN
  357.  */
  358.  
  359. /** \defgroup flac FLAC C API
  360.  *
  361.  * The FLAC C API is the interface to libFLAC, a set of structures
  362.  * describing the components of FLAC streams, and functions for
  363.  * encoding and decoding streams, as well as manipulating FLAC
  364.  * metadata in files.
  365.  *
  366.  * You should start with the format components as all other modules
  367.  * are dependent on it.
  368.  */
  369.  
  370. #endif
  371.