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 | 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 | 22 | 2020-03-27 - xxxxxxxxxx - lavc 58.77.100 - avcodec.h |
| 19 | 23 | av_packet_ref() now guarantees to return the destination packet |
| 20 | 24 | in a blank state on error. |
| @@ -170,14 +170,9 @@ · 169 unmodified lines | ||
| 170 | 170 | * information will be in AVStream.time_base units, i.e. it has to be |
| 171 | 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 | |
| 174 | − * allocated dynamically and the user may keep it indefinitely. | |
| 175 | − * Otherwise, if AVPacket.buf is NULL, the packet data is backed by a | |
| 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 | |
| 173 | + * A packet returned by av_read_frame() is always reference-counted, | |
| 174 | + * i.e. AVPacket.buf is set and the user may keep it indefinitely. | |
| 175 | + * The packet must be freed with av_packet_unref() when it is no | |
| 181 | 176 | * longer needed. |
| 182 | 177 | * |
| 183 | 178 | * @section lavf_decoding_seek Seeking |
| @@ -2396,13 +2391,12 @@ int av_find_best_stream(AVFormatContext *ic, · 2212 unmodified lines | ||
| 2396 | 2391 | * omit invalid data between valid frames so as to give the decoder the maximum |
| 2397 | 2392 | * information possible for decoding. |
| 2398 | 2393 | * |
| 2399 | − * If pkt->buf is NULL, then the packet is valid until the next | |
| 2400 | − * av_read_frame() or until avformat_close_input(). Otherwise the packet | |
| 2401 | − * is valid indefinitely. In both cases the packet must be freed with | |
| 2402 | − * av_packet_unref when it is no longer needed. For video, the packet contains | |
| 2403 | − * exactly one frame. For audio, it contains an integer number of frames if each | |
| 2404 | − * frame has a known fixed size (e.g. PCM or ADPCM data). If the audio frames | |
| 2405 | − * have a variable size (e.g. MPEG audio), then it contains one frame. | |
| 2394 | + * On success, the returned packet is reference-counted (pkt->buf is set) and | |
| 2395 | + * valid indefinitely. The packet must be freed with av_packet_unref() when | |
| 2396 | + * it is no longer needed. For video, the packet contains exactly one frame. | |
| 2397 | + * For audio, it contains an integer number of frames if each frame has | |
| 2398 | + * a known fixed size (e.g. PCM or ADPCM data). If the audio frames have | |
| 2399 | + * a variable size (e.g. MPEG audio), then it contains one frame. | |
| 2406 | 2400 | * |
| 2407 | 2401 | * pkt->pts, pkt->dts and pkt->duration are always set to correct |
| 2408 | 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 | 2404 | * has B-frames, so it is better to rely on pkt->dts if you do not |
| 2411 | 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 | 2413 | int av_read_frame(AVFormatContext *s, AVPacket *pkt); |
| 2416 | 2414 | |