From patchwork Fri Sep 3 23:18:04 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andreas Rheinhardt X-Patchwork-Id: 29995 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6602:2a4a:0:0:0:0 with SMTP id k10csp1731356iov; Fri, 3 Sep 2021 16:18:32 -0700 (PDT) X-Google-Smtp-Source: ABdhPJzn2yuTvh4DGFZ6c/k+VIRGIYuFBi39eiduxpgZwevo4TJD9Z4F+3gDj526+p3cO1x1H8Xw X-Received: by 2002:a17:906:d045:: with SMTP id bo5mr1312891ejb.461.1630711112545; Fri, 03 Sep 2021 16:18:32 -0700 (PDT) Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id ec52si797877edb.515.2021.09.03.16.18.32; Fri, 03 Sep 2021 16:18:32 -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=@outlook.com header.s=selector1 header.b=UtOWEaQX; arc=fail (body hash mismatch); 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=QUARANTINE dis=NONE) header.from=outlook.com Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 64B2D6804B8; Sat, 4 Sep 2021 02:18:29 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from EUR05-VI1-obe.outbound.protection.outlook.com (mail-vi1eur05olkn2036.outbound.protection.outlook.com [40.92.90.36]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id DB45B6804B8 for ; Sat, 4 Sep 2021 02:18:22 +0300 (EEST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=Zsp8jvRMXESyVKc9r+orU2+zmwz9K9/L9veQydxUeb5NWZsOc1MJ91i0RNw3EiP2GkR0UYDT89s6ZkhI8rgrnYVJotoPa3+2xrDE4xx9qZZl5QaIqpzI5/CVUpchguHulgP+YUpxyg5xcgK7sLFrjqLQOIsd+UjEIvza1eDjc09k2LbKb8l2xJvm9oY4Dy7PuKAuxOHl4HHWpFYzcTLrzXYRJbKxvZzXi7AcYshSdTGvDgCDmaPYDOKwUsipapy4RLnHPyfMOlVC+g/hczNmgDZZIsTVA9+bNBm1VfmaplHDon4Nj9LHjS5Q2kZxvyQbX/ZX8tyWcmpl9PCB+V7DPg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=PTZ5MSpOK0HsUHp6TzgEdf/FqAcEQn7OV4dZbwghs0s=; b=kJP6Dapwux7bJVpTMeIK2PlyHJaXyCyhfRbFm7UjaOAnc0IirmBQoWd4F3Znz67hT9jZ4c+HYulph60Tr0N2d6CMbkXhKZNc4X615+tT3iiTkLkBbuIkE3fWhUjblJ3BE0lozoWV+ojIZLIPEFpa9jQDaM+d2cvhF7WhNpfRi2PfBeU8AAmwiXjvQ8RXNSF8ohWONcff07v+5sC3psQnFwvAKrbZQMkdGEQxbJDBIYkvNmYwVcUR6DPVPT5hoTlhXfEKKDV0vEIALsAmKunTnnG4gfKRAv4r0NEc8rsZMVJI3qfg/fwbg5IDTva4GWIBnFdIOaVUMenN9c6MPYOvyg== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=none; dmarc=none; dkim=none; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=outlook.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=PTZ5MSpOK0HsUHp6TzgEdf/FqAcEQn7OV4dZbwghs0s=; b=UtOWEaQXt44Zj27e500w+N44jdMUHXuI2v6jXT7+G13UhV/qvRKFWibNipFDmnMl5klN4fZ4YrRrRoAJFLfs1S79nJ6Np8JKAPBmaXw9vtoCnZNhp8zpHKO8LMyxdfJSYk9HZVisqu2y6XqSEBdi0F3FYWB8zT7OV/g9KVnDdYWTZGmv9nYhFrYA0d1fvnU6By+OVEAt7HqaeN+r3OCsI3Q1Y4i63PXAkLeczj8ND/uo4+/V+od35AN1fz4Fu5kYDqUnbBalftAqlHnzZKxChljObZadeQJW6r6Pl1sICxy9x0zectts+PlMeOhBT8GIPMdFIcYjRhxOEmM1yjhY9A== Received: from AM7PR03MB6660.eurprd03.prod.outlook.com (2603:10a6:20b:1c1::22) by AM6PR03MB3768.eurprd03.prod.outlook.com (2603:10a6:209:37::32) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4457.23; Fri, 3 Sep 2021 23:18:21 +0000 Received: from AM7PR03MB6660.eurprd03.prod.outlook.com ([fe80::787b:2156:ca99:fe00]) by AM7PR03MB6660.eurprd03.prod.outlook.com ([fe80::787b:2156:ca99:fe00%3]) with mapi id 15.20.4478.022; Fri, 3 Sep 2021 23:18:21 +0000 From: Andreas Rheinhardt To: ffmpeg-devel@ffmpeg.org Date: Sat, 4 Sep 2021 01:18:04 +0200 Message-ID: X-Mailer: git-send-email 2.30.2 In-Reply-To: References: X-TMN: [cefIOHAIZ14DGc47tGbrzOVE959kQ1fx] X-ClientProxiedBy: AM0P190CA0016.EURP190.PROD.OUTLOOK.COM (2603:10a6:208:190::26) To AM7PR03MB6660.eurprd03.prod.outlook.com (2603:10a6:20b:1c1::22) X-Microsoft-Original-Message-ID: <20210903231813.3346446-1-andreas.rheinhardt@outlook.com> MIME-Version: 1.0 X-MS-Exchange-MessageSentRepresentingType: 1 Received: from sblaptop.fritz.box (188.192.142.38) by AM0P190CA0016.EURP190.PROD.OUTLOOK.COM (2603:10a6:208:190::26) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4478.19 via Frontend Transport; Fri, 3 Sep 2021 23:18:20 +0000 X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: fbd7aee4-ba87-497c-8d26-08d96f311ee0 X-MS-Exchange-SLBlob-MailProps: f36zkjAOy3XsX14DgrS8o/592aMI43cZcGhDfgzByoP8Fu4cr+eAcTG1M++MfwJ1tvpFjBbF6V9oYVq1jJuIhWZpSUMy8uRX/UQKNNOlv7wuqFEJWcPkaFaVJcykoT5ri8shmG2s8MizSqQNqzgu09VO0JlsemfBp1olvvluB7GAlFX5/+KVlGhlqD7CyU40xb0Amfzmmmehwsro8Wx4QLTVhuqeD5/ijENPoqThDbaqDEdfyWWG4Fq18q2qSpx1fav5azoBytD9IvR4UTUAqrWW+w6/KQ32FdBi3QHZQMjbjxPsOW550iOK3f5OFts1VPbhVF3w1iL24js3n03gj8D5EfxiOBNbpEsZzzfExwrHcFmhdwWIg7TFK7/SUVQSY1W4UxwR+Pv/8z2FT8fF+ydeDN27aJtQxZVpOOD0CkMzZ3WAdxlhnjSqD3hFDPTvc+CK62EgM6H8boKR9y1+1dTw0th9wF8lFcN1jxIvLv9YlAKYJ9TPVQiasGuCI5kb7C5v3AQsfcGfNJYvgDGmGP36jc1NyyK5lLsW60h1r+zjJManWQICY3CnARyYShIK7igmtzqhyG/Yeu/ZeIaCMTv8V+Ms2mMtAjj6bvP/JvPycSBHO6LHstkwUPPMeBjsWKz8LCN0LjxH5zn/VRoUuc0QKdRwsqd8FKspd+esfMFbxElyiVyOlaHjMENeKXor5m182PhmXUz224U8UQdFvUqr5xHVQNbbiyhMLTyCTlE= X-MS-TrafficTypeDiagnostic: AM6PR03MB3768: X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: g2mDycn3SJerf+8OOpwsMOgNYmWLmTWhryshp/m/S3P8eT9tTpPb8jjPrCvUruFKb5UqQFfnnhjcb/W+h4mvBMgKEAzIa5twCg5GtHt0Lc7Hh9vEkDhmMqr+M3o2pZcY5c47pivO9//pR6Ub3qNqEULI9FL7cT0QI1xOpFJ5LJaRornMz/fP+/qOSNTHz0nHLL4VbEa6jOWc81EyB96x8sIfTIKtQt/1sj8+DmcVkyVfbifXYNYZWXHauGzyaC+hDklpPPnf73jfuWVkVyWFjCn7FFUmSbZ0GeSMQRKQN8AKEbuUZIvb67eFQORiTHGeuBtHCSmTyGkefI6zitzhJqxjZJQNXUaOr0qlVevFplKXrB3zyyBUqk04v2pX4r3zoHxbhO3aChD0cKXW4OYBuvoQH9hV5p0SimWkr3ZUEPARxR7bHav820JYfM+Uw56+ X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: jzd3pykKnIunS6rAdnT3CgZeOZqJfpp373Ezwx0iLXMN3We0JNovDg6RFjl4a1Zcn82tFY15dkzzOTpD41IFadHvjmxZjVY7z11gCGuHsLzyszRnGFc4IVD6IWc3mvh84smZpnuFJrQlJAyakckIew== X-OriginatorOrg: outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: fbd7aee4-ba87-497c-8d26-08d96f311ee0 X-MS-Exchange-CrossTenant-AuthSource: AM7PR03MB6660.eurprd03.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 03 Sep 2021 23:18:21.3830 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 84df9e7f-e9f6-40af-b435-aaaaaaaaaaaa X-MS-Exchange-CrossTenant-RMS-PersistedConsumerOrg: 00000000-0000-0000-0000-000000000000 X-MS-Exchange-Transport-CrossTenantHeadersStamped: AM6PR03MB3768 Subject: [FFmpeg-devel] [PATCH 02/11] avformat/avformat: Clarify documentation of av_interleaved_write_frame() 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 Cc: Andreas Rheinhardt Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: NLE9aJAnXiep The earlier documentation claimed that av_interleaved_write_frame() always orders by dts, which is not necessarily true when using muxers with custom interleavement functions or the audio_preload option. Furthermore, the documentation stated that libavformat takes ownership of the reference of the provided packet (if it is refcounted) and that the caller may not access the data through this reference after the function returns. This suggests that the returned packet is not blank, but instead still contains some set, but invalid fields, which implies that it would be dangerous to unreference this packet again. But this is not true: av_interleaved_write_frame()'s actual behaviour is to always output blank packet (even on error). This commit documents this fact so that callers know that they can directly reuse this packet. Signed-off-by: Andreas Rheinhardt --- libavformat/avformat.h | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/libavformat/avformat.h b/libavformat/avformat.h index 81d2ac38d0..9b560c15be 100644 --- a/libavformat/avformat.h +++ b/libavformat/avformat.h @@ -2264,7 +2264,7 @@ int av_write_frame(AVFormatContext *s, AVPacket *pkt); * Write a packet to an output media file ensuring correct interleaving. * * This function will buffer the packets internally as needed to make sure the - * packets in the output file are properly interleaved in the order of + * packets in the output file are properly interleaved, usually ordered by * increasing dts. Callers doing their own interleaving should call * av_write_frame() instead of this function. * @@ -2277,10 +2277,10 @@ int av_write_frame(AVFormatContext *s, AVPacket *pkt); *
* If the packet is reference-counted, this function will take * ownership of this reference and unreference it later when it sees - * fit. - * The caller must not access the data through this reference after - * this function returns. If the packet is not reference-counted, - * libavformat will make a copy. + * fit. If the packet is not reference-counted, libavformat will + * make a copy. + * The returned packet will be blank (as if returned from + * av_packet_alloc()), even on error. *
* This parameter can be NULL (at any time, not just at the end), to * flush the interleaving queues. @@ -2296,10 +2296,9 @@ int av_write_frame(AVFormatContext *s, AVPacket *pkt); * The dts for subsequent packets in one stream must be strictly * increasing (unless the output format is flagged with the * AVFMT_TS_NONSTRICT, then they merely have to be nondecreasing). - * @ref AVPacket.duration "duration") should also be set if known. + * @ref AVPacket.duration "duration" should also be set if known. * - * @return 0 on success, a negative AVERROR on error. Libavformat will always - * take care of freeing the packet, even if this function fails. + * @return 0 on success, a negative AVERROR on error. * * @see av_write_frame(), AVFormatContext.max_interleave_delta */