Add 'projects/rocdecode/' from commit 'b0bab079403eda171f9056409fa96b0908f61073'
git-subtree-dir: projects/rocdecode git-subtree-mainline:5d609c1e57git-subtree-split:b0bab07940
This commit is contained in:
Ameya Keshava Mallya
@@ -0,0 +1,37 @@
|
||||
.. meta::
|
||||
:description: Using rocDecode
|
||||
:keywords: parse video, parse, decode, video decoder, video decoding, rocDecode, core APIs, AMD, ROCm
|
||||
|
||||
********************************************************************
|
||||
The rocDecode core APIs
|
||||
********************************************************************
|
||||
|
||||
The rocDecode core APIs are intended for users who want to have full control of the decoding pipeline and interact with the core components instead of the utility classes. The :doc:`Using the rocDecode videodecode sample <../how-to/using-rocDecode-videodecode-sample>` provides an introduction to using the utility classes.
|
||||
|
||||
The rocDecode core APIs are exposed in header files in the |apifolder|_ folder of the `rocDecode GitHub repository <https://github.com/ROCm/rocDecode>`_.
|
||||
|
||||
:doc:`The rocDecode parser API <./rocDecode-parser>` is exposed in |rocparser|_. It contains functions that create and destroy the parser, as well as functions that parse the bitstream.
|
||||
|
||||
:doc:`The hardware decoder API <./rocDecode-hw-decoder>` is exposed in |rocdecode|_. It contains functions that create, control, and destroy the decoder, as well as functions that decode the parsed frames on the GPU.
|
||||
|
||||
:doc:`The software decoder API <./rocDecode-sw-decoder>` is exposed in |rocdecodehost|_. It contains the same functionality as ``rocdecode.h``, but all the operations are run on the host rather than the GPU.
|
||||
|
||||
:doc:`The bitstream reader API <../how-to/using-rocDecode-bitstream>` is exposed in |bitstreamreader|_. It provides an alternative to the FFMpeg demuxer and contains a simple stream file parser that can read elementary files and IVF container files.
|
||||
|
||||
.. |apifolder| replace:: ``api/rocdecode``
|
||||
.. _apifolder: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode
|
||||
|
||||
.. |rocparser| replace:: ``api/rocdecode/rocparser.h``
|
||||
.. _rocparser: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocparser.h
|
||||
|
||||
.. |rocdecode| replace:: ``api/rocDecode/rocdecode.h``
|
||||
.. _rocdecode: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocdecode.h
|
||||
|
||||
.. |rocdecodehost| replace:: ``api/rocDecode/rocdecode_host.h``
|
||||
.. _rocdecodehost: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocdecode_host.h
|
||||
|
||||
.. |bitstreamreader| replace:: ``api/rocDecode/roc_bitstream_reader.h``
|
||||
.. _bitstreamreader: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/roc_bitstream_reader.h
|
||||
|
||||
.. |utilsfolder| replace:: ``utils`` folder
|
||||
.. _utilsfolder: https://github.com/ROCm/rocDecode/tree/develop/utils
|
||||
@@ -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
|
||||
* VP9: 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", "AV1", "Max width, Max height - AV1", "VP9", "Max width, Max height - VP9"
|
||||
|
||||
"gfx908 - MI1xx", "VCN 2.5.0", "2", "Yes", "7680, 4320", "Yes", "4096, 2160", "No", "N/A, N/A", "Yes", "7680, 4320"
|
||||
"gfx90a - MI2xx", "VCN 2.6.0", "2", "Yes", "7680, 4320", "Yes", "4096, 2160", "No", "N/A, N/A", "Yes", "7680, 4320"
|
||||
"gfx942 - MI3xx", "VCN 4.0", "3/4", "Yes", "7680, 4320", "Yes", "4096, 2176", "Yes", "8192, 4352", "Yes", "7680, 4320"
|
||||
"gfx1030, gfx1031, gfx1032 - Navi2x", "VCN 3.x", "2", "Yes", "7680, 4320", "Yes", "4096, 2176", "Yes", "8192, 4352", "Yes", "7680, 4320"
|
||||
"gfx1100, gfx1102 - Navi3x", "VCN 4.0", "2", "Yes", "7680, 4320", "Yes", "4096, 2176", "Yes", "8192, 4352", "Yes", "7680, 4320"
|
||||
"gfx1101 - Navi3x", "VCN 4.0", "1", "Yes", "7680, 4320", "Yes", "4096, 2176", "Yes", "8192, 4352", "Yes", "7680, 4320"
|
||||
@@ -0,0 +1,62 @@
|
||||
.. meta::
|
||||
:description: The rocDecode hardware decoder
|
||||
:keywords: decode, video decoder, video decoding, rocDecode, core APIs, AMD, ROCm
|
||||
|
||||
********************************************************************
|
||||
The rocDecode hardware decoder API
|
||||
********************************************************************
|
||||
|
||||
The rocDecode hardware decoder API exposed in |rocdecode|_ is used to decode frames that were parsed by :doc:`the rocDecode parser <./rocDecode-parser>`.
|
||||
|
||||
Parsing parameters are stored in the ``RocDecoderCreateInfo`` struct and passed to ``rocDecCreateDecoder()`` to create a new decoder. ``rocDecCreateDecoder()`` returns a handle to the decoder. For example:
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
RocDecoderCreateInfo create_info = {};
|
||||
create_info.codec_type = dec_info.rocdec_codec_id; // user specified codec_type for raw files
|
||||
create_info.max_width = DEFAULT_WIDTH;
|
||||
create_info.max_height = DEFAULT_HEIGHT;
|
||||
create_info.width = DEFAULT_WIDTH;
|
||||
create_info.height = DEFAULT_HEIGHT;
|
||||
create_info.num_decode_surfaces = 6;
|
||||
create_info.num_output_surfaces = 1;
|
||||
rocDecCreateDecoder(&decoder_handle, &create_info);
|
||||
|
||||
|
||||
``rocDecGetDecoderCaps()`` queries the capabilities of the underlying hardware video decoder. Decoder capabilities usually include supported codecs, maximum resolution, and
|
||||
bit depth.
|
||||
|
||||
``rocDecDecodeFrame()`` is used to submit frames for hardware decoding. This function must be called when the ``pfn_decode_picture`` callback is triggered in the ``rocDecParseVideoData()`` call. See :doc:`The rocDecode parser API <./rocDecode-parser>` for details about this call.
|
||||
|
||||
``rocDecDecodeFrame()`` takes the decoder handle and the pointer to the ``RocdecPicParams()`` struct and initiates the video decoding using VA-API. ``RocdecPicParams`` is populated with the decoded frame information.
|
||||
|
||||
The ``pfn_sequence_callback`` callback is triggered when a format change occurs or when a new sequence header is encountered. The implementation of ``pfn_sequence_callback`` must call ``rocDecReconfigureDecoder()`` to reconfigure the decoder to handle the new sequence or format. See :doc:`The rocDecode parser API <./rocDecode-parser>` for details about this callback.
|
||||
|
||||
``rocDecGetDecodeStatus()`` can be called to query the decoding status of a frame. The result of the query is either ``rocDecodeStatus_Success``, if decoding is complete, or ``rocDecodeStatus_InProgress``, if decoding is still in progress.
|
||||
|
||||
The ``pfn_display_picture`` callback is triggered when a frame has been decoded. The decoded frame can then be further processed in device memory. The implementation for this callback must call ``rocDecGetVideoFrame()`` to obtain the decoded frame's HIP device pointer.
|
||||
|
||||
``rocDecGetVideoFrame()`` provides a way to access the decoded frame in HIP. This is a blocking call that only returns once frame decoding and memory mapping is complete. It returns the HIP device pointer as well as information about the :doc:`output surface type <../conceptual/rocDecode-memory-types>`.
|
||||
|
||||
If the output surface type is ``OUT_SURFACE_MEM_DEV_INTERNAL``, meaning intermediate GPU memory, the direct pointer to the decoded surface is provided. 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.
|
||||
|
||||
Once decoding is complete, ``rocDecDestroyVideoParser()`` and ``rocDecDestroyDecoder()`` must be called to destroy the parser and the decoding session, and free resources.
|
||||
|
||||
.. |apifolder| replace:: ``api/rocdecode``
|
||||
.. _apifolder: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode
|
||||
|
||||
.. |rocparser| replace:: ``api/rocdecode/rocparser.h``
|
||||
.. _rocparser: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocparser.h
|
||||
|
||||
.. |rocdecode| replace:: ``api/rocDecode/rocdecode.h``
|
||||
.. _rocdecode: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocdecode.h
|
||||
|
||||
.. |rocdecodehost| replace:: ``api/rocDecode/rocdecode_host.h``
|
||||
.. _rocdecodehost: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocdecode_host.h
|
||||
|
||||
.. |bitstreamreader| replace:: ``api/rocDecode/roc_bitstream_reader.h``
|
||||
.. _bitstreamreader: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/roc_bitstream_reader.h
|
||||
|
||||
.. |utilsfolder| replace:: ``utils`` folder
|
||||
.. _utilsfolder: https://github.com/ROCm/rocDecode/tree/develop/utils
|
||||
@@ -0,0 +1,53 @@
|
||||
.. meta::
|
||||
:description: rocDecode logging controls
|
||||
:keywords: rocDecode, core APIs, logging, AMD, ROCm
|
||||
|
||||
********************************************************************
|
||||
rocDecode logging control
|
||||
********************************************************************
|
||||
|
||||
rocDecode core components can be configured to output different levels of log messages during decoding.
|
||||
|
||||
The log level can be changed by either setting the log level through the ``ROCDEC_LOG_LEVEL`` environment variable, or by calling the ``RocDecLogger::SetLogLevel()`` function in |commons|_.
|
||||
|
||||
The logging levels are:
|
||||
|
||||
| 0: Critical (Default level)
|
||||
| 1: Error
|
||||
| 2: Warning
|
||||
| 3: Info
|
||||
| 4: Debug
|
||||
|
||||
The log level defines the maximum severity of log messages to output. For example, to output warning and error messages as well as critical messages, ``ROCDEC_LOG_LEVEL`` would need to be set to 2:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
ROCDEC_LOG_LEVEL = 2
|
||||
|
||||
or
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
SetLogLevel(2);
|
||||
|
||||
|
||||
.. |apifolder| replace:: ``api/rocdecode``
|
||||
.. _apifolder: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode
|
||||
|
||||
.. |rocparser| replace:: ``api/rocdecode/rocparser.h``
|
||||
.. _rocparser: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocparser.h
|
||||
|
||||
.. |rocdecode| replace:: ``api/rocDecode/rocdecode.h``
|
||||
.. _rocdecode: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocdecode.h
|
||||
|
||||
.. |rocdecodehost| replace:: ``api/rocDecode/rocdecode_host.h``
|
||||
.. _rocdecodehost: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocdecode_host.h
|
||||
|
||||
.. |bitstreamreader| replace:: ``api/rocDecode/roc_bitstream_reader.h``
|
||||
.. _bitstreamreader: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/roc_bitstream_reader.h
|
||||
|
||||
.. |utilsfolder| replace:: ``utils`` folder
|
||||
.. _utilsfolder: https://github.com/ROCm/rocDecode/tree/develop/utils
|
||||
|
||||
.. |commons| replace:: ``commons.h``
|
||||
.. _commons: https://github.com/ROCm/rocDecode/tree/develop/src/commons.h
|
||||
@@ -0,0 +1,54 @@
|
||||
.. meta::
|
||||
:description: The rocDecode parser API
|
||||
:keywords: parse video, parser, decode, video decoder, video decoding, rocDecode, core APIs, AMD, ROCm
|
||||
|
||||
********************************************************************
|
||||
The rocDecode parser API
|
||||
********************************************************************
|
||||
|
||||
The rocDecode parser API, exposed in |rocparser|_, is used to decode bitstreams and organize them in a structured format that can be consumed by the hardware decoder.
|
||||
|
||||
The parser parameters are stored in the ``RocdecParserParams`` struct and passed to ``rocDecCreateVideoParser()`` to create a new parser. ``rocDecCreateVideoParser()`` returns a handle to the parser. For example:
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
RocdecParserParams params = {};
|
||||
params.codec_type = rocdec_codec_id;
|
||||
params.max_num_decode_surfaces = 6;
|
||||
params.max_display_delay = 1;
|
||||
params.user_data = &dec_info;
|
||||
rocDecCreateVideoParser(&parser_handle, ¶ms);
|
||||
|
||||
Elementary stream video packets extracted from the demultiplexer (demuxer) are passed to the parser using the ``RocdecSourceDataPacket`` struct. Packet information in ``RocdecSourceDataPacket`` is passed to ``rocDecParseVideoData()``. For example:
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
RocdecSourceDataPacket packet = {};
|
||||
packet.payload_size = frames[i].size();
|
||||
packet.payload = frames[i].data();
|
||||
rocDecParseVideoData(parser_handle, &packet);
|
||||
|
||||
Three callbacks must be registered when the parser is used: ``pfn_decode_picture``, ``pfn_sequence_callback``, and ``pfn_display_picture``. These callbacks are triggered in the ``rocDecParseVideoData()`` call.
|
||||
|
||||
``pfn_decode_picture`` is triggered when a picture is ready for decoding. Its implementation must call ``rocDecDecodeFrame()`` from the hardware decoder API.
|
||||
|
||||
``pfn_sequence_callback`` is triggered when a new sequence header is encountered or when there's a format change. Its implementation handles reconfiguring the decoder to handle the new frame format. Its implementation must call ``rocDecReconfigureDecoder()`` from the hardware decoder API.
|
||||
|
||||
``pfn_display_picture`` is triggered when a frame has been decoded. Its implementation must call ``rocDecGetVideoFrame()`` from the hardware decoder API.
|
||||
|
||||
A fourth callback, ``pfn_get_sei_msg``, is optional. ``pfn_get_sei_msg`` is triggered when a Supplementation Enhancement Information (SEI) message is parsed and returned to the caller.
|
||||
|
||||
If any of the callbacks return an error, the error is propagated back to the application.
|
||||
|
||||
Once the stream is fully decoded, ``rocDecDestroyVideoParser()`` must be called to destroy the parser object and free all allocated resources.
|
||||
|
||||
|
||||
|
||||
.. |rocparser| replace:: ``rocparser.h``
|
||||
.. _rocparser: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocparser.h
|
||||
|
||||
.. |utilsfolder| replace:: ``utils`` folder
|
||||
.. _utilsfolder: https://github.com/ROCm/rocDecode/tree/develop/utils
|
||||
|
||||
.. |rocdecdecode| replace:: ``rocdecdecode.cpp``
|
||||
.. _rocdecdecode: https://github.com/ROCm/rocDecode/tree/develop/samples/rocdecDecode/rocdecdecode.cpp
|
||||
@@ -0,0 +1,61 @@
|
||||
.. meta::
|
||||
:description: The rocDecode software decoder
|
||||
:keywords: decode, video decoder, video decoding, rocDecode, core APIs, AMD, ROCm
|
||||
|
||||
********************************************************************
|
||||
The rocDecode software decoder API
|
||||
********************************************************************
|
||||
|
||||
The rocDecode software decoder API exposed in |rocdecodehost|_ is used to decode frames that have been demultiplexed (demuxed) by :doc:`the FFmpeg demuxer <../how-to/using-rocDecode-ffmpeg>`.
|
||||
|
||||
Decoding parameters are stored in the ``RocDecoderHostCreateInfo`` struct and passed to ``rocDecCreateDecoderHost()`` to create a new software decoder. ``rocDecCreateDecoderHost()`` returns a handle to the decoder. For example:
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
RocDecoderHostCreateInfo create_info = {};
|
||||
create_info.codec_type = rocdec_codec_id;
|
||||
create_info.num_decode_threads = 0; // default
|
||||
create_info.max_width = DEFAULT_WIDTH;
|
||||
create_info.max_height = DEFAULT_HEIGHT;
|
||||
create_info.chroma_format = rocDecVideoChromaFormat_420;
|
||||
create_info.output_format = rocDecVideoSurfaceFormat_P016;
|
||||
create_info.bit_depth_minus_8 = 2;
|
||||
create_info.num_output_surfaces = 1;
|
||||
create_info.user_data = &dec_info;
|
||||
rocDecCreateDecoderHost(&dec_info.decoder, &create_info);
|
||||
|
||||
``rocDecGetDecoderCapsHost()`` queries the capabilities of the underlying software video decoder. Decoder capabilities usually include supported codecs, maximum resolution, and
|
||||
bit depth.
|
||||
|
||||
``rocDecDecodeFrameHost()`` is used to submit frames for software decoding. ``rocDecDecodeFrameHost()`` takes the decoder handle and the pointer to the ``RocdecPicParamsHost`` struct and initiates the video decoding. ``RocdecPicParamsHost`` is populated with the decoded frame information.
|
||||
|
||||
The ``pfn_sequence_callback`` callback is triggered when a format change occurs or when a new sequence header is encountered. This callback must be registered in any application that uses the software decoder and its implementation must call ``rocDecReconfigureDecoderHost()`` to reconfigure the decoder to handle the new sequence or format.
|
||||
|
||||
``rocDecGetDecodeStatusHost()`` can be called to query the decoding status of a frame. The result of the query is either ``rocDecodeStatus_Success``, if decoding is complete, or ``rocDecodeStatus_InProgress``, if decoding is still in progress.
|
||||
|
||||
The ``pfn_display_picture`` callback is triggered when a frame has been decoded. This callback must be registered by any application that uses the software decoder and its implementation must call ``rocDecGetVideoFrameHost()``. ``rocDecGetVideoFrameHost()`` returns the decoded frame's host memory pointer. The decoded frame can then be further processed using this pointer.
|
||||
|
||||
``rocDecGetVideoFrameHost()`` provides a way to access the decoded frame in host memory. This is a blocking call that only returns once both frame decoding and memory mapping are done. It returns the host memory pointer as well as information about the :doc:`output surface type <../conceptual/rocDecode-memory-types>`.
|
||||
|
||||
If the output surface type is ``OUT_SURFACE_MEM_DEV_INTERNAL``, meaning intermediate GPU memory, the direct pointer to the decoded surface is provided. 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.
|
||||
|
||||
Once decoding is complete, ``rocDecDestroyDecoderHost()`` must be called to destroy the decoder and free resources.
|
||||
|
||||
.. |apifolder| replace:: ``api/rocdecode``
|
||||
.. _apifolder: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode
|
||||
|
||||
.. |rocparser| replace:: ``api/rocdecode/rocparser.h``
|
||||
.. _rocparser: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocparser.h
|
||||
|
||||
.. |rocdecode| replace:: ``api/rocDecode/rocdecode.h``
|
||||
.. _rocdecode: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocdecode.h
|
||||
|
||||
.. |rocdecodehost| replace:: ``api/rocDecode/rocdecode_host.h``
|
||||
.. _rocdecodehost: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/rocdecode_host.h
|
||||
|
||||
.. |bitstreamreader| replace:: ``api/rocDecode/roc_bitstream_reader.h``
|
||||
.. _bitstreamreader: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode/roc_bitstream_reader.h
|
||||
|
||||
.. |utilsfolder| replace:: ``utils`` folder
|
||||
.. _utilsfolder: https://github.com/ROCm/rocDecode/tree/develop/utils
|
||||
Reference in New Issue
Block a user