diff --git a/projects/rocjpeg/docs/.gitignore b/projects/rocjpeg/docs/.gitignore index 2f8fc8f6d1..1b3c55ba68 100644 --- a/projects/rocjpeg/docs/.gitignore +++ b/projects/rocjpeg/docs/.gitignore @@ -5,5 +5,4 @@ _static/ _templates/ _toc.yml docBin/ -_doxygen/ -index.md +_doxygen/ \ No newline at end of file diff --git a/projects/rocjpeg/docs/doxygen/Doxyfile b/projects/rocjpeg/docs/doxygen/Doxyfile index 667532d2ac..97a100a7a9 100644 --- a/projects/rocjpeg/docs/doxygen/Doxyfile +++ b/projects/rocjpeg/docs/doxygen/Doxyfile @@ -38,20 +38,20 @@ PROJECT_NAME = "rocJPEG" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = +PROJECT_NUMBER = "V0.1.0" # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = +PROJECT_BRIEF = "rocJPEG is a high performance JPEG decode SDK for AMD hardware." # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # the logo to the output directory. -PROJECT_LOGO = +PROJECT_LOGO = "../data/AMD-Logo-Doxygen.png" # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is @@ -829,7 +829,8 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../../src +INPUT = ../reference/index.md \ + ../../api/rocjpeg.h # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/projects/rocjpeg/docs/how-to/using-rocjpeg.rst b/projects/rocjpeg/docs/how-to/using-rocjpeg.rst new file mode 100644 index 0000000000..2f32eeb275 --- /dev/null +++ b/projects/rocjpeg/docs/how-to/using-rocjpeg.rst @@ -0,0 +1,40 @@ +.. meta:: + :description: Using rocJPEG + :keywords: parse JPEG, parse, decode, JPEG decoder, JPEG decoding, rocJPEG, AMD, ROCm + +******************************************************************** +Using rocJPEG +******************************************************************** + +To learn how to use the rocJPEG SDK library, follow these instructions: + +1. API overview +==================================================== + +All rocJPEG APIs are exposed in the header file ``rocjpeg.h``. You can find +this file in the `api` folder in the rocJPEG repository. + +2. Create a decoder +==================================================== + +``rocJpegCreate()`` creates an instance of the hardware JPEG decoder object and provides you +with a handle upon successful creation. The decoder handle +returned by ``rocJpegCreate()`` must be retained for the entire decode session because the +handle is passed along with the other decoding APIs. + +3. Retrieve the image info +==================================================== +``rocJpegGetImageInfo()`` retrieves the image info, including channel, width and height of each component, and chroma subsampling. + +4. Decode a JPEG stream +==================================================== +``rocJpegDecode()`` decodes single image based on the backend used to create the rocJpeg handle in rocJpegCreate API. +Destination buffers should be large enough to be able to store output of specified format. These buffers should be pre-allocted by the user in the device memories. +For each color plane (channel) sizes could be retrieved for image using ``rocJpegGetImageInfo()`` API +and minimum required memory buffer for each plane is plane_height * plane_pitch where plane_pitch >= plane_width for +planar output formats and plane_pitch >= plane_width * num_components for interleaved output format. + +5. Destroy the decoder +==================================================== + +You must call the ``rocJpegDestroy()`` to destroy the session and free up resources. \ No newline at end of file diff --git a/projects/rocjpeg/docs/index.rst b/projects/rocjpeg/docs/index.rst new file mode 100644 index 0000000000..03ff7bc5d8 --- /dev/null +++ b/projects/rocjpeg/docs/index.rst @@ -0,0 +1,43 @@ +.. meta:: + :description: rocJPEG documentation and API reference library + :keywords: rocJPEG, ROCm, API, documentation + +******************************************************************** +rocJPEG documentation +******************************************************************** + +rocJPEG provides APIs and samples that you can use to easily access the JPEG decoding +features of your media engines (VCNs). It also allows interoperability with other compute engines on +the GPU using Video Acceleration API (VA-API)/HIP. To learn more, see :doc:`what-is-rocJPEG` + +You can access rocJPEG code on our `GitHub repository `_. + +Our documentation is structured as follows: + +.. grid:: 2 + :gutter: 3 + + .. grid-item-card:: Install + + * :doc:`Quick-start <./install/quick-start>` + * :doc:`rocJPEG installation <./install/install>` + + .. grid-item-card:: API reference + + * :doc:`API library <../doxygen/html/files>` + * :doc:`Functions <../doxygen/html/globals>` + * :doc:`Data structures <../doxygen/html/annotated>` + + .. grid-item-card:: How to + + * :doc:`Use rocJPEG ` + + .. grid-item-card:: Tutorials + + * `GitHub samples `_ + +To contribute to the documentation, refer to +`Contributing to ROCm `_. + +You can find licensing information on the +`Licensing `_ page. diff --git a/projects/rocjpeg/docs/install/install.rst b/projects/rocjpeg/docs/install/install.rst new file mode 100644 index 0000000000..b944f6282b --- /dev/null +++ b/projects/rocjpeg/docs/install/install.rst @@ -0,0 +1,238 @@ +.. meta:: + :description: Install rocJPEG + :keywords: install, rocJPEG, AMD, ROCm + +******************************************************************** +Installation +******************************************************************** + +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. + +Tested configurations +======================================== + +* Linux + + * Ubuntu: 20.04/22.04 + * RHEL: 8/9 + * SLES: 15-SP5 + +* ROCm + + * rocm-core: 6.1.0.60100-65 + * amdgpu-core: 1:6.1.60100-1744891 + +* rocJPEG Setup Script: V1.0 + +Supported JPEG chroma subsampling +======================================== + +* YUV 4:4:4 +* YUV 4:2:2 +* YUV 4:2:0 +* YUV 4:0:0 + +Prerequisites +======================================== + +* Linux distribution + + * Ubuntu: 20.04/22.04 + * RHEL: 8/9 + * SLES: 15-SP5 + +* `ROCm-supported hardware `_ + (``gfx908`` or higher is required) + +* Install ROCm 6.1.0 or later with + `amdgpu-install `_ + + * Run: ``--usecase=rocm`` + * To install rocJPEG with minimum requirements, follow the :doc:`quick-start instructions <./quick-start>` + +* AMD multimedia packages + + .. code:: shell + + sudo apt install libva-amdgpu-dev libdrm-amdgpu1 mesa-amdgpu-va-drivers + +* CMake 3.5 or later + + .. code:: shell + + sudo apt install cmake + +* `pkg-config `_ + + .. code:: shell + + sudo apt install pkg-config + +* If using Ubuntu 22.04, you must install ``libstdc++-12-dev`` + + .. code:: shell + + sudo apt install libstdc++-12-dev + +.. note:: + + All package installs are shown with the ``apt`` package manager. Use the appropriate package + manager for your operating system. + +Prerequisites setup script +---------------------------------------------------------------------------------------------------------- + +For your convenience, we provide the setup script, +`rocJPEG-setup.py `_, +which installs all required dependencies. Run this script only once. + +.. code:: shell + + python rocJPEG-setup.py --rocm_path [ ROCm Installation Path - optional (default:/opt/rocm)] + +Installation instructions +======================================== + +To install rocJPEG, you can use :ref:`package-install` or +:ref:`source-install`. + +.. _package-install: + +Package install +------------------------------------------------------------------------------------------------------------ + +To install rocJPEG runtime, development, and test packages, run the line of code for your operating +system. + +.. tab-set:: + + .. tab-item:: Ubuntu + + .. code:: shell + + sudo apt install rocjpeg rocjpeg-dev rocjpeg-test + + .. tab-item:: RHEL + + .. code:: shell + + sudo yum install rocjpeg rocjpeg-devel rocjpeg-test + + .. tab-item:: SLES + + .. code:: shell + + sudo zypper install rocjpeg rocjpeg-devel rocjpeg-test + +.. note:: + + Package install auto installs all dependencies. + +* Runtime package: ``rocjpeg`` only provides the rocjpeg library ``librocdecode.so`` +* Development package: ``rocjpeg-dev``or ``rocjpeg-devel`` provides the library, header files, and samples +* Test package: ``rocjpeg-test`` provides CTest to verify installation + +.. _source-install: + +Source install +------------------------------------------------------------------------------------------------------------ + +To build rocJPEG from source, run: + +.. code:: shell + + git clone https://github.com/ROCm/rocJPEG.git + cd rocJPEG + mkdir build && cd build + cmake ../ + make -j8 + sudo make install + +Run tests: + +.. code:: shell + + make test + +To run tests with verbose option, use ``make test ARGS="-VV"``. + +Make package: + +.. code:: shell + + sudo make package + +Verify installation +======================================== + +The installer copies: + +* Libraries into ``/opt/rocm/lib`` +* Header files into ``/opt/rocm/include/rocjpeg`` +* Samples folder into ``/opt/rocm/share/rocjpeg`` +* Documents folder into ``/opt/rocm/share/doc/rocjpeg`` + +To verify your installation using a sample application, run: + +.. code:: shell + + mkdir rocjpeg-sample && cd rocjpeg-sample + cmake /opt/rocm/share/rocjpeg/samples/videoDecode/ + make -j8 + ./jpegdecode -i /opt/rocm/share/rocjpeg/images/ + +To verify your installation using the ``rocjpeg-test`` package, run: + +.. code:: shell + + mkdir rocjpeg-test && cd rocjpeg-test + cmake /opt/rocm/share/rocjpeg/test/ + ctest -VV + +This test package installs the CTest module. + +Samples +======================================== + +You can access samples to decode your JPEG images in our +`GitHub repository `_. Refer to the +individual folders to build and run the samples. + +Docker +======================================== + +You can find rocJPEG Docker containers in our +`GitHub repository `_. + +Documentation +======================================== + +Run the following code to build our documentation locally. + +.. code:: 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 +:doc:`Building documentation ` page. + +Hardware capabilities +=================================================== + +The following table shows the capabilities of the VCN and JPEG cores for each supported GPU +architecture. + +.. csv-table:: + :header: "GPU Architecture", "VCN Generation", "Number of VCNs", "Number of JPEG cores per VCN", "Max width, Max height" + + "gfx908 - MI1xx", "VCN 2.5.0", "2", "1", "4096, 4096" + "gfx90a - MI2xx", "VCN 2.6.0", "2", "1", "4096, 4096" + "gfx940 - MI3xx", "VCN 3.0", "3", "8", "4096, 4096" + "gfx941 - MI3xx", "VCN 3.0", "4", "8", "4096, 4096" + "gfx942 - MI3xx", "VCN 3.0", "4", "8", "4096, 4096" + "gfx1030, gfx1031, gfx1032 - Navi2x", "VCN 3.x", "2", "1", "4096, 4096" + "gfx1100, gfx1102 - Navi3x", "VCN 4.0", "2", "1", "4096, 4096" + "gfx1101 - Navi3x", "VCN 4.0", "1", "1", "4096, 4096" diff --git a/projects/rocjpeg/docs/install/quick-start.rst b/projects/rocjpeg/docs/install/quick-start.rst new file mode 100644 index 0000000000..42ff0451c4 --- /dev/null +++ b/projects/rocjpeg/docs/install/quick-start.rst @@ -0,0 +1,42 @@ +.. meta:: + :description: Install rocJPEG + :keywords: install, rocJPEG, AMD, ROCm + +******************************************************************** +rocJPEG quick-start installation +******************************************************************** + +To install the rocJPEG runtime with minimum requirements, follow these steps: + +1. Install core ROCm components (ROCm 6.1.0 or later) using the +:doc:`native package manager ` +installation instructions. + +* Register repositories +* Register kernel-mode driver +* Register ROCm packages +* Install kernel driver (``amdgpu-dkms``)--only required on bare metal install. Docker runtime uses the + base ``dkms`` package irrespective of the version installed. + +2. Install rocJPEG runtime package. rocJPEG only provides the ``librocjpeg.so`` library (the +runtime package only installs the required core dependencies). + +.. tab-set:: + + .. tab-item:: Ubuntu + + .. code:: shell + + sudo apt install rocjpeg + + .. tab-item:: RHEL + + .. code:: shell + + sudo yum install rocjpeg + + .. tab-item:: SLES + + .. code:: shell + + sudo zypper install rocjpeg diff --git a/projects/rocjpeg/docs/reference/index.md b/projects/rocjpeg/docs/reference/index.md new file mode 100644 index 0000000000..335d201953 --- /dev/null +++ b/projects/rocjpeg/docs/reference/index.md @@ -0,0 +1,14 @@ + + + + + + +# API reference + +This section provides technical descriptions and important information about the different rocJPEG +APIs and library components. + +* {doc}`Library <../doxygen/html/files>` +* {doc}`Functions <../doxygen/html/globals>` +* {doc}`Data structures <../doxygen/html/annotated>` diff --git a/projects/rocjpeg/docs/sphinx/_toc.yml.in b/projects/rocjpeg/docs/sphinx/_toc.yml.in index f3e4314ac5..923434af0f 100644 --- a/projects/rocjpeg/docs/sphinx/_toc.yml.in +++ b/projects/rocjpeg/docs/sphinx/_toc.yml.in @@ -2,9 +2,36 @@ defaults: numbered: False root: index subtrees: -- caption: API Reference +- entries: + - file: what-is-rocJPEG.rst + title: What is rocJPEG? + +- caption: Install entries: - - file: doxygen/html/index + - file: install/quick-start.rst + title: Quick-start + - file: install/install.md + title: Installation guide + +- caption: API reference + entries: + - file: doxygen/html/files + title: API library + - file: doxygen/html/globals + title: Functions + - file: doxygen/html/annotated + title: Data structures + +- caption: How to + entries: + - file: how-to/using-rocjpeg.rst + title: Use rocJPEG + +- caption: Tutorials + entries: + - url: https://github.com/ROCm/rocJPEG/tree/develop/samples + title: GitHub samples + - caption: About entries: - - file: license + - file: license.md diff --git a/projects/rocjpeg/docs/what-is-rocJPEG.rst b/projects/rocjpeg/docs/what-is-rocJPEG.rst new file mode 100644 index 0000000000..ddcb3ce955 --- /dev/null +++ b/projects/rocjpeg/docs/what-is-rocJPEG.rst @@ -0,0 +1,23 @@ +.. meta:: + :description: What is rocJPEG? + :keywords: video decoding, rocJPEG, AMD, ROCm + +******************************************************************** +What is rocJPEG? +******************************************************************** + +AMD GPUs contain one or more media engines (VCNs). Each VCN has one or more JPEG engines +that provide fully accelerated, hardware-based JPEG decoding. Hardware decoders consume lower power +than CPU-based decoders. Dedicated hardware decoders offload decoding tasks from the CPU, boosting +overall decoding throughput. With proper power management, decoding on hardware decoders can lower the +overall system power consumption and improve decoding performance. + +Using the rocJPEG API, you can decode compressed JPEG streams while keeping the resulting YUV +images in video memory. With decoded images in video memory, you can run image post-processing +using ROCm HIP, thereby avoiding unnecessary data copies via PCIe bus. You can post-process images +using scaling or color conversion and augmentation kernels (on a GPU or host) in a format for +GPU/CPU-accelerated inferencing and training. + +In addition, you can use the rocJPEG API to create multiple instances of JPEG decoder based on the +number of available VCNs/JPEG engines in a GPU device. By configuring the decoder for a device, all available +VCNs can be used seamlessly for decoding a batch of JPEG streams in parallel. \ No newline at end of file