diff --git a/projects/rocdecode/docs/index.rst b/projects/rocdecode/docs/index.rst index f320567b49..959c2044a8 100644 --- a/projects/rocdecode/docs/index.rst +++ b/projects/rocdecode/docs/index.rst @@ -10,42 +10,40 @@ rocDecode provides APIs, utilities, and samples that you can use to easily acces 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-rocDecode` -The code is open and hosted at ``_. - +The rocDecode public repository is located at `https://github.com/ROCm/rocDecode `_. .. grid:: 2 :gutter: 3 .. grid-item-card:: Install - * :doc:`Quick start <./install/quick-start>` - * :doc:`rocDecode installation <./install/install>` - - -The documentation is structured as follows: + * :doc:`Installing rocDecode with the package installer <./install/rocDecode-package-install>` + * :doc:`Building and installing rocDecode from source code <./install/rocDecode-build-and-install>` + * `rocDecode Docker containers `_ .. grid:: 2 :gutter: 3 - .. grid-item-card:: Tutorials + .. grid-item-card:: Conceptual - * `GitHub samples `_ + * :doc:`Video decoding pipeline <./conceptual/video-decoding-pipeline>` .. grid-item-card:: How to - * :doc:`Using rocDecode ` + * :doc:`Using rocDecode <./how-to/using-rocdecode>` - .. grid-item-card:: Conceptual + .. grid-item-card:: Samples + + * :doc:`rocDecode samples <./tutorials/rocDecode-samples>` - * :doc:`Video decoding pipeline <./conceptual/video-decoding-pipeline>` - .. grid-item-card:: Reference + * :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>` - To contribute to the documentation, refer to `Contributing to ROCm `_. diff --git a/projects/rocdecode/docs/install/quick-start.rst b/projects/rocdecode/docs/install/quick-start.rst deleted file mode 100644 index 4d33f2a76b..0000000000 --- a/projects/rocdecode/docs/install/quick-start.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. meta:: - :description: Install rocDecode - :keywords: install, rocDecode, AMD, ROCm - -******************************************************************** -rocDecode quick start installation -******************************************************************** - -To install the rocDecode 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 rocDecode runtime package. rocDecode only provides the ``librocdecode.so`` library (the -runtime package only installs the required core dependencies). - -.. tab-set:: - - .. tab-item:: Ubuntu - - .. code:: shell - - sudo apt install rocdecode - - .. tab-item:: RHEL - - .. code:: shell - - sudo yum install rocdecode - - .. tab-item:: SLES - - .. code:: shell - - sudo zypper install rocdecode diff --git a/projects/rocdecode/docs/install/rocDecode-build-and-install.rst b/projects/rocdecode/docs/install/rocDecode-build-and-install.rst new file mode 100644 index 0000000000..288b334cf8 --- /dev/null +++ b/projects/rocdecode/docs/install/rocDecode-build-and-install.rst @@ -0,0 +1,55 @@ +.. meta:: + :description: Build and install rocDecode with the source code + :keywords: install, building, rocDecode, AMD, ROCm, source code, developer + +******************************************************************** +Building and installing rocDecode from source code +******************************************************************** + +If you will be contributing to the rocDecode code base, or if you want to preview new features, build rocDecode from its source code. + +If you will not be previewing features or contributing to the code base, use the :doc:`package installers <./rocDecode-package-install>` to install rocDecode. + +Before building rocDecode, use `rocDecode-setup.py `_ to install all the required prerequisites: + +.. code:: shell + + python3 rocDecode-setup.py [--rocm_path ROCM_INSTALLATION_PATH; default=/opt/rocm] + [--runtime {ON|OFF}; default=ON] + [--developer {ON|OFF}; default=OFF] + +.. note:: + + Never run ``rocDecode-setup.py`` with ``--runtime OFF``. + + ``--developer ON`` is required to use the code samples. + +Build and install rocDecode using the following commands: + +.. code:: shell + + git clone https://github.com/ROCm/rocDecode.git + cd rocDecode + mkdir build && cd build + cmake ../ + make -j8 + sudo make install + +After installation, the rocDecode libraries will be copied to ``/opt/rocm/lib`` and the rocDecode header files will be copied to ``/opt/rocm/include/rocdecode``. + +Build and install the rocDecode test module. This module is required if you'll be using the rocDecode samples, and can only be installed if ``rocDecode-setup.py`` was run with ``--developer ON``. + +.. code:: shell + + mkdir rocdecode-test && cd rocdecode-test + cmake /opt/rocm/share/rocdecode/test/ + ctest -VV + +Run ``make test`` to test your build. To run the test with the verbose option, run ``make test ARGS="-VV"``. + +To create a package installer for rocDecode, run: + +.. code:: shell + + sudo make package + diff --git a/projects/rocdecode/docs/install/rocDecode-package-install.rst b/projects/rocdecode/docs/install/rocDecode-package-install.rst new file mode 100644 index 0000000000..66ce6d8148 --- /dev/null +++ b/projects/rocdecode/docs/install/rocDecode-package-install.rst @@ -0,0 +1,67 @@ +.. meta:: + :description: Installing rocDecode with the package installer + :keywords: install, rocDecode, AMD, ROCm, basic, development, package + +******************************************************************** +Installing rocDecode with the package installer +******************************************************************** + +Three rocDecode packages are available: + +* ``rocdecode``: The rocDecode runtime package. This is the basic rocDecode package. It must always be installed. +* ``rocdecode-dev``: The rocDecode development package. This package installs a full suite of libraries, header files, and samples. This package needs to be installed to use the rocDecode samples. +* ``rocdecode-test``: A test package that provides a CTest to verify the installation. This package needs to be installed to use the rocDecode samples. + +All the required prerequisites are installed when the package installation method is used. + + +Basic installation +======================================== + +Use the following commands to install only the rocDecode runtime package: + +.. tab-set:: + + .. tab-item:: Ubuntu + + .. code:: shell + + sudo apt install rocdecode + + .. tab-item:: RHEL + + .. code:: shell + + sudo yum install rocdecode + + .. tab-item:: SLES + + .. code:: shell + + sudo zypper install rocdecode + + +Complete installation +======================================== + +Use the following commands to install ``rocdecode``, ``rocdecode-dev``, and ``rocdecode-test``: + +.. tab-set:: + + .. tab-item:: Ubuntu + + .. code:: shell + + sudo apt install rocdecode rocdecode-dev rocdecode-test + + .. tab-item:: RHEL + + .. code:: shell + + sudo yum install rocdecode rocdecode-devel rocdecode-test + + .. tab-item:: SLES + + .. code:: shell + + sudo zypper install rocdecode rocdecode-devel rocdecode-test diff --git a/projects/rocdecode/docs/install/rocDecode-prerequisites.rst b/projects/rocdecode/docs/install/rocDecode-prerequisites.rst new file mode 100644 index 0000000000..5c27827f57 --- /dev/null +++ b/projects/rocdecode/docs/install/rocDecode-prerequisites.rst @@ -0,0 +1,37 @@ +.. meta:: + :description: rocDecode Installation Prerequisites + :keywords: install, rocDecode, AMD, ROCm, prerequisites, dependencies, requirements + +******************************************************************** +rocDecode prerequisites +******************************************************************** + +rocDecode requires ROCm 6.1 or later running on `accelerators based on the CDNA architecture `_. + +ROCm must be installed using the [AMDGPU installer](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/amdgpu-install.html) with the ``rocm`` usecase: + +.. code:: shell + + sudo amdgpu-install --usecase=rocm + +rocDecode can be installed on the following Linux environments: + +* Ubuntu 20.04, 22.04 +* RHEL 8 or 9 +* SLES: 15-SP5 + +The following prerequisites are installed by the package installer. If you are building and installing using the source code, use the `rocDecode-setup.py `_ to install these prerequisites. + +.. note:: + + To use the rocDecode samples, the ``rocdecode``, ``rocdecode-dev``, and ``rocdecode-test`` packages need to be installed. + + If you're installing using the rocDecode source code, the ``rocDecode-setup.py`` script must be run with ``--developer`` set to ``ON``. + +* Libva, an implementation for Video Acceleration API (VA-API) +* AMD VA Drivers +* CMake version 3.5 or later +* Clang Version 5.0.1 or later +* pkg-config +* FFmpeg runtime and headers +* libstdc++-12-dev for installations on Ubuntu 22.04 diff --git a/projects/rocdecode/docs/reference/rocDecode-formats-and-architectures.rst b/projects/rocdecode/docs/reference/rocDecode-formats-and-architectures.rst new file mode 100644 index 0000000000..de84f24beb --- /dev/null +++ b/projects/rocdecode/docs/reference/rocDecode-formats-and-architectures.rst @@ -0,0 +1,27 @@ +.. meta:: + :description: rocDecode supported codex and hardware capabilities + :keywords: install, rocDecode, AMD, ROCm, GPU, codec, VCN + +******************************************************************** +rocDecode supported codecs and hardware capabilities +******************************************************************** + +rocDecode supports the following codecs: + +* H.265 (HEVC): 8 bit and 10 bit +* H.264 (AVC): 8 bit +* AV1: 8 bit and 10 bit + +The following table shows the codec support and capabilities of the VCN for each supported GPU +architecture: + +.. csv-table:: + :header: "GPU Architecture", "VCN Generation", "Number of VCNs", "H.265/HEVC", "Max width, Max height - H.265", "H.264/AVC", "Max width, Max height - H.264" + + "gfx908 - MI1xx", "VCN 2.5.0", "2", "Yes", "4096, 2176", "Yes", "4096, 2160" + "gfx90a - MI2xx", "VCN 2.6.0", "2", "Yes", "4096, 2176", "Yes", "4096, 2160" + "gfx940, gfx942 - MI3xx", "VCN 3.0", "3", "Yes", "7680, 4320", "Yes", "4096, 2176" + "gfx941 - MI3xx", "VCN 3.0", "4", "Yes", "7680, 4320", "Yes", "4096, 2176" + "gfx1030, gfx1031, gfx1032 - Navi2x", "VCN 3.x", "2", "Yes", "7680, 4320", "Yes", "4096, 2176" + "gfx1100, gfx1102 - Navi3x", "VCN 4.0", "2", "Yes", "7680, 4320", "Yes", "4096, 2176" + "gfx1101 - Navi3x", "VCN 4.0", "1", "Yes", "7680, 4320", "Yes", "4096, 2176" \ No newline at end of file diff --git a/projects/rocdecode/docs/reference/rocDecode-tested-configurations.rst b/projects/rocdecode/docs/reference/rocDecode-tested-configurations.rst new file mode 100644 index 0000000000..eeb6f16049 --- /dev/null +++ b/projects/rocdecode/docs/reference/rocDecode-tested-configurations.rst @@ -0,0 +1,24 @@ +.. 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 \ No newline at end of file diff --git a/projects/rocdecode/docs/sphinx/_toc.yml.in b/projects/rocdecode/docs/sphinx/_toc.yml.in index 3f3ab5f837..e73ca8b775 100644 --- a/projects/rocdecode/docs/sphinx/_toc.yml.in +++ b/projects/rocdecode/docs/sphinx/_toc.yml.in @@ -8,15 +8,21 @@ subtrees: - caption: Install entries: - - file: install/quick-start.rst - title: Quick start - - file: install/install.md - title: Installation guide + - file: install/prerequisites.rst + title: rocDecode prerequisites + - file: install/rocDecode-package-install.rst + title: Installing rocDecode with the package installer + - file: install/rocDecode-build-and-install.rst + title: Installing rocDecode from its source code + - url: https://github.com/ROCm/rocDecode/tree/develop/docker + title: rocDecode Docker containers -- caption: Tutorials +- caption: Samples entries: + - file: tutorials/rocDecode-samples.rst + title: rocDecode samples - url: https://github.com/ROCm/rocDecode/tree/develop/samples - title: GitHub samples + title: rocDecode samples on GitHub - caption: How to entries: @@ -30,12 +36,16 @@ subtrees: - caption: Reference entries: + - 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: API library + title: rocDecode API library - file: doxygen/html/globals - title: Functions + title: rocDecode functions - file: doxygen/html/annotated - title: Data structures + title: rocDecode data structures - caption: About entries: diff --git a/projects/rocdecode/docs/tutorials/rocDecode-samples.rst b/projects/rocdecode/docs/tutorials/rocDecode-samples.rst new file mode 100644 index 0000000000..8c9a6a8314 --- /dev/null +++ b/projects/rocdecode/docs/tutorials/rocDecode-samples.rst @@ -0,0 +1,29 @@ +.. meta:: + :description: rocDecode Sample Prerequisites + :keywords: install, rocDecode, AMD, ROCm, samples, prerequisites, dependencies, requirements + +******************************************************************** +rocDecode samples +******************************************************************** + +rocDecode samples are available in the `rocDecode GitHub repository `_. + +All three rocDecode packages, ``rocDecode``, ``rocdecode-dev``, and ``rocdecode-test``, must be installed to use the rocDecode samples. + +If you're using a :doc:`package installer <./install/rocDecode-package-install>`, install ``rocdecode``, ``rocdecode-dev``, and ``rocdecode-test``. + +If you're building and installing rocDecode from its :doc:`source code <../install/rocDecode-build-and-install>`, ``rocDecode-setup.py`` needs to be run with ``--developer`` set to ``ON``: + +.. code:: cpp + + python3 rocDecode-setup.py --developer ON + +The rocDecode-test package needs to be built and installed as well: + +.. code:: shell + + mkdir rocdecode-test && cd rocdecode-test + cmake /opt/rocm/share/rocdecode/test/ + ctest -VV + + diff --git a/projects/rocdecode/docs/what-is-rocDecode.rst b/projects/rocdecode/docs/what-is-rocDecode.rst index 7768818315..30a51fcde3 100644 --- a/projects/rocdecode/docs/what-is-rocDecode.rst +++ b/projects/rocdecode/docs/what-is-rocDecode.rst @@ -14,7 +14,7 @@ consumption and improve decoding performance. Using the rocDecode API, you can decode compressed video streams while keeping the resulting YUV frames in video memory. With decoded frames in video memory, you can run video post-processing -using ROCm HIP, thereby avoiding unnecessary data copies via PCIe bus. You can post-process video +using ROCm HIP, thereby avoiding unnecessary data copies via the PCIe bus. You can post-process video frames using scaling or color conversion and augmentation kernels (on a GPU or host) in a format for GPU/CPU-accelerated inferencing and training.