From: Josh Coalson Date: Thu, 25 Jul 2002 05:35:16 +0000 (+0000) Subject: more doxygen docs X-Git-Tag: 1.2.0~1738 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=03706dce5e9fa9bfd7243875bf60d41315facf94;p=platform%2Fupstream%2Fflac.git more doxygen docs --- diff --git a/include/FLAC/all.h b/include/FLAC/all.h index 948142b..f86416e 100644 --- a/include/FLAC/all.h +++ b/include/FLAC/all.h @@ -56,6 +56,13 @@ * encoder and plugins is available and is a useful source of * examples. * + * Aside from encoders and decoders, libFLAC provides a powerful + * metadata interface for manipulating metadata in FLAC files. It + * allows the user to add, delete, and modify FLAC metadata blocks + * and it can automatically take advantage of PADDING blocks to avoid + * rewriting the entire FLAC file when changing the size of the + * metadata. + * * libFLAC usually only requires the standard C library and C math * library. In particular, threading is not used so there is no * dependency on a thread library. However, libFLAC does not use @@ -78,7 +85,7 @@ * \section getting_started Getting Started * * A good starting point for learning the API is to browse through - * the modules. Modules are logical + * the modules. Modules are logical * groupings of related functions or classes, which correspond roughly * to header files or sections of header files. Each module includes a * detailed description of the general usage of its functions or diff --git a/include/FLAC/file_decoder.h b/include/FLAC/file_decoder.h index 91728f2..9fa4cfa 100644 --- a/include/FLAC/file_decoder.h +++ b/include/FLAC/file_decoder.h @@ -26,6 +26,80 @@ extern "C" { #endif + +/** \file include/FLAC/file_decoder.h + * + * \brief + * This module contains the functions which implement the file + * decoder. + * + * See the detailed documentation in the + * \link flac_file_decoder file decoder \endlink module. + */ + +/** \defgroup flac_file_decoder FLAC/file_decoder.h: file decoder interface + * \ingroup flac_decoder + * + * \brief + * 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 + * FLAC__file_decoder_new(). + * - The program overrides the default settings and sets callbacks for + * writing, error reporting, and metadata reporting using + * FLAC__file_decoder_set_*() functions. + * - The program initializes the instance to validate the settings and + * prepare for decoding using FLAC__file_decoder_init(). + * - The program calls the FLAC__file_decoder_process_*() functions + * to decode data, which subsequently calls the callbacks. + * - The program finishes the decoding with FLAC__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 + * FLAC__file_decoder_delete(). + * + * The file decoder is a trivial wrapper around the + * \link flac_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 + * FLAC__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, + * FLAC__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. + * + * \note + * The "set" functions may only be called when the decoder is in the + * state FLAC__FILE_DECODER_UNINITIALIZED, i.e. after + * FLAC__file_decoder_new() or FLAC__file_decoder_finish(), but + * before FLAC__file_decoder_init(). If this is the case they will + * return \c true, otherwise \c false. + * + * \note + * FLAC__file_decoder_finish() resets all settings to the constructor + * defaults, including the callbacks. + * + * \{ + */ + + +/** State values for a FLAC__FileDecoder + * + * The decoder's state can be obtained by calling FLAC__file_decoder_get_state(). + */ typedef enum { FLAC__FILE_DECODER_OK = 0, FLAC__FILE_DECODER_END_OF_FILE, @@ -154,6 +228,8 @@ FLAC__bool FLAC__file_decoder_process_remaining_frames(FLAC__FileDecoder *decode FLAC__bool FLAC__file_decoder_seek_absolute(FLAC__FileDecoder *decoder, FLAC__uint64 sample); +/* \} */ + #ifdef __cplusplus } #endif diff --git a/include/FLAC/metadata.h b/include/FLAC/metadata.h index ec1da0a..63f58e7 100644 --- a/include/FLAC/metadata.h +++ b/include/FLAC/metadata.h @@ -102,7 +102,7 @@ extern "C" { /** \defgroup flac_metadata_level0 FLAC/metadata.h: metadata level 0 interface * \ingroup flac_metadata - * + * * \brief * The level 0 interface consists of a single routine to read the * STREAMINFO block. @@ -132,7 +132,7 @@ FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetad /** \defgroup flac_metadata_level1 FLAC/metadata.h: metadata level 1 interface * \ingroup flac_metadata - * + * * \brief * The level 1 interface provides read-write access to FLAC file metadata and * operates directly on the FLAC file. @@ -185,10 +185,12 @@ FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetad * \{ */ -/** \typedef FLAC__Metadata_SimpleIterator - * The opaque structure definition for the level 1 iterator type. - */ struct FLAC__Metadata_SimpleIterator; +/** The opaque structure definition for the level 1 iterator type. + * See the + * \link flac_metadata_level1 metadata level 1 module \endlink + * for a detailed description. + */ typedef struct FLAC__Metadata_SimpleIterator FLAC__Metadata_SimpleIterator; /** Status type for FLAC__Metadata_SimpleIterator. @@ -466,7 +468,7 @@ FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIter /** \defgroup flac_metadata_level2 FLAC/metadata.h: metadata level 2 interface * \ingroup flac_metadata - * + * * \brief * The level 2 interface provides read-write access to FLAC file metadata; * all metadata is read into memory, operated on in memory, and then written @@ -516,16 +518,14 @@ FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIter * \{ */ -/** \typedef FLAC__Metadata_Chain - * The opaque structure definition for the level 2 chain type. - */ struct FLAC__Metadata_Chain; +/** The opaque structure definition for the level 2 chain type. + */ typedef struct FLAC__Metadata_Chain FLAC__Metadata_Chain; -/** \typedef FLAC__Metadata_Iterator - * The opaque structure definition for the level 2 iterator type. - */ struct FLAC__Metadata_Iterator; +/** The opaque structure definition for the level 2 iterator type. + */ typedef struct FLAC__Metadata_Iterator FLAC__Metadata_Iterator; typedef enum { diff --git a/include/FLAC/seekable_stream_decoder.h b/include/FLAC/seekable_stream_decoder.h index 6163864..60080ff 100644 --- a/include/FLAC/seekable_stream_decoder.h +++ b/include/FLAC/seekable_stream_decoder.h @@ -27,6 +27,91 @@ extern "C" { #endif +/** \file include/FLAC/seekable_stream_decoder.h + * + * \brief + * This module contains the functions which implement the seekable stream + * decoder. + * + * See the detailed documentation in the + * \link flac_seekable_stream_decoder seekable stream decoder \endlink module. + */ + +/** \defgroup flac_seekable_stream_decoder FLAC/seekable_stream_decoder.h: seekable stream decoder interface + * \ingroup flac_decoder + * + * \brief + * 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 + * FLAC__seekable_stream_decoder_new(). + * - The program overrides the default settings and sets callbacks for + * reading, writing, seeking, error reporting, and metadata reporting + * using FLAC__seekable_stream_decoder_set_*() functions. + * - The program initializes the instance to validate the settings and + * prepare for decoding using FLAC__seekable_stream_decoder_init(). + * - The program calls the FLAC__seekable_stream_decoder_process_*() + * functions to decode data, which subsequently calls the callbacks. + * - The program finishes the decoding with + * FLAC__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 + * FLAC__seekable_stream_decoder_delete(). + * + * The seekable stream decoder is a wrapper around the + * \link flac_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 + * FLAC__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, + * FLAC__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 + * FLAC__seekable_stream_decoder_reset()) if there is no signature in the + * STREAMINFO block or when a seek is attempted. + * + * \note + * The "set" functions may only be called when the decoder is in the + * state FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED, i.e. after + * FLAC__seekable_stream_decoder_new() or + * FLAC__seekable_stream_decoder_finish(), but before + * FLAC__seekable_stream_decoder_init(). If this is the case they will + * return \c true, otherwise \c false. + * + * \note + * FLAC__stream_decoder_finish() resets all settings to the constructor + * defaults, including the callbacks. + * + * \{ + */ + + +/** State values for a FLAC__SeekableStreamDecoder + * + * The decoder's state can be obtained by calling FLAC__seekable_tream_decoder_get_state(). + */ typedef enum { FLAC__SEEKABLE_STREAM_DECODER_OK = 0, FLAC__SEEKABLE_STREAM_DECODER_SEEKING, @@ -195,6 +280,8 @@ FLAC__bool FLAC__seekable_stream_decoder_process_remaining_frames(FLAC__Seekable FLAC__bool FLAC__seekable_stream_decoder_seek_absolute(FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample); +/* \} */ + #ifdef __cplusplus } #endif diff --git a/include/FLAC/stream_decoder.h b/include/FLAC/stream_decoder.h index 970a024..7788a47 100644 --- a/include/FLAC/stream_decoder.h +++ b/include/FLAC/stream_decoder.h @@ -27,41 +27,255 @@ extern "C" { #endif +/** \file include/FLAC/stream_decoder.h + * + * \brief + * This module contains the functions which implement the stream + * decoder. + * + * See the detailed documentation in the + * \link flac_stream_decoder stream decoder \endlink module. + */ + +/** \defgroup flac_decoder FLAC/*_decoder.h: decoder interfaces + * \ingroup flac + * + * \brief + * This module describes the three decoder layers provided by libFLAC. + * + * For decoding FLAC streams, libFLAC 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 flac_stream_decoder stream decoder + * \endlink, \link flac_seekable_stream_decoder seekable stream decoder + * \endlink, and \link flac_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. + */ + +/** \defgroup flac_stream_decoder FLAC/stream_decoder.h: stream decoder interface + * \ingroup flac_decoder + * + * \brief + * 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 + * FLAC__stream_decoder_new(). + * - The program overrides the default settings and sets callbacks for + * reading, writing, error reporting, and metadata reporting using + * FLAC__stream_decoder_set_*() functions. + * - The program initializes the instance to validate the settings and + * prepare for decoding using FLAC__stream_decoder_init(). + * - The program calls the FLAC__stream_decoder_process_*() functions + * to decode data, which subsequently calls the callbacks. + * - The program finishes the decoding with FLAC__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 + * FLAC__stream_decoder_delete(). + * + * In more detail, the program will create a new instance by calling + * FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*() + * functions to set the callbacks and client data, and call + * FLAC__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 FLAC__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 + * FLAC__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 + * FLAC__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: + * + * - FLAC__stream_decoder_process_whole_stream() - Tells the decoder to + * start and continue processing the stream until the read callback + * returns FLAC__STREAM_DECODER_READ_END_OF_STREAM or + * FLAC__STREAM_DECODER_READ_ABORT. + * - FLAC__stream_decoder_process_metadata() - Tells the decoder to start + * processing the stream and stop upon reaching the first audio frame. + * - FLAC__stream_decoder_process_one_frame() - Tells the decoder to + * process one audio frame and return. The decoder must have processed + * all metadata first before calling this function. + * - FLAC__stream_decoder_process_remaining_frames() - Tells the decoder to + * process all remaining frames. The decoder must have processed all + * metadata first but may also have processed frames with + * FLAC__stream_decoder_process_one_frame(). + * + * When the decoder has finished decoding (normally or through an abort), + * the instance is finished by calling FLAC__stream_decoder_finish(), which + * ensures the decoder is in the correct state and frees memory. Then the + * instance may be deleted with FLAC__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 FLAC__stream_decoder_flush() and start feeding + * data from the new position through the read callback. The seekable + * stream decoder does just this. + * + * \note + * The "set" functions may only be called when the decoder is in the + * state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after + * FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but + * before FLAC__stream_decoder_init(). If this is the case they will + * return \c true, otherwise \c false. + * + * \note + * FLAC__stream_decoder_finish() resets all settings to the constructor + * defaults, including the callbacks. + * + * \{ + */ + + +/** State values for a FLAC__StreamDecoder + * + * The decoder's state can be obtained by calling FLAC__stream_decoder_get_state(). + */ typedef enum { + FLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0, + /**< The decoder is ready to search for metadata. */ + FLAC__STREAM_DECODER_READ_METADATA, + /**< The decoder is ready to or is in the process of reading metadata. */ + FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC, + /**< The decoder is ready to or is in the process of searching for the frame sync code. */ + FLAC__STREAM_DECODER_READ_FRAME, + /**< The decoder is ready to or is in the process of reading a frame. */ + FLAC__STREAM_DECODER_END_OF_STREAM, + /**< The decoder has reached the end of the stream. */ + FLAC__STREAM_DECODER_ABORTED, + /**< The decoder was aborted by the read callback. */ + FLAC__STREAM_DECODER_UNPARSEABLE_STREAM, + /**< The decoder encountered reserved fields in use in the stream. */ + FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR, + /**< An error occurred allocating memory. */ + FLAC__STREAM_DECODER_ALREADY_INITIALIZED, + /**< FLAC__stream_decoder_init() was called when the decoder was + * already initialized, usually because + * FLAC__stream_decoder_finish() was not called. + */ + FLAC__STREAM_DECODER_INVALID_CALLBACK, + /**< FLAC__stream_decoder_init() was called without all callbacks being set. */ + FLAC__STREAM_DECODER_UNINITIALIZED + /**< The decoder is in the uninitialized state. */ + } FLAC__StreamDecoderState; + +/** Maps a FLAC__StreamDecoderState to a C string. + * + * Using a FLAC__StreamDecoderState as the index to this array + * will give the string equivalent. The contents should not be modified. + */ extern const char * const FLAC__StreamDecoderStateString[]; + +/** Return values for the FLAC__StreamDecoder read callback. + */ typedef enum { + FLAC__STREAM_DECODER_READ_STATUS_CONTINUE, + /**< The read was OK and decoding can continue. */ + FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM, + /**< The read was attempted at the end of the stream. */ + FLAC__STREAM_DECODER_READ_STATUS_ABORT + /**< An unrecoverable error occurred. The decoder will return from the process call. */ + } FLAC__StreamDecoderReadStatus; + +/** Maps a FLAC__StreamDecoderReadStatus to a C string. + * + * Using a FLAC__StreamDecoderReadStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ extern const char * const FLAC__StreamDecoderReadStatusString[]; + +/** Return values for the FLAC__StreamDecoder write callback. + */ typedef enum { + FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE, + /**< The write was OK and decoding can continue. */ + FLAC__STREAM_DECODER_WRITE_STATUS_ABORT + /**< An unrecoverable error occurred. The decoder will return from the process call. */ + } FLAC__StreamDecoderWriteStatus; + +/** Maps a FLAC__StreamDecoderWriteStatus to a C string. + * + * Using a FLAC__StreamDecoderWriteStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ extern const char * const FLAC__StreamDecoderWriteStatusString[]; + +/** Possible values passed in to the FLAC__StreamDecoder error callback. + */ typedef enum { + FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC, + /**< An error in the stream caused the decoder to lose synchronization. */ + FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER, + /**< The decoder encountered a corrupted frame header. */ + FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH + /**< The frame's data did not match the CRC in the footer. */ + } FLAC__StreamDecoderErrorStatus; + +/** Maps a FLAC__StreamDecoderErrorStatus to a C string. + * + * Using a FLAC__StreamDecoderErrorStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ extern const char * const FLAC__StreamDecoderErrorStatusString[]; + /*********************************************************************** * * class FLAC__StreamDecoder @@ -70,60 +284,148 @@ extern const char * const FLAC__StreamDecoderErrorStatusString[]; struct FLAC__StreamDecoderProtected; struct FLAC__StreamDecoderPrivate; +/** The opaque structure definition for the stream decoder type. + * See the \link flac_stream_decoder stream decoder module \endlink + * for a detailed description. + */ typedef struct { struct FLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */ struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */ } FLAC__StreamDecoder; + /*********************************************************************** * * Class constructor/destructor * ***********************************************************************/ -/* - * Any parameters that are not set before FLAC__stream_decoder_init() - * will take on the defaults from the constructor, shown below. - * For more on what the parameters mean, see the documentation. - * - * (*read_callback)() (DEFAULT: NULL ) The callbacks are the only values that MUST be set before FLAC__stream_decoder_init() - * (*write_callback)() (DEFAULT: NULL ) - * (*metadata_callback)() (DEFAULT: NULL ) - * (*error_callback)() (DEFAULT: NULL ) - * void* client_data (DEFAULT: NULL ) passed back through the callbacks - * metadata_respond/ignore By default, only the STREAMINFO block is returned via metadata_callback() +/** Create a new stream decoder instance. The instance is created with + * default settings; see the individual FLAC__stream_decoder_set_*() + * functions for each setting's default. + * + * \retval FLAC__StreamDecoder* + * \c NULL if there was an error allocating memory, else the new instance. */ FLAC__StreamDecoder *FLAC__stream_decoder_new(); + +/** Free an decoder instance. Deletes the object pointed to by \a decoder. + * + * \param decoder A pointer to an existing decoder. + * \assert + * \code decoder != NULL \endcode + */ void FLAC__stream_decoder_delete(FLAC__StreamDecoder *); + /*********************************************************************** * * Public class method prototypes * ***********************************************************************/ -/* - * Various "set" methods. These may only be called when the decoder - * is in the state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after - * FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but - * before FLAC__stream_decoder_init(). If this is the case they will - * return true, otherwise false. +/** 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 FLAC__StreamDecoderReadStatus. * - * NOTE that these functions do not validate the values as many are - * interdependent. The FLAC__stream_decoder_init() function will do - * this, so make sure to pay attention to the state returned by - * FLAC__stream_decoder_init(). + * \note + * The callback is mandatory and must be set before initialization. * - * Any parameters that are not set before FLAC__stream_decoder_init() - * will take on the defaults from the constructor. NOTE that - * FLAC__stream_decoder_flush() or FLAC__stream_decoder_reset() do - * NOT reset the values to the constructor defaults. + * \default \c NULL + * \param decoder An decoder instance to set. + * \param value See above. + * \assert + * \code decoder != NULL \endcode + * \code value != NULL \endcode + * \retval FLAC__bool + * \c false if the decoder is already initialized, else \c true. */ FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderReadStatus (*value)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data)); + +/** 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. + * + * \note + * The callback is mandatory and must be set before initialization. + * + * \default \c NULL + * \param decoder An decoder instance to set. + * \param value See above. + * \assert + * \code decoder != NULL \endcode + * \code value != NULL \endcode + * \retval FLAC__bool + * \c false if the decoder is already initialized, else \c true. + */ FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteStatus (*value)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data)); + +/** 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 + * FLAC__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 + * FLAC__stream_decoder_set_metadata_*() calls. + * + * \note + * The callback is mandatory and must be set before initialization. + * + * \default \c NULL + * \param decoder An decoder instance to set. + * \param value See above. + * \assert + * \code decoder != NULL \endcode + * \code value != NULL \endcode + * \retval FLAC__bool + * \c false if the decoder is already initialized, else \c true. + */ FLAC__bool FLAC__stream_decoder_set_metadata_callback(FLAC__StreamDecoder *decoder, void (*value)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data)); + +/** Set the error callback. + * The supplied function will be called whenever an error occurs during + * decoding. + * + * \note + * The callback is mandatory and must be set before initialization. + * + * \default \c NULL + * \param decoder An decoder instance to set. + * \param value See above. + * \assert + * \code decoder != NULL \endcode + * \code value != NULL \endcode + * \retval FLAC__bool + * \c false if the decoder is already initialized, else \c true. + */ FLAC__bool FLAC__stream_decoder_set_error_callback(FLAC__StreamDecoder *decoder, void (*value)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *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 decoder An decoder instance to set. + * \param value See above. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__bool + * \c false if the decoder is already initialized, else \c true. + */ FLAC__bool FLAC__stream_decoder_set_client_data(FLAC__StreamDecoder *decoder, void *value); + /* * These deserve special attention. By default, the decoder only calls the * metadata_callback for the STREAMINFO block. These functions allow you to @@ -138,6 +440,9 @@ FLAC__bool FLAC__stream_decoder_set_client_data(FLAC__StreamDecoder *decoder, vo * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but * they still can legally be filtered from the metadata_callback here. */ +/* + * metadata_respond/ignore By default, only the STREAMINFO block is returned via metadata_callback() + */ FLAC__bool FLAC__stream_decoder_set_metadata_respond(FLAC__StreamDecoder *decoder, FLAC__MetadataType type); FLAC__bool FLAC__stream_decoder_set_metadata_respond_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]); FLAC__bool FLAC__stream_decoder_set_metadata_respond_all(FLAC__StreamDecoder *decoder); @@ -187,6 +492,8 @@ FLAC__bool FLAC__stream_decoder_process_metadata(FLAC__StreamDecoder *decoder); FLAC__bool FLAC__stream_decoder_process_one_frame(FLAC__StreamDecoder *decoder); FLAC__bool FLAC__stream_decoder_process_remaining_frames(FLAC__StreamDecoder *decoder); +/* \} */ + #ifdef __cplusplus } #endif diff --git a/include/FLAC/stream_encoder.h b/include/FLAC/stream_encoder.h index 3e73421..679eaef 100644 --- a/include/FLAC/stream_encoder.h +++ b/include/FLAC/stream_encoder.h @@ -37,59 +37,130 @@ extern "C" { * \link flac_stream_encoder stream encoder \endlink module. */ -/** \defgroup flac_stream_encoder FLAC/stream_encoder.h: stream encoder interface +/** \defgroup flac_encoder FLAC/*_encoder.h: encoder interfaces + * \ingroup flac + * + * \brief + * This module describes the single encoder layer provided by libFLAC. + * + * Currently there is only one level of encoder implementation which is at + * the stream level. There is currently no file encoder because seeking + * within a file while encoding seemed like too obscure a feature. + */ + +/** \defgroup flac_encoder FLAC/*_encoder.h: encoder interfaces * \ingroup flac * + */ + +/** \defgroup flac_stream_encoder FLAC/stream_encoder.h: stream encoder interface + * \ingroup flac_encoder + * * \brief * This module contains the functions which implement the stream * encoder. * - * The basic usage of a libFLAC encoder is as follows: + * The basic usage of this encoder is as follows: * - The program creates an instance of an encoder using * FLAC__stream_encoder_new(). * - The program overrides the default settings and sets callbacks for - * reading, writing, error reporting, and metadata reporting using + * writing and metadata reporting using * FLAC__stream_encoder_set_*() functions. * - The program initializes the instance to validate the settings and - * prepare for encoding using FLAC__stream_encoder_init(). + * prepare for encoding using FLAC__stream_encoder_init(). * - The program calls FLAC__stream_encoder_process() or * FLAC__stream_encoder_process_interleaved() to encode data, which - * subsequently calls the callbacks. - * - The program finishes the instance with FLAC__stream_encoder_finish(), - * which flushes the input and output and resets the encoder to the - * unitialized state. + * subsequently calls the callbacks when there is encoder data ready + * to be written. + * - The program finishes the encoding with FLAC__stream_encoder_finish(), + * which causes the encoder to encode any data still in its input pipe, + * call the metadata callback with the final encoding statistics, and + * finally reset the encoder to the uninitialized state. * - The instance may be used again or deleted with - * FLAC__stream_encoder_delete(). - * - * \note - * The "set" functions may only be called when the encoder is in the - * state FLAC__STREAM_ENCODER_UNINITIALIZED, i.e. after - * FLAC__stream_encoder_new() or FLAC__stream_encoder_finish(), but - * before FLAC__stream_encoder_init(). If this is the case they will - * return true, otherwise false. + * FLAC__stream_encoder_delete(). * - * \note - * The "set" functions do not validate the values as many are - * interdependent. The FLAC__stream_encoder_init() function will do - * this, so make sure to pay attention to the state returned by - * FLAC__stream_encoder_init() to make sure that it is - * FLAC__STREAM_ENCODER_OK. + * In more detail, the stream encoder functions similarly to the + * \link flac_stream_decoder stream decoder \endlink, but has fewer + * callbacks and more options. Typically the user will create a new + * instance by calling FLAC__stream_encoder_new(), then set the necessary + * parameters and callbacks with FLAC__stream_encoder_set_*(), and + * initialize it by calling FLAC__stream_encoder_init(). * - * \note * Unlike the decoders, the stream encoder has many options that can * affect the speed and compression ratio. When setting these parameters * you should have some basic knowledge of the format (see the * user-level documentation - * or the formal description). + * or the formal description). The + * FLAC__stream_encoder_set_*() functions themselves do not validate the + * values as many are interdependent. The FLAC__stream_encoder_init() + * function will do this, so make sure to pay attention to the state + * returned by FLAC__stream_encoder_init() to make sure that it is + * FLAC__STREAM_ENCODER_OK. Any parameters that are not set before + * FLAC__stream_encoder_init() will take on the defaults from the + * constructor. + * + * The user must provide function pointers for the following callbacks: + * + * - Write callback - This function is called by the encoder anytime there + * is raw encoded data to write. It may include metadata mixed with + * encoded audio frames and the data is not guaranteed to be aligned on + * frame or metadata block boundaries. + * - Metadata callback - This function is called once at the end of + * encoding with the populated STREAMINFO structure. This is so file + * encoders can seek back to the beginning of the file and write the + * STREAMINFO block with the correct statistics after encoding (like + * minimum/maximum frame size). + * + * The call to FLAC__stream_encoder_init() currently will also immediately + * call the write callback with the \c fLaC signature and all the encoded + * metadata. + * + * After initializing the instance, the user may feed audio data to the + * encoder in one of two ways: + * + * - Channel separate, through FLAC__stream_encoder_process() - The user + * will pass an array of pointers to buffers, one for each channel, to + * the encoder, each of the same length. The samples need not be + * block-aligned. + * - Channel interleaved, through + * FLAC__stream_encoder_process_interleaved() - The user will pass a single + * pointer to data that is channel-interleaved (i.e. channel0_sample0, + * channel1_sample0, ... , channelN_sample0, channel0_sample1, ...). + * Again, the samples need not be block-aligned but they must be + * sample-aligned, i.e. the first value should be channel0_sample0 and + * the last value channelN_sampleM. + * + * When the user is finished encoding data, it calls + * FLAC__stream_encoder_finish(), which causes the encoder to encode any + * data still in its input pipe, and call the metadata callback with the + * final encoding statistics. Then the instance may be deleted with + * FLAC__stream_encoder_delete() or initialized again to encode another + * stream. + * + * For programs that write their own metadata, but that do not know the + * actual metadata until after encoding, it is advantageous to instruct + * the encoder to write a PADDING block of the correct size, so that + * instead of rewriting the whole stream after encoding, the program can + * just overwrite the PADDING block. If only the maximum size of the + * metadata is known, the program can write a slightly larger padding + * block, then split it after encoding. + * + * Make sure you understand how lengths are calculated. All FLAC metadata + * blocks have a 4 byte header which contains the type and length. This + * length does not include the 4 bytes of the header. See the format page + * for the specification of metadata blocks and their lengths. * * \note - * Any parameters that are not set before FLAC__stream_encoder_init() - * will take on the defaults from the constructor. + * The "set" functions may only be called when the encoder is in the + * state FLAC__STREAM_ENCODER_UNINITIALIZED, i.e. after + * FLAC__stream_encoder_new() or FLAC__stream_encoder_finish(), but + * before FLAC__stream_encoder_init(). If this is the case they will + * return \c true, otherwise \c false. * * \note * FLAC__stream_encoder_finish() resets all settings to the constructor * defaults, including the callbacks. - * + * * \{ */ @@ -201,6 +272,8 @@ extern const char * const FLAC__StreamEncoderWriteStatusString[]; struct FLAC__StreamEncoderProtected; struct FLAC__StreamEncoderPrivate; /** The opaque structure definition for the stream encoder type. + * See the \link flac_stream_encoder stream encoder module \endlink + * for a detailed description. */ typedef struct { struct FLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */ @@ -237,19 +310,6 @@ void FLAC__stream_encoder_delete(FLAC__StreamEncoder *encoder); * ***********************************************************************/ -/* - * FLAC__bool do_qlp_coeff_prec_search (DEFAULT: false ) false => use qlp_coeff_precision, true => search around qlp_coeff_precision, take best - * FLAC__bool do_escape_coding (DEFAULT: false ) true => search for escape codes in the entropy coding stage for slightly better compression - * FLAC__bool do_exhaustive_model_search (DEFAULT: false ) false => use estimated bits per residual for scoring, true => generate all, take shortest - * unsigned min_residual_partition_order (DEFAULT: 0 ) 0 => estimate Rice parameter based on residual variance; >0 => partition residual, use parameter - * unsigned max_residual_partition_order (DEFAULT: 0 ) for each based on mean; min_ and max_ specify the min and max Rice partition order - * unsigned rice_parameter_search_dist (DEFAULT: 0 ) 0 => try only calc'd parameter k; else try all [k-dist..k+dist] parameters, use best - * FLAC__uint64 total_samples_estimate (DEFAULT: 0 ) may be 0 if unknown. acts as a placeholder in the STREAMINFO until the actual total is calculated - * FLAC__StreamMetadata **metadata (DEFAULT: NULL,0) optional metadata blocks to prepend. STREAMINFO is not allowed since it is done internally. - * + unsigned num_blocks - * void* client_data (DEFAULT: NULL ) passed back through the callbacks - */ - /** Set the "streamable subset" flag. If \c true, the encoder will comply * with the subset (see the format specification) and will check the * settings during FLAC__stream_encoder_init() to see if all settings @@ -379,7 +439,9 @@ FLAC__bool FLAC__stream_encoder_set_max_lpc_order(FLAC__StreamEncoder *encoder, */ FLAC__bool FLAC__stream_encoder_set_qlp_coeff_precision(FLAC__StreamEncoder *encoder, unsigned value); -/** Set the number of channels to be encoded. +/** Set to \c false to use only the specified quantized linear predictor + * coefficient precision, or \c true to search neighboring precision + * values and use the best one. * * \default \c false * \param encoder An encoder instance to set. @@ -391,7 +453,7 @@ FLAC__bool FLAC__stream_encoder_set_qlp_coeff_precision(FLAC__StreamEncoder *enc */ FLAC__bool FLAC__stream_encoder_set_do_qlp_coeff_prec_search(FLAC__StreamEncoder *encoder, FLAC__bool value); -/** Set the number of channels to be encoded. +/** Deprecated. Setting this value has no effect. * * \default \c false * \param encoder An encoder instance to set. @@ -403,7 +465,9 @@ FLAC__bool FLAC__stream_encoder_set_do_qlp_coeff_prec_search(FLAC__StreamEncoder */ FLAC__bool FLAC__stream_encoder_set_do_escape_coding(FLAC__StreamEncoder *encoder, FLAC__bool value); -/** Set the number of channels to be encoded. +/** Set to \c false to let the encoder estimate the best model order + * based on the residual signal energy, or \c true to force the + * encoder to evaluate all order models and select the best. * * \default \c false * \param encoder An encoder instance to set. @@ -415,7 +479,18 @@ FLAC__bool FLAC__stream_encoder_set_do_escape_coding(FLAC__StreamEncoder *encode */ FLAC__bool FLAC__stream_encoder_set_do_exhaustive_model_search(FLAC__StreamEncoder *encoder, FLAC__bool value); -/** Set the number of channels to be encoded. +/** Set the minimum partition order to search when coding the residual. + * This is used in tandem with + * FLAC__stream_encoder_set_max_residual_partition_order(). + * + * The partition order determines the context size in the residual. + * The context size will be approximately blocksize / (2 ^ order). + * + * Set both min and max values to \c 0 to force a single context, + * whose Rice parameter is based on the residual signal variance. + * Otherwise, set a min and max order, and the encoder will search + * all orders, using the mean of each context for its Rice parameter, + * and use the best. * * \default \c 0 * \param encoder An encoder instance to set. @@ -427,7 +502,18 @@ FLAC__bool FLAC__stream_encoder_set_do_exhaustive_model_search(FLAC__StreamEncod */ FLAC__bool FLAC__stream_encoder_set_min_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value); -/** Set the number of channels to be encoded. +/** Set the minimum partition order to search when coding the residual. + * This is used in tandem with + * FLAC__stream_encoder_set_min_residual_partition_order(). + * + * The partition order determines the context size in the residual. + * The context size will be approximately blocksize / (2 ^ order). + * + * Set both min and max values to \c 0 to force a single context, + * whose Rice parameter is based on the residual signal variance. + * Otherwise, set a min and max order, and the encoder will search + * all orders, using the mean of each context for its Rice parameter, + * and use the best. * * \default \c 0 * \param encoder An encoder instance to set. @@ -439,7 +525,7 @@ FLAC__bool FLAC__stream_encoder_set_min_residual_partition_order(FLAC__StreamEnc */ FLAC__bool FLAC__stream_encoder_set_max_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value); -/** Set the number of channels to be encoded. +/** Deprecated. Setting this value has no effect. * * \default \c 0 * \param encoder An encoder instance to set. @@ -451,7 +537,11 @@ FLAC__bool FLAC__stream_encoder_set_max_residual_partition_order(FLAC__StreamEnc */ FLAC__bool FLAC__stream_encoder_set_rice_parameter_search_dist(FLAC__StreamEncoder *encoder, unsigned value); -/** Set the number of channels to be encoded. +/** Set an estimate of the total samples that will be encoded. + * This is merely an estimate and may be set to \c 0 if unknown. + * This value will be written to the STREAMINFO block before encoding, + * and can remove the need for the caller to rewrite the value later + * if the value is known before encoding. * * \default \c 0 * \param encoder An encoder instance to set. @@ -463,7 +553,14 @@ FLAC__bool FLAC__stream_encoder_set_rice_parameter_search_dist(FLAC__StreamEncod */ FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder *encoder, FLAC__uint64 value); -/** Set the number of channels to be encoded. +/** Set the metadata blocks to be emitted to the stream before encoding. + * A value of \c NULL, \c 0 implies no metadata; otherwise, supply an + * array of pointers to metadata blocks. The array is non-const since + * the encoder may need to change the \a is_last flag inside them. + * Otherwise, the encoder will not modify or free the blocks. + * + * The STREAMINFO block is always written and no STREAMINFO block may + * occur in the supplied array. * * \default \c NULL, 0 * \param encoder An encoder instance to set. @@ -475,9 +572,16 @@ FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder * */ FLAC__bool FLAC__stream_encoder_set_metadata(FLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks); -/** Set the number of channels to be encoded. +/** Set the write callback. + * The supplied function will be called by the encoder anytime there is raw + * encoded data ready to write. It may include metadata mixed with encoded + * audio frames and the data is not guaranteed to be aligned on frame or + * metadata block boundaries. * - * \default \c NULL; the callback is mandatory and must be set before initialization + * \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 @@ -488,9 +592,17 @@ FLAC__bool FLAC__stream_encoder_set_metadata(FLAC__StreamEncoder *encoder, FLAC_ */ FLAC__bool FLAC__stream_encoder_set_write_callback(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderWriteStatus (*value)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data)); -/** Set the number of channels to be encoded. +/** Set the metadata callback. + * The supplied function will be called once at the end of encoding with + * the populated STREAMINFO structure. This is so file encoders can seek + * back to the beginning of the file and write the STREAMINFO block with + * the correct statistics after encoding (like minimum/maximum frame size + * and total samples). + * + * \note + * The callback is mandatory and must be set before initialization. * - * \default \c NULL; 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 @@ -501,7 +613,9 @@ FLAC__bool FLAC__stream_encoder_set_write_callback(FLAC__StreamEncoder *encoder, */ FLAC__bool FLAC__stream_encoder_set_metadata_callback(FLAC__StreamEncoder *encoder, void (*value)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data)); -/** Set the number of channels to be encoded. +/** 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. @@ -513,45 +627,245 @@ FLAC__bool FLAC__stream_encoder_set_metadata_callback(FLAC__StreamEncoder *encod */ FLAC__bool FLAC__stream_encoder_set_client_data(FLAC__StreamEncoder *encoder, void *value); -/* - * Various "get" methods +/** Get the current encoder state. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__StreamEncoderState + * The current encoder state. */ FLAC__StreamEncoderState FLAC__stream_encoder_get_state(const FLAC__StreamEncoder *encoder); + +/** Get the "streamable subset" flag. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See FLAC__stream_encoder_set_streamable_subset(). + */ FLAC__bool FLAC__stream_encoder_get_streamable_subset(const FLAC__StreamEncoder *encoder); + +/** Get the "mid/side stereo coding" flag. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See FLAC__stream_encoder_get_do_mid_side_stereo(). + */ FLAC__bool FLAC__stream_encoder_get_do_mid_side_stereo(const FLAC__StreamEncoder *encoder); + +/** Get the "adaptive mid/side switching" flag. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See FLAC__stream_encoder_set_loose_mid_side_stereo(). + */ FLAC__bool FLAC__stream_encoder_get_loose_mid_side_stereo(const FLAC__StreamEncoder *encoder); -unsigned FLAC__stream_encoder_get_channels(const FLAC__StreamEncoder *encoder); -unsigned FLAC__stream_encoder_get_bits_per_sample(const FLAC__StreamEncoder *encoder); -unsigned FLAC__stream_encoder_get_sample_rate(const FLAC__StreamEncoder *encoder); -unsigned FLAC__stream_encoder_get_blocksize(const FLAC__StreamEncoder *encoder); -unsigned FLAC__stream_encoder_get_max_lpc_order(const FLAC__StreamEncoder *encoder); -unsigned FLAC__stream_encoder_get_qlp_coeff_precision(const FLAC__StreamEncoder *encoder); + +/** Get the number of input channels being processed. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See FLAC__stream_encoder_set_channels(). + */ +unsigned FLAC__stream_encoder_get_channels(const FLAC__StreamEncoder *encoder); + +/** Get the input sample resolution setting. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See FLAC__stream_encoder_set_bits_per_sample(). + */ +unsigned FLAC__stream_encoder_get_bits_per_sample(const FLAC__StreamEncoder *encoder); + +/** Get the input sample rate setting. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See FLAC__stream_encoder_set_sample_rate(). + */ +unsigned FLAC__stream_encoder_get_sample_rate(const FLAC__StreamEncoder *encoder); + +/** Get the blocksize setting. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See FLAC__stream_encoder_set_blocksize(). + */ +unsigned FLAC__stream_encoder_get_blocksize(const FLAC__StreamEncoder *encoder); + +/** Get the maximum LPC order setting. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See FLAC__stream_encoder_set_max_lpc_order(). + */ +unsigned FLAC__stream_encoder_get_max_lpc_order(const FLAC__StreamEncoder *encoder); + +/** Get the quantized linear predictor coefficient precision setting. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See FLAC__stream_encoder_set_qlp_coeff_precision(). + */ +unsigned FLAC__stream_encoder_get_qlp_coeff_precision(const FLAC__StreamEncoder *encoder); + +/** Get the qlp coefficient precision search flag. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See FLAC__stream_encoder_set_do_qlp_coeff_prec_search(). + */ FLAC__bool FLAC__stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__StreamEncoder *encoder); + +/** Get the "escape coding" flag. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See FLAC__stream_encoder_set_do_escape_coding(). + */ FLAC__bool FLAC__stream_encoder_get_do_escape_coding(const FLAC__StreamEncoder *encoder); + +/** Get the exhaustive model search flag. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See FLAC__stream_encoder_set_do_exhaustive_model_search(). + */ FLAC__bool FLAC__stream_encoder_get_do_exhaustive_model_search(const FLAC__StreamEncoder *encoder); -unsigned FLAC__stream_encoder_get_min_residual_partition_order(const FLAC__StreamEncoder *encoder); -unsigned FLAC__stream_encoder_get_max_residual_partition_order(const FLAC__StreamEncoder *encoder); -unsigned FLAC__stream_encoder_get_rice_parameter_search_dist(const FLAC__StreamEncoder *encoder); -/* - * Initialize the instance; should be called after construction and - * 'set' calls but before any of the 'process' calls. Will set and - * return the encoder state, which will be FLAC__STREAM_ENCODER_OK - * if initialization succeeded. +/** Get the minimum residual partition order setting. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See FLAC__stream_encoder_set_min_residual_partition_order(). + */ +unsigned FLAC__stream_encoder_get_min_residual_partition_order(const FLAC__StreamEncoder *encoder); + +/** Get maximum residual partition order setting. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See FLAC__stream_encoder_set_max_residual_partition_order(). + */ +unsigned FLAC__stream_encoder_get_max_residual_partition_order(const FLAC__StreamEncoder *encoder); + +/** Get the Rice parameter search distance setting. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See FLAC__stream_encoder_set_rice_parameter_search_dist(). + */ +unsigned FLAC__stream_encoder_get_rice_parameter_search_dist(const FLAC__StreamEncoder *encoder); + +/** Initialize the encoder instance. + * Should be called after FLAC__stream_encoder_new() and + * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process() + * or FLAC__stream_encoder_process_interleaved(). Will set and return + * the encoder state, which will be FLAC__STREAM_ENCODER_OK if + * initialization succeeded. + * + * The call to FLAC__stream_encoder_init() currently will also immediately + * call the write callback with the \c fLaC signature and all the encoded + * metadata. + * + * \param encoder An uninitialized encoder instance. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__StreamEncoderState + * \c FLAC__STREAM_ENCODER_OK if initialization was successful; see + * FLAC__StreamEncoderState for the meanings of other return values. */ FLAC__StreamEncoderState FLAC__stream_encoder_init(FLAC__StreamEncoder *encoder); -/* - * Flush the encoding buffer, release resources, and return the encoder - * state to FLAC__STREAM_ENCODER_UNINITIALIZED. Note that this can - * generate one or more write_callback()s before returning. +/** Finish the encoding process. + * Flushes the encoding buffer, releases resources, and returns the encoder + * state to FLAC__STREAM_ENCODER_UNINITIALIZED. Note that this can + * generate one or more write callbacks before returning, and will + * generate a metadata callback. + * + * In the event of a prematurely-terminated encode, it is not strictly + * necessary to call this immediately before FLAC__stream_encoder_delete() + * but it is good practice to match every FLAC__stream_encoder_init() + * with a FLAC__stream_encoder_finish(). + * + * \param encoder An uninitialized encoder instance. + * \assert + * \code encoder != NULL \endcode */ void FLAC__stream_encoder_finish(FLAC__StreamEncoder *encoder); -/* - * Methods for encoding the data +/** Submit data for encoding. + * This version allows you to supply the input data via an array of + * pointers, each pointer pointing to an array of \a samples samples + * representing one channel. The samples need not be block-aligned, + * but each channel should have the same number of samples. + * + * \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 FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK \endcode + * \retval FLAC__bool + * \c true if successful, else \c false; in this case, check the + * encoder state with FLAC__stream_encoder_get_state() to see what + * went wrong. */ FLAC__bool FLAC__stream_encoder_process(FLAC__StreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples); + +/** Submit data for encoding. + * This version allows you to supply the input data where the channels + * are interleaved into a single array (i.e. channel0_sample0, + * channel1_sample0, ... , channelN_sample0, channel0_sample1, ...). + * The samples need not be block-aligned but they must be + * sample-aligned, i.e. the first value should be channel0_sample0 + * and the last value channelN_sampleM. + * + * + * \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 + * FLAC__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 FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK \endcode + * \retval FLAC__bool + * \c true if successful, else \c false; in this case, check the + * encoder state with FLAC__stream_encoder_get_state() to see what + * went wrong. + */ FLAC__bool FLAC__stream_encoder_process_interleaved(FLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples); /* \} */