mirror of
https://github.com/FFmpeg/FFmpeg.git
synced 2024-12-23 12:43:46 +02:00
ac3enc: doxygen update.
Add some parameters to existing function documentation. Remove some unneeded documentation. Convert some static function documentation to non-doxygen style.
This commit is contained in:
Justin Ruggles
parent
a4998e448f
commit
c2d9a65bc0
@ -176,6 +176,8 @@ static const int8_t ac3_coupling_start_tab[6][3][19] = {
|
||||
/**
|
||||
* Adjust the frame size to make the average bit rate match the target bit rate.
|
||||
* This is only needed for 11025, 22050, and 44100 sample rates or any E-AC-3.
|
||||
*
|
||||
* @param s AC-3 encoder private context
|
||||
*/
|
||||
void ff_ac3_adjust_frame_size(AC3EncodeContext *s)
|
||||
{
|
||||
@ -190,6 +192,11 @@ void ff_ac3_adjust_frame_size(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Set the initial coupling strategy parameters prior to coupling analysis.
|
||||
*
|
||||
* @param s AC-3 encoder private context
|
||||
*/
|
||||
void ff_ac3_compute_coupling_strategy(AC3EncodeContext *s)
|
||||
{
|
||||
int blk, ch;
|
||||
@ -258,6 +265,8 @@ void ff_ac3_compute_coupling_strategy(AC3EncodeContext *s)
|
||||
|
||||
/**
|
||||
* Apply stereo rematrixing to coefficients based on rematrixing flags.
|
||||
*
|
||||
* @param s AC-3 encoder private context
|
||||
*/
|
||||
void ff_ac3_apply_rematrixing(AC3EncodeContext *s)
|
||||
{
|
||||
@ -290,7 +299,7 @@ void ff_ac3_apply_rematrixing(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Initialize exponent tables.
|
||||
*/
|
||||
static av_cold void exponent_init(AC3EncodeContext *s)
|
||||
@ -312,7 +321,7 @@ static av_cold void exponent_init(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Extract exponents from the MDCT coefficients.
|
||||
*/
|
||||
static void extract_exponents(AC3EncodeContext *s)
|
||||
@ -341,7 +350,7 @@ static const uint8_t exp_strategy_reuse_tab[4][6] = {
|
||||
{ EXP_D45, EXP_D25, EXP_D25, EXP_D15, EXP_D15, EXP_D15 }
|
||||
};
|
||||
|
||||
/**
|
||||
/*
|
||||
* Calculate exponent strategies for all channels.
|
||||
* Array arrangement is reversed to simplify the per-channel calculation.
|
||||
*/
|
||||
@ -405,6 +414,11 @@ static void compute_exp_strategy(AC3EncodeContext *s)
|
||||
|
||||
/**
|
||||
* Update the exponents so that they are the ones the decoder will decode.
|
||||
*
|
||||
* @param[in,out] exp array of exponents for 1 block in 1 channel
|
||||
* @param nb_exps number of exponents in active bandwidth
|
||||
* @param exp_strategy exponent strategy for the block
|
||||
* @param cpl indicates if the block is in the coupling channel
|
||||
*/
|
||||
static void encode_exponents_blk_ch(uint8_t *exp, int nb_exps, int exp_strategy,
|
||||
int cpl)
|
||||
@ -473,7 +487,7 @@ static void encode_exponents_blk_ch(uint8_t *exp, int nb_exps, int exp_strategy,
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Encode exponents from original extracted form to what the decoder will see.
|
||||
* This copies and groups exponents based on exponent strategy and reduces
|
||||
* deltas between adjacent exponent groups so that they can be differentially
|
||||
@ -526,7 +540,7 @@ static void encode_exponents(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Count exponent bits based on bandwidth, coupling, and exponent strategies.
|
||||
*/
|
||||
static int count_exponent_bits(AC3EncodeContext *s)
|
||||
@ -558,6 +572,8 @@ static int count_exponent_bits(AC3EncodeContext *s)
|
||||
* Group exponents.
|
||||
* 3 delta-encoded exponents are in each 7-bit group. The number of groups
|
||||
* varies depending on exponent strategy and bandwidth.
|
||||
*
|
||||
* @param s AC-3 encoder private context
|
||||
*/
|
||||
void ff_ac3_group_exponents(AC3EncodeContext *s)
|
||||
{
|
||||
@ -614,6 +630,8 @@ void ff_ac3_group_exponents(AC3EncodeContext *s)
|
||||
* Calculate final exponents from the supplied MDCT coefficients and exponent shift.
|
||||
* Extract exponents from MDCT coefficients, calculate exponent strategies,
|
||||
* and encode final exponents.
|
||||
*
|
||||
* @param s AC-3 encoder private context
|
||||
*/
|
||||
void ff_ac3_process_exponents(AC3EncodeContext *s)
|
||||
{
|
||||
@ -627,7 +645,7 @@ void ff_ac3_process_exponents(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Count frame bits that are based solely on fixed parameters.
|
||||
* This only has to be run once when the encoder is initialized.
|
||||
*/
|
||||
@ -733,7 +751,7 @@ static void count_frame_bits_fixed(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Initialize bit allocation.
|
||||
* Set default parameter codes and calculate parameter values.
|
||||
*/
|
||||
@ -768,7 +786,7 @@ static void bit_alloc_init(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Count the bits used to encode the frame, minus exponents and mantissas.
|
||||
* Bits based on fixed parameters have already been counted, so now we just
|
||||
* have to add the bits based on parameters that change during encoding.
|
||||
@ -915,7 +933,7 @@ static void count_frame_bits(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Calculate masking curve based on the final exponents.
|
||||
* Also calculate the power spectral densities to use in future calculations.
|
||||
*/
|
||||
@ -945,7 +963,7 @@ static void bit_alloc_masking(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Ensure that bap for each block and channel point to the current bap_buffer.
|
||||
* They may have been switched during the bit allocation search.
|
||||
*/
|
||||
@ -971,6 +989,8 @@ static void reset_block_bap(AC3EncodeContext *s)
|
||||
* Initialize mantissa counts.
|
||||
* These are set so that they are padded to the next whole group size when bits
|
||||
* are counted in compute_mantissa_size.
|
||||
*
|
||||
* @param[in,out] mant_cnt running counts for each bap value for each block
|
||||
*/
|
||||
static void count_mantissa_bits_init(uint16_t mant_cnt[AC3_MAX_BLOCKS][16])
|
||||
{
|
||||
@ -987,6 +1007,12 @@ static void count_mantissa_bits_init(uint16_t mant_cnt[AC3_MAX_BLOCKS][16])
|
||||
/**
|
||||
* Update mantissa bit counts for all blocks in 1 channel in a given bandwidth
|
||||
* range.
|
||||
*
|
||||
* @param s AC-3 encoder private context
|
||||
* @param ch channel index
|
||||
* @param[in,out] mant_cnt running counts for each bap value for each block
|
||||
* @param start starting coefficient bin
|
||||
* @param end ending coefficient bin
|
||||
*/
|
||||
static void count_mantissa_bits_update_ch(AC3EncodeContext *s, int ch,
|
||||
uint16_t mant_cnt[AC3_MAX_BLOCKS][16],
|
||||
@ -1005,7 +1031,7 @@ static void count_mantissa_bits_update_ch(AC3EncodeContext *s, int ch,
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Count the number of mantissa bits in the frame based on the bap values.
|
||||
*/
|
||||
static int count_mantissa_bits(AC3EncodeContext *s)
|
||||
@ -1028,6 +1054,9 @@ static int count_mantissa_bits(AC3EncodeContext *s)
|
||||
* Run the bit allocation with a given SNR offset.
|
||||
* This calculates the bit allocation pointers that will be used to determine
|
||||
* the quantization of each mantissa.
|
||||
*
|
||||
* @param s AC-3 encoder private context
|
||||
* @param snr_offset SNR offset, 0 to 1023
|
||||
* @return the number of bits needed for mantissas if the given SNR offset is
|
||||
* is used.
|
||||
*/
|
||||
@ -1058,7 +1087,7 @@ static int bit_alloc(AC3EncodeContext *s, int snr_offset)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Constant bitrate bit allocation search.
|
||||
* Find the largest SNR offset that will allow data to fit in the frame.
|
||||
*/
|
||||
@ -1107,7 +1136,7 @@ static int cbr_bit_allocation(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Perform bit allocation search.
|
||||
* Finds the SNR offset value that maximizes quality and fits in the specified
|
||||
* frame size. Output is the SNR offset and a set of bit allocation pointers
|
||||
@ -1127,6 +1156,11 @@ int ff_ac3_compute_bit_allocation(AC3EncodeContext *s)
|
||||
|
||||
/**
|
||||
* Symmetric quantization on 'levels' levels.
|
||||
*
|
||||
* @param c unquantized coefficient
|
||||
* @param e exponent
|
||||
* @param levels number of quantization levels
|
||||
* @return quantized coefficient
|
||||
*/
|
||||
static inline int sym_quant(int c, int e, int levels)
|
||||
{
|
||||
@ -1138,6 +1172,11 @@ static inline int sym_quant(int c, int e, int levels)
|
||||
|
||||
/**
|
||||
* Asymmetric quantization on 2^qbits levels.
|
||||
*
|
||||
* @param c unquantized coefficient
|
||||
* @param e exponent
|
||||
* @param qbits number of quantization bits
|
||||
* @return quantized coefficient
|
||||
*/
|
||||
static inline int asym_quant(int c, int e, int qbits)
|
||||
{
|
||||
@ -1154,6 +1193,14 @@ static inline int asym_quant(int c, int e, int qbits)
|
||||
|
||||
/**
|
||||
* Quantize a set of mantissas for a single channel in a single block.
|
||||
*
|
||||
* @param s Mantissa count context
|
||||
* @param fixed_coef unquantized fixed-point coefficients
|
||||
* @param exp exponents
|
||||
* @param bap bit allocation pointer indices
|
||||
* @param[out] qmant quantized coefficients
|
||||
* @param start_freq starting coefficient bin
|
||||
* @param end_freq ending coefficient bin
|
||||
*/
|
||||
static void quantize_mantissas_blk_ch(AC3Mant *s, int32_t *fixed_coef,
|
||||
uint8_t *exp, uint8_t *bap,
|
||||
@ -1249,6 +1296,8 @@ static void quantize_mantissas_blk_ch(AC3Mant *s, int32_t *fixed_coef,
|
||||
|
||||
/**
|
||||
* Quantize mantissas using coefficients, exponents, and bit allocation pointers.
|
||||
*
|
||||
* @param s AC-3 encoder private context
|
||||
*/
|
||||
void ff_ac3_quantize_mantissas(AC3EncodeContext *s)
|
||||
{
|
||||
@ -1276,7 +1325,7 @@ void ff_ac3_quantize_mantissas(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Write the AC-3 frame header to the output bitstream.
|
||||
*/
|
||||
static void ac3_output_frame_header(AC3EncodeContext *s)
|
||||
@ -1332,7 +1381,7 @@ static void ac3_output_frame_header(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Write one audio block to the output bitstream.
|
||||
*/
|
||||
static void output_audio_block(AC3EncodeContext *s, int blk)
|
||||
@ -1560,7 +1609,7 @@ static unsigned int pow_poly(unsigned int a, unsigned int n, unsigned int poly)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Fill the end of the frame with 0's and compute the two CRCs.
|
||||
*/
|
||||
static void output_frame_end(AC3EncodeContext *s)
|
||||
@ -1608,6 +1657,9 @@ static void output_frame_end(AC3EncodeContext *s)
|
||||
|
||||
/**
|
||||
* Write the frame to the output bitstream.
|
||||
*
|
||||
* @param s AC-3 encoder private context
|
||||
* @param frame output data buffer
|
||||
*/
|
||||
void ff_ac3_output_frame(AC3EncodeContext *s, unsigned char *frame)
|
||||
{
|
||||
@ -1778,6 +1830,8 @@ static void validate_mix_level(void *log_ctx, const char *opt_name,
|
||||
/**
|
||||
* Validate metadata options as set by AVOption system.
|
||||
* These values can optionally be changed per-frame.
|
||||
*
|
||||
* @param s AC-3 encoder private context
|
||||
*/
|
||||
int ff_ac3_validate_metadata(AC3EncodeContext *s)
|
||||
{
|
||||
@ -1960,6 +2014,8 @@ int ff_ac3_validate_metadata(AC3EncodeContext *s)
|
||||
|
||||
/**
|
||||
* Finalize encoding and free any memory allocated by the encoder.
|
||||
*
|
||||
* @param avctx Codec context
|
||||
*/
|
||||
av_cold int ff_ac3_encode_close(AVCodecContext *avctx)
|
||||
{
|
||||
@ -2003,7 +2059,7 @@ av_cold int ff_ac3_encode_close(AVCodecContext *avctx)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Set channel information during initialization.
|
||||
*/
|
||||
static av_cold int set_channel_info(AC3EncodeContext *s, int channels,
|
||||
@ -2173,7 +2229,7 @@ static av_cold int validate_options(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Set bandwidth for all channels.
|
||||
* The user can optionally supply a cutoff frequency. Otherwise an appropriate
|
||||
* default value will be used.
|
||||
@ -2351,9 +2407,6 @@ alloc_fail:
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Initialize the encoder.
|
||||
*/
|
||||
av_cold int ff_ac3_encode_init(AVCodecContext *avctx)
|
||||
{
|
||||
AC3EncodeContext *s = avctx->priv_data;
|
||||
|
||||
@ -41,6 +41,8 @@ static const AVClass ac3enc_class = { "Fixed-Point AC-3 Encoder", av_default_ite
|
||||
|
||||
/**
|
||||
* Finalize MDCT and free allocated memory.
|
||||
*
|
||||
* @param s AC-3 encoder private context
|
||||
*/
|
||||
av_cold void AC3_NAME(mdct_end)(AC3EncodeContext *s)
|
||||
{
|
||||
@ -50,7 +52,9 @@ av_cold void AC3_NAME(mdct_end)(AC3EncodeContext *s)
|
||||
|
||||
/**
|
||||
* Initialize MDCT tables.
|
||||
* @param nbits log2(MDCT size)
|
||||
*
|
||||
* @param s AC-3 encoder private context
|
||||
* @return 0 on success, negative error code on failure
|
||||
*/
|
||||
av_cold int AC3_NAME(mdct_init)(AC3EncodeContext *s)
|
||||
{
|
||||
@ -60,7 +64,7 @@ av_cold int AC3_NAME(mdct_init)(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Apply KBD window to input samples prior to MDCT.
|
||||
*/
|
||||
static void apply_window(DSPContext *dsp, int16_t *output, const int16_t *input,
|
||||
@ -70,11 +74,9 @@ static void apply_window(DSPContext *dsp, int16_t *output, const int16_t *input,
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Normalize the input samples to use the maximum available precision.
|
||||
* This assumes signed 16-bit input samples.
|
||||
*
|
||||
* @return exponent shift
|
||||
*/
|
||||
static int normalize_samples(AC3EncodeContext *s)
|
||||
{
|
||||
@ -87,7 +89,7 @@ static int normalize_samples(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Scale MDCT coefficients to 25-bit signed fixed-point.
|
||||
*/
|
||||
static void scale_coefficients(AC3EncodeContext *s)
|
||||
@ -104,7 +106,7 @@ static void scale_coefficients(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Clip MDCT coefficients to allowable range.
|
||||
*/
|
||||
static void clip_coefficients(DSPContext *dsp, int32_t *coef, unsigned int len)
|
||||
@ -113,7 +115,7 @@ static void clip_coefficients(DSPContext *dsp, int32_t *coef, unsigned int len)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Calculate a single coupling coordinate.
|
||||
*/
|
||||
static CoefType calc_cpl_coord(CoefSumType energy_ch, CoefSumType energy_cpl)
|
||||
|
||||
@ -44,6 +44,8 @@ static const AVClass ac3enc_class = { "AC-3 Encoder", av_default_item_name,
|
||||
|
||||
/**
|
||||
* Finalize MDCT and free allocated memory.
|
||||
*
|
||||
* @param s AC-3 encoder private context
|
||||
*/
|
||||
av_cold void ff_ac3_float_mdct_end(AC3EncodeContext *s)
|
||||
{
|
||||
@ -54,7 +56,9 @@ av_cold void ff_ac3_float_mdct_end(AC3EncodeContext *s)
|
||||
|
||||
/**
|
||||
* Initialize MDCT tables.
|
||||
* @param nbits log2(MDCT size)
|
||||
*
|
||||
* @param s AC-3 encoder private context
|
||||
* @return 0 on success, negative error code on failure
|
||||
*/
|
||||
av_cold int ff_ac3_float_mdct_init(AC3EncodeContext *s)
|
||||
{
|
||||
@ -78,7 +82,7 @@ av_cold int ff_ac3_float_mdct_init(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Apply KBD window to input samples prior to MDCT.
|
||||
*/
|
||||
static void apply_window(DSPContext *dsp, float *output, const float *input,
|
||||
@ -88,7 +92,7 @@ static void apply_window(DSPContext *dsp, float *output, const float *input,
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Normalize the input samples.
|
||||
* Not needed for the floating-point encoder.
|
||||
*/
|
||||
@ -98,7 +102,7 @@ static int normalize_samples(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Scale MDCT coefficients from float to 24-bit fixed-point.
|
||||
*/
|
||||
static void scale_coefficients(AC3EncodeContext *s)
|
||||
@ -111,7 +115,7 @@ static void scale_coefficients(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Clip MDCT coefficients to allowable range.
|
||||
*/
|
||||
static void clip_coefficients(DSPContext *dsp, float *coef, unsigned int len)
|
||||
@ -120,7 +124,7 @@ static void clip_coefficients(DSPContext *dsp, float *coef, unsigned int len)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Calculate a single coupling coordinate.
|
||||
*/
|
||||
static CoefType calc_cpl_coord(CoefSumType energy_ch, CoefSumType energy_cpl)
|
||||
|
||||
@ -64,7 +64,7 @@ alloc_fail:
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Deinterleave input samples.
|
||||
* Channels are reordered from Libav's default order to AC-3 order.
|
||||
*/
|
||||
@ -93,7 +93,7 @@ static void deinterleave_input_samples(AC3EncodeContext *s,
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Apply the MDCT to input samples to generate frequency coefficients.
|
||||
* This applies the KBD window and normalizes the input to reduce precision
|
||||
* loss due to fixed-point calculations.
|
||||
@ -120,7 +120,7 @@ static void apply_mdct(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Calculate coupling channel and coupling coordinates.
|
||||
*/
|
||||
static void apply_channel_coupling(AC3EncodeContext *s)
|
||||
@ -328,7 +328,7 @@ static void apply_channel_coupling(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
/*
|
||||
* Determine rematrixing flags for each block and band.
|
||||
*/
|
||||
static void compute_rematrixing_strategy(AC3EncodeContext *s)
|
||||
@ -391,9 +391,6 @@ static void compute_rematrixing_strategy(AC3EncodeContext *s)
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Encode a single AC-3 frame.
|
||||
*/
|
||||
int AC3_NAME(encode_frame)(AVCodecContext *avctx, unsigned char *frame,
|
||||
int buf_size, void *data)
|
||||
{
|
||||
|
||||
Loading…
Reference in New Issue
Block a user