[FFmpeg-devel] [PATCH v2 05/13] avpriv_find_start_code(): add doxygen comment and rename a parameter

[Scott Theisen]

---
 libavcodec/internal.h | 26 +++++++++++++++++++++++++-
 libavcodec/utils.c    | 10 +++++-----
 2 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/libavcodec/internal.h b/libavcodec/internal.h
index 005f308b70..94c41aef0b 100644
--- a/libavcodec/internal.h
+++ b/libavcodec/internal.h
@@ -300,9 +300,33 @@ static av_always_inline int avpriv_start_code_is_valid(uint32_t start_code) {
     return (start_code & 0xFFFFFF00) == 0x100;
 }
 
+/**
+ * @brief Find the first start code in the buffer @p p.
+ *
+ * A start code is a sequence of 4 bytes with the hexadecimal value <b><tt> 00 00 01 XX </tt></b>,
+ * where <b><tt> XX </tt></b> represents any value and memory address increases left to right.
+ *
+ * By preserving the <b>@p start_code</b> value between subsequent calls, the caller can
+ * detect start codes across buffer boundaries.
+ *
+ * @param[in] p     A pointer to the start of the memory buffer to scan.
+ * @param[in] end   A pointer to the past-the-end memory address for the buffer
+ *                  given by @p p.  <b>@p p</b> must be ≤ <b>@p end</b>.
+ *
+ * @param[in,out] start_code A reference to a mutable @c uint32_t.<br>
+ *          As input: For no history preset to <b>@c ~0 </b>, otherwise preset to the last
+ *                    returned start code to enable detecting start codes across
+ *                    buffer boundaries.<br>
+ *          On output: Set to the found start code if it exists or an invalid
+ *                     start code (the 4 bytes prior to the returned value,
+ *                     using the input history if @f$ p - end < 4 @f$).
+ *
+ * @return A pointer to the memory address following the found start code, or <b>@p end</b>
+ *         if no start code was found.
+ */
 const uint8_t *avpriv_find_start_code(const uint8_t *p,
                                       const uint8_t *end,
-                                      uint32_t *state);
+                                      uint32_t *start_code);
 
 int avpriv_codec_get_cap_skip_frame_fill_param(const AVCodec *codec);
 
diff --git a/libavcodec/utils.c b/libavcodec/utils.c
index 1a806b9fa8..80ccde023f 100644
--- a/libavcodec/utils.c
+++ b/libavcodec/utils.c
@@ -942,7 +942,7 @@ void ff_thread_report_progress2(AVCodecContext *avctx, int field, int thread, in
 
 const uint8_t *avpriv_find_start_code(const uint8_t *av_restrict p,
                                       const uint8_t *end,
-                                      uint32_t *av_restrict state)
+                                      uint32_t *av_restrict start_code)
 {
     av_assert0(p <= end);
     if (p >= end)
@@ -951,10 +951,10 @@ const uint8_t *avpriv_find_start_code(const uint8_t *av_restrict p,
     // read up to the first three bytes in p to enable reading a start code across
     // two (to four) buffers
     for (int i = 0; i < 3; i++) {
-        *state <<= 8;
-        *state += *p;
+        *start_code <<= 8;
+        *start_code += *p;
         p++;
-        if (avpriv_start_code_is_valid(*state) || p == end)
+        if (avpriv_start_code_is_valid(*start_code) || p == end)
             return p;
     }
     // p is now properly incremented for the negative indices in the while loop
@@ -988,7 +988,7 @@ const uint8_t *avpriv_find_start_code(const uint8_t *av_restrict p,
     // this will cause the last 4 bytes before end to be read,
     // i.e. no out of bounds memory access occurs
 
-    *state = AV_RB32(p - 4);
+    *start_code = AV_RB32(p - 4);
     // read the previous 4 bytes, i.e. bytes {p - 4, p - 3, p - 2, p - 1}
 
     return p;
-- 
2.32.0