From patchwork Wed Aug 23 02:43:24 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tyler Jones X-Patchwork-Id: 4801 Delivered-To: ffmpegpatchwork@gmail.com Received: by 10.2.137.29 with SMTP id o29csp1472660jaj; Tue, 22 Aug 2017 19:43:33 -0700 (PDT) X-Received: by 10.223.179.196 with SMTP id x4mr515229wrd.86.1503456213282; Tue, 22 Aug 2017 19:43:33 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1503456213; cv=none; d=google.com; s=arc-20160816; b=dSwnV3AfcbYSjL+5fYtYqVcDkUX+0sv/M0aUF3lRlmSD0CkGKRMpBiLXYux00ptQt6 ByiIxyE64B0HocssH49x8PR6dk5nTygN4nAeE5O4n8cbLtwBdmzE36+yy8z+EQwusWhU N8ZItMP6pPppiLGVDI9OP+eq5UkFG+m0zb2noJ6AnElSp+4oWZ9qUStXZ/40Soznw+Li NaSdMGcoP6Sxe/+04/bNdzuBNtUJH8486aLwGaIY8oH/MjCbyTCB2UWjssaHn26hKL+0 hS8US8JLYHCFInKpePParz/seq2def2xefsLwedTx1xBYwlMKSaTxq0d7sttcXByfjz4 Rg6w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:mime-version:reply-to :list-subscribe:list-help:list-post:list-archive:list-unsubscribe :list-id:precedence:subject:references:in-reply-to:message-id:date :to:from:dkim-signature:delivered-to:arc-authentication-results; bh=Vgy3/HKwiaxBtLqe+aj4N5HOccu5WYw0Gg4EnEfo8tQ=; b=M54eo58tdNxO09tOKCr8X7Pi5bzF+qM9DF7KLurgzEtQ1GTRfTc+13camglyuMAMfu vRbX07rxVeI0qlhn9kHPJzzsyIUM7NskiLfTCFLq82Y5Mro1MVpFPWz/6BN1+Qsf1CJP VHPRZsvFGCI2gAedHZ36Ogqg6h7YiPUeL51hucF6zm/+y9pqgAT28vxLFYbFsHEhzivb WmbNsxdcdhh9dQ8PUOpFmjYlCnvF/xm1k39F2xKko2GdIjCCkkJs28s1QYVqniP2FARa fj+k5XkJwGbwdxuW5BoxhQ2UyxtAB00w6McT0fg16HfnChJt3302205MjLwh7dY/D7TF fWSA== ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20161025 header.b=SxMYeCT0; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=gmail.com Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id b2si351315wrh.536.2017.08.22.19.43.32; Tue, 22 Aug 2017 19:43:33 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20161025 header.b=SxMYeCT0; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=gmail.com Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 6A22A689C63; Wed, 23 Aug 2017 05:43:22 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail-io0-f194.google.com (mail-io0-f194.google.com [209.85.223.194]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id A387A689C63 for ; Wed, 23 Aug 2017 05:43:15 +0300 (EEST) Received: by mail-io0-f194.google.com with SMTP id m40so570088ioi.4 for ; Tue, 22 Aug 2017 19:43:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:subject:date:message-id:in-reply-to:references; bh=bWJy2n7OUW/L6AL+ko7p1K2l6tG3qMV5GQJPlWn3M0Q=; b=SxMYeCT0wRYBd9FpXBfmVg5ULYDbUp9AixORIphPoCNF+MB101QfJpNWMkkdieNBRU iQyW2Ap/5RWbjrsjN6wuvhxzAB1gYE0QULlB8LW96/RNbr+rE0/mDz7so2WPzUHFxiZ9 6E1wzGwhDYT/Er714r1saNiN2ZekGW38+dh6JAxz3Gp1lx4t6z1LpXjsxxj5Se9Hqqp7 xE4A4KutZixxU4TfWcozKyN5JPlhT/A0slhVjwtxU3jYnjpaO2y21wRr0E/+GxAfM4xX D/OTcfFNcgoBKTh8mLweALHkmMKWmAffAQfS1ElqAug9kz9YxhDAjpzEO8govPKrv3vZ QBqQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:in-reply-to :references; bh=bWJy2n7OUW/L6AL+ko7p1K2l6tG3qMV5GQJPlWn3M0Q=; b=ZTKF9wGYDz/8Hp+pRjjDrcN/JlXE8AiDcJx7j/xH4hAbJHJwhx8KHPT94VqVTPzxfA Q8jFyTVWWV9aYueKdChOoNGwelF/+dUqgdgqtTE+Vu6zNEK8cjpuvcyxs3ftXfjVRgf9 I6bmQrBD/O6URhc5GcTWGHTO0pOXDK6ErVVXgLE3HVK/t1I68syiXdPreq98GfZRK82f 3S+MZCIFLhgl8IxNAff+3V8jfOBJdOA2HVF3ACwtOtn342zBe9HH44lW5Anj2J0tTOAO TSUCMt/5U8yQT3NQ26e1mEri9Pgh6OsQ7gUsowH/iKiEJzibnNTdth+RRVwcLPeSeavO NXPg== X-Gm-Message-State: AHYfb5gbUeRILChxJP7qnifHajn9UfBJ+/tpZbmQZG1Ejbld64x26PDB ReD06DH0Unb2MbBo X-Received: by 10.107.128.65 with SMTP id b62mr828641iod.280.1503456201427; Tue, 22 Aug 2017 19:43:21 -0700 (PDT) Received: from tdjones.localdomain (host-184-167-177-46.csp-wy.client.bresnan.net. [184.167.177.46]) by smtp.gmail.com with ESMTPSA id z140sm422072itb.30.2017.08.22.19.43.20 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 22 Aug 2017 19:43:20 -0700 (PDT) From: Tyler Jones To: ffmpeg-devel@ffmpeg.org Date: Tue, 22 Aug 2017 20:43:24 -0600 Message-Id: <20170823024324.14387-1-tdjones879@gmail.com> In-Reply-To: <20170822012307.6019-1-tdjones879@gmail.com> References: <20170822012307.6019-1-tdjones879@gmail.com> Subject: [FFmpeg-devel] [PATCH] avcodec/vorbisenc: Improve documentation X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches MIME-Version: 1.0 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Signed-off-by: Tyler Jones --- 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;