From ec5ea04c05efadd33951632af8987c1da60469bc Mon Sep 17 00:00:00 2001 From: Josh Coalson Date: Sun, 25 Aug 2002 05:27:53 +0000 Subject: [PATCH] more comments --- include/FLAC/stream_decoder.h | 24 ++++++++++++------------ include/FLAC/stream_encoder.h | 24 +++++++++++++++++++++--- 2 files changed, 33 insertions(+), 15 deletions(-) diff --git a/include/FLAC/stream_decoder.h b/include/FLAC/stream_decoder.h index d2a21206..9ab781b9 100644 --- a/include/FLAC/stream_decoder.h +++ b/include/FLAC/stream_decoder.h @@ -100,16 +100,16 @@ extern "C" { * 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 + * decoded a metadata block. In a valid FLAC file there will always be + * one STREAMINFO block, 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. @@ -442,8 +442,8 @@ FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder, FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteCallback value); /** 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, + * The supplied function will be called when the decoder has decoded a metadata + * block. In a valid FLAC file there will always be one STREAMINFO block, * 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 diff --git a/include/FLAC/stream_encoder.h b/include/FLAC/stream_encoder.h index 0813d6fa..a33530fc 100644 --- a/include/FLAC/stream_encoder.h +++ b/include/FLAC/stream_encoder.h @@ -227,7 +227,11 @@ typedef enum { /**< An error occurred while writing the stream; usually, the write_callback returned an error. */ FLAC__STREAM_ENCODER_INVALID_METADATA, - /**< The metadata input to the encoder is invalid. */ + /**< The metadata input to the encoder is invalid, in one of the following ways: + * - FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0 + * - It contains an illegal SEEKTABLE as checked by FLAC__format_seektable_is_legal() + * - It contains more than one SEEKTABLE block or more than one VORBIS_COMMENT block + */ FLAC__STREAM_ENCODER_FATAL_ERROR_WHILE_ENCODING, /**< An error occurred while writing the stream; usually, the write_callback returned an error. */ @@ -616,8 +620,22 @@ FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder * * Otherwise, the encoder will not modify or free the blocks. It is up * to the caller to free the metadata blocks after encoding. * - * The STREAMINFO block is always written and no STREAMINFO block may - * occur in the supplied array. + * \note + * The encoder stores only the \a metadata pointer; the passed-in array + * must survive at least until after FLAC__stream_encoder_init() returns. + * Do not modify the array or free the blocks until then. + * + * \note + * The STREAMINFO block is always written and no STREAMINFO block may + * occur in the supplied array. + * + * \note + * A VORBIS_COMMENT block may be supplied. The vendor string in it + * will be ignored. libFLAC will use it's own vendor string. libFLAC + * will not modify the passed-in VORBIS_COMMENT's vendor string, it + * will simply write it's own into the stream. If no VORBIS_COMMENT + * block is present in the \a metadata array, libFLAC will write an + * empty one, containing only the vendor string. * * \default \c NULL, 0 * \param encoder An encoder instance to set.