From 969eb83653bb30fc32d8eb770902d4eca13b158b Mon Sep 17 00:00:00 2001
From: spolifroni-amd <Sandra.Polifroni@amd.com>
Date: Fri, 21 Mar 2025 14:48:10 -0400
Subject: [PATCH] adding some bitstream reader api doc (#539)

* adding some bitstream reader api doc

* changes based on Jeff and Aryan's review

[ROCm/rocdecode commit: 72e7d23d125ef4c41dbccdb42d471bac72a9b6a6]
---
 .../docs/how-to/using-rocDecode-bitstream.rst | 76 +++++++++++++++++++
 projects/rocdecode/docs/index.rst             |  1 +
 projects/rocdecode/docs/sphinx/_toc.yml.in    |  2 +
 3 files changed, 79 insertions(+)
 create mode 100644 projects/rocdecode/docs/how-to/using-rocDecode-bitstream.rst

diff --git a/projects/rocdecode/docs/how-to/using-rocDecode-bitstream.rst b/projects/rocdecode/docs/how-to/using-rocDecode-bitstream.rst
new file mode 100644
index 0000000000..d07cd6b7bd
--- /dev/null
+++ b/projects/rocdecode/docs/how-to/using-rocDecode-bitstream.rst
@@ -0,0 +1,76 @@
+.. meta::
+  :description: Using the rocDecode bitstream reader API
+  :keywords: rocDecode, AMD, ROCm, bitstream decoder
+
+********************************************************************
+Using the rocDecode bitstream reader APIs
+********************************************************************
+
+The rocDecode bitstream reader APIs are a simplified set of APIs that provide a way to use and test the decoder without relying on FFMpeg. The bitstream reader APIs can be used to extract and parse coded picture data from an elementary video stream for the decoder to consume.
+
+.. note::
+
+    The bitstream reader APIs can only be used with elementary video streams and IVF container files.
+
+
+The |videodecoderaw|_ sample demonstrates how to use the bitstream reader APIs, including how to create a bitstream reader and use it to extract picture data and pass it to the decoder:
+
+.. code:: C++
+
+    RocdecBitstreamReader bs_reader = nullptr;
+    rocDecVideoCodec rocdec_codec_id;
+    int bit_depth;
+    if (rocDecCreateBitstreamReader(&bs_reader, input_file_path.c_str()) != ROCDEC_SUCCESS) {
+        std::cerr << "Failed to create the bitstream reader." << std::endl;
+        return 1;
+    }
+    [...]
+    # Decode loop:
+    do { 
+        if (rocDecGetBitstreamPicData(bs_reader, &pvideo, &n_video_bytes, &pts) != ROCDEC_SUCCESS) {
+            std::cerr << "Failed to get picture data." << std::endl;
+            return 1;
+        }
+        [...]    
+        n_frame_returned = viddec.DecodeFrame(pvideo, n_video_bytes, pkg_flags, pts, &decoded_pics);
+    }
+  
+        
+The ``videodecoderaw.cpp`` example also demonstrates how to use the bitstream reader APIs to obtain the bit depth and codec of a stream:
+
+.. code:: C++
+        
+        if (rocDecGetBitstreamCodecType(bs_reader, &rocdec_codec_id) != ROCDEC_SUCCESS) {
+            std::cerr << "Failed to get stream codec type." << std::endl;
+             return 1;
+        }
+        [...]
+        if (rocDecGetBitstreamBitDepth(bs_reader, &bit_depth) != ROCDEC_SUCCESS) {
+            std::cerr << "Failed to get stream bit depth." << std::endl;
+            return 1;
+        }
+
+
+.. note:: 
+    
+    ``rocDecDestroyBitstreamReader`` must always be called to destroy the bitstream reader once processing is complete.
+
+
+.. |videodecode| replace:: ``videodecode.cpp``
+.. _videodecode: https://github.com/ROCm/rocDecode/tree/develop/samples/videoDecode/videodecode.cpp
+
+.. |videodecoderaw| replace:: ``videodecoderaw.cpp``
+.. _videodecoderaw: https://github.com/ROCm/rocDecode/tree/develop/samples/videoDecodeRaw
+
+.. |common| replace:: ``common.h``
+.. _common: https://github.com/ROCm/rocDecode/blob/develop/samples/common.h
+
+.. |apifolder| replace:: ``api`` folder
+.. _apifolder: https://github.com/ROCm/rocDecode/tree/develop/api
+
+.. |utilsfolder| replace:: ``utils`` folder
+.. _utilsfolder: https://github.com/ROCm/rocDecode/tree/develop/utils
+
+
+.. |reconfig_struct| replace:: ``ReconfigParams_t``
+.. _reconfig_struct: https://rocm.docs.amd.com/projects/rocDecode/en/latest/doxygen/html/structReconfigParams__t.html
\ No newline at end of file
diff --git a/projects/rocdecode/docs/index.rst b/projects/rocdecode/docs/index.rst
index cfcbbaa3c3..bb14c17eed 100644
--- a/projects/rocdecode/docs/index.rst
+++ b/projects/rocdecode/docs/index.rst
@@ -34,6 +34,7 @@ The rocDecode public repository is located at `https://github.com/ROCm/rocDecode
     * :doc:`Understand the rocDecode videodecode.cpp sample <./how-to/using-rocDecode-videodecode-sample>`
     * :doc:`Use the rocDecode RocVideoDecoder <./how-to/using-rocDecode-video-decoder>`
     * :doc:`Use the rocDecode FFmpeg demultiplexer <./how-to/using-rocDecode-ffmpeg>`
+    * :doc:`Use the rocDecode bitstream reader APIs <./how-to/using-rocDecode-bitstream>`    
     * :doc:`Use the rocDecode core APIs <./how-to/using-rocdecode>`
 
 
diff --git a/projects/rocdecode/docs/sphinx/_toc.yml.in b/projects/rocdecode/docs/sphinx/_toc.yml.in
index c2af344b3c..e5b1ff7428 100644
--- a/projects/rocdecode/docs/sphinx/_toc.yml.in
+++ b/projects/rocdecode/docs/sphinx/_toc.yml.in
@@ -37,6 +37,8 @@ subtrees:
     title: Use the rocDecode RocVideoDecoder
   - file: how-to/using-rocDecode-ffmpeg.rst
     title: Use the rocDecode FFmpeg demultiplexer
+  - file: how-to/using-rocDecode-bitstream.rst
+    title: Use the rocDecode bitstream reader APIs  
   - file: how-to/using-rocdecode.rst
     title: Use the rocDecode core APIs