include/FLAC/all.h

   1 /* libFLAC - Free Lossless Audio Codec library
   2  * Copyright (C) 2000,2001,2002,2003,2004,2005,2006 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 "file_decoder.h"
  40 #include "file_encoder.h"
  41 #include "format.h"
  42 #include "metadata.h"
  43 #include "ordinals.h"
  44 #include "seekable_stream_decoder.h"
  45 #include "seekable_stream_encoder.h"
  46 #include "stream_decoder.h"
  47 #include "stream_encoder.h"
  48
  49 /** \mainpage
  50  *
  51  * \section intro Introduction
  52  *
  53  * This is the documentation for the FLAC C and C++ APIs.  It is
  54  * highly interconnected; this introduction should give you a top
  55  * level idea of the structure and how to find the information you
  56  * need.  As a prerequisite you should have at least a basic
  57  * knowledge of the FLAC format, documented
  58  * <A HREF="../format.html">here</A>.
  59  *
  60  * \section c_api FLAC C API
  61  *
  62  * The FLAC C API is the interface to libFLAC, a set of structures
  63  * describing the components of FLAC streams, and functions for
  64  * encoding and decoding streams, as well as manipulating FLAC
  65  * metadata in files.  The public include files will be installed
  66  * in your include area as <include>/FLAC/...
  67  *
  68  * By writing a little code and linking against libFLAC, it is
  69  * relatively easy to add FLAC support to another program.  The
  70  * library is licensed under <A HREF="../license.html">Xiph's BSD license</A>.
  71  * Complete source code of libFLAC as well as the command-line
  72  * encoder and plugins is available and is a useful source of
  73  * examples.
  74  *
  75  * Aside from encoders and decoders, libFLAC provides a powerful
  76  * metadata interface for manipulating metadata in FLAC files.  It
  77  * allows the user to add, delete, and modify FLAC metadata blocks
  78  * and it can automatically take advantage of PADDING blocks to avoid
  79  * rewriting the entire FLAC file when changing the size of the
  80  * metadata.
  81  *
  82  * libFLAC usually only requires the standard C library and C math
  83  * library. In particular, threading is not used so there is no
  84  * dependency on a thread library. However, libFLAC does not use
  85  * global variables and should be thread-safe.
  86  *
  87  * There is also a new libOggFLAC library which wraps around libFLAC
  88  * to provide routines for encoding to and decoding from FLAC streams
  89  * inside an Ogg container.  The interfaces are very similar or identical
  90  * to their counterparts in libFLAC.  libOggFLAC is also licensed under
  91  * <A HREF="../license.html">Xiph's BSD license</A>.
  92  *
  93  * \section cpp_api FLAC C++ API
  94  *
  95  * The FLAC C++ API is a set of classes that encapsulate the
  96  * structures and functions in libFLAC.  They provide slightly more
  97  * functionality with respect to metadata but are otherwise
  98  * equivalent.  For the most part, they share the same usage as
  99  * their counterparts in libFLAC, and the FLAC C API documentation
 100  * can be used as a supplement.  The public include files
 101  * for the C++ API will be installed in your include area as
 102  * <include>/FLAC++/...
 103  *
 104  * There is also a new libOggFLAC++ library, which provides classes
 105  * for encoding to and decoding from FLAC streams in an Ogg container.
 106  * The classes are very similar to their counterparts in libFLAC++.
 107  *
 108  * Both libFLAC++ libOggFLAC++ are also licensed under
 109  * <A HREF="../license.html">Xiph's BSD license</A>.
 110  *
 111  * \section getting_started Getting Started
 112  *
 113  * A good starting point for learning the API is to browse through
 114  * the <A HREF="modules.html">modules</A>.  Modules are logical
 115  * groupings of related functions or classes, which correspond roughly
 116  * to header files or sections of header files.  Each module includes a
 117  * detailed description of the general usage of its functions or
 118  * classes.
 119  *
 120  * From there you can go on to look at the documentation of
 121  * individual functions.  You can see different views of the individual
 122  * functions through the links in top bar across this page.
 123  *
 124  * \section embedded_developers Embedded Developers
 125  *
 126  * libFLAC has grown larger over time as more functionality has been
 127  * included, but much of it may be unnecessary for a particular embedded
 128  * implementation.  Unused parts may be pruned by some simple editing of
 129  * src/libFLAC/Makefile.am.  In general, the decoders, encoders, and
 130  * metadata interface are all independent from each other.
 131  *
 132  * It is easiest to just describe the dependencies:
 133  *
 134  * - 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
 140  *
 141  * 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.
 145  */
 146
 147 /** \defgroup flac FLAC C API
 148  *
 149  * The FLAC C API is the interface to libFLAC, a set of structures
 150  * describing the components of FLAC streams, and functions for
 151  * encoding and decoding streams, as well as manipulating FLAC
 152  * metadata in files.
 153  *
 154  * You should start with the format components as all other modules
 155  * are dependent on it.
 156  */
 157
 158 #endif