include/FLAC/seekable_stream_encoder.h

   1 /* libFLAC - Free Lossless Audio Codec 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 FLAC__SEEKABLE_STREAM_ENCODER_H
  21 #define FLAC__SEEKABLE_STREAM_ENCODER_H
  22
  23 #include "stream_encoder.h"
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29
  30 /** \file include/FLAC/seekable_stream_encoder.h
  31  *
  32  *  \brief
  33  *  This module contains the functions which implement the seekable stream
  34  *  encoder.
  35  *
  36  *  See the detailed documentation in the
  37  *  \link flac_seekable_stream_encoder seekable stream encoder \endlink module.
  38  */
  39
  40 /** \defgroup flac_seekable_stream_encoder FLAC/seekable_stream_encoder.h: seekable stream encoder interface
  41  *  \ingroup flac_encoder
  42  *
  43  *  \brief
  44  *  This module contains the functions which implement the seekable stream
  45  *  encoder.
  46  *
  47  * XXX (import)
  48  *
  49  * The seekable stream encoder is a wrapper around the
  50  * \link flac_stream_encoder stream encoder \endlink which (XXXimport)
  51  *
  52  * Make sure to read the detailed description of the
  53  * \link flac_stream_encoder stream encoder module \endlink since the
  54  * seekable stream encoder inherits much of its behavior.
  55  *
  56  * \note
  57  * The "set" functions may only be called when the encoder is in the
  58  * state FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED, i.e. after
  59  * FLAC__seekable_stream_encoder_new() or FLAC__seekable_stream_encoder_finish(), but
  60  * before FLAC__seekable_stream_encoder_init().  If this is the case they will
  61  * return \c true, otherwise \c false.
  62  *
  63  * \note
  64  * FLAC__seekable_stream_encoder_finish() resets all settings to the constructor
  65  * defaults, including the callbacks.
  66  *
  67  * \{
  68  */
  69
  70
  71 /** State values for a FLAC__SeekableStreamEncoder
  72  *
  73  *  The encoder's state can be obtained by calling FLAC__seekable_stream_encoder_get_state().
  74  */
  75 typedef enum {
  76
  77         FLAC__SEEKABLE_STREAM_ENCODER_OK = 0,
  78         /**< The encoder is in the normal OK state. */
  79
  80         FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR,
  81         /**< An error occurred in the underlying stream encoder;
  82          * check FLAC__seekable_stream_encoder_get_stream_encoder_state().
  83          */
  84
  85         FLAC__SEEKABLE_STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
  86         /**< Memory allocation failed. */
  87
  88         FLAC__SEEKABLE_STREAM_ENCODER_WRITE_ERROR,
  89         /**< The write callback returned an error. */
  90
  91         FLAC__SEEKABLE_STREAM_ENCODER_READ_ERROR,
  92         /**< The read callback returned an error. */
  93
  94         FLAC__SEEKABLE_STREAM_ENCODER_SEEK_ERROR,
  95         /**< The seek callback returned an error. */
  96
  97         FLAC__SEEKABLE_STREAM_ENCODER_ALREADY_INITIALIZED,
  98         /**< FLAC__seekable_stream_encoder_init() was called when the encoder was
  99          * already initialized, usually because
 100          * FLAC__seekable_stream_encoder_finish() was not called.
 101          */
 102
 103     FLAC__SEEKABLE_STREAM_ENCODER_INVALID_CALLBACK,
 104         /**< FLAC__seekable_stream_encoder_init() was called without all
 105          * callbacks being set.
 106          */
 107
 108     FLAC__SEEKABLE_STREAM_ENCODER_INVALID_SEEKTABLE,
 109         /**< An invalid seek table was passed is the metadata to
 110          * FLAC__seekable_stream_encoder_set_metadata().
 111          */
 112
 113         FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED
 114         /**< The encoder is in the uninitialized state. */
 115
 116 } FLAC__SeekableStreamEncoderState;
 117
 118 /** Maps a FLAC__SeekableStreamEncoderState to a C string.
 119  *
 120  *  Using a FLAC__SeekableStreamEncoderState as the index to this array
 121  *  will give the string equivalent.  The contents should not be modified.
 122  */
 123 /* @@@@ double-check mapping */
 124 extern const char * const FLAC__SeekableStreamEncoderStateString[];
 125
 126
 127 /** Return values for the FLAC__SeekableStreamEncoder seek callback.
 128  */
 129 typedef enum {
 130
 131         FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_OK,
 132         /**< The seek was OK and encoding can continue. */
 133
 134         FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_ERROR
 135         /**< An unrecoverable error occurred.  The encoder will return from the process call. */
 136
 137 } FLAC__SeekableStreamEncoderSeekStatus;
 138
 139 /** Maps a FLAC__SeekableStreamEncoderSeekStatus to a C string.
 140  *
 141  *  Using a FLAC__SeekableStreamEncoderSeekStatus as the index to this array
 142  *  will give the string equivalent.  The contents should not be modified.
 143  */
 144 extern const char * const FLAC__SeekableStreamEncoderSeekStatusString[];
 145
 146
 147 /***********************************************************************
 148  *
 149  * class FLAC__SeekableStreamEncoder
 150  *
 151  ***********************************************************************/
 152
 153 struct FLAC__SeekableStreamEncoderProtected;
 154 struct FLAC__SeekableStreamEncoderPrivate;
 155 /** The opaque structure definition for the seekable stream encoder type.
 156  *  See the \link flac_seekable_stream_encoder seekable stream encoder module \endlink
 157  *  for a detailed description.
 158  */
 159 typedef struct {
 160         struct FLAC__SeekableStreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
 161         struct FLAC__SeekableStreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
 162 } FLAC__SeekableStreamEncoder;
 163
 164
 165 /***********************************************************************
 166  *
 167  * Class constructor/destructor
 168  *
 169  ***********************************************************************/
 170
 171 /** Create a new seekable stream encoder instance.  The instance is created with
 172  *  default settings; see the individual FLAC__seekable_stream_encoder_set_*()
 173  *  functions for each setting's default.
 174  *
 175  * \retval FLAC__SeekableStreamEncoder*
 176  *    \c NULL if there was an error allocating memory, else the new instance.
 177  */
 178 FLAC__SeekableStreamEncoder *FLAC__seekable_stream_encoder_new();
 179
 180 /** Free an encoder instance.  Deletes the object pointed to by \a encoder.
 181  *
 182  * \param encoder  A pointer to an existing encoder.
 183  * \assert
 184  *    \code encoder != NULL \endcode
 185  */
 186 void FLAC__seekable_stream_encoder_delete(FLAC__SeekableStreamEncoder *encoder);
 187
 188 /***********************************************************************
 189  *
 190  * Public class method prototypes
 191  *
 192  ***********************************************************************/
 193
 194 /** This is inherited from FLAC__StreamEncoder; see
 195  *  FLAC__stream_encoder_set_streamable_subset().
 196  *
 197  * \default \c true
 198  * \param  encoder  An encoder instance to set.
 199  * \param  value    See above.
 200  * \assert
 201  *    \code encoder != NULL \endcode
 202  * \retval FLAC__bool
 203  *    \c false if the encoder is already initialized, else \c true.
 204  */
 205 FLAC__bool FLAC__seekable_stream_encoder_set_streamable_subset(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
 206
 207 /** This is inherited from FLAC__StreamEncoder; see
 208  *  FLAC__stream_encoder_set_do_mid_side_stereo().
 209  *
 210  * \default \c false
 211  * \param  encoder  An encoder instance to set.
 212  * \param  value    See above.
 213  * \assert
 214  *    \code encoder != NULL \endcode
 215  * \retval FLAC__bool
 216  *    \c false if the encoder is already initialized, else \c true.
 217  */
 218 FLAC__bool FLAC__seekable_stream_encoder_set_do_mid_side_stereo(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
 219
 220 /** This is inherited from FLAC__StreamEncoder; see
 221  *  FLAC__stream_encoder_set_loose_mid_side_stereo().
 222  *
 223  * \default \c false
 224  * \param  encoder  An encoder instance to set.
 225  * \param  value    See above.
 226  * \assert
 227  *    \code encoder != NULL \endcode
 228  * \retval FLAC__bool
 229  *    \c false if the encoder is already initialized, else \c true.
 230  */
 231 FLAC__bool FLAC__seekable_stream_encoder_set_loose_mid_side_stereo(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
 232
 233 /** This is inherited from FLAC__StreamEncoder; see
 234  *  FLAC__stream_encoder_set_channels().
 235  *
 236  * \default \c 2
 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 FLAC__seekable_stream_encoder_set_channels(FLAC__SeekableStreamEncoder *encoder, unsigned value);
 245
 246 /** This is inherited from FLAC__StreamEncoder; see
 247  *  FLAC__stream_encoder_set_bits_per_sample().
 248  *
 249  * \warning
 250  * Do not feed the encoder data that is wider than the value you
 251  * set here or you will generate an invalid stream.
 252  *
 253  * \default \c 16
 254  * \param  encoder  An encoder instance to set.
 255  * \param  value    See above.
 256  * \assert
 257  *    \code encoder != NULL \endcode
 258  * \retval FLAC__bool
 259  *    \c false if the encoder is already initialized, else \c true.
 260  */
 261 FLAC__bool FLAC__seekable_stream_encoder_set_bits_per_sample(FLAC__SeekableStreamEncoder *encoder, unsigned value);
 262
 263 /** This is inherited from FLAC__StreamEncoder; see
 264  *  FLAC__stream_encoder_set_sample_rate().
 265  *
 266  * \default \c 44100
 267  * \param  encoder  An encoder instance to set.
 268  * \param  value    See above.
 269  * \assert
 270  *    \code encoder != NULL \endcode
 271  * \retval FLAC__bool
 272  *    \c false if the encoder is already initialized, else \c true.
 273  */
 274 FLAC__bool FLAC__seekable_stream_encoder_set_sample_rate(FLAC__SeekableStreamEncoder *encoder, unsigned value);
 275
 276 /** This is inherited from FLAC__StreamEncoder; see
 277  *  FLAC__stream_encoder_set_blocksize().
 278  *
 279  * \default \c 1152
 280  * \param  encoder  An encoder instance to set.
 281  * \param  value    See above.
 282  * \assert
 283  *    \code encoder != NULL \endcode
 284  * \retval FLAC__bool
 285  *    \c false if the encoder is already initialized, else \c true.
 286  */
 287 FLAC__bool FLAC__seekable_stream_encoder_set_blocksize(FLAC__SeekableStreamEncoder *encoder, unsigned value);
 288
 289 /** This is inherited from FLAC__StreamEncoder; see
 290  *  FLAC__stream_encoder_set_max_lpc_order().
 291  *
 292  * \default \c 0
 293  * \param  encoder  An encoder instance to set.
 294  * \param  value    See above.
 295  * \assert
 296  *    \code encoder != NULL \endcode
 297  * \retval FLAC__bool
 298  *    \c false if the encoder is already initialized, else \c true.
 299  */
 300 FLAC__bool FLAC__seekable_stream_encoder_set_max_lpc_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
 301
 302 /** This is inherited from FLAC__StreamEncoder; see
 303  *  FLAC__stream_encoder_set_qlp_coeff_precision().
 304  *
 305  * \note
 306  * In the current implementation, qlp_coeff_precision + bits_per_sample must
 307  * be less than 32.
 308  *
 309  * \default \c 0
 310  * \param  encoder  An encoder instance to set.
 311  * \param  value    See above.
 312  * \assert
 313  *    \code encoder != NULL \endcode
 314  * \retval FLAC__bool
 315  *    \c false if the encoder is already initialized, else \c true.
 316  */
 317 FLAC__bool FLAC__seekable_stream_encoder_set_qlp_coeff_precision(FLAC__SeekableStreamEncoder *encoder, unsigned value);
 318
 319 /** This is inherited from FLAC__StreamEncoder; see
 320  *  FLAC__stream_encoder_set_do_qlp_coeff_prec_search().
 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 FLAC__bool FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
 331
 332 /** This is inherited from FLAC__StreamEncoder; see
 333  *  FLAC__stream_encoder_set_do_escape_coding().
 334  *
 335  * \default \c false
 336  * \param  encoder  An encoder instance to set.
 337  * \param  value    See above.
 338  * \assert
 339  *    \code encoder != NULL \endcode
 340  * \retval FLAC__bool
 341  *    \c false if the encoder is already initialized, else \c true.
 342  */
 343 FLAC__bool FLAC__seekable_stream_encoder_set_do_escape_coding(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
 344
 345 /** This is inherited from FLAC__StreamEncoder; see
 346  *  FLAC__stream_encoder_set_do_exhaustive_model_search().
 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 FLAC__bool FLAC__seekable_stream_encoder_set_do_exhaustive_model_search(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
 357
 358 /** This is inherited from FLAC__StreamEncoder; see
 359  *  FLAC__stream_encoder_set_min_residual_partition_order().
 360  *
 361  * \default \c 0
 362  * \param  encoder  An encoder instance to set.
 363  * \param  value    See above.
 364  * \assert
 365  *    \code encoder != NULL \endcode
 366  * \retval FLAC__bool
 367  *    \c false if the encoder is already initialized, else \c true.
 368  */
 369 FLAC__bool FLAC__seekable_stream_encoder_set_min_residual_partition_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
 370
 371 /** This is inherited from FLAC__StreamEncoder; see
 372  *  FLAC__stream_encoder_set_max_residual_partition_order().
 373  *
 374  * \default \c 0
 375  * \param  encoder  An encoder instance to set.
 376  * \param  value    See above.
 377  * \assert
 378  *    \code encoder != NULL \endcode
 379  * \retval FLAC__bool
 380  *    \c false if the encoder is already initialized, else \c true.
 381  */
 382 FLAC__bool FLAC__seekable_stream_encoder_set_max_residual_partition_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
 383
 384 /** This is inherited from FLAC__StreamEncoder; see
 385  *  FLAC__stream_encoder_set_rice_parameter_search_dist().
 386  *
 387  * \default \c 0
 388  * \param  encoder  An encoder instance to set.
 389  * \param  value    See above.
 390  * \assert
 391  *    \code encoder != NULL \endcode
 392  * \retval FLAC__bool
 393  *    \c false if the encoder is already initialized, else \c true.
 394  */
 395 FLAC__bool FLAC__seekable_stream_encoder_set_rice_parameter_search_dist(FLAC__SeekableStreamEncoder *encoder, unsigned value);
 396
 397 /** This is inherited from FLAC__StreamEncoder; see
 398  *  FLAC__stream_encoder_set_total_samples_estimate().
 399  *
 400  * \default \c 0
 401  * \param  encoder  An encoder instance to set.
 402  * \param  value    See above.
 403  * \assert
 404  *    \code encoder != NULL \endcode
 405  * \retval FLAC__bool
 406  *    \c false if the encoder is already initialized, else \c true.
 407  */
 408 FLAC__bool FLAC__seekable_stream_encoder_set_total_samples_estimate(FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 value);
 409
 410 /** This is inherited from FLAC__StreamEncoder; see
 411  *  FLAC__stream_encoder_set_metadata().
 412  *
 413  * \note
 414  * The decoder instance \b will modify the first \c SEEKTABLE block
 415  * as it transforms the template to a valid seektable while encoding,
 416  * but it is still up to the caller to free all metadata blocks after
 417  * encoding.
 418  *
 419  * \default \c NULL, 0
 420  * \param  encoder     An encoder instance to set.
 421  * \param  metadata    See above.
 422  * \param  num_blocks  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 FLAC__seekable_stream_encoder_set_metadata(FLAC__SeekableStreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
 429
 430 /** Set the seek callback.
 431  *  The supplied function will be called when the encoder needs to seek
 432  *  the output stream.  The encoder will pass the absolute byte offset
 433  *  to seek to, 0 meaning the beginning of the stream.
 434  *
 435  * \note
 436  * The callback is mandatory and must be set before initialization.
 437  *
 438  * \default \c NULL
 439  * \param  encoder  An encoder instance to set.
 440  * \param  value    See above.
 441  * \assert
 442  *    \code encoder != NULL \endcode
 443  *    \code value != NULL \endcode
 444  * \retval FLAC__bool
 445  *    \c false if the encoder is already initialized, else \c true.
 446  */
 447 FLAC__bool FLAC__seekable_stream_encoder_set_seek_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderSeekStatus (*value)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data));
 448
 449 /** Set the write callback.
 450  *  This is inherited from FLAC__StreamEncoder; see
 451  *  FLAC__stream_encoder_set_write_callback().
 452  *
 453  * \note
 454  * The callback is mandatory and must be set before initialization.
 455  *
 456  * \default \c NULL
 457  * \param  encoder  An encoder instance to set.
 458  * \param  value    See above.
 459  * \assert
 460  *    \code encoder != NULL \endcode
 461  *    \code value != NULL \endcode
 462  * \retval FLAC__bool
 463  *    \c false if the encoder is already initialized, else \c true.
 464  */
 465 FLAC__bool FLAC__seekable_stream_encoder_set_write_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__StreamEncoderWriteStatus (*value)(const FLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data));
 466
 467 /** Set the client data to be passed back to callbacks.
 468  *  This value will be supplied to callbacks in their \a client_data
 469  *  argument.
 470  *
 471  * \default \c NULL
 472  * \param  encoder  An encoder instance to set.
 473  * \param  value    See above.
 474  * \assert
 475  *    \code encoder != NULL \endcode
 476  * \retval FLAC__bool
 477  *    \c false if the encoder is already initialized, else \c true.
 478  */
 479 FLAC__bool FLAC__seekable_stream_encoder_set_client_data(FLAC__SeekableStreamEncoder *encoder, void *value);
 480
 481 /** Get the current encoder state.
 482  *
 483  * \param  encoder  An encoder instance to query.
 484  * \assert
 485  *    \code encoder != NULL \endcode
 486  * \retval FLAC__SeekableStreamEncoderState
 487  *    The current encoder state.
 488  */
 489 FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_get_state(const FLAC__SeekableStreamEncoder *encoder);
 490
 491 /** Get the state of the underlying stream encoder.
 492  *  Useful when the seekable stream encoder state is
 493  *  \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR.
 494  *
 495  * \param  encoder  An encoder instance to query.
 496  * \assert
 497  *    \code encoder != NULL \endcode
 498  * \retval FLAC__StreamEncoderState
 499  *    The stream encoder state.
 500  */
 501 FLAC__StreamEncoderState FLAC__seekable_stream_encoder_get_stream_encoder_state(const FLAC__SeekableStreamEncoder *encoder);
 502
 503 /** Get the "streamable subset" flag.
 504  *  This is inherited from FLAC__StreamEncoder; see
 505  *  FLAC__stream_encoder_get_streamable_subset().
 506  *
 507  * \param  encoder  An encoder instance to query.
 508  * \assert
 509  *    \code encoder != NULL \endcode
 510  * \retval FLAC__bool
 511  *    See FLAC__seekable_stream_encoder_set_streamable_subset().
 512  */
 513 FLAC__bool FLAC__seekable_stream_encoder_get_streamable_subset(const FLAC__SeekableStreamEncoder *encoder);
 514
 515 /** Get the "mid/side stereo coding" flag.
 516  *  This is inherited from FLAC__StreamEncoder; see
 517  *  FLAC__stream_encoder_get_do_mid_side_stereo().
 518  *
 519  * \param  encoder  An encoder instance to query.
 520  * \assert
 521  *    \code encoder != NULL \endcode
 522  * \retval FLAC__bool
 523  *    See FLAC__seekable_stream_encoder_get_do_mid_side_stereo().
 524  */
 525 FLAC__bool FLAC__seekable_stream_encoder_get_do_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder);
 526
 527 /** Get the "adaptive mid/side switching" flag.
 528  *  This is inherited from FLAC__StreamEncoder; see
 529  *  FLAC__stream_encoder_get_loose_mid_side_stereo().
 530  *
 531  * \param  encoder  An encoder instance to query.
 532  * \assert
 533  *    \code encoder != NULL \endcode
 534  * \retval FLAC__bool
 535  *    See FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
 536  */
 537 FLAC__bool FLAC__seekable_stream_encoder_get_loose_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder);
 538
 539 /** Get the number of input channels being processed.
 540  *  This is inherited from FLAC__StreamEncoder; see
 541  *  FLAC__stream_encoder_get_channels().
 542  *
 543  * \param  encoder  An encoder instance to query.
 544  * \assert
 545  *    \code encoder != NULL \endcode
 546  * \retval FLAC__bool
 547  *    See FLAC__seekable_stream_encoder_set_channels().
 548  */
 549 unsigned FLAC__seekable_stream_encoder_get_channels(const FLAC__SeekableStreamEncoder *encoder);
 550
 551 /** Get the input sample resolution setting.
 552  *  This is inherited from FLAC__StreamEncoder; see
 553  *  FLAC__stream_encoder_get_bits_per_sample().
 554  *
 555  * \param  encoder  An encoder instance to query.
 556  * \assert
 557  *    \code encoder != NULL \endcode
 558  * \retval FLAC__bool
 559  *    See FLAC__seekable_stream_encoder_set_bits_per_sample().
 560  */
 561 unsigned FLAC__seekable_stream_encoder_get_bits_per_sample(const FLAC__SeekableStreamEncoder *encoder);
 562
 563 /** Get the input sample rate setting.
 564  *  This is inherited from FLAC__StreamEncoder; see
 565  *  FLAC__stream_encoder_get_sample_rate().
 566  *
 567  * \param  encoder  An encoder instance to query.
 568  * \assert
 569  *    \code encoder != NULL \endcode
 570  * \retval FLAC__bool
 571  *    See FLAC__seekable_stream_encoder_set_sample_rate().
 572  */
 573 unsigned FLAC__seekable_stream_encoder_get_sample_rate(const FLAC__SeekableStreamEncoder *encoder);
 574
 575 /** Get the blocksize setting.
 576  *  This is inherited from FLAC__StreamEncoder; see
 577  *  FLAC__stream_encoder_get_blocksize().
 578  *
 579  * \param  encoder  An encoder instance to query.
 580  * \assert
 581  *    \code encoder != NULL \endcode
 582  * \retval FLAC__bool
 583  *    See FLAC__seekable_stream_encoder_set_blocksize().
 584  */
 585 unsigned FLAC__seekable_stream_encoder_get_blocksize(const FLAC__SeekableStreamEncoder *encoder);
 586
 587 /** Get the maximum LPC order setting.
 588  *  This is inherited from FLAC__StreamEncoder; see
 589  *  FLAC__stream_encoder_get_max_lpc_order().
 590  *
 591  * \param  encoder  An encoder instance to query.
 592  * \assert
 593  *    \code encoder != NULL \endcode
 594  * \retval FLAC__bool
 595  *    See FLAC__seekable_stream_encoder_set_max_lpc_order().
 596  */
 597 unsigned FLAC__seekable_stream_encoder_get_max_lpc_order(const FLAC__SeekableStreamEncoder *encoder);
 598
 599 /** Get the quantized linear predictor coefficient precision setting.
 600  *  This is inherited from FLAC__StreamEncoder; see
 601  *  FLAC__stream_encoder_get_qlp_coeff_precision().
 602  *
 603  * \param  encoder  An encoder instance to query.
 604  * \assert
 605  *    \code encoder != NULL \endcode
 606  * \retval FLAC__bool
 607  *    See FLAC__seekable_stream_encoder_set_qlp_coeff_precision().
 608  */
 609 unsigned FLAC__seekable_stream_encoder_get_qlp_coeff_precision(const FLAC__SeekableStreamEncoder *encoder);
 610
 611 /** Get the qlp coefficient precision search flag.
 612  *  This is inherited from FLAC__StreamEncoder; see
 613  *  FLAC__stream_encoder_get_do_qlp_coeff_prec_search().
 614  *
 615  * \param  encoder  An encoder instance to query.
 616  * \assert
 617  *    \code encoder != NULL \endcode
 618  * \retval FLAC__bool
 619  *    See FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
 620  */
 621 FLAC__bool FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__SeekableStreamEncoder *encoder);
 622
 623 /** Get the "escape coding" flag.
 624  *  This is inherited from FLAC__StreamEncoder; see
 625  *  FLAC__stream_encoder_get_do_escape_coding().
 626  *
 627  * \param  encoder  An encoder instance to query.
 628  * \assert
 629  *    \code encoder != NULL \endcode
 630  * \retval FLAC__bool
 631  *    See FLAC__seekable_stream_encoder_set_do_escape_coding().
 632  */
 633 FLAC__bool FLAC__seekable_stream_encoder_get_do_escape_coding(const FLAC__SeekableStreamEncoder *encoder);
 634
 635 /** Get the exhaustive model search flag.
 636  *  This is inherited from FLAC__StreamEncoder; see
 637  *  FLAC__stream_encoder_get_do_exhaustive_model_search().
 638  *
 639  * \param  encoder  An encoder instance to query.
 640  * \assert
 641  *    \code encoder != NULL \endcode
 642  * \retval FLAC__bool
 643  *    See FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
 644  */
 645 FLAC__bool FLAC__seekable_stream_encoder_get_do_exhaustive_model_search(const FLAC__SeekableStreamEncoder *encoder);
 646
 647 /** Get the minimum residual partition order setting.
 648  *  This is inherited from FLAC__StreamEncoder; see
 649  *  FLAC__stream_encoder_get_min_residual_partition_order().
 650  *
 651  * \param  encoder  An encoder instance to query.
 652  * \assert
 653  *    \code encoder != NULL \endcode
 654  * \retval FLAC__bool
 655  *    See FLAC__seekable_stream_encoder_set_min_residual_partition_order().
 656  */
 657 unsigned FLAC__seekable_stream_encoder_get_min_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder);
 658
 659 /** Get maximum residual partition order setting.
 660  *  This is inherited from FLAC__StreamEncoder; see
 661  *  FLAC__stream_encoder_get_max_residual_partition_order().
 662  *
 663  * \param  encoder  An encoder instance to query.
 664  * \assert
 665  *    \code encoder != NULL \endcode
 666  * \retval FLAC__bool
 667  *    See FLAC__seekable_stream_encoder_set_max_residual_partition_order().
 668  */
 669 unsigned FLAC__seekable_stream_encoder_get_max_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder);
 670
 671 /** Get the Rice parameter search distance setting.
 672  *  This is inherited from FLAC__StreamEncoder; see
 673  *  FLAC__stream_encoder_get_rice_parameter_search_dist().
 674  *
 675  * \param  encoder  An encoder instance to query.
 676  * \assert
 677  *    \code encoder != NULL \endcode
 678  * \retval FLAC__bool
 679  *    See FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
 680  */
 681 unsigned FLAC__seekable_stream_encoder_get_rice_parameter_search_dist(const FLAC__SeekableStreamEncoder *encoder);
 682
 683 /** Initialize the encoder instance.
 684  *  Should be called after FLAC__seekable_stream_encoder_new() and
 685  *  FLAC__seekable_stream_encoder_set_*() but before FLAC__seekable_stream_encoder_process()
 686  *  or FLAC__seekable_stream_encoder_process_interleaved().  Will set and return
 687  *  the encoder state, which will be FLAC__SEEKABLE_STREAM_ENCODER_OK if
 688  *  initialization succeeded.
 689  *
 690  *  The call to FLAC__seekable_stream_encoder_init() currently will also immediately
 691  *  call the write callback with the \c fLaC signature and all the encoded
 692  *  metadata.
 693  *
 694  * \param  encoder  An uninitialized encoder instance.
 695  * \assert
 696  *    \code encoder != NULL \endcode
 697  * \retval FLAC__SeekableStreamEncoderState
 698  *    \c FLAC__SEEKABLE_STREAM_ENCODER_OK if initialization was successful; see
 699  *    FLAC__SeekableStreamEncoderState for the meanings of other return values.
 700  */
 701 FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_init(FLAC__SeekableStreamEncoder *encoder);
 702
 703 /** Finish the encoding process.
 704  *  Flushes the encoding buffer, releases resources, resets the encoder
 705  *  settings to their defaults, and returns the encoder state to
 706  *  FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED.
 707  *
 708  *  In the event of a prematurely-terminated encode, it is not strictly
 709  *  necessary to call this immediately before FLAC__seekable_stream_encoder_delete()
 710  *  but it is good practice to match every FLAC__seekable_stream_encoder_init()
 711  *  with a FLAC__seekable_stream_encoder_finish().
 712  *
 713  * \param  encoder  An uninitialized encoder instance.
 714  * \assert
 715  *    \code encoder != NULL \endcode
 716  */
 717 void FLAC__seekable_stream_encoder_finish(FLAC__SeekableStreamEncoder *encoder);
 718
 719 /** Submit data for encoding.
 720  *  This is inherited from FLAC__StreamEncoder; see
 721  *  FLAC__stream_encoder_process().
 722  *
 723  * \param  encoder  An initialized encoder instance in the OK state.
 724  * \param  buffer   An array of pointers to each channel's signal.
 725  * \param  samples  The number of samples in one channel.
 726  * \assert
 727  *    \code encoder != NULL \endcode
 728  *    \code FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
 729  * \retval FLAC__bool
 730  *    \c true if successful, else \c false; in this case, check the
 731  *    encoder state with FLAC__seekable_stream_encoder_get_state() to see what
 732  *    went wrong.
 733  */
 734 FLAC__bool FLAC__seekable_stream_encoder_process(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
 735
 736 /** Submit data for encoding.
 737  *  This is inherited from FLAC__StreamEncoder; see
 738  *  FLAC__stream_encoder_process_interleaved().
 739  *
 740  * \param  encoder  An initialized encoder instance in the OK state.
 741  * \param  buffer   An array of channel-interleaved data (see above).
 742  * \param  samples  The number of samples in one channel, the same as for
 743  *                  FLAC__seekable_stream_encoder_process().  For example, if
 744  *                  encoding two channels, \c 1000 \a samples corresponds
 745  *                  to a \a buffer of 2000 values.
 746  * \assert
 747  *    \code encoder != NULL \endcode
 748  *    \code FLAC__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
 749  * \retval FLAC__bool
 750  *    \c true if successful, else \c false; in this case, check the
 751  *    encoder state with FLAC__seekable_stream_encoder_get_state() to see what
 752  *    went wrong.
 753  */
 754 FLAC__bool FLAC__seekable_stream_encoder_process_interleaved(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
 755
 756 /* \} */
 757
 758 #ifdef __cplusplus
 759 }
 760 #endif
 761
 762 #endif