From patchwork Tue Feb 28 12:00:57 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anton Khirnov X-Patchwork-Id: 40540 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:d046:b0:cd:afd7:272c with SMTP id hv6csp1539781pzb; Tue, 28 Feb 2023 04:01:33 -0800 (PST) X-Google-Smtp-Source: AK7set85iXIN0EipsCQDBiuozJS5cRjbh64hcXFTWPLPSZszLJC1XHvdw/Vudsf1H/yeHqaEGKaa X-Received: by 2002:a05:6402:134b:b0:4ab:4c5e:b0ed with SMTP id y11-20020a056402134b00b004ab4c5eb0edmr3191819edw.21.1677585693514; Tue, 28 Feb 2023 04:01:33 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1677585693; cv=none; d=google.com; s=arc-20160816; b=sXqLcAFFqjez63atycBS5xdkyBh3eFRNsnfv6ppNhkTl16QteBG9hbftFd+3Ffdlg2 D28wmi4g+9SPDu/FV2lE3mLsffushTkcQqE8R3FoMouia5zoIVD8Z4EhoCGnoO2lGg6V 8gsSo7+4mqt2p7GE2ZiQx7YDzhQptPNra2EN1sr58LmIjuxmUV9wzen6UTmCFZWQRcxv aYNW7NqXrYTwH4Ocqx3/0PE/3EwOR1sdoaARDes5q4rcn72on89nfWvT4VWs4sK8LkVX IOSWgLvy/9ywVsADfaPn5Asynx1XzfQxehHnnOdZgEMRXVc4WLVtwrLJPQdX/IGrOSI6 CdRg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:reply-to:list-subscribe :list-help:list-post:list-archive:list-unsubscribe:list-id :precedence:subject:mime-version:message-id:date:to:from :delivered-to; bh=OiD+DIxLBXMZ2c+lxVCJqQXdGlmBU1rICSqxGT8yop8=; b=YVKprbhpXbawBGwEUgaPBKpDR8xW+4P+uk4LYmRCrT7fMeiSYi85wsf6HCYpFPfbQj piChTyK4xLPb22HyYhxbzZJD6FqGrZKJkkk6bfI4ZCy1yL34RGz/mDb3Y6f8QmYSfKLU kCMXEPijKmMhw2QXj3U/8B3w76u/WjY3plLGfGwTITqwxHKSLLgNtfuMzXVcaGfwiyh/ 2YMnpYm5x4q9NeVDtDcSDdhL7D+Ifi6EsOQ/OK9moxqoVqf2XosuKXKCJo7Tq9wH5gDi jC6l/4LPE+K48o8DQLRE2VCIV1t9uifma92umqd6yssnj99dyG9RnKSJYFITo2WuS4VO McYw== ARC-Authentication-Results: i=1; mx.google.com; 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 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id r17-20020a056402035100b004ad8fc759f9si1141361edw.17.2023.02.28.04.01.32; Tue, 28 Feb 2023 04:01:33 -0800 (PST) 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; 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 Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id C905D68AA08; Tue, 28 Feb 2023 14:01:28 +0200 (EET) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail0.khirnov.net (red.khirnov.net [176.97.15.12]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 88BB468A8F3 for ; Tue, 28 Feb 2023 14:01:22 +0200 (EET) Received: from localhost (localhost [IPv6:::1]) by mail0.khirnov.net (Postfix) with ESMTP id 9381D2406CA for ; Tue, 28 Feb 2023 13:01:21 +0100 (CET) Received: from mail0.khirnov.net ([IPv6:::1]) by localhost (mail0.khirnov.net [IPv6:::1]) (amavisd-new, port 10024) with ESMTP id VLCLsfHWgpWO for ; Tue, 28 Feb 2023 13:01:20 +0100 (CET) Received: from libav.khirnov.net (libav.khirnov.net [IPv6:2a00:c500:561:201::7]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "libav.khirnov.net", Issuer "smtp.khirnov.net SMTP CA" (verified OK)) by mail0.khirnov.net (Postfix) with ESMTPS id B69392404EC for ; Tue, 28 Feb 2023 13:01:20 +0100 (CET) Received: from libav.khirnov.net (libav.khirnov.net [IPv6:::1]) by libav.khirnov.net (Postfix) with ESMTP id 244253A02E1 for ; Tue, 28 Feb 2023 13:01:14 +0100 (CET) From: Anton Khirnov To: ffmpeg-devel@ffmpeg.org Date: Tue, 28 Feb 2023 13:00:57 +0100 Message-Id: <20230228120104.2347-1-anton@khirnov.net> X-Mailer: git-send-email 2.39.1 MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 1/8] lavu/frame: improve AVFrame.opaque[_ref] documentation X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 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" X-TUID: T+0gy7uimLxF Make them match each other, mention interaction with AV_CODEC_FLAG_COPY_OPAQUE. --- libavutil/frame.h | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/libavutil/frame.h b/libavutil/frame.h index 2580269549..4ed27cf43f 100644 --- a/libavutil/frame.h +++ b/libavutil/frame.h @@ -470,7 +470,18 @@ typedef struct AVFrame { int quality; /** - * for some private data of the user + * Frame owner's private data. + * + * This field may be set by the code that allocates/owns the frame data. + * It is then not touched by any library functions, except: + * - it is copied to other references by av_frame_copy_props() (and hence by + * av_frame_ref()); + * - it is set to NULL when the frame is cleared by av_frame_unref() + * - on the caller's explicit request. E.g. libavcodec encoders/decoders + * will copy this field to/from @ref AVPacket "AVPackets" if the caller sets + * @ref AV_CODEC_FLAG_COPY_OPAQUE. + * + * @see opaque_ref the reference-counted analogue */ void *opaque; @@ -678,13 +689,18 @@ typedef struct AVFrame { AVBufferRef *hw_frames_ctx; /** - * AVBufferRef for free use by the API user. FFmpeg will never check the - * contents of the buffer ref. FFmpeg calls av_buffer_unref() on it when - * the frame is unreferenced. av_frame_copy_props() calls create a new - * reference with av_buffer_ref() for the target frame's opaque_ref field. + * Frame owner's private data. + * + * This field may be set by the code that allocates/owns the frame data. + * It is then not touched by any library functions, except: + * - a new reference to the underlying buffer is propagated by + * av_frame_copy_props() (and hence by av_frame_ref()); + * - it is unreferenced in av_frame_unref(); + * - on the caller's explicit request. E.g. libavcodec encoders/decoders + * will propagate a new reference to/from @ref AVPacket "AVPackets" if the + * caller sets @ref AV_CODEC_FLAG_COPY_OPAQUE. * - * This is unrelated to the opaque field, although it serves a similar - * purpose. + * @see opaque the plain pointer analogue */ AVBufferRef *opaque_ref;