This function implements a generic interface to miscellaneous
encoder settings similar to the clasasic UNIX 'ioctl()' system call.
Applications may use vorbis_encode_ctl() to query or set bitrate
management or quality mode details by using one of several
request arguments detailed below. Vorbis_encode_ctl() must be
called after one of vorbis_encode_setup_managed()
or vorbis_encode_setup_vbr().
When used to modify settings, vorbis_encode_ctl() must be called
before vorbis_encode_setup_init().
extern int vorbis_encode_ctl(vorbis_info *vi,int request,void *arg);
Parameters
vi
File pointer to an initialized vorbis_info struct.
request
Specifies the desired action; possible request fields are detailed below.
arg
void * pointing to a data structure matching the request argument.
Requests
OV_ECTL_RATEMANAGE2_GET
Argument: struct
ovectl_ratemanage2_arg * Used to query the current
encoder bitrate management setting. Also used to initialize fields of
an ovectl_ratemanage2_arg structure for use with
OV_ECTL_RATEMANAGE2_SET.
OV_ECTL_RATEMANAGE2_SET
Argument: struct
ovectl_ratemanage2_arg * Used to set the current
encoder bitrate management settings to the values listed in the
ovectl_ratemanage2_arg. Passing a NULL pointer will disable bitrate
management.
OV_ECTL_LOWPASS_GET
Argument: double * Returns the current encoder hard-lowpass
setting (kHz) in the double pointed to by arg.
OV_ECTL_LOWPASS_SET
Argument: double * Sets the encoder hard-lowpass to the value
(kHz) pointed to by arg. Valid lowpass settings range from 2 to 99.
OV_ECTL_IBLOCK_GET
Argument: double * Returns the current encoder impulse
block setting in the double pointed to by arg.
OV_ECTL_IBLOCK_SET
Argument: double * Sets
the impulse block bias to the the value pointed to by arg; valid range
is -15.0 to 0.0 [default]. A negative impulse block bias will direct
to encoder to use more bits when incoding short blocks that contain
strong impulses, thus improving the accuracy of impulse encoding.
OV_ECTL_RATEMANAGE_GET [deprecated]
Argument: struct
ovectl_ratemanage_arg * Old interface to querying bitrate
management settings; deprecated after move to bit-reservoir style
management in 1.1 rendered this interface partially obsolete. Please
use OV_ECTL_RATEMANGE2_GET instead.
OV_ECTL_RATEMANAGE_SET [deprecated]
Argument: struct
ovectl_ratemanage_arg * Old interface to modifying bitrate
management settings; deprecated after move to bit-reservoir style
management in 1.1 rendered this interface partially obsolete. Please
use OV_ECTL_RATEMANGE2_SET instead.
OV_ECTL_RATEMANAGE_AVG [deprecated]
Argument: struct
ovectl_ratemanage_arg * Old interface to setting
average-bitrate encoding mode; deprecated after move to bit-reservoir
style management in 1.1 rendered this interface partially obsolete.
Please use OV_ECTL_RATEMANGE2_SET instead.
OV_ECTL_RATEMANAGE_HARD [deprecated]
Argument: struct
ovectl_ratemanage_arg * Old interface to setting
bounded-bitrate encoding modes; deprecated after move to bit-reservoir
style management in 1.1 rendered this interface partially obsolete.
Please use OV_ECTL_RATEMANGE2_SET instead.
Return Values
vorbis_encode_ctl() returns zero on success,
placing any further return information (such as the result of a query)
into the storage pointed to by *arg. On error,
vorbis_encode_ctl() may return one of the following error codes: