[FFmpeg-cvslog] r25964 - trunk/libavcodec/ac3enc.c
jbr
subversion
Tue Dec 14 15:51:30 CET 2010
Author: jbr
Date: Tue Dec 14 15:51:30 2010
New Revision: 25964
Log:
cosmetics: add new function documentation and clean up existing documentation
Modified:
trunk/libavcodec/ac3enc.c
Modified: trunk/libavcodec/ac3enc.c
==============================================================================
--- trunk/libavcodec/ac3enc.c Tue Dec 14 15:51:26 2010 (r25963)
+++ trunk/libavcodec/ac3enc.c Tue Dec 14 15:51:30 2010 (r25964)
@@ -37,15 +37,24 @@
#define MDCT_NBITS 9
#define MDCT_SAMPLES (1 << MDCT_NBITS)
+/** Scale a float value by 2^bits and convert to an integer. */
#define SCALE_FLOAT(a, bits) lrintf((a) * (float)(1 << (bits)))
+/** Scale a float value by 2^15, convert to an integer, and clip to int16_t range. */
#define FIX15(a) av_clip_int16(SCALE_FLOAT(a, 15))
+/**
+ * Compex number.
+ * Used in fixed-point MDCT calculation.
+ */
typedef struct IComplex {
int16_t re,im;
} IComplex;
+/**
+ * AC-3 encoder private context.
+ */
typedef struct AC3EncodeContext {
PutBitContext pb; ///< bitstream writer context
@@ -89,12 +98,17 @@ typedef struct AC3EncodeContext {
} AC3EncodeContext;
+/** MDCT and FFT tables */
static int16_t costab[64];
static int16_t sintab[64];
static int16_t xcos1[128];
static int16_t xsin1[128];
+/**
+ * Initialize FFT tables.
+ * @param ln log2(FFT size)
+ */
static av_cold void fft_init(int ln)
{
int i, n, n2;
@@ -111,6 +125,10 @@ static av_cold void fft_init(int ln)
}
+/**
+ * Initialize MDCT tables.
+ * @param nbits log2(MDCT size)
+ */
static av_cold void mdct_init(int nbits)
{
int i, n, n4;
@@ -128,7 +146,7 @@ static av_cold void mdct_init(int nbits)
}
-/* butter fly op */
+/** Butterfly op */
#define BF(pre, pim, qre, qim, pre1, pim1, qre1, qim1) \
{ \
int ax, ay, bx, by; \
@@ -143,6 +161,7 @@ static av_cold void mdct_init(int nbits)
}
+/** Complex multiply */
#define CMUL(pre, pim, are, aim, bre, bim) \
{ \
pre = (MUL16(are, bre) - MUL16(aim, bim)) >> 15; \
@@ -150,7 +169,11 @@ static av_cold void mdct_init(int nbits)
}
-/* do a 2^n point complex fft on 2^ln points. */
+/**
+ * Calculate a 2^n point complex FFT on 2^ln points.
+ * @param z complex input/output samples
+ * @param ln log2(FFT size)
+ */
static void fft(IComplex *z, int ln)
{
int j, l, np, np2;
@@ -218,6 +241,11 @@ static void fft(IComplex *z, int ln)
}
+/**
+ * Calculate a 512-point MDCT
+ * @param out 256 output frequency coefficients
+ * @param in 512 windowed input audio samples
+ */
static void mdct512(int32_t *out, int16_t *in)
{
int i, re, im, re1, im1;
@@ -250,7 +278,12 @@ static void mdct512(int32_t *out, int16_
}
-/* compute log2(max(abs(tab[]))) */
+/**
+ * Calculate the log2() of the maximum absolute value in an array.
+ * @param tab input array
+ * @param n number of values in the array
+ * @return log2(max(abs(tab[])))
+ */
static int log2_tab(int16_t *tab, int n)
{
int i, v;
@@ -263,6 +296,12 @@ static int log2_tab(int16_t *tab, int n)
}
+/**
+ * Left-shift each value in an array by a specified amount.
+ * @param tab input array
+ * @param n number of values in the array
+ * @param lshift left shift amount. a negative value means right shift.
+ */
static void lshift_tab(int16_t *tab, int n, int lshift)
{
int i;
@@ -278,6 +317,9 @@ static void lshift_tab(int16_t *tab, int
}
+/**
+ * Calculate the sum of absolute differences (SAD) between 2 sets of exponents.
+ */
static int calc_exp_diff(uint8_t *exp1, uint8_t *exp2, int n)
{
int sum, i;
@@ -288,10 +330,16 @@ static int calc_exp_diff(uint8_t *exp1,
}
-/* new exponents are sent if their Norm 1 exceed this number */
+/**
+ * Exponent Difference Threshold.
+ * New exponents are sent if their SAD exceed this number.
+ */
#define EXP_DIFF_THRESHOLD 1000
+/**
+ * Calculate exponent strategies for all blocks in a single channel.
+ */
static void compute_exp_strategy(uint8_t exp_strategy[AC3_MAX_BLOCKS][AC3_MAX_CHANNELS],
uint8_t exp[AC3_MAX_BLOCKS][AC3_MAX_CHANNELS][AC3_MAX_COEFS],
int ch, int is_lfe)
@@ -330,7 +378,11 @@ static void compute_exp_strategy(uint8_t
}
-/* set exp[i] to min(exp[i], exp1[i]) */
+/**
+ * Set each encoded exponent in a block to the minimum of itself and the
+ * exponent in the same frequency bin of a following block.
+ * exp[i] = min(exp[i], exp1[i]
+ */
static void exponent_min(uint8_t exp[AC3_MAX_COEFS], uint8_t exp1[AC3_MAX_COEFS], int n)
{
int i;
@@ -341,8 +393,10 @@ static void exponent_min(uint8_t exp[AC3
}
-/* update the exponents so that they are the ones the decoder will
- decode. Return the number of bits used to code the exponents */
+/**
+ * Update the exponents so that they are the ones the decoder will decode.
+ * @return the number of bits used to encode the exponents.
+ */
static int encode_exp(uint8_t encoded_exp[AC3_MAX_COEFS],
uint8_t exp[AC3_MAX_COEFS],
int nb_exps, int exp_strategy)
@@ -391,7 +445,9 @@ static int encode_exp(uint8_t encoded_ex
}
-/* return the size in bits taken by the mantissa */
+/**
+ * Calculate the number of bits needed to encode a set of mantissas.
+ */
static int compute_mantissa_size(AC3EncodeContext *s, uint8_t *m, int nb_coefs)
{
int bits, mant, i;
@@ -442,6 +498,10 @@ static int compute_mantissa_size(AC3Enco
}
+/**
+ * Calculate masking curve based on the final exponents.
+ * Also calculate the power spectral densities to use in future calculations.
+ */
static void bit_alloc_masking(AC3EncodeContext *s,
uint8_t encoded_exp[AC3_MAX_BLOCKS][AC3_MAX_CHANNELS][AC3_MAX_COEFS],
uint8_t exp_strategy[AC3_MAX_BLOCKS][AC3_MAX_CHANNELS],
@@ -472,6 +532,13 @@ static void bit_alloc_masking(AC3EncodeC
}
+/**
+ * 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.
+ * @return the number of remaining bits (positive or negative) if the given
+ * SNR offset is used to quantize the mantissas.
+ */
static int bit_alloc(AC3EncodeContext *s,
int16_t mask[AC3_MAX_BLOCKS][AC3_MAX_CHANNELS][50],
int16_t psd[AC3_MAX_BLOCKS][AC3_MAX_CHANNELS][AC3_MAX_COEFS],
@@ -501,6 +568,12 @@ static int bit_alloc(AC3EncodeContext *s
#define SNR_INC1 4
+/**
+ * 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
+ * used to quantize the mantissas.
+ */
static int compute_bit_allocation(AC3EncodeContext *s,
uint8_t bap[AC3_MAX_BLOCKS][AC3_MAX_CHANNELS][AC3_MAX_COEFS],
uint8_t encoded_exp[AC3_MAX_BLOCKS][AC3_MAX_CHANNELS][AC3_MAX_COEFS],
@@ -616,7 +689,9 @@ static int compute_bit_allocation(AC3Enc
}
-/* output the AC-3 frame header */
+/**
+ * Write the AC-3 frame header to the output bitstream.
+ */
static void output_frame_header(AC3EncodeContext *s, unsigned char *frame)
{
init_put_bits(&s->pb, frame, AC3_MAX_CODED_FRAME_SIZE);
@@ -647,7 +722,9 @@ static void output_frame_header(AC3Encod
}
-/* symetric quantization on 'levels' levels */
+/**
+ * Symmetric quantization on 'levels' levels.
+ */
static inline int sym_quant(int c, int e, int levels)
{
int v;
@@ -666,7 +743,9 @@ static inline int sym_quant(int c, int e
}
-/* asymetric quantization on 2^qbits levels */
+/**
+ * Asymmetric quantization on 2^qbits levels.
+ */
static inline int asym_quant(int c, int e, int qbits)
{
int lshift, m, v;
@@ -686,8 +765,9 @@ static inline int asym_quant(int c, int
}
-/* Output one audio block. There are AC3_MAX_BLOCKS audio blocks in one AC-3
- frame */
+/**
+ * Write one audio block to the output bitstream.
+ */
static void output_audio_block(AC3EncodeContext *s,
uint8_t exp_strategy[AC3_MAX_CHANNELS],
uint8_t encoded_exp[AC3_MAX_CHANNELS][AC3_MAX_COEFS],
@@ -920,6 +1000,7 @@ static void output_audio_block(AC3Encode
}
+/** CRC-16 Polynomial */
#define CRC16_POLY ((1 << 0) | (1 << 2) | (1 << 15) | (1 << 16))
@@ -954,7 +1035,9 @@ static unsigned int pow_poly(unsigned in
}
-/* fill the end of the frame and compute the two crcs */
+/**
+ * Fill the end of the frame with 0's and compute the two CRCs.
+ */
static int output_frame_end(AC3EncodeContext *s)
{
int frame_size, frame_size_58, n, crc1, crc2, crc_inv;
@@ -991,6 +1074,9 @@ static int output_frame_end(AC3EncodeCon
}
+/**
+ * Encode a single AC-3 frame.
+ */
static int AC3_encode_frame(AVCodecContext *avctx,
unsigned char *frame, int buf_size, void *data)
{
@@ -1105,6 +1191,9 @@ static int AC3_encode_frame(AVCodecConte
}
+/**
+ * Finalize encoding and free any memory allocated by the encoder.
+ */
static av_cold int AC3_encode_close(AVCodecContext *avctx)
{
av_freep(&avctx->coded_frame);
@@ -1112,6 +1201,9 @@ static av_cold int AC3_encode_close(AVCo
}
+/**
+ * Set channel information during initialization.
+ */
static av_cold int set_channel_info(AC3EncodeContext *s, int channels,
int64_t *channel_layout)
{
@@ -1157,6 +1249,9 @@ static av_cold int set_channel_info(AC3E
}
+/**
+ * Initialize the encoder.
+ */
static av_cold int AC3_encode_init(AVCodecContext *avctx)
{
int freq = avctx->sample_rate;
More information about the ffmpeg-cvslog
mailing list