[FFmpeg-devel] [PATCH v4 5/8] avpriv_find_start_code(): add doxygen comment and rename a parameter

[Scott Theisen]

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

diff --git a/libavcodec/startcode.h b/libavcodec/startcode.h
index 833754af09..69389c729c 100644
--- a/libavcodec/startcode.h
+++ b/libavcodec/startcode.h
@@ -44,9 +44,33 @@ static av_always_inline int 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 pointer 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$ end - p < 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 ff_startcode_find_candidate_c(const uint8_t *buf, int size);
 
diff --git a/libavcodec/utils.c b/libavcodec/utils.c
index 83f7d8a01a..63bf4b8cb7 100644
--- a/libavcodec/utils.c
+++ b/libavcodec/utils.c
@@ -981,7 +981,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)
@@ -990,10 +990,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 (start_code_is_valid(*state) || p == end)
+        if (start_code_is_valid(*start_code) || p == end)
             return p;
     }
     // p is now properly incremented for the negative indices in the while loop
@@ -1023,7 +1023,7 @@ const uint8_t *avpriv_find_start_code(const uint8_t *av_restrict p,
     if (p > end)
         p = end;
     // read the previous 4 bytes, i.e. bytes {p - 4, p - 3, p - 2, p - 1}
-    *state = AV_RB32(p - 4);
+    *start_code = AV_RB32(p - 4);
     return p;
 }
 
-- 
2.34.1