[FFmpeg-devel] [PATCH] avcodec/vorbisenc: Improve documentation
Tyler Jones
tdjones879 at gmail.com
Wed Aug 23 05:43:24 EEST 2017
Signed-off-by: Tyler Jones <tdjones879 at gmail.com>
---
This patch applies cleanly onto "[PATCH 6/6] avcodec/vorbisenc: Add support
for mono streams".
libavcodec/vorbis_enc_data.h | 20 ++++++++++----------
libavcodec/vorbisenc.c | 43 +++++++++++++++++++++++++++++++++----------
libavcodec/vorbisenc.h | 20 ++++++++++----------
3 files changed, 53 insertions(+), 30 deletions(-)
diff --git a/libavcodec/vorbis_enc_data.h b/libavcodec/vorbis_enc_data.h
index 32750da803..cf94700350 100644
--- a/libavcodec/vorbis_enc_data.h
+++ b/libavcodec/vorbis_enc_data.h
@@ -27,14 +27,14 @@
#define RES_MAX_CLASSIF 10
typedef const struct {
- int dim;
- int len;
- int real_len;
- const uint8_t *clens;
- int lookup;
- float min;
- float delta;
- const uint8_t *quant;
+ int dim; ///< The number of elements per coded vector
+ int len; ///< The number of filled entries in the book
+ int real_len; ///< The expected number of entries, padded with 0 if len < real_len
+ const uint8_t *clens; ///< List of codeword lengths in bits
+ int lookup; ///< Flag if vector lookup is available with this book
+ float min; ///< The minimum value encoded by this book
+ float delta; ///< The distance between encoded points
+ const uint8_t *quant; ///< Pointer to a (entries)^(1/dim) column map if lookup is set
} codebook_setup;
typedef const struct {
@@ -817,8 +817,8 @@ static codebook_setup res_mono_config[] = {
};
static const struct {
- int dim;
- int subclass;
+ int dim; ///< Dimensions of the class master book
+ int subclass; ///< Integer log base 2 of the number of subclass books
int masterbook;
const int nbooks[4];
} floor_classes[2][5] = {
diff --git a/libavcodec/vorbisenc.c b/libavcodec/vorbisenc.c
index f4af2f4071..78b41b2b49 100644
--- a/libavcodec/vorbisenc.c
+++ b/libavcodec/vorbisenc.c
@@ -414,7 +414,7 @@ static void put_codebook_header(PutBitContext *pb, vorbis_enc_codebook *cb)
int i;
int ordered = 0;
- put_bits(pb, 24, 0x564342); //magic
+ put_bits(pb, 24, 0x564342); // Signal the start of a codebook
put_bits(pb, 16, cb->ndimensions);
put_bits(pb, 24, cb->nentries);
@@ -520,6 +520,7 @@ static void put_residue_header(PutBitContext *pb, vorbis_enc_residue *rc,
put_bits(pb, 6, rc->classifications - 1);
put_bits(pb, 8, book_offset + rc->classbook);
+ /* We must specify which partition classes are used in each pass */
for (i = 0; i < rc->classifications; i++) {
int j, tmp = 0;
for (j = 0; j < 8; j++)
@@ -540,6 +541,13 @@ static void put_residue_header(PutBitContext *pb, vorbis_enc_residue *rc,
}
}
+/**
+ * Output necessary information for all primary headers.
+ *
+ * @see Vorbis I spec "4.2. Header decode and decode setup"
+ * @param out Empty buffer on input, encoded headers on output
+ * @return Number of bits written to the buffer or error value
+ */
static int put_main_header(vorbis_enc_context *venc, uint8_t **out)
{
int i;
@@ -552,15 +560,15 @@ static int put_main_header(vorbis_enc_context *venc, uint8_t **out)
// identification header
init_put_bits(&pb, p, buffer_len);
- put_bits(&pb, 8, 1); //magic
+ put_bits(&pb, 8, 1); // Signal an ID header
for (i = 0; "vorbis"[i]; i++)
put_bits(&pb, 8, "vorbis"[i]);
put_bits32(&pb, 0); // version
put_bits(&pb, 8, venc->channels);
put_bits32(&pb, venc->sample_rate);
- put_bits32(&pb, 0); // bitrate
- put_bits32(&pb, 0); // bitrate
- put_bits32(&pb, 0); // bitrate
+ put_bits32(&pb, 0); // Maximum bitrate
+ put_bits32(&pb, 0); // Nominal bitrate
+ put_bits32(&pb, 0); // Minimum bitrate
put_bits(&pb, 4, venc->log2_blocksize[0]);
put_bits(&pb, 4, venc->log2_blocksize[1]);
put_bits(&pb, 1, 1); // framing
@@ -572,11 +580,11 @@ static int put_main_header(vorbis_enc_context *venc, uint8_t **out)
// comment header
init_put_bits(&pb, p, buffer_len);
- put_bits(&pb, 8, 3); //magic
+ put_bits(&pb, 8, 3); // Signal a comment header
for (i = 0; "vorbis"[i]; i++)
put_bits(&pb, 8, "vorbis"[i]);
put_bits32(&pb, 0); // vendor length TODO
- put_bits32(&pb, 0); // amount of comments
+ put_bits32(&pb, 0); // amount of comments TODO
put_bits(&pb, 1, 1); // framing
flush_put_bits(&pb);
@@ -586,7 +594,7 @@ static int put_main_header(vorbis_enc_context *venc, uint8_t **out)
// setup header
init_put_bits(&pb, p, buffer_len);
- put_bits(&pb, 8, 5); //magic
+ put_bits(&pb, 8, 5); // Signal a setup header
for (i = 0; "vorbis"[i]; i++)
put_bits(&pb, 8, "vorbis"[i]);
@@ -623,7 +631,7 @@ static int put_main_header(vorbis_enc_context *venc, uint8_t **out)
if (mc->submaps > 1)
put_bits(&pb, 4, mc->submaps - 1);
- put_bits(&pb, 1, !!mc->coupling_steps);
+ put_bits(&pb, 1, !!mc->coupling_steps); // Signal if square polar channel mapping is used
if (mc->coupling_steps) {
put_bits(&pb, 8, mc->coupling_steps - 1);
for (j = 0; j < mc->coupling_steps; j++) {
@@ -937,7 +945,13 @@ static int residue_encode(vorbis_enc_context *venc, vorbis_enc_residue *rc,
/**
* Overlap windowed samples based on the suggested sequence from psy model.
+ *
* See Vorbis I spec Fig. 2, 3 for examples.
+ *
+ * @param blockflags Determines the window size to use for previous, current, and next frame
+ * @param out Pointer to windowed samples suitable for correct overlapping
+ * @param in Pointer to unmodified samples from the input stream
+ * @param clip_factor Scalar coefficient used to avoid clipping, especially for short windows
*/
static void apply_window(vorbis_enc_context *venc, const int *blockflags,
float *out, float* in, const float clip_factor)
@@ -975,6 +989,11 @@ static void apply_window(vorbis_enc_context *venc, const int *blockflags,
fdsp->vector_fmul_scalar(out, out, scale, 2 * curr_size);
}
+/**
+ * Window input samples and apply the correct MDCT
+ *
+ * @param next_type Flag that specifies the length type of the next frame, exhibits a full block delay.
+ */
static int apply_window_and_mdct(vorbis_enc_context *venc, int next_type)
{
int channel, transient_offset, curr_len, curr_type;
@@ -993,6 +1012,7 @@ static int apply_window_and_mdct(vorbis_enc_context *venc, int next_type)
if (!curr_type)
venc->transient++;
+ /* A short window must always treat the windows before and after as short as well. */
blockflags[0] = curr_type ? blockflags[1] : 0;
blockflags[1] = curr_type;
blockflags[2] = curr_type ? next_type : 0;
@@ -1008,6 +1028,7 @@ static int apply_window_and_mdct(vorbis_enc_context *venc, int next_type)
venc->coeffs + channel * curr_len, out);
}
+ /* We must also check to see if we are leaving the series of transients */
if (venc->transient < 0 || venc->transient >= venc->num_transient - 1) {
blockflags[2] = next_type;
venc->transient = -1;
@@ -1015,7 +1036,9 @@ static int apply_window_and_mdct(vorbis_enc_context *venc, int next_type)
return 1;
}
-/* Used for padding the last encoded packet */
+/**
+ * Create a padding frame with zeroed samples so that a full block of samples is available.
+ */
static AVFrame *spawn_empty_frame(AVCodecContext *avctx, int channels)
{
AVFrame *f = av_frame_alloc();
diff --git a/libavcodec/vorbisenc.h b/libavcodec/vorbisenc.h
index 15ee02dfa6..dc1ff06db8 100644
--- a/libavcodec/vorbisenc.h
+++ b/libavcodec/vorbisenc.h
@@ -67,15 +67,15 @@ typedef struct vorbis_enc_floor {
int nclasses;
vorbis_enc_floor_class *classes;
int multiplier;
- int rangebits;
+ int rangebits; ///< Number of bits required to represent the max window size
int values;
vorbis_floor1_entry *list;
} vorbis_enc_floor;
typedef struct vorbis_enc_residue {
int type;
- int begin;
- int end;
+ int begin; ///< Index of the actual start of coded residue values
+ int end; ///< Final index of coded residue values
int partition_size;
int classifications;
int classbook;
@@ -89,8 +89,8 @@ typedef struct vorbis_enc_mapping {
int *floor;
int *residue;
int coupling_steps;
- int *magnitude;
- int *angle;
+ int *magnitude; ///< Index offsetting for the magnitude vector used in coupling
+ int *angle; ///< Index offsetting for the angle vector used in coupling
} vorbis_enc_mapping;
typedef struct vorbis_enc_mode {
@@ -108,12 +108,12 @@ typedef struct vorbis_enc_context {
FFTContext mdct[2];
const float *win[2];
int have_saved;
- float *saved;
+ float *saved; ///< Old samples for window application between frames
float *samples;
- float *floor; // also used for tmp values for mdct
- float *coeffs; // also used for residue after floor
- float *scratch; //< Used for temp values for psy model and window application
- float quality;
+ float *floor; ///< Calculated floor values removed from mdct output
+ float *coeffs; ///< MDCT output used as the input for residue encoding
+ float *scratch; ///< Used for temp values for psy model and window application
+ float quality; ///< Controls the resolution for floor construction
AudioFrameQueue afq;
struct FFBufQueue bufqueue;
--
2.14.1
More information about the ffmpeg-devel
mailing list