Add initial support for rocJPEG documentation (#9)
[ROCm/rocjpeg commit: 3c803847f7]
Этот коммит содержится в:
Aryan Salmanpour
коммит произвёл
GitHub
GitHub
родитель
74b4963c90
Коммит
bd2767ccab
@@ -5,5 +5,4 @@ _static/
|
||||
_templates/
|
||||
_toc.yml
|
||||
docBin/
|
||||
_doxygen/
|
||||
index.md
|
||||
_doxygen/
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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 <https://github.com/ROCm/rocJPEG>`_.
|
||||
|
||||
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 <how-to/using-rocjpeg>`
|
||||
|
||||
.. grid-item-card:: Tutorials
|
||||
|
||||
* `GitHub samples <https://github.com/ROCm/rocJPEG/tree/develop/samples>`_
|
||||
|
||||
To contribute to the documentation, refer to
|
||||
`Contributing to ROCm <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.
|
||||
|
||||
You can find licensing information on the
|
||||
`Licensing <https://rocm.docs.amd.com/en/latest/about/license.html>`_ page.
|
||||
@@ -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 <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html>`_
|
||||
(``gfx908`` or higher is required)
|
||||
|
||||
* Install ROCm 6.1.0 or later with
|
||||
`amdgpu-install <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/amdgpu-install.html>`_
|
||||
|
||||
* 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 <https://en.wikipedia.org/wiki/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 <https://github.com/ROCm/rocJPEG/blob/develop/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 <https://github.com/ROCm/rocJPEG/tree/develop/samples>`_. Refer to the
|
||||
individual folders to build and run the samples.
|
||||
|
||||
Docker
|
||||
========================================
|
||||
|
||||
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.
|
||||
|
||||
.. 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 <rocm:contribute/building>` 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"
|
||||
@@ -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 <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 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
|
||||
@@ -0,0 +1,14 @@
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="description" content="rocJPEG API reference">
|
||||
<meta name="keywords" content="API reference, rocJPEG, AMD, ROCm">
|
||||
</head>
|
||||
|
||||
# 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>`
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
Ссылка в новой задаче
Block a user