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