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