Dependencies/libvorbis/doc/vorbisenc/vorbis_encode_ctl.html

   1 <html>
   2
   3 <head>
   4 <title>libvorbisenc - function - vorbis_encode_ctl</title>
   5 <link rel=stylesheet href="style.css" type="text/css">
   6 </head>
   7
   8 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
   9 <table border=0 width=100%>
  10 <tr>
  11 <td><p class=tiny>libvorbisenc documentation</p></td>
  12 <td align=right><p class=tiny>libvorbisenc release 1.1 - 20040709</p></td>
  13 </tr>
  14 </table>
  15
  16 <h1>vorbis_encode_ctl</h1>
  17
  18 <p><i>declared in "vorbis/vorbisenc.h";</i></p>
  19
  20 <p>This function implements a generic interface to miscellaneous
  21 encoder settings similar to the clasasic UNIX 'ioctl()' system call.
  22 Applications may use vorbis_encode_ctl() to query or set bitrate
  23 management or quality mode details by using one of several
  24 <i>request</i> arguments detailed below.  Vorbis_encode_ctl() must be
  25 called after one of <a
  26 href="vorbis_encode_setup_managed.html">vorbis_encode_setup_managed()</a>
  27 or <a
  28 href="vorbis_encode_setup_vbr.html">vorbis_encode_setup_vbr()</a>.
  29 When used to modify settings, vorbis_encode_ctl() must be called
  30 before <a
  31 href="vorbis_encode_setup_init.html">vorbis_encode_setup_init()</a>.
  32
  33 <p>
  34 <br><br>
  35 <table border=0 color=black cellspacing=0 cellpadding=7>
  36 <tr bgcolor=#cccccc>
  37         <td>
  38 <pre><b>
  39 extern int vorbis_encode_ctl(vorbis_info *vi,int request,void *arg);
  40
  41 </b></pre>
  42         </td>
  43 </tr>
  44 </table>
  45
  46 <h3>Parameters</h3>
  47 <dl>
  48 <dt><i>vi</i></dt>
  49 <dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd><p>
  50 <dt><i>request</i></dt>
  51 <dd>Specifies the desired action; possible request fields are detailed below.</dd><p>
  52 <dt><i>arg</i></dt>
  53 <dd>void * pointing to a data structure matching the request argument.</dd><p>
  54 </dl><p>
  55
  56 <h3>Requests</h3>
  57 <dl>
  58
  59 <dt><i>OV_ECTL_RATEMANAGE2_GET</i></dt>
  60
  61 <dd><b>Argument: <a href="ovectl_ratemanage2_arg.html">struct
  62 ovectl_ratemanage2_arg *</a></b><br> Used to query the current
  63 encoder bitrate management setting.  Also used to initialize fields of
  64 an ovectl_ratemanage2_arg structure for use with
  65 OV_ECTL_RATEMANAGE2_SET.</dd><p>
  66
  67 <dt><i>OV_ECTL_RATEMANAGE2_SET</i></dt>
  68 <dd><b>Argument: <a href="ovectl_ratemanage2_arg.html">struct
  69 ovectl_ratemanage2_arg *</a></b><br> Used to set the current
  70 encoder bitrate management settings to the values listed in the
  71 ovectl_ratemanage2_arg.  Passing a NULL pointer will disable bitrate
  72 management.
  73 </dd><p>
  74
  75 <dt><i>OV_ECTL_LOWPASS_GET</i></dt>
  76 <dd><b>Argument: double *</b><br> Returns the current encoder hard-lowpass
  77 setting (kHz) in the double pointed to by arg.
  78 </dd><p>
  79
  80 <dt><i>OV_ECTL_LOWPASS_SET</i></dt>
  81 <dd><b>Argument: double *</b><br> Sets the encoder hard-lowpass to the value
  82 (kHz) pointed to by arg. Valid lowpass settings range from 2 to 99.
  83 </dd><p>
  84
  85 <dt><i>OV_ECTL_IBLOCK_GET</i></dt>
  86 <dd><b>Argument: double *</b><br> Returns the current encoder impulse
  87 block setting in the double pointed to by arg.</dd><p>
  88
  89 <dt><i>OV_ECTL_IBLOCK_SET</i></dt> <dd><b>Argument: double *</b><br> Sets
  90 the impulse block bias to the the value pointed to by arg; valid range
  91 is -15.0 to 0.0 [default].  A negative impulse block bias will direct
  92 to encoder to use more bits when incoding short blocks that contain
  93 strong impulses, thus improving the accuracy of impulse encoding.</dd><p>
  94
  95 <dt><i>OV_ECTL_COUPLING_GET</i></dt>
  96 <dd><b>Argument: int *</b><br>
  97 Returns the current encoder coupling enabled/disabled
  98 setting in the int pointed to by arg.
  99 </dd><p>
 100
 101 <dt><i>OV_ECTL_COUPLING_SET</i></dt>
 102 <dd><b>Argument: int *</b><br>
 103 Enables/disables channel coupling in multichannel encoding according to arg.
 104 *arg of zero disables all channel coupling, nonzero allows the encoder to use
 105 coupling if a coupled mode is available for the input.  At present, coupling
 106 is available for stereo and 5.1 input modes.
 107 </dd><p>
 108
 109 <dt><i>OV_ECTL_RATEMANAGE_GET [deprecated]</i></dt>
 110 <dd>
 111
 112 <b>Argument: <a href="ovectl_ratemanage_arg.html">struct
 113 ovectl_ratemanage_arg *</a></b><br> Old interface to querying bitrate
 114 management settings; deprecated after move to bit-reservoir style
 115 management in 1.1 rendered this interface partially obsolete.  Please
 116 use OV_ECTL_RATEMANGE2_GET instead.
 117
 118 </dd><p>
 119
 120 <dt><i>OV_ECTL_RATEMANAGE_SET [deprecated]</i></dt>
 121 <dd>
 122 <b>Argument: <a href="ovectl_ratemanage_arg.html">struct
 123 ovectl_ratemanage_arg *</a></b><br> Old interface to modifying bitrate
 124 management settings; deprecated after move to bit-reservoir style
 125 management in 1.1 rendered this interface partially obsolete.  Please
 126 use OV_ECTL_RATEMANGE2_SET instead.
 127 </dd><p>
 128
 129 <dt><i>OV_ECTL_RATEMANAGE_AVG [deprecated]</i></dt>
 130 <dd>
 131 <b>Argument: <a href="ovectl_ratemanage_arg.html">struct
 132 ovectl_ratemanage_arg *</a></b><br> Old interface to setting
 133 average-bitrate encoding mode; deprecated after move to bit-reservoir
 134 style management in 1.1 rendered this interface partially obsolete.
 135 Please use OV_ECTL_RATEMANGE2_SET instead.
 136 </dd><p>
 137
 138 <dt><i>OV_ECTL_RATEMANAGE_HARD [deprecated]</i></dt>
 139 <dd>
 140 <b>Argument: <a href="ovectl_ratemanage_arg.html">struct
 141 ovectl_ratemanage_arg *</a></b><br> Old interface to setting
 142 bounded-bitrate encoding modes; deprecated after move to bit-reservoir
 143 style management in 1.1 rendered this interface partially obsolete.
 144 Please use OV_ECTL_RATEMANGE2_SET instead.
 145 </dd><p>
 146
 147
 148 </dl>
 149
 150
 151 <h3>Return Values</h3> vorbis_encode_ctl() returns zero on success,
 152 placing any further return information (such as the result of a query)
 153 into the storage pointed to by <i>*arg</i>.  On error,
 154 vorbis_encode_ctl() may return one of the following error codes:
 155
 156 <dl>
 157
 158 <dt>OV_EINVAL</dt><dd>Invalid argument, or an attempt to modify a
 159 setting after calling <a
 160 href="vorbis_encode_setup_init.html">vorbis_encode_setup_init()</a>.</dd><p>
 161
 162 <dt>OV_EIMPL</dt><dd>Unimplemented or unknown request</dd><p>
 163
 164 </dl>
 165
 166 <p>
 167
 168 <br><br>
 169 <hr noshade>
 170 <table border=0 width=100%>
 171 <tr valign=top>
 172 <td><p class=tiny>copyright &copy; 2004 xiph.org</p></td>
 173 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team@vorbis.org">team@vorbis.org</a></p></td>
 174 </tr><tr>
 175 <td><p class=tiny>libvorbisenc documentation</p></td>
 176 <td align=right><p class=tiny>libvorbisenc release 1.1 - 20040709</p></td>
 177 </tr>
 178 </table>
 179
 180
 181 </body>
 182
 183 </html>