From patchwork Wed Feb 27 22:00:19 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mark Thompson X-Patchwork-Id: 12166 Return-Path: X-Original-To: patchwork@ffaux-bg.ffmpeg.org Delivered-To: patchwork@ffaux-bg.ffmpeg.org Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org [79.124.17.100]) by ffaux.localdomain (Postfix) with ESMTP id B6748449182 for ; Thu, 28 Feb 2019 00:08:45 +0200 (EET) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 8F66F689E48; Thu, 28 Feb 2019 00:08:45 +0200 (EET) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail-wr1-f67.google.com (mail-wr1-f67.google.com [209.85.221.67]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id BA1056803CB for ; Thu, 28 Feb 2019 00:08:38 +0200 (EET) Received: by mail-wr1-f67.google.com with SMTP id w6so16493715wrs.4 for ; Wed, 27 Feb 2019 14:08:38 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jkqxz-net.20150623.gappssmtp.com; s=20150623; h=from:to:subject:date:message-id:mime-version :content-transfer-encoding; bh=4E73xPqD6sX+K1phG4tB0PTs2rkuQa3jkQvPgoYfI6Y=; b=SC9+ffevFkQXOOCWHe33Az9bycr/RU2VomcTK5ADgx7fhbRq305YtKRO8Jfo58lfkV fg7u7QOMcm7eQyE+RrFo4B11W2GAiLo3I85ozFuevguZ5RKAyad1mXkJafEX7TkpFwLm BwnZAt7XscOK0lTPXpIbvMihcbii0jtnRr3N8vE85yamztVoPfNA6CNL9uFvGNt1e7sT L77cieI7IymMDnK6ltn6OJ1NRgdkPiIkkMM3E0B8Vzz5D9JqpR4lsUB7rweJOHmpGvsC bK8FsMU02/8QnVfaW8zFbfnpE3+ZV8HnXHSD5MNPug3q8xTJHgInkDvzd+kL5QWHz01f 7dJg== 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:mime-version :content-transfer-encoding; bh=4E73xPqD6sX+K1phG4tB0PTs2rkuQa3jkQvPgoYfI6Y=; b=khV11IawpZvXhfBrMNWgbwQDFe1wGyo7ZV7+wkSW/msOzx85ukwjN4uztRJ7Q8X/Pb LFpNLi7ZRoIU2ADfI5957wk0t/Ok12IN5rXYdgjrm6mcA4urGrcoWy+7RQesKI82ITzO hsLOqMtUpkzvqfPqgFgKQLgHXxDXwiQOQaXRKMRDB7DVfBu6Eihtu+TK8tA/LvPoHmp+ gHM38NTjCEA3ec8uXfZUpc3VGFb1F5li57GvH5cJX5ijnep2jNMhqTPaNBwRN12qxHGM ikJNJQ4jjzfIGWsbnFJQzj7aNrhNFBlKx1WF7bk1iWjoc/tsOqUg4CliUvEBhoI72/rQ ZNtw== X-Gm-Message-State: APjAAAUFPrYfyXG9qeHVx9UD0PAHi/xNYy5c7kYDBYE1szSpOF6ZNOhm qwyIBO4gYXgTUPRw975J4TEP3oXCYeSBWw== X-Google-Smtp-Source: APXvYqxy4bUwD6a0t003q9DvM3QFc1rP7zrUskNp9FQGpjClNEV2K9HGfqpZox8xVapt9fXINaPcFQ== X-Received: by 2002:adf:f388:: with SMTP id m8mr4128606wro.133.1551304831908; Wed, 27 Feb 2019 14:00:31 -0800 (PST) Received: from rywe.jkqxz.net (cpc91242-cmbg18-2-0-cust650.5-4.cable.virginm.net. [82.8.130.139]) by smtp.gmail.com with ESMTPSA id n14sm20586073wrx.24.2019.02.27.14.00.30 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 27 Feb 2019 14:00:30 -0800 (PST) From: Mark Thompson To: ffmpeg-devel@ffmpeg.org Date: Wed, 27 Feb 2019 22:00:19 +0000 Message-Id: <20190227220023.16040-1-sw@jkqxz.net> X-Mailer: git-send-email 2.19.2 MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 1/5] lavu/frame: Expand ROI 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 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Clarify and add examples for the behaviour of the quantisation offset, and define how multiple ranges should be handled. --- libavutil/frame.h | 62 +++++++++++++++++++++++++++++++++++------------ 1 file changed, 46 insertions(+), 16 deletions(-) diff --git a/libavutil/frame.h b/libavutil/frame.h index 8aa3e88367..2cd6c33a90 100644 --- a/libavutil/frame.h +++ b/libavutil/frame.h @@ -207,31 +207,61 @@ typedef struct AVFrameSideData { } AVFrameSideData; /** - * Structure to hold Region Of Interest. + * Structure describing a single Region Of Interest. * - * self_size specifies the size of this data structure. This value - * should be set to sizeof(AVRegionOfInterest). EINVAL is returned if self_size is zero. + * When multiple regions are defined in a single side-data block, they + * should be ordered from most to least important - some encoders are only + * capable of supporting a limited number of distinct regions, so will have + * to truncate the list. * - * Number of pixels to discard from the top/bottom/left/right border of - * the frame to obtain the region of interest of the frame. - * They are encoder dependent and will be extended internally - * if the codec requires an alignment. - * If the regions overlap, the last value in the list will be used. - * - * qoffset is quant offset, and base rule here: - * returns EINVAL if AVRational.den is zero. - * the value (num/den) range is [-1.0, 1.0], clamp to +-1.0 if out of range. - * 0 means no picture quality change, - * negative offset asks for better quality (and the best with value -1.0), - * positive offset asks for worse quality (and the worst with value 1.0). - * How to explain/implement the different quilaity requirement is encoder dependent. + * When overlapping regions are defined, the first region containing a given + * area of the frame applies. */ typedef struct AVRegionOfInterest { + /** + * Must be set to the size of this data structure (that is, + * sizeof(AVRegionOfInterest)). + */ uint32_t self_size; + /** + * Number of pixels to discard from the top/bottom/left/right border of + * the frame to obtain the region of interest. + * + * The constraints on a region are encoder dependent, so the region + * actually affected may be slightly larger for alignment or other + * reasons. + */ int top; int bottom; int left; int right; + /** + * Quantisation offset. + * + * Must be in the range -1 to +1. A value of zero indicates no quality + * change. A negative value asks for better quality (less quantisation), + * while a positive value asks for worse quality (greater quantisation). + * + * The range is calibrated so that the extreme values indicate the + * largest possible offset - if the rest of the frame is encoded with the + * worst possible quality, an offset of -1 indicates that this region + * should be encoded with the best possible quality anyway. Intermediate + * values are then interpolated in some codec-dependent way. + * + * For example, in 10-bit H.264 the quantisation parameter varies between + * -12 and 51. A typical qoffset value of -1/10 therefore indicates that + * this region should be encoded with a QP around one-tenth of the full + * range better than the rest of the frame. So, if most of the frame + * were to be encoded with a QP of around 30, this region would get a QP + * of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3). + * + * The extreme qoffset values (-1 and +1) therefore indicate that the + * region should be encoded with the best/worst possible quality + * regardless of the treatment of the rest of the frame - e.g. if qoffset + * is -1 in the 10-bit H.264 example, this region should use a QP of -12 + * independent of the rest of the frame (which could be good quality with + * QP -4, or terrible quality with QP 50, or any other value). + */ AVRational qoffset; } AVRegionOfInterest;