Documentation - 6.1 Updates (Lisa edits) (#260)
* Update video-decoding-pipeline.md changed image alignment to left from center * Update Create-a-decoder-using-rocDecCreateDecoder().md language edits * Update Create-parser-object-using-rocDecCreateVideoParser().md Language edits * Update Create-parser-object-using-rocDecCreateVideoParser().md * Update Create-parser-object-using-rocDecCreateVideoParser().md * Update Create-parser-object-using-rocDecCreateVideoParser().md * Update Create-parser-object-using-rocDecCreateVideoParser().md * Update Create-parser-object-using-rocDecCreateVideoParser().md expanded SEI * Update Decode-the-frame-using-rocDecDecodeFrame().md language edits * Update Destroy-the-decoder.md * Update Decode-the-frame-using-rocDecDecodeFrame().md * Update Destroy-the-parser-using-rocDecDestroyVideoParser().md * Update Parse-video-data-using-rocDecParseVideoData().md language and spacing edits * Update Prepare-the-decoded-frame-for-further-processing.md language and spacing edits * Update Query-decode-capabilities-using-rocDecGetDecoderCaps().md Language and spacing edits. * Update Query-the-decoding-status.md language edits and spacing * Update Reconfigure-the-decorder.md language edits and spacing fixes * Update Use-rocDecode-API.md language and spacing edits * Update Use-rocDecode-API.md * Update Destroy-the-decoder.md updated to RocDecoder * Update Parse-video-data-using-rocDecParseVideoData().md Added link for callback * Update Reconfigure-the-decorder.md Corrected to RocDecoder * Delete docs/tutorial directory Tutorial not required for the user guide. * Add files via upload * Delete docs/data/VideoDecoderPipeline.PNG * Update video-decoding-pipeline.md * Update video-decoding-pipeline.md * Update video-decoding-pipeline.md * Update README.md * resolve conflicts * Update video-decoding-pipeline.md * Update video-decoding-pipeline.md * Update video-decoding-pipeline.md * Update install.md * Update install.md Minor language edits. * Update install.md * Update install.md * Update install.md * Update install.md * Update README.md Updated link to https://github.com/ROCm/rocDecode/blob/develop/rocDecode-setup.py * Update _toc.yml.in * Update index.md * Update index.md * Update index.md corrections to index.md * Update index.md * Update index.md * Create index.md * Update index.md Updated for installation and how to. Reference has header files. Need confirmation. * Update index.md * Update index.md Changed AMD's rocDecode SDK Library to rocDecode SDK * Update what-is-rocDecode.md * Update _toc.yml.in * Update _toc.yml.in * Update _toc.yml.in * Update _toc.yml.in * Update _toc.yml.in * Update _toc.yml.in * Update index.md * Update index.md * Update index.md * Update index.md * Docs - Update config * Docs - yml updates * Docs - Updates * Update _toc.yml.in * Update _toc.yml.in * Update _toc.yml.in * Update what-is-rocDecode.md * Update _toc.yml.in * Update what-is-rocDecode.md * Update what-is-rocDecode.md Added installation content * Update _toc.yml.in * Update install.md changed heading to Installation * Update index.md * Update what-is-rocDecode.md removed installation content * Update what-is-rocDecode.md Updated product name * Update install.md * Update _toc.yml.in * Update Create-a-decoder-using-rocDecCreateDecoder.md * Update Create-parser-object-using-rocDecCreateVideoParser.md * Update Decode-the-frame-using-rocDecDecodeFrame.md * Update Destroy-the-decoder.md * Update Destroy-the-parser-using-rocDecDestroyVideoParser.md * Update Parse-video-data-using-rocDecParseVideoData.md * Update Prepare-the-decoded-frame-for-further-processing.md * Update Query-decode-capabilities-using-rocDecGetDecoderCaps.md * Update Query-the-decoding-status.md * Update Reconfigure-the-decorder.md * Update Use-rocDecode-API.md * Update _toc.yml.in * Update _toc.yml.in * Update index.md * Update index.md * Index - Change to RST * Fix - index * Update conf.py copyright * Cleanup - Index * Update _toc.yml.in * Update _toc.yml.in * Update what-is-rocDecode.md Added concept * Add files via upload * Update what-is-rocDecode.md * Update what-is-rocDecode.md * Update what-is-rocDecode.md * Update what-is-rocDecode.md * Update what-is-rocDecode.md * Rename VideoDecoderPipeline (1).png to VideoDecoderPipelinetest.png * Update what-is-rocDecode.md * Update what-is-rocDecode.md * Rename VideoDecoderPipeline.png to VideoDecoderPipelinetest.png * Update what-is-rocDecode.md * Update what-is-rocDecode.md * Update what-is-rocDecode.md * Update what-is-rocDecode.md * Update index.md Added a numbered list of actions. * Update index.md add links * Update index.md * Update index.md * Update index.md * Update index.md * Update index.md * Update index.md * Update index.md * Update index.md * Update index.md * Update index.md * Update index.md * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.md * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.md corrected the order of steps. * Update index.rst Corrected the order of tasks * Update _toc.yml.in Reorder the how to * Update install.md * Update what-is-rocDecode.md * Update what-is-rocDecode.md updated image path * Update index.rst Fixed Reconfigure the decoder <https://github.com/ROCm/rocDecode/blob/master/docs/how-to/Reconfigure-the-decorder.html>`_to Reconfigure the decoder <https://github.com/ROCm/rocDecode/blob/master/docs/how-to/Reconfigure-the-decoder.html>`_ * Rename Reconfigure-the-decorder.md to Reconfigure-the-decoder.md Corrected the page name to Reconfigure the decoder * Update index.rst Updated to relative links * Update index.rst Updated index.rst * Update index.rst * Update index.md * Update index.md * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst updated ref to doc * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Add files via upload * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst * Update index.md * Update index.md * Update what-is-rocDecode.md * Update what-is-rocDecode.md * Update install.md * Update install.md * Update what-is-rocDecode.md * Update what-is-rocDecode.md * Update what-is-rocDecode.md * Update what-is-rocDecode.md * Update index.md * Update index.md * Update _toc.yml.in * Update _toc.yml.in * Update what-is-rocDecode.md * Update install.md * Update install.md * Update what-is-rocDecode.md * Update index.md * restructure & edits * udpate readme * cleanup * verbiage * minor fixes * update changelog * update changelog * update title * add metadata * more metadata * convert to RST * intersphinx test * edits, install reorg, address comments * verbiage * update requirements * remove extraneous note * Update docs/sphinx/requirements.in * clean up install info * update readme * update readme * update requirements * formatting * revert requirements * Docs - Update Requirements * requirements * Update requirements * Fix typo in requirements pip-compile error --------- Co-authored-by: Roopa Malavally <56051583+Rmalavally@users.noreply.github.com> Co-authored-by: Kiriti Gowda <kiritigowda@gmail.com> Co-authored-by: Pavel Tcherniaev <Pavel.Tcherniaev@amd.com> Co-authored-by: Sam Wu <sjwu@ualberta.ca> Co-authored-by: kiritigowda <kiriti.nageshgowda@amd.com> Co-authored-by: Sam Wu <sam.wu2@amd.com>
This commit is contained in:
Lisa
GitHub
+27
-42
@@ -1,67 +1,52 @@
|
||||
# rocDecode
|
||||
# rocDecode changelog
|
||||
|
||||
# Changelog
|
||||
Documentation for rocDecode is available at
|
||||
[https://rocm.docs.amd.com/projects/rocDecode/en/latest/](https://rocm.docs.amd.com/projects/rocDecode/en/latest/)
|
||||
|
||||
## Online Documentation
|
||||
## (Unreleased) rocDecode 0.5.0
|
||||
|
||||
[rocDecode Documentation](https://github.com/ROCmSoftwarePlatform/rocDecode#rocDecode)
|
||||
### Changes
|
||||
|
||||
## rocDecode 0.5.0 (unreleased)
|
||||
* Changed setup updates
|
||||
* Added AMDGPU package support
|
||||
* Optimized package dependencies
|
||||
* Updated README
|
||||
|
||||
### Added
|
||||
### Fixes
|
||||
|
||||
* AMDGPU package support
|
||||
|
||||
### Optimizations
|
||||
|
||||
* Package dependdencies
|
||||
* Readme
|
||||
|
||||
### Changed
|
||||
|
||||
* Setup Updates
|
||||
|
||||
### Fixed
|
||||
|
||||
* minor bug fix and updates
|
||||
* Minor bug fix and updates
|
||||
|
||||
### Tested configurations
|
||||
|
||||
* Linux distribution
|
||||
+ Ubuntu - `20.04` / `22.04`
|
||||
* ROCm:
|
||||
+ rocm-core - `5.6.1.50601-93`
|
||||
+ amdgpu-core - `1:5.6.50601-1649308`
|
||||
* Ubuntu - `20.04` / `22.04`
|
||||
* ROCm:
|
||||
* rocm-core - `6.1.0.60100-28`
|
||||
* amdgpu-core - `1:6.1.60100-1731559`
|
||||
* FFMPEG - `4.2.7` / `4.4.2-0`
|
||||
* rocDecode Setup Script - `V1.4`
|
||||
|
||||
## rocDecode 0.4.0
|
||||
|
||||
### Added
|
||||
### Changes
|
||||
|
||||
* CTest - Tests for install verification
|
||||
* Doxygen - Support for API documentation
|
||||
* Added CTest - Tests for install verification
|
||||
* Added Doxygen - Support for API documentation
|
||||
* Changed setup updates
|
||||
* Optimized CMakeList Cleanup
|
||||
* Added README
|
||||
|
||||
### Optimizations
|
||||
### Fixes
|
||||
|
||||
* CMakeList Cleanup
|
||||
* Readme
|
||||
|
||||
### Changed
|
||||
|
||||
* Setup Updates
|
||||
|
||||
### Fixed
|
||||
|
||||
* minor bug fix and updates
|
||||
* Minor bug fix and updates
|
||||
|
||||
### Tested configurations
|
||||
|
||||
* Linux distribution
|
||||
+ Ubuntu - `20.04` / `22.04`
|
||||
* ROCm:
|
||||
+ rocm-core - `5.6.1.50601-93`
|
||||
+ amdgpu-core - `1:5.6.50601-1649308`
|
||||
* Ubuntu - `20.04` / `22.04`
|
||||
* ROCm:
|
||||
* rocm-core - `5.6.1.50601-93`
|
||||
* amdgpu-core - `1:5.6.50601-1649308`
|
||||
* FFMPEG - `4.2.7` / `4.4.2-0`
|
||||
* libva-dev - `2.7.0-2` / `2.14.0-1`
|
||||
* rocDecode Setup Script - `V1.1`
|
||||
+107
-107
@@ -1,9 +1,21 @@
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
|
||||
|
||||
<p align="center"><img width="70%" src="docs/data/AMD_rocDecode_Logo.png" /></p>
|
||||
|
||||
rocDecode is a high-performance video decode SDK for AMD GPUs. rocDecode API lets developers access the video decoding features available on the GPU.
|
||||
rocDecode is a high-performance video decode SDK for AMD GPUs. Using the rocDecode API, you can
|
||||
access the video decoding features available on your GPU.
|
||||
|
||||
## Tested configurations
|
||||
|
||||
* Linux
|
||||
* Ubuntu - `20.04` / `22.04`
|
||||
* RHEL - `8` / `9`
|
||||
* SLES - `15-SP4`
|
||||
* ROCm:
|
||||
* rocm-core - `6.1.0.60100-28`
|
||||
* amdgpu-core - `1:6.1.60100-1731559`
|
||||
* FFmpeg - `4.2.7` / `4.4.2-0`
|
||||
* rocDecode Setup Script - `V1.4`
|
||||
|
||||
## Supported codecs
|
||||
|
||||
@@ -12,92 +24,94 @@ rocDecode is a high-performance video decode SDK for AMD GPUs. rocDecode API let
|
||||
## Prerequisites
|
||||
|
||||
* Linux distribution
|
||||
* Ubuntu - `20.04` / `22.04`
|
||||
* RHEL - `8` / `9`
|
||||
* SLES - `15-SP4`
|
||||
* Ubuntu - `20.04` / `22.04`
|
||||
* RHEL - `8` / `9`
|
||||
* SLES - `15-SP4`
|
||||
|
||||
* [ROCm supported hardware](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html)
|
||||
* **NOTE:** `gfx908` or higher required
|
||||
* [ROCm-supported hardware](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html) (`gfx908` or higher 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) with `--usecase=multimediasdk,rocm --no-32`
|
||||
* **NOTE:** To install rocdecode with minimum requirements follow instructions [here](https://github.com/ROCm/rocDecode/wiki#how-can-i-install-rocdecode-runtime-with-minimum-requirements)
|
||||
|
||||
### To build from source
|
||||
* 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=multimediasdk,rocm --no-32`
|
||||
* To install rocDecode with minimum requirements, follow the
|
||||
[quick-start](./docs/install/quick-start.rst) instructions
|
||||
|
||||
* CMake `3.5` or later
|
||||
|
||||
```shell
|
||||
sudo apt install cmake
|
||||
```
|
||||
```shell
|
||||
sudo apt install cmake
|
||||
```
|
||||
|
||||
* [pkg-config](https://en.wikipedia.org/wiki/Pkg-config)
|
||||
|
||||
```shell
|
||||
sudo apt install pkg-config
|
||||
```
|
||||
```shell
|
||||
sudo apt install pkg-config
|
||||
```
|
||||
|
||||
* [FFMPEG](https://ffmpeg.org/about.html) runtime and headers - for tests and samples
|
||||
* [FFmpeg](https://ffmpeg.org/about.html) runtime and headers - for tests and samples
|
||||
|
||||
```shell
|
||||
sudo apt install ffmpeg libavcodec-dev libavformat-dev libavutil-dev
|
||||
```
|
||||
```shell
|
||||
sudo apt install ffmpeg libavcodec-dev libavformat-dev libavutil-dev
|
||||
```
|
||||
|
||||
**NOTE:**
|
||||
* If using Ubuntu 22.04, you must install `libstdc++-12-dev`
|
||||
|
||||
* All package installs are shown with the `apt` package manager, use the appropriate package manager depending on the OS.
|
||||
```shell
|
||||
sudo apt install libstdc++-12-dev
|
||||
```
|
||||
|
||||
* Ubuntu 22.04 - Install `libstdc++-12-dev`
|
||||
>[!NOTE]
|
||||
> All package installs are shown with the `apt` package manager. Use the appropriate package
|
||||
> manager for your operating system.
|
||||
|
||||
```shell
|
||||
sudo apt install libstdc++-12-dev
|
||||
```
|
||||
### Prerequisites setup script
|
||||
|
||||
#### Prerequisites setup script for Linux
|
||||
|
||||
For the convenience of the developer, we provide the setup script [rocDecode-setup.py](rocDecode-setup.py) which will install all the dependencies required by this project.
|
||||
|
||||
**Usage:**
|
||||
For your convenience, we provide the setup script,
|
||||
[rocDecode-setup.py](https://github.com/ROCm/rocDecode/blob/develop/rocDecode-setup.py),
|
||||
which installs all required dependencies. Run this script only once.
|
||||
|
||||
```shell
|
||||
python rocDecode-setup.py --rocm_path [ ROCm Installation Path - optional (default:/opt/rocm)]
|
||||
--developer [ Setup Developer Options - optional (default:ON) [options:ON/OFF]]
|
||||
```
|
||||
|
||||
**NOTE:** This script only needs to be executed once.
|
||||
## Installation instructions
|
||||
|
||||
## Build and install instructions
|
||||
To install rocDecode, you can use [Package install](#package-install) or [Source install](#source-install).
|
||||
|
||||
### Package install
|
||||
|
||||
Install rocDecode runtime, development, and test packages.
|
||||
To install rocDecode runtime, development, and test packages, run the line of code for your operating
|
||||
system.
|
||||
|
||||
* Ubuntu
|
||||
|
||||
```shell
|
||||
sudo apt install rocdecode rocdecode-dev rocdecode-test
|
||||
```
|
||||
|
||||
* RHEL
|
||||
|
||||
```shell
|
||||
sudo yum install rocdecode rocdecode-devel rocdecode-test
|
||||
```
|
||||
|
||||
* SLES
|
||||
|
||||
```shell
|
||||
sudo zypper install rocdecode rocdecode-devel rocdecode-test
|
||||
```
|
||||
|
||||
>[!NOTE]
|
||||
> Package install auto installs all dependencies.
|
||||
|
||||
* Runtime package - `rocdecode` only provides the rocdecode library `librocdecode.so`
|
||||
* Development package - `rocdecode-dev`/`rocdecode-devel` provides the library, header files, and samples
|
||||
* Test package - `rocdecode-test` provides ctest to verify installation
|
||||
* Test package - `rocdecode-test` provides CTest to verify installation
|
||||
|
||||
**NOTE:** Package install will auto install all dependencies.
|
||||
### Source install
|
||||
|
||||
#### Ubuntu
|
||||
|
||||
```shell
|
||||
sudo apt install rocdecode rocdecode-dev rocdecode-test
|
||||
```
|
||||
|
||||
#### RHEL
|
||||
|
||||
```shell
|
||||
sudo yum install rocdecode rocdecode-devel rocdecode-test
|
||||
```
|
||||
|
||||
#### SLES
|
||||
|
||||
```shell
|
||||
sudo zypper install rocdecode rocdecode-devel rocdecode-test
|
||||
```
|
||||
|
||||
**NOTE:** `RHEL`/`SLES` package install requires manual `FFMPEG V4.X` dev install
|
||||
|
||||
### Source build and install
|
||||
To build rocDecode from source, run:
|
||||
|
||||
```shell
|
||||
git clone https://github.com/ROCm/rocDecode.git
|
||||
@@ -108,75 +122,75 @@ make -j8
|
||||
sudo make install
|
||||
```
|
||||
|
||||
* run tests - Requires `FFMPEG` dev install
|
||||
Run tests (this requires FFmpeg dev install):
|
||||
|
||||
```shell
|
||||
make test
|
||||
```
|
||||
|
||||
**NOTE:** run tests with verbose option `make test ARGS="-VV"`
|
||||
To run tests with verbose option, use `make test ARGS="-VV"`.
|
||||
|
||||
Make package:
|
||||
|
||||
* make package
|
||||
|
||||
```shell
|
||||
sudo make package
|
||||
```
|
||||
|
||||
## Verify installation
|
||||
|
||||
The installer will copy
|
||||
The installer copies:
|
||||
|
||||
* Libraries into `/opt/rocm/lib`
|
||||
* Header files into `/opt/rocm/include/rocdecode`
|
||||
* Samples folder into `/opt/rocm/share/rocdecode`
|
||||
* Documents folder into `/opt/rocm/share/doc/rocdecode`
|
||||
|
||||
**NOTE:** FFMPEG dev install required to run samples and tests
|
||||
* To verify your installation using a sample application, run:
|
||||
|
||||
### Verify with sample application
|
||||
```shell
|
||||
mkdir rocdecode-sample && cd rocdecode-sample
|
||||
cmake /opt/rocm/share/rocdecode/samples/videoDecode/
|
||||
make -j8
|
||||
./videodecode -i /opt/rocm/share/rocdecode/video/AMD_driving_virtual_20-H265.mp4
|
||||
```
|
||||
|
||||
```shell
|
||||
mkdir rocdecode-sample && cd rocdecode-sample
|
||||
cmake /opt/rocm/share/rocdecode/samples/videoDecode/
|
||||
make -j8
|
||||
./videodecode -i /opt/rocm/share/rocdecode/video/AMD_driving_virtual_20-H265.mp4
|
||||
```
|
||||
* To verify your installation using the `rocdecode-test` package, run:
|
||||
|
||||
### Verify with rocdecode-test package
|
||||
```shell
|
||||
mkdir rocdecode-test && cd rocdecode-test
|
||||
cmake /opt/rocm/share/rocdecode/test/
|
||||
ctest -VV
|
||||
```
|
||||
|
||||
The test package will install the ctest module to test the rocdecode. Follow the below steps to test the package install
|
||||
|
||||
```shell
|
||||
mkdir rocdecode-test && cd rocdecode-test
|
||||
cmake /opt/rocm/share/rocdecode/test/
|
||||
ctest -VV
|
||||
```
|
||||
This test package installs the CTest module.
|
||||
|
||||
## Samples
|
||||
|
||||
The tool provides a few samples to decode videos [here](samples/). Please refer to the individual folders to build and run the samples.
|
||||
You can access samples to decode your videos in our
|
||||
[GitHub repository](https://github.com/ROCm/rocDecode/tree/develop/samples). Refer to the
|
||||
individual folders to build and run the samples.
|
||||
|
||||
### Sample prerequisites
|
||||
[FFmpeg](https://ffmpeg.org/about.html) is required for sample applications and `make test`. To install
|
||||
FFmpeg, refer to the instructions listed for your operating system:
|
||||
|
||||
* [FFMPEG](https://ffmpeg.org/about.html) - required to run sample applications & make test
|
||||
|
||||
* On `Ubuntu`
|
||||
* Ubuntu:
|
||||
|
||||
```shell
|
||||
sudo apt install ffmpeg libavcodec-dev libavformat-dev libavutil-dev
|
||||
```
|
||||
|
||||
* On `RHEL`/`SLES` - install ffmpeg development packages manually or use `rocDecode-setup.py` script
|
||||
|
||||
* RHEL/SLES:
|
||||
|
||||
Install ffmpeg development packages manually or use `rocDecode-setup.py` script
|
||||
|
||||
## Docker
|
||||
|
||||
Docker files to build rocDecode containers are available [here](docker/)
|
||||
You can find rocDecode Docker containers in our
|
||||
[GitHub repository](https://github.com/ROCm/rocDecode/tree/develop/docker).
|
||||
|
||||
## Documentation
|
||||
|
||||
Run the steps below to build documentation locally.
|
||||
|
||||
* Sphinx
|
||||
Run the following code to build our documentation locally.
|
||||
|
||||
```shell
|
||||
cd docs
|
||||
@@ -184,20 +198,6 @@ pip3 install -r sphinx/requirements.txt
|
||||
python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
|
||||
```
|
||||
|
||||
* Doxygen
|
||||
|
||||
```shell
|
||||
doxygen .Doxyfile
|
||||
```
|
||||
|
||||
## Tested configurations
|
||||
|
||||
* Linux distribution
|
||||
* Ubuntu - `20.04` / `22.04`
|
||||
* RHEL - `8` / `9`
|
||||
* SLES - `15-SP4`
|
||||
* ROCm:
|
||||
* rocm-core - `6.1.0.60100-1137`
|
||||
* amdgpu-core - `1:6.1.60100-1709965`
|
||||
* FFMPEG - `4.2.7` / `4.4.2-0`
|
||||
* rocDecode Setup Script - `V1.4`
|
||||
For more information on documentation builds, refer to the
|
||||
[Building documentation](https://rocm.docs.amd.com/en/latest/contribute/building.html)
|
||||
page.
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
.. meta::
|
||||
:description: Video decoding pipeline
|
||||
:keywords: video decoder, video decoding, rocDecode, AMD, ROCm
|
||||
|
||||
********************************************************************
|
||||
Video decoding pipeline
|
||||
********************************************************************
|
||||
|
||||
.. image:: ../data/VideoDecoderPipelinetest.png
|
||||
:alt: Video decoder pipeline test
|
||||
|
||||
There are three main components in rocDecode:
|
||||
|
||||
* Demuxer: Our demuxer is based on FFmpeg, a leading multimedia framework. For more information,
|
||||
refer to the `FFmpeg website <https://ffmpeg.org/about.html>`_.
|
||||
* Video parser APIs
|
||||
* Video decoder APIs
|
||||
|
||||
rocDecode follows this workflow:
|
||||
|
||||
1. The demuxer extracts a segment of video data and sends it to the video parser.
|
||||
2. The video parser extracts crucial information, such as picture and slice parameters, and sends it to
|
||||
the decoder APIs.
|
||||
3. The hardware receives the picture and slice parameters, then decodes a frame using Video
|
||||
Acceleration API (VA-API).
|
||||
4. This process repeats in a loop until all frames have been decoded.
|
||||
|
||||
Steps in decoding video content for applications (available in the rocDecode Toolkit):
|
||||
|
||||
1. Demultiplex the content into elementary stream packets (FFmpeg)
|
||||
2. Parse the demultiplexed packets into video frames for the decoder provided by rocDecode API.
|
||||
3. Decode compressed video frames into YUV frames using rocDecode API.
|
||||
4. Wait for the decoding to finish.
|
||||
5. Get the decoded YUV frame from amd-gpu context to HIP (using VAAPI-HIP interoperability under
|
||||
ROCm).
|
||||
6. Run HIP kernels in the mapped YUV frame. For example, format conversion, scaling, object detection,
|
||||
classification, and others.
|
||||
7. Release the decoded frame.
|
||||
|
||||
.. note::
|
||||
YUV is a color space that represents images using luminance (Y) for brightness and two chrominance
|
||||
components (U and V) for color information.
|
||||
|
||||
The preceding steps are demonstrated in the sample applications located in our
|
||||
`GitHub repository <https://github.com/ROCm/rocDecode/tree/develop/samples>`_ directory.
|
||||
+5
-14
@@ -1,6 +1,6 @@
|
||||
# MIT License
|
||||
|
||||
# Copyright (c) 2023 - 2024 Advanced Micro Devices, Inc.
|
||||
# Copyright (c) 2023 - 2024 Advanced Micro Devices, Inc. All rights reserved.
|
||||
|
||||
# Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
# of this software and associated documentation files (the "Software"), to deal
|
||||
@@ -17,7 +17,7 @@
|
||||
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
# SOFTWARE.
|
||||
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
@@ -27,7 +27,6 @@
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
import re
|
||||
import shutil
|
||||
|
||||
from rocm_docs import ROCmDocs
|
||||
|
||||
@@ -36,20 +35,12 @@ with open('../CMakeLists.txt', encoding='utf-8') as f:
|
||||
if not match:
|
||||
raise ValueError("VERSION not found!")
|
||||
version_number = match[1]
|
||||
left_nav_title = f"rocDecode {version_number} Documentation"
|
||||
|
||||
shutil.copy2('../README.md','./quickStart.md')
|
||||
shutil.copy2('../samples/README.md','./samples.md')
|
||||
shutil.copy2('../samples/videoDecode/README.md','./videoDecode.md')
|
||||
shutil.copy2('../samples/videoDecodeMem/README.md','./videoDecodeMem.md')
|
||||
shutil.copy2('../samples/videoDecodeMultiFiles/README.md','./videoDecodeMultiFiles.md')
|
||||
shutil.copy2('../samples/videoDecodePerf/README.md','./videoDecodePerf.md')
|
||||
shutil.copy2('../samples/videoDecodeRGB/README.md','./videoDecodeRGB.md')
|
||||
left_nav_title = f"rocDecode {version_number} documentation"
|
||||
|
||||
# for PDF output on Read the Docs
|
||||
project = "rocDecode Documentation"
|
||||
project = "rocDecode documentation"
|
||||
author = "Advanced Micro Devices, Inc."
|
||||
copyright = "Copyright (c) 2023 - 2024 Advanced Micro Devices, Inc. All rights reserved."
|
||||
copyright = "Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved."
|
||||
version = version_number
|
||||
release = version_number
|
||||
|
||||
|
||||
|
Before Width: | Height: | Ukuran: 60 KiB After Width: | Height: | Ukuran: 60 KiB |
@@ -943,11 +943,11 @@ WARN_LOGFILE =
|
||||
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
|
||||
# Note: If this tag is empty the current directory is searched.
|
||||
|
||||
INPUT = ../../README.md \
|
||||
../../api/rocdecode.h \
|
||||
../../api/rocparser.h \
|
||||
../../utils/rocvideodecode/roc_video_dec.h \
|
||||
../../utils/video_demuxer.h
|
||||
INPUT = ../reference/index.md \
|
||||
../../api/rocdecode.h \
|
||||
../../api/rocparser.h \
|
||||
../../utils/rocvideodecode/roc_video_dec.h \
|
||||
../../utils/video_demuxer.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,214 @@
|
||||
.. meta::
|
||||
:description: Using rocDecode
|
||||
:keywords: parse video, parse, decode, video decoder, video decoding, rocDecode, AMD, ROCm
|
||||
|
||||
********************************************************************
|
||||
Using rocDecode
|
||||
********************************************************************
|
||||
|
||||
To learn how to use the rocDecode SDK library and its different utilities, follow these instructions:
|
||||
|
||||
1. API overview
|
||||
====================================================
|
||||
|
||||
All rocDecode APIs are exposed in the header files ``rocdecode.h`` and ``rocparser.h``. You can find
|
||||
these files in the `api` folder in the rocDecode repository.
|
||||
|
||||
The samples use the ``RocVideoDecoder`` user class provided in ``roc_video_dec.h`` in the ``utils`` folder
|
||||
of the rocDecode repository.
|
||||
|
||||
A video parser (defined in ``rocparser.h``) is needed to extract and decode headers from the bitstream
|
||||
in order to organize the data into a structured format for the hardware decoder. The parser is critical in
|
||||
video decoding, as it controls the decoding and display of a bitstream's individual frames and fields.
|
||||
|
||||
The parser object in ``rocparser.h`` has three main APIs:
|
||||
|
||||
* ``rocDecCreateVideoParser()``
|
||||
* ``rocDecParseVideoData()``
|
||||
* ``rocDecDestroyVideoParser()``
|
||||
|
||||
2. Create a parser object
|
||||
====================================================
|
||||
|
||||
The ``rocDecCreateVideoParser()`` API creates a video parser object for the codec that you specify. The
|
||||
API takes ``max_num_decode_surfaces``, which determines the Decoded Picture Buffer (DPB) size for
|
||||
decoding. When creating a parser object, the application must register certain callback functions with
|
||||
the driver, which is called from the parser during decode.
|
||||
|
||||
* ``pfn_sequence_callback`` is called when the parser encounters a new sequence header. The parser
|
||||
informs you of the minimum number of surfaces needed by the parser's DPB to successfully decode
|
||||
the bitstream. In addition, the caller can set additional parameters, like ``max_display_delay``, to
|
||||
control frame decoding and display.
|
||||
|
||||
* The ``pfn_decode_picture`` callback function is triggered when a picture is set for decoding.
|
||||
|
||||
* The ``pfn_display_picture`` callback function is triggered when a frame in display order is ready to be
|
||||
consumed by the caller.
|
||||
|
||||
* The ``pfn_get_sei_msg`` callback function is triggered when your Supplementation Enhancement
|
||||
Information (SEI) message is parsed and sent back to the caller.
|
||||
|
||||
3. Parse video data
|
||||
====================================================
|
||||
|
||||
Elementary stream video packets extracted from the de-multiplexer are fed into the parser using the
|
||||
``rocDecParseVideoData()`` API.
|
||||
|
||||
During this call, the parser triggers the callbacks as it encounters a new sequence header, receives
|
||||
compressed frame/field data ready to be decoded, or when it's ready to display a frame. If any of the
|
||||
callbacks return a failure, it is propagated back to the application so the decoding can be ended
|
||||
gracefully.
|
||||
|
||||
4. Query decode capabilities
|
||||
====================================================
|
||||
|
||||
The ``rocDecGetDecoderCaps()`` API allows you to query the capabilities of the underlying hardware
|
||||
video decoder. Decoder capabilities usually include supported codecs, maximum resolution, and
|
||||
bit-depth.
|
||||
|
||||
The following pseudo-code illustrates the use of this API. The application handles the error
|
||||
appropriately for non-supported decoder capabilities.
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
RocdecDecodeCaps decode_caps;
|
||||
memset(&decode_caps, 0, sizeof(decode_caps));
|
||||
decode_caps.codec_type = p_video_format->codec;
|
||||
decode_caps.chroma_format = p_video_format->chroma_format;
|
||||
decode_caps.bit_depth_minus_8 = p_video_format->bit_depth_luma_minus8;
|
||||
|
||||
ROCDEC_API_CALL(rocDecGetDecoderCaps(&decode_caps));
|
||||
|
||||
if(!decode_caps.is_supported) {
|
||||
ROCDEC_THROW("Rocdec:: Codec not supported on this GPU: ", ROCDEC_NOT_SUPPORTED);
|
||||
return 0;
|
||||
}
|
||||
|
||||
if ((p_video_format->coded_width > decode_caps.max_width) ||
|
||||
(p_video_format->coded_height > decode_caps.max_height)) {
|
||||
|
||||
std::ostringstream errorString;
|
||||
errorString << std::endl
|
||||
<< "Resolution : " << p_video_format->coded_width << "x" << p_video_format->coded_height << std::endl
|
||||
<< "Max Supported (wxh) : " << decode_caps.max_width << "x" << decode_caps.max_height << std::endl
|
||||
<< "Resolution not supported on this GPU ";
|
||||
|
||||
const std::string cErr = errorString.str();
|
||||
ROCDEC_THROW(cErr, ROCDEC_NOT_SUPPORTED);
|
||||
return 0;
|
||||
}
|
||||
|
||||
5. Create a decoder
|
||||
====================================================
|
||||
|
||||
``rocDecCreateDecoder()`` creates an instance of the hardware video decoder object and provides you
|
||||
with a handle upon successful creation. Refer to the ``RocDecoderCreateInfo`` structure for information
|
||||
about the parameters passed for creating the decoder. For example,
|
||||
``RocDecoderCreateInfo::codec_type`` represents the codec type of the video. The decoder handle
|
||||
returned by ``rocDecCreateDecoder()`` must be retained for the entire decode session because the
|
||||
handle is passed along with the other decoding APIs. In addition, you can inform display or crop
|
||||
dimensions along with this API.
|
||||
|
||||
6. Decode the frame
|
||||
====================================================
|
||||
|
||||
After de-multiplexing and parsing, you can decode bitstream data containing a frame/field using
|
||||
hardware.
|
||||
|
||||
Use the ``rocDecDecodeFrame()`` API to submit a new frame for hardware decoding. Underneath the
|
||||
driver, the Video Acceleration API (VA-API) is used to submit compressed picture data to the driver.
|
||||
The parser extracts all the necessary information from the bitstream and fills the ``RocdecPicParams``
|
||||
structure that's appropriate for the codec. The high-level ``RocVideoDecoder`` class connects the parser
|
||||
and decoder used for all sample applications.
|
||||
|
||||
The ``rocDecDecodeFrame()`` call takes the decoder handle and the pointer to the ``RocdecPicParams``
|
||||
structure and initiates the video decoding using VA-API.
|
||||
|
||||
7. Query the decoding status
|
||||
====================================================
|
||||
|
||||
After submitting a frame for decoding, you can call ``rocDecGetDecodeStatus()`` to query the decoding
|
||||
status for a given frame. A structure pointer, ``RocdecDecodeStatus*``, is filled and returned.
|
||||
|
||||
The API inputs are:
|
||||
|
||||
* ``decoder_handle``: A ``RocDecoder`` handler, ``rocDecDecoderHandle``.
|
||||
* ``pic_idx``: An `int` value for the ``picIdx`` for which you want a status in order to index of the picture.
|
||||
* ``decode_status``: A pointer to ``RocdecDecodeStatus`` as a return value.
|
||||
|
||||
The API returns one of the following statuses:
|
||||
|
||||
* Invalid (0): Decode status is not valid.
|
||||
* In Progress (1): Decoding is in progress.
|
||||
* Success (2): Decoding was successful and no errors were returned.
|
||||
* Error (8): The frame was corrupted, but the error was not concealed.
|
||||
* Error Concealed (9): The frame was corrupted and the error was concealed.
|
||||
* Displaying (10): Decode is complete, display in progress.
|
||||
|
||||
8. Prepare the decoded frame for further processing
|
||||
====================================================
|
||||
|
||||
The decoded frames can be used for further postprocessing using ``rocDecGetVideoFrame()``. The
|
||||
successful completion of ``rocDecGetVideoFrame()`` indicates that the decoding process is complete and
|
||||
the device memory pointer is inter-opped into the ROCm HIP address space in order to further process
|
||||
the decoded frame in device memory. The caller gets the necessary information on the output surface,
|
||||
such as YUV format, dimensions, and pitch from this call. In the high-level ``RocVideoDecoder`` class, we
|
||||
provide four different surface type modes for the mapped surface, as specified in
|
||||
``OutputSurfaceMemoryType``.
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
typedef enum OutputSurfaceMemoryType_enum {
|
||||
OUT_SURFACE_MEM_DEV_INTERNAL = 0, /**< Internal interopped decoded surface memory **/
|
||||
OUT_SURFACE_MEM_DEV_COPIED = 1, /**< decoded output will be copied to a separate device memory **/
|
||||
OUT_SURFACE_MEM_HOST_COPIED = 2 /**< decoded output will be copied to a separate host memory **/
|
||||
OUT_SURFACE_MEM_NOT_MAPPED = 3 /**< decoded output is not available (interop won't be used): useful for decode only performance app*/
|
||||
} OutputSurfaceMemoryType;
|
||||
|
||||
|
||||
If the mapped surface type is ``OUT_SURFACE_MEM_DEV_INTERNAL``, the direct pointer to the decoded
|
||||
surface is provided. You must call ``ReleaseFrame()`` (``RocVideoDecoder`` class). If the requested surface
|
||||
type is ``OUT_SURFACE_MEM_DEV_COPIED`` or ``OUT_SURFACE_MEM_HOST_COPIED``, the internal
|
||||
decoded frame is copied to another buffer, either in device memory or host memory. After that, it's
|
||||
immediately unmapped for re-use by the ``RocVideoDecoder`` class.
|
||||
|
||||
Refer to the ``RocVideoDecoder`` class and
|
||||
`samples <https://github.com/ROCm/rocDecode/tree/develop/samples>`_ for details on how to use
|
||||
these APIs.
|
||||
|
||||
9. Reconfigure the decoder
|
||||
====================================================
|
||||
|
||||
You can call ``rocDecReconfigureDecoder()`` to reuse a single decoder for multiple clips or when the
|
||||
video resolution changes during the decode. The API currently supports resolution changes, resize
|
||||
parameter changes, and target area parameter changes for the same codec without destroying an
|
||||
ongoing decoder instance. This can improve performance and reduce overall latency.
|
||||
|
||||
The API inputs are:
|
||||
|
||||
* ``decoder_handle``: A ``RocDecoder`` handler, ``rocDecDecoderHandle``.
|
||||
* ``reconfig_params``: You must specify the parameters for the changes in
|
||||
``RocdecReconfigureDecoderInfo``. The width and height used for reconfiguration cannot exceed the
|
||||
values set for ``max_width`` and ``max_height``, defined in ``RocDecoderCreateInfo``. If you need to
|
||||
change these values, you have to destroy and recreate the session.
|
||||
|
||||
.. note::
|
||||
|
||||
You must call ``rocDecReconfigureDecoder()`` during ``RocdecParserParams::pfn_sequence_callback``.
|
||||
|
||||
10. Destroy the decoder
|
||||
====================================================
|
||||
|
||||
You must call the ``rocDecDestroyDecoder()`` to destroy the session and free up resources.
|
||||
|
||||
The API input is:
|
||||
|
||||
* ``decoder_handle``: A ``RocDecoder`` handler, ``rocDecDecoderHandle``.
|
||||
|
||||
The API returns a ``RocdecDecodeStatus`` value.
|
||||
|
||||
11. Destroy the parser
|
||||
====================================================
|
||||
|
||||
You must call ``rocDecDestroyVideoParser()`` to destroy the parser object and free up all allocated
|
||||
resources at the end of video decoding.
|
||||
@@ -0,0 +1,47 @@
|
||||
.. meta::
|
||||
:description: rocDecode documentation and API reference library
|
||||
:keywords: rocDecode, ROCm, API, documentation
|
||||
|
||||
********************************************************************
|
||||
rocDecode documentation
|
||||
********************************************************************
|
||||
|
||||
rocDecode provides APIs, utilities, and samples that you can use to easily access the video 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.
|
||||
|
||||
You can access rocDecode code on our `GitHub repository <https://github.com/ROCm/rocDecode>`_.
|
||||
|
||||
Our documentation is structured as follows:
|
||||
|
||||
.. grid:: 2
|
||||
:gutter: 3
|
||||
|
||||
.. grid-item-card:: Install
|
||||
|
||||
* :doc:`Quick-start <./install/quick-start>`
|
||||
* :doc:`rocDecode installation <./install/install>`
|
||||
|
||||
.. grid-item-card:: API reference
|
||||
|
||||
* :doc:`Functions <../doxygen/html/globals>`
|
||||
* :doc:`Data structures <../doxygen/html/annotated>`
|
||||
* :doc:`File list <../doxygen/html/files>`
|
||||
|
||||
.. grid-item-card:: How to
|
||||
|
||||
* :doc:`Use rocDecode <how-to/using-rocdecode>`
|
||||
|
||||
.. grid-item-card:: Conceptual
|
||||
|
||||
* :doc:`Video decoding pipeline <./conceptual/video-decoding-pipeline>`
|
||||
|
||||
.. grid-item-card:: Tutorials
|
||||
|
||||
* `GitHub samples <https://github.com/ROCm/rocDecode/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,261 @@
|
||||
.. meta::
|
||||
:description: Install rocDecode
|
||||
:keywords: install, rocDecode, AMD, ROCm
|
||||
|
||||
********************************************************************
|
||||
Installation
|
||||
********************************************************************
|
||||
|
||||
rocDecode SDK is a high-performance video decode SDK for AMD GPUs. Using the rocDecode API,
|
||||
you can access the video decoding features available on your GPU.
|
||||
|
||||
Tested configurations
|
||||
========================================
|
||||
|
||||
* Linux
|
||||
|
||||
* Ubuntu: 20.04/22.04
|
||||
* RHEL: 8/9
|
||||
* SLES: 15-SP4
|
||||
|
||||
* ROCm
|
||||
|
||||
* rocm-core: 6.1.0.60100-28
|
||||
* amdgpu-core: 1:6.1.60100-1731559
|
||||
|
||||
* FFmpeg: 4.2.7/4.4.2-0
|
||||
|
||||
* rocDecode Setup Script: V1.4
|
||||
|
||||
Supported codecs
|
||||
========================================
|
||||
|
||||
H.265 (HEVC) - 8 bit, and 10 bit
|
||||
|
||||
Prerequisites
|
||||
========================================
|
||||
|
||||
* Linux distribution
|
||||
|
||||
* Ubuntu: 20.04/22.04
|
||||
* RHEL: 8/9
|
||||
* SLES: 15-SP4
|
||||
|
||||
* `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=multimediasdk,rocm --no-32``
|
||||
* To install rocDecode with minimum requirements, follow the :doc:`quick-start instructions <./quick-start>`
|
||||
|
||||
* 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
|
||||
|
||||
* `FFmpeg <https://ffmpeg.org/about.html>`_ runtime and headers - for tests and samples
|
||||
|
||||
.. code:: shell
|
||||
|
||||
sudo apt install ffmpeg libavcodec-dev libavformat-dev libavutil-dev
|
||||
|
||||
* 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,
|
||||
`rocDecode-setup.py <https://github.com/ROCm/rocDecode/blob/develop/rocDecode-setup.py>`_,
|
||||
which installs all required dependencies. Run this script only once.
|
||||
|
||||
.. code:: shell
|
||||
|
||||
python rocDecode-setup.py --rocm_path [ ROCm Installation Path - optional (default:/opt/rocm)]
|
||||
--developer [ Setup Developer Options - optional (default:ON) [options:ON/OFF]]
|
||||
|
||||
Installation instructions
|
||||
========================================
|
||||
|
||||
To install rocDecode, you can use :ref:`package-install` or
|
||||
:ref:`source-install`.
|
||||
|
||||
.. _package-install:
|
||||
|
||||
Package install
|
||||
------------------------------------------------------------------------------------------------------------
|
||||
|
||||
To install rocDecode runtime, development, and test packages, run the line of code for your operating
|
||||
system.
|
||||
|
||||
.. 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
|
||||
|
||||
.. note::
|
||||
|
||||
Package install auto installs all dependencies.
|
||||
|
||||
* Runtime package: ``rocdecode`` only provides the rocdecode library ``librocdecode.so``
|
||||
* Development package: ``rocdecode-dev``or ``rocdecode-devel`` provides the library, header files, and samples
|
||||
* Test package: ``rocdecode-test`` provides CTest to verify installation
|
||||
|
||||
.. _source-install:
|
||||
|
||||
Source install
|
||||
------------------------------------------------------------------------------------------------------------
|
||||
|
||||
To build rocDecode from source, run:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
git clone https://github.com/ROCm/rocDecode.git
|
||||
cd rocDecode
|
||||
mkdir build && cd build
|
||||
cmake ../
|
||||
make -j8
|
||||
sudo make install
|
||||
|
||||
Run tests (this requires FFmpeg dev install):
|
||||
|
||||
.. 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/rocdecode``
|
||||
* Samples folder into ``/opt/rocm/share/rocdecode``
|
||||
* Documents folder into ``/opt/rocm/share/doc/rocdecode``
|
||||
|
||||
To verify your installation using a sample application, run:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
mkdir rocdecode-sample && cd rocdecode-sample
|
||||
cmake /opt/rocm/share/rocdecode/samples/videoDecode/
|
||||
make -j8
|
||||
./videodecode -i /opt/rocm/share/rocdecode/video/AMD_driving_virtual_20-H265.mp4
|
||||
|
||||
To verify your installation using the ``rocdecode-test`` package, run:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
mkdir rocdecode-test && cd rocdecode-test
|
||||
cmake /opt/rocm/share/rocdecode/test/
|
||||
ctest -VV
|
||||
|
||||
This test package installs the CTest module.
|
||||
|
||||
Samples
|
||||
========================================
|
||||
|
||||
You can access samples to decode your videos in our
|
||||
`GitHub repository <https://github.com/ROCm/rocDecode/tree/develop/samples>`_. Refer to the
|
||||
individual folders to build and run the samples.
|
||||
|
||||
`FFmpeg <https://ffmpeg.org/about.html>`_ is required for sample applications and ``make test``. To
|
||||
install FFmpeg, refer to the instructions listed for your operating system:
|
||||
|
||||
.. tab-set::
|
||||
|
||||
.. tab-item:: Ubuntu
|
||||
|
||||
.. code:: shell
|
||||
|
||||
sudo apt install ffmpeg libavcodec-dev libavformat-dev libavutil-dev
|
||||
|
||||
.. tab-item:: RHEL
|
||||
|
||||
Install FFmpeg development packages manually or use the
|
||||
`rocDecode-setup.py <https://github.com/ROCm/rocDecode/blob/develop/rocDecode-setup.py>`_
|
||||
script
|
||||
|
||||
|
||||
.. tab-item:: SLES
|
||||
|
||||
Install FFmpeg development packages manually or use the
|
||||
`rocDecode-setup.py <https://github.com/ROCm/rocDecode/blob/develop/rocDecode-setup.py>`_
|
||||
script
|
||||
|
||||
Docker
|
||||
========================================
|
||||
|
||||
You can find rocDecode Docker containers in our
|
||||
`GitHub repository <https://github.com/ROCm/rocDecode/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 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", "No", "4096, 2160"
|
||||
"gfx90a - MI2xx", "VCN 2.6.0", "2", "Yes", "4096, 2176", "No", "4096, 2160"
|
||||
"gfx940, gfx942 - MI3xx", "VCN 3.0", "3", "Yes", "7680, 4320", "No", "4096, 2176"
|
||||
"gfx941 - MI3xx", "VCN 3.0", "4", "Yes", "7680, 4320", "No", "4096, 2176"
|
||||
"gfx1030, gfx1031, gfx1032 - Navi2x", "VCN 3.x", "2", "Yes", "7680, 4320", "No", "4096, 2176"
|
||||
"gfx1100, gfx1102 - Navi3x", "VCN 4.0", "2", "Yes", "7680, 4320", "No", "4096, 2176"
|
||||
"gfx1101 - Navi3x", "VCN 4.0", "1", "Yes", "7680, 4320", "No", "4096, 2176"
|
||||
@@ -0,0 +1,42 @@
|
||||
.. 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
|
||||
@@ -1 +0,0 @@
|
||||
tutorial/overview.md
|
||||
@@ -0,0 +1,14 @@
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="description" content="rocDecode API reference">
|
||||
<meta name="keywords" content="API reference, rocDecode, AMD, ROCm">
|
||||
</head>
|
||||
|
||||
# API reference
|
||||
|
||||
This section provides technical descriptions and important information about the different rocDecode
|
||||
APIs and library components.
|
||||
|
||||
* {doc}`Library <../doxygen/html/files>`
|
||||
* {doc}`Functions <../doxygen/html/globals>`
|
||||
* {doc}`Data structures <../doxygen/html/annotated>`
|
||||
+41
-33
@@ -1,34 +1,42 @@
|
||||
# Anywhere {branch} is used, the branch name will be substituted.
|
||||
# These comments will also be removed.
|
||||
root: doxygen/html/index
|
||||
defaults:
|
||||
numbered: False
|
||||
root: index
|
||||
subtrees:
|
||||
- caption: What is rocDecode?
|
||||
entries:
|
||||
- file: quick_overview
|
||||
- caption: Quick-start
|
||||
entries:
|
||||
- file: quickStart
|
||||
- caption: Hardware requirements
|
||||
entries:
|
||||
- file: tutorial/hardwareCapabilities
|
||||
- caption: API reference
|
||||
entries:
|
||||
- file: doxygen/html/files
|
||||
- caption: Tutorials
|
||||
entries:
|
||||
- file: tutorial/overview
|
||||
- file: tutorial/decodingPipeline
|
||||
- file: tutorial/usingAPI
|
||||
- caption: Samples
|
||||
entries:
|
||||
- file: samples
|
||||
subtrees:
|
||||
- entries:
|
||||
- file: videoDecode
|
||||
- file: videoDecodeMem
|
||||
- file: videoDecodeMultiFiles
|
||||
- file: videoDecodePerf
|
||||
- file: videoDecodeRGB
|
||||
- caption: About
|
||||
entries:
|
||||
- file: license
|
||||
- entries:
|
||||
- file: what-is-rocDecode.rst
|
||||
title: What is rocDecode?
|
||||
|
||||
- caption: Install
|
||||
entries:
|
||||
- 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-rocdecode.rst
|
||||
title: Use rocDecode
|
||||
|
||||
- caption: Conceptual
|
||||
entries:
|
||||
- file: conceptual/video-decoding-pipeline.rst
|
||||
title: Video decoding pipeline
|
||||
|
||||
- caption: Tutorials
|
||||
entries:
|
||||
- url: https://github.com/ROCm/rocDecode/tree/develop/samples
|
||||
title: GitHub samples
|
||||
|
||||
- caption: About
|
||||
entries:
|
||||
- file: license.md
|
||||
|
||||
@@ -1 +1 @@
|
||||
rocm-docs-core[api_reference]==0.30.3
|
||||
rocm-docs-core[api_reference]==0.35.0
|
||||
|
||||
@@ -8,15 +8,15 @@ accessible-pygments==0.0.4
|
||||
# via pydata-sphinx-theme
|
||||
alabaster==0.7.13
|
||||
# via sphinx
|
||||
babel==2.13.1
|
||||
babel==2.14.0
|
||||
# via
|
||||
# pydata-sphinx-theme
|
||||
# sphinx
|
||||
beautifulsoup4==4.12.2
|
||||
beautifulsoup4==4.12.3
|
||||
# via pydata-sphinx-theme
|
||||
breathe==4.35.0
|
||||
# via rocm-docs-core
|
||||
certifi==2023.11.17
|
||||
certifi==2024.2.2
|
||||
# via requests
|
||||
cffi==1.16.0
|
||||
# via
|
||||
@@ -31,7 +31,7 @@ click==8.1.7
|
||||
# sphinx-external-toc
|
||||
click-log==0.4.0
|
||||
# via doxysphinx
|
||||
cryptography==41.0.5
|
||||
cryptography==42.0.5
|
||||
# via pyjwt
|
||||
deprecated==1.2.14
|
||||
# via pygithub
|
||||
@@ -43,35 +43,41 @@ docutils==0.19
|
||||
# sphinx
|
||||
doxysphinx==3.3.7
|
||||
# via rocm-docs-core
|
||||
fastjsonschema==2.19.0
|
||||
fastjsonschema==2.19.1
|
||||
# via rocm-docs-core
|
||||
gitdb==4.0.11
|
||||
# via gitpython
|
||||
gitpython==3.1.40
|
||||
gitpython==3.1.42
|
||||
# via rocm-docs-core
|
||||
idna==3.4
|
||||
idna==3.6
|
||||
# via requests
|
||||
imagesize==1.4.1
|
||||
# via sphinx
|
||||
jinja2==3.1.2
|
||||
importlib-metadata==7.0.1
|
||||
# via sphinx
|
||||
importlib-resources==6.1.2
|
||||
# via
|
||||
# mpire
|
||||
# rocm-docs-core
|
||||
jinja2==3.1.3
|
||||
# via
|
||||
# myst-parser
|
||||
# sphinx
|
||||
libsass==0.22.0
|
||||
# via doxysphinx
|
||||
lxml==4.9.3
|
||||
lxml==4.9.4
|
||||
# via doxysphinx
|
||||
markdown-it-py==2.2.0
|
||||
# via
|
||||
# mdit-py-plugins
|
||||
# myst-parser
|
||||
markupsafe==2.1.3
|
||||
markupsafe==2.1.5
|
||||
# via jinja2
|
||||
mdit-py-plugins==0.3.5
|
||||
# via myst-parser
|
||||
mdurl==0.1.2
|
||||
# via markdown-it-py
|
||||
mpire==2.8.1
|
||||
mpire==2.10.0
|
||||
# via doxysphinx
|
||||
myst-parser==1.0.0
|
||||
# via rocm-docs-core
|
||||
@@ -81,19 +87,19 @@ packaging==23.2
|
||||
# sphinx
|
||||
pycparser==2.21
|
||||
# via cffi
|
||||
pydata-sphinx-theme==0.14.3
|
||||
pydata-sphinx-theme==0.14.4
|
||||
# via
|
||||
# rocm-docs-core
|
||||
# sphinx-book-theme
|
||||
pygithub==2.1.1
|
||||
pygithub==2.2.0
|
||||
# via rocm-docs-core
|
||||
pygments==2.17.1
|
||||
pygments==2.17.2
|
||||
# via
|
||||
# accessible-pygments
|
||||
# mpire
|
||||
# pydata-sphinx-theme
|
||||
# sphinx
|
||||
pyjson5==1.6.4
|
||||
pyjson5==1.6.6
|
||||
# via doxysphinx
|
||||
pyjwt[crypto]==2.8.0
|
||||
# via
|
||||
@@ -103,8 +109,8 @@ pynacl==1.5.0
|
||||
# via pygithub
|
||||
pyparsing==3.1.1
|
||||
# via doxysphinx
|
||||
python-dateutil==2.8.2
|
||||
# via pygithub
|
||||
pytz==2024.1
|
||||
# via babel
|
||||
pyyaml==6.0.1
|
||||
# via
|
||||
# myst-parser
|
||||
@@ -114,12 +120,10 @@ requests==2.31.0
|
||||
# via
|
||||
# pygithub
|
||||
# sphinx
|
||||
rocm-docs-core[api-reference]==0.30.3
|
||||
rocm-docs-core[api_reference]==0.35.0
|
||||
# via
|
||||
# -r requirements.in
|
||||
# rocm-docs-core
|
||||
six==1.16.0
|
||||
# via python-dateutil
|
||||
smmap==5.0.1
|
||||
# via gitdb
|
||||
snowballstemmer==2.2.0
|
||||
@@ -159,15 +163,19 @@ sphinxcontrib-qthelp==1.0.3
|
||||
# via sphinx
|
||||
sphinxcontrib-serializinghtml==1.1.5
|
||||
# via sphinx
|
||||
tqdm==4.66.1
|
||||
tqdm==4.66.2
|
||||
# via mpire
|
||||
typing-extensions==4.8.0
|
||||
typing-extensions==4.10.0
|
||||
# via
|
||||
# pydata-sphinx-theme
|
||||
# pygithub
|
||||
urllib3==2.1.0
|
||||
urllib3==2.2.1
|
||||
# via
|
||||
# pygithub
|
||||
# requests
|
||||
wrapt==1.16.0
|
||||
# via deprecated
|
||||
zipp==3.17.0
|
||||
# via
|
||||
# importlib-metadata
|
||||
# importlib-resources
|
||||
|
||||
@@ -1,18 +0,0 @@
|
||||
# Video decoding pipeline
|
||||
|
||||
<p align="center"><img width="70%" src="../data/VideoDecoderPipeline.png" /></p>
|
||||
|
||||
There are three main components in the rocDecode shown in the figure above: Demuxer, Video Parser APIs, and Video Decode APIs.
|
||||
The Demuxer is based on FFMPEG. The demuxer extracts a segment of video data and sends it to the Video Parser. The parser then extracts crucial information such as picture and slice parameters, which is then sent to the Decoder APIs. These APIs submit the information to the hardware for the decoding of a frame. This process repeats in a loop until all frames have been decoded.
|
||||
|
||||
Steps in decoding video content for applications (available in rocDecode Toolkit)
|
||||
|
||||
1. Demultiplex the content into elementary stream packets (FFmpeg)
|
||||
2. Parse the demultiplexed packets into video frames for the decoder provided by rocDecode API.
|
||||
3. Decode compressed video frames into YUV frames using rocDecode API.
|
||||
4. Wait for the decoding to finish.
|
||||
5. Map the decoded YUV frame from amd-gpu context to HIP (using VAAPI-HIP under ROCm)
|
||||
6. Execute HIP kernels in the mapped YUV frame (e.g., format conversion, scaling, object detection, classification, etc.)
|
||||
7. Un-map decoded HIP YUV frame.
|
||||
|
||||
The above steps are demonstrated in the sample applications included in the repository.
|
||||
@@ -1,13 +0,0 @@
|
||||
# rocDecode hardware capabilities
|
||||
|
||||
The table below shows the codec support and capabilities of the VCN for each GPU architecture supported by rocDecode.
|
||||
|
||||
| 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 | No | 4096, 2160 |
|
||||
| gfx90a - MI2xx | VCN 2.6.0 | 2 | Yes | 4096, 2176 | No | 4096, 2160 |
|
||||
| gfx940, gfx942 - MI3xx | VCN 3.0 | 3 | Yes | 7680, 4320 | No | 4096, 2176 |
|
||||
| gfx941 - MI3xx | VCN 3.0 | 4 | Yes | 7680, 4320 | No | 4096, 2176 |
|
||||
| gfx1030, gfx1031, gfx1032 - Navi2x | VCN 3.x | 2 | Yes | 7680, 4320 | No | 4096, 2176 |
|
||||
| gfx1100, gfx1102 - Navi3x | VCN 4.0 | 2 | Yes | 7680, 4320 | No | 4096, 2176 |
|
||||
| gfx1101 - Navi3x | VCN 4.0 | 1 | Yes | 7680, 4320 | No | 4096, 2176 |
|
||||
@@ -1,7 +0,0 @@
|
||||
# rocDecode overview
|
||||
|
||||
AMD GPUs contain one or more media engines (VCNs) that provide fully accelerated hardware-based video 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.
|
||||
|
||||
This document describes AMD's rocDecode SDK library which provides APIs, utilities, and samples, allowing the developers to access the video decoding features of VCNs easily. Furthermore, it allows interoperability with other compute engines on the GPU using VA-API/HIP interop. rocDecode API facilitates decoding of the compressed video streams and keeps the resulting YUV frames in video memory. With decoded frames in video memory, video post-processing can be executed using ROCm HIP, thereby avoiding unnecessary data copies via PCIe bus. The video frames can further be post-processed using scaling/color-conversion and augmentation kernels (on GPU or host) and be in a format for GPU/CPU accelerated inferencing/training.
|
||||
|
||||
In addition, rocDecode API can be used to create multiple instances of video decoder based on the number of available VCN engines in a GPU device. By configuring the decoder for a device, all the available engines can be used seamlessly for decoding a batch of video streams in parallel.
|
||||
@@ -1,115 +0,0 @@
|
||||
# Using rocDecode API
|
||||
|
||||
All rocDecode APIs are exposed in the two header files: `rocdecode.h` and `rocparser.h`. These headers can be found under the `api` folder in this repository.
|
||||
|
||||
The samples use the `RocVideoDecoder` user class provided in `roc_video_dec.h` under the `utils` folder in this repository.
|
||||
|
||||
## Video parser (defined in rocparser.h)
|
||||
|
||||
A Video Parser is needed to extract and decode headers from the bitstream to organize the data into a structured format required for the hardware decoder. The parser plays an important role in video decoding as it controls the decoding and display of the individual frames/fields of a bitstream.
|
||||
|
||||
The parser object in `rocparser.h` has 3 main apis as described below
|
||||
|
||||
## Creating parser object using rocDecCreateVideoParser()
|
||||
|
||||
This API creates a video parser object for the Codec specified by the user. The API takes `max_num_decode_surfaces` which determines the DPB (Decoded Picture Buffer) size for decoding. When creating a parser object, the application must register certain callback functions with the driver which will be called from the parser during the decode.
|
||||
|
||||
* `pfn_sequence_callback` will be called when the parser encounters a new sequence header. The parser informs the user of the minimum number of surfaces needed by the parser's DPB for successful decoding of the bitstream. In addition, the caller can set additional parameters like `max_display_delay` to control the decoding and displaying of the frames.
|
||||
* `pfn_decode_picture` callback function will be triggered when a picture is ready to be decoded.
|
||||
* `pfn_display_picture` callback function will be triggered when a frame in display order is ready to be consumed by the caller.
|
||||
* `pfn_get_sei_msg` callback function will be triggered when a user SEI message is parsed by the parser and sent back to the caller.
|
||||
|
||||
## Parsing video data using rocDecParseVideoData()
|
||||
|
||||
Elementary stream video packets extracted from the demultiplexer are fed into the parser using the `rocDecParseVideoData()` API. During this call, the parser triggers the above callbacks as it encounters a new sequence header, gets a compressed frame/field data ready to be decoded, or when it is ready to display a frame. If any of the callbacks returns failure, it will be propagated back to the application so the decoding can be terminated gracefully.
|
||||
|
||||
## Destroying the parser using rocDecDestroyVideoParser()
|
||||
|
||||
The user needs to call `rocDecDestroyVideoParser()` to destroy the parser object and free up all allocated resources at the end of video decoding.
|
||||
|
||||
## Querying decode capabilities using rocDecGetDecoderCaps() (defined in rocdecode.h)
|
||||
|
||||
`rocDecGetDecoderCaps()` Allows users to query the capabilities of underlying hardware video decoder as different hardware will have different capabilities. Caps usually inform the user of the supported codecs, max. resolution, bit-depth, etc.
|
||||
|
||||
The following pseudo-code illustrates the use of this API. If any of the decoder caps are not supported, the application is supposed to handle the error appropriately.
|
||||
|
||||
RocdecDecodeCaps decode_caps;
|
||||
memset(&decode_caps, 0, sizeof(decode_caps));
|
||||
decode_caps.codec_type = p_video_format->codec;
|
||||
decode_caps.chroma_format = p_video_format->chroma_format;
|
||||
decode_caps.bit_depth_minus_8 = p_video_format->bit_depth_luma_minus8;
|
||||
|
||||
ROCDEC_API_CALL(rocDecGetDecoderCaps(&decode_caps));
|
||||
|
||||
if(!decode_caps.is_supported) {
|
||||
ROCDEC_THROW("Rocdec:: Codec not supported on this GPU: ", ROCDEC_NOT_SUPPORTED);
|
||||
return 0;
|
||||
}
|
||||
|
||||
if ((p_video_format->coded_width > decode_caps.max_width) ||
|
||||
(p_video_format->coded_height > decode_caps.max_height)) {
|
||||
|
||||
std::ostringstream errorString;
|
||||
errorString << std::endl
|
||||
<< "Resolution : " << p_video_format->coded_width << "x" << p_video_format->coded_height << std::endl
|
||||
<< "Max Supported (wxh) : " << decode_caps.max_width << "x" << decode_caps.max_height << std::endl
|
||||
<< "Resolution not supported on this GPU ";
|
||||
|
||||
const std::string cErr = errorString.str();
|
||||
ROCDEC_THROW(cErr, ROCDEC_NOT_SUPPORTED);
|
||||
return 0;
|
||||
}
|
||||
|
||||
## Creating a Decoder using rocDecCreateDecoder()
|
||||
Creates an instance of the hardware video decoder object and gives a handle to the user on successful creation. Refer to `RocDecoderCreateInfo` structure for information about parameters that are passed for creating the decoder. E.g. `RocDecoderCreateInfo::codec_type` represents the codec type of the video. The decoder handle returned by the `rocDecCreateDecoder()` must be retained for the entire session of the decode because the handle is passed along with the other decoding APIs. In addition, users can inform display or crop dimensions along with this API.
|
||||
|
||||
## Decoding the frame using rocDecDecodeFrame()
|
||||
After de-muxing and parsing, the next step is to decode bitstream data containing a frame/field using hardware. `rocDecDecodeFrame()` API is to submit a new frame for hardware decoding. Underneath the driver, VA-API is used to submit compressed picture data to the driver. The parser extracts all the necessary information from the bitstream and fills the "RocdecPicParams" struct which is appropriate for the codec used. The high-level `RocVideoDecoder` class connects the parser and decoder which is used for all the sample applications.
|
||||
The `rocDecDecodeFrame()` call takes the decoder handle and the pointer to RocdecPicParams structure and kicks off video decoding using VA-API.
|
||||
|
||||
## Preparing the decoded frame for further processing
|
||||
The decoded frames can be used for further postprocessing using the `rocDecGetVideoFrame()` API call. The successful completion of `rocDecGetVideoFrame()` indicates that the decoding process is completed and the device memory pointer is inter-opped into ROCm HIP address space for further processing of the decoded frame in device memory. The caller will get all the necessary information on the output surface like YUV format, dimensions, pitch, etc. from this call. In the high-level `RocVideoDecoder` class, we provide 4 different surface type modes for the mapped surface as specified in OutputSurfaceMemoryType as explained below.
|
||||
|
||||
typedef enum OutputSurfaceMemoryType_enum {
|
||||
OUT_SURFACE_MEM_DEV_INTERNAL = 0, /**< Internal interopped decoded surface memory **/
|
||||
OUT_SURFACE_MEM_DEV_COPIED = 1, /**< decoded output will be copied to a separate device memory **/
|
||||
OUT_SURFACE_MEM_HOST_COPIED = 2 /**< decoded output will be copied to a separate host memory **/
|
||||
OUT_SURFACE_MEM_NOT_MAPPED = 3 /**< decoded output is not available (interop won't be used): useful for decode only performance app*/
|
||||
} OutputSurfaceMemoryType;
|
||||
|
||||
If the mapped surface type is `OUT_SURFACE_MEM_DEV_INTERNAL`, the direct pointer to the decoded surface is given to the user. The user is supposed to trigger `rocDecUnMapVideoFrame()` using the `ReleaseFrame()` call of the RocVideoDecoder class. If the requested surface type `OUT_SURFACE_MEM_DEV_COPIED` or `OUT_SURFACE_MEM_HOST_COPIED`, the internal decoded frame will be copied to another buffer either in device memory or host memory. After that, it is immediately unmapped for re-use by the RocVideoDecoder class.
|
||||
In all the cases, the user needs to call `rocDecUnMapVideoFrame()` to indicate that the frame is ready to be used for decoding again.
|
||||
Please refer to the RocVideoDecoder class and samples for detailed use of these APIs.
|
||||
|
||||
## Querying the decoding status
|
||||
The `rocDecGetDecodeStatus()` can be called at any time to query the status of the decoding for a given frame. A struct pointer `RocdecDecodeStatus*` will be filled and returned to the user.
|
||||
|
||||
The inputs to the API are:
|
||||
* decoder_handle: A rocdec decoder handler `rocDecDecoderHandle`.
|
||||
* pic_idx: An int value for the picIdx for which the user wants a status.
|
||||
* decode_status: A pointer to `RocdecDecodeStatus` as a return value.
|
||||
|
||||
The API returns one of the following statuses:
|
||||
* Invalid (0): Decode status is not valid.
|
||||
* In Progress (1): Decoding is in progress.
|
||||
* Success (2): Decoding was successful and no errors were returned.
|
||||
* Error (8): The frame was corrupted, but the error was not concealed.
|
||||
* Error Concealed (9): The frame was corrupted and the error was concealed.
|
||||
* Displaying (10): Decode is completed, displaying in progress.
|
||||
|
||||
## Reconfiguring the decoder
|
||||
The `rocDecReconfigureDecoder()` can be called to reuse a single decoder for multiple clips or when the video resolution changes during the decode. The API currently supports resolution changes, resize parameter changes, and target area parameter changes for the same codec without having to destroy the ongoing decoder instance and create a new one. This can improve performance and reduce the overall latency.
|
||||
|
||||
The inputs to the API are:
|
||||
* decoder_handle: A rocdec decoder handler `rocDecDecoderHandle`.
|
||||
* reconfig_params: The user needs to specify the parameters for the changes in `RocdecReconfigureDecoderInfo`. The width and height used for reconfiguration cannot exceed the values set for max_width and max_height defined at RocDecoderCreateInfo. If these values need to be changed, the session needs to be destroyed and recreated.
|
||||
|
||||
The call to the `rocDecReconfigureDecoder()` must be called during `RocdecParserParams::pfn_sequence_callback`.
|
||||
|
||||
## Destroying the decoder
|
||||
The user needs to call the `rocDecDestroyDecoder()` to destroy the session and free up resources.
|
||||
|
||||
The inputs to the API are:
|
||||
* decoder_handle: A rocdec decoder handler `rocDecDecoderHandle`.
|
||||
|
||||
The API returns a `RocdecDecodeStatus` value.
|
||||
@@ -0,0 +1,26 @@
|
||||
.. meta::
|
||||
:description: What is rocDecode?
|
||||
:keywords: video decoding, rocDecode, AMD, ROCm
|
||||
|
||||
********************************************************************
|
||||
What is rocDecode?
|
||||
********************************************************************
|
||||
|
||||
AMD GPUs contain one or more media engines (VCNs) that provide fully accelerated, hardware-based
|
||||
video 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 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
|
||||
frames 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 rocDecode API to create multiple instances of video decoder based on the
|
||||
number of available VCNs in a GPU device. By configuring the decoder for a device, all available
|
||||
VCNs can be used seamlessly for decoding a batch of video streams in parallel.
|
||||
|
||||
For more information, refer to the
|
||||
:doc:`Video decoding pipeline <./conceptual/video-decoding-pipeline>`.
|
||||
Reference in New Issue
Block a user