VisualC/flac/include/FLAC/all.h
changeset 556 2686e67b59fd
parent 555 b92bfb451700
child 557 a55168d8babe
equal deleted inserted replaced
555:b92bfb451700 556:2686e67b59fd
     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