RepoMirrors
/
ffmpeg
mirror of https://git.ffmpeg.org/ffmpeg.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

avformat/avformat: Update av_read_frame() documentation 

This commit updates the documentation of av_read_frame() to match its
actual behaviour in several ways:

1. On success, av_read_frame() always returns refcounted packets.
2. It can handle uninitialized packets.
3. On error, it always returns blank packets.

This will allow callers to not initialize or unref unnecessarily.

Signed-off-by: Andreas Rheinhardt <andreas.rheinhardt@gmail.com>
This commit is contained in:
Andreas Rheinhardt 2019-12-01 08:45:05 +01:00
parent 3c138e5ceb
commit 4cb0dda555
2 changed files with 18 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/APIchanges
View File

@ -15,6 +15,10 @@ libavutil: 2017-10-21
API changes, most recent first:
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.
2020-03-27 - xxxxxxxxxx - lavc 58.77.100 - avcodec.h
av_packet_ref() now guarantees to return the destination packet
in a blank state on error.

30
libavformat/avformat.h
View File

@ -170,14 +170,9 @@
* information will be in AVStream.time_base units, i.e. it has to be
* multiplied by the timebase to convert them to seconds.
*
* If AVPacket.buf is set on the returned packet, then the packet is
* allocated dynamically and the user may keep it indefinitely.
* Otherwise, if AVPacket.buf is NULL, the packet data is backed by a
* static storage somewhere inside the demuxer and the packet is only valid
* until the next av_read_frame() call or closing the file. If the caller
* requires a longer lifetime, av_packet_make_refcounted() will ensure that
* the data is reference counted, copying the data if necessary.
* In both cases, the packet must be freed with av_packet_unref() when it is no
* A packet returned by av_read_frame() is always reference-counted,
* i.e. AVPacket.buf is set and the user may keep it indefinitely.
* The packet must be freed with av_packet_unref() when it is no
* longer needed.
*
* @section lavf_decoding_seek Seeking
@ -2396,13 +2391,12 @@ int av_find_best_stream(AVFormatContext *ic,
* omit invalid data between valid frames so as to give the decoder the maximum
* information possible for decoding.
*
* If pkt->buf is NULL, then the packet is valid until the next
* av_read_frame() or until avformat_close_input(). Otherwise the packet
* is valid indefinitely. In both cases the packet must be freed with
* av_packet_unref when it is no longer needed. For video, the packet contains
* exactly one frame. For audio, it contains an integer number of frames if each
* frame has a known fixed size (e.g. PCM or ADPCM data). If the audio frames
* have a variable size (e.g. MPEG audio), then it contains one frame.
* On success, the returned packet is reference-counted (pkt->buf is set) and
* valid indefinitely. The packet must be freed with av_packet_unref() when
* it is no longer needed. For video, the packet contains exactly one frame.
* For audio, it contains an integer number of frames if each frame has
* a known fixed size (e.g. PCM or ADPCM data). If the audio frames have
* a variable size (e.g. MPEG audio), then it contains one frame.
*
* pkt->pts, pkt->dts and pkt->duration are always set to correct
* values in AVStream.time_base units (and guessed if the format cannot
@ -2410,7 +2404,11 @@ int av_find_best_stream(AVFormatContext *ic,
* has B-frames, so it is better to rely on pkt->dts if you do not
* decompress the payload.
*
* @return 0 if OK, < 0 on error or end of file
* @return 0 if OK, < 0 on error or end of file. On error, pkt will be blank
* (as if it came from av_packet_alloc()).
*
* @note pkt will be initialized, so it may be uninitialized, but it must not
* contain data that needs to be freed.
*/
int av_read_frame(AVFormatContext *s, AVPacket *pkt);