diff mbox series

[FFmpeg-devel,02/11] avformat/avformat: Clarify documentation of av_interleaved_write_frame()

Message ID AM7PR03MB6660248B76FF8B6418D9F2F98FCF9@AM7PR03MB6660.eurprd03.prod.outlook.com
State Accepted
Commit 259026b45758295d045e91b3a4456bd2c0249c47
Headers show
Series [FFmpeg-devel,01/11] avformat/mux: Sanitize packets without data and side-data
Related show

Checks

Context Check Description
andriy/make_x86 success Make finished
andriy/make_fate_x86 success Make fate finished
andriy/make_ppc success Make finished
andriy/make_fate_ppc success Make fate finished

Commit Message

Andreas Rheinhardt Sept. 3, 2021, 11:18 p.m. UTC
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 <andreas.rheinhardt@outlook.com>
---
 libavformat/avformat.h | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)
diff mbox series

Patch

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);
  *            <br>
  *            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.
  *            <br>
  *            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
  */