Docs - Core api reference refresh (#669)

* Updated core docs + Doxyfile

* fixed issues, renamed a file, deleted unused files

* added hip-dev as a requirement for 7.2

* updated with Jeff's review

* updated getvideoframe description

* Update docs/reference/rocDecode-parser.rst

Co-authored-by: Leo Paoletti <164940351+lpaoletti@users.noreply.github.com>

* Update docs/how-to/using-rocDecode-video-decoder.rst

Co-authored-by: Leo Paoletti <164940351+lpaoletti@users.noreply.github.com>

* updated with Leo's feedback

* fixed a wrong link in toc

---------

Co-authored-by: Kiriti Gowda <kiritigowda@gmail.com>
Co-authored-by: Leo Paoletti <164940351+lpaoletti@users.noreply.github.com>

docs/doxygen/Doxyfile

@@ -1158,7 +1158,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = README.md
+USE_MDFILE_AS_MAINPAGE = 
 
 # The Fortran standard specifies that for fixed formatted Fortran code all
 # characters from position 72 are to be considered as comment. A common

docs/how-to/using-rocDecode-rocdecdecoder.rst

@@ -0,0 +1,245 @@
+.. meta::
+  :description: Using the rocDecode core API
+  :keywords: rocDecode, AMD, ROCm, core API
+
+********************************************************************
+Using the rocdecdecode example
+********************************************************************
+
+rocDecode provides four core APIs exposed in the header files in the |apifolder|_ directory:
+
+| The rocDecode parser API, exposed in ``rocparser.h``. 
+| The hardware decoder API, exposed in ``rocdecode.h``.
+| The software decoder API, exposed in ``rocdecode_host.h``.
+| The bitstream reader API, exposed in ``roc_bitstream_reader.h``.
+
+The |rocdecdecode|_ sample demonstrates how to use the rocDecode core APIs in an application. It shows how to use the parser and both the hardware and software decoders. For information on how to use the bitstream reader API, see :doc:`Using the rocDecode bitstream reader API <./using-rocDecode-bitstream>`.
+
+The sample decodes raw elementary video frame files as input and produces individually decoded frames in YUV format as output. The input can be one individual frame file or multiple frames from one or more video files. The individual frame files must be numbered in ascending order of frames.
+
+``rocdecdecode.cpp`` takes the following arguments:
+
+.. list-table:: 
+    :widths: 10 60 30 
+    :header-rows: 1
+
+    * - Argument      
+      - Description 
+      - Note
+
+    * - ``-i``
+      - Path to the input video frame file or to frame folder.
+      - Required. 
+    
+    * - ``-o`` 
+      - Output path. Saves the decoded YUV frames to this folder. 
+      - Optional. Decoded frames aren't saved by default.
+
+    * - ``-d`` 
+      - GPU device ID. Set it to 0 for the first device, 1 for the second device, 2 for the third device, and so on for each subsequent device. 
+      - Optional. Set to 0 by default.
+  
+    * - ``-b`` 
+      - Backend. Set it to 0 to use the hardware decoder on the GPU or to 1 to use the software decoder on the CPU.
+      - Optional. Set to 0 by default.
+
+
+    * - ``-c``
+      - Codec. Set to 0 for HEVC, 1 for H264, 2 for AV1, 4 for VP9, 5 for VP8, or 6 for MJPEG.
+      - Optional. Set to 0 by default.
+      
+    * - ``-n`` 
+      - Number of iterations for performance evaluation.
+      - Optional. Set to 1 by default.
+
+    * - ``-m`` 
+      - The output surface memory type. The memory type where the surface data, such as the decoded frames, resides. Set this to 0 for intermediate GPU memory, to 1 for GPU memory, and to 2 for CPU memory. See :doc:`Surface data memory locations <../conceptual/rocDecode-memory-types>` for more information. 
+      - Optional. Set to 0 by default. 
+
+The ``DecoderInfo`` struct defined in the sample is used to store user-supplied parameters as well as the decoder and parser handles. 
+
+The memory type and the type of decoder is set by the specified backend. If the GPU (device) backend is selected, both a parser and a hardware decoder are created. If the CPU (host) backend is selected, only a software decoder is created:
+
+.. code:: cpp
+  
+  DecoderInfo dec_info;
+  [...]
+  int main(int argc, char** argv) {
+    [...]
+    dec_info.rocdec_codec_id = CodecTypeToRocDecVideoCodec(codec_type);
+    dec_info.dec_device_id = device_id;
+    dec_info.mem_type = (!backend) ? OUT_SURFACE_MEM_DEV_INTERNAL : OUT_SURFACE_MEM_HOST;
+    init();
+    if (backend == DECODER_BACKEND_DEVICE) {
+      create_parser(dec_info);
+      create_decoder(dec_info);
+    } else {
+      create_decoder_host(dec_info);
+    }
+  [...]
+  }
+
+All applications need to register the ``pfn_sequence_callback`` and ``pfn_display_picture`` callbacks. Applications that use the parser must also register the ``pfn_decode_picture`` callback.
+
+When the GPU backend is selected, these callbacks are registered in the ``create_parser()`` function. ``create_parser`` also creates the parser using ``rocDecCreateVideoParser()``:
+
+.. code:: cpp
+
+  void create_parser(DecoderInfo& dec_info) {
+    RocdecParserParams params = {};
+    params.codec_type = dec_info.rocdec_codec_id;
+    params.max_num_decode_surfaces = 6;
+    params.max_display_delay = 1;      
+    params.user_data = &dec_info;
+    params.pfn_sequence_callback = handle_video_sequence;
+    params.pfn_decode_picture = handle_picture_decode;
+    params.pfn_display_picture = handle_picture_display;
+    CHECK(rocDecCreateVideoParser(&dec_info.parser, &params));
+  }
+
+The ``create_decoder()`` function sets the decoder parameters and passes them to ``rocDecCreateDecoder()`` to create the hardware decoder:
+
+.. code:: cpp
+  
+  void create_decoder(DecoderInfo& dec_info) {
+    RocDecoderCreateInfo create_info = {};
+    create_info.codec_type = dec_info.rocdec_codec_id;     // user specified codec_type for raw files
+    [...]
+    CHECK(rocDecCreateDecoder(&dec_info.decoder, &create_info));
+  }
+
+The ``create_decoder_host()`` function performs the same actions as ``create_decoder()``, but uses ``rocDecCreateDecoderHost()`` to create a software decoder. Because the parser isn't used with the software decoder, and because the software decoder uses different function calls, the callbacks for the software decoder are registered in ``create_decoder_host()``:
+
+.. code:: cpp
+
+  void create_decoder_host(DecoderInfo& dec_info) {
+    RocDecoderHostCreateInfo create_info = {};
+    create_info.codec_type = dec_info.rocdec_codec_id;
+    [...]
+    create_info.pfn_sequence_callback = handle_video_sequence_host;
+    create_info.pfn_display_picture = handle_picture_display_host;
+    CHECK(rocDecCreateDecoderHost(&dec_info.decoder, &create_info));
+    dec_info.backend = DECODER_BACKEND_HOST;
+  }
+
+After the decoder and parser have been created, ``decode_frames`` is called. 
+
+.. code:: cpp
+
+  int main(int argc, char** argv) {
+    [...]
+    dec_info.dump_decoded_frames = dump_output_frames;
+    auto input_frames = read_frames(input_file_names);
+    auto start = std::chrono::high_resolution_clock::now();
+    for (int i = 0; i < num_iterations; i++) {
+      decode_frames(dec_info, input_frames);
+    }
+    [...]
+  }
+
+``decode_frames`` calls ``rocDecParseVideoData()`` or ``rocDecDecodeFrameHost()``, depending on the backend, to parse and decode the frames:
+
+.. code:: cpp
+
+  void decode_frames(DecoderInfo& dec_info, const std::vector<std::vector<uint8_t>>& frames) {
+    // gpu backend using VCN
+    if (dec_info.backend == DECODER_BACKEND_DEVICE) {
+        for (int i=0; i < static_cast<int>(frames.size()); ++i) {
+            RocdecSourceDataPacket packet = {};
+            packet.payload_size = frames[i].size();
+            packet.payload = frames[i].data();
+            if (i == static_cast<int>(frames.size() - 1)) {
+                packet.flags = ROCDEC_PKT_ENDOFPICTURE;     // mark end_of_picture flag for last frame
+            }
+            CHECK(rocDecParseVideoData(dec_info.parser, &packet));
+        }
+    } else if (dec_info.backend == DECODER_BACKEND_HOST) {
+        for (int i=0; i < static_cast<int>(frames.size()); ++i) {
+            RocdecPicParamsHost pic_params = {};
+            pic_params.bitstream_data_len = frames[i].size();
+            pic_params.bitstream_data = frames[i].data();
+            if (i == static_cast<int>(frames.size() - 1)) {
+                pic_params.flags = ROCDEC_PKT_ENDOFPICTURE;     // mark end_of_picture flag for last frame
+            }
+            CHECK(rocDecDecodeFrameHost(dec_info.decoder, &pic_params));
+        }   
+    }
+  }
+
+The registered callbacks are triggered during the calls to ``rocDecParseVideoData()`` and ``rocDecDecodeFrameHost()``. 
+
+``pfn_decode_picture`` is triggered when a new frame is ready to be decoded, ``pfn_sequence_callback`` is triggered when a new sequence header is encountered, and ``pfn_display_picture`` is triggered when a frame has finished being decoded. 
+
+``pfn_decode_picture`` needs to call ``rocDecDecodeFrame()`` or ``rocDecodeFrameHost()``, depending on the specified backend, to decode a frame. 
+
+In ``rocdecdecode.cpp``, ``pfn_decode_picture`` calls ``handle_picture_decode()`` or ``handle_picture_decode_host()``, depending on the specified backend:
+
+.. code:: cpp
+
+  int ROCDECAPI handle_picture_decode(void* user_data, RocdecPicParams* params) {
+    DecoderInfo *p_dec_info = static_cast<DecoderInfo *>(user_data);
+    CHECK(rocDecDecodeFrame(p_dec_info->decoder, params));
+    return 1;
+  }
+
+``pfn_sequence_callback`` is triggered when a format change occurs or when a new sequence header is encountered. When this happens, the decoder is reconfigured to handle the new sequence or format. 
+
+``pfn_sequence_callback`` needs to call ``rocDecReconfigureDecoder()`` or ``rocDecReconfigureDecoderHost()`` depending on the backend, to reconfigure the decoder. 
+
+In the ``rocdecdecode.cpp`` sample, ``pfn_sequence_callback`` calls ``handle_video_sequence()`` or ``handle_video_sequence_host()``, depending on the specified backend:
+
+.. code:: cpp
+
+  int ROCDECAPI handle_video_sequence(void* user_data, RocdecVideoFormat* format) {
+    DecoderInfo *p_dec_info = static_cast<DecoderInfo *>(user_data);
+    [...]
+    RocdecReconfigureDecoderInfo reconfig_params = {};
+    reconfig_params.width = format->coded_width;
+    reconfig_params.height = format->coded_height;
+    reconfig_params.bit_depth_minus_8 = bitdepth_minus_8;
+    reconfig_params.num_decode_surfaces = format->min_num_decode_surfaces;
+    reconfig_params.target_width = target_width;
+    reconfig_params.target_height = target_height;
+    reconfig_params.display_rect.left = format->display_area.left;
+    reconfig_params.display_rect.right = format->display_area.right;
+    reconfig_params.display_rect.top = format->display_area.top;
+    reconfig_params.display_rect.bottom = format->display_area.bottom;        
+    CHECK(rocDecReconfigureDecoder(p_dec_info->decoder, &reconfig_params));
+    [...]
+    return 1;
+  }
+
+``pfn_display_picture`` is triggered when a frame has been decoded. It needs to call ``rocDecGetVideoFrame()`` or ``rocDecGetVideoFrameHost()``, depending on the specified backend. 
+
+``rocDecGetVideoFrame()`` and ``rocDecGetVideoFrameHost()`` map the video ID of the decoded frame to HIP. Calls to both these functions block until the frame is decoded and the memory mapping is complete. They return the HIP device pointer or the host memory pointer, depending on the backend specified, as well as information about the :doc:`output surface <../conceptual/rocDecode-memory-types>`. 
+
+``pfn_display_picture`` calls ``handle_picture_display()`` or ``handle_handle_picture_display_host()``, depending on the specified backend, and saves the frames to file if the ``rocdecdecode`` was run with the ``-o`` option:
+
+From the ``rocdecdecode.cpp`` sample:
+
+.. code:: cpp
+
+  int ROCDECAPI handle_picture_display(void* user_data, RocdecParserDispInfo* disp_info) {
+    DecoderInfo *p_dec_info = static_cast<DecoderInfo *>(user_data);
+    RocdecProcParams params = {};
+    params.progressive_frame = disp_info->progressive_frame;
+    params.top_field_first = disp_info->top_field_first;
+    void* dev_mem_ptr[3] = { 0 };
+    uint32_t pitch[3] = { 0 };
+    CHECK(rocDecGetVideoFrame(p_dec_info->decoder, disp_info->picture_index, dev_mem_ptr, pitch, &params));
+      if (p_dec_info->dump_decoded_frames) {
+        save_frame_to_file(p_dec_info, dev_mem_ptr, pitch);
+      }
+    return 1;
+  }
+
+Once decoding is complete, ``rocDecDestroyVideoParser()`` needs to be called to destroy the parser, and either ``rocDecDestroyDecoderHost()`` or ``rocDecDestroyDecoder()`` needs to be called to destroy the decoder.
+
+.. |rocdecdecode| replace:: ``rocdecdecode``
+.. _rocdecdecode: https://github.com/ROCm/rocDecode/tree/develop/samples/rocdecDecode/README.md
+
+.. |apifolder| replace:: ``api/rocdecode/``
+.. _apifolder: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode
+
+.. |utilsfolder| replace:: ``utils`` folder
+.. _utilsfolder: https://github.com/ROCm/rocDecode/tree/develop/utils

docs/how-to/using-rocDecode-video-decoder.rst

@@ -6,9 +6,10 @@
 Using the rocDecode RocVideoDecoder
 ********************************************************************
 
-rocDecode provides two ways of decoding a video stream: using the rocDecode RocVideoDecoder on GPU or using the FFmpeg decoder on CPU. 
+rocDecode provides two methods fpr decoding a video stream: using the rocDecode RocVideoDecoder on the GPU or using the FFmpeg decoder on the CPU. 
 
-This topic covers how to decode a video stream using the RocVideoDecoder class in |roc_video_dec|_. The RocVideoDecode class provides high-level calls to the core APIs in the |apifolder|_ of the rocDecode GitHub repository. For information about the core APIs, see :doc:`Using the rocDecode core APIs <./using-rocdecode>`.
+
+This topic covers how to decode a video stream using the RocVideoDecoder class in |roc_video_dec|_. The RocVideoDecode class provides high-level calls to the core APIs in the |apifolder|_ of the rocDecode GitHub repository. For information about the core APIs, see :doc:`Using the rocDecode core APIs <../reference/rocDecode-core-APIs>`.
 
 The RocVideoDecoder takes a demultiplexed coded picture as input. The picture can be demultiplexed from a video stream using the :doc:`FFmpeg demultiplexer <./using-rocDecode-ffmpeg>`.
 
@@ -86,12 +87,10 @@ To prevent the remaining frames in the buffers from being deleted along with the
 
 The |reconfig_struct|_ struct stores information on how to handle the reconfiguration. A callback, a user-defined flush mode, and a user-defined struct are passed to ``ReconfigParams_t``. The reconfiguration parameters are then passed to the decoder using ``SetReconfigParams``.
 
-The reconfiguration parameters need to be defined prior to entering the decoding loop. 
-
-For example, the reconfiguration structs are defined in |common|_ in the rocDecode samples and then used in ``videodecode.cpp``:
-
-.. code:: C++
+The reconfiguration parameters need to be defined prior to entering the decoding loop. For example, the reconfiguration structs are defined in |common|_ in the rocDecode samples and then used in ``videodecode.cpp``
 
+.. code:: cpp
+    
     typedef enum ReconfigFlushMode_enum {
         RECONFIG_FLUSH_MODE_NONE = 0x0,                      /**<  Just flush to get the frame count */
         RECONFIG_FLUSH_MODE_DUMP_TO_FILE = 0x1,              /**<  The remaining frames will be dumped to file in this mode */
@@ -104,7 +103,6 @@ For example, the reconfiguration structs are defined in |common|_ in the rocDeco
         void *md5_generator_handle;
     } ReconfigDumpFileStruct;
 
-
     reconfig_params.p_fn_reconfigure_flush = ReconfigureFlushCallback;
     reconfig_user_struct.b_dump_frames_to_file = dump_output_frames;
     reconfig_user_struct.output_file_name = output_file_path;
@@ -118,13 +116,8 @@ For example, the reconfiguration structs are defined in |common|_ in the rocDeco
     reconfig_params.p_reconfig_user_struct = &reconfig_user_struct;
     viddec.SetReconfigParams(&reconfig_params);
 
-
 In the decode loop, the demultiplexed coded picture is passed to ``DecodeFrame``. Once the frame is decoded and processed, it is released with ``ReleaseFrame``. 
 
-
-
-
-
 .. |videodecode| replace:: ``videodecode.cpp``
 .. _videodecode: https://github.com/ROCm/rocDecode/tree/develop/samples/videoDecode/videodecode.cpp
 

docs/how-to/using-rocDecode-videodecode-sample.rst

@@ -76,7 +76,6 @@ The ``videodecode.cpp`` sample lets the user choose which method to use through
       - Seek criteria and seek starting point
       - Optional. Set to 1 and the frame number to start demultiplexing from that specific frame. Set to 2 and the timestamp to start demultiplexing from that specific timestamp. The seek criteria and starting point must be comma-separated (``,``). Demultiplexing begins at the first frame by default. 
 
-      
     * - ``-seek_mode``
       - Seek mode 
       - Optional. Set to 0 to seek to the previous keyframe. Set to 1 to seek to the exact frame. Seeks to previous keyframe by default.

docs/how-to/using-rocdecode.rst

@@ -1,236 +0,0 @@
-.. meta::
-  :description: Using rocDecode
-  :keywords: parse video, parse, decode, video decoder, video decoding, rocDecode, core APIs, AMD, ROCm
-
-********************************************************************
-Using the rocDecode core APIs
-********************************************************************
-
-rocDecode core APIs are available in the |apifolder|_ of the `rocDecode GitHub repository <https://github.com/ROCm/rocDecode>`_. 
-
-.. note::
-
-  The rocDecode samples use the utility classes in the |utilsfolder|_ instead of the core APIs. For information about using the utility classes, see :doc:`Using rocDecode with the FFmpeg decoder <./using-rocDecode-ffmpeg>` and :doc:`Using rocDecode with the bitstream decoder <./using-rocDecode-bitstream>`.
-
-
-API overview
-====================================================
-
-All rocDecode APIs are exposed in the header files ``rocdecode.h`` and ``rocparser.h``. You can find
-these files in the ``api`` folder in the rocDecode repository.
-
-The samples use the ``RocVideoDecoder`` user class provided in ``roc_video_dec.h`` in the ``utils`` folder
-of the rocDecode repository.
-
-A video parser (defined in ``rocparser.h``) is needed to extract and decode headers from the bitstream
-in order to organize the data into a structured format for the hardware decoder. The parser is critical in
-video decoding, as it controls the decoding and display of a bitstream's individual frames and fields.
-
-The parser object in ``rocparser.h`` has three main APIs:
-
-* ``rocDecCreateVideoParser()``
-* ``rocDecParseVideoData()``
-* ``rocDecDestroyVideoParser()``
-
-Create a parser object
-====================================================
-
-The ``rocDecCreateVideoParser()`` API creates a video parser object for the codec that you specify. The
-API takes ``max_num_decode_surfaces``, which determines the Decoded Picture Buffer (DPB) size for
-decoding. When creating a parser object, the application must register certain callback functions with
-the driver, which is called from the parser during decode.
-
-
-* ``pfn_sequence_callback`` is called when the parser encounters a new sequence header. The parser
-  informs you of the minimum number of surfaces needed by the parser's DPB to successfully decode
-  the bitstream. In addition, the caller can set additional parameters, like ``max_display_delay``, to
-  control frame decoding and display.
-
-* The ``pfn_decode_picture`` callback function is triggered when a picture is set for decoding.
-
-* The ``pfn_display_picture`` callback function is triggered when a frame in display order is ready to be
-  consumed by the caller.
-
-* The ``pfn_get_sei_msg`` callback function is triggered when your Supplementation Enhancement
-  Information (SEI) message is parsed and returned to the caller.
-
-
-Parse video data
-====================================================
-
-Elementary stream video packets extracted from the de-multiplexer are fed into the parser using the
-``rocDecParseVideoData()`` API.
-
-During this call, the parser triggers the callbacks as it encounters a new sequence header, receives
-compressed frame/field data ready to be decoded, or when it's ready to display a frame. If any of the
-callbacks return a failure, it is propagated back to the application so the decoding can be ended
-gracefully.
-
-Query decode capabilities
-====================================================
-
-The ``rocDecGetDecoderCaps()`` API allows you to query the capabilities of the underlying hardware
-video decoder. Decoder capabilities usually include supported codecs, maximum resolution, and
-bit depth.
-
-
-The following pseudo-code illustrates the use of this API. The application handles the error
-appropriately for non-supported decoder capabilities.
-
-.. code:: cpp
-
-    RocdecDecodeCaps decode_caps;
-    memset(&decode_caps, 0, sizeof(decode_caps));
-    decode_caps.codec_type = p_video_format->codec;
-    decode_caps.chroma_format = p_video_format->chroma_format;
-    decode_caps.bit_depth_minus_8 = p_video_format->bit_depth_luma_minus8;
-
-    ROCDEC_API_CALL(rocDecGetDecoderCaps(&decode_caps));
-
-    if(!decode_caps.is_supported) {
-        ROCDEC_THROW("Rocdec:: Codec not supported on this GPU: ", ROCDEC_NOT_SUPPORTED);
-        return 0;
-    }
-
-    if ((p_video_format->coded_width > decode_caps.max_width) ||
-        (p_video_format->coded_height > decode_caps.max_height)) {
-
-        std::ostringstream errorString;
-        errorString << std::endl
-                    << "Resolution          : " << p_video_format->coded_width << "x" << p_video_format->coded_height << std::endl
-                    << "Max Supported (wxh) : " << decode_caps.max_width << "x" << decode_caps.max_height << std::endl
-                    << "Resolution not supported on this GPU ";
-
-        const std::string cErr = errorString.str();
-        ROCDEC_THROW(cErr, ROCDEC_NOT_SUPPORTED);
-        return 0;
-    }
-
-Create a decoder
-====================================================
-
-``rocDecCreateDecoder()`` creates an instance of the hardware video decoder object and provides you
-with a handle upon successful creation. Refer to the ``RocDecoderCreateInfo`` structure for information
-about the parameters passed for creating the decoder. For example,
-``RocDecoderCreateInfo::codec_type`` represents the codec type of the video. The decoder handle
-returned by ``rocDecCreateDecoder()`` needs to be retained for the entire decode session because the
-handle is passed along with the other decoding APIs. In addition, you can inform display or crop
-dimensions along with this API.
-
-Decode the frame
-====================================================
-
-After de-multiplexing and parsing, you can decode bitstream data containing a frame/field using
-hardware.
-
-Use the ``rocDecDecodeFrame()`` API to submit a new frame for hardware decoding. Underneath the
-driver, the Video Acceleration API (VA-API) is used to submit compressed picture data to the driver.
-The parser extracts all the necessary information from the bitstream and fills the ``RocdecPicParams``
-structure that's appropriate for the codec. The high-level ``RocVideoDecoder`` class connects the parser
-and decoder used for all sample applications.
-
-The ``rocDecDecodeFrame()`` call takes the decoder handle and the pointer to the ``RocdecPicParams``
-structure and initiates the video decoding using VA-API.
-
-Query the decoding status
-====================================================
-
-After submitting a frame for decoding, you can call ``rocDecGetDecodeStatus()`` to query the decoding
-status for a given frame. A structure pointer, ``RocdecDecodeStatus*``, is filled and returned.
-
-The API inputs are:
-
-* ``decoder_handle``: A ``RocDecoder`` handler, ``rocDecDecoderHandle``.
-* ``pic_idx``: An `int` value for the ``picIdx`` for which you want a status in order to index of the picture.
-* ``decode_status``: A pointer to ``RocdecDecodeStatus`` as a return value.
-
-Please note that this API makes a non-blocking call and returns the status of the frame associated with nPicIdx at the time of the call,
-without waiting for the decoding to complete. The ``decode_status->decode_status`` can be either ``rocDecodeStatus_Success``, indicating that
-the decoding has been completed, or ``rocDecodeStatus_InProgress``, which means that the decoding is still in progress.
-
-Prepare the decoded frame for further processing
-====================================================
-
-The decoded frames can be used for further postprocessing using ``rocDecGetVideoFrame()``. The
-successful completion of ``rocDecGetVideoFrame()`` indicates that the decoding process is complete and
-the device memory pointer is inter-opped into the ROCm HIP address space in order to further process
-the decoded frame in device memory. Please note that the ``rocDecGetVideoFrame()`` API is a blocking call.
-If the video frame associated with the pic_idx is not ready, the call will wait for the decoding to complete before mapping the video frame for use in HIP.
-The caller gets the necessary information on the output surface,
-such as YUV format, dimensions, and pitch from this call. In the high-level ``RocVideoDecoder`` class, we
-provide four different surface type modes for the mapped surface, as specified in
-``OutputSurfaceMemoryType``.
-
-.. code:: cpp
-
-    typedef enum OutputSurfaceMemoryType_enum {
-        OUT_SURFACE_MEM_DEV_INTERNAL = 0,      /**<  Internal interopped decoded surface memory **/
-        OUT_SURFACE_MEM_DEV_COPIED = 1,        /**<  decoded output will be copied to a separate device memory **/
-        OUT_SURFACE_MEM_HOST_COPIED = 2        /**<  decoded output will be copied to a separate host memory **/
-        OUT_SURFACE_MEM_NOT_MAPPED = 3         /**<  decoded output is not available (interop won't be used): useful for decode only performance app*/
-    } OutputSurfaceMemoryType;
-
-
-If the mapped surface type is ``OUT_SURFACE_MEM_DEV_INTERNAL``, the direct pointer to the decoded
-surface is provided. You need to call ``ReleaseFrame()`` (``RocVideoDecoder`` class). If the requested surface
-type is ``OUT_SURFACE_MEM_DEV_COPIED`` or ``OUT_SURFACE_MEM_HOST_COPIED``, the internal
-decoded frame is copied to another buffer, either in device memory or host memory. After that, it's
-immediately unmapped for reuse by the ``RocVideoDecoder`` class.
-
-Refer to the ``RocVideoDecoder`` class and
-`samples <https://github.com/ROCm/rocDecode/tree/develop/samples>`_ for details on how to use
-these APIs.
-
-Reconfigure the decoder
-====================================================
-
-You can call ``rocDecReconfigureDecoder()`` to reuse a single decoder for multiple clips or when the
-video resolution changes during the decode. The API currently supports resolution changes, resize
-parameter changes, and target area parameter changes for the same codec without destroying an
-ongoing decoder instance. This can improve performance and reduce overall latency.
-
-The API inputs are:
-
-* ``decoder_handle``: A ``RocDecoder`` handler, ``rocDecDecoderHandle``.
-* ``reconfig_params``: You need to specify the parameters for the changes in
-  ``RocdecReconfigureDecoderInfo``. The width and height used for reconfiguration cannot exceed the
-  values set for ``max_width`` and ``max_height``, defined in ``RocDecoderCreateInfo``. If you need to
-  change these values, you have to destroy and recreate the session.
-
-.. note::
-
-  You need to call ``rocDecReconfigureDecoder()`` during ``RocdecParserParams::pfn_sequence_callback``.
-
-Destroy the decoder
-====================================================
-
-You need to call the ``rocDecDestroyDecoder()`` to destroy the session and free up resources.
-
-The API input is:
-
-* ``decoder_handle``: A ``RocDecoder`` handler, ``rocDecDecoderHandle``.
-
-The API returns a ``RocdecDecodeStatus`` value.
-
-Destroy the parser
-====================================================
-
-You need to call ``rocDecDestroyVideoParser()`` to destroy the parser object and free up all allocated
-resources at the end of video decoding.
-
-Logging control
-====================================================
-rocDecode core components can generate various logs during the decode session. The logs can be critical status reports, error reports, warnings, etc. 
-Each log has a significance level associated to it. The level can be from critical (0) to debug info related (4). Lower value has greater importance. 
-An internal logging level threshold can be set to control the verbosity of logging output from each rocDecode component. If a log's level value is less 
-than or equal to the logging level threshold, the log is output. Otherwise, the log is not output.
-
-The logging level threshold can be set by the environment variable ROCDEC_LOG_LEVEL, or by calling the SetLogLevel method of the logger class. The default 
-logging level is 0 (critical log only).
-
-
-.. |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

docs/index.rst

@@ -33,11 +33,11 @@ The rocDecode public repository is located at `https://github.com/ROCm/rocDecode
   .. grid-item-card:: How to
 
     * :doc:`Understand the rocDecode videodecode.cpp sample <./how-to/using-rocDecode-videodecode-sample>`
+    * :doc:`Understand the rocDecode rocdecdecode.cpp sample <./how-to/using-rocDecode-rocdecdecoder>`    
     * :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>`
-
+    * :doc:`Use the rocDecode bitstream reader APIs <./how-to/using-rocDecode-bitstream>` 
+   
 
   .. grid-item-card:: Samples
 
@@ -45,8 +45,14 @@ The rocDecode public repository is located at `https://github.com/ROCm/rocDecode
 
   .. grid-item-card:: Reference
 
+    * :doc:`The rocDecode core APIs <./reference/rocDecode-core-APIs>`
+
+      * :doc:`The rocDecode parser API <./reference/rocDecode-parser>`
+      * :doc:`The rocDecode hardware decoder API <./reference/rocDecode-hw-decoder>`
+      * :doc:`The rocDecode software decoder API <./reference/rocDecode-sw-decoder>`
+      
+    * :doc:`rocDecode logging levels <./reference/rocDecode-logging-control>`
     * :doc:`rocDecode codec support and hardware capabilities <./reference/rocDecode-formats-and-architectures>`
-    * :doc:`rocDecode tested configurations <./reference/rocDecode-tested-configurations>`
     * :doc:`API library <../doxygen/html/files>`
     * :doc:`Functions <../doxygen/html/globals>`
     * :doc:`Data structures <../doxygen/html/annotated>`

docs/install/rocDecode-prerequisites.rst

@@ -6,7 +6,7 @@
 rocDecode prerequisites
 ********************************************************************
 
-rocDecode requires ROCm 6.1 or later running on `accelerators based on the CDNA architecture <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html>`_.
+rocDecode requires ROCm running on `GPUs based on the CDNA architecture <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html>`_.
 
 ROCm must be installed using the AMDGPU installer with the ``rocm`` usecase:
 
@@ -37,4 +37,5 @@ The following prerequisites are installed by the package installer. If you are b
 * pkg-config
 * FFmpeg runtime and headers
 * libstdc++-12-dev for installations on Ubuntu 22.04 
+* HIP, specifically the ``hip-dev`` package
 

docs/reference/index.md

@@ -1,14 +0,0 @@
-<head>
-  <meta charset="UTF-8">
-  <meta name="description" content="rocDecode API reference">
-  <meta name="keywords" content="API reference, rocDecode, AMD, ROCm">
-</head>
-
-# API reference
-
-This section provides technical descriptions and important information about the different rocDecode
-APIs and library components.
-
-* {doc}`Library <../doxygen/html/files>`
-* {doc}`Functions <../doxygen/html/globals>`
-* {doc}`Data structures <../doxygen/html/annotated>`

docs/reference/rocDecode-core-APIs.rst

@@ -0,0 +1,37 @@
+.. meta::
+  :description: Using rocDecode
+  :keywords: parse video, parse, decode, video decoder, video decoding, rocDecode, core APIs, AMD, ROCm
+
+********************************************************************
+The rocDecode core APIs
+********************************************************************
+
+The rocDecode core APIs are intended for users who want to have full control of the decoding pipeline and interact with the core components instead of the utility classes. The :doc:`Using the rocDecode videodecode sample <../how-to/using-rocDecode-videodecode-sample>` provides an introduction to using the utility classes.
+
+The rocDecode core APIs are exposed in header files in the |apifolder|_ folder of the `rocDecode GitHub repository <https://github.com/ROCm/rocDecode>`_. 
+
+:doc:`The rocDecode parser API <./rocDecode-parser>` is exposed in |rocparser|_. It contains functions that create and destroy the parser, as well as functions that parse the bitstream.
+
+:doc:`The hardware decoder API <./rocDecode-hw-decoder>` is exposed in |rocdecode|_. It contains functions that create, control, and destroy the decoder, as well as functions that decode the parsed frames on the GPU.
+
+:doc:`The software decoder API <./rocDecode-sw-decoder>` is exposed in |rocdecodehost|_. It contains the same functionality as ``rocdecode.h``, but all the operations are run on the host rather than the GPU.
+
+:doc:`The bitstream reader API <../how-to/using-rocDecode-bitstream>` is exposed in |bitstreamreader|_. It provides an alternative to the FFMpeg demuxer and contains a simple stream file parser that can read elementary files and IVF container files.
+
+.. |apifolder| replace:: ``api/rocdecode``
+.. _apifolder: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode
+
+.. |rocparser| replace:: ``api/rocdecode/rocparser.h``
+.. _rocparser: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocparser.h
+
+.. |rocdecode| replace:: ``api/rocDecode/rocdecode.h``
+.. _rocdecode: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocdecode.h
+
+.. |rocdecodehost| replace:: ``api/rocDecode/rocdecode_host.h``
+.. _rocdecodehost: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocdecode_host.h
+
+.. |bitstreamreader| replace:: ``api/rocDecode/roc_bitstream_reader.h``
+.. _bitstreamreader: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/roc_bitstream_reader.h
+
+.. |utilsfolder| replace:: ``utils`` folder
+.. _utilsfolder: https://github.com/ROCm/rocDecode/tree/develop/utils

docs/reference/rocDecode-hw-decoder.rst

@@ -0,0 +1,62 @@
+.. meta::
+  :description: The rocDecode hardware decoder 
+  :keywords: decode, video decoder, video decoding, rocDecode, core APIs, AMD, ROCm
+
+********************************************************************
+The rocDecode hardware decoder API
+********************************************************************
+
+The rocDecode hardware decoder API exposed in |rocdecode|_ is used to decode frames that were parsed by :doc:`the rocDecode parser <./rocDecode-parser>`.
+
+Parsing parameters are stored in the ``RocDecoderCreateInfo`` struct and passed to ``rocDecCreateDecoder()`` to create a new decoder. ``rocDecCreateDecoder()`` returns a handle to the decoder. For example:
+
+.. code:: cpp
+
+  RocDecoderCreateInfo create_info = {};
+  create_info.codec_type = dec_info.rocdec_codec_id;     // user specified codec_type for raw files
+  create_info.max_width = DEFAULT_WIDTH;
+  create_info.max_height = DEFAULT_HEIGHT;
+  create_info.width = DEFAULT_WIDTH;
+  create_info.height = DEFAULT_HEIGHT;
+  create_info.num_decode_surfaces = 6;
+  create_info.num_output_surfaces = 1;
+  rocDecCreateDecoder(&decoder_handle, &create_info);
+
+
+``rocDecGetDecoderCaps()`` queries the capabilities of the underlying hardware video decoder. Decoder capabilities usually include supported codecs, maximum resolution, and
+bit depth.
+
+``rocDecDecodeFrame()`` is used to submit frames for hardware decoding. This function must be called when the ``pfn_decode_picture`` callback is triggered in the ``rocDecParseVideoData()`` call. See :doc:`The rocDecode parser API <./rocDecode-parser>` for details about this call.
+
+``rocDecDecodeFrame()`` takes the decoder handle and the pointer to the ``RocdecPicParams()`` struct and initiates the video decoding using VA-API. ``RocdecPicParams`` is populated with the decoded frame information.
+
+The ``pfn_sequence_callback`` callback is triggered when a format change occurs or when a new sequence header is encountered. The implementation of ``pfn_sequence_callback`` must call ``rocDecReconfigureDecoder()`` to reconfigure the decoder to handle the new sequence or format. See :doc:`The rocDecode parser API <./rocDecode-parser>` for details about this callback.
+
+``rocDecGetDecodeStatus()`` can be called to query the decoding status of a frame. The result of the query is either ``rocDecodeStatus_Success``, if decoding is complete, or ``rocDecodeStatus_InProgress``, if decoding is still in progress.
+
+The ``pfn_display_picture`` callback is triggered when a frame has been decoded. The decoded frame can then be further processed in device memory. The implementation for this callback must call ``rocDecGetVideoFrame()`` to obtain the decoded frame's HIP device pointer.
+
+``rocDecGetVideoFrame()`` provides a way to access the decoded frame in HIP. This is a blocking call that only returns once frame decoding and memory mapping is complete. It returns the HIP device pointer as well as information about the :doc:`output surface type <../conceptual/rocDecode-memory-types>`. 
+
+If the output surface type is ``OUT_SURFACE_MEM_DEV_INTERNAL``, meaning intermediate GPU memory, the direct pointer to the decoded surface is provided. If the requested surface
+type is ``OUT_SURFACE_MEM_DEV_COPIED`` or ``OUT_SURFACE_MEM_HOST_COPIED``, the internal decoded frame is copied to another buffer, either in device memory or host memory. 
+
+Once decoding is complete, ``rocDecDestroyVideoParser()`` and ``rocDecDestroyDecoder()`` must be called to destroy the parser and the decoding session, and free resources.
+
+.. |apifolder| replace:: ``api/rocdecode``
+.. _apifolder: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode
+
+.. |rocparser| replace:: ``api/rocdecode/rocparser.h``
+.. _rocparser: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocparser.h
+
+.. |rocdecode| replace:: ``api/rocDecode/rocdecode.h``
+.. _rocdecode: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocdecode.h
+
+.. |rocdecodehost| replace:: ``api/rocDecode/rocdecode_host.h``
+.. _rocdecodehost: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocdecode_host.h
+
+.. |bitstreamreader| replace:: ``api/rocDecode/roc_bitstream_reader.h``
+.. _bitstreamreader: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/roc_bitstream_reader.h
+
+.. |utilsfolder| replace:: ``utils`` folder
+.. _utilsfolder: https://github.com/ROCm/rocDecode/tree/develop/utils

docs/reference/rocDecode-logging-control.rst

@@ -0,0 +1,53 @@
+.. meta::
+  :description: rocDecode logging controls
+  :keywords: rocDecode, core APIs, logging, AMD, ROCm
+
+********************************************************************
+rocDecode logging control
+********************************************************************
+
+rocDecode core components can be configured to output different levels of log messages during decoding.
+
+The log level can be changed by either setting the log level through the ``ROCDEC_LOG_LEVEL`` environment variable, or by calling the ``RocDecLogger::SetLogLevel()`` function in |commons|_.
+
+The logging levels are:
+
+| 0: Critical (Default level)
+| 1: Error
+| 2: Warning
+| 3: Info
+| 4: Debug
+
+The log level defines the maximum severity of log messages to output. For example, to output warning and error messages as well as critical messages, ``ROCDEC_LOG_LEVEL`` would need to be set to 2:
+
+.. code:: shell
+
+    ROCDEC_LOG_LEVEL = 2
+
+or
+
+.. code:: cpp
+
+    SetLogLevel(2);
+
+
+.. |apifolder| replace:: ``api/rocdecode``
+.. _apifolder: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode
+
+.. |rocparser| replace:: ``api/rocdecode/rocparser.h``
+.. _rocparser: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocparser.h
+
+.. |rocdecode| replace:: ``api/rocDecode/rocdecode.h``
+.. _rocdecode: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocdecode.h
+
+.. |rocdecodehost| replace:: ``api/rocDecode/rocdecode_host.h``
+.. _rocdecodehost: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocdecode_host.h
+
+.. |bitstreamreader| replace:: ``api/rocDecode/roc_bitstream_reader.h``
+.. _bitstreamreader: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/roc_bitstream_reader.h
+
+.. |utilsfolder| replace:: ``utils`` folder
+.. _utilsfolder: https://github.com/ROCm/rocDecode/tree/develop/utils
+
+.. |commons| replace:: ``commons.h``
+.. _commons: https://github.com/ROCm/rocDecode/tree/develop/src/commons.h

docs/reference/rocDecode-parser.rst

@@ -0,0 +1,54 @@
+.. meta::
+  :description: The rocDecode parser API
+  :keywords: parse video, parser, decode, video decoder, video decoding, rocDecode, core APIs, AMD, ROCm
+
+********************************************************************
+The rocDecode parser API
+********************************************************************
+
+The rocDecode parser API, exposed in |rocparser|_, is used to decode bitstreams and organize them in a structured format that can be consumed by the hardware decoder.
+
+The parser parameters are stored in the ``RocdecParserParams`` struct and passed to ``rocDecCreateVideoParser()`` to create a new parser. ``rocDecCreateVideoParser()`` returns a handle to the parser. For example:
+
+.. code:: cpp
+
+    RocdecParserParams params = {};
+    params.codec_type = rocdec_codec_id;
+    params.max_num_decode_surfaces = 6;
+    params.max_display_delay = 1;
+    params.user_data = &dec_info;
+    rocDecCreateVideoParser(&parser_handle, &params);
+
+Elementary stream video packets extracted from the demultiplexer (demuxer) are passed to the parser using the ``RocdecSourceDataPacket`` struct. Packet information in ``RocdecSourceDataPacket`` is passed to ``rocDecParseVideoData()``. For example:
+
+.. code:: cpp
+
+    RocdecSourceDataPacket packet = {};
+    packet.payload_size = frames[i].size();
+    packet.payload = frames[i].data();
+    rocDecParseVideoData(parser_handle, &packet);
+
+Three callbacks must be registered when the parser is used: ``pfn_decode_picture``, ``pfn_sequence_callback``, and ``pfn_display_picture``. These callbacks are triggered in the ``rocDecParseVideoData()`` call.
+
+``pfn_decode_picture`` is triggered when a picture is ready for decoding. Its implementation must call ``rocDecDecodeFrame()`` from the hardware decoder API. 
+
+``pfn_sequence_callback`` is triggered when a new sequence header is encountered or when there's a format change. Its implementation handles reconfiguring the decoder to handle the new frame format. Its implementation must call ``rocDecReconfigureDecoder()`` from the hardware decoder API.
+
+``pfn_display_picture`` is triggered when a frame has been decoded.  Its implementation must call ``rocDecGetVideoFrame()`` from the hardware decoder API. 
+
+A fourth callback, ``pfn_get_sei_msg``, is optional. ``pfn_get_sei_msg`` is triggered when a Supplementation Enhancement Information (SEI) message is parsed and returned to the caller. 
+
+If any of the callbacks return an error, the error is propagated back to the application.
+
+Once the stream is fully decoded, ``rocDecDestroyVideoParser()`` must be called to destroy the parser object and free all allocated resources.
+
+
+
+.. |rocparser| replace:: ``rocparser.h``
+.. _rocparser: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocparser.h
+
+.. |utilsfolder| replace:: ``utils`` folder
+.. _utilsfolder: https://github.com/ROCm/rocDecode/tree/develop/utils
+
+.. |rocdecdecode| replace:: ``rocdecdecode.cpp``
+.. _rocdecdecode: https://github.com/ROCm/rocDecode/tree/develop/samples/rocdecDecode/rocdecdecode.cpp

docs/reference/rocDecode-sw-decoder.rst

@@ -0,0 +1,61 @@
+.. meta::
+  :description: The rocDecode software decoder 
+  :keywords: decode, video decoder, video decoding, rocDecode, core APIs, AMD, ROCm
+
+********************************************************************
+The rocDecode software decoder API
+********************************************************************
+
+The rocDecode software decoder API exposed in |rocdecodehost|_ is used to decode frames that have been demultiplexed (demuxed) by :doc:`the FFmpeg demuxer <../how-to/using-rocDecode-ffmpeg>`.
+
+Decoding parameters are stored in the ``RocDecoderHostCreateInfo`` struct and passed to ``rocDecCreateDecoderHost()`` to create a new software decoder. ``rocDecCreateDecoderHost()`` returns a handle to the decoder. For example:
+
+.. code:: cpp
+
+  RocDecoderHostCreateInfo create_info = {};
+  create_info.codec_type = rocdec_codec_id;
+  create_info.num_decode_threads = 0;     // default
+  create_info.max_width = DEFAULT_WIDTH;
+  create_info.max_height = DEFAULT_HEIGHT;
+  create_info.chroma_format = rocDecVideoChromaFormat_420;
+  create_info.output_format = rocDecVideoSurfaceFormat_P016;
+  create_info.bit_depth_minus_8 = 2;
+  create_info.num_output_surfaces = 1;
+  create_info.user_data = &dec_info;
+  rocDecCreateDecoderHost(&dec_info.decoder, &create_info);
+
+``rocDecGetDecoderCapsHost()`` queries the capabilities of the underlying software video decoder. Decoder capabilities usually include supported codecs, maximum resolution, and
+bit depth.
+
+``rocDecDecodeFrameHost()`` is used to submit frames for software decoding. ``rocDecDecodeFrameHost()`` takes the decoder handle and the pointer to the ``RocdecPicParamsHost`` struct and initiates the video decoding. ``RocdecPicParamsHost`` is populated with the decoded frame information.
+
+The ``pfn_sequence_callback`` callback is triggered when a format change occurs or when a new sequence header is encountered. This callback must be registered in any application that uses the software decoder and its implementation must call ``rocDecReconfigureDecoderHost()`` to reconfigure the decoder to handle the new sequence or format. 
+
+``rocDecGetDecodeStatusHost()`` can be called to query the decoding status of a frame. The result of the query is either ``rocDecodeStatus_Success``, if decoding is complete, or ``rocDecodeStatus_InProgress``, if decoding is still in progress.
+
+The ``pfn_display_picture`` callback is triggered when a frame has been decoded. This callback must be registered by any application that uses the software decoder and its implementation must call ``rocDecGetVideoFrameHost()``. ``rocDecGetVideoFrameHost()`` returns the decoded frame's host memory pointer. The decoded frame can then be further processed using this pointer.
+
+``rocDecGetVideoFrameHost()`` provides a way to access the decoded frame in host memory. This is a blocking call that only returns once both frame decoding and memory mapping are done. It returns the host memory pointer as well as information about the :doc:`output surface type <../conceptual/rocDecode-memory-types>`. 
+
+If the output surface type is ``OUT_SURFACE_MEM_DEV_INTERNAL``, meaning intermediate GPU memory, the direct pointer to the decoded surface is provided. If the requested surface
+type is ``OUT_SURFACE_MEM_DEV_COPIED`` or ``OUT_SURFACE_MEM_HOST_COPIED``, the internal decoded frame is copied to another buffer, either in device memory or host memory. 
+
+Once decoding is complete, ``rocDecDestroyDecoderHost()`` must be called to destroy the decoder and free resources.
+
+.. |apifolder| replace:: ``api/rocdecode``
+.. _apifolder: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode
+
+.. |rocparser| replace:: ``api/rocdecode/rocparser.h``
+.. _rocparser: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocparser.h
+
+.. |rocdecode| replace:: ``api/rocDecode/rocdecode.h``
+.. _rocdecode: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocdecode.h
+
+.. |rocdecodehost| replace:: ``api/rocDecode/rocdecode_host.h``
+.. _rocdecodehost: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocdecode_host.h
+
+.. |bitstreamreader| replace:: ``api/rocDecode/roc_bitstream_reader.h``
+.. _bitstreamreader: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/roc_bitstream_reader.h
+
+.. |utilsfolder| replace:: ``utils`` folder
+.. _utilsfolder: https://github.com/ROCm/rocDecode/tree/develop/utils

docs/reference/rocDecode-tested-configurations.rst

@@ -1,24 +0,0 @@
-.. meta::
-  :description: rocDecode tested configurations
-  :keywords: install, rocDecode, AMD, ROCm, tested configurations, prerequisites, dependencies, requirements
-
-********************************************************************
-rocDecode tested configurations
-********************************************************************
-
-rocDecode has been tested on the following operating system, software, and library versions:
-
-* Linux:
-  
-  * Ubuntu 20.04, 22.04
-  * RHEL 8, 9
-  * SLES 15-SP5
-
-* ROCm:
-  
-  * rocm-core 6.2.0.60200-66
-  * amdgpu-core 1:6.2.60200-2009582
-
-* libva-dev 2.7.0-2, 2.14.0-1
-* mesa-amdgpu-va-drivers 1:24.2.0.60200-2009582
-* FFmpeg 4.2.7, 4.4.2-0

docs/sphinx/_toc.yml.in

@@ -32,22 +32,32 @@ subtrees:
 - caption: How to
   entries:
   - file: how-to/using-rocDecode-videodecode-sample.rst
-    title: Understand the rocDecode videodecode sample
+    title: Understand the videodecode sample
+  - file: how-to/using-rocDecode-rocdecdecoder.rst
+    title: Understand the rocdecdecode.cpp sample    
   - file: how-to/using-rocDecode-video-decoder.rst
-    title: Use the rocDecode RocVideoDecoder
+    title: Use RocVideoDecoder
   - file: how-to/using-rocDecode-ffmpeg.rst
-    title: Use the rocDecode FFmpeg demultiplexer
+    title: Use the 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
+    title: Use the bitstream reader APIs 
 
 - caption: Reference
   entries:
+  - file: reference/rocDecode-core-APIs.rst
+    title: Core APIs 
+    subtrees:
+    - entries:
+      - file: reference/rocDecode-parser.rst
+        title: Parser API
+      - file: reference/rocDecode-hw-decoder.rst
+        title: Hardware decoder API
+      - file: reference/rocDecode-sw-decoder.rst
+        title: Software decoder API
+  - file: reference/rocDecode-logging-control.rst
+    title: Logging levels 
   - file: reference/rocDecode-formats-and-architectures.rst
     title: rocDecode supported codecs and architectures
-  - file: reference/rocDecode-tested-configurations.rst
-    title: rocDecode tested configurations
   - file: doxygen/html/files
     title: rocDecode API library
   - file: doxygen/html/globals

docs/tutorials/README.md

@@ -1 +0,0 @@
-Placeholder to ensure docs/tutorials folder is created.  Can remove once tutorial content is provided.