more doxygen comments
[flac.git] / include / FLAC / stream_encoder.h
index 7ef9574..0813d6f 100644 (file)
@@ -21,6 +21,7 @@
 #define FLAC__STREAM_ENCODER_H
 
 #include "format.h"
+#include "stream_decoder.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -114,8 +115,8 @@ extern "C" {
  *   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.
+ * call the write callback several times, once with the \c fLaC signature,
+ * and once for each encoded metadata block.
  *
  * After initializing the instance, the user may feed audio data to the
  * encoder in one of two ways:
@@ -176,6 +177,16 @@ typedef enum {
        FLAC__STREAM_ENCODER_OK = 0,
        /**< The encoder is in the normal OK state. */
 
+       FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR,
+       /**< An error occurred in the underlying verify stream decoder;
+        * check FLAC__stream_encoder_get_verify_decoder_state().
+        */
+
+       FLAC__STREAM_ENCODER_VERIFY_MISMATCH_IN_AUDIO_DATA,
+       /**< The verify decoder detected a mismatch between the original
+        * audio signal and the decoded audio signal.
+        */
+
        FLAC__STREAM_ENCODER_INVALID_CALLBACK,
        /**< The encoder was initialized before setting all the required callbacks. */
 
@@ -249,10 +260,10 @@ extern const char * const FLAC__StreamEncoderStateString[];
  */
 typedef enum {
 
-       FLAC__STREAM_ENCODER_WRITE_OK = 0,
+       FLAC__STREAM_ENCODER_WRITE_STATUS_OK = 0,
        /**< The write was OK and encoding can continue. */
 
-       FLAC__STREAM_ENCODER_WRITE_FATAL_ERROR
+       FLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR
        /**< An unrecoverable error occurred.  The encoder will return from the process call. */
 
 } FLAC__StreamEncoderWriteStatus;
@@ -282,6 +293,33 @@ typedef struct {
        struct FLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
 } FLAC__StreamEncoder;
 
+/** Signature for the write callback.
+ *  See FLAC__stream_encoder_set_write_callback() for more info.
+ *
+ * \param  encoder  The encoder instance calling the callback.
+ * \param  buffer   An array of encoded data of length \a bytes.
+ * \param  bytes    The byte length of \a buffer.
+ * \param  samples  The number of samples encoded by \a buffer.
+ *                  \c 0 has a special meaning; see
+ *                  FLAC__stream_encoder_set_write_callback().
+ * \param  current_frame  The number of the current frame being encoded.
+ * \param  client_data  The callee's client data set through
+ *                      FLAC__stream_encoder_set_client_data().
+ * \retval FLAC__StreamDecoderWriteStatus
+ *    The callee's return status.
+ */
+typedef FLAC__StreamEncoderWriteStatus (*FLAC__StreamEncoderWriteCallback)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
+
+/** Signature for the metadata callback.
+ *  See FLAC__stream_encoder_set_metadata_callback() for more info.
+ *
+ * \param  encoder      The encoder instance calling the callback.
+ * \param  metadata     The final populated STREAMINFO block.
+ * \param  client_data  The callee's client data set through
+ *                      FLAC__stream_encoder_set_client_data().
+ */
+typedef void (*FLAC__StreamEncoderMetadataCallback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
+
 
 /***********************************************************************
  *
@@ -312,6 +350,22 @@ void FLAC__stream_encoder_delete(FLAC__StreamEncoder *encoder);
  *
  ***********************************************************************/
 
+/** Set the "verify" flag.  If \c true, the encoder will verify it's own
+ *  encoded output by feeding it through an internal decoder and comparing
+ *  the original signal against the decoded signal.  If a mismatch occurs,
+ *  the process call will return \c false.  Note that this will slow the
+ *  encoding process by the extra time required for decoding and comparison.
+ *
+ * \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 FLAC__stream_encoder_set_verify(FLAC__StreamEncoder *encoder, FLAC__bool value);
+
 /** 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
@@ -559,7 +613,8 @@ FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder *
  *  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.
+ *  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.
@@ -600,7 +655,7 @@ FLAC__bool FLAC__stream_encoder_set_metadata(FLAC__StreamEncoder *encoder, FLAC_
  * \retval FLAC__bool
  *    \c false if the encoder is already initialized, else \c true.
  */
-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));
+FLAC__bool FLAC__stream_encoder_set_write_callback(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderWriteCallback value);
 
 /** Set the metadata callback.
  *  The supplied function will be called once at the end of encoding with
@@ -621,7 +676,7 @@ FLAC__bool FLAC__stream_encoder_set_write_callback(FLAC__StreamEncoder *encoder,
  * \retval FLAC__bool
  *    \c false if the encoder is already initialized, else \c true.
  */
-FLAC__bool FLAC__stream_encoder_set_metadata_callback(FLAC__StreamEncoder *encoder, void (*value)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data));
+FLAC__bool FLAC__stream_encoder_set_metadata_callback(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderMetadataCallback value);
 
 /** Set the client data to be passed back to callbacks.
  *  This value will be supplied to callbacks in their \a client_data
@@ -647,6 +702,47 @@ FLAC__bool FLAC__stream_encoder_set_client_data(FLAC__StreamEncoder *encoder, vo
  */
 FLAC__StreamEncoderState FLAC__stream_encoder_get_state(const FLAC__StreamEncoder *encoder);
 
+/** Get the state of the verify stream decoder.
+ *  Useful when 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 verify stream decoder state.
+ */
+FLAC__StreamDecoderState FLAC__stream_encoder_get_verify_decoder_state(const FLAC__StreamEncoder *encoder);
+
+/** Get relevant values about the nature of a verify decoder error.
+ *  Useful when the stream encoder state is
+ *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.  The arguments should
+ *  be addresses in which the stats will be returned, or NULL if value
+ *  is not desired.
+ *
+ * \param  encoder  An encoder instance to query.
+ * \param  absolute_sample  The absolute sample number of the mismatch.
+ * \param  frame_number  The number of the frame in which the mismatch occurred.
+ * \param  channel       The channel in which the mismatch occurred.
+ * \param  sample        The number of the sample (relative to the frame) in
+ *                       which the mismatch occurred.
+ * \param  expected      The expected value for the sample in question.
+ * \param  got           The actual value returned by the decoder.
+ * \assert
+ *    \code encoder != NULL \endcode
+ */
+void FLAC__stream_encoder_get_verify_decoder_error_stats(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
+
+/** Get the "verify" flag.
+ *
+ * \param  encoder  An encoder instance to query.
+ * \assert
+ *    \code encoder != NULL \endcode
+ * \retval FLAC__bool
+ *    See FLAC__stream_encoder_set_verify().
+ */
+FLAC__bool FLAC__stream_encoder_get_verify(const FLAC__StreamEncoder *encoder);
+
 /** Get the "streamable subset" flag.
  *
  * \param  encoder  An encoder instance to query.
@@ -682,7 +778,7 @@ FLAC__bool FLAC__stream_encoder_get_loose_mid_side_stereo(const FLAC__StreamEnco
  * \param  encoder  An encoder instance to query.
  * \assert
  *    \code encoder != NULL \endcode
- * \retval FLAC__bool
+ * \retval unsigned
  *    See FLAC__stream_encoder_set_channels().
  */
 unsigned FLAC__stream_encoder_get_channels(const FLAC__StreamEncoder *encoder);
@@ -692,7 +788,7 @@ unsigned FLAC__stream_encoder_get_channels(const FLAC__StreamEncoder *encoder);
  * \param  encoder  An encoder instance to query.
  * \assert
  *    \code encoder != NULL \endcode
- * \retval FLAC__bool
+ * \retval unsigned
  *    See FLAC__stream_encoder_set_bits_per_sample().
  */
 unsigned FLAC__stream_encoder_get_bits_per_sample(const FLAC__StreamEncoder *encoder);
@@ -702,7 +798,7 @@ unsigned FLAC__stream_encoder_get_bits_per_sample(const FLAC__StreamEncoder *enc
  * \param  encoder  An encoder instance to query.
  * \assert
  *    \code encoder != NULL \endcode
- * \retval FLAC__bool
+ * \retval unsigned
  *    See FLAC__stream_encoder_set_sample_rate().
  */
 unsigned FLAC__stream_encoder_get_sample_rate(const FLAC__StreamEncoder *encoder);
@@ -712,7 +808,7 @@ unsigned FLAC__stream_encoder_get_sample_rate(const FLAC__StreamEncoder *encoder
  * \param  encoder  An encoder instance to query.
  * \assert
  *    \code encoder != NULL \endcode
- * \retval FLAC__bool
+ * \retval unsigned
  *    See FLAC__stream_encoder_set_blocksize().
  */
 unsigned FLAC__stream_encoder_get_blocksize(const FLAC__StreamEncoder *encoder);
@@ -722,7 +818,7 @@ unsigned FLAC__stream_encoder_get_blocksize(const FLAC__StreamEncoder *encoder);
  * \param  encoder  An encoder instance to query.
  * \assert
  *    \code encoder != NULL \endcode
- * \retval FLAC__bool
+ * \retval unsigned
  *    See FLAC__stream_encoder_set_max_lpc_order().
  */
 unsigned FLAC__stream_encoder_get_max_lpc_order(const FLAC__StreamEncoder *encoder);
@@ -732,7 +828,7 @@ unsigned FLAC__stream_encoder_get_max_lpc_order(const FLAC__StreamEncoder *encod
  * \param  encoder  An encoder instance to query.
  * \assert
  *    \code encoder != NULL \endcode
- * \retval FLAC__bool
+ * \retval unsigned
  *    See FLAC__stream_encoder_set_qlp_coeff_precision().
  */
 unsigned FLAC__stream_encoder_get_qlp_coeff_precision(const FLAC__StreamEncoder *encoder);
@@ -772,7 +868,7 @@ FLAC__bool FLAC__stream_encoder_get_do_exhaustive_model_search(const FLAC__Strea
  * \param  encoder  An encoder instance to query.
  * \assert
  *    \code encoder != NULL \endcode
- * \retval FLAC__bool
+ * \retval unsigned
  *    See FLAC__stream_encoder_set_min_residual_partition_order().
  */
 unsigned FLAC__stream_encoder_get_min_residual_partition_order(const FLAC__StreamEncoder *encoder);
@@ -782,7 +878,7 @@ unsigned FLAC__stream_encoder_get_min_residual_partition_order(const FLAC__Strea
  * \param  encoder  An encoder instance to query.
  * \assert
  *    \code encoder != NULL \endcode
- * \retval FLAC__bool
+ * \retval unsigned
  *    See FLAC__stream_encoder_set_max_residual_partition_order().
  */
 unsigned FLAC__stream_encoder_get_max_residual_partition_order(const FLAC__StreamEncoder *encoder);
@@ -792,11 +888,24 @@ unsigned FLAC__stream_encoder_get_max_residual_partition_order(const FLAC__Strea
  * \param  encoder  An encoder instance to query.
  * \assert
  *    \code encoder != NULL \endcode
- * \retval FLAC__bool
+ * \retval unsigned
  *    See FLAC__stream_encoder_set_rice_parameter_search_dist().
  */
 unsigned FLAC__stream_encoder_get_rice_parameter_search_dist(const FLAC__StreamEncoder *encoder);
 
+/** Get the previously set estimate of the total samples to be encoded.
+ *  The encoder merely mimics back the value given to
+ *  FLAC__stream_encoder_set_total_samples_estimate() since it has no
+ *  other way of knowing how many samples the user will encode.
+ *
+ * \param  encoder  An encoder instance to set.
+ * \assert
+ *    \code encoder != NULL \endcode
+ * \retval FLAC__uint64
+ *    See FLAC__stream_encoder_get_total_samples_estimate().
+ */
+FLAC__uint64 FLAC__stream_encoder_get_total_samples_estimate(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()
@@ -805,8 +914,8 @@ unsigned FLAC__stream_encoder_get_rice_parameter_search_dist(const FLAC__StreamE
  *  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.
+ *  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