From ac2932b47fcf81987889a2289b9bcf02318fa2bd Mon Sep 17 00:00:00 2001 From: Josh Coalson Date: Tue, 6 Aug 2002 05:38:55 +0000 Subject: [PATCH] did more work but still not finished --- include/OggFLAC/file_decoder.h | 235 +++++------ include/OggFLAC/file_encoder.h | 284 ++++++------- include/OggFLAC/seekable_stream_decoder.h | 361 +++++------------ include/OggFLAC/seekable_stream_encoder.h | 250 ++++++------ include/OggFLAC/stream_decoder.h | 364 +++-------------- include/OggFLAC/stream_encoder.h | 465 ++++++++++++++++++---- 6 files changed, 887 insertions(+), 1072 deletions(-) diff --git a/include/OggFLAC/file_decoder.h b/include/OggFLAC/file_decoder.h index 147cfb43..c5cadea3 100644 --- a/include/OggFLAC/file_decoder.h +++ b/include/OggFLAC/file_decoder.h @@ -44,114 +44,57 @@ extern "C" { * This module contains the functions which implement the file * decoder. * - * The basic usage of this decoder is as follows: - * - The program creates an instance of a decoder using - * OggFLAC__file_decoder_new(). - * - The program overrides the default settings and sets callbacks for - * writing, error reporting, and metadata reporting using - * OggFLAC__file_decoder_set_*() functions. - * - The program initializes the instance to validate the settings and - * prepare for decoding using OggFLAC__file_decoder_init(). - * - The program calls the OggFLAC__file_decoder_process_*() functions - * to decode data, which subsequently calls the callbacks. - * - The program finishes the decoding with OggFLAC__file_decoder_finish(), - * which flushes the input and output and resets the decoder to the - * uninitialized state. - * - The instance may be used again or deleted with - * OggFLAC__file_decoder_delete(). - * - * The file decoder is a trivial wrapper around the - * \link oggflac_seekable_stream_decoder seekable stream decoder \endlink - * meant to simplfy the process of decoding from a standard file. The - * file decoder supplies all but the Write/Metadata/Error callbacks. - * The user needs only to provide the path to the file and the file - * decoder handles the rest. - * - * Like the seekable stream decoder, seeking is exposed through the - * OggFLAC__file_decoder_seek_absolute() method. At any point after the file - * decoder has been initialized, the user can call this function to seek to - * an exact sample within the file. Subsequently, the first time the write - * callback is called it will be passed a (possibly partial) block starting - * at that sample. - * - * The file decoder also inherits MD5 signature checking from the seekable - * stream decoder. If this is turned on before initialization, - * OggFLAC__file_decoder_finish() will report when the decoded MD5 signature - * does not match the one stored in the STREAMINFO block. MD5 checking is - * automatically turned off if there is no signature in the STREAMINFO - * block or when a seek is attempted. - * - * Make sure to read the detailed descriptions of the - * \link oggflac_seekable_stream_decoder seekable stream decoder module \endlink - * and \link oggflac_stream_decoder stream decoder module \endlink - * since the file decoder inherits much of its behavior from them. - * - * \note - * The "set" functions may only be called when the decoder is in the - * state OggFLAC__FILE_DECODER_UNINITIALIZED, i.e. after - * OggFLAC__file_decoder_new() or OggFLAC__file_decoder_finish(), but - * before OggFLAC__file_decoder_init(). If this is the case they will - * return \c true, otherwise \c false. - * - * \note - * OggFLAC__file_decoder_finish() resets all settings to the constructor - * defaults, including the callbacks. + * The interface here is identical to FLAC's file decoder. See the + * defaults, including the callbacks. See the \link flac_file_decoder + * FLAC file decoder module \endlink for full documentation. * * \{ */ -/** State values for a OggFLAC__FileDecoder +/** State values for an OggFLAC__FileDecoder * * The decoder's state can be obtained by calling OggFLAC__file_decoder_get_state(). */ typedef enum { - OggFLAC__FILE_DECODER_OK = 0, + OggFLAC__FILE_DECODER_OK = 0, /**< The decoder is in the normal OK state. */ - OggFLAC__FILE_DECODER_END_OF_FILE, - /**< The decoder has reached the end of the file. */ - - OggFLAC__FILE_DECODER_ERROR_OPENING_FILE, - /**< An error occurred opening the input file. */ - - OggFLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR, - /**< An error occurred allocating memory. */ - - OggFLAC__FILE_DECODER_SEEK_ERROR, - /**< An error occurred while seeking. */ - - OggFLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR, - /**< An error occurred in the underlying seekable stream decoder. */ - - OggFLAC__FILE_DECODER_ALREADY_INITIALIZED, - /**< OggFLAC__file_decoder_init() was called when the decoder was already - * initialized, usually because OggFLAC__file_decoder_finish() was not - * called. + OggFLAC__FILE_DECODER_FLAC_FILE_DECODER_ERROR, + /**< An error occurred in the underlying FLAC file decoder; + * check OggFLAC__file_decoder_get_FLAC_file_decoder_state(). */ - OggFLAC__FILE_DECODER_INVALID_CALLBACK, - /**< OggFLAC__file_decoder_init() was called without all callbacks - * being set. + OggFLAC__FILE_DECODER_INVALID_CALLBACK, + /**< The decoder was initialized before setting all the required callbacks. */ + + OggFLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR, + /**< Memory allocation failed. */ + + OggFLAC__FILE_DECODER_ALREADY_INITIALIZED, + /**< OggFLAC__file_decoder_init() was called when the decoder was + * already initialized, usually because + * OggFLAC__file_decoder_finish() was not called. */ - OggFLAC__FILE_DECODER_UNINITIALIZED + OggFLAC__FILE_DECODER_UNINITIALIZED /**< The decoder is in the uninitialized state. */ } OggFLAC__FileDecoderState; -/** Maps a OggFLAC__FileDecoderState to a C string. +/** Maps an OggFLAC__FileDecoderState to a C string. * - * Using a OggFLAC__FileDecoderState as the index to this array + * Using an OggFLAC__FileDecoderState as the index to this array * will give the string equivalent. The contents should not be modified. */ +/* @@@@ double-check mapping */ extern const char * const OggFLAC__FileDecoderStateString[]; /*********************************************************************** * - * class OggFLAC__FileDecoder : public OggFLAC__StreamDecoder + * class OggFLAC__FileDecoder : public FLAC__FileDecoder * ***********************************************************************/ @@ -167,9 +110,9 @@ typedef struct { } OggFLAC__FileDecoder; /* @@@@ document */ -typedef OggFLAC__StreamDecoderWriteStatus (*OggFLAC__FileDecoderWriteCallback)(const OggFLAC__FileDecoder *decoder, const OggFLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data); -typedef void (*OggFLAC__FileDecoderMetadataCallback)(const OggFLAC__FileDecoder *decoder, const OggFLAC__StreamMetadata *metadata, void *client_data); -typedef void (*OggFLAC__FileDecoderErrorCallback)(const OggFLAC__FileDecoder *decoder, OggFLAC__StreamDecoderErrorStatus status, void *client_data); +typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__FileDecoderWriteCallback)(const OggFLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data); +typedef void (*OggFLAC__FileDecoderMetadataCallback)(const OggFLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data); +typedef void (*OggFLAC__FileDecoderErrorCallback)(const OggFLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data); /*********************************************************************** @@ -203,8 +146,8 @@ void OggFLAC__file_decoder_delete(OggFLAC__FileDecoder *decoder); ***********************************************************************/ /** Set the "MD5 signature checking" flag. - * This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_set_md5_checking(). + * This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_set_md5_checking(). * * \default \c false * \param decoder A decoder instance to set. @@ -217,6 +160,8 @@ void OggFLAC__file_decoder_delete(OggFLAC__FileDecoder *decoder); FLAC__bool OggFLAC__file_decoder_set_md5_checking(OggFLAC__FileDecoder *decoder, FLAC__bool value); /** Set the input file name to decode. + * This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_set_filename(). * * \default \c "-" * \param decoder A decoder instance to set. @@ -231,8 +176,8 @@ FLAC__bool OggFLAC__file_decoder_set_md5_checking(OggFLAC__FileDecoder *decoder, FLAC__bool OggFLAC__file_decoder_set_filename(OggFLAC__FileDecoder *decoder, const char *value); /** Set the write callback. - * This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_set_write_callback(). + * This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_set_write_callback(). * * \note * The callback is mandatory and must be set before initialization. @@ -249,8 +194,8 @@ FLAC__bool OggFLAC__file_decoder_set_filename(OggFLAC__FileDecoder *decoder, con FLAC__bool OggFLAC__file_decoder_set_write_callback(OggFLAC__FileDecoder *decoder, OggFLAC__FileDecoderWriteCallback value); /** Set the metadata callback. - * This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_set_metadata_callback(). + * This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_set_metadata_callback(). * * \note * The callback is mandatory and must be set before initialization. @@ -267,8 +212,8 @@ FLAC__bool OggFLAC__file_decoder_set_write_callback(OggFLAC__FileDecoder *decode FLAC__bool OggFLAC__file_decoder_set_metadata_callback(OggFLAC__FileDecoder *decoder, OggFLAC__FileDecoderMetadataCallback value); /** Set the error callback. - * This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_set_error_callback(). + * This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_set_error_callback(). * * \note * The callback is mandatory and must be set before initialization. @@ -298,8 +243,8 @@ FLAC__bool OggFLAC__file_decoder_set_error_callback(OggFLAC__FileDecoder *decode */ FLAC__bool OggFLAC__file_decoder_set_client_data(OggFLAC__FileDecoder *decoder, void *value); -/** This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_set_metadata_respond(). +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_set_metadata_respond(). * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -313,8 +258,8 @@ FLAC__bool OggFLAC__file_decoder_set_client_data(OggFLAC__FileDecoder *decoder, */ FLAC__bool OggFLAC__file_decoder_set_metadata_respond(OggFLAC__FileDecoder *decoder, OggFLAC__MetadataType type); -/** This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_set_metadata_respond_application(). +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_set_metadata_respond_application(). * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -328,8 +273,8 @@ FLAC__bool OggFLAC__file_decoder_set_metadata_respond(OggFLAC__FileDecoder *deco */ FLAC__bool OggFLAC__file_decoder_set_metadata_respond_application(OggFLAC__FileDecoder *decoder, const FLAC__byte id[4]); -/** This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_set_metadata_respond_all(). +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_set_metadata_respond_all(). * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -341,8 +286,8 @@ FLAC__bool OggFLAC__file_decoder_set_metadata_respond_application(OggFLAC__FileD */ FLAC__bool OggFLAC__file_decoder_set_metadata_respond_all(OggFLAC__FileDecoder *decoder); -/** This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_set_metadata_ignore(). +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_set_metadata_ignore(). * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -356,8 +301,8 @@ FLAC__bool OggFLAC__file_decoder_set_metadata_respond_all(OggFLAC__FileDecoder * */ FLAC__bool OggFLAC__file_decoder_set_metadata_ignore(OggFLAC__FileDecoder *decoder, OggFLAC__MetadataType type); -/** This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_set_metadata_ignore_application(). +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_set_metadata_ignore_application(). * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -371,8 +316,8 @@ FLAC__bool OggFLAC__file_decoder_set_metadata_ignore(OggFLAC__FileDecoder *decod */ FLAC__bool OggFLAC__file_decoder_set_metadata_ignore_application(OggFLAC__FileDecoder *decoder, const FLAC__byte id[4]); -/** This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_set_metadata_ignore_all(). +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_set_metadata_ignore_all(). * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -394,34 +339,47 @@ FLAC__bool OggFLAC__file_decoder_set_metadata_ignore_all(OggFLAC__FileDecoder *d */ OggFLAC__FileDecoderState OggFLAC__file_decoder_get_state(const OggFLAC__FileDecoder *decoder); -/** Get the state of the underlying seekable stream decoder. +/** Get the state of the underlying FLAC file decoder. * Useful when the file decoder state is - * \c OggFLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR. + * \c OggFLAC__FILE_DECODER_FLAC_FILE_DECODER_ERROR. * * \param decoder An decoder instance to query. * \assert * \code decoder != NULL \endcode - * \retval OggFLAC__SeekableStreamDecoderState - * The seekable stream decoder state. + * \retval FLAC__FileDecoderState + * The FLAC file decoder state. */ -OggFLAC__SeekableStreamDecoderState OggFLAC__file_decoder_get_seekable_stream_decoder_state(const OggFLAC__FileDecoder *decoder); +FLAC__FileDecoderState OggFLAC__file_decoder_get_FLAC_file_decoder_state(const OggFLAC__FileDecoder *decoder); -/** Get the state of the underlying stream decoder. +/** Get the state of the underlying FLAC file decoder's seekable stream decoder. * Useful when the file decoder state is - * \c OggFLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR and the seekable stream - * decoder state is \c OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR. + * \c OggFLAC__FILE_DECODER_FLAC_FILE_DECODER_ERROR and the FLAC file decoder state is + * \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR. * * \param decoder An decoder instance to query. * \assert * \code decoder != NULL \endcode - * \retval OggFLAC__SeekableStreamDecoderState - * The seekable stream decoder state. + * \retval FLAC__SeekableStreamDecoderState + * The FLAC seekable stream decoder state. */ -OggFLAC__StreamDecoderState OggFLAC__file_decoder_get_stream_decoder_state(const OggFLAC__FileDecoder *decoder); +FLAC__SeekableStreamDecoderState OggFLAC__file_decoder_get_FLAC_seekable_stream_decoder_state(const OggFLAC__FileDecoder *decoder); -/** Get the "MD5 signature checking" flag. - * This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_get_md5_checking(). +/** Get the state of the underlying FLAC file decoder's stream decoder. + * Useful when the file decoder state is + * \c OggFLAC__FILE_DECODER_FLAC_FILE_DECODER_ERROR and the FLAC file decoder state is + * \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR and the + * FLAC seekable stream decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR. + * + * \param decoder An decoder instance to query. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__StreamDecoderState + * The FLAC stream decoder state. + */ +FLAC__StreamDecoderState OggFLAC__file_decoder_get_FLAC_stream_decoder_state(const OggFLAC__FileDecoder *decoder); + +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_get_md5_checking(). * * \param decoder A decoder instance to query. * \assert @@ -431,8 +389,8 @@ OggFLAC__StreamDecoderState OggFLAC__file_decoder_get_stream_decoder_state(const */ FLAC__bool OggFLAC__file_decoder_get_md5_checking(const OggFLAC__FileDecoder *decoder); -/** This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_get_channels(). +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_get_channels(). * * \param decoder A decoder instance to query. * \assert @@ -442,8 +400,8 @@ FLAC__bool OggFLAC__file_decoder_get_md5_checking(const OggFLAC__FileDecoder *de */ unsigned OggFLAC__file_decoder_get_channels(const OggFLAC__FileDecoder *decoder); -/** This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_get_channel_assignment(). +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_get_channel_assignment(). * * \param decoder A decoder instance to query. * \assert @@ -453,8 +411,8 @@ unsigned OggFLAC__file_decoder_get_channels(const OggFLAC__FileDecoder *decoder) */ OggFLAC__ChannelAssignment OggFLAC__file_decoder_get_channel_assignment(const OggFLAC__FileDecoder *decoder); -/** This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_get_bits_per_sample(). +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_get_bits_per_sample(). * * \param decoder A decoder instance to query. * \assert @@ -464,8 +422,8 @@ OggFLAC__ChannelAssignment OggFLAC__file_decoder_get_channel_assignment(const Og */ unsigned OggFLAC__file_decoder_get_bits_per_sample(const OggFLAC__FileDecoder *decoder); -/** This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_get_sample_rate(). +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_get_sample_rate(). * * \param decoder A decoder instance to query. * \assert @@ -475,8 +433,8 @@ unsigned OggFLAC__file_decoder_get_bits_per_sample(const OggFLAC__FileDecoder *d */ unsigned OggFLAC__file_decoder_get_sample_rate(const OggFLAC__FileDecoder *decoder); -/** This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_get_blocksize(). +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_get_blocksize(). * * \param decoder A decoder instance to query. * \assert @@ -510,7 +468,7 @@ OggFLAC__FileDecoderState OggFLAC__file_decoder_init(OggFLAC__FileDecoder *decod * In the event of a prematurely-terminated decode, it is not strictly * necessary to call this immediately before OggFLAC__file_decoder_delete() * but it is good practice to match every OggFLAC__file_decoder_init() with - * a OggFLAC__file_decoder_finish(). + * an OggFLAC__file_decoder_finish(). * * \param decoder An uninitialized decoder instance. * \assert @@ -523,8 +481,8 @@ OggFLAC__FileDecoderState OggFLAC__file_decoder_init(OggFLAC__FileDecoder *decod */ FLAC__bool OggFLAC__file_decoder_finish(OggFLAC__FileDecoder *decoder); -/** This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_process_single(). +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_process_single(). * * \param decoder A decoder instance. * \assert @@ -534,8 +492,8 @@ FLAC__bool OggFLAC__file_decoder_finish(OggFLAC__FileDecoder *decoder); */ FLAC__bool OggFLAC__file_decoder_process_single(OggFLAC__FileDecoder *decoder); -/** This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_process_until_end_of_metadata(). +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_process_until_end_of_metadata(). * * \param decoder A decoder instance. * \assert @@ -545,8 +503,8 @@ FLAC__bool OggFLAC__file_decoder_process_single(OggFLAC__FileDecoder *decoder); */ FLAC__bool OggFLAC__file_decoder_process_until_end_of_metadata(OggFLAC__FileDecoder *decoder); -/** This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_process_until_end_of_stream(). +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_process_until_end_of_stream(). * * \param decoder A decoder instance. * \assert @@ -556,8 +514,8 @@ FLAC__bool OggFLAC__file_decoder_process_until_end_of_metadata(OggFLAC__FileDeco */ FLAC__bool OggFLAC__file_decoder_process_until_end_of_file(OggFLAC__FileDecoder *decoder); -/** This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_process_remaining_frames(). +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_process_remaining_frames(). * * \param decoder A decoder instance. * \assert @@ -567,9 +525,8 @@ FLAC__bool OggFLAC__file_decoder_process_until_end_of_file(OggFLAC__FileDecoder */ FLAC__bool OggFLAC__file_decoder_process_remaining_frames(OggFLAC__FileDecoder *decoder); -/** Flush the input and seek to an absolute sample. - * This is inherited from OggFLAC__SeekableStreamDecoder; see - * OggFLAC__seekable_stream_decoder_seek_absolute(). +/** This is inherited from FLAC__FileDecoder; see + * FLAC__file_decoder_seek_absolute(). * * \param decoder A decoder instance. * \param sample The target sample number to seek to. diff --git a/include/OggFLAC/file_encoder.h b/include/OggFLAC/file_encoder.h index d75699a2..84047431 100644 --- a/include/OggFLAC/file_encoder.h +++ b/include/OggFLAC/file_encoder.h @@ -44,48 +44,15 @@ extern "C" { * This module contains the functions which implement the file * encoder. * - * The basic usage of this encoder is as follows: - * - The program creates an instance of an encoder using - * OggFLAC__file_encoder_new(). - * - The program overrides the default settings using - * OggFLAC__file_encoder_set_*() functions. - * - The program initializes the instance to validate the settings and - * prepare for encoding using OggFLAC__file_encoder_init(). - * - The program calls OggFLAC__file_encoder_process() or - * OggFLAC__file_encoder_process_interleaved() to encode data, which - * subsequently writes data to the output file. - * - The program finishes the encoding with OggFLAC__file_encoder_finish(), - * which causes the encoder to encode any data still in its input pipe, - * rewind and write the STREAMINFO metadata to file, and finally reset - * the encoder to the uninitialized state. - * - The instance may be used again or deleted with - * OggFLAC__file_encoder_delete(). - * - * The file encoder is a wrapper around the - * \link oggflac_seekable_stream_encoder seekable stream encoder \endlink which supplies all - * callbacks internally; the user need specify only the filename. - * - * Make sure to read the detailed description of the - * \link oggflac_seekable_stream_encoder seekable stream encoder module \endlink since the - * \link oggflac_stream_encoder stream encoder module \endlink since the - * file encoder inherits much of its behavior from them. - * - * \note - * The "set" functions may only be called when the encoder is in the - * state OggFLAC__FILE_ENCODER_UNINITIALIZED, i.e. after - * OggFLAC__file_encoder_new() or OggFLAC__file_encoder_finish(), but - * before OggFLAC__file_encoder_init(). If this is the case they will - * return \c true, otherwise \c false. - * - * \note - * OggFLAC__file_encoder_finish() resets all settings to the constructor - * defaults. + * The interface here is identical to FLAC's file encoder. See the + * defaults, including the callbacks. See the \link flac_file_encoder + * FLAC file encoder module \endlink for full documentation. * * \{ */ -/** State values for a OggFLAC__FileEncoder +/** State values for an OggFLAC__FileEncoder * * The encoder's state can be obtained by calling OggFLAC__file_encoder_get_state(). */ @@ -94,21 +61,13 @@ typedef enum { OggFLAC__FILE_ENCODER_OK = 0, /**< The encoder is in the normal OK state. */ - OggFLAC__FILE_ENCODER_NO_FILENAME, - /**< OggFLAC__file_encoder_init() was called without first calling - * OggFLAC__file_encoder_set_filename(). + OggFLAC__FILE_ENCODER_FLAC_FILE_ENCODER_ERROR, + /**< An error occurred in the underlying FLAC file encoder; + * check OggFLAC__file_encoder_get_FLAC_file_encoder_state(). */ - OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR, - /**< An error occurred in the underlying seekable stream encoder; - * check OggFLAC__file_encoder_get_seekable_stream_encoder_state(). - */ - - OggFLAC__FILE_ENCODER_FATAL_ERROR_WHILE_WRITING, - /**< A fatal error occurred while writing to the encoded file. */ - - OggFLAC__FILE_ENCODER_ERROR_OPENING_FILE, - /**< An error occurred opening the output file for writing. */ + OggFLAC__FILE_ENCODER_INVALID_CALLBACK, + /**< The encoder was initialized before setting all the required callbacks. */ OggFLAC__FILE_ENCODER_MEMORY_ALLOCATION_ERROR, /**< Memory allocation failed. */ @@ -124,9 +83,9 @@ typedef enum { } OggFLAC__FileEncoderState; -/** Maps a OggFLAC__FileEncoderState to a C string. +/** Maps an OggFLAC__FileEncoderState to a C string. * - * Using a OggFLAC__FileEncoderState as the index to this array + * Using an OggFLAC__FileEncoderState as the index to this array * will give the string equivalent. The contents should not be modified. */ /* @@@@ double-check mapping */ @@ -183,8 +142,8 @@ void OggFLAC__file_encoder_delete(OggFLAC__FileEncoder *encoder); * ***********************************************************************/ -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_verify(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_verify(). * * \default \c true * \param encoder An encoder instance to set. @@ -196,8 +155,8 @@ void OggFLAC__file_encoder_delete(OggFLAC__FileEncoder *encoder); */ FLAC__bool OggFLAC__file_encoder_set_verify(OggFLAC__FileEncoder *encoder, FLAC__bool value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_streamable_subset(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_streamable_subset(). * * \default \c true * \param encoder An encoder instance to set. @@ -209,8 +168,8 @@ FLAC__bool OggFLAC__file_encoder_set_verify(OggFLAC__FileEncoder *encoder, FLAC_ */ FLAC__bool OggFLAC__file_encoder_set_streamable_subset(OggFLAC__FileEncoder *encoder, FLAC__bool value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_do_mid_side_stereo(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_do_mid_side_stereo(). * * \default \c false * \param encoder An encoder instance to set. @@ -222,8 +181,8 @@ FLAC__bool OggFLAC__file_encoder_set_streamable_subset(OggFLAC__FileEncoder *enc */ FLAC__bool OggFLAC__file_encoder_set_do_mid_side_stereo(OggFLAC__FileEncoder *encoder, FLAC__bool value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_loose_mid_side_stereo(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_loose_mid_side_stereo(). * * \default \c false * \param encoder An encoder instance to set. @@ -235,8 +194,8 @@ FLAC__bool OggFLAC__file_encoder_set_do_mid_side_stereo(OggFLAC__FileEncoder *en */ FLAC__bool OggFLAC__file_encoder_set_loose_mid_side_stereo(OggFLAC__FileEncoder *encoder, FLAC__bool value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_channels(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_channels(). * * \default \c 2 * \param encoder An encoder instance to set. @@ -248,8 +207,8 @@ FLAC__bool OggFLAC__file_encoder_set_loose_mid_side_stereo(OggFLAC__FileEncoder */ FLAC__bool OggFLAC__file_encoder_set_channels(OggFLAC__FileEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_bits_per_sample(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_bits_per_sample(). * * \warning * Do not feed the encoder data that is wider than the value you @@ -265,8 +224,8 @@ FLAC__bool OggFLAC__file_encoder_set_channels(OggFLAC__FileEncoder *encoder, uns */ FLAC__bool OggFLAC__file_encoder_set_bits_per_sample(OggFLAC__FileEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_sample_rate(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_sample_rate(). * * \default \c 44100 * \param encoder An encoder instance to set. @@ -278,8 +237,8 @@ FLAC__bool OggFLAC__file_encoder_set_bits_per_sample(OggFLAC__FileEncoder *encod */ FLAC__bool OggFLAC__file_encoder_set_sample_rate(OggFLAC__FileEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_blocksize(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_blocksize(). * * \default \c 1152 * \param encoder An encoder instance to set. @@ -291,8 +250,8 @@ FLAC__bool OggFLAC__file_encoder_set_sample_rate(OggFLAC__FileEncoder *encoder, */ FLAC__bool OggFLAC__file_encoder_set_blocksize(OggFLAC__FileEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_max_lpc_order(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_max_lpc_order(). * * \default \c 0 * \param encoder An encoder instance to set. @@ -304,8 +263,8 @@ FLAC__bool OggFLAC__file_encoder_set_blocksize(OggFLAC__FileEncoder *encoder, un */ FLAC__bool OggFLAC__file_encoder_set_max_lpc_order(OggFLAC__FileEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_qlp_coeff_precision(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_qlp_coeff_precision(). * * \note * In the current implementation, qlp_coeff_precision + bits_per_sample must @@ -321,8 +280,8 @@ FLAC__bool OggFLAC__file_encoder_set_max_lpc_order(OggFLAC__FileEncoder *encoder */ FLAC__bool OggFLAC__file_encoder_set_qlp_coeff_precision(OggFLAC__FileEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_do_qlp_coeff_prec_search(). * * \default \c false * \param encoder An encoder instance to set. @@ -334,8 +293,8 @@ FLAC__bool OggFLAC__file_encoder_set_qlp_coeff_precision(OggFLAC__FileEncoder *e */ FLAC__bool OggFLAC__file_encoder_set_do_qlp_coeff_prec_search(OggFLAC__FileEncoder *encoder, FLAC__bool value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_do_escape_coding(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_do_escape_coding(). * * \default \c false * \param encoder An encoder instance to set. @@ -347,8 +306,8 @@ FLAC__bool OggFLAC__file_encoder_set_do_qlp_coeff_prec_search(OggFLAC__FileEncod */ FLAC__bool OggFLAC__file_encoder_set_do_escape_coding(OggFLAC__FileEncoder *encoder, FLAC__bool value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_do_exhaustive_model_search(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_do_exhaustive_model_search(). * * \default \c false * \param encoder An encoder instance to set. @@ -360,8 +319,8 @@ FLAC__bool OggFLAC__file_encoder_set_do_escape_coding(OggFLAC__FileEncoder *enco */ FLAC__bool OggFLAC__file_encoder_set_do_exhaustive_model_search(OggFLAC__FileEncoder *encoder, FLAC__bool value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_min_residual_partition_order(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_min_residual_partition_order(). * * \default \c 0 * \param encoder An encoder instance to set. @@ -373,8 +332,8 @@ FLAC__bool OggFLAC__file_encoder_set_do_exhaustive_model_search(OggFLAC__FileEnc */ FLAC__bool OggFLAC__file_encoder_set_min_residual_partition_order(OggFLAC__FileEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_max_residual_partition_order(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_max_residual_partition_order(). * * \default \c 0 * \param encoder An encoder instance to set. @@ -386,8 +345,8 @@ FLAC__bool OggFLAC__file_encoder_set_min_residual_partition_order(OggFLAC__FileE */ FLAC__bool OggFLAC__file_encoder_set_max_residual_partition_order(OggFLAC__FileEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_rice_parameter_search_dist(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_rice_parameter_search_dist(). * * \default \c 0 * \param encoder An encoder instance to set. @@ -399,8 +358,8 @@ FLAC__bool OggFLAC__file_encoder_set_max_residual_partition_order(OggFLAC__FileE */ FLAC__bool OggFLAC__file_encoder_set_rice_parameter_search_dist(OggFLAC__FileEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_total_samples_estimate(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_total_samples_estimate(). * * \default \c 0 * \param encoder An encoder instance to set. @@ -412,8 +371,8 @@ FLAC__bool OggFLAC__file_encoder_set_rice_parameter_search_dist(OggFLAC__FileEnc */ FLAC__bool OggFLAC__file_encoder_set_total_samples_estimate(OggFLAC__FileEncoder *encoder, FLAC__uint64 value); -/** This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_set_metadata(). +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_metadata(). * * \default \c NULL, 0 * \param encoder An encoder instance to set. @@ -426,14 +385,8 @@ FLAC__bool OggFLAC__file_encoder_set_total_samples_estimate(OggFLAC__FileEncoder */ FLAC__bool OggFLAC__file_encoder_set_metadata(OggFLAC__FileEncoder *encoder, OggFLAC__StreamMetadata **metadata, unsigned num_blocks); -/** Set the output file name encode to. - * - * \note - * The filename is mandatory and must be set before initialization. - * - * \note - * Unlike the OggFLAC__FileDecoder, the filename does not interpret "-" for - * \c stdout; writing to \c stdout is not relevant in the file encoder. +/** This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_filename(). * * \default \c NULL * \param encoder A encoder instance to set. @@ -448,14 +401,8 @@ FLAC__bool OggFLAC__file_encoder_set_metadata(OggFLAC__FileEncoder *encoder, Ogg FLAC__bool OggFLAC__file_encoder_set_filename(OggFLAC__FileEncoder *encoder, const char *value); /** Set the progress callback. - * The supplied function will be called when the encoder has finished - * writing a frame. The \c total_frames_estimate argument to the callback - * will be based on the value from - * OggFLAC__file_encoder_set_total_samples_estimate(). - * - * \note - * Unlike most other callbacks, the progress callback is \b not mandatory - * and need not be set before initialization. + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_set_progress_callback(). * * \default \c NULL * \param encoder An encoder instance to set. @@ -492,48 +439,63 @@ FLAC__bool OggFLAC__file_encoder_set_client_data(OggFLAC__FileEncoder *encoder, */ OggFLAC__FileEncoderState OggFLAC__file_encoder_get_state(const OggFLAC__FileEncoder *encoder); -/** Get the state of the underlying seekable stream encoder. +/** Get the state of the underlying FLAC file encoder. * Useful when the file encoder state is - * \c OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR. + * \c OggFLAC__FILE_ENCODER_FLAC_FILE_ENCODER_ERROR. * * \param encoder An encoder instance to query. * \assert * \code encoder != NULL \endcode - * \retval OggFLAC__SeekableStreamEncoderState - * The seekable stream encoder state. + * \retval FLAC__FileEncoderState + * The FLAC file encoder state. */ -OggFLAC__SeekableStreamEncoderState OggFLAC__file_encoder_get_seekable_stream_encoder_state(const OggFLAC__FileEncoder *encoder); +FLAC__FileEncoderState OggFLAC__file_encoder_get_FLAC_file_encoder_state(const OggFLAC__FileEncoder *encoder); -/** Get the state of the underlying stream encoder. +/** Get the state of the underlying FLAC file encoder's seekable stream encoder. * Useful when the file encoder state is - * \c OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream - * encoder state is \c OggFLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR. + * \c OggFLAC__FILE_ENCODER_FLAC_FILE_ENCODER_ERROR and the FLAC file encoder state is + * \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_DECODER_ERROR. * * \param encoder An encoder instance to query. * \assert * \code encoder != NULL \endcode - * \retval OggFLAC__SeekableStreamEncoderState - * The seekable stream encoder state. + * \retval FLAC__SeekableStreamEncoderState + * The FLAC seekable stream encoder state. */ -OggFLAC__StreamEncoderState OggFLAC__file_encoder_get_stream_encoder_state(const OggFLAC__FileEncoder *encoder); +FLAC__SeekableStreamEncoderState OggFLAC__file_encoder_get_FLAC_seekable_stream_encoder_state(const OggFLAC__FileEncoder *encoder); -/** Get the state of the underlying stream encoder's verify decoder. +/** Get the state of the underlying FLAC file encoder's stream encoder. * Useful when the file encoder state is - * \c OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream - * encoder state is \c OggFLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and - * the stream encoder state is \c OggFLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. + * \c OggFLAC__FILE_ENCODER_FLAC_FILE_ENCODER_ERROR and the FLAC file encoder state is + * \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_DECODER_ERROR and the + * FLAC seekable stream encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR. * * \param encoder An encoder instance to query. * \assert * \code encoder != NULL \endcode - * \retval OggFLAC__StreamEncoderState - * The stream encoder state. + * \retval FLAC__StreamEncoderState + * The FLAC stream encoder state. */ -OggFLAC__StreamDecoderState OggFLAC__file_encoder_get_verify_decoder_state(const OggFLAC__FileEncoder *encoder); +FLAC__StreamEncoderState OggFLAC__file_encoder_get_FLAC_stream_encoder_state(const OggFLAC__FileEncoder *encoder); + +/** Get the state of the underlying FLAC file encoder's verify decoder. + * Useful when the file encoder state is + * \c OggFLAC__FILE_ENCODER_FLAC_FILE_ENCODER_ERROR and the FLAC file encoder state is + * \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_DECODER_ERROR and the + * FLAC seekable stream encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR + * and the stream encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__StreamDecoderState + * The FLAC verify decoder state. + */ +FLAC__StreamDecoderState OggFLAC__file_encoder_get_verify_decoder_state(const OggFLAC__FileEncoder *encoder); /** Get the "verify" flag. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_verify(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_verify(). * * \param encoder An encoder instance to query. * \assert @@ -544,8 +506,8 @@ OggFLAC__StreamDecoderState OggFLAC__file_encoder_get_verify_decoder_state(const FLAC__bool OggFLAC__file_encoder_get_verify(const OggFLAC__FileEncoder *encoder); /** Get the "streamable subset" flag. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_streamable_subset(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_streamable_subset(). * * \param encoder An encoder instance to query. * \assert @@ -556,8 +518,8 @@ FLAC__bool OggFLAC__file_encoder_get_verify(const OggFLAC__FileEncoder *encoder) FLAC__bool OggFLAC__file_encoder_get_streamable_subset(const OggFLAC__FileEncoder *encoder); /** Get the "mid/side stereo coding" flag. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_do_mid_side_stereo(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_do_mid_side_stereo(). * * \param encoder An encoder instance to query. * \assert @@ -568,8 +530,8 @@ FLAC__bool OggFLAC__file_encoder_get_streamable_subset(const OggFLAC__FileEncode FLAC__bool OggFLAC__file_encoder_get_do_mid_side_stereo(const OggFLAC__FileEncoder *encoder); /** Get the "adaptive mid/side switching" flag. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_loose_mid_side_stereo(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_loose_mid_side_stereo(). * * \param encoder An encoder instance to query. * \assert @@ -580,8 +542,8 @@ FLAC__bool OggFLAC__file_encoder_get_do_mid_side_stereo(const OggFLAC__FileEncod FLAC__bool OggFLAC__file_encoder_get_loose_mid_side_stereo(const OggFLAC__FileEncoder *encoder); /** Get the number of input channels being processed. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_channels(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_channels(). * * \param encoder An encoder instance to query. * \assert @@ -592,8 +554,8 @@ FLAC__bool OggFLAC__file_encoder_get_loose_mid_side_stereo(const OggFLAC__FileEn unsigned OggFLAC__file_encoder_get_channels(const OggFLAC__FileEncoder *encoder); /** Get the input sample resolution setting. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_bits_per_sample(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_bits_per_sample(). * * \param encoder An encoder instance to query. * \assert @@ -604,8 +566,8 @@ unsigned OggFLAC__file_encoder_get_channels(const OggFLAC__FileEncoder *encoder) unsigned OggFLAC__file_encoder_get_bits_per_sample(const OggFLAC__FileEncoder *encoder); /** Get the input sample rate setting. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_sample_rate(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_sample_rate(). * * \param encoder An encoder instance to query. * \assert @@ -616,8 +578,8 @@ unsigned OggFLAC__file_encoder_get_bits_per_sample(const OggFLAC__FileEncoder *e unsigned OggFLAC__file_encoder_get_sample_rate(const OggFLAC__FileEncoder *encoder); /** Get the blocksize setting. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_blocksize(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_blocksize(). * * \param encoder An encoder instance to query. * \assert @@ -628,8 +590,8 @@ unsigned OggFLAC__file_encoder_get_sample_rate(const OggFLAC__FileEncoder *encod unsigned OggFLAC__file_encoder_get_blocksize(const OggFLAC__FileEncoder *encoder); /** Get the maximum LPC order setting. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_max_lpc_order(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_max_lpc_order(). * * \param encoder An encoder instance to query. * \assert @@ -640,8 +602,8 @@ unsigned OggFLAC__file_encoder_get_blocksize(const OggFLAC__FileEncoder *encoder unsigned OggFLAC__file_encoder_get_max_lpc_order(const OggFLAC__FileEncoder *encoder); /** Get the quantized linear predictor coefficient precision setting. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_qlp_coeff_precision(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_qlp_coeff_precision(). * * \param encoder An encoder instance to query. * \assert @@ -652,8 +614,8 @@ unsigned OggFLAC__file_encoder_get_max_lpc_order(const OggFLAC__FileEncoder *enc unsigned OggFLAC__file_encoder_get_qlp_coeff_precision(const OggFLAC__FileEncoder *encoder); /** Get the qlp coefficient precision search flag. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_do_qlp_coeff_prec_search(). * * \param encoder An encoder instance to query. * \assert @@ -664,8 +626,8 @@ unsigned OggFLAC__file_encoder_get_qlp_coeff_precision(const OggFLAC__FileEncode FLAC__bool OggFLAC__file_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__FileEncoder *encoder); /** Get the "escape coding" flag. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_do_escape_coding(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_do_escape_coding(). * * \param encoder An encoder instance to query. * \assert @@ -676,8 +638,8 @@ FLAC__bool OggFLAC__file_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__Fil FLAC__bool OggFLAC__file_encoder_get_do_escape_coding(const OggFLAC__FileEncoder *encoder); /** Get the exhaustive model search flag. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_do_exhaustive_model_search(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_do_exhaustive_model_search(). * * \param encoder An encoder instance to query. * \assert @@ -688,8 +650,8 @@ FLAC__bool OggFLAC__file_encoder_get_do_escape_coding(const OggFLAC__FileEncoder FLAC__bool OggFLAC__file_encoder_get_do_exhaustive_model_search(const OggFLAC__FileEncoder *encoder); /** Get the minimum residual partition order setting. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_min_residual_partition_order(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_min_residual_partition_order(). * * \param encoder An encoder instance to query. * \assert @@ -700,8 +662,8 @@ FLAC__bool OggFLAC__file_encoder_get_do_exhaustive_model_search(const OggFLAC__F unsigned OggFLAC__file_encoder_get_min_residual_partition_order(const OggFLAC__FileEncoder *encoder); /** Get maximum residual partition order setting. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_max_residual_partition_order(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_max_residual_partition_order(). * * \param encoder An encoder instance to query. * \assert @@ -712,8 +674,8 @@ unsigned OggFLAC__file_encoder_get_min_residual_partition_order(const OggFLAC__F unsigned OggFLAC__file_encoder_get_max_residual_partition_order(const OggFLAC__FileEncoder *encoder); /** Get the Rice parameter search distance setting. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_rice_parameter_search_dist(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_rice_parameter_search_dist(). * * \param encoder An encoder instance to query. * \assert @@ -724,8 +686,8 @@ unsigned OggFLAC__file_encoder_get_max_residual_partition_order(const OggFLAC__F unsigned OggFLAC__file_encoder_get_rice_parameter_search_dist(const OggFLAC__FileEncoder *encoder); /** Get the previously set estimate of the total samples to be encoded. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_get_total_samples_estimate(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_get_total_samples_estimate(). * * \param encoder An encoder instance to query. * \assert @@ -759,7 +721,7 @@ OggFLAC__FileEncoderState OggFLAC__file_encoder_init(OggFLAC__FileEncoder *encod * In the event of a prematurely-terminated encode, it is not strictly * necessary to call this immediately before OggFLAC__file_encoder_delete() * but it is good practice to match every OggFLAC__file_encoder_init() - * with a OggFLAC__file_encoder_finish(). + * with an OggFLAC__file_encoder_finish(). * * \param encoder An uninitialized encoder instance. * \assert @@ -768,8 +730,8 @@ OggFLAC__FileEncoderState OggFLAC__file_encoder_init(OggFLAC__FileEncoder *encod void OggFLAC__file_encoder_finish(OggFLAC__FileEncoder *encoder); /** Submit data for encoding. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_process(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_process(). * * \param encoder An initialized encoder instance in the OK state. * \param buffer An array of pointers to each channel's signal. @@ -785,8 +747,8 @@ void OggFLAC__file_encoder_finish(OggFLAC__FileEncoder *encoder); FLAC__bool OggFLAC__file_encoder_process(OggFLAC__FileEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples); /** Submit data for encoding. - * This is inherited from OggFLAC__SeekableStreamEncoder; see - * OggFLAC__seekable_stream_encoder_process_interleaved(). + * This is inherited from FLAC__FileEncoder; see + * FLAC__file_encoder_process_interleaved(). * * \param encoder An initialized encoder instance in the OK state. * \param buffer An array of channel-interleaved data (see above). diff --git a/include/OggFLAC/seekable_stream_decoder.h b/include/OggFLAC/seekable_stream_decoder.h index d50b436c..3970bccc 100644 --- a/include/OggFLAC/seekable_stream_decoder.h +++ b/include/OggFLAC/seekable_stream_decoder.h @@ -44,210 +44,56 @@ extern "C" { * This module contains the functions which implement the seekable stream * decoder. * - * The basic usage of this decoder is as follows: - * - The program creates an instance of a decoder using - * OggFLAC__seekable_stream_decoder_new(). - * - The program overrides the default settings and sets callbacks for - * reading, writing, seeking, error reporting, and metadata reporting - * using OggFLAC__seekable_stream_decoder_set_*() functions. - * - The program initializes the instance to validate the settings and - * prepare for decoding using OggFLAC__seekable_stream_decoder_init(). - * - The program calls the OggFLAC__seekable_stream_decoder_process_*() - * functions to decode data, which subsequently calls the callbacks. - * - The program finishes the decoding with - * OggFLAC__seekable_stream_decoder_finish(), which flushes the input and - * output and resets the decoder to the uninitialized state. - * - The instance may be used again or deleted with - * OggFLAC__seekable_stream_decoder_delete(). - * - * The seekable stream decoder is a wrapper around the - * \link oggflac_stream_decoder stream decoder \endlink which also provides - * seeking capability. In addition to the Read/Write/Metadata/Error - * callbacks of the stream decoder, the user must also provide the following: - * - * - Seek callback - This function will be called when the decoder wants to - * seek to an absolute position in the stream. - * - Tell callback - This function will be called when the decoder wants to - * know the current absolute position of the stream. - * - Length callback - This function will be called when the decoder wants - * to know length of the stream. The seeking algorithm currently requires - * that the overall stream length be known. - * - EOF callback - This function will be called when the decoder wants to - * know if it is at the end of the stream. This could be synthesized from - * the tell and length callbacks but it may be more expensive that way, so - * there is a separate callback for it. - * - * Seeking is exposed through the - * OggFLAC__seekable_stream_decoder_seek_absolute() method. At any point after - * the seekable stream decoder has been initialized, the user can call this - * function to seek to an exact sample within the stream. Subsequently, the - * first time the write callback is called it will be passed a (possibly - * partial) block starting at that sample. - * - * The seekable stream decoder also provides MD5 signature checking. If - * this is turned on before initialization, - * OggFLAC__seekable_stream_decoder_finish() will report when the decoded MD5 - * signature does not match the one stored in the STREAMINFO block. MD5 - * checking is automatically turned off (until the next - * OggFLAC__seekable_stream_decoder_reset()) if there is no signature in the - * STREAMINFO block or when a seek is attempted. - * - * Make sure to read the detailed description of the - * \link oggflac_stream_decoder stream decoder module \endlink since the - * seekable stream decoder inherits much of its behavior. - * - * \note - * The "set" functions may only be called when the decoder is in the - * state OggFLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED, i.e. after - * OggFLAC__seekable_stream_decoder_new() or - * OggFLAC__seekable_stream_decoder_finish(), but before - * OggFLAC__seekable_stream_decoder_init(). If this is the case they will - * return \c true, otherwise \c false. - * - * \note - * OggFLAC__stream_decoder_finish() resets all settings to the constructor - * defaults, including the callbacks. + * The interface here is identical to FLAC's seekable stream decoder. See the + * defaults, including the callbacks. See the \link flac_seekable_stream_decoder + * FLAC seekable stream decoder module \endlink for full documentation. * * \{ */ -/** State values for a OggFLAC__SeekableStreamDecoder +/** State values for an OggFLAC__SeekableStreamDecoder * * The decoder's state can be obtained by calling OggFLAC__seekable_stream_decoder_get_state(). */ typedef enum { - OggFLAC__SEEKABLE_STREAM_DECODER_OK = 0, + OggFLAC__SEEKABLE_STREAM_DECODER_OK = 0, /**< The decoder is in the normal OK state. */ - OggFLAC__SEEKABLE_STREAM_DECODER_SEEKING, - /**< The decoder is in the process of seeking. */ - - OggFLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM, - /**< The decoder has reached the end of the stream. */ - - OggFLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR, - /**< An error occurred allocating memory. */ - - OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR, - /**< An error occurred in the underlying stream decoder. */ - - OggFLAC__SEEKABLE_STREAM_DECODER_READ_ERROR, - /**< The read callback returned an error. */ - - OggFLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR, - /**< An error occurred while seeking or the seek or tell - * callback returned an error. + OggFLAC__SEEKABLE_STREAM_DECODER_FLAC_SEEKABLE_STREAM_DECODER_ERROR, + /**< An error occurred in the underlying FLAC seekable stream decoder; + * check OggFLAC__seekable_stream_decoder_get_FLAC_seekable_stream_decoder_state(). */ - OggFLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED, - /**< OggFLAC__seekable_stream_decoder_init() was called when the - * decoder was already initialized, usually because + OggFLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK, + /**< The decoder was initialized before setting all the required callbacks. */ + + OggFLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR, + /**< Memory allocation failed. */ + + OggFLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED, + /**< OggFLAC__seekable_stream_decoder_init() was called when the decoder was + * already initialized, usually because * OggFLAC__seekable_stream_decoder_finish() was not called. */ - OggFLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK, - /**< OggFLAC__seekable_stream_decoder_init() was called without all - * callbacks being set. - */ - - OggFLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED + OggFLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED /**< The decoder is in the uninitialized state. */ } OggFLAC__SeekableStreamDecoderState; -/** Maps a OggFLAC__SeekableStreamDecoderState to a C string. +/** Maps an OggFLAC__SeekableStreamDecoderState to a C string. * - * Using a OggFLAC__SeekableStreamDecoderState as the index to this array + * Using an OggFLAC__SeekableStreamDecoderState as the index to this array * will give the string equivalent. The contents should not be modified. */ extern const char * const OggFLAC__SeekableStreamDecoderStateString[]; -/** Return values for the OggFLAC__SeekableStreamDecoder read callback. - */ -typedef enum { - - OggFLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK, - /**< The read was OK and decoding can continue. */ - - OggFLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR - /**< An unrecoverable error occurred. The decoder will return from the process call. */ - -} OggFLAC__SeekableStreamDecoderReadStatus; - -/** Maps a OggFLAC__SeekableStreamDecoderReadStatus to a C string. - * - * Using a OggFLAC__SeekableStreamDecoderReadStatus as the index to this array - * will give the string equivalent. The contents should not be modified. - */ -extern const char * const OggFLAC__SeekableStreamDecoderReadStatusString[]; - - -/** Return values for the OggFLAC__SeekableStreamDecoder seek callback. - */ -typedef enum { - - OggFLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK, - /**< The seek was OK and decoding can continue. */ - - OggFLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR - /**< An unrecoverable error occurred. The decoder will return from the process call. */ - -} OggFLAC__SeekableStreamDecoderSeekStatus; - -/** Maps a OggFLAC__SeekableStreamDecoderSeekStatus to a C string. - * - * Using a OggFLAC__SeekableStreamDecoderSeekStatus as the index to this array - * will give the string equivalent. The contents should not be modified. - */ -extern const char * const OggFLAC__SeekableStreamDecoderSeekStatusString[]; - - -/** Return values for the OggFLAC__SeekableStreamDecoder tell callback. - */ -typedef enum { - - OggFLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK, - /**< The tell was OK and decoding can continue. */ - - OggFLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR - /**< An unrecoverable error occurred. The decoder will return from the process call. */ - -} OggFLAC__SeekableStreamDecoderTellStatus; - -/** Maps a OggFLAC__SeekableStreamDecoderTellStatus to a C string. - * - * Using a OggFLAC__SeekableStreamDecoderTellStatus as the index to this array - * will give the string equivalent. The contents should not be modified. - */ -extern const char * const OggFLAC__SeekableStreamDecoderTellStatusString[]; - - -/** Return values for the OggFLAC__SeekableStreamDecoder length callback. - */ -typedef enum { - - OggFLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK, - /**< The length call was OK and decoding can continue. */ - - OggFLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR - /**< An unrecoverable error occurred. The decoder will return from the process call. */ - -} OggFLAC__SeekableStreamDecoderLengthStatus; - -/** Maps a OggFLAC__SeekableStreamDecoderLengthStatus to a C string. - * - * Using a OggFLAC__SeekableStreamDecoderLengthStatus as the index to this array - * will give the string equivalent. The contents should not be modified. - */ -extern const char * const OggFLAC__SeekableStreamDecoderLengthStatusString[]; - - /*********************************************************************** * - * class OggFLAC__SeekableStreamDecoder : public OggFLAC__StreamDecoder + * class OggFLAC__SeekableStreamDecoder : public FLAC__StreamDecoder * ***********************************************************************/ @@ -264,14 +110,14 @@ typedef struct { } OggFLAC__SeekableStreamDecoder; /*@@@ document */ -typedef OggFLAC__SeekableStreamDecoderReadStatus (*OggFLAC__SeekableStreamDecoderReadCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data); -typedef OggFLAC__SeekableStreamDecoderSeekStatus (*OggFLAC__SeekableStreamDecoderSeekCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data); -typedef OggFLAC__SeekableStreamDecoderTellStatus (*OggFLAC__SeekableStreamDecoderTellCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data); -typedef OggFLAC__SeekableStreamDecoderLengthStatus (*OggFLAC__SeekableStreamDecoderLengthCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data); +typedef FLAC__SeekableStreamDecoderReadStatus (*OggFLAC__SeekableStreamDecoderReadCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data); +typedef FLAC__SeekableStreamDecoderSeekStatus (*OggFLAC__SeekableStreamDecoderSeekCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data); +typedef FLAC__SeekableStreamDecoderTellStatus (*OggFLAC__SeekableStreamDecoderTellCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data); +typedef FLAC__SeekableStreamDecoderLengthStatus (*OggFLAC__SeekableStreamDecoderLengthCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data); typedef FLAC__bool (*OggFLAC__SeekableStreamDecoderEofCallback)(const OggFLAC__SeekableStreamDecoder *decoder, void *client_data); -typedef OggFLAC__StreamDecoderWriteStatus (*OggFLAC__SeekableStreamDecoderWriteCallback)(const OggFLAC__SeekableStreamDecoder *decoder, const OggFLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data); -typedef void (*OggFLAC__SeekableStreamDecoderMetadataCallback)(const OggFLAC__SeekableStreamDecoder *decoder, const OggFLAC__StreamMetadata *metadata, void *client_data); -typedef void (*OggFLAC__SeekableStreamDecoderErrorCallback)(const OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__StreamDecoderErrorStatus status, void *client_data); +typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__SeekableStreamDecoderWriteCallback)(const OggFLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data); +typedef void (*OggFLAC__SeekableStreamDecoderMetadataCallback)(const OggFLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data); +typedef void (*OggFLAC__SeekableStreamDecoderErrorCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data); /*********************************************************************** @@ -305,14 +151,9 @@ void OggFLAC__seekable_stream_decoder_delete(OggFLAC__SeekableStreamDecoder *dec * ***********************************************************************/ -/** 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 - * exists, during OggFLAC__seekable_stream_decoder_finish(). - * - * MD5 signature checking will be turned off (until the next - * OggFLAC__seekable_stream_decoder_reset()) if there is no signature in - * the STREAMINFO block or when a seek is attempted. +/** Set the "MD5 signature checking" flag. + * This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_set_md5_checking(). * * \default \c false * \param decoder A decoder instance to set. @@ -325,8 +166,8 @@ void OggFLAC__seekable_stream_decoder_delete(OggFLAC__SeekableStreamDecoder *dec FLAC__bool OggFLAC__seekable_stream_decoder_set_md5_checking(OggFLAC__SeekableStreamDecoder *decoder, FLAC__bool value); /** Set the read callback. - * This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_set_read_callback(). + * This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_set_read_callback(). * * \note * The callback is mandatory and must be set before initialization. @@ -343,9 +184,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_md5_checking(OggFLAC__SeekableSt FLAC__bool OggFLAC__seekable_stream_decoder_set_read_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderReadCallback value); /** Set the seek callback. - * The supplied function will be called when the decoder needs to seek - * the input stream. The decoder will pass the absolute byte offset - * to seek to, 0 meaning the beginning of the stream. + * This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_set_seek_callback(). * * \note * The callback is mandatory and must be set before initialization. @@ -362,9 +202,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_read_callback(OggFLAC__SeekableS FLAC__bool OggFLAC__seekable_stream_decoder_set_seek_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderSeekCallback value); /** Set the tell callback. - * The supplied function will be called when the decoder wants to know - * the current position of the stream. The callback should return the - * byte offset from the beginning of the stream. + * This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_set_tell_callback(). * * \note * The callback is mandatory and must be set before initialization. @@ -381,8 +220,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_seek_callback(OggFLAC__SeekableS FLAC__bool OggFLAC__seekable_stream_decoder_set_tell_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderTellCallback value); /** Set the length callback. - * The supplied function will be called when the decoder wants to know - * the total length of the stream in bytes. + * This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_set_length_callback(). * * \note * The callback is mandatory and must be set before initialization. @@ -399,8 +238,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_tell_callback(OggFLAC__SeekableS FLAC__bool OggFLAC__seekable_stream_decoder_set_length_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderLengthCallback value); /** Set the eof callback. - * The supplied function will be called when the decoder needs to know - * if the end of the stream has been reached. + * This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_set_eof_callback(). * * \note * The callback is mandatory and must be set before initialization. @@ -417,8 +256,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_length_callback(OggFLAC__Seekabl FLAC__bool OggFLAC__seekable_stream_decoder_set_eof_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderEofCallback value); /** Set the write callback. - * This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_set_write_callback(). + * This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_set_write_callback(). * * \note * The callback is mandatory and must be set before initialization. @@ -435,8 +274,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_eof_callback(OggFLAC__SeekableSt FLAC__bool OggFLAC__seekable_stream_decoder_set_write_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderWriteCallback value); /** Set the metadata callback. - * This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_set_metadata_callback(). + * This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_set_metadata_callback(). * * \note * The callback is mandatory and must be set before initialization. @@ -453,8 +292,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_write_callback(OggFLAC__Seekable FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderMetadataCallback value); /** Set the error callback. - * This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_set_error_callback(). + * This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_set_error_callback(). * * \note * The callback is mandatory and must be set before initialization. @@ -484,8 +323,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_error_callback(OggFLAC__Seekable */ FLAC__bool OggFLAC__seekable_stream_decoder_set_client_data(OggFLAC__SeekableStreamDecoder *decoder, void *value); -/** This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_set_metadata_respond(). +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_set_metadata_respond(). * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -499,8 +338,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_client_data(OggFLAC__SeekableStr */ FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__MetadataType type); -/** This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_set_metadata_respond_application(). +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_set_metadata_respond_application(). * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -514,8 +353,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond(OggFLAC__Seekab */ FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond_application(OggFLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]); -/** This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_set_metadata_respond_all(). +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_set_metadata_respond_all(). * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -527,8 +366,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond_application(Ogg */ FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond_all(OggFLAC__SeekableStreamDecoder *decoder); -/** This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_set_metadata_ignore(). +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_set_metadata_ignore(). * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -542,8 +381,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond_all(OggFLAC__Se */ FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__MetadataType type); -/** This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_set_metadata_ignore_application(). +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_set_metadata_ignore_application(). * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -557,8 +396,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore(OggFLAC__Seekabl */ FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore_application(OggFLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]); -/** This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_set_metadata_ignore_all(). +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_set_metadata_ignore_all(). * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -580,23 +419,33 @@ FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore_all(OggFLAC__See */ OggFLAC__SeekableStreamDecoderState OggFLAC__seekable_stream_decoder_get_state(const OggFLAC__SeekableStreamDecoder *decoder); -/** Get the state of the underlying stream decoder. +/** Get the state of the underlying FLAC seekable stream decoder. * Useful when the seekable stream decoder state is - * \c OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR. + * \c OggFLAC__SEEKABLE_STREAM_DECODER_FLAC_SEEKABLE_STREAM_DECODER_ERROR. * * \param decoder An decoder instance to query. * \assert * \code decoder != NULL \endcode - * \retval OggFLAC__StreamDecoderState - * The stream decoder state. + * \retval FLAC__SeekableStreamDecoderState + * The FLAC seekable stream decoder state. */ -OggFLAC__StreamDecoderState OggFLAC__seekable_stream_decoder_get_stream_decoder_state(const OggFLAC__SeekableStreamDecoder *decoder); +FLAC__SeekableStreamDecoderState OggFLAC__seekable_stream_decoder_get_FLAC_seekable_stream_decoder_state(const OggFLAC__SeekableStreamDecoder *decoder); -/** Get the "MD5 signature checking" flag. - * This is the value of the setting, not whether or not the decoder is - * currently checking the MD5 (remember, it can be turned off automatically - * by a seek). When the decoder is reset the flag will be restored to the - * value returned by this function. +/** Get the state of the underlying FLAC seekable stream decoder's stream decoder. + * Useful when the seekable stream decoder state is + * \c OggFLAC__SEEKABLE_STREAM_DECODER_FLAC_SEEKABLE_STREAM_DECODER_ERROR and the + * FLAC seekable stream decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR + * + * \param decoder An decoder instance to query. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__StreamDecoderState + * The FLAC stream decoder state. + */ +FLAC__StreamDecoderState OggFLAC__seekable_stream_decoder_get_FLAC_stream_decoder_state(const OggFLAC__SeekableStreamDecoder *decoder); + +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_get_md5_checking(). * * \param decoder A decoder instance to query. * \assert @@ -606,8 +455,8 @@ OggFLAC__StreamDecoderState OggFLAC__seekable_stream_decoder_get_stream_decoder_ */ FLAC__bool OggFLAC__seekable_stream_decoder_get_md5_checking(const OggFLAC__SeekableStreamDecoder *decoder); -/** This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_get_channels(). +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_get_channels(). * * \param decoder A decoder instance to query. * \assert @@ -617,8 +466,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_get_md5_checking(const OggFLAC__Seek */ unsigned OggFLAC__seekable_stream_decoder_get_channels(const OggFLAC__SeekableStreamDecoder *decoder); -/** This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_get_channel_assignment(). +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_get_channel_assignment(). * * \param decoder A decoder instance to query. * \assert @@ -628,8 +477,8 @@ unsigned OggFLAC__seekable_stream_decoder_get_channels(const OggFLAC__SeekableSt */ OggFLAC__ChannelAssignment OggFLAC__seekable_stream_decoder_get_channel_assignment(const OggFLAC__SeekableStreamDecoder *decoder); -/** This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_get_bits_per_sample(). +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_get_bits_per_sample(). * * \param decoder A decoder instance to query. * \assert @@ -639,8 +488,8 @@ OggFLAC__ChannelAssignment OggFLAC__seekable_stream_decoder_get_channel_assignme */ unsigned OggFLAC__seekable_stream_decoder_get_bits_per_sample(const OggFLAC__SeekableStreamDecoder *decoder); -/** This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_get_sample_rate(). +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_get_sample_rate(). * * \param decoder A decoder instance to query. * \assert @@ -650,8 +499,8 @@ unsigned OggFLAC__seekable_stream_decoder_get_bits_per_sample(const OggFLAC__See */ unsigned OggFLAC__seekable_stream_decoder_get_sample_rate(const OggFLAC__SeekableStreamDecoder *decoder); -/** This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_get_blocksize(). +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_get_blocksize(). * * \param decoder A decoder instance to query. * \assert @@ -700,10 +549,8 @@ OggFLAC__SeekableStreamDecoderState OggFLAC__seekable_stream_decoder_init(OggFLA */ FLAC__bool OggFLAC__seekable_stream_decoder_finish(OggFLAC__SeekableStreamDecoder *decoder); -/** Flush the stream input. - * The decoder's input buffer will be cleared and the state set to - * \c OggFLAC__SEEKABLE_STREAM_DECODER_OK. This will also turn off MD5 - * checking. +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_flush(). * * \param decoder A decoder instance. * \assert @@ -714,13 +561,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_finish(OggFLAC__SeekableStreamDecode */ FLAC__bool OggFLAC__seekable_stream_decoder_flush(OggFLAC__SeekableStreamDecoder *decoder); -/** Reset the decoding process. - * The decoder's input buffer will be cleared and the state set to - * \c OggFLAC__SEEKABLE_STREAM_DECODER_OK. This is similar to - * OggFLAC__seekable_stream_decoder_finish() except that the settings are - * preserved; there is no need to call OggFLAC__seekable_stream_decoder_init() - * before decoding again. MD5 checking will be restored to its original - * setting. +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_reset(). * * \param decoder A decoder instance. * \assert @@ -731,8 +573,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_flush(OggFLAC__SeekableStreamDecoder */ FLAC__bool OggFLAC__seekable_stream_decoder_reset(OggFLAC__SeekableStreamDecoder *decoder); -/** This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_process_single(). +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_process_single(). * * \param decoder A decoder instance. * \assert @@ -742,8 +584,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_reset(OggFLAC__SeekableStreamDecoder */ FLAC__bool OggFLAC__seekable_stream_decoder_process_single(OggFLAC__SeekableStreamDecoder *decoder); -/** This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_process_until_end_of_metadata(). +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_process_until_end_of_metadata(). * * \param decoder A decoder instance. * \assert @@ -753,8 +595,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_process_single(OggFLAC__SeekableStre */ FLAC__bool OggFLAC__seekable_stream_decoder_process_until_end_of_metadata(OggFLAC__SeekableStreamDecoder *decoder); -/** This is inherited from OggFLAC__StreamDecoder; see - * OggFLAC__stream_decoder_process_until_end_of_stream(). +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_process_until_end_of_stream(). * * \param decoder A decoder instance. * \assert @@ -764,9 +606,8 @@ FLAC__bool OggFLAC__seekable_stream_decoder_process_until_end_of_metadata(OggFLA */ FLAC__bool OggFLAC__seekable_stream_decoder_process_until_end_of_stream(OggFLAC__SeekableStreamDecoder *decoder); -/** Flush the input and seek to an absolute sample. - * Decoding will resume at the given sample. Note that because of - * this, the next write callback may contain a partial block. +/** This is inherited from FLAC__SeekableStreamDecoder; see + * FLAC__seekable_stream_decoder_seek_absolute(). * * \param decoder A decoder instance. * \param sample The target sample number to seek to. diff --git a/include/OggFLAC/seekable_stream_encoder.h b/include/OggFLAC/seekable_stream_encoder.h index 55cf8cbd..fee06b98 100644 --- a/include/OggFLAC/seekable_stream_encoder.h +++ b/include/OggFLAC/seekable_stream_encoder.h @@ -44,31 +44,15 @@ extern "C" { * This module contains the functions which implement the seekable stream * encoder. * - * XXX (import) - * - * The seekable stream encoder is a wrapper around the - * \link oggflac_stream_encoder stream encoder \endlink which (XXXimport) - * - * Make sure to read the detailed description of the - * \link oggflac_stream_encoder stream encoder module \endlink since the - * seekable stream encoder inherits much of its behavior. - * - * \note - * The "set" functions may only be called when the encoder is in the - * state OggFLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED, i.e. after - * OggFLAC__seekable_stream_encoder_new() or OggFLAC__seekable_stream_encoder_finish(), but - * before OggFLAC__seekable_stream_encoder_init(). If this is the case they will - * return \c true, otherwise \c false. - * - * \note - * OggFLAC__seekable_stream_encoder_finish() resets all settings to the constructor - * defaults, including the callbacks. + * The interface here is identical to FLAC's seekable stream encoder. See the + * defaults, including the callbacks. See the \link flac_seekable_stream_encoder + * FLAC seekable stream encoder module \endlink for full documentation. * * \{ */ -/** State values for a OggFLAC__SeekableStreamEncoder +/** State values for an OggFLAC__SeekableStreamEncoder * * The encoder's state can be obtained by calling OggFLAC__seekable_stream_encoder_get_state(). */ @@ -77,47 +61,31 @@ typedef enum { OggFLAC__SEEKABLE_STREAM_ENCODER_OK = 0, /**< The encoder is in the normal OK state. */ - OggFLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR, - /**< An error occurred in the underlying stream encoder; - * check OggFLAC__seekable_stream_encoder_get_stream_encoder_state(). + OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_SEEKABLE_STREAM_ENCODER_ERROR, + /**< An error occurred in the underlying FLAC seekable stream encoder; + * check OggFLAC__seekable_stream_encoder_get_FLAC_seekable_stream_encoder_state(). */ + OggFLAC__SEEKABLE_STREAM_ENCODER_INVALID_CALLBACK, + /**< The encoder was initialized before setting all the required callbacks. */ + OggFLAC__SEEKABLE_STREAM_ENCODER_MEMORY_ALLOCATION_ERROR, /**< Memory allocation failed. */ - OggFLAC__SEEKABLE_STREAM_ENCODER_WRITE_ERROR, - /**< The write callback returned an error. */ - - OggFLAC__SEEKABLE_STREAM_ENCODER_READ_ERROR, - /**< The read callback returned an error. */ - - OggFLAC__SEEKABLE_STREAM_ENCODER_SEEK_ERROR, - /**< The seek callback returned an error. */ - OggFLAC__SEEKABLE_STREAM_ENCODER_ALREADY_INITIALIZED, /**< OggFLAC__seekable_stream_encoder_init() was called when the encoder was * already initialized, usually because * OggFLAC__seekable_stream_encoder_finish() was not called. */ - OggFLAC__SEEKABLE_STREAM_ENCODER_INVALID_CALLBACK, - /**< OggFLAC__seekable_stream_encoder_init() was called without all - * callbacks being set. - */ - - OggFLAC__SEEKABLE_STREAM_ENCODER_INVALID_SEEKTABLE, - /**< An invalid seek table was passed is the metadata to - * OggFLAC__seekable_stream_encoder_set_metadata(). - */ - OggFLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED /**< The encoder is in the uninitialized state. */ } OggFLAC__SeekableStreamEncoderState; -/** Maps a OggFLAC__SeekableStreamEncoderState to a C string. +/** Maps an OggFLAC__SeekableStreamEncoderState to a C string. * - * Using a OggFLAC__SeekableStreamEncoderState as the index to this array + * Using an OggFLAC__SeekableStreamEncoderState as the index to this array * will give the string equivalent. The contents should not be modified. */ /* @@@@ double-check mapping */ @@ -136,9 +104,9 @@ typedef enum { } OggFLAC__SeekableStreamEncoderSeekStatus; -/** Maps a OggFLAC__SeekableStreamEncoderSeekStatus to a C string. +/** Maps an OggFLAC__SeekableStreamEncoderSeekStatus to a C string. * - * Using a OggFLAC__SeekableStreamEncoderSeekStatus as the index to this array + * Using an OggFLAC__SeekableStreamEncoderSeekStatus as the index to this array * will give the string equivalent. The contents should not be modified. */ extern const char * const OggFLAC__SeekableStreamEncoderSeekStatusString[]; @@ -195,8 +163,8 @@ void OggFLAC__seekable_stream_encoder_delete(OggFLAC__SeekableStreamEncoder *enc * ***********************************************************************/ -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_verify(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_verify(). * * \default \c true * \param encoder An encoder instance to set. @@ -208,8 +176,8 @@ void OggFLAC__seekable_stream_encoder_delete(OggFLAC__SeekableStreamEncoder *enc */ FLAC__bool OggFLAC__seekable_stream_encoder_set_verify(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_streamable_subset(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_streamable_subset(). * * \default \c true * \param encoder An encoder instance to set. @@ -221,8 +189,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_verify(OggFLAC__SeekableStreamEn */ FLAC__bool OggFLAC__seekable_stream_encoder_set_streamable_subset(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_do_mid_side_stereo(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_do_mid_side_stereo(). * * \default \c false * \param encoder An encoder instance to set. @@ -234,8 +202,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_streamable_subset(OggFLAC__Seeka */ FLAC__bool OggFLAC__seekable_stream_encoder_set_do_mid_side_stereo(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_loose_mid_side_stereo(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_loose_mid_side_stereo(). * * \default \c false * \param encoder An encoder instance to set. @@ -247,8 +215,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_do_mid_side_stereo(OggFLAC__Seek */ FLAC__bool OggFLAC__seekable_stream_encoder_set_loose_mid_side_stereo(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_channels(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_channels(). * * \default \c 2 * \param encoder An encoder instance to set. @@ -260,8 +228,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_loose_mid_side_stereo(OggFLAC__S */ FLAC__bool OggFLAC__seekable_stream_encoder_set_channels(OggFLAC__SeekableStreamEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_bits_per_sample(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_bits_per_sample(). * * \warning * Do not feed the encoder data that is wider than the value you @@ -277,8 +245,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_channels(OggFLAC__SeekableStream */ FLAC__bool OggFLAC__seekable_stream_encoder_set_bits_per_sample(OggFLAC__SeekableStreamEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_sample_rate(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_sample_rate(). * * \default \c 44100 * \param encoder An encoder instance to set. @@ -290,8 +258,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_bits_per_sample(OggFLAC__Seekabl */ FLAC__bool OggFLAC__seekable_stream_encoder_set_sample_rate(OggFLAC__SeekableStreamEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_blocksize(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_blocksize(). * * \default \c 1152 * \param encoder An encoder instance to set. @@ -303,8 +271,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_sample_rate(OggFLAC__SeekableStr */ FLAC__bool OggFLAC__seekable_stream_encoder_set_blocksize(OggFLAC__SeekableStreamEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_max_lpc_order(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_max_lpc_order(). * * \default \c 0 * \param encoder An encoder instance to set. @@ -316,8 +284,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_blocksize(OggFLAC__SeekableStrea */ FLAC__bool OggFLAC__seekable_stream_encoder_set_max_lpc_order(OggFLAC__SeekableStreamEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_qlp_coeff_precision(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_qlp_coeff_precision(). * * \note * In the current implementation, qlp_coeff_precision + bits_per_sample must @@ -333,8 +301,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_max_lpc_order(OggFLAC__SeekableS */ FLAC__bool OggFLAC__seekable_stream_encoder_set_qlp_coeff_precision(OggFLAC__SeekableStreamEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(). * * \default \c false * \param encoder An encoder instance to set. @@ -346,8 +314,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_qlp_coeff_precision(OggFLAC__See */ FLAC__bool OggFLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_do_escape_coding(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_do_escape_coding(). * * \default \c false * \param encoder An encoder instance to set. @@ -359,8 +327,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(OggFLAC */ FLAC__bool OggFLAC__seekable_stream_encoder_set_do_escape_coding(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_do_exhaustive_model_search(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_do_exhaustive_model_search(). * * \default \c false * \param encoder An encoder instance to set. @@ -372,8 +340,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_do_escape_coding(OggFLAC__Seekab */ FLAC__bool OggFLAC__seekable_stream_encoder_set_do_exhaustive_model_search(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_min_residual_partition_order(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_min_residual_partition_order(). * * \default \c 0 * \param encoder An encoder instance to set. @@ -385,8 +353,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_do_exhaustive_model_search(OggFL */ FLAC__bool OggFLAC__seekable_stream_encoder_set_min_residual_partition_order(OggFLAC__SeekableStreamEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_max_residual_partition_order(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_max_residual_partition_order(). * * \default \c 0 * \param encoder An encoder instance to set. @@ -398,8 +366,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_min_residual_partition_order(Ogg */ FLAC__bool OggFLAC__seekable_stream_encoder_set_max_residual_partition_order(OggFLAC__SeekableStreamEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_rice_parameter_search_dist(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_rice_parameter_search_dist(). * * \default \c 0 * \param encoder An encoder instance to set. @@ -411,8 +379,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_max_residual_partition_order(Ogg */ FLAC__bool OggFLAC__seekable_stream_encoder_set_rice_parameter_search_dist(OggFLAC__SeekableStreamEncoder *encoder, unsigned value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_total_samples_estimate(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_total_samples_estimate(). * * \default \c 0 * \param encoder An encoder instance to set. @@ -424,8 +392,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_rice_parameter_search_dist(OggFL */ FLAC__bool OggFLAC__seekable_stream_encoder_set_total_samples_estimate(OggFLAC__SeekableStreamEncoder *encoder, FLAC__uint64 value); -/** This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_metadata(). +/** This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_metadata(). * * \note * The decoder instance \b will modify the first \c SEEKTABLE block @@ -464,8 +432,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_metadata(OggFLAC__SeekableStream FLAC__bool OggFLAC__seekable_stream_encoder_set_seek_callback(OggFLAC__SeekableStreamEncoder *encoder, OggFLAC__SeekableStreamEncoderSeekCallback value); /** Set the write callback. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_set_write_callback(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_set_write_callback(). * * \note * The callback is mandatory and must be set before initialization. @@ -505,34 +473,48 @@ FLAC__bool OggFLAC__seekable_stream_encoder_set_client_data(OggFLAC__SeekableStr */ OggFLAC__SeekableStreamEncoderState OggFLAC__seekable_stream_encoder_get_state(const OggFLAC__SeekableStreamEncoder *encoder); -/** Get the state of the underlying stream encoder. +/** Get the state of the underlying FLAC seekable stream encoder. * Useful when the seekable stream encoder state is - * \c OggFLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR. + * \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_SEEKABLE_STREAM_ENCODER_ERROR. * * \param encoder An encoder instance to query. * \assert * \code encoder != NULL \endcode - * \retval OggFLAC__StreamEncoderState - * The stream encoder state. + * \retval FLAC__SeekableStreamEncoderState + * The FLAC seekable stream encoder state. */ -OggFLAC__StreamEncoderState OggFLAC__seekable_stream_encoder_get_stream_encoder_state(const OggFLAC__SeekableStreamEncoder *encoder); +FLAC__SeekableStreamEncoderState OggFLAC__seekable_stream_encoder_get_FLAC_seekable_stream_encoder_state(const OggFLAC__SeekableStreamEncoder *encoder); -/** Get the state of the underlying stream encoder's verify decoder. +/** Get the state of the underlying FLAC seekable stream encoder's stream encoder. * Useful when the seekable stream encoder state is - * \c OggFLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the - * stream encoder state is \c OggFLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. + * \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_SEEKABLE_STREAM_ENCODER_ERROR and the + * FLAC seekable stream encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR * * \param encoder An encoder instance to query. * \assert * \code encoder != NULL \endcode - * \retval OggFLAC__StreamEncoderState - * The stream encoder state. + * \retval FLAC__StreamEncoderState + * The FLAC stream encoder state. */ -OggFLAC__StreamDecoderState OggFLAC__seekable_stream_encoder_get_verify_decoder_state(const OggFLAC__SeekableStreamEncoder *encoder); +FLAC__StreamEncoderState OggFLAC__seekable_stream_encoder_get_FLAC_stream_encoder_state(const OggFLAC__SeekableStreamEncoder *encoder); + +/** Get the state of the underlying FLAC seekable stream encoder's verify decoder. + * Useful when the seekable stream encoder state is + * \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_SEEKABLE_STREAM_ENCODER_ERROR and the + * FLAC seekable stream encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR + * and the stream encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval OggFLAC__StreamDecoderState + * The FLAC verify decoder state. + */ +FLAC__StreamDecoderState OggFLAC__seekable_stream_encoder_get_verify_decoder_state(const OggFLAC__SeekableStreamEncoder *encoder); /** Get the "verify" flag. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_verify(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_verify(). * * \param encoder An encoder instance to query. * \assert @@ -543,8 +525,8 @@ OggFLAC__StreamDecoderState OggFLAC__seekable_stream_encoder_get_verify_decoder_ FLAC__bool OggFLAC__seekable_stream_encoder_get_verify(const OggFLAC__SeekableStreamEncoder *encoder); /** Get the "streamable subset" flag. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_streamable_subset(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_streamable_subset(). * * \param encoder An encoder instance to query. * \assert @@ -555,8 +537,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_get_verify(const OggFLAC__SeekableSt FLAC__bool OggFLAC__seekable_stream_encoder_get_streamable_subset(const OggFLAC__SeekableStreamEncoder *encoder); /** Get the "mid/side stereo coding" flag. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_do_mid_side_stereo(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_do_mid_side_stereo(). * * \param encoder An encoder instance to query. * \assert @@ -567,8 +549,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_get_streamable_subset(const OggFLAC_ FLAC__bool OggFLAC__seekable_stream_encoder_get_do_mid_side_stereo(const OggFLAC__SeekableStreamEncoder *encoder); /** Get the "adaptive mid/side switching" flag. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_loose_mid_side_stereo(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_loose_mid_side_stereo(). * * \param encoder An encoder instance to query. * \assert @@ -579,8 +561,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_get_do_mid_side_stereo(const OggFLAC FLAC__bool OggFLAC__seekable_stream_encoder_get_loose_mid_side_stereo(const OggFLAC__SeekableStreamEncoder *encoder); /** Get the number of input channels being processed. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_channels(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_channels(). * * \param encoder An encoder instance to query. * \assert @@ -591,8 +573,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_get_loose_mid_side_stereo(const OggF unsigned OggFLAC__seekable_stream_encoder_get_channels(const OggFLAC__SeekableStreamEncoder *encoder); /** Get the input sample resolution setting. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_bits_per_sample(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_bits_per_sample(). * * \param encoder An encoder instance to query. * \assert @@ -603,8 +585,8 @@ unsigned OggFLAC__seekable_stream_encoder_get_channels(const OggFLAC__SeekableSt unsigned OggFLAC__seekable_stream_encoder_get_bits_per_sample(const OggFLAC__SeekableStreamEncoder *encoder); /** Get the input sample rate setting. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_sample_rate(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_sample_rate(). * * \param encoder An encoder instance to query. * \assert @@ -615,8 +597,8 @@ unsigned OggFLAC__seekable_stream_encoder_get_bits_per_sample(const OggFLAC__See unsigned OggFLAC__seekable_stream_encoder_get_sample_rate(const OggFLAC__SeekableStreamEncoder *encoder); /** Get the blocksize setting. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_blocksize(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_blocksize(). * * \param encoder An encoder instance to query. * \assert @@ -627,8 +609,8 @@ unsigned OggFLAC__seekable_stream_encoder_get_sample_rate(const OggFLAC__Seekabl unsigned OggFLAC__seekable_stream_encoder_get_blocksize(const OggFLAC__SeekableStreamEncoder *encoder); /** Get the maximum LPC order setting. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_max_lpc_order(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_max_lpc_order(). * * \param encoder An encoder instance to query. * \assert @@ -639,8 +621,8 @@ unsigned OggFLAC__seekable_stream_encoder_get_blocksize(const OggFLAC__SeekableS unsigned OggFLAC__seekable_stream_encoder_get_max_lpc_order(const OggFLAC__SeekableStreamEncoder *encoder); /** Get the quantized linear predictor coefficient precision setting. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_qlp_coeff_precision(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_qlp_coeff_precision(). * * \param encoder An encoder instance to query. * \assert @@ -651,8 +633,8 @@ unsigned OggFLAC__seekable_stream_encoder_get_max_lpc_order(const OggFLAC__Seeka unsigned OggFLAC__seekable_stream_encoder_get_qlp_coeff_precision(const OggFLAC__SeekableStreamEncoder *encoder); /** Get the qlp coefficient precision search flag. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_do_qlp_coeff_prec_search(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(). * * \param encoder An encoder instance to query. * \assert @@ -663,8 +645,8 @@ unsigned OggFLAC__seekable_stream_encoder_get_qlp_coeff_precision(const OggFLAC_ FLAC__bool OggFLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__SeekableStreamEncoder *encoder); /** Get the "escape coding" flag. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_do_escape_coding(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_do_escape_coding(). * * \param encoder An encoder instance to query. * \assert @@ -675,8 +657,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(const O FLAC__bool OggFLAC__seekable_stream_encoder_get_do_escape_coding(const OggFLAC__SeekableStreamEncoder *encoder); /** Get the exhaustive model search flag. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_do_exhaustive_model_search(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_do_exhaustive_model_search(). * * \param encoder An encoder instance to query. * \assert @@ -687,8 +669,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_get_do_escape_coding(const OggFLAC__ FLAC__bool OggFLAC__seekable_stream_encoder_get_do_exhaustive_model_search(const OggFLAC__SeekableStreamEncoder *encoder); /** Get the minimum residual partition order setting. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_min_residual_partition_order(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_min_residual_partition_order(). * * \param encoder An encoder instance to query. * \assert @@ -699,8 +681,8 @@ FLAC__bool OggFLAC__seekable_stream_encoder_get_do_exhaustive_model_search(const unsigned OggFLAC__seekable_stream_encoder_get_min_residual_partition_order(const OggFLAC__SeekableStreamEncoder *encoder); /** Get maximum residual partition order setting. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_max_residual_partition_order(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_max_residual_partition_order(). * * \param encoder An encoder instance to query. * \assert @@ -711,8 +693,8 @@ unsigned OggFLAC__seekable_stream_encoder_get_min_residual_partition_order(const unsigned OggFLAC__seekable_stream_encoder_get_max_residual_partition_order(const OggFLAC__SeekableStreamEncoder *encoder); /** Get the Rice parameter search distance setting. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_rice_parameter_search_dist(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_rice_parameter_search_dist(). * * \param encoder An encoder instance to query. * \assert @@ -723,8 +705,8 @@ unsigned OggFLAC__seekable_stream_encoder_get_max_residual_partition_order(const unsigned OggFLAC__seekable_stream_encoder_get_rice_parameter_search_dist(const OggFLAC__SeekableStreamEncoder *encoder); /** Get the previously set estimate of the total samples to be encoded. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_get_total_samples_estimate(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_get_total_samples_estimate(). * * \param encoder An encoder instance to query. * \assert @@ -762,7 +744,7 @@ OggFLAC__SeekableStreamEncoderState OggFLAC__seekable_stream_encoder_init(OggFLA * In the event of a prematurely-terminated encode, it is not strictly * necessary to call this immediately before OggFLAC__seekable_stream_encoder_delete() * but it is good practice to match every OggFLAC__seekable_stream_encoder_init() - * with a OggFLAC__seekable_stream_encoder_finish(). + * with an OggFLAC__seekable_stream_encoder_finish(). * * \param encoder An uninitialized encoder instance. * \assert @@ -771,8 +753,8 @@ OggFLAC__SeekableStreamEncoderState OggFLAC__seekable_stream_encoder_init(OggFLA void OggFLAC__seekable_stream_encoder_finish(OggFLAC__SeekableStreamEncoder *encoder); /** Submit data for encoding. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_process(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_process(). * * \param encoder An initialized encoder instance in the OK state. * \param buffer An array of pointers to each channel's signal. @@ -788,8 +770,8 @@ void OggFLAC__seekable_stream_encoder_finish(OggFLAC__SeekableStreamEncoder *enc FLAC__bool OggFLAC__seekable_stream_encoder_process(OggFLAC__SeekableStreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples); /** Submit data for encoding. - * This is inherited from OggFLAC__StreamEncoder; see - * OggFLAC__stream_encoder_process_interleaved(). + * This is inherited from FLAC__SeekableStreamEncoder; see + * FLAC__seekable_stream_encoder_process_interleaved(). * * \param encoder An initialized encoder instance in the OK state. * \param buffer An array of channel-interleaved data (see above). diff --git a/include/OggFLAC/stream_decoder.h b/include/OggFLAC/stream_decoder.h index 182000ec..08f24507 100644 --- a/include/OggFLAC/stream_decoder.h +++ b/include/OggFLAC/stream_decoder.h @@ -43,22 +43,9 @@ extern "C" { * \brief * This module describes the three decoder layers provided by libOggFLAC. * - * For decoding OggFLAC streams, libOggFLAC provides three layers of access. The - * lowest layer is non-seekable stream-level decoding, the next is seekable - * stream-level decoding, and the highest layer is file-level decoding. The - * interfaces are described in the \link oggflac_stream_decoder stream decoder - * \endlink, \link oggflac_seekable_stream_decoder seekable stream decoder - * \endlink, and \link oggflac_file_decoder file decoder \endlink modules - * respectively. Typically you will choose the highest layer that your input - * source will support. - * - * The stream decoder relies on callbacks for all input and output and has no - * provisions for seeking. The seekable stream decoder wraps the stream - * decoder and exposes functions for seeking. However, you must provide - * extra callbacks for seek-related operations on your stream, like seek and - * tell. The file decoder wraps the seekable stream decoder and supplies - * most of the callbacks internally, simplifying the processing of standard - * files. + * libOggFLAC provides the same three layers of access as libFLAC and the + * interface is identical. See the \link flac_decoder FLAC decoder module + * \endlink for full documentation. */ /** \defgroup oggflac_stream_decoder OggFLAC/stream_decoder.h: stream decoder interface @@ -68,143 +55,33 @@ extern "C" { * This module contains the functions which implement the stream * decoder. * - * The basic usage of this decoder is as follows: - * - The program creates an instance of a decoder using - * OggFLAC__stream_decoder_new(). - * - The program overrides the default settings and sets callbacks for - * reading, writing, error reporting, and metadata reporting using - * OggFLAC__stream_decoder_set_*() functions. - * - The program initializes the instance to validate the settings and - * prepare for decoding using OggFLAC__stream_decoder_init(). - * - The program calls the OggFLAC__stream_decoder_process_*() functions - * to decode data, which subsequently calls the callbacks. - * - The program finishes the decoding with OggFLAC__stream_decoder_finish(), - * which flushes the input and output and resets the decoder to the - * uninitialized state. - * - The instance may be used again or deleted with - * OggFLAC__stream_decoder_delete(). - * - * In more detail, the program will create a new instance by calling - * OggFLAC__stream_decoder_new(), then call OggFLAC__stream_decoder_set_*() - * functions to set the callbacks and client data, and call - * OggFLAC__stream_decoder_init(). The required callbacks are: - * - * - Read callback - This function will be called when the decoder needs - * more input data. The address of the buffer to be filled is supplied, - * along with the number of bytes the buffer can hold. The callback may - * choose to supply less data and modify the byte count but must be careful - * not to overflow the buffer. The callback then returns a status code - * chosen from OggFLAC__StreamDecoderReadStatus. - * - Write callback - This function will be called when the decoder has - * decoded a single frame of data. The decoder will pass the frame - * metadata as well as an array of pointers (one for each channel) - * pointing to the decoded audio. - * - Metadata callback - This function will be called when the decoder has - * decoded a metadata block. There will always be one STREAMINFO block - * per stream, followed by zero or more other metadata blocks. These will - * be supplied by the decoder in the same order as they appear in the - * stream and always before the first audio frame (i.e. write callback). - * The metadata block that is passed in must not be modified, and it - * doesn't live beyond the callback, so you should make a copy of it with - * OggFLAC__metadata_object_clone() if you will need it elsewhere. Since - * metadata blocks can potentially be large, by default the decoder only - * calls the metadata callback for the STREAMINFO block; you can instruct - * the decoder to pass or filter other blocks with - * OggFLAC__stream_decoder_set_metadata_*() calls. - * - Error callback - This function will be called whenever an error occurs - * during decoding. - * - * Once the decoder is initialized, your program will call one of several - * functions to start the decoding process: - * - * - OggFLAC__stream_decoder_process_single() - Tells the decoder to process at - * most one metadata block or audio frame and return, calling either the - * metadata callback or write callback, respectively, once. If the decoder - * loses sync it will return with only the error callback being called. - * - OggFLAC__stream_decoder_process_until_end_of_metadata() - Tells the decoder - * to process the stream from the current location and stop upon reaching - * the first audio frame. The user will get one metadata, write, or error - * callback per metadata block, audio frame, or sync error, respectively. - * - OggFLAC__stream_decoder_process_until_end_of_stream() - Tells the decoder - * to process the stream from the current location until the read callback - * returns OggFLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM or - * OggFLAC__STREAM_DECODER_READ_STATUS_ABORT. The user will get one metadata, - * write, or error callback per metadata block, audio frame, or sync error, - * respectively. - * - * When the decoder has finished decoding (normally or through an abort), - * the instance is finished by calling OggFLAC__stream_decoder_finish(), which - * ensures the decoder is in the correct state and frees memory. Then the - * instance may be deleted with OggFLAC__stream_decoder_delete() or initialized - * again to decode another stream. - * - * Note that the stream decoder has no real concept of stream position, it - * just converts data. To seek within a stream the callbacks have only to - * flush the decoder using OggFLAC__stream_decoder_flush() and start feeding - * data from the new position through the read callback. The seekable - * stream decoder does just this. - * - * The OggFLAC__stream_decoder_set_metadata_*() functions deserve special - * attention. By default, the decoder only calls the metadata_callback for - * the STREAMINFO block. These functions allow you to tell the decoder - * explicitly which blocks to parse and return via the metadata_callback - * and/or which to skip. Use a OggFLAC__stream_decoder_respond_all(), - * OggFLAC__stream_decoder_ignore() ... or OggFLAC__stream_decoder_ignore_all(), - * OggFLAC__stream_decoder_respond() ... sequence to exactly specify which - * blocks to return. Remember that some metadata blocks can be big so - * filtering out the ones you don't use can reduce the memory requirements - * of the decoder. Also note the special forms - * OggFLAC__stream_decoder_respond_application(id) and - * OggFLAC__stream_decoder_ignore_application(id) for filtering APPLICATION - * blocks based on the application ID. - * - * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but - * they still can legally be filtered from the metadata_callback. - * - * \note - * The "set" functions may only be called when the decoder is in the - * state OggFLAC__STREAM_DECODER_UNINITIALIZED, i.e. after - * OggFLAC__stream_decoder_new() or OggFLAC__stream_decoder_finish(), but - * before OggFLAC__stream_decoder_init(). If this is the case they will - * return \c true, otherwise \c false. - * - * \note - * OggFLAC__stream_decoder_finish() resets all settings to the constructor - * defaults, including the callbacks. + * The interface here is identical to FLAC's stream decoder. See the + * defaults, including the callbacks. See the \link flac_stream_decoder + * FLAC stream decoder module \endlink for full documentation. * * \{ */ -/** State values for a OggFLAC__StreamDecoder +/** State values for an OggFLAC__StreamDecoder * * The decoder's state can be obtained by calling OggFLAC__stream_decoder_get_state(). */ typedef enum { - OggFLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0, - /**< The decoder is ready to search for metadata. */ + OggFLAC__STREAM_DECODER_OK = 0, + /**< The decoder is in the normal OK state. */ - OggFLAC__STREAM_DECODER_READ_METADATA, - /**< The decoder is ready to or is in the process of reading metadata. */ + OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR, + /**< An error occurred in the underlying FLAC stream decoder; + * check OggFLAC__stream_decoder_get_FLAC_stream_decoder_state(). + */ - OggFLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC, - /**< The decoder is ready to or is in the process of searching for the frame sync code. */ - - OggFLAC__STREAM_DECODER_READ_FRAME, - /**< The decoder is ready to or is in the process of reading a frame. */ - - OggFLAC__STREAM_DECODER_END_OF_STREAM, - /**< The decoder has reached the end of the stream. */ - - OggFLAC__STREAM_DECODER_ABORTED, - /**< The decoder was aborted by the read callback. */ - - OggFLAC__STREAM_DECODER_UNPARSEABLE_STREAM, - /**< The decoder encountered reserved fields in use in the stream. */ + OggFLAC__STREAM_DECODER_INVALID_CALLBACK, + /**< The decoder was initialized before setting all the required callbacks. */ OggFLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR, - /**< An error occurred allocating memory. */ + /**< Memory allocation failed. */ OggFLAC__STREAM_DECODER_ALREADY_INITIALIZED, /**< OggFLAC__stream_decoder_init() was called when the decoder was @@ -212,88 +89,19 @@ typedef enum { * OggFLAC__stream_decoder_finish() was not called. */ - OggFLAC__STREAM_DECODER_INVALID_CALLBACK, - /**< OggFLAC__stream_decoder_init() was called without all callbacks being set. */ - OggFLAC__STREAM_DECODER_UNINITIALIZED /**< The decoder is in the uninitialized state. */ } OggFLAC__StreamDecoderState; -/** Maps a OggFLAC__StreamDecoderState to a C string. +/** Maps an OggFLAC__StreamDecoderState to a C string. * - * Using a OggFLAC__StreamDecoderState as the index to this array + * Using an OggFLAC__StreamDecoderState as the index to this array * will give the string equivalent. The contents should not be modified. */ extern const char * const OggFLAC__StreamDecoderStateString[]; -/** Return values for the OggFLAC__StreamDecoder read callback. - */ -typedef enum { - - OggFLAC__STREAM_DECODER_READ_STATUS_CONTINUE, - /**< The read was OK and decoding can continue. */ - - OggFLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM, - /**< The read was attempted at the end of the stream. */ - - OggFLAC__STREAM_DECODER_READ_STATUS_ABORT - /**< An unrecoverable error occurred. The decoder will return from the process call. */ - -} OggFLAC__StreamDecoderReadStatus; - -/** Maps a OggFLAC__StreamDecoderReadStatus to a C string. - * - * Using a OggFLAC__StreamDecoderReadStatus as the index to this array - * will give the string equivalent. The contents should not be modified. - */ -extern const char * const OggFLAC__StreamDecoderReadStatusString[]; - - -/** Return values for the OggFLAC__StreamDecoder write callback. - */ -typedef enum { - - OggFLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE, - /**< The write was OK and decoding can continue. */ - - OggFLAC__STREAM_DECODER_WRITE_STATUS_ABORT - /**< An unrecoverable error occurred. The decoder will return from the process call. */ - -} OggFLAC__StreamDecoderWriteStatus; - -/** Maps a OggFLAC__StreamDecoderWriteStatus to a C string. - * - * Using a OggFLAC__StreamDecoderWriteStatus as the index to this array - * will give the string equivalent. The contents should not be modified. - */ -extern const char * const OggFLAC__StreamDecoderWriteStatusString[]; - - -/** Possible values passed in to the OggFLAC__StreamDecoder error callback. - */ -typedef enum { - - OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC, - /**< An error in the stream caused the decoder to lose synchronization. */ - - OggFLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER, - /**< The decoder encountered a corrupted frame header. */ - - OggFLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH - /**< The frame's data did not match the CRC in the footer. */ - -} OggFLAC__StreamDecoderErrorStatus; - -/** Maps a OggFLAC__StreamDecoderErrorStatus to a C string. - * - * Using a OggFLAC__StreamDecoderErrorStatus as the index to this array - * will give the string equivalent. The contents should not be modified. - */ -extern const char * const OggFLAC__StreamDecoderErrorStatusString[]; - - /*********************************************************************** * * class OggFLAC__StreamDecoder @@ -311,10 +119,10 @@ typedef struct { struct OggFLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */ } OggFLAC__StreamDecoder; -typedef OggFLAC__StreamDecoderReadStatus (*OggFLAC__StreamDecoderReadCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data); -typedef OggFLAC__StreamDecoderWriteStatus (*OggFLAC__StreamDecoderWriteCallback)(const OggFLAC__StreamDecoder *decoder, const OggFLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data); -typedef void (*OggFLAC__StreamDecoderMetadataCallback)(const OggFLAC__StreamDecoder *decoder, const OggFLAC__StreamMetadata *metadata, void *client_data); -typedef void (*OggFLAC__StreamDecoderErrorCallback)(const OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderErrorStatus status, void *client_data); +typedef FLAC__StreamDecoderReadStatus (*OggFLAC__StreamDecoderReadCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data); +typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__StreamDecoderWriteCallback)(const OggFLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data); +typedef void (*OggFLAC__StreamDecoderMetadataCallback)(const OggFLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data); +typedef void (*OggFLAC__StreamDecoderErrorCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data); /*********************************************************************** @@ -348,12 +156,7 @@ void OggFLAC__stream_decoder_delete(OggFLAC__StreamDecoder *decoder); ***********************************************************************/ /** Set the read callback. - * The supplied function will be called when the decoder needs more input - * data. The address of the buffer to be filled is supplied, along with - * the number of bytes the buffer can hold. The callback may choose to - * supply less data and modify the byte count but must be careful not to - * overflow the buffer. The callback then returns a status code chosen - * from OggFLAC__StreamDecoderReadStatus. + * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_read_callback() * * \note * The callback is mandatory and must be set before initialization. @@ -370,10 +173,7 @@ void OggFLAC__stream_decoder_delete(OggFLAC__StreamDecoder *decoder); FLAC__bool OggFLAC__stream_decoder_set_read_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderReadCallback); /** Set the write callback. - * The supplied function will be called when the decoder has decoded a - * single frame of data. The decoder will pass the frame metadata as - * well as an array of pointers (one for each channel) pointing to the - * decoded audio. + * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_write_callback() * * \note * The callback is mandatory and must be set before initialization. @@ -390,18 +190,7 @@ FLAC__bool OggFLAC__stream_decoder_set_read_callback(OggFLAC__StreamDecoder *dec FLAC__bool OggFLAC__stream_decoder_set_write_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderWriteCallback); /** Set the metadata callback. - * The supplied function will be called when the decoder has decoded a - * metadata block. There will always be one STREAMINFO block per stream, - * followed by zero or more other metadata blocks. These will be supplied - * by the decoder in the same order as they appear in the stream and always - * before the first audio frame (i.e. write callback). The metadata block - * that is passed in must not be modified, and it doesn't live beyond the - * callback, so you should make a copy of it with - * OggFLAC__metadata_object_clone() if you will need it elsewhere. Since - * metadata blocks can potentially be large, by default the decoder only - * calls the metadata callback for the STREAMINFO block; you can instruct - * the decoder to pass or filter other blocks with - * OggFLAC__stream_decoder_set_metadata_*() calls. + * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_callback() * * \note * The callback is mandatory and must be set before initialization. @@ -418,8 +207,7 @@ FLAC__bool OggFLAC__stream_decoder_set_write_callback(OggFLAC__StreamDecoder *de FLAC__bool OggFLAC__stream_decoder_set_metadata_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderMetadataCallback); /** Set the error callback. - * The supplied function will be called whenever an error occurs during - * decoding. + * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_error_callback() * * \note * The callback is mandatory and must be set before initialization. @@ -450,6 +238,7 @@ FLAC__bool OggFLAC__stream_decoder_set_error_callback(OggFLAC__StreamDecoder *de FLAC__bool OggFLAC__stream_decoder_set_client_data(OggFLAC__StreamDecoder *decoder, void *value); /** Direct the decoder to pass on all metadata blocks of type \a type. + * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond() * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -465,6 +254,7 @@ FLAC__bool OggFLAC__stream_decoder_set_metadata_respond(OggFLAC__StreamDecoder * /** Direct the decoder to pass on all APPLICATION metadata blocks of the * given \a id. + * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond_application() * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -479,6 +269,7 @@ FLAC__bool OggFLAC__stream_decoder_set_metadata_respond(OggFLAC__StreamDecoder * FLAC__bool OggFLAC__stream_decoder_set_metadata_respond_application(OggFLAC__StreamDecoder *decoder, const FLAC__byte id[4]); /** Direct the decoder to pass on all metadata blocks of any type. + * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond_all() * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -491,6 +282,7 @@ FLAC__bool OggFLAC__stream_decoder_set_metadata_respond_application(OggFLAC__Str FLAC__bool OggFLAC__stream_decoder_set_metadata_respond_all(OggFLAC__StreamDecoder *decoder); /** Direct the decoder to filter out all metadata blocks of type \a type. + * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore() * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -506,6 +298,7 @@ FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore(OggFLAC__StreamDecoder *d /** Direct the decoder to filter out all APPLICATION metadata blocks of * the given \a id. + * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore_application() * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -520,6 +313,7 @@ FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore(OggFLAC__StreamDecoder *d FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore_application(OggFLAC__StreamDecoder *decoder, const FLAC__byte id[4]); /** Direct the decoder to filter out all metadata blocks of any type. + * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore_all() * * \default By default, only the \c STREAMINFO block is returned via the * metadata callback. @@ -541,9 +335,19 @@ FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore_all(OggFLAC__StreamDecode */ OggFLAC__StreamDecoderState OggFLAC__stream_decoder_get_state(const OggFLAC__StreamDecoder *decoder); -/** Get the current number of channels in the stream being decoded. - * Will only be valid after decoding has started and will contain the - * value from the most recently decoded frame header. +/** Get the state of the underlying FLAC stream decoder. + * Useful when the stream decoder state is + * \c OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR. + * + * \param decoder An decoder instance to query. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__StreamDecoderState + * The FLAC stream decoder state. + */ +FLAC__StreamDecoderState OggFLAC__stream_decoder_get_FLAC_stream_decoder_state(const OggFLAC__StreamDecoder *decoder); + +/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_channels() * * \param decoder A decoder instance to query. * \assert @@ -553,9 +357,7 @@ OggFLAC__StreamDecoderState OggFLAC__stream_decoder_get_state(const OggFLAC__Str */ unsigned OggFLAC__stream_decoder_get_channels(const OggFLAC__StreamDecoder *decoder); -/** Get the current channel assignment in the stream being decoded. - * Will only be valid after decoding has started and will contain the - * value from the most recently decoded frame header. +/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_channel_assignment() * * \param decoder A decoder instance to query. * \assert @@ -565,9 +367,7 @@ unsigned OggFLAC__stream_decoder_get_channels(const OggFLAC__StreamDecoder *deco */ OggFLAC__ChannelAssignment OggFLAC__stream_decoder_get_channel_assignment(const OggFLAC__StreamDecoder *decoder); -/** Get the current sample resolution in the stream being decoded. - * Will only be valid after decoding has started and will contain the - * value from the most recently decoded frame header. +/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_bits_per_sample() * * \param decoder A decoder instance to query. * \assert @@ -577,9 +377,7 @@ OggFLAC__ChannelAssignment OggFLAC__stream_decoder_get_channel_assignment(const */ unsigned OggFLAC__stream_decoder_get_bits_per_sample(const OggFLAC__StreamDecoder *decoder); -/** Get the current sample rate in Hz of the stream being decoded. - * Will only be valid after decoding has started and will contain the - * value from the most recently decoded frame header. +/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_sample_rate() * * \param decoder A decoder instance to query. * \assert @@ -589,9 +387,7 @@ unsigned OggFLAC__stream_decoder_get_bits_per_sample(const OggFLAC__StreamDecode */ unsigned OggFLAC__stream_decoder_get_sample_rate(const OggFLAC__StreamDecoder *decoder); -/** Get the current blocksize of the stream being decoded. - * Will only be valid after decoding has started and will contain the - * value from the most recently decoded frame header. +/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_blocksize() * * \param decoder A decoder instance to query. * \assert @@ -605,14 +401,14 @@ unsigned OggFLAC__stream_decoder_get_blocksize(const OggFLAC__StreamDecoder *dec * Should be called after OggFLAC__stream_decoder_new() and * OggFLAC__stream_decoder_set_*() but before any of the * OggFLAC__stream_decoder_process_*() functions. Will set and return the - * decoder state, which will be OggFLAC__STREAM_DECODER_SEARCH_FOR_METADATA + * decoder state, which will be OggFLAC__STREAM_DECODER_OK * if initialization succeeded. * * \param decoder An uninitialized decoder instance. * \assert * \code decoder != NULL \endcode * \retval OggFLAC__StreamDecoderState - * \c OggFLAC__STREAM_DECODER_SEARCH_FOR_MEATADATA if initialization was + * \c OggFLAC__STREAM_DECODER_OK if initialization was * successful; see OggFLAC__StreamDecoderState for the meanings of other * return values. */ @@ -626,7 +422,7 @@ OggFLAC__StreamDecoderState OggFLAC__stream_decoder_init(OggFLAC__StreamDecoder * In the event of a prematurely-terminated decode, it is not strictly * necessary to call this immediately before OggFLAC__stream_decoder_delete() * but it is good practice to match every OggFLAC__stream_decoder_init() - * with a OggFLAC__stream_decoder_finish(). + * with an OggFLAC__stream_decoder_finish(). * * \param decoder An uninitialized decoder instance. * \assert @@ -634,9 +430,7 @@ OggFLAC__StreamDecoderState OggFLAC__stream_decoder_init(OggFLAC__StreamDecoder */ void OggFLAC__stream_decoder_finish(OggFLAC__StreamDecoder *decoder); -/** Flush the stream input. - * The decoder's input buffer will be cleared and the state set to - * \c OggFLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC. +/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_flush() * * \param decoder A decoder instance. * \assert @@ -647,12 +441,7 @@ void OggFLAC__stream_decoder_finish(OggFLAC__StreamDecoder *decoder); */ FLAC__bool OggFLAC__stream_decoder_flush(OggFLAC__StreamDecoder *decoder); -/** Reset the decoding process. - * The decoder's input buffer will be cleared and the state set to - * \c OggFLAC__STREAM_DECODER_SEARCH_FOR_METADATA. This is similar to - * OggFLAC__stream_decoder_finish() except that the settings are - * preserved; there is no need to call OggFLAC__stream_decoder_init() - * before decoding again. +/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_reset() * * \param decoder A decoder instance. * \assert @@ -664,25 +453,16 @@ FLAC__bool OggFLAC__stream_decoder_flush(OggFLAC__StreamDecoder *decoder); FLAC__bool OggFLAC__stream_decoder_reset(OggFLAC__StreamDecoder *decoder); /** Decode one metadata block or audio frame. - * This version instructs the decoder to decode a either a single metadata - * block or a single frame and stop, unless the callbacks return a fatal - * error or the read callback returns - * \c OggFLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM. - * - * As the decoder needs more input it will call the read callback. - * Depending on what was decoded, the metadata or write callback will be - * called with the decoded metadata block or audio frame, unless an error - * occurred. If the decoder loses sync it will call the error callback - * instead. + * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_single() * * \param decoder An initialized decoder instance in the state - * \c OggFLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC. + * \c OggFLAC__STREAM_DECODER_OK. * \assert * \code decoder != NULL \endcode - * \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC \endcode + * \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK \endcode * \retval FLAC__bool * \c false if any read or write error occurred (except - * \c OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false; + * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false; * in any case, check the decoder state with * OggFLAC__stream_decoder_get_state() to see what went wrong or to * check for lost synchronization (a sign of stream corruption). @@ -690,21 +470,13 @@ FLAC__bool OggFLAC__stream_decoder_reset(OggFLAC__StreamDecoder *decoder); FLAC__bool OggFLAC__stream_decoder_process_single(OggFLAC__StreamDecoder *decoder); /** Decode until the end of the metadata. - * This version instructs the decoder to decode from the current position - * and continue until all the metadata has been read, or until the - * callbacks return a fatal error or the read callback returns - * \c OggFLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM. - * - * As the decoder needs more input it will call the read callback. - * As each metadata block is decoded, the metadata callback will be called - * with the decoded metadata. If the decoder loses sync it will call the - * error callback. + * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_until_end_of_metadata() * * \param decoder An initialized decoder instance in the state - * \c OggFLAC__STREAM_DECODER_SEARCH_FOR_METADATA. + * \c OggFLAC__STREAM_DECODER_OK. * \assert * \code decoder != NULL \endcode - * \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode + * \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK \endcode * \retval FLAC__bool * \c false if any read or write error occurred (except * \c OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false; @@ -715,21 +487,13 @@ FLAC__bool OggFLAC__stream_decoder_process_single(OggFLAC__StreamDecoder *decode FLAC__bool OggFLAC__stream_decoder_process_until_end_of_metadata(OggFLAC__StreamDecoder *decoder); /** Decode until the end of the stream. - * This version instructs the decoder to decode from the current position - * and continue until the end of stream (the read callback returns - * \c OggFLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the - * callbacks return a fatal error. - * - * As the decoder needs more input it will call the read callback. - * As each metadata block and frame is decoded, the metadata or write - * callback will be called with the decoded metadata or frame. If the - * decoder loses sync it will call the error callback. + * This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_until_end_of_stream() * * \param decoder An initialized decoder instance in the state - * \c OggFLAC__STREAM_DECODER_SEARCH_FOR_METADATA. + * \c OggFLAC__STREAM_DECODER_OK. * \assert * \code decoder != NULL \endcode - * \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode + * \code OggFLAC__stream_decoder_get_state(decoder) == OggFLAC__STREAM_DECODER_OK \endcode * \retval FLAC__bool * \c false if any read or write error occurred (except * \c OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c false; diff --git a/include/OggFLAC/stream_encoder.h b/include/OggFLAC/stream_encoder.h index 70f742fc..5e4c45be 100644 --- a/include/OggFLAC/stream_encoder.h +++ b/include/OggFLAC/stream_encoder.h @@ -58,11 +58,12 @@ extern "C" { * The interface here is identical to FLAC's stream encoder. See the * defaults, including the callbacks. See the \link flac_stream_encoder * FLAC stream encoder module \endlink for full documentation. + * * \{ */ -/** State values for a OggFLAC__StreamEncoder +/** State values for an OggFLAC__StreamEncoder * * The encoder's state can be obtained by calling OggFLAC__stream_encoder_get_state(). */ @@ -71,9 +72,9 @@ typedef enum { OggFLAC__STREAM_ENCODER_OK = 0, /**< The encoder is in the normal OK state. */ - OggFLAC__STREAM_ENCODER_FLAC_ENCODER_ERROR, + OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR, /**< An error occurred in the underlying FLAC stream encoder; - * check OggFLAC__stream_encoder_get_FLAC_encoder_state(). + * check OggFLAC__stream_encoder_get_FLAC_stream_encoder_state(). */ OggFLAC__STREAM_ENCODER_INVALID_CALLBACK, @@ -95,30 +96,11 @@ typedef enum { /** Maps an OggFLAC__StreamEncoderState to a C string. * - * Using a OggFLAC__StreamEncoderState as the index to this array + * Using an OggFLAC__StreamEncoderState as the index to this array * will give the string equivalent. The contents should not be modified. */ extern const char * const OggFLAC__StreamEncoderStateString[]; -/** Return values for the OggFLAC__StreamEncoder write callback. - */ -typedef enum { - - OggFLAC__STREAM_ENCODER_WRITE_STATUS_OK = 0, - /**< The write was OK and encoding can continue. */ - - OggFLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR - /**< An unrecoverable error occurred. The encoder will return from the process call. */ - -} OggFLAC__StreamEncoderWriteStatus; - -/** Maps an OggFLAC__StreamEncoderWriteStatus to a C string. - * - * Using a OggFLAC__StreamEncoderWriteStatus as the index to this array - * will give the string equivalent. The contents should not be modified. - */ -extern const char * const OggFLAC__StreamEncoderWriteStatusString[]; - /*********************************************************************** * @@ -139,7 +121,6 @@ typedef struct { /*@@@@ document: */ typedef OggFLAC__StreamEncoderWriteStatus (*OggFLAC__StreamEncoderWriteCallback)(const OggFLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data); -typedef void (*OggFLAC__StreamEncoderMetadataCallback)(const OggFLAC__StreamEncoder *encoder, const OggFLAC__StreamMetadata *metadata, void *client_data); /*********************************************************************** @@ -165,206 +146,534 @@ OggFLAC__StreamEncoder *OggFLAC__stream_encoder_new(); */ void OggFLAC__stream_encoder_delete(OggFLAC__StreamEncoder *encoder); + /*********************************************************************** * * Public class method prototypes * ***********************************************************************/ -/** Inherited from FLAC__stream_encoder_set_verify() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_verify() + * + * \default \c false + * \param encoder An encoder instance to set. + * \param value Flag value (see above). + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_verify(OggFLAC__StreamEncoder *encoder, FLAC__bool value); -/** Inherited from FLAC__stream_encoder_set_streamable_subset() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_streamable_subset() + * + * \default \c true + * \param encoder An encoder instance to set. + * \param value Flag value (see above). + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_streamable_subset(OggFLAC__StreamEncoder *encoder, FLAC__bool value); -/** Inherited from FLAC__stream_encoder_set_do_mid_side_stereo() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_mid_side_stereo() + * + * \default \c false + * \param encoder An encoder instance to set. + * \param value Flag value (see above). + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_do_mid_side_stereo(OggFLAC__StreamEncoder *encoder, FLAC__bool value); -/** Inherited from FLAC__stream_encoder_set_loose_mid_side_stereo() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_loose_mid_side_stereo() + * + * \default \c false + * \param encoder An encoder instance to set. + * \param value Flag value (see above). + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_loose_mid_side_stereo(OggFLAC__StreamEncoder *encoder, FLAC__bool value); -/** Inherited from FLAC__stream_encoder_set_channels() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_channels() + * + * \default \c 2 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_channels(OggFLAC__StreamEncoder *encoder, unsigned value); -/** Inherited from FLAC__stream_encoder_set_bits_per_sample() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_bits_per_sample() + * + * \default \c 16 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_bits_per_sample(OggFLAC__StreamEncoder *encoder, unsigned value); -/** Inherited from FLAC__stream_encoder_set_sample_rate() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_sample_rate() + * + * \default \c 44100 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_sample_rate(OggFLAC__StreamEncoder *encoder, unsigned value); -/** Inherited from FLAC__stream_encoder_set_blocksize() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_blocksize() + * + * \default \c 1152 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_blocksize(OggFLAC__StreamEncoder *encoder, unsigned value); -/** Inherited from FLAC__stream_encoder_set_max_lpc_order() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_lpc_order() + * + * \default \c 0 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_max_lpc_order(OggFLAC__StreamEncoder *encoder, unsigned value); -/** Inherited from FLAC__stream_encoder_set_qlp_coeff_precision() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_precision() + * + * \default \c 0 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_qlp_coeff_precision(OggFLAC__StreamEncoder *encoder, unsigned value); -/** Inherited from FLAC__stream_encoder_set_do_qlp_coeff_prec_search() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_prec_search() + * + * \default \c false + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search(OggFLAC__StreamEncoder *encoder, FLAC__bool value); -/** Inherited from FLAC__stream_encoder_set_do_escape_coding() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_escape_coding() + * + * \default \c false + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_do_escape_coding(OggFLAC__StreamEncoder *encoder, FLAC__bool value); -/** Inherited from FLAC__stream_encoder_set_do_exhaustive_model_search() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_exhaustive_model_search() + * + * \default \c false + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_do_exhaustive_model_search(OggFLAC__StreamEncoder *encoder, FLAC__bool value); -/** Inherited from FLAC__stream_encoder_set_min_residual_partition_order() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_min_residual_partition_order() + * + * \default \c 0 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_min_residual_partition_order(OggFLAC__StreamEncoder *encoder, unsigned value); -/** Inherited from FLAC__stream_encoder_set_max_residual_partition_order() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_residual_partition_order() + * + * \default \c 0 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_max_residual_partition_order(OggFLAC__StreamEncoder *encoder, unsigned value); -/** Inherited from FLAC__stream_encoder_set_rice_parameter_search_dist() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_rice_parameter_search_dist() + * + * \default \c 0 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_rice_parameter_search_dist(OggFLAC__StreamEncoder *encoder, unsigned value); -/** Inherited from FLAC__stream_encoder_set_total_samples_estimate() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_total_samples_estimate() + * + * \default \c 0 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_total_samples_estimate(OggFLAC__StreamEncoder *encoder, FLAC__uint64 value); -/** Inherited from FLAC__stream_encoder_set_metadata() +/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_metadata() + * + * \default \c NULL, 0 + * \param encoder An encoder instance to set. + * \param metadata See above. + * \param num_blocks See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_metadata(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamMetadata **metadata, unsigned num_blocks); -/** Inherited from FLAC__stream_encoder_set_write_callback() +/** Set the write callback. + * + * \note + * The callback is mandatory and must be set before initialization. + * + * \default \c NULL + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \code value != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_write_callback(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderWriteCallback value); -/** Inherited from FLAC__stream_encoder_set_metadata_callback() - */ -FLAC__bool OggFLAC__stream_encoder_set_metadata_callback(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderMetadataCallback value); - -/** Inherited from FLAC__stream_encoder_set_client_data() +/** Set the client data to be passed back to callbacks. + * This value will be supplied to callbacks in their \a client_data + * argument. + * + * \default \c NULL + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. */ FLAC__bool OggFLAC__stream_encoder_set_client_data(OggFLAC__StreamEncoder *encoder, void *value); -/** Inherited from FLAC__stream_encoder_get_state() +/** Get the current encoder state. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval OggFLAC__StreamEncoderState + * The current encoder state. */ OggFLAC__StreamEncoderState OggFLAC__stream_encoder_get_state(const OggFLAC__StreamEncoder *encoder); -/** Get the state of the underlying FLAC encoder. +/** Get the state of the underlying FLAC stream encoder. * Useful when the stream encoder state is - * \c OggFLAC__STREAM_ENCODER_FLAC_ENCODER_ERROR. + * \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR. * * \param encoder An encoder instance to query. * \assert * \code encoder != NULL \endcode * \retval FLAC__StreamEncoderState - * The stream encoder state. + * The FLAC stream encoder state. */ -FLAC__StreamEncoderState OggFLAC__stream_encoder_get_FLAC_encoder_state(const OggFLAC__StreamEncoder *encoder); +FLAC__StreamEncoderState OggFLAC__stream_encoder_get_FLAC_stream_encoder_state(const OggFLAC__StreamEncoder *encoder); -/** Get the state of the FLAC encoder's verify decoder. +/** Get the state of the underlying FLAC stream encoder's verify decoder. * Useful when the stream encoder state is - * \c OggFLAC__STREAM_ENCODER_FLAC_ENCODER_ERROR and the - * FLAC encoder state is \c OggFLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. + * \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR and the + * FLAC encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. * * \param encoder An encoder instance to query. * \assert * \code encoder != NULL \endcode * \retval FLAC__StreamDecoderState - * The stream encoder state. + * The FLAC verify decoder state. */ FLAC__StreamDecoderState OggFLAC__stream_encoder_get_verify_decoder_state(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_verify() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_verify() + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See OggFLAC__stream_encoder_set_verify(). */ FLAC__bool OggFLAC__stream_encoder_get_verify(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_streamable_subset() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_streamable_subset() + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See OggFLAC__stream_encoder_set_streamable_subset(). */ FLAC__bool OggFLAC__stream_encoder_get_streamable_subset(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_do_mid_side_stereo() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_mid_side_stereo() + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See OggFLAC__stream_encoder_get_do_mid_side_stereo(). */ FLAC__bool OggFLAC__stream_encoder_get_do_mid_side_stereo(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_loose_mid_side_stereo() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_loose_mid_side_stereo() + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See OggFLAC__stream_encoder_set_loose_mid_side_stereo(). */ FLAC__bool OggFLAC__stream_encoder_get_loose_mid_side_stereo(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_channels() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_channels() + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval unsigned + * See OggFLAC__stream_encoder_set_channels(). */ unsigned OggFLAC__stream_encoder_get_channels(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_bits_per_sample() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_bits_per_sample() + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval unsigned + * See OggFLAC__stream_encoder_set_bits_per_sample(). */ unsigned OggFLAC__stream_encoder_get_bits_per_sample(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_sample_rate() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_sample_rate() + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval unsigned + * See OggFLAC__stream_encoder_set_sample_rate(). */ unsigned OggFLAC__stream_encoder_get_sample_rate(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_blocksize() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_blocksize() + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval unsigned + * See OggFLAC__stream_encoder_set_blocksize(). */ unsigned OggFLAC__stream_encoder_get_blocksize(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_max_lpc_order() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_max_lpc_order() + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval unsigned + * See OggFLAC__stream_encoder_set_max_lpc_order(). */ unsigned OggFLAC__stream_encoder_get_max_lpc_order(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_qlp_coeff_precision() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_qlp_coeff_precision() + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval unsigned + * See OggFLAC__stream_encoder_set_qlp_coeff_precision(). */ unsigned OggFLAC__stream_encoder_get_qlp_coeff_precision(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_do_qlp_coeff_prec_search() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_qlp_coeff_prec_search() + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search(). */ FLAC__bool OggFLAC__stream_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_do_escape_coding() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_escape_coding() + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See OggFLAC__stream_encoder_set_do_escape_coding(). */ FLAC__bool OggFLAC__stream_encoder_get_do_escape_coding(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_do_exhaustive_model_search() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_exhaustive_model_search() + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See OggFLAC__stream_encoder_set_do_exhaustive_model_search(). */ FLAC__bool OggFLAC__stream_encoder_get_do_exhaustive_model_search(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_min_residual_partition_order() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_min_residual_partition_order() + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval unsigned + * See OggFLAC__stream_encoder_set_min_residual_partition_order(). */ unsigned OggFLAC__stream_encoder_get_min_residual_partition_order(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_max_residual_partition_order() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_man_residual_partition_order() + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval unsigned + * See OggFLAC__stream_encoder_set_max_residual_partition_order(). */ unsigned OggFLAC__stream_encoder_get_max_residual_partition_order(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_rice_parameter_search_dist() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_rice_parameter_search_dist() + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval unsigned + * See OggFLAC__stream_encoder_set_rice_parameter_search_dist(). */ unsigned OggFLAC__stream_encoder_get_rice_parameter_search_dist(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_get_total_samples_estimate() +/* This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_total_samples_estimate() + * + * \param encoder An encoder instance to set. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__uint64 + * See OggFLAC__stream_encoder_get_total_samples_estimate(). */ FLAC__uint64 OggFLAC__stream_encoder_get_total_samples_estimate(const OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_init() +/** Initialize the encoder instance. + * Should be called after OggFLAC__stream_encoder_new() and + * OggFLAC__stream_encoder_set_*() but before OggFLAC__stream_encoder_process() + * or OggFLAC__stream_encoder_process_interleaved(). Will set and return + * the encoder state, which will be OggFLAC__STREAM_ENCODER_OK if + * initialization succeeded. + * + * The call to OggFLAC__stream_encoder_init() currently will also immediately + * call the write callback several times, once with the \c fLaC signature, + * and once for each encoded metadata block. + * + * \param encoder An uninitialized encoder instance. + * \assert + * \code encoder != NULL \endcode + * \retval OggFLAC__StreamEncoderState + * \c OggFLAC__STREAM_ENCODER_OK if initialization was successful; see + * OggFLAC__StreamEncoderState for the meanings of other return values. */ OggFLAC__StreamEncoderState OggFLAC__stream_encoder_init(OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_finish() +/** Finish the encoding process. + * Flushes the encoding buffer, releases resources, resets the encoder + * settings to their defaults, and returns the encoder state to + * OggFLAC__STREAM_ENCODER_UNINITIALIZED. Note that this can generate + * one or more write callbacks before returning. + * + * In the event of a prematurely-terminated encode, it is not strictly + * necessary to call this immediately before OggFLAC__stream_encoder_delete() + * but it is good practice to match every OggFLAC__stream_encoder_init() + * with an OggFLAC__stream_encoder_finish(). + * + * \param encoder An uninitialized encoder instance. + * \assert + * \code encoder != NULL \endcode */ void OggFLAC__stream_encoder_finish(OggFLAC__StreamEncoder *encoder); -/** Inherited from FLAC__stream_encoder_process() +/** Submit data for encoding. + * This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process(). + * + * \param encoder An initialized encoder instance in the OK state. + * \param buffer An array of pointers to each channel's signal. + * \param samples The number of samples in one channel. + * \assert + * \code encoder != NULL \endcode + * \code OggFLAC__stream_encoder_get_state(encoder) == OggFLAC__STREAM_ENCODER_OK \endcode + * \retval FLAC__bool + * \c true if successful, else \c false; in this case, check the + * encoder state with OggFLAC__stream_encoder_get_state() to see what + * went wrong. */ FLAC__bool OggFLAC__stream_encoder_process(OggFLAC__StreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples); -/** Inherited from FLAC__stream_encoder_process_interleaved() +/** Submit data for encoding. + * This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process_interleaved(). + * + * \param encoder An initialized encoder instance in the OK state. + * \param buffer An array of channel-interleaved data (see above). + * \param samples The number of samples in one channel, the same as for + * OggFLAC__stream_encoder_process(). For example, if + * encoding two channels, \c 1000 \a samples corresponds + * to a \a buffer of 2000 values. + * \assert + * \code encoder != NULL \endcode + * \code OggFLAC__stream_encoder_get_state(encoder) == OggFLAC__STREAM_ENCODER_OK \endcode + * \retval FLAC__bool + * \c true if successful, else \c false; in this case, check the + * encoder state with OggFLAC__stream_encoder_get_state() to see what + * went wrong. */ FLAC__bool OggFLAC__stream_encoder_process_interleaved(OggFLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);