made changes to installation and landing pages (#445)

* initial commit of changes to the installation and landing pages * deleted original install; fixed the toc; fixed typos * fixed some wording issues; fixed some formatting issues * adding back install.rst to try to fix the conflict --------- Co-authored-by: Aryan Salmanpour <aryan.salmanpour@amd.com> [ROCm/rocdecode commit: 6cc30f12a4]
2024-11-12 10:40:37 -05:00
@@ -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 `<https://github.com/ROCm/rocDecode>`_.
-
+The rocDecode public repository is located at `https://github.com/ROCm/rocDecode <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 <https://github.com/ROCm/rocDecode/tree/develop/docker>`_

 .. grid:: 2
  :gutter: 3

-  .. grid-item-card:: Tutorials
+  .. grid-item-card:: Conceptual

-    * `GitHub samples <https://github.com/ROCm/rocDecode/tree/develop/samples>`_
+    * :doc:`Video decoding pipeline <./conceptual/video-decoding-pipeline>`

  .. grid-item-card:: How to

-    * :doc:`Using rocDecode <how-to/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 <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.

@@ -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 <rocm-install-on-linux:how-to/native-install/index>`
-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
@@ -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 <https://github.com/ROCm/rocDecode/blob/develop/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
+
@@ -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
@@ -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 <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html>`_.
+
+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 <https://github.com/ROCm/rocDecode/blob/develop/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 
@@ -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"
@@ -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
@@ -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:
@@ -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 <https://github.com/ROCm/rocDecode/tree/develop/samples>`_.
+
+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
+
+
@@ -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.