include/FLAC/all.h

   1 /* libFLAC - Free Lossless Audio Codec library
   2  * Copyright (C) 2000,2001,2002  Josh Coalson
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA  02111-1307, USA.
  18  */
  19
  20 #ifndef FLAC__ALL_H
  21 #define FLAC__ALL_H
  22
  23 #include "export.h"
  24
  25 #include "assert.h"
  26 #include "file_decoder.h"
  27 #include "file_encoder.h"
  28 #include "format.h"
  29 #include "metadata.h"
  30 #include "ordinals.h"
  31 #include "seekable_stream_decoder.h"
  32 #include "seekable_stream_encoder.h"
  33 #include "stream_decoder.h"
  34 #include "stream_encoder.h"
  35
  36 /** \mainpage
  37  *
  38  * \section intro Introduction
  39  *
  40  * This is the documentation for the FLAC C and C++ APIs.  It is
  41  * highly interconnected; this introduction should give you a top
  42  * level idea of the structure and how to find the information you
  43  * need.  As a prerequisite you should have at least a basic
  44  * knowledge of the FLAC format, documented
  45  * <A HREF="../format.html">here</A>.
  46  *
  47  * \section c_api FLAC C API
  48  *
  49  * The FLAC C API is the interface to libFLAC, a set of structures
  50  * describing the components of FLAC streams, and functions for
  51  * encoding and decoding streams, as well as manipulating FLAC
  52  * metadata in files.  The public include files will be installed
  53  * in your include area as <include>/FLAC/...
  54  *
  55  * By writing a little code and linking against libFLAC, it is
  56  * relatively easy to add FLAC support to another program.  The
  57  * library is licensed under the
  58  * <A HREF="http://www.gnu.org/copyleft/lesser.html">LGPL</A>.
  59  * Complete source code of libFLAC as well as the command-line
  60  * encoder and plugins is available and is a useful source of
  61  * examples.
  62  *
  63  * Aside from encoders and decoders, libFLAC provides a powerful
  64  * metadata interface for manipulating metadata in FLAC files.  It
  65  * allows the user to add, delete, and modify FLAC metadata blocks
  66  * and it can automatically take advantage of PADDING blocks to avoid
  67  * rewriting the entire FLAC file when changing the size of the
  68  * metadata.
  69  *
  70  * libFLAC usually only requires the standard C library and C math
  71  * library. In particular, threading is not used so there is no
  72  * dependency on a thread library. However, libFLAC does not use
  73  * global variables and should be thread-safe.
  74  *
  75  * There is also a new libOggFLAC library which wraps around libFLAC
  76  * to provide routines for encoding to and decoding from FLAC streams
  77  * inside an Ogg container.  The interfaces are very similar or identical
  78  * to their counterparts in libFLAC.  libOggFLAC is also licensed under
  79  * the LGPL.
  80  *
  81  * \section cpp_api FLAC C API
  82  *
  83  * The FLAC C++ API is a set of classes that encapsulate the
  84  * structures and functions in libFLAC.  They provide slightly more
  85  * functionality with respect to metadata but are otherwise
  86  * equivalent.  For the most part, they share the same usage as
  87  * their counterparts in libFLAC, and the FLAC C API documentation
  88  * can be used as a supplement.  The public include files
  89  * for the C++ API will be installed in your include area as
  90  * <include>/FLAC++/...
  91  *
  92  * There is also a new libOggFLAC++ library, which provides classes
  93  * for encoding to and decoding from FLAC streams in an Ogg container.
  94  * The classes are very similar to their counterparts in libFLAC++.
  95  *
  96  * Both libFLAC++ libOggFLAC++ are also licensed under the
  97  * <A HREF="http://www.gnu.org/copyleft/lesser.html">LGPL</A>.
  98  *
  99  * \section getting_started Getting Started
 100  *
 101  * A good starting point for learning the API is to browse through
 102  * the <A HREF="modules.html">modules</A>.  Modules are logical
 103  * groupings of related functions or classes, which correspond roughly
 104  * to header files or sections of header files.  Each module includes a
 105  * detailed description of the general usage of its functions or
 106  * classes.
 107  *
 108  * From there you can go on to look at the documentation of
 109  * individual functions.  You can see different views of the individual
 110  * functions through the links in top bar across this page.
 111  *
 112  * \section embedded_developers Embedded Developers
 113  *
 114  * libFLAC has grown larger over time as more functionality has been
 115  * included, but much of it may be unnecessary for a particular embedded
 116  * implementation.  Unused parts may be pruned by some simple editing of
 117  * src/libFLAC/Makefile.am.  In general, the decoders, encoders, and
 118  * metadata interface are all independent from each other.
 119  *
 120  * It is easiest to just describe the dependencies:
 121  *
 122  * - All modules depend on the \link flac_format Format \endlink module.
 123  * - The decoders and encoders are independent of each other.
 124  * - The metadata interface requires the file decoder.
 125  * - The decoder and encoder layers depend on the layers below them, but
 126  *   not above them; e.g. the seekable stream decoder depends on the stream
 127  *   decoder but not the file decoder
 128  *
 129  * For example, if your application only requires the stream decoder, no
 130  * encoders, and no metadata interface, you can remove the seekable stream
 131  * decoder, file decoder, all encoders, and the metadata interface, which
 132  * will greatly reduce the size of the library.
 133  */
 134
 135 /** \defgroup flac FLAC C API
 136  *
 137  * The FLAC C API is the interface to libFLAC, a set of structures
 138  * describing the components of FLAC streams, and functions for
 139  * encoding and decoding streams, as well as manipulating FLAC
 140  * metadata in files.
 141  *
 142  * You should start with the format components as all other modules
 143  * are dependent on it.
 144  */
 145
 146 #endif