diff options
author | Anton Khirnov <anton@khirnov.net> | 2013-10-08 10:53:50 +0400 |
---|---|---|
committer | Anton Khirnov <anton@khirnov.net> | 2013-10-12 17:10:21 +0400 |
commit | 16ea20c827ef2ffaf77d5e05d5cf9983689f7b2b (patch) | |
tree | c9b199ddb593a111c87cb0671438eeb41c007fdb /libavcodec | |
parent | 66d3f5fd5ca4cb3d09b52ad1041cd4359325a21a (diff) |
lavc doxy: extend/clarify avcodec_decode_audio4() doxy
Elaborate on flushing the decoder.
Diffstat (limited to 'libavcodec')
-rw-r--r-- | libavcodec/avcodec.h | 24 |
1 files changed, 18 insertions, 6 deletions
diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h index bb36acd7fb..84bfccb5ac 100644 --- a/libavcodec/avcodec.h +++ b/libavcodec/avcodec.h @@ -3368,11 +3368,20 @@ void avcodec_align_dimensions2(AVCodecContext *s, int *width, int *height, * Decode the audio frame of size avpkt->size from avpkt->data into frame. * * Some decoders may support multiple frames in a single AVPacket. Such - * decoders would then just decode the first frame. In this case, - * avcodec_decode_audio4 has to be called again with an AVPacket containing - * the remaining data in order to decode the second frame, etc... - * Even if no frames are returned, the packet needs to be fed to the decoder - * with remaining data until it is completely consumed or an error occurs. + * decoders would then just decode the first frame and the return value would be + * less than the packet size. In this case, avcodec_decode_audio4 has to be + * called again with an AVPacket containing the remaining data in order to + * decode the second frame, etc... Even if no frames are returned, the packet + * needs to be fed to the decoder with remaining data until it is completely + * consumed or an error occurs. + * + * Some decoders (those marked with CODEC_CAP_DELAY) have a delay between input + * and output. This means that for some packets they will not immediately + * produce decoded output and need to be flushed at the end of decoding to get + * all the decoded data. Flushing is done by calling this function with packets + * with avpkt->data set to NULL and avpkt->size set to 0 until it stops + * returning samples. It is safe to flush even those decoders that are not + * marked with CODEC_CAP_DELAY, then no samples will be returned. * * @warning The input buffer, avpkt->data must be FF_INPUT_BUFFER_PADDING_SIZE * larger than the actual read bytes because some optimized bitstream @@ -3392,7 +3401,10 @@ void avcodec_align_dimensions2(AVCodecContext *s, int *width, int *height, * next call to this function or until closing or flushing the * decoder. The caller may not write to it. * @param[out] got_frame_ptr Zero if no frame could be decoded, otherwise it is - * non-zero. + * non-zero. Note that this field being set to zero + * does not mean that an error has occurred. For + * decoders with CODEC_CAP_DELAY set, no given decode + * call is guaranteed to produce a frame. * @param[in] avpkt The input AVPacket containing the input buffer. * At least avpkt->data and avpkt->size should be set. Some * decoders might also require additional fields to be set. |