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.
Unified · Split
| @@ -15,6 +15,10 @@ libavutil: 2017-10-21 · 14 unmodified lines | |||
| 15 | 15 | ||
| 16 | API changes, most recent first: | 16 | API changes, most recent first: |
| 17 | 17 | ||
| 18 | 2020-03-29 - xxxxxxxxxx - lavf 58.42.100 - avformat.h | ||
| 19 | av_read_frame() now guarantees to handle uninitialized input packets | ||
| 20 | and to return refcounted packets on success. | ||
| 21 | |||
| 18 | 2020-03-27 - xxxxxxxxxx - lavc 58.77.100 - avcodec.h | 22 | 2020-03-27 - xxxxxxxxxx - lavc 58.77.100 - avcodec.h |
| 19 | av_packet_ref() now guarantees to return the destination packet | 23 | av_packet_ref() now guarantees to return the destination packet |
| 20 | in a blank state on error. | 24 | in a blank state on error. |
| @@ -170,14 +170,9 @@ · 169 unmodified lines | |||
| 170 | * information will be in AVStream.time_base units, i.e. it has to be | 170 | * information will be in AVStream.time_base units, i.e. it has to be |
| 171 | * multiplied by the timebase to convert them to seconds. | 171 | * multiplied by the timebase to convert them to seconds. |
| 172 | * | 172 | * |
| 173 | * If AVPacket.buf is set on the returned packet, then the packet is | 173 | * A packet returned by av_read_frame() is always reference-counted, |
| 174 | * allocated dynamically and the user may keep it indefinitely. | 174 | * i.e. AVPacket.buf is set and the user may keep it indefinitely. |
| 175 | * Otherwise, if AVPacket.buf is NULL, the packet data is backed by a | 175 | * The packet must be freed with av_packet_unref() when it is no |
| 176 | * static storage somewhere inside the demuxer and the packet is only valid | ||
| 177 | * until the next av_read_frame() call or closing the file. If the caller | ||
| 178 | * requires a longer lifetime, av_packet_make_refcounted() will ensure that | ||
| 179 | * the data is reference counted, copying the data if necessary. | ||
| 180 | * In both cases, the packet must be freed with av_packet_unref() when it is no | ||
| 181 | * longer needed. | 176 | * longer needed. |
| 182 | * | 177 | * |
| 183 | * @section lavf_decoding_seek Seeking | 178 | * @section lavf_decoding_seek Seeking |
| @@ -2396,13 +2391,12 @@ int av_find_best_stream(AVFormatContext *ic, · 2212 unmodified lines | |||
| 2396 | * omit invalid data between valid frames so as to give the decoder the maximum | 2391 | * omit invalid data between valid frames so as to give the decoder the maximum |
| 2397 | * information possible for decoding. | 2392 | * information possible for decoding. |
| 2398 | * | 2393 | * |
| 2399 | * If pkt->buf is NULL, then the packet is valid until the next | 2394 | * On success, the returned packet is reference-counted (pkt->buf is set) and |
| 2400 | * av_read_frame() or until avformat_close_input(). Otherwise the packet | 2395 | * valid indefinitely. The packet must be freed with av_packet_unref() when |
| 2401 | * is valid indefinitely. In both cases the packet must be freed with | 2396 | * it is no longer needed. For video, the packet contains exactly one frame. |
| 2402 | * av_packet_unref when it is no longer needed. For video, the packet contains | 2397 | * For audio, it contains an integer number of frames if each frame has |
| 2403 | * exactly one frame. For audio, it contains an integer number of frames if each | 2398 | * a known fixed size (e.g. PCM or ADPCM data). If the audio frames have |
| 2404 | * frame has a known fixed size (e.g. PCM or ADPCM data). If the audio frames | 2399 | * a variable size (e.g. MPEG audio), then it contains one frame. |
| 2405 | * have a variable size (e.g. MPEG audio), then it contains one frame. | ||
| 2406 | * | 2400 | * |
| 2407 | * pkt->pts, pkt->dts and pkt->duration are always set to correct | 2401 | * pkt->pts, pkt->dts and pkt->duration are always set to correct |
| 2408 | * values in AVStream.time_base units (and guessed if the format cannot | 2402 | * values in AVStream.time_base units (and guessed if the format cannot |
| @@ -2410,7 +2404,11 @@ int av_find_best_stream(AVFormatContext *ic, · 1 unmodified line | |||
| 2410 | * has B-frames, so it is better to rely on pkt->dts if you do not | 2404 | * has B-frames, so it is better to rely on pkt->dts if you do not |
| 2411 | * decompress the payload. | 2405 | * decompress the payload. |
| 2412 | * | 2406 | * |
| 2413 | * @return 0 if OK, < 0 on error or end of file | 2407 | * @return 0 if OK, < 0 on error or end of file. On error, pkt will be blank |
| 2408 | * (as if it came from av_packet_alloc()). | ||
| 2409 | * | ||
| 2410 | * @note pkt will be initialized, so it may be uninitialized, but it must not | ||
| 2411 | * contain data that needs to be freed. | ||
| 2414 | */ | 2412 | */ |
| 2415 | int av_read_frame(AVFormatContext *s, AVPacket *pkt); | 2413 | int av_read_frame(AVFormatContext *s, AVPacket *pkt); |
| 2416 | 2414 | ||