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