1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/libs/vorbis/vorbisenc.h	Sat Feb 01 19:58:19 2014 +0200
     1.3 @@ -0,0 +1,436 @@
     1.4 +/********************************************************************
     1.5 + *                                                                  *
     1.6 + * THIS FILE IS PART OF THE OggVorbis SOFTWARE CODEC SOURCE CODE.   *
     1.7 + * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS     *
     1.8 + * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
     1.9 + * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING.       *
    1.10 + *                                                                  *
    1.11 + * THE OggVorbis SOURCE CODE IS (C) COPYRIGHT 1994-2001             *
    1.12 + * by the Xiph.Org Foundation http://www.xiph.org/                  *
    1.13 + *                                                                  *
    1.14 + ********************************************************************
    1.15 +
    1.16 + function: vorbis encode-engine setup
    1.17 + last mod: $Id: vorbisenc.h 17021 2010-03-24 09:29:41Z xiphmont $
    1.18 +
    1.19 + ********************************************************************/
    1.20 +
    1.21 +/** \file
    1.22 + * Libvorbisenc is a convenient API for setting up an encoding
    1.23 + * environment using libvorbis. Libvorbisenc encapsulates the
    1.24 + * actions needed to set up the encoder properly.
    1.25 + */
    1.26 +
    1.27 +#ifndef _OV_ENC_H_
    1.28 +#define _OV_ENC_H_
    1.29 +
    1.30 +#ifdef __cplusplus
    1.31 +extern "C"
    1.32 +{
    1.33 +#endif /* __cplusplus */
    1.34 +
    1.35 +#include "codec.h"
    1.36 +
    1.37 +/**
    1.38 + * This is the primary function within libvorbisenc for setting up managed
    1.39 + * bitrate modes.
    1.40 + *
    1.41 + * Before this function is called, the \ref vorbis_info
    1.42 + * struct should be initialized by using vorbis_info_init() from the libvorbis
    1.43 + * API.  After encoding, vorbis_info_clear() should be called.
    1.44 + *
    1.45 + * The max_bitrate, nominal_bitrate, and min_bitrate settings are used to set
    1.46 + * constraints for the encoded file.  This function uses these settings to
    1.47 + * select the appropriate encoding mode and set it up.
    1.48 + *
    1.49 + * \param vi               Pointer to an initialized \ref vorbis_info struct.
    1.50 + * \param channels         The number of channels to be encoded.
    1.51 + * \param rate             The sampling rate of the source audio.
    1.52 + * \param max_bitrate      Desired maximum bitrate (limit). -1 indicates unset.
    1.53 + * \param nominal_bitrate  Desired average, or central, bitrate. -1 indicates unset.
    1.54 + * \param min_bitrate      Desired minimum bitrate. -1 indicates unset.
    1.55 + *
    1.56 + * \return Zero for success, and negative values for failure.
    1.57 + *
    1.58 + * \retval 0          Success.
    1.59 + * \retval OV_EFAULT  Internal logic fault; indicates a bug or heap/stack corruption.
    1.60 + * \retval OV_EINVAL  Invalid setup request, eg, out of range argument.
    1.61 + * \retval OV_EIMPL   Unimplemented mode; unable to comply with bitrate request.
    1.62 + */
    1.63 +extern int vorbis_encode_init(vorbis_info *vi,
    1.64 +                              long channels,
    1.65 +                              long rate,
    1.66 +
    1.67 +                              long max_bitrate,
    1.68 +                              long nominal_bitrate,
    1.69 +                              long min_bitrate);
    1.70 +
    1.71 +/**
    1.72 + * This function performs step-one of a three-step bitrate-managed encode
    1.73 + * setup.  It functions similarly to the one-step setup performed by \ref
    1.74 + * vorbis_encode_init but allows an application to make further encode setup
    1.75 + * tweaks using \ref vorbis_encode_ctl before finally calling \ref
    1.76 + * vorbis_encode_setup_init to complete the setup process.
    1.77 + *
    1.78 + * Before this function is called, the \ref vorbis_info struct should be
    1.79 + * initialized by using vorbis_info_init() from the libvorbis API.  After
    1.80 + * encoding, vorbis_info_clear() should be called.
    1.81 + *
    1.82 + * The max_bitrate, nominal_bitrate, and min_bitrate settings are used to set
    1.83 + * constraints for the encoded file.  This function uses these settings to
    1.84 + * select the appropriate encoding mode and set it up.
    1.85 + *
    1.86 + * \param vi                Pointer to an initialized vorbis_info struct.
    1.87 + * \param channels          The number of channels to be encoded.
    1.88 + * \param rate              The sampling rate of the source audio.
    1.89 + * \param max_bitrate       Desired maximum bitrate (limit). -1 indicates unset.
    1.90 + * \param nominal_bitrate   Desired average, or central, bitrate. -1 indicates unset.
    1.91 + * \param min_bitrate       Desired minimum bitrate. -1 indicates unset.
    1.92 + *
    1.93 + * \return Zero for success, and negative for failure.
    1.94 + *
    1.95 + * \retval 0           Success
    1.96 + * \retval OV_EFAULT   Internal logic fault; indicates a bug or heap/stack corruption.
    1.97 + * \retval OV_EINVAL   Invalid setup request, eg, out of range argument.
    1.98 + * \retval OV_EIMPL    Unimplemented mode; unable to comply with bitrate request.
    1.99 + */
   1.100 +extern int vorbis_encode_setup_managed(vorbis_info *vi,
   1.101 +                                       long channels,
   1.102 +                                       long rate,
   1.103 +
   1.104 +                                       long max_bitrate,
   1.105 +                                       long nominal_bitrate,
   1.106 +                                       long min_bitrate);
   1.107 +
   1.108 +/**
   1.109 + * This function performs step-one of a three-step variable bitrate
   1.110 + * (quality-based) encode setup.  It functions similarly to the one-step setup
   1.111 + * performed by \ref vorbis_encode_init_vbr() but allows an application to
   1.112 + * make further encode setup tweaks using \ref vorbis_encode_ctl() before
   1.113 + * finally calling \ref vorbis_encode_setup_init to complete the setup
   1.114 + * process.
   1.115 + *
   1.116 + * Before this function is called, the \ref vorbis_info struct should be
   1.117 + * initialized by using \ref vorbis_info_init() from the libvorbis API.  After
   1.118 + * encoding, vorbis_info_clear() should be called.
   1.119 + *
   1.120 + * \param vi        Pointer to an initialized vorbis_info struct.
   1.121 + * \param channels  The number of channels to be encoded.
   1.122 + * \param rate      The sampling rate of the source audio.
   1.123 + * \param quality   Desired quality level, currently from -0.1 to 1.0 (lo to hi).
   1.124 + *
   1.125 + * \return Zero for success, and negative values for failure.
   1.126 + *
   1.127 + * \retval  0          Success
   1.128 + * \retval  OV_EFAULT  Internal logic fault; indicates a bug or heap/stack corruption.
   1.129 + * \retval  OV_EINVAL  Invalid setup request, eg, out of range argument.
   1.130 + * \retval  OV_EIMPL   Unimplemented mode; unable to comply with quality level request.
   1.131 + */
   1.132 +extern int vorbis_encode_setup_vbr(vorbis_info *vi,
   1.133 +                                  long channels,
   1.134 +                                  long rate,
   1.135 +
   1.136 +                                  float quality
   1.137 +                                  );
   1.138 +
   1.139 +/**
   1.140 + * This is the primary function within libvorbisenc for setting up variable
   1.141 + * bitrate ("quality" based) modes.
   1.142 + *
   1.143 + *
   1.144 + * Before this function is called, the vorbis_info struct should be
   1.145 + * initialized by using vorbis_info_init() from the libvorbis API. After
   1.146 + * encoding, vorbis_info_clear() should be called.
   1.147 + *
   1.148 + * \param vi           Pointer to an initialized vorbis_info struct.
   1.149 + * \param channels     The number of channels to be encoded.
   1.150 + * \param rate         The sampling rate of the source audio.
   1.151 + * \param base_quality Desired quality level, currently from -0.1 to 1.0 (lo to hi).
   1.152 + *
   1.153 + *
   1.154 + * \return Zero for success, or a negative number for failure.
   1.155 + *
   1.156 + * \retval 0           Success
   1.157 + * \retval OV_EFAULT   Internal logic fault; indicates a bug or heap/stack corruption.
   1.158 + * \retval OV_EINVAL   Invalid setup request, eg, out of range argument.
   1.159 + * \retval OV_EIMPL    Unimplemented mode; unable to comply with quality level request.
   1.160 + */
   1.161 +extern int vorbis_encode_init_vbr(vorbis_info *vi,
   1.162 +                                  long channels,
   1.163 +                                  long rate,
   1.164 +
   1.165 +                                  float base_quality
   1.166 +                                  );
   1.167 +
   1.168 +/**
   1.169 + * This function performs the last stage of three-step encoding setup, as
   1.170 + * described in the API overview under managed bitrate modes.
   1.171 + *
   1.172 + * Before this function is called, the \ref vorbis_info struct should be
   1.173 + * initialized by using vorbis_info_init() from the libvorbis API, one of
   1.174 + * \ref vorbis_encode_setup_managed() or \ref vorbis_encode_setup_vbr() called to
   1.175 + * initialize the high-level encoding setup, and \ref vorbis_encode_ctl()
   1.176 + * called if necessary to make encoding setup changes.
   1.177 + * vorbis_encode_setup_init() finalizes the highlevel encoding structure into
   1.178 + * a complete encoding setup after which the application may make no further
   1.179 + * setup changes.
   1.180 + *
   1.181 + * After encoding, vorbis_info_clear() should be called.
   1.182 + *
   1.183 + * \param vi Pointer to an initialized \ref vorbis_info struct.
   1.184 + *
   1.185 + * \return Zero for success, and negative values for failure.
   1.186 + *
   1.187 + * \retval  0           Success.
   1.188 + * \retval  OV_EFAULT  Internal logic fault; indicates a bug or heap/stack corruption.
   1.189 + *
   1.190 + * \retval OV_EINVAL   Attempt to use vorbis_encode_setup_init() without first
   1.191 + * calling one of vorbis_encode_setup_managed() or vorbis_encode_setup_vbr() to
   1.192 + * initialize the high-level encoding setup
   1.193 + *
   1.194 + */
   1.195 +extern int vorbis_encode_setup_init(vorbis_info *vi);
   1.196 +
   1.197 +/**
   1.198 + * This function implements a generic interface to miscellaneous encoder
   1.199 + * settings similar to the classic UNIX 'ioctl()' system call.  Applications
   1.200 + * may use vorbis_encode_ctl() to query or set bitrate management or quality
   1.201 + * mode details by using one of several \e request arguments detailed below.
   1.202 + * vorbis_encode_ctl() must be called after one of
   1.203 + * vorbis_encode_setup_managed() or vorbis_encode_setup_vbr().  When used
   1.204 + * to modify settings, \ref vorbis_encode_ctl() must be called before \ref
   1.205 + * vorbis_encode_setup_init().
   1.206 + *
   1.207 + * \param vi      Pointer to an initialized vorbis_info struct.
   1.208 + *
   1.209 + * \param number Specifies the desired action; See \ref encctlcodes "the list
   1.210 + * of available requests".
   1.211 + *
   1.212 + * \param arg void * pointing to a data structure matching the request
   1.213 + * argument.
   1.214 + *
   1.215 + * \retval 0          Success. Any further return information (such as the result of a
   1.216 + * query) is placed into the storage pointed to by *arg.
   1.217 + *
   1.218 + * \retval OV_EINVAL  Invalid argument, or an attempt to modify a setting after
   1.219 + * calling vorbis_encode_setup_init().
   1.220 + *
   1.221 + * \retval OV_EIMPL   Unimplemented or unknown request
   1.222 + */
   1.223 +extern int vorbis_encode_ctl(vorbis_info *vi,int number,void *arg);
   1.224 +
   1.225 +/**
   1.226 + * \deprecated This is a deprecated interface. Please use vorbis_encode_ctl()
   1.227 + * with the \ref ovectl_ratemanage2_arg struct and \ref
   1.228 + * OV_ECTL_RATEMANAGE2_GET and \ref OV_ECTL_RATEMANAGE2_SET calls in new code.
   1.229 + *
   1.230 + * The \ref ovectl_ratemanage_arg structure is used with vorbis_encode_ctl()
   1.231 + * and the \ref OV_ECTL_RATEMANAGE_GET, \ref OV_ECTL_RATEMANAGE_SET, \ref
   1.232 + * OV_ECTL_RATEMANAGE_AVG, \ref OV_ECTL_RATEMANAGE_HARD calls in order to
   1.233 + * query and modify specifics of the encoder's bitrate management
   1.234 + * configuration.
   1.235 +*/
   1.236 +struct ovectl_ratemanage_arg {
   1.237 +  int    management_active; /**< nonzero if bitrate management is active*/
   1.238 +/** hard lower limit (in kilobits per second) below which the stream bitrate
   1.239 +    will never be allowed for any given bitrate_hard_window seconds of time.*/
   1.240 +  long   bitrate_hard_min;
   1.241 +/** hard upper limit (in kilobits per second) above which the stream bitrate
   1.242 +    will never be allowed for any given bitrate_hard_window seconds of time.*/
   1.243 +  long   bitrate_hard_max;
   1.244 +/** the window period (in seconds) used to regulate the hard bitrate minimum
   1.245 +    and maximum*/
   1.246 +  double bitrate_hard_window;
   1.247 +/** soft lower limit (in kilobits per second) below which the average bitrate
   1.248 +    tracker will start nudging the bitrate higher.*/
   1.249 +  long   bitrate_av_lo;
   1.250 +/** soft upper limit (in kilobits per second) above which the average bitrate
   1.251 +    tracker will start nudging the bitrate lower.*/
   1.252 +  long   bitrate_av_hi;
   1.253 +/** the window period (in seconds) used to regulate the average bitrate
   1.254 +    minimum and maximum.*/
   1.255 +  double bitrate_av_window;
   1.256 +/** Regulates the relative centering of the average and hard windows; in
   1.257 +    libvorbis 1.0 and 1.0.1, the hard window regulation overlapped but
   1.258 +    followed the average window regulation. In libvorbis 1.1 a bit-reservoir
   1.259 +    interface replaces the old windowing interface; the older windowing
   1.260 +    interface is simulated and this field has no effect.*/
   1.261 +  double bitrate_av_window_center;
   1.262 +};
   1.263 +
   1.264 +/**
   1.265 + * \name struct ovectl_ratemanage2_arg
   1.266 + *
   1.267 + * The ovectl_ratemanage2_arg structure is used with vorbis_encode_ctl() and
   1.268 + * the OV_ECTL_RATEMANAGE2_GET and OV_ECTL_RATEMANAGE2_SET calls in order to
   1.269 + * query and modify specifics of the encoder's bitrate management
   1.270 + * configuration.
   1.271 + *
   1.272 +*/
   1.273 +struct ovectl_ratemanage2_arg {
   1.274 +  int    management_active; /**< nonzero if bitrate management is active */
   1.275 +/** Lower allowed bitrate limit in kilobits per second */
   1.276 +  long   bitrate_limit_min_kbps;
   1.277 +/** Upper allowed bitrate limit in kilobits per second */
   1.278 +  long   bitrate_limit_max_kbps;
   1.279 +  long   bitrate_limit_reservoir_bits; /**<Size of the bitrate reservoir in bits */
   1.280 +/** Regulates the bitrate reservoir's preferred fill level in a range from 0.0
   1.281 + * to 1.0; 0.0 tries to bank bits to buffer against future bitrate spikes, 1.0
   1.282 + * buffers against future sudden drops in instantaneous bitrate. Default is
   1.283 + * 0.1
   1.284 + */
   1.285 +  double bitrate_limit_reservoir_bias;
   1.286 +/** Average bitrate setting in kilobits per second */
   1.287 +  long   bitrate_average_kbps;
   1.288 +/** Slew rate limit setting for average bitrate adjustment; sets the minimum
   1.289 + *  time in seconds the bitrate tracker may swing from one extreme to the
   1.290 + *  other when boosting or damping average bitrate.
   1.291 + */
   1.292 +  double bitrate_average_damping;
   1.293 +};
   1.294 +
   1.295 +
   1.296 +/**
   1.297 + * \name vorbis_encode_ctl() codes
   1.298 + *
   1.299 + * \anchor encctlcodes
   1.300 + *
   1.301 + * These values are passed as the \c number parameter of vorbis_encode_ctl().
   1.302 + * The type of the referent of that function's \c arg pointer depends on these
   1.303 + * codes.
   1.304 + */
   1.305 +/*@{*/
   1.306 +
   1.307 +/**
   1.308 + * Query the current encoder bitrate management setting.
   1.309 + *
   1.310 + *Argument: <tt>struct ovectl_ratemanage2_arg *</tt>
   1.311 + *
   1.312 + * Used to query the current encoder bitrate management setting. Also used to
   1.313 + * initialize fields of an ovectl_ratemanage2_arg structure for use with
   1.314 + * \ref OV_ECTL_RATEMANAGE2_SET.
   1.315 + */
   1.316 +#define OV_ECTL_RATEMANAGE2_GET      0x14
   1.317 +
   1.318 +/**
   1.319 + * Set the current encoder bitrate management settings.
   1.320 + *
   1.321 + * Argument: <tt>struct ovectl_ratemanage2_arg *</tt>
   1.322 + *
   1.323 + * Used to set the current encoder bitrate management settings to the values
   1.324 + * listed in the ovectl_ratemanage2_arg. Passing a NULL pointer will disable
   1.325 + * bitrate management.
   1.326 +*/
   1.327 +#define OV_ECTL_RATEMANAGE2_SET      0x15
   1.328 +
   1.329 +/**
   1.330 + * Returns the current encoder hard-lowpass setting (kHz) in the double
   1.331 + * pointed to by arg.
   1.332 + *
   1.333 + * Argument: <tt>double *</tt>
   1.334 +*/
   1.335 +#define OV_ECTL_LOWPASS_GET          0x20
   1.336 +
   1.337 +/**
   1.338 + *  Sets the encoder hard-lowpass to the value (kHz) pointed to by arg. Valid
   1.339 + *  lowpass settings range from 2 to 99.
   1.340 + *
   1.341 + * Argument: <tt>double *</tt>
   1.342 +*/
   1.343 +#define OV_ECTL_LOWPASS_SET          0x21
   1.344 +
   1.345 +/**
   1.346 + *  Returns the current encoder impulse block setting in the double pointed
   1.347 + *  to by arg.
   1.348 + *
   1.349 + * Argument: <tt>double *</tt>
   1.350 +*/
   1.351 +#define OV_ECTL_IBLOCK_GET           0x30
   1.352 +
   1.353 +/**
   1.354 + *  Sets the impulse block bias to the the value pointed to by arg.
   1.355 + *
   1.356 + * Argument: <tt>double *</tt>
   1.357 + *
   1.358 + *  Valid range is -15.0 to 0.0 [default]. A negative impulse block bias will
   1.359 + *  direct to encoder to use more bits when incoding short blocks that contain
   1.360 + *  strong impulses, thus improving the accuracy of impulse encoding.
   1.361 + */
   1.362 +#define OV_ECTL_IBLOCK_SET           0x31
   1.363 +
   1.364 +/**
   1.365 + *  Returns the current encoder coupling setting in the int pointed
   1.366 + *  to by arg.
   1.367 + *
   1.368 + * Argument: <tt>int *</tt>
   1.369 +*/
   1.370 +#define OV_ECTL_COUPLING_GET         0x40
   1.371 +
   1.372 +/**
   1.373 + *  Enables/disables channel coupling in multichannel encoding according to arg.
   1.374 + *
   1.375 + * Argument: <tt>int *</tt>
   1.376 + *
   1.377 + *  Zero disables channel coupling for multichannel inputs, nonzer enables
   1.378 + *  channel coupling.  Setting has no effect on monophonic encoding or
   1.379 + *  multichannel counts that do not offer coupling.  At present, coupling is
   1.380 + *  available for stereo and 5.1 encoding.
   1.381 + */
   1.382 +#define OV_ECTL_COUPLING_SET         0x41
   1.383 +
   1.384 +  /* deprecated rate management supported only for compatibility */
   1.385 +
   1.386 +/**
   1.387 + * Old interface to querying bitrate management settings.
   1.388 + *
   1.389 + * Deprecated after move to bit-reservoir style management in 1.1 rendered
   1.390 + * this interface partially obsolete.
   1.391 +
   1.392 + * \deprecated Please use \ref OV_ECTL_RATEMANAGE2_GET instead.
   1.393 + *
   1.394 + * Argument: <tt>struct ovectl_ratemanage_arg *</tt>
   1.395 + */
   1.396 +#define OV_ECTL_RATEMANAGE_GET       0x10
   1.397 +/**
   1.398 + * Old interface to modifying bitrate management settings.
   1.399 + *
   1.400 + *  deprecated after move to bit-reservoir style management in 1.1 rendered
   1.401 + *  this interface partially obsolete.
   1.402 + *
   1.403 + * \deprecated Please use \ref OV_ECTL_RATEMANAGE2_SET instead.
   1.404 + *
   1.405 + * Argument: <tt>struct ovectl_ratemanage_arg *</tt>
   1.406 + */
   1.407 +#define OV_ECTL_RATEMANAGE_SET       0x11
   1.408 +/**
   1.409 + * Old interface to setting average-bitrate encoding mode.
   1.410 + *
   1.411 + * Deprecated after move to bit-reservoir style management in 1.1 rendered
   1.412 + * this interface partially obsolete.
   1.413 + *
   1.414 + *  \deprecated Please use \ref OV_ECTL_RATEMANAGE2_SET instead.
   1.415 + *
   1.416 + * Argument: <tt>struct ovectl_ratemanage_arg *</tt>
   1.417 + */
   1.418 +#define OV_ECTL_RATEMANAGE_AVG       0x12
   1.419 +/**
   1.420 + * Old interface to setting bounded-bitrate encoding modes.
   1.421 + *
   1.422 + * deprecated after move to bit-reservoir style management in 1.1 rendered
   1.423 + * this interface partially obsolete.
   1.424 + *
   1.425 + *  \deprecated Please use \ref OV_ECTL_RATEMANAGE2_SET instead.
   1.426 + *
   1.427 + * Argument: <tt>struct ovectl_ratemanage_arg *</tt>
   1.428 + */
   1.429 +#define OV_ECTL_RATEMANAGE_HARD      0x13
   1.430 +
   1.431 +/*@}*/
   1.432 +
   1.433 +
   1.434 +
   1.435 +#ifdef __cplusplus
   1.436 +}
   1.437 +#endif /* __cplusplus */
   1.438 +
   1.439 +#endif