Commit 8da98c89 authored by Josh Coalson's avatar Josh Coalson

merge libOggFLAC into libFLAC and libOggFLAC++ into FLAC++; documentation still needs work

parent 03dbb26a
......@@ -69,18 +69,6 @@ Package=<4>
Project_Dep_Name libFLAC++_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC_dynamic
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC++_dynamic
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC++_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libs_common_static
End Project Dependency
Begin Project Dependency
......@@ -102,12 +90,6 @@ Package=<4>
Project_Dep_Name test_libFLAC++
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libOggFLAC
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libOggFLAC++
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_seeking
End Project Dependency
Begin Project Dependency
......@@ -159,12 +141,6 @@ Package=<4>
Project_Dep_Name libFLAC++_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC++_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libs_common_static
End Project Dependency
Begin Project Dependency
......@@ -186,12 +162,6 @@ Package=<4>
Project_Dep_Name test_libFLAC++
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libOggFLAC
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libOggFLAC++
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_seeking
End Project Dependency
Begin Project Dependency
......@@ -225,9 +195,6 @@ Package=<4>
Project_Dep_Name libFLAC_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name utf8_static
End Project Dependency
}}}
......@@ -384,72 +351,6 @@ Package=<4>
###############################################################################
Project: "libOggFLAC_dynamic"=.\src\libOggFLAC\libOggFLAC_dynamic.dsp - Package Owner=<4>
Package=<5>
{{{
}}}
Package=<4>
{{{
Begin Project Dependency
Project_Dep_Name libFLAC_dynamic
End Project Dependency
}}}
###############################################################################
Project: "libOggFLAC_static"=.\src\libOggFLAC\libOggFLAC_static.dsp - Package Owner=<4>
Package=<5>
{{{
}}}
Package=<4>
{{{
Begin Project Dependency
Project_Dep_Name libFLAC_static
End Project Dependency
}}}
###############################################################################
Project: "libOggFLAC++_dynamic"=".\src\libOggFLAC++\libOggFLAC++_dynamic.dsp" - Package Owner=<4>
Package=<5>
{{{
}}}
Package=<4>
{{{
Begin Project Dependency
Project_Dep_Name libOggFLAC_dynamic
End Project Dependency
Begin Project Dependency
Project_Dep_Name libFLAC++_dynamic
End Project Dependency
}}}
###############################################################################
Project: "libOggFLAC++_static"=".\src\libOggFLAC++\libOggFLAC++_static.dsp" - Package Owner=<4>
Package=<5>
{{{
}}}
Package=<4>
{{{
Begin Project Dependency
Project_Dep_Name libOggFLAC_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name libFLAC++_static
End Project Dependency
}}}
###############################################################################
Project: "metaflac"=.\src\metaflac\metaflac.dsp - Package Owner=<4>
Package=<5>
......@@ -536,9 +437,6 @@ Package=<4>
Begin Project Dependency
Project_Dep_Name libFLAC_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC_static
End Project Dependency
}}}
###############################################################################
......@@ -579,42 +477,6 @@ Package=<4>
###############################################################################
Project: "test_libOggFLAC"=.\src\test_libOggFLAC\test_libOggFLAC.dsp - Package Owner=<4>
Package=<5>
{{{
}}}
Package=<4>
{{{
Begin Project Dependency
Project_Dep_Name libOggFLAC_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libs_common_static
End Project Dependency
}}}
###############################################################################
Project: "test_libOggFLAC++"=".\src\test_libOggFLAC++\test_libOggFLAC++.dsp" - Package Owner=<4>
Package=<5>
{{{
}}}
Package=<4>
{{{
Begin Project Dependency
Project_Dep_Name libOggFLAC++_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libs_common_static
End Project Dependency
}}}
###############################################################################
Project: "test_seeking"=.\src\test_seeking\test_seeking.dsp - Package Owner=<4>
Package=<5>
......
......@@ -30,7 +30,7 @@
topdir = .
.PHONY: all doc src libFLAC libFLAC++ libOggFLAC libOggFLAC++ share plugin_common plugin_xmms flac metaflac test_grabbag test_libFLAC test_libFLAC++ test_libOggFLAC test_libOggFLAC++ test_seeking test_streams
.PHONY: all doc src libFLAC libFLAC++ share plugin_common plugin_xmms flac metaflac test_grabbag test_libFLAC test_libFLAC++ test_seeking test_streams
all: doc src
DEFAULT_CONFIG = release
......@@ -57,16 +57,10 @@ libFLAC:
libFLAC++: libFLAC
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
libOggFLAC: libFLAC
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
libOggFLAC++: libFLAC
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
share: libFLAC
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
flac: libFLAC libOggFLAC share
flac: libFLAC share
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
metaflac: libFLAC share
......@@ -78,7 +72,7 @@ plugin_common: libFLAC
plugin_xmms: libFLAC plugin_common
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
test_seeking: libFLAC libOggFLAC
test_seeking: libFLAC
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
test_streams: libFLAC
......@@ -93,12 +87,6 @@ test_libFLAC: libFLAC
test_libFLAC++: libFLAC libFLAC++
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
test_libOggFLAC: libFLAC libOggFLAC
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
test_libOggFLAC++: libFLAC libOggFLAC libOggFLAC++
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
test: debug
(cd test ; $(MAKE) -f Makefile.lite debug)
......
......@@ -22,17 +22,15 @@ codec developed by Josh Coalson.
FLAC is comprised of
* `libFLAC', a library which implements reference encoders and
decoders, and a metadata interface
decoders for native FLAC and Ogg FLAC, and a metadata interface
* `libFLAC++', a C++ object wrapper library around libFLAC
* `libOggFLAC' and `libOggFLAC++', which provide encoders and
decoders for FLAC streams in an Ogg container
* `flac', a command-line program for encoding and decoding files
* `metaflac', a command-line program for viewing and editing FLAC
metadata
* player plugins for XMMS and Winamp
* user and API documentation
The libraries (libFLAC, libFLAC++, libOggFLAC, and libOggFLAC++) are
The libraries (libFLAC, libFLAC++) are
licensed under Xiph.org's BSD-like license (see COPYING.Xiph). All other
programs and plugins are licensed under the GNU General Public License
(see COPYING.GPL). The documentation is licensed under the GNU Free
......
......@@ -289,11 +289,6 @@ AC_CONFIG_FILES([ \
src/libFLAC/include/private/Makefile \
src/libFLAC/include/protected/Makefile \
src/libFLAC++/Makefile \
src/libOggFLAC/Makefile \
src/libOggFLAC/include/Makefile \
src/libOggFLAC/include/private/Makefile \
src/libOggFLAC/include/protected/Makefile \
src/libOggFLAC++/Makefile \
src/flac/Makefile \
src/metaflac/Makefile \
src/monkeys_audio_utilities/Makefile \
......@@ -318,15 +313,11 @@ AC_CONFIG_FILES([ \
src/test_libs_common/Makefile \
src/test_libFLAC/Makefile \
src/test_libFLAC++/Makefile \
src/test_libOggFLAC/Makefile \
src/test_libOggFLAC++/Makefile \
src/test_seeking/Makefile \
src/test_streams/Makefile \
include/Makefile \
include/FLAC/Makefile \
include/FLAC++/Makefile \
include/OggFLAC/Makefile \
include/OggFLAC++/Makefile \
include/share/Makefile \
include/share/grabbag/Makefile \
include/test_libs_common/Makefile \
......
......@@ -72,7 +72,7 @@
<li><span class="commandname">flac</span> now supports FLAC as input to the encoder (i.e. can re-encode FLAC to FLAC) and preserve all the metadata like tags, etc.</li>
<li>New <a href="format.html#def_PICTURE"><span class="code">PICTURE</span></a> metadata block for storing things like cover art, new <span class="argument"><a href="documentation.html#flac_options_picture">--picture</a></span> option to <span class="commandname">flac</span> and <span class="argument"><a href="documentation.html#metaflac_shorthand_import_picture">--import-picture</a></span> option to <span class="commandname">metaflac</span> for importing pictures, and metadata API <a href="api/group__flac__metadata__level0.html#ga3">additions</a> for searching for suitable pictures based on type, size and color constraints.</li>
<li>Support for new <tt>REPLAYGAIN_REFERENCE_LOUDNESS</tt> tag.</li>
<li>In the developer libraries, the interface has been simplfied by merging the three decoding layers into a single class; ditto for the encoders.</li>
<li>In the developer libraries, the interface has been simplfied by merging the three decoding layers into a single class; ditto for the encoders. Also, libOggFLAC has been merged into libFLAC and libOggFLAC++ has been merged into libFLAC++ so there is a single API supporting both native FLAC and Ogg FLAC.</li>
</ul>
</li>
<li>
......@@ -154,6 +154,8 @@
<li>
libraries:
<ul>
<li>Merged libOggFLAC into libFLAC; both formats are now supporte through the same API.</li>
<li>Merged libOggFLAC++ into libFLAC++; both formats are now supporte through the same API.</li>
<li>libFLAC: Improved compression with no impact on FLAC format or decoding time by adding a windowing stage before LPC analysis.</li>
<li>libFLAC: Fixed a bug in cuesheet parsing where it would return an error if the last line of the cuesheet did not end with a newline.</li>
<li>libFLAC: Fixed UTF-8 decoder to disallow non-shortest-form and surrogate sequences (see <a href="http://www.unicode.org/versions/corrigendum1.html">here</a>).</li>
......@@ -166,6 +168,8 @@
<li>
all libraries;
<ul>
<li>Merged libOggFLAC into libFLAC; both formats are now supporte through the same API.</li>
<li>Merged libOggFLAC++ into libFLAC++; both formats are now supporte through the same API.</li>
<li>Merged seekable stream decoder and file decoder into the stream decoder.</li>
<li>Merged seekable stream encoder and file encoder into the stream encoder.</li>
<li>Added #defines for the API version number to make porting easier; see <tt>include/lib*FLAC*/export.h</tt>.</li>
......@@ -196,19 +200,13 @@
<li>
libOggFLAC:
<ul>
<li><b>Added</b> OggFLAC__stream_encoder_set_apodization()</li>
<li><b>Added</b> OggFLAC__metadata_object_cuesheet_calculate_cddb_id()</li>
<li><b>Added</b> OggFLAC__metadata_get_cuesheet()</li>
<li><b>Added</b> OggFLAC__metadata_get_picture()</li>
<li>Merged into libFLAC.</li>
</ul>
</li>
<li>
libOggFLAC++:
<ul>
<li><b>Added</b> OggFLAC::Encoder::Stream::set_apodization()</li>
<li><b>Added</b> OggFLAC::Metadata::CueSheet::calculate_cddb_id()</li>
<li><b>Added</b> OggFLAC::Metadata::get_cuesheet()</li>
<li><b>Added</b> OggFLAC::Metadata::get_picture()</li>
<li>Merged into libFLAC++.</li>
</ul>
</li>
</ul>
......
......@@ -129,6 +129,7 @@ namespace FLAC {
inline operator bool() const { return is_valid(); }
//@}
virtual bool set_serial_number(long value); ///< See FLAC__stream_decoder_set_serial_number()
virtual bool set_md5_checking(bool value); ///< See FLAC__stream_decoder_set_md5_checking()
virtual bool set_metadata_respond(::FLAC__MetadataType type); ///< See FLAC__stream_decoder_set_metadata_respond()
virtual bool set_metadata_respond_application(const FLAC__byte id[4]); ///< See FLAC__stream_decoder_set_metadata_respond_application()
......@@ -147,13 +148,8 @@ namespace FLAC {
virtual unsigned get_sample_rate() const; ///< See FLAC__stream_decoder_get_sample_rate()
virtual unsigned get_blocksize() const; ///< See FLAC__stream_decoder_get_blocksize()
/** Initialize the instance; as with the C interface,
* init() should be called after construction and 'set'
* calls but before any of the 'process' calls.
*
* See FLAC__stream_decoder_init_stream().
*/
virtual ::FLAC__StreamDecoderInitStatus init();
virtual ::FLAC__StreamDecoderInitStatus init(); ///< Seek FLAC__stream_decoder_init_stream()
virtual ::FLAC__StreamDecoderInitStatus init_ogg(); ///< Seek FLAC__stream_decoder_init_ogg_stream()
virtual void finish(); ///< See FLAC__stream_decoder_finish()
......@@ -250,18 +246,12 @@ namespace FLAC {
File();
virtual ~File();
//@{
/** Initialize the instance; as with the C interface,
* init() should be called after construction and 'set'
* calls but before any of the 'process' calls.
*
* See FLAC__stream_decoder_init_FILE() and
* FLAC__stream_decoder_init_file().
*/
::FLAC__StreamDecoderInitStatus init(FILE *file);
::FLAC__StreamDecoderInitStatus init(const char *filename);
::FLAC__StreamDecoderInitStatus init(const std::string &filename);
//@}
virtual ::FLAC__StreamDecoderInitStatus init(FILE *file); ///< See FLAC__stream_decoder_init_FILE()
virtual ::FLAC__StreamDecoderInitStatus init(const char *filename); ///< See FLAC__stream_decoder_init_file()
virtual ::FLAC__StreamDecoderInitStatus init(const std::string &filename); ///< See FLAC__stream_decoder_init_file()
virtual ::FLAC__StreamDecoderInitStatus init_ogg(FILE *file); ///< See FLAC__stream_decoder_init_ogg_FILE()
virtual ::FLAC__StreamDecoderInitStatus init_ogg(const char *filename); ///< See FLAC__stream_decoder_init_ogg_file()
virtual ::FLAC__StreamDecoderInitStatus init_ogg(const std::string &filename); ///< See FLAC__stream_decoder_init_ogg_file()
protected:
// this is a dummy implementation to satisfy the pure virtual in Stream that is actually supplied internally by the C layer
virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes);
......
......@@ -56,7 +56,7 @@
* This module describes the encoder layers provided by libFLAC++.
*
* The libFLAC++ encoder classes are object wrappers around their
* counterparts in libFLAC. All decoding layers available in
* counterparts in libFLAC. All encoding layers available in
* libFLAC are also provided here. The interface is very similar;
* make sure to read the \link flac_encoder libFLAC encoder module \endlink.
*
......@@ -132,6 +132,7 @@ namespace FLAC {
inline operator bool() const { return is_valid(); }
//@}
virtual bool set_serial_number(long value); ///< See FLAC__stream_encoder_set_serial_number()
virtual bool set_verify(bool value); ///< See FLAC__stream_encoder_set_verify()
virtual bool set_streamable_subset(bool value); ///< See FLAC__stream_encoder_set_streamable_subset()
virtual bool set_do_mid_side_stereo(bool value); ///< See FLAC__stream_encoder_set_do_mid_side_stereo()
......@@ -175,19 +176,17 @@ namespace FLAC {
virtual unsigned get_rice_parameter_search_dist() const; ///< See FLAC__stream_encoder_get_rice_parameter_search_dist()
virtual FLAC__uint64 get_total_samples_estimate() const; ///< See FLAC__stream_encoder_get_total_samples_estimate()
/** Initialize the instance; as with the C interface,
* init() should be called after construction and 'set'
* calls but before any of the 'process' calls.
*
* See FLAC__stream_encoder_init_stream().
*/
virtual ::FLAC__StreamEncoderInitStatus init();
virtual ::FLAC__StreamEncoderInitStatus init(); ///< See FLAC__stream_encoder_init_stream()
virtual ::FLAC__StreamEncoderInitStatus init_ogg(); ///< See FLAC__stream_encoder_init_ogg_stream()
virtual void finish(); ///< See FLAC__stream_encoder_finish()
virtual bool process(const FLAC__int32 * const buffer[], unsigned samples); ///< See FLAC__stream_encoder_process()
virtual bool process_interleaved(const FLAC__int32 buffer[], unsigned samples); ///< See FLAC__stream_encoder_process_interleaved()
protected:
/// See FLAC__StreamEncoderReadCallback
virtual ::FLAC__StreamEncoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes);
/// See FLAC__StreamEncoderWriteCallback
virtual ::FLAC__StreamEncoderWriteStatus write_callback(const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame) = 0;
......@@ -209,6 +208,7 @@ namespace FLAC {
::FLAC__StreamEncoder *encoder_;
static ::FLAC__StreamEncoderReadStatus read_callback_(const ::FLAC__StreamEncoder *encoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
static ::FLAC__StreamEncoderWriteStatus write_callback_(const ::FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
static ::FLAC__StreamEncoderSeekStatus seek_callback_(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
static ::FLAC__StreamEncoderTellStatus tell_callback_(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
......@@ -256,18 +256,12 @@ namespace FLAC {
File();
virtual ~File();
//@{
/* Initialize the instance; as with the C interface,
* init() should be called after construction and 'set'
* calls but before any of the 'process' calls.
*
* See FLAC__stream_encoder_init_FILE() and
* FLAC__stream_encoder_init_file().
*/
::FLAC__StreamEncoderInitStatus init(FILE *file);
::FLAC__StreamEncoderInitStatus init(const char *filename);
::FLAC__StreamEncoderInitStatus init(const std::string &filename);
//@}
virtual ::FLAC__StreamEncoderInitStatus init(FILE *file); ///< See FLAC__stream_encoder_init_FILE()
virtual ::FLAC__StreamEncoderInitStatus init(const char *filename); ///< See FLAC__stream_encoder_init_file()
virtual ::FLAC__StreamEncoderInitStatus init(const std::string &filename); ///< See FLAC__stream_encoder_init_file()
virtual ::FLAC__StreamEncoderInitStatus init_ogg(FILE *file); ///< See FLAC__stream_encoder_init_ogg_FILE()
virtual ::FLAC__StreamEncoderInitStatus init_ogg(const char *filename); ///< See FLAC__stream_encoder_init_ogg_file()
virtual ::FLAC__StreamEncoderInitStatus init_ogg(const std::string &filename); ///< See FLAC__stream_encoder_init_ogg_file()
protected:
/// See FLAC__StreamEncoderProgressCallback
virtual void progress_callback(FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate);
......@@ -282,8 +276,6 @@ namespace FLAC {
void operator=(const Stream &);
};
/* \} */
}
}
......
......@@ -52,4 +52,7 @@
#define FLAC_API_VERSION_REVISION 0
#define FLAC_API_VERSION_AGE 0
/** \c 1 if the library has been compiled with support for Ogg FLAC, else \c 0. */
extern int FLAC_API_SUPPORTS_OGG_FLAC;
#endif
......@@ -208,6 +208,9 @@ typedef enum {
FLAC__STREAM_DECODER_END_OF_STREAM,
/**< The decoder has reached the end of the stream. */
FLAC__STREAM_DECODER_OGG_ERROR,
/**< An error occurred in the underlying Ogg layer. */
FLAC__STREAM_DECODER_SEEK_ERROR,
/**< An error occurred while seeking. The decoder must be flushed
* with FLAC__stream_decoder_flush() or reset with
......@@ -245,6 +248,11 @@ typedef enum {
FLAC__STREAM_DECODER_INIT_STATUS_OK = 0,
/**< Initialization was successful. */
FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER,
/**< The library was not compiled with support for the given container
* format.
*/
FLAC__STREAM_DECODER_INIT_STATUS_INVALID_CALLBACKS,
/**< A required callback was not supplied. */
......@@ -659,6 +667,21 @@ FLAC_API void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
*
***********************************************************************/
/** Set the serial number for the Ogg stream.
* The default behavior is to use the serial number of the first Ogg
* page. Setting a serial number here will explicitly specify which
* stream is to be decoded.
*
* \default \c use serial number of first page
* \param decoder A decoder instance to set.
* \param serial_number See above.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__stream_decoder_set_serial_number(FLAC__StreamDecoder *decoder, long serial_number);
/** Set the "MD5 signature checking" flag. If \c true, the decoder will
* compute the MD5 signature of the unencoded audio data while decoding
* and compare it to the signature from the STREAMINFO block, if it
......@@ -875,24 +898,28 @@ FLAC_API unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *
* there may still be undecoded bytes in the decoder's read FIFO.
* The returned position is correct even after a seek.
*
* \warning This function currently only works for native FLAC,
* not Ogg FLAC streams.
*
* \param decoder A decoder instance to query.
* \param position Address at which to return the desired position.
* \assert
* \code decoder != NULL \endcode
* \code position != NULL \endcode
* \retval FLAC__bool
* \c true if successful, \c false if there was an error from
* the 'tell' callback or it returned
* \c true if successful, \c false if the stream is not native FLAC,
* or there was an error from the 'tell' callback or it returned
* \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED.
*/
FLAC_API FLAC__bool FLAC__stream_decoder_get_decode_position(const FLAC__StreamDecoder *decoder, FLAC__uint64 *position);
/** Initialize the decoder instance.
/** Initialize the decoder instance to decode native FLAC streams.
*
* This flavor of initialization sets up the decoder to decode from a stream.
* I/O is performed via callbacks to the client. For decoding from a plain file
* via filename or open FILE*, FLAC__stream_decoder_init_file() and
* FLAC__stream_decoder_init_FILE() provide a simpler interface.
* This flavor of initialization sets up the decoder to decode from a
* native FLAC stream. I/O is performed via callbacks to the client.
* For decoding from a plain file via filename or open FILE*,
* FLAC__stream_decoder_init_file() and FLAC__stream_decoder_init_FILE()
* provide a simpler interface.
*
* This function should be called after FLAC__stream_decoder_new() and
* FLAC__stream_decoder_set_*() but before any of the
......@@ -963,10 +990,91 @@ FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_stream(
void *client_data
);
/** Initialize the decoder instance.
/** Initialize the decoder instance to decode Ogg FLAC streams.
*
* This flavor of initialization sets up the decoder to decode from a plain
* file. For non-stdio streams, you must use
* This flavor of initialization sets up the decoder to decode from a
* FLAC stream in an Ogg container. I/O is performed via callbacks to the
* client. For decoding from a plain file via filename or open FILE*,
* FLAC__stream_decoder_init_ogg_file() and FLAC__stream_decoder_init_ogg_FILE()
* provide a simpler interface.
*
* This function should be called after FLAC__stream_decoder_new() and
* FLAC__stream_decoder_set_*() but before any of the
* FLAC__stream_decoder_process_*() functions. Will set and return the
* decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
* if initialization succeeded.
*
* \note Support for Ogg FLAC in the library is optional. If this
* library has been built without support for Ogg FLAC, this function
* will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
*
* \param decoder An uninitialized decoder instance.
* \param read_callback See FLAC__StreamDecoderReadCallback. This
* pointer must not be \c NULL.
* \param seek_callback See FLAC__StreamDecoderSeekCallback. This
* pointer may be \c NULL if seeking is not
* supported. If \a seek_callback is not \c NULL then a
* \a tell_callback, \a length_callback, and \a eof_callback must also be supplied.
* Alternatively, a dummy seek callback that just
* returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
* may also be supplied, all though this is slightly
* less efficient for the decoder.
* \param tell_callback See FLAC__StreamDecoderTellCallback. This
* pointer may be \c NULL if not supported by the client. If
* \a seek_callback is not \c NULL then a
* \a tell_callback must also be supplied.
* Alternatively, a dummy tell callback that just
* returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
* may also be supplied, all though this is slightly
* less efficient for the decoder.
* \param length_callback See FLAC__StreamDecoderLengthCallback. This
* pointer may be \c NULL if not supported by the client. If
* \a seek_callback is not \c NULL then a
* \a length_callback must also be supplied.
* Alternatively, a dummy length callback that just
* returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
* may also be supplied, all though this is slightly
* less efficient for the decoder.
* \param eof_callback See FLAC__StreamDecoderEofCallback. This
* pointer may be \c NULL if not supported by the client. If
* \a seek_callback is not \c NULL then a
* \a eof_callback must also be supplied.
* Alternatively, a dummy length callback that just
* returns \c false
* may also be supplied, all though this is slightly
* less efficient for the decoder.
* \param write_callback See FLAC__StreamDecoderWriteCallback. This
* pointer must not be \c NULL.
* \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
* pointer may be \c NULL if the callback is not
* desired.
* \param error_callback See FLAC__StreamDecoderErrorCallback. This
* pointer must not be \c NULL.
* \param client_data This value will be supplied to callbacks in their