From patchwork Tue Mar 31 12:37:43 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andreas Rheinhardt X-Patchwork-Id: 18537 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 8E8CE44B82D for ; Tue, 31 Mar 2020 15:45:37 +0300 (EEST) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 669B168B16A; Tue, 31 Mar 2020 15:45:37 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail-wm1-f65.google.com (mail-wm1-f65.google.com [209.85.128.65]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 84E4668B133 for ; Tue, 31 Mar 2020 15:45:30 +0300 (EEST) Received: by mail-wm1-f65.google.com with SMTP id j19so2447731wmi.2 for ; Tue, 31 Mar 2020 05:45:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=kP6r5X602DKIG6fkyARYJGooJVR0mC5ZIOKyGG23NGM=; b=rYgZgeNd/sBUy9Mqq9+4jrCJ/B2hcfhB8TidQ2Ogtp31qkRg6XmiJCb9wjeK3rSeY2 zQJPvkt9OiI987DXYo8vr2EsOnyxQLAhJ73khzV1vl9KdOfykffd8/3pnqpveLmtLlfW hx/cZjWhHD2LscUB2J5DDwkiM/pU/0oj8565Ur3xzq49wMmRa81E2G6HSXZzoUqzSQrV Wjh9spL0Nt4/kmkGcv58EumMyRMW1CeV1srw7nHfwCm2iwUS5zMyQ87YIRUtRIFqGdC7 dwZNAsYnqUPujIILYjLRQAnFA43HTr0Og9yBn3GCM2iCq6DmNkUoOnkw18vaqtucKoBP aNPg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=kP6r5X602DKIG6fkyARYJGooJVR0mC5ZIOKyGG23NGM=; b=Bl/RDoDeOaqBrTkTrbo+RfAqjFm6UXaVyhWxhBpfl3+C8eWOzslMj/cqYU8mW0bn6f QN8fm71NVsLMJZNGDZlUTNohpiGV0pFdCM54OL+bkJUH2N9fazXfuwEreVT3aLccjP0f Rr5NqrY1AKoKExAZmybMteEi8eBL+sTF0pvYXJcrnRJPJP9I8oWkF+UrFXMUMRqk/S8l mwf+yKNeFVH24Hu2TbalrXRfpUl3rxH+rmH1br+SitxtOGbWoKtgD70GAWIpeMuDJEmA Z7F4u639wejzK3JCxOvBwpVEHBEZrH+9uM0mMg4cyr0D/KwSqXi72AVr6Zo4zE2IF+cd 0MFA== X-Gm-Message-State: ANhLgQ2ikhsO36OTC9blNV6qLcWftRhdLOiIJPxzWC+qS0b+jLSfBU+o UAGqNDxz+3Aji4ZBW7WWZ2uwGv6/ X-Google-Smtp-Source: ADFU+vsJWGkCKrGl2aLR7pFEnUhAeYlKU3DiMaVXJS4SdGyTBI7ZgjYcQCl44vZGAI1IwJlPw2SCDQ== X-Received: by 2002:a1c:7719:: with SMTP id t25mr3393985wmi.144.1585658315491; Tue, 31 Mar 2020 05:38:35 -0700 (PDT) Received: from sblaptop.fritz.box (ipbcc1ab57.dynamic.kabel-deutschland.de. [188.193.171.87]) by smtp.gmail.com with ESMTPSA id p13sm26301532wru.3.2020.03.31.05.38.34 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 31 Mar 2020 05:38:34 -0700 (PDT) From: Andreas Rheinhardt To: ffmpeg-devel@ffmpeg.org Date: Tue, 31 Mar 2020 14:37:43 +0200 Message-Id: <20200331123745.6461-9-andreas.rheinhardt@gmail.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200331123745.6461-1-andreas.rheinhardt@gmail.com> References: <20200331123745.6461-1-andreas.rheinhardt@gmail.com> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 08/10] avformat/avformat: Clarify documentation of av_interleaved_write_frame() 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 Cc: Andreas Rheinhardt Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" 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 --- doc/APIchanges | 4 ++++ libavformat/avformat.h | 15 +++++++-------- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/doc/APIchanges b/doc/APIchanges index f1d7eac2ee..31dc6c6c16 100644 --- a/doc/APIchanges +++ b/doc/APIchanges @@ -15,6 +15,10 @@ libavutil: 2017-10-21 API changes, most recent first: +2020-03-31 - xxxxxxxxxx - lavf 58.42.100 - avformat.h + av_interleaved_write_frame() now guarantees to always return + blank packets, even on failure. + 2020-03-29 - xxxxxxxxxx - lavf 58.42.100 - avformat.h av_read_frame() now guarantees to handle uninitialized input packets and to return refcounted packets on success. diff --git a/libavformat/avformat.h b/libavformat/avformat.h index 8f7466931a..9669ded1cd 100644 --- a/libavformat/avformat.h +++ b/libavformat/avformat.h @@ -2596,7 +2596,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. * @@ -2609,10 +2609,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. @@ -2628,10 +2628,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 */