Docs - Adding documentation (#95)

* Update documentation requirements * Upd doc reqs * Update RTD yaml * cherry pick to add documentation (#94) * Prepare documentation (#57) * Updated the readme file to point to the official documentation * first commit of new documentation structure * split up and reconfigured Using rocJpeg * Updated the readme file to point to the official documentation * first commit of new documentation structure * split up and reconfigured Using rocJpeg * fixed missing space * All changes asked for in the PR except the Destroy Handles part. * separated creating and destroying handles; added a destroying handles section; added links to hipmalloc() and hipfree() * removed the installation and build sections so that it doesn't conflict/go out of sync with the official doc * putting readme back the way it was, minus documentation section * changed some wording around hipFree() * Fix a typo in README/Docs (#66) * Edited the readme and reorganized the toc (#69) * Edited the readme so that it doesn't duplicate information in the official online docs * rearranged the toc to match the new structure * moved Docker section --------- Co-authored-by: Aryan Salmanpour <[email protected]> * Update README.md --------- Co-authored-by: alexxu-amd <[email protected]> Co-authored-by: Sam Wu <[email protected]> Co-authored-by: Aryan Salmanpour <[email protected]>
ROCm · Dec 10, 2024 · 442a539 · 442a539
1 parent d2e5131
commit 442a539
Show file tree

Hide file tree

Showing 15 changed files with 611 additions and 861 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -15,4 +15,4 @@ python:
 build:
    os: ubuntu-22.04
    tools:
-      python: "3.8"
+      python: "3.10"
diff --git a/README.md b/README.md
@@ -4,6 +4,9 @@
 
 rocJPEG is a high performance JPEG decode SDK for AMD GPUs. Using the rocJPEG API, you can access the JPEG decoding features available on your GPU.
 
+>[!Note]
+>The published documentation is available at [rocJPEG](https://rocm.docs.amd.com/projects/rocJPEG/en/latest/) in an organized, easy-to-read format, with search and a table of contents. The documentation source files reside in the `docs` folder of this repository. As with all ROCm projects, the documentation is open source. For more information on contributing to the documentation, see [Contribute to ROCm documentation](https://rocm.docs.amd.com/en/latest/contribute/contributing.html)
+
 ## Supported JPEG chroma subsampling
 
 * YUV 4:4:4
@@ -15,7 +18,7 @@ rocJPEG is a high performance JPEG decode SDK for AMD GPUs. Using the rocJPEG AP
 ## Prerequisites
 
 * Linux distribution
-  * Ubuntu - `20.04` / `22.04` / `24.04`
+  * Ubuntu - `22.04` / `24.04`
   * RHEL - `8` / `9`
   * SLES - `15-SP5`
 
@@ -29,26 +32,29 @@ rocJPEG is a high performance JPEG decode SDK for AMD GPUs. Using the rocJPEG AP
 > [!IMPORTANT]
 > `sudo amdgpu-install --usecase=rocm`
 
-* Video Acceleration API (VA-API) Version `2.16.0+` - `Libva` is an implementation for VA-API
-   ```shell
-   sudo apt install libva-amdgpu-dev
-   ```
- > [!NOTE]
- > RPM Packages for `RHEL`/`SLES` - `libva-amdgpu-devel`
+* Video Acceleration API - `libva-amdgpu-dev` is an AMD implementation for VA-API
+  ```shell
+  sudo apt install libva-amdgpu-dev
+  ```
+> [!NOTE]
+> * RPM Packages for `RHEL`/`SLES` - `libva-amdgpu-devel`
+> * `libva-amdgpu` is strongly recommended over system `libva` as it is used for building mesa-amdgpu-va-driver
 
 * AMD VA Drivers
-   ```shell
-   sudo apt install libva2-amdgpu libva-amdgpu-drm2 libva-amdgpu-wayland2 libva-amdgpu-x11-2 mesa-amdgpu-va-drivers
-   ```
- > [!NOTE]
- > RPM Packages for `RHEL`/`SLES` - `libva-amdgpu mesa-amdgpu-va-drivers`
+  ```shell
+  sudo apt install libva2-amdgpu libva-amdgpu-drm2 libva-amdgpu-wayland2 libva-amdgpu-x11-2 mesa-amdgpu-va-drivers
+  ```
+> [!NOTE]
+> RPM Packages for `RHEL`/`SLES` - `libva-amdgpu mesa-amdgpu-va-drivers`
 
-* CMake `3.5` or later
+* CMake `3.10` or later
 
   ```shell
   sudo apt install cmake
   ```
-
+
+* AMD Clang++ Version 18.0.0 or later - installed with ROCm
+
 * pkg-config
 
   ```shell
@@ -67,7 +73,6 @@ rocJPEG is a high performance JPEG decode SDK for AMD GPUs. Using the rocJPEG AP
 >[!NOTE]
 >
 > * All package installs are shown with the `apt` package manager. Use the appropriate package manager for your operating system.
-> * To install rocJPEG with minimum requirements, follow the [quick-start](./docs/install/quick-start.rst) instructions
 
 ### Prerequisites setup script for Linux
 
@@ -90,7 +95,8 @@ The installation process uses the following steps:
 
 * Install ROCm `6.3.0` or later with [amdgpu-install](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/amdgpu-install.html) with `--usecase=rocm`
 
-* Use either [Package install](#package-install) or [Source install](#source-install) as described below.
+>[!IMPORTANT]
+> Use **either** [package install](#package-install) **or** [source install](#source-install) as described below.
 
 ### Package install
 
@@ -188,16 +194,3 @@ individual folders to build and run the samples.
 You can find rocJPEG Docker containers in our
 [GitHub repository](https://github.com/ROCm/rocJPEG/tree/develop/docker).
 
-## Documentation
-
-Run the following code to build our documentation locally.
-
-```shell
-cd docs
-pip3 install -r sphinx/requirements.txt
-python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
-```
-
-For more information on documentation builds, refer to the
-[Building documentation](https://rocm.docs.amd.com/en/latest/contribute/building.html)
-page.
diff --git a/docs/how-to/rocjpeg-decoding-a-jpeg-stream.rst b/docs/how-to/rocjpeg-decoding-a-jpeg-stream.rst
@@ -0,0 +1,151 @@
+.. meta::
+  :description: decoding a jpeg stream with rocJPEG
+  :keywords: rocJPEG, ROCm, API, documentation, decoding, jpeg
+
+
+********************************************************************
+Decoding a JPEG stream with rocJPEG
+********************************************************************
+
+rocJPEG provides two functions, ``rocJpegDecode()`` and ``rocJpegDecodeBatched()``, for decoding JPEG image. 
+
+.. code:: cpp
+
+  RocJpegStatus rocJpegDecode(
+    RocJpegHandle handle,
+    RocJpegStreamHandle jpeg_stream_handle,
+    const RocJpegDecodeParams *decode_params,
+    RocJpegImage *destination);
+
+  RocJpegStatus rocJpegDecodeBatched(
+    RocJpegHandle handle,
+    RocJpegStreamHandle *jpeg_stream_handles,
+    int batch_size,
+    const RocJpegDecodeParams *decode_params,
+    RocJpegImage *destinations);
+
+``rocJpegDecode()`` is used for decoding single images and ``rocJpegDecodeBatched()`` is used for decoding batches of JPEG images. ``rocJpegDecode()`` and ``rocJpegDecodeBatched()`` copy decoded images to a ``RocJpegImage`` struct.
+
+.. code:: cpp
+
+    typedef struct {
+      uint8_t* channel[ROCJPEG_MAX_COMPONENT];
+      uint32_t pitch[ROCJPEG_MAX_COMPONENT];
+    } RocJpegImage;
+
+``rocJpegDecodeBatched()`` behaves the same way as ``rocJpegDecode()`` except that ``rocJpegDecodeBatched()`` takes an array of stream handles and an array of decode parameters as input, decodes the batch of JPEG images, and stores the decoded images in an output array of destination images. 
+
+``rocJpegDecodeBatched()`` is suited for use on ASICs with multiple JPEG cores and is more efficient than multiple calls to ``rocJpegDecode()``. Choosing a batch size that is a multiple of available JPEG cores is recommended. 
+
+Memory has to be allocate to each channel of ``RocJpegImage``, including every channel of every ``RocJpegImage`` in the destination image array passed to ``rocJpegDecodeBatched()``. Use |hipmalloc|_ to allocate memory.
+
+.. |hipmalloc| replace:: ``hipMalloc()``
+.. _hipmalloc: https://rocm.docs.amd.com/projects/HIP/en/latest/how-to/virtual_memory.html
+
+For example:
+
+.. code:: cpp
+
+  // Allocate device memory for the decoded output image
+  RocJpegImage output_image = {};
+  RocJpegDecodeParams decode_params = {};
+  decode_params.output_format = ROCJPEG_OUTPUT_NATIVE;
+
+  // For this sample assuming the input image has a YUV420 chroma subsampling.
+  // For YUV420 subsampling, the native decoded output image would be NV12 (i.e., the rocJPegDecode API copies Y to first channel and UV (interleaved) to second channel of RocJpegImage)
+  output_image.pitch[1] = output_image.pitch[0] = widths[0];
+  hipError_t hip_status;
+  hip_status = hipMalloc(&output_image.channel[0], output_image.pitch[0] * heights[0]);
+  if (hip_status != hipSuccess) {
+    std::cerr << "Failed to allocate device memory for the first channel" << std::endl;
+    rocJpegStreamDestroy(rocjpeg_stream_handle);
+    rocJpegDestroy(handle);
+    return EXIT_FAILURE;
+  }
+
+  hip_status = hipMalloc(&output_image.channel[1], output_image.pitch[1] * (heights[0] >> 1));
+  if (hip_status != hipSuccess) {
+    std::cerr << "Failed to allocate device memory for the second channel" << std::endl;
+    hipFree((void *)output_image.channel[0]);
+    rocJpegStreamDestroy(rocjpeg_stream_handle);
+    rocJpegDestroy(handle);
+    return EXIT_FAILURE;
+  }
+
+  // Decode the JPEG stream
+  status = rocJpegDecode(handle, rocjpeg_stream_handle, &decode_params, &output_image);
+  if (status != ROCJPEG_STATUS_SUCCESS) {
+    std::cerr << "Failed to decode JPEG stream with error code: " << rocJpegGetErrorName(status) << std::endl;
+    hipFree((void *)output_image.channel[0]);
+    hipFree((void *)output_image.channel[1]);
+    rocJpegStreamDestroy(rocjpeg_stream_handle);
+    rocJpegDestroy(handle);
+    return EXIT_FAILURE;
+  }
+
+
+The behaviors of ``rocJpegDecode()`` and ``rocJpegDecodeBatched()`` depend on ``RocJpegOutputFormat`` and ``RocJpegDecodeParms``. 
+
+``RocJpegOutputFormat`` specifies the output format to be used to decode the JPEG image. It can be set to any one of these output formats:
+
+.. csv-table::
+  :header: "Output format", "Meaning"
+
+  "ROCJPEG_OUTPUT_NATIVE", "Return native unchanged decoded YUV image from the VCN JPEG deocder."
+  "ROCJPEG_OUTPUT_YUV_PLANAR", "Return in the YUV planar format."
+  "ROCJPEG_OUTPUT_Y", "Return the Y component only."
+  "ROCJPEG_OUTPUT_RGB", "Convert to interleaved RGB."
+  "ROCJPEG_OUTPUT_RGB_PLANAR", "Convert to planar RGB."
+
+``RocJpegOutputFormat`` is a member of the ``RocJpegDecodeParams`` struct. ``RocJpegDecodeParams`` defines the output format, crop rectangle, and target dimensions to use when decoding the image.
+
+.. code:: cpp
+
+  typedef struct {
+    RocJpegOutputFormat output_format; /**< Output data format. See RocJpegOutputFormat for description. */
+    struct {
+        int16_t left; /**< Left coordinate of the crop rectangle. */
+        int16_t top; /**< Top coordinate of the crop rectangle. */
+        int16_t right; /**< Right coordinate of the crop rectangle. */
+        int16_t bottom; /**< Bottom coordinate of the crop rectangle. */
+    } crop_rectangle; /**< Defines the region of interest (ROI) to be copied into the RocJpegImage output buffers. */
+    struct {
+        uint32_t width; /**< Target width of the picture to be resized. */
+        uint32_t height; /**< Target height of the picture to be resized. */
+    } target_dimension; /**< (future use) Defines the target width and height of the picture to be resized. Both should be even.
+                            If specified, allocate the RocJpegImage buffers based on these dimensions. */
+  } RocJpegDecodeParams;
+
+
+For example, consider a situation where ``RocJpegOutputFormat`` is set to ``ROCJPEG_OUTPUT_NATIVE``. Based on the chroma subsampling of the input image, ``rocJpegDecode()`` does one of the following:
+
+* For ``ROCJPEG_CSS_444`` and ``ROCJPEG_CSS_440``: writes Y, U, and V to the first, second, and third channels of ``RocJpegImage``.
+* For ``ROCJPEG_CSS_422``: writes YUYV (packed) to the first channel of ``RocJpegImage``.
+* For ``ROCJPEG_CSS_420``: writes Y to the first channel and UV (interleaved) to the second channel of ``RocJpegImage``.
+* For ``ROCJPEG_CSS_400``: writes Y to the first channel of ``RocJpegImage``.
+
+If ``RocJpegOutputFormat`` is set to ``ROCJPEG_OUTPUT_Y`` or   ``ROCJPEG_OUTPUT_RGB``, then ``rocJpegDecode()`` copies the output to the first channel of ``RocJpegImage``.
+
+If ``RocJpegOutputFormat`` is set to ``ROCJPEG_OUTPUT_YUV_PLANAR`` or ``ROCJPEG_OUTPUT_RGB_PLANAR``, the data is written to the corresponding channels of the ``RocJpegImage`` destination structure.
+
+The destination images must be large enough to store the output.
+
+Use |rocjpegimageinfo|_ to extract information and calculate the required memory sizes for the destination image following these guidelines:.
+
+.. |rocjpegimageinfo| replace:: ``rocJpegGetImageInfo()``
+.. _rocjpegimageinfo: ./rocjpeg-retrieve-image-info.html
+
+.. csv-table::
+  :header: "Output format", "Chroma subsampling", "Minimum size of destination.pitch[c]", "Minimum size of destination.channel[c]"
+
+  "ROCJPEG_OUTPUT_NATIVE", "ROCJPEG_CSS_444", "destination.pitch[c] = widths[c] for c = 0, 1, 2", "destination.channel[c] = destination.pitch[c] * heights[0] for c = 0, 1, 2"
+  "ROCJPEG_OUTPUT_NATIVE", "ROCJPEG_CSS_440", "destination.pitch[c] = widths[c] for c = 0, 1, 2", "destination.channel[0] = destination.pitch[0] * heights[0], destination.channel[c] = destination.pitch[c] * heights[0] / 2 for c = 1, 2"
+  "ROCJPEG_OUTPUT_NATIVE", "ROCJPEG_CSS_422", "destination.pitch[0] = widths[0] * 2", "destination.channel[0] = destination.pitch[0] * heights[0]"
+  "ROCJPEG_OUTPUT_NATIVE", "ROCJPEG_CSS_420", "destination.pitch[1] = destination.pitch[0] = widths[0]", "destination.channel[0] = destination.pitch[0] * heights[0], destination.channel[1] = destination.pitch[1] * (heights[0] >> 1)"
+  "ROCJPEG_OUTPUT_NATIVE", "ROCJPEG_CSS_400", "destination.pitch[0] = widths[0]", "destination.channel[0] = destination.pitch[0] * heights[0]"
+  "ROCJPEG_OUTPUT_YUV_PLANAR", "ROCJPEG_CSS_444, ROCJPEG_CSS_440, ROCJPEG_CSS_422, ROCJPEG_CSS_420", "destination.pitch[c] = widths[c] for c = 0, 1, 2", "destination.channel[c] = destination.pitch[c] * heights[c] for c = 0, 1, 2"
+  "ROCJPEG_OUTPUT_YUV_PLANAR", "ROCJPEG_CSS_400", "destination.pitch[0] = widths[0]", "destination.channel[0] = destination.pitch[0] * heights[0]"
+  "ROCJPEG_OUTPUT_Y", "Any of the supported chroma subsampling", "destination.pitch[0] = widths[0]", "destination.channel[0] = destination.pitch[0] * heights[0]"
+  "ROCJPEG_OUTPUT_RGB", "Any of the supported chroma subsampling", "destination.pitch[0] = widths[0] * 3", "destination.channel[0] = destination.pitch[0] * heights[0]"
+  "ROCJPEG_OUTPUT_RGB_PLANAR", "Any of the supported chroma subsampling", "destination.pitch[c] = widths[c] for c = 0, 1, 2", "destination.channel[c] = destination.pitch[c] * heights[c] for c = 0, 1, 2"
+
diff --git a/docs/how-to/rocjpeg-retrieve-image-info.rst b/docs/how-to/rocjpeg-retrieve-image-info.rst
@@ -0,0 +1,63 @@
+.. meta::
+  :description: retrieving image information with rocJPEG
+  :keywords: rocJPEG, ROCm, API, documentation, image information, jpeg
+
+
+********************************************************************
+Retrieving image information with rocJPEG
+********************************************************************
+
+Retrieving image information is done using ``rocJpegGetImageInfo()``. 
+
+.. code:: cpp
+
+    RocJpegStatus rocJpegGetImageInfo(
+      RocJpegHandle handle,
+      RocJpegStreamHandle jpeg_stream_handle,
+      uint8_t *num_components,
+      RocJpegChromaSubsampling *subsampling,
+      uint32_t *widths,
+      uint32_t *heights);
+
+``rocJpegGetImageInfo()`` takes the ``RocJpegHandle`` and a ``RocJpegStreamHandle`` as inputs, and returns the subsampling, number of components, and widths and heights of the components. These are passed to the ``subsampling``, ``num_components``, and ``widths`` and ``heights`` output parameters.
+
+The ``subsampling`` output parameter is a ``RocJpegChromaSubsampling`` enum. 
+
+.. code:: cpp
+
+    typedef enum {
+      ROCJPEG_CSS_444 = 0,
+      ROCJPEG_CSS_440 = 1,
+      ROCJPEG_CSS_422 = 2,
+      ROCJPEG_CSS_420 = 3,
+      ROCJPEG_CSS_411 = 4,
+      ROCJPEG_CSS_400 = 5,
+      ROCJPEG_CSS_UNKNOWN = -1
+    } RocJpegChromaSubsampling;
+
+Its value is set to the chroma subsampling retrieved from the image. 
+
+For example:
+
+.. code:: cpp
+
+  // Get the image info
+  uint8_t num_components;
+  RocJpegChromaSubsampling subsampling;
+  uint32_t widths[ROCJPEG_MAX_COMPONENT] = {};
+  uint32_t heights[ROCJPEG_MAX_COMPONENT] = {};
+
+  status = rocJpegGetImageInfo(handle, rocjpeg_stream_handle, &num_components, &subsampling, widths, heights);
+  if (status != ROCJPEG_STATUS_SUCCESS) {
+    std::cerr << "Failed to get image info with error code: " << rocJpegGetErrorName(status) << std::endl;
+    rocJpegStreamDestroy(rocjpeg_stream_handle);
+    rocJpegDestroy(handle);
+    return EXIT_FAILURE;
+  }
+
+
+``rocJpegGetImageInfo()`` is thread safe.
+
+.. note::
+
+  The VCN hardware-accelerated JPEG decoder in AMD GPUs only supports decoding JPEG images with ``ROCJPEG_CSS_444``, ``ROCJPEG_CSS_440``, ``ROCJPEG_CSS_422``, ``ROCJPEG_CSS_420``, and ``ROCJPEG_CSS_400`` chroma subsampling.