Small correction in the ffmpeg 2.5 headers (almost only comments)

git-svn-id: svn://svn.code.sf.net/p/ultrastardx/svn/trunk@3115 b956fd51-792f-4845-bead-9b4dfca2ff2c

2 files changed, 33 insertions, 23 deletions

diff --git a/src/lib/ffmpeg-2.5/avcodec.pas b/src/lib/ffmpeg-2.5/avcodec.pas
index d52bd8f0..8425fb91 100644
--- a/src/lib/ffmpeg-2.5/avcodec.pas
+++ b/src/lib/ffmpeg-2.5/avcodec.pas
@@ -4756,19 +4756,25 @@ function avcodec_decode_audio3(avctx: PAVCodecContext; samples: PSmallint;
  * 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
  *          readers read 32 or 64 bits at once and could read over the end.
  *
- * @note You might have to align the input buffer. The alignment requirements
- *       depend on the CPU and the decoder.
- *
  * @param      avctx the codec context
  * @param[out] frame The AVFrame in which to store decoded audio samples.
  *                   The decoder will allocate a buffer for the decoded frame by
@@ -4780,10 +4786,13 @@ function avcodec_decode_audio3(avctx: PAVCodecContext; samples: PSmallint;
  *                   to the frame if av_frame_is_writable() returns 1.
  *                   When AVCodecContext.refcounted_frames is set to 0, the returned
  *                   reference belongs to the decoder and is valid only until the
- *                   next call to this function or until closing the decoder.
- *                   The caller may not write to it.
+ *                   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.
@@ -4807,13 +4816,6 @@ function avcodec_decode_audio4(avctx: PAVCodecContext; frame: PAVFrame;
  * @warning The end of the input buffer buf should be set to 0 to ensure that
  * no overreading happens for damaged MPEG streams.
  *
- * @note You might have to align the input buffer avpkt->data.
- * The alignment requirements depend on the CPU: on some CPUs it isn't
- * necessary at all, on others it won't work at all if not aligned and on others
- * it will work but it will have an impact on performance.
- *
- * In practice, avpkt->data should have 4 byte alignment at minimum.
- *
  * @note Codecs which have the CODEC_CAP_DELAY capability set have a delay
  * between input and output, these need to be fed with avpkt->data=NULL,
  * avpkt->size=0 at the end to return the remaining frames.
@@ -4830,10 +4832,10 @@ function avcodec_decode_audio4(avctx: PAVCodecContext; frame: PAVFrame;
  *             to the frame if av_frame_is_writable() returns 1.
  *             When AVCodecContext.refcounted_frames is set to 0, the returned
  *             reference belongs to the decoder and is valid only until the
- *             next call to this function or until closing the decoder. The
- *             caller may not write to it.
+ *             next call to this function or until closing or flushing the
+ *             decoder. The caller may not write to it.
  *
- * @param[in] avpkt The input AVpacket containing the input buffer.
+ * @param[in] avpkt The input AVPacket containing the input buffer.
  *            You can create such packet with av_init_packet() and by then setting
  *            data and size, some decoders might in addition need other fields like
  *            flags&AV_PKT_FLAG_KEY. All decoders are designed to use the least
@@ -4847,7 +4849,8 @@ function avcodec_decode_video2(avctx: PAVCodecContext; picture: PAVFrame;
                        avpkt: {const} PAVPacket): cint;
   cdecl; external av__codec;
 
-(* Decode a subtitle message.
+(*
+ * Decode a subtitle message.
  * Return a negative value on error, otherwise return the number of bytes used.
  * If no subtitle could be decompressed, got_sub_ptr is zero.
  * Otherwise, the subtitle is stored in *sub.
@@ -5032,6 +5035,13 @@ type
      *)
     picture_structure: TAVPictureStructure;
 
+    (**
+     * Picture number incremented in presentation or output order.
+     * This field may be reinitialized at the first picture of a new sequence.
+     *
+     * For example, this corresponds to H.264 PicOrderCnt.
+     *)
+    output_picture_number: cint;
   end; {AVCodecParserContext}
 
   TAVCodecParser = record
diff --git a/src/lib/ffmpeg-2.5/avformat.pas b/src/lib/ffmpeg-2.5/avformat.pas
index 89177a5e..ce2effce 100644
--- a/src/lib/ffmpeg-2.5/avformat.pas
+++ b/src/lib/ffmpeg-2.5/avformat.pas
@@ -1734,7 +1734,7 @@ type
      *)
     format_whitelist: PAnsiChar;
 
-		(*****************************************************************
+    (*****************************************************************
      * All fields below this line are not part of the public API. They
      * may not be used outside of libavformat and can be changed and
      * removed at will.