minor comments
[flac.git] / include / OggFLAC / stream_encoder.h
1 /* libOggFLAC - Free Lossless Audio Codec + Ogg library
2  * Copyright (C) 2002,2003  Josh Coalson
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  *
8  * - Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  *
11  * - Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the distribution.
14  *
15  * - Neither the name of the Xiph.org Foundation nor the names of its
16  * contributors may be used to endorse or promote products derived from
17  * this software without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
23  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
24  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
25  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
26  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
27  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
28  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
29  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30  */
31
32 #ifndef OggFLAC__STREAM_ENCODER_H
33 #define OggFLAC__STREAM_ENCODER_H
34
35 #include "export.h"
36
37 #include "FLAC/stream_encoder.h"
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42
43
44 /** \file include/OggFLAC/stream_encoder.h
45  *
46  *  \brief
47  *  This module contains the functions which implement the stream
48  *  encoder.
49  *
50  *  See the detailed documentation in the
51  *  \link oggflac_stream_encoder stream encoder \endlink module.
52  */
53
54 /** \defgroup oggflac_encoder OggFLAC/ *_encoder.h: encoder interfaces
55  *  \ingroup oggflac
56  *
57  *  \brief
58  *  This module describes the three encoder layers provided by libOggFLAC.
59  *
60  * libOggFLAC currently provides the same three layers of access as libFLAC;
61  * the interfaces are nearly identical, with the addition of a method for
62  * specifying the Ogg serial number.  See the \link flac_encoder FLAC
63  * encoder module \endlink for full documentation.
64  */
65
66 /** \defgroup oggflac_stream_encoder OggFLAC/stream_encoder.h: stream encoder interface
67  *  \ingroup oggflac_encoder
68  *
69  *  \brief
70  *  This module contains the functions which implement the stream
71  *  encoder.
72  *
73  * The interface here is nearly identical to FLAC's stream encoder,
74  * including the callbacks, with the addition of
75  * OggFLAC__stream_encoder_set_serial_number().  See the
76  * \link flac_stream_encoder FLAC stream encoder module \endlink
77  * for full documentation.
78  *
79  * \{
80  */
81
82
83 /** State values for an OggFLAC__StreamEncoder
84  *
85  *  The encoder's state can be obtained by calling OggFLAC__stream_encoder_get_state().
86  */
87 typedef enum {
88
89         OggFLAC__STREAM_ENCODER_OK = 0,
90         /**< The encoder is in the normal OK state. */
91
92         OggFLAC__STREAM_ENCODER_OGG_ERROR,
93         /**< An error occurred in the underlying Ogg layer.  */
94
95         OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR,
96         /**< An error occurred in the underlying FLAC stream encoder;
97          * check OggFLAC__stream_encoder_get_FLAC_stream_encoder_state().
98          */
99
100         OggFLAC__STREAM_ENCODER_INVALID_CALLBACK,
101         /**< The encoder was initialized before setting all the required callbacks. */
102
103         OggFLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
104         /**< Memory allocation failed. */
105
106         OggFLAC__STREAM_ENCODER_ALREADY_INITIALIZED,
107         /**< OggFLAC__stream_encoder_init() was called when the encoder was
108          * already initialized, usually because
109          * OggFLAC__stream_encoder_finish() was not called.
110          */
111
112         OggFLAC__STREAM_ENCODER_UNINITIALIZED
113         /**< The encoder is in the uninitialized state. */
114
115 } OggFLAC__StreamEncoderState;
116
117 /** Maps an OggFLAC__StreamEncoderState to a C string.
118  *
119  *  Using an OggFLAC__StreamEncoderState as the index to this array
120  *  will give the string equivalent.  The contents should not be modified.
121  */
122 extern OggFLAC_API const char * const OggFLAC__StreamEncoderStateString[];
123
124
125 /***********************************************************************
126  *
127  * class OggFLAC__StreamEncoder
128  *
129  ***********************************************************************/
130
131 struct OggFLAC__StreamEncoderProtected;
132 struct OggFLAC__StreamEncoderPrivate;
133 /** The opaque structure definition for the stream encoder type.
134  *  See the \link oggflac_stream_encoder stream encoder module \endlink
135  *  for a detailed description.
136  */
137 typedef struct {
138         struct OggFLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
139         struct OggFLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
140 } OggFLAC__StreamEncoder;
141
142 /** Signature for the write callback.
143  *  See OggFLAC__stream_encoder_set_write_callback()
144  *  and FLAC__StreamEncoderWriteCallback for more info.
145  *
146  * \param  encoder  The encoder instance calling the callback.
147  * \param  buffer   An array of encoded data of length \a bytes.
148  * \param  bytes    The byte length of \a buffer.
149  * \param  samples  The number of samples encoded by \a buffer.
150  *                  \c 0 has a special meaning; see
151  *                  OggFLAC__stream_encoder_set_write_callback().
152  * \param  current_frame  The number of current frame being encoded.
153  * \param  client_data  The callee's client data set through
154  *                      OggFLAC__stream_encoder_set_client_data().
155  * \retval FLAC__StreamEncoderWriteStatus
156  *    The callee's return status.
157  */
158 typedef FLAC__StreamEncoderWriteStatus (*OggFLAC__StreamEncoderWriteCallback)(const OggFLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
159
160 /** Signature for the metadata callback.
161  *  See OggFLAC__stream_encoder_set_metadata_callback()
162  *  and FLAC__stream_encoder_set_metadata_callback() for more info.
163  *
164  * \param  encoder      The encoder instance calling the callback.
165  * \param  metadata     The final populated STREAMINFO block.
166  * \param  client_data  The callee's client data set through
167  *                      FLAC__stream_encoder_set_client_data().
168  */
169 typedef void (*OggFLAC__StreamEncoderMetadataCallback)(const OggFLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
170
171
172 /***********************************************************************
173  *
174  * Class constructor/destructor
175  *
176  ***********************************************************************/
177
178 /** Create a new stream encoder instance.  The instance is created with
179  *  default settings; see the individual OggFLAC__stream_encoder_set_*()
180  *  functions for each setting's default.
181  *
182  * \retval OggFLAC__StreamEncoder*
183  *    \c NULL if there was an error allocating memory, else the new instance.
184  */
185 OggFLAC_API OggFLAC__StreamEncoder *OggFLAC__stream_encoder_new();
186
187 /** Free an encoder instance.  Deletes the object pointed to by \a encoder.
188  *
189  * \param encoder  A pointer to an existing encoder.
190  * \assert
191  *    \code encoder != NULL \endcode
192  */
193 OggFLAC_API void OggFLAC__stream_encoder_delete(OggFLAC__StreamEncoder *encoder);
194
195
196 /***********************************************************************
197  *
198  * Public class method prototypes
199  *
200  ***********************************************************************/
201
202 /** Set the serial number for the FLAC stream.
203  *
204  * \default \c NULL, 0
205  * \param  encoder        An encoder instance to set.
206  * \param  serial_number  See above.
207  * \assert
208  *    \code encoder != NULL \endcode
209  * \retval FLAC__bool
210  *    \c false if the encoder is already initialized, else \c true.
211  */
212 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_serial_number(OggFLAC__StreamEncoder *encoder, long serial_number);
213
214 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_verify()
215  *
216  * \default \c false
217  * \param  encoder  An encoder instance to set.
218  * \param  value    Flag value (see above).
219  * \assert
220  *    \code encoder != NULL \endcode
221  * \retval FLAC__bool
222  *    \c false if the encoder is already initialized, else \c true.
223  */
224 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_verify(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
225
226 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_streamable_subset()
227  *
228  * \default \c true
229  * \param  encoder  An encoder instance to set.
230  * \param  value    Flag value (see above).
231  * \assert
232  *    \code encoder != NULL \endcode
233  * \retval FLAC__bool
234  *    \c false if the encoder is already initialized, else \c true.
235  */
236 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_streamable_subset(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
237
238 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_mid_side_stereo()
239  *
240  * \default \c false
241  * \param  encoder  An encoder instance to set.
242  * \param  value    Flag value (see above).
243  * \assert
244  *    \code encoder != NULL \endcode
245  * \retval FLAC__bool
246  *    \c false if the encoder is already initialized, else \c true.
247  */
248 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_mid_side_stereo(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
249
250 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_loose_mid_side_stereo()
251  *
252  * \default \c false
253  * \param  encoder  An encoder instance to set.
254  * \param  value    Flag value (see above).
255  * \assert
256  *    \code encoder != NULL \endcode
257  * \retval FLAC__bool
258  *    \c false if the encoder is already initialized, else \c true.
259  */
260 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_loose_mid_side_stereo(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
261
262 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_channels()
263  *
264  * \default \c 2
265  * \param  encoder  An encoder instance to set.
266  * \param  value    See above.
267  * \assert
268  *    \code encoder != NULL \endcode
269  * \retval FLAC__bool
270  *    \c false if the encoder is already initialized, else \c true.
271  */
272 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_channels(OggFLAC__StreamEncoder *encoder, unsigned value);
273
274 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_bits_per_sample()
275  *
276  * \default \c 16
277  * \param  encoder  An encoder instance to set.
278  * \param  value    See above.
279  * \assert
280  *    \code encoder != NULL \endcode
281  * \retval FLAC__bool
282  *    \c false if the encoder is already initialized, else \c true.
283  */
284 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_bits_per_sample(OggFLAC__StreamEncoder *encoder, unsigned value);
285
286 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_sample_rate()
287  *
288  * \default \c 44100
289  * \param  encoder  An encoder instance to set.
290  * \param  value    See above.
291  * \assert
292  *    \code encoder != NULL \endcode
293  * \retval FLAC__bool
294  *    \c false if the encoder is already initialized, else \c true.
295  */
296 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_sample_rate(OggFLAC__StreamEncoder *encoder, unsigned value);
297
298 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_blocksize()
299  *
300  * \default \c 1152
301  * \param  encoder  An encoder instance to set.
302  * \param  value    See above.
303  * \assert
304  *    \code encoder != NULL \endcode
305  * \retval FLAC__bool
306  *    \c false if the encoder is already initialized, else \c true.
307  */
308 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_blocksize(OggFLAC__StreamEncoder *encoder, unsigned value);
309
310 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_lpc_order()
311  *
312  * \default \c 0
313  * \param  encoder  An encoder instance to set.
314  * \param  value    See above.
315  * \assert
316  *    \code encoder != NULL \endcode
317  * \retval FLAC__bool
318  *    \c false if the encoder is already initialized, else \c true.
319  */
320 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_max_lpc_order(OggFLAC__StreamEncoder *encoder, unsigned value);
321
322 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_precision()
323  *
324  * \default \c 0
325  * \param  encoder  An encoder instance to set.
326  * \param  value    See above.
327  * \assert
328  *    \code encoder != NULL \endcode
329  * \retval FLAC__bool
330  *    \c false if the encoder is already initialized, else \c true.
331  */
332 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_qlp_coeff_precision(OggFLAC__StreamEncoder *encoder, unsigned value);
333
334 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_qlp_coeff_prec_search()
335  *
336  * \default \c false
337  * \param  encoder  An encoder instance to set.
338  * \param  value    See above.
339  * \assert
340  *    \code encoder != NULL \endcode
341  * \retval FLAC__bool
342  *    \c false if the encoder is already initialized, else \c true.
343  */
344 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
345
346 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_escape_coding()
347  *
348  * \default \c false
349  * \param  encoder  An encoder instance to set.
350  * \param  value    See above.
351  * \assert
352  *    \code encoder != NULL \endcode
353  * \retval FLAC__bool
354  *    \c false if the encoder is already initialized, else \c true.
355  */
356 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_escape_coding(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
357
358 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_do_exhaustive_model_search()
359  *
360  * \default \c false
361  * \param  encoder  An encoder instance to set.
362  * \param  value    See above.
363  * \assert
364  *    \code encoder != NULL \endcode
365  * \retval FLAC__bool
366  *    \c false if the encoder is already initialized, else \c true.
367  */
368 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_do_exhaustive_model_search(OggFLAC__StreamEncoder *encoder, FLAC__bool value);
369
370 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_min_residual_partition_order()
371  *
372  * \default \c 0
373  * \param  encoder  An encoder instance to set.
374  * \param  value    See above.
375  * \assert
376  *    \code encoder != NULL \endcode
377  * \retval FLAC__bool
378  *    \c false if the encoder is already initialized, else \c true.
379  */
380 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_min_residual_partition_order(OggFLAC__StreamEncoder *encoder, unsigned value);
381
382 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_max_residual_partition_order()
383  *
384  * \default \c 0
385  * \param  encoder  An encoder instance to set.
386  * \param  value    See above.
387  * \assert
388  *    \code encoder != NULL \endcode
389  * \retval FLAC__bool
390  *    \c false if the encoder is already initialized, else \c true.
391  */
392 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_max_residual_partition_order(OggFLAC__StreamEncoder *encoder, unsigned value);
393
394 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_rice_parameter_search_dist()
395  *
396  * \default \c 0
397  * \param  encoder  An encoder instance to set.
398  * \param  value    See above.
399  * \assert
400  *    \code encoder != NULL \endcode
401  * \retval FLAC__bool
402  *    \c false if the encoder is already initialized, else \c true.
403  */
404 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_rice_parameter_search_dist(OggFLAC__StreamEncoder *encoder, unsigned value);
405
406 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_total_samples_estimate()
407  *
408  * \default \c 0
409  * \param  encoder  An encoder instance to set.
410  * \param  value    See above.
411  * \assert
412  *    \code encoder != NULL \endcode
413  * \retval FLAC__bool
414  *    \c false if the encoder is already initialized, else \c true.
415  */
416 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_total_samples_estimate(OggFLAC__StreamEncoder *encoder, FLAC__uint64 value);
417
418 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_metadata()
419  *
420  * \default \c NULL, 0
421  * \param  encoder     An encoder instance to set.
422  * \param  metadata    See above.
423  * \param  num_blocks  See above.
424  * \assert
425  *    \code encoder != NULL \endcode
426  * \retval FLAC__bool
427  *    \c false if the encoder is already initialized, else \c true.
428  */
429 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_metadata(OggFLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
430
431 /** Set the write callback.
432  *  This is inherited from FLAC__StreamEncoder; see
433  *  FLAC__stream_encoder_set_write_callback().
434  *
435  * \note
436  * Unlike the FLAC stream encoder write callback, the Ogg stream
437  * encoder write callback will be called twice when writing audio
438  * frames; once for the page header, and once for the page body.
439  * When writing the page header, the \a samples argument to the
440  * write callback will be \c 0.
441  *
442  * \note
443  * The callback is mandatory and must be set before initialization.
444  *
445  * \default \c NULL
446  * \param  encoder  An encoder instance to set.
447  * \param  value    See above.
448  * \assert
449  *    \code encoder != NULL \endcode
450  *    \code value != NULL \endcode
451  * \retval FLAC__bool
452  *    \c false if the encoder is already initialized, else \c true.
453  */
454 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_write_callback(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderWriteCallback value);
455
456 /** Set the metadata callback.
457  *  This is inherited from FLAC__StreamEncoder; see
458  *  FLAC__stream_encoder_set_metadata_callback().
459  *
460  * \note
461  * The callback is mandatory and must be set before initialization.
462  *
463  * \default \c NULL
464  * \param  encoder  An encoder instance to set.
465  * \param  value    See above.
466  * \assert
467  *    \code encoder != NULL \endcode
468  *    \code value != NULL \endcode
469  * \retval FLAC__bool
470  *    \c false if the encoder is already initialized, else \c true.
471  */
472 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_metadata_callback(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderMetadataCallback value);
473
474 /** Set the client data to be passed back to callbacks.
475  *  This value will be supplied to callbacks in their \a client_data
476  *  argument.
477  *
478  * \default \c NULL
479  * \param  encoder  An encoder instance to set.
480  * \param  value    See above.
481  * \assert
482  *    \code encoder != NULL \endcode
483  * \retval FLAC__bool
484  *    \c false if the encoder is already initialized, else \c true.
485  */
486 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_client_data(OggFLAC__StreamEncoder *encoder, void *value);
487
488 /** Get the current encoder state.
489  *
490  * \param  encoder  An encoder instance to query.
491  * \assert
492  *    \code encoder != NULL \endcode
493  * \retval OggFLAC__StreamEncoderState
494  *    The current encoder state.
495  */
496 OggFLAC_API OggFLAC__StreamEncoderState OggFLAC__stream_encoder_get_state(const OggFLAC__StreamEncoder *encoder);
497
498 /** Get the state of the underlying FLAC stream encoder.
499  *  Useful when the stream encoder state is
500  *  \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR.
501  *
502  * \param  encoder  An encoder instance to query.
503  * \assert
504  *    \code encoder != NULL \endcode
505  * \retval FLAC__StreamEncoderState
506  *    The FLAC stream encoder state.
507  */
508 OggFLAC_API FLAC__StreamEncoderState OggFLAC__stream_encoder_get_FLAC_stream_encoder_state(const OggFLAC__StreamEncoder *encoder);
509
510 /** Get the state of the underlying FLAC stream encoder's verify decoder.
511  *  Useful when the stream encoder state is
512  *  \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR and the
513  *  FLAC encoder state is \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
514  *
515  * \param  encoder  An encoder instance to query.
516  * \assert
517  *    \code encoder != NULL \endcode
518  * \retval FLAC__StreamDecoderState
519  *    The FLAC verify decoder state.
520  */
521 OggFLAC_API FLAC__StreamDecoderState OggFLAC__stream_encoder_get_verify_decoder_state(const OggFLAC__StreamEncoder *encoder);
522
523 /** Get the current encoder state as a C string.
524  *  This version automatically resolves
525  *  \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR by getting the
526  *  FLAC stream encoder's state.
527  *
528  * \param  encoder  A encoder instance to query.
529  * \assert
530  *    \code encoder != NULL \endcode
531  * \retval const char *
532  *    The encoder state as a C string.  Do not modify the contents.
533  */
534 OggFLAC_API const char *OggFLAC__stream_encoder_get_resolved_state_string(const OggFLAC__StreamEncoder *encoder);
535
536 /** Get relevant values about the nature of a verify decoder error.
537  *  Inherited from FLAC__stream_encoder_get_verify_decoder_error_stats().
538  *  Useful when the stream encoder state is
539  *  \c OggFLAC__STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR and the
540  *  FLAC stream encoder state is
541  *  \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
542  *
543  * \param  encoder  An encoder instance to query.
544  * \param  absolute_sample  The absolute sample number of the mismatch.
545  * \param  frame_number  The number of the frame in which the mismatch occurred.
546  * \param  channel       The channel in which the mismatch occurred.
547  * \param  sample        The number of the sample (relative to the frame) in
548  *                       which the mismatch occurred.
549  * \param  expected      The expected value for the sample in question.
550  * \param  got           The actual value returned by the decoder.
551  * \assert
552  *    \code encoder != NULL \endcode
553  *    \code absolute_sample != NULL \endcode
554  *    \code frame_number != NULL \endcode
555  *    \code channel != NULL \endcode
556  *    \code sample != NULL \endcode
557  *    \code expected != NULL \endcode
558  */
559 OggFLAC_API void OggFLAC__stream_encoder_get_verify_decoder_error_stats(const OggFLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
560
561 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_verify()
562  *
563  * \param  encoder  An encoder instance to query.
564  * \assert
565  *    \code encoder != NULL \endcode
566  * \retval FLAC__bool
567  *    See OggFLAC__stream_encoder_set_verify().
568  */
569 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_verify(const OggFLAC__StreamEncoder *encoder);
570
571 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_streamable_subset()
572  *
573  * \param  encoder  An encoder instance to query.
574  * \assert
575  *    \code encoder != NULL \endcode
576  * \retval FLAC__bool
577  *    See OggFLAC__stream_encoder_set_streamable_subset().
578  */
579 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_streamable_subset(const OggFLAC__StreamEncoder *encoder);
580
581 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_mid_side_stereo()
582  *
583  * \param  encoder  An encoder instance to query.
584  * \assert
585  *    \code encoder != NULL \endcode
586  * \retval FLAC__bool
587  *    See OggFLAC__stream_encoder_get_do_mid_side_stereo().
588  */
589 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_mid_side_stereo(const OggFLAC__StreamEncoder *encoder);
590
591 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_loose_mid_side_stereo()
592  *
593  * \param  encoder  An encoder instance to query.
594  * \assert
595  *    \code encoder != NULL \endcode
596  * \retval FLAC__bool
597  *    See OggFLAC__stream_encoder_set_loose_mid_side_stereo().
598  */
599 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_loose_mid_side_stereo(const OggFLAC__StreamEncoder *encoder);
600
601 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_channels()
602  *
603  * \param  encoder  An encoder instance to query.
604  * \assert
605  *    \code encoder != NULL \endcode
606  * \retval unsigned
607  *    See OggFLAC__stream_encoder_set_channels().
608  */
609 OggFLAC_API unsigned OggFLAC__stream_encoder_get_channels(const OggFLAC__StreamEncoder *encoder);
610
611 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_bits_per_sample()
612  *
613  * \param  encoder  An encoder instance to query.
614  * \assert
615  *    \code encoder != NULL \endcode
616  * \retval unsigned
617  *    See OggFLAC__stream_encoder_set_bits_per_sample().
618  */
619 OggFLAC_API unsigned OggFLAC__stream_encoder_get_bits_per_sample(const OggFLAC__StreamEncoder *encoder);
620
621 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_sample_rate()
622  *
623  * \param  encoder  An encoder instance to query.
624  * \assert
625  *    \code encoder != NULL \endcode
626  * \retval unsigned
627  *    See OggFLAC__stream_encoder_set_sample_rate().
628  */
629 OggFLAC_API unsigned OggFLAC__stream_encoder_get_sample_rate(const OggFLAC__StreamEncoder *encoder);
630
631 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_blocksize()
632  *
633  * \param  encoder  An encoder instance to query.
634  * \assert
635  *    \code encoder != NULL \endcode
636  * \retval unsigned
637  *    See OggFLAC__stream_encoder_set_blocksize().
638  */
639 OggFLAC_API unsigned OggFLAC__stream_encoder_get_blocksize(const OggFLAC__StreamEncoder *encoder);
640
641 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_max_lpc_order()
642  *
643  * \param  encoder  An encoder instance to query.
644  * \assert
645  *    \code encoder != NULL \endcode
646  * \retval unsigned
647  *    See OggFLAC__stream_encoder_set_max_lpc_order().
648  */
649 OggFLAC_API unsigned OggFLAC__stream_encoder_get_max_lpc_order(const OggFLAC__StreamEncoder *encoder);
650
651 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_qlp_coeff_precision()
652  *
653  * \param  encoder  An encoder instance to query.
654  * \assert
655  *    \code encoder != NULL \endcode
656  * \retval unsigned
657  *    See OggFLAC__stream_encoder_set_qlp_coeff_precision().
658  */
659 OggFLAC_API unsigned OggFLAC__stream_encoder_get_qlp_coeff_precision(const OggFLAC__StreamEncoder *encoder);
660
661 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_qlp_coeff_prec_search()
662  *
663  * \param  encoder  An encoder instance to query.
664  * \assert
665  *    \code encoder != NULL \endcode
666  * \retval FLAC__bool
667  *    See OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search().
668  */
669 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__StreamEncoder *encoder);
670
671 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_escape_coding()
672  *
673  * \param  encoder  An encoder instance to query.
674  * \assert
675  *    \code encoder != NULL \endcode
676  * \retval FLAC__bool
677  *    See OggFLAC__stream_encoder_set_do_escape_coding().
678  */
679 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_escape_coding(const OggFLAC__StreamEncoder *encoder);
680
681 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_do_exhaustive_model_search()
682  *
683  * \param  encoder  An encoder instance to query.
684  * \assert
685  *    \code encoder != NULL \endcode
686  * \retval FLAC__bool
687  *    See OggFLAC__stream_encoder_set_do_exhaustive_model_search().
688  */
689 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_get_do_exhaustive_model_search(const OggFLAC__StreamEncoder *encoder);
690
691 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_min_residual_partition_order()
692  *
693  * \param  encoder  An encoder instance to query.
694  * \assert
695  *    \code encoder != NULL \endcode
696  * \retval unsigned
697  *    See OggFLAC__stream_encoder_set_min_residual_partition_order().
698  */
699 OggFLAC_API unsigned OggFLAC__stream_encoder_get_min_residual_partition_order(const OggFLAC__StreamEncoder *encoder);
700
701 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_man_residual_partition_order()
702  *
703  * \param  encoder  An encoder instance to query.
704  * \assert
705  *    \code encoder != NULL \endcode
706  * \retval unsigned
707  *    See OggFLAC__stream_encoder_set_max_residual_partition_order().
708  */
709 OggFLAC_API unsigned OggFLAC__stream_encoder_get_max_residual_partition_order(const OggFLAC__StreamEncoder *encoder);
710
711 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_rice_parameter_search_dist()
712  *
713  * \param  encoder  An encoder instance to query.
714  * \assert
715  *    \code encoder != NULL \endcode
716  * \retval unsigned
717  *    See OggFLAC__stream_encoder_set_rice_parameter_search_dist().
718  */
719 OggFLAC_API unsigned OggFLAC__stream_encoder_get_rice_parameter_search_dist(const OggFLAC__StreamEncoder *encoder);
720
721 /** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_get_total_samples_estimate()
722  *
723  * \param  encoder  An encoder instance to set.
724  * \assert
725  *    \code encoder != NULL \endcode
726  * \retval FLAC__uint64
727  *    See OggFLAC__stream_encoder_get_total_samples_estimate().
728  */
729 OggFLAC_API FLAC__uint64 OggFLAC__stream_encoder_get_total_samples_estimate(const OggFLAC__StreamEncoder *encoder);
730
731 /** Initialize the encoder instance.
732  *  Should be called after OggFLAC__stream_encoder_new() and
733  *  OggFLAC__stream_encoder_set_*() but before OggFLAC__stream_encoder_process()
734  *  or OggFLAC__stream_encoder_process_interleaved().  Will set and return
735  *  the encoder state, which will be OggFLAC__STREAM_ENCODER_OK if
736  *  initialization succeeded.
737  *
738  *  The call to OggFLAC__stream_encoder_init() currently will also immediately
739  *  call the write callback several times, once with the \c fLaC signature,
740  *  and once for each encoded metadata block.
741  *
742  * \param  encoder  An uninitialized encoder instance.
743  * \assert
744  *    \code encoder != NULL \endcode
745  * \retval OggFLAC__StreamEncoderState
746  *    \c OggFLAC__STREAM_ENCODER_OK if initialization was successful; see
747  *    OggFLAC__StreamEncoderState for the meanings of other return values.
748  */
749 OggFLAC_API OggFLAC__StreamEncoderState OggFLAC__stream_encoder_init(OggFLAC__StreamEncoder *encoder);
750
751 /** Finish the encoding process.
752  *  Flushes the encoding buffer, releases resources, resets the encoder
753  *  settings to their defaults, and returns the encoder state to
754  *  OggFLAC__STREAM_ENCODER_UNINITIALIZED.  Note that this can generate
755  *  one or more write callbacks before returning.
756  *
757  *  In the event of a prematurely-terminated encode, it is not strictly
758  *  necessary to call this immediately before OggFLAC__stream_encoder_delete()
759  *  but it is good practice to match every OggFLAC__stream_encoder_init()
760  *  with an OggFLAC__stream_encoder_finish().
761  *
762  * \param  encoder  An uninitialized encoder instance.
763  * \assert
764  *    \code encoder != NULL \endcode
765  */
766 OggFLAC_API void OggFLAC__stream_encoder_finish(OggFLAC__StreamEncoder *encoder);
767
768 /** Submit data for encoding.
769  * This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process().
770  *
771  * \param  encoder  An initialized encoder instance in the OK state.
772  * \param  buffer   An array of pointers to each channel's signal.
773  * \param  samples  The number of samples in one channel.
774  * \assert
775  *    \code encoder != NULL \endcode
776  *    \code OggFLAC__stream_encoder_get_state(encoder) == OggFLAC__STREAM_ENCODER_OK \endcode
777  * \retval FLAC__bool
778  *    \c true if successful, else \c false; in this case, check the
779  *    encoder state with OggFLAC__stream_encoder_get_state() to see what
780  *    went wrong.
781  */
782 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_process(OggFLAC__StreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
783
784 /** Submit data for encoding.
785  * This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_process_interleaved().
786  *
787  * \param  encoder  An initialized encoder instance in the OK state.
788  * \param  buffer   An array of channel-interleaved data (see above).
789  * \param  samples  The number of samples in one channel, the same as for
790  *                  OggFLAC__stream_encoder_process().  For example, if
791  *                  encoding two channels, \c 1000 \a samples corresponds
792  *                  to a \a buffer of 2000 values.
793  * \assert
794  *    \code encoder != NULL \endcode
795  *    \code OggFLAC__stream_encoder_get_state(encoder) == OggFLAC__STREAM_ENCODER_OK \endcode
796  * \retval FLAC__bool
797  *    \c true if successful, else \c false; in this case, check the
798  *    encoder state with OggFLAC__stream_encoder_get_state() to see what
799  *    went wrong.
800  */
801 OggFLAC_API FLAC__bool OggFLAC__stream_encoder_process_interleaved(OggFLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
802
803 /* \} */
804
805 #ifdef __cplusplus
806 }
807 #endif
808
809 #endif