From 717a4509930854081deea54a3bfcdb547161fecf Mon Sep 17 00:00:00 2001 From: Anton Khirnov Date: Wed, 31 Oct 2012 19:59:53 +0100 Subject: [PATCH] lavf: clarify the lifetime of demuxed packets. --- libavformat/avformat.h | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/libavformat/avformat.h b/libavformat/avformat.h index 8af007e640..0961308028 100644 --- a/libavformat/avformat.h +++ b/libavformat/avformat.h @@ -158,9 +158,15 @@ * information will be in AVStream.time_base units, i.e. it has to be * multiplied by the timebase to convert them to seconds. * - * The packet data belongs to the demuxer and is invalid after the next call to - * av_read_frame(). The user must free the packet with av_free_packet() before - * calling av_read_frame() again or closing the file. + * If AVPacket.destruct is set on the returned packet, then the packet is + * allocated dynamically and the user may keep it indefinitely. + * Otherwise, if AVPacket.destruct 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_dup_packet() will make an av_malloc()ed copy + * of it. + * In both cases, the packet must be freed with av_free_packet() when it is no + * longer needed. * * @section lavf_decoding_seek Seeking * @} @@ -1307,13 +1313,13 @@ int av_read_packet(AVFormatContext *s, AVPacket *pkt); * omit invalid data between valid frames so as to give the decoder the maximum * information possible for decoding. * - * The returned packet is valid - * until the next av_read_frame() or until av_close_input_file() and - * must be freed with av_free_packet. 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. + * If pkt->destruct is NULL, then the packet is valid until the next + * av_read_frame() or until av_close_input_file(). Otherwise the packet is valid + * indefinitely. In both cases the packet must be freed with + * av_free_packet 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