Docs - Core api reference refresh (#669)
* Updated core docs + Doxyfile
* fixed issues, renamed a file, deleted unused files
* added hip-dev as a requirement for 7.2
* updated with Jeff's review
* updated getvideoframe description
* Update docs/reference/rocDecode-parser.rst
Co-authored-by: Leo Paoletti <164940351+lpaoletti@users.noreply.github.com>
* Update docs/how-to/using-rocDecode-video-decoder.rst
Co-authored-by: Leo Paoletti <164940351+lpaoletti@users.noreply.github.com>
* updated with Leo's feedback
* fixed a wrong link in toc
---------
Co-authored-by: Kiriti Gowda <kiritigowda@gmail.com>
Co-authored-by: Leo Paoletti <164940351+lpaoletti@users.noreply.github.com>
[ROCm/rocdecode commit: 134369824d]
This commit is contained in:
spolifroni-amd
GitHub
@@ -0,0 +1,245 @@
|
||||
.. meta::
|
||||
:description: Using the rocDecode core API
|
||||
:keywords: rocDecode, AMD, ROCm, core API
|
||||
|
||||
********************************************************************
|
||||
Using the rocdecdecode example
|
||||
********************************************************************
|
||||
|
||||
rocDecode provides four core APIs exposed in the header files in the |apifolder|_ directory:
|
||||
|
||||
| The rocDecode parser API, exposed in ``rocparser.h``.
|
||||
| The hardware decoder API, exposed in ``rocdecode.h``.
|
||||
| The software decoder API, exposed in ``rocdecode_host.h``.
|
||||
| The bitstream reader API, exposed in ``roc_bitstream_reader.h``.
|
||||
|
||||
The |rocdecdecode|_ sample demonstrates how to use the rocDecode core APIs in an application. It shows how to use the parser and both the hardware and software decoders. For information on how to use the bitstream reader API, see :doc:`Using the rocDecode bitstream reader API <./using-rocDecode-bitstream>`.
|
||||
|
||||
The sample decodes raw elementary video frame files as input and produces individually decoded frames in YUV format as output. The input can be one individual frame file or multiple frames from one or more video files. The individual frame files must be numbered in ascending order of frames.
|
||||
|
||||
``rocdecdecode.cpp`` takes the following arguments:
|
||||
|
||||
.. list-table::
|
||||
:widths: 10 60 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Argument
|
||||
- Description
|
||||
- Note
|
||||
|
||||
* - ``-i``
|
||||
- Path to the input video frame file or to frame folder.
|
||||
- Required.
|
||||
|
||||
* - ``-o``
|
||||
- Output path. Saves the decoded YUV frames to this folder.
|
||||
- Optional. Decoded frames aren't saved by default.
|
||||
|
||||
* - ``-d``
|
||||
- GPU device ID. Set it to 0 for the first device, 1 for the second device, 2 for the third device, and so on for each subsequent device.
|
||||
- Optional. Set to 0 by default.
|
||||
|
||||
* - ``-b``
|
||||
- Backend. Set it to 0 to use the hardware decoder on the GPU or to 1 to use the software decoder on the CPU.
|
||||
- Optional. Set to 0 by default.
|
||||
|
||||
|
||||
* - ``-c``
|
||||
- Codec. Set to 0 for HEVC, 1 for H264, 2 for AV1, 4 for VP9, 5 for VP8, or 6 for MJPEG.
|
||||
- Optional. Set to 0 by default.
|
||||
|
||||
* - ``-n``
|
||||
- Number of iterations for performance evaluation.
|
||||
- Optional. Set to 1 by default.
|
||||
|
||||
* - ``-m``
|
||||
- The output surface memory type. The memory type where the surface data, such as the decoded frames, resides. Set this to 0 for intermediate GPU memory, to 1 for GPU memory, and to 2 for CPU memory. See :doc:`Surface data memory locations <../conceptual/rocDecode-memory-types>` for more information.
|
||||
- Optional. Set to 0 by default.
|
||||
|
||||
The ``DecoderInfo`` struct defined in the sample is used to store user-supplied parameters as well as the decoder and parser handles.
|
||||
|
||||
The memory type and the type of decoder is set by the specified backend. If the GPU (device) backend is selected, both a parser and a hardware decoder are created. If the CPU (host) backend is selected, only a software decoder is created:
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
DecoderInfo dec_info;
|
||||
[...]
|
||||
int main(int argc, char** argv) {
|
||||
[...]
|
||||
dec_info.rocdec_codec_id = CodecTypeToRocDecVideoCodec(codec_type);
|
||||
dec_info.dec_device_id = device_id;
|
||||
dec_info.mem_type = (!backend) ? OUT_SURFACE_MEM_DEV_INTERNAL : OUT_SURFACE_MEM_HOST;
|
||||
init();
|
||||
if (backend == DECODER_BACKEND_DEVICE) {
|
||||
create_parser(dec_info);
|
||||
create_decoder(dec_info);
|
||||
} else {
|
||||
create_decoder_host(dec_info);
|
||||
}
|
||||
[...]
|
||||
}
|
||||
|
||||
All applications need to register the ``pfn_sequence_callback`` and ``pfn_display_picture`` callbacks. Applications that use the parser must also register the ``pfn_decode_picture`` callback.
|
||||
|
||||
When the GPU backend is selected, these callbacks are registered in the ``create_parser()`` function. ``create_parser`` also creates the parser using ``rocDecCreateVideoParser()``:
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
void create_parser(DecoderInfo& dec_info) {
|
||||
RocdecParserParams params = {};
|
||||
params.codec_type = dec_info.rocdec_codec_id;
|
||||
params.max_num_decode_surfaces = 6;
|
||||
params.max_display_delay = 1;
|
||||
params.user_data = &dec_info;
|
||||
params.pfn_sequence_callback = handle_video_sequence;
|
||||
params.pfn_decode_picture = handle_picture_decode;
|
||||
params.pfn_display_picture = handle_picture_display;
|
||||
CHECK(rocDecCreateVideoParser(&dec_info.parser, ¶ms));
|
||||
}
|
||||
|
||||
The ``create_decoder()`` function sets the decoder parameters and passes them to ``rocDecCreateDecoder()`` to create the hardware decoder:
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
void create_decoder(DecoderInfo& dec_info) {
|
||||
RocDecoderCreateInfo create_info = {};
|
||||
create_info.codec_type = dec_info.rocdec_codec_id; // user specified codec_type for raw files
|
||||
[...]
|
||||
CHECK(rocDecCreateDecoder(&dec_info.decoder, &create_info));
|
||||
}
|
||||
|
||||
The ``create_decoder_host()`` function performs the same actions as ``create_decoder()``, but uses ``rocDecCreateDecoderHost()`` to create a software decoder. Because the parser isn't used with the software decoder, and because the software decoder uses different function calls, the callbacks for the software decoder are registered in ``create_decoder_host()``:
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
void create_decoder_host(DecoderInfo& dec_info) {
|
||||
RocDecoderHostCreateInfo create_info = {};
|
||||
create_info.codec_type = dec_info.rocdec_codec_id;
|
||||
[...]
|
||||
create_info.pfn_sequence_callback = handle_video_sequence_host;
|
||||
create_info.pfn_display_picture = handle_picture_display_host;
|
||||
CHECK(rocDecCreateDecoderHost(&dec_info.decoder, &create_info));
|
||||
dec_info.backend = DECODER_BACKEND_HOST;
|
||||
}
|
||||
|
||||
After the decoder and parser have been created, ``decode_frames`` is called.
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
int main(int argc, char** argv) {
|
||||
[...]
|
||||
dec_info.dump_decoded_frames = dump_output_frames;
|
||||
auto input_frames = read_frames(input_file_names);
|
||||
auto start = std::chrono::high_resolution_clock::now();
|
||||
for (int i = 0; i < num_iterations; i++) {
|
||||
decode_frames(dec_info, input_frames);
|
||||
}
|
||||
[...]
|
||||
}
|
||||
|
||||
``decode_frames`` calls ``rocDecParseVideoData()`` or ``rocDecDecodeFrameHost()``, depending on the backend, to parse and decode the frames:
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
void decode_frames(DecoderInfo& dec_info, const std::vector<std::vector<uint8_t>>& frames) {
|
||||
// gpu backend using VCN
|
||||
if (dec_info.backend == DECODER_BACKEND_DEVICE) {
|
||||
for (int i=0; i < static_cast<int>(frames.size()); ++i) {
|
||||
RocdecSourceDataPacket packet = {};
|
||||
packet.payload_size = frames[i].size();
|
||||
packet.payload = frames[i].data();
|
||||
if (i == static_cast<int>(frames.size() - 1)) {
|
||||
packet.flags = ROCDEC_PKT_ENDOFPICTURE; // mark end_of_picture flag for last frame
|
||||
}
|
||||
CHECK(rocDecParseVideoData(dec_info.parser, &packet));
|
||||
}
|
||||
} else if (dec_info.backend == DECODER_BACKEND_HOST) {
|
||||
for (int i=0; i < static_cast<int>(frames.size()); ++i) {
|
||||
RocdecPicParamsHost pic_params = {};
|
||||
pic_params.bitstream_data_len = frames[i].size();
|
||||
pic_params.bitstream_data = frames[i].data();
|
||||
if (i == static_cast<int>(frames.size() - 1)) {
|
||||
pic_params.flags = ROCDEC_PKT_ENDOFPICTURE; // mark end_of_picture flag for last frame
|
||||
}
|
||||
CHECK(rocDecDecodeFrameHost(dec_info.decoder, &pic_params));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
The registered callbacks are triggered during the calls to ``rocDecParseVideoData()`` and ``rocDecDecodeFrameHost()``.
|
||||
|
||||
``pfn_decode_picture`` is triggered when a new frame is ready to be decoded, ``pfn_sequence_callback`` is triggered when a new sequence header is encountered, and ``pfn_display_picture`` is triggered when a frame has finished being decoded.
|
||||
|
||||
``pfn_decode_picture`` needs to call ``rocDecDecodeFrame()`` or ``rocDecodeFrameHost()``, depending on the specified backend, to decode a frame.
|
||||
|
||||
In ``rocdecdecode.cpp``, ``pfn_decode_picture`` calls ``handle_picture_decode()`` or ``handle_picture_decode_host()``, depending on the specified backend:
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
int ROCDECAPI handle_picture_decode(void* user_data, RocdecPicParams* params) {
|
||||
DecoderInfo *p_dec_info = static_cast<DecoderInfo *>(user_data);
|
||||
CHECK(rocDecDecodeFrame(p_dec_info->decoder, params));
|
||||
return 1;
|
||||
}
|
||||
|
||||
``pfn_sequence_callback`` is triggered when a format change occurs or when a new sequence header is encountered. When this happens, the decoder is reconfigured to handle the new sequence or format.
|
||||
|
||||
``pfn_sequence_callback`` needs to call ``rocDecReconfigureDecoder()`` or ``rocDecReconfigureDecoderHost()`` depending on the backend, to reconfigure the decoder.
|
||||
|
||||
In the ``rocdecdecode.cpp`` sample, ``pfn_sequence_callback`` calls ``handle_video_sequence()`` or ``handle_video_sequence_host()``, depending on the specified backend:
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
int ROCDECAPI handle_video_sequence(void* user_data, RocdecVideoFormat* format) {
|
||||
DecoderInfo *p_dec_info = static_cast<DecoderInfo *>(user_data);
|
||||
[...]
|
||||
RocdecReconfigureDecoderInfo reconfig_params = {};
|
||||
reconfig_params.width = format->coded_width;
|
||||
reconfig_params.height = format->coded_height;
|
||||
reconfig_params.bit_depth_minus_8 = bitdepth_minus_8;
|
||||
reconfig_params.num_decode_surfaces = format->min_num_decode_surfaces;
|
||||
reconfig_params.target_width = target_width;
|
||||
reconfig_params.target_height = target_height;
|
||||
reconfig_params.display_rect.left = format->display_area.left;
|
||||
reconfig_params.display_rect.right = format->display_area.right;
|
||||
reconfig_params.display_rect.top = format->display_area.top;
|
||||
reconfig_params.display_rect.bottom = format->display_area.bottom;
|
||||
CHECK(rocDecReconfigureDecoder(p_dec_info->decoder, &reconfig_params));
|
||||
[...]
|
||||
return 1;
|
||||
}
|
||||
|
||||
``pfn_display_picture`` is triggered when a frame has been decoded. It needs to call ``rocDecGetVideoFrame()`` or ``rocDecGetVideoFrameHost()``, depending on the specified backend.
|
||||
|
||||
``rocDecGetVideoFrame()`` and ``rocDecGetVideoFrameHost()`` map the video ID of the decoded frame to HIP. Calls to both these functions block until the frame is decoded and the memory mapping is complete. They return the HIP device pointer or the host memory pointer, depending on the backend specified, as well as information about the :doc:`output surface <../conceptual/rocDecode-memory-types>`.
|
||||
|
||||
``pfn_display_picture`` calls ``handle_picture_display()`` or ``handle_handle_picture_display_host()``, depending on the specified backend, and saves the frames to file if the ``rocdecdecode`` was run with the ``-o`` option:
|
||||
|
||||
From the ``rocdecdecode.cpp`` sample:
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
int ROCDECAPI handle_picture_display(void* user_data, RocdecParserDispInfo* disp_info) {
|
||||
DecoderInfo *p_dec_info = static_cast<DecoderInfo *>(user_data);
|
||||
RocdecProcParams params = {};
|
||||
params.progressive_frame = disp_info->progressive_frame;
|
||||
params.top_field_first = disp_info->top_field_first;
|
||||
void* dev_mem_ptr[3] = { 0 };
|
||||
uint32_t pitch[3] = { 0 };
|
||||
CHECK(rocDecGetVideoFrame(p_dec_info->decoder, disp_info->picture_index, dev_mem_ptr, pitch, ¶ms));
|
||||
if (p_dec_info->dump_decoded_frames) {
|
||||
save_frame_to_file(p_dec_info, dev_mem_ptr, pitch);
|
||||
}
|
||||
return 1;
|
||||
}
|
||||
|
||||
Once decoding is complete, ``rocDecDestroyVideoParser()`` needs to be called to destroy the parser, and either ``rocDecDestroyDecoderHost()`` or ``rocDecDestroyDecoder()`` needs to be called to destroy the decoder.
|
||||
|
||||
.. |rocdecdecode| replace:: ``rocdecdecode``
|
||||
.. _rocdecdecode: https://github.com/ROCm/rocDecode/tree/develop/samples/rocdecDecode/README.md
|
||||
|
||||
.. |apifolder| replace:: ``api/rocdecode/``
|
||||
.. _apifolder: https://github.com/ROCm/rocDecode/tree/develop/api/rocdecode
|
||||
|
||||
.. |utilsfolder| replace:: ``utils`` folder
|
||||
.. _utilsfolder: https://github.com/ROCm/rocDecode/tree/develop/utils
|
||||
@@ -6,9 +6,10 @@
|
||||
Using the rocDecode RocVideoDecoder
|
||||
********************************************************************
|
||||
|
||||
rocDecode provides two ways of decoding a video stream: using the rocDecode RocVideoDecoder on GPU or using the FFmpeg decoder on CPU.
|
||||
rocDecode provides two methods fpr decoding a video stream: using the rocDecode RocVideoDecoder on the GPU or using the FFmpeg decoder on the CPU.
|
||||
|
||||
This topic covers how to decode a video stream using the RocVideoDecoder class in |roc_video_dec|_. The RocVideoDecode class provides high-level calls to the core APIs in the |apifolder|_ of the rocDecode GitHub repository. For information about the core APIs, see :doc:`Using the rocDecode core APIs <./using-rocdecode>`.
|
||||
|
||||
This topic covers how to decode a video stream using the RocVideoDecoder class in |roc_video_dec|_. The RocVideoDecode class provides high-level calls to the core APIs in the |apifolder|_ of the rocDecode GitHub repository. For information about the core APIs, see :doc:`Using the rocDecode core APIs <../reference/rocDecode-core-APIs>`.
|
||||
|
||||
The RocVideoDecoder takes a demultiplexed coded picture as input. The picture can be demultiplexed from a video stream using the :doc:`FFmpeg demultiplexer <./using-rocDecode-ffmpeg>`.
|
||||
|
||||
@@ -86,12 +87,10 @@ To prevent the remaining frames in the buffers from being deleted along with the
|
||||
|
||||
The |reconfig_struct|_ struct stores information on how to handle the reconfiguration. A callback, a user-defined flush mode, and a user-defined struct are passed to ``ReconfigParams_t``. The reconfiguration parameters are then passed to the decoder using ``SetReconfigParams``.
|
||||
|
||||
The reconfiguration parameters need to be defined prior to entering the decoding loop.
|
||||
|
||||
For example, the reconfiguration structs are defined in |common|_ in the rocDecode samples and then used in ``videodecode.cpp``:
|
||||
|
||||
.. code:: C++
|
||||
The reconfiguration parameters need to be defined prior to entering the decoding loop. For example, the reconfiguration structs are defined in |common|_ in the rocDecode samples and then used in ``videodecode.cpp``
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
typedef enum ReconfigFlushMode_enum {
|
||||
RECONFIG_FLUSH_MODE_NONE = 0x0, /**< Just flush to get the frame count */
|
||||
RECONFIG_FLUSH_MODE_DUMP_TO_FILE = 0x1, /**< The remaining frames will be dumped to file in this mode */
|
||||
@@ -104,7 +103,6 @@ For example, the reconfiguration structs are defined in |common|_ in the rocDeco
|
||||
void *md5_generator_handle;
|
||||
} ReconfigDumpFileStruct;
|
||||
|
||||
|
||||
reconfig_params.p_fn_reconfigure_flush = ReconfigureFlushCallback;
|
||||
reconfig_user_struct.b_dump_frames_to_file = dump_output_frames;
|
||||
reconfig_user_struct.output_file_name = output_file_path;
|
||||
@@ -118,13 +116,8 @@ For example, the reconfiguration structs are defined in |common|_ in the rocDeco
|
||||
reconfig_params.p_reconfig_user_struct = &reconfig_user_struct;
|
||||
viddec.SetReconfigParams(&reconfig_params);
|
||||
|
||||
|
||||
In the decode loop, the demultiplexed coded picture is passed to ``DecodeFrame``. Once the frame is decoded and processed, it is released with ``ReleaseFrame``.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
.. |videodecode| replace:: ``videodecode.cpp``
|
||||
.. _videodecode: https://github.com/ROCm/rocDecode/tree/develop/samples/videoDecode/videodecode.cpp
|
||||
|
||||
|
||||
@@ -76,7 +76,6 @@ The ``videodecode.cpp`` sample lets the user choose which method to use through
|
||||
- Seek criteria and seek starting point
|
||||
- Optional. Set to 1 and the frame number to start demultiplexing from that specific frame. Set to 2 and the timestamp to start demultiplexing from that specific timestamp. The seek criteria and starting point must be comma-separated (``,``). Demultiplexing begins at the first frame by default.
|
||||
|
||||
|
||||
* - ``-seek_mode``
|
||||
- Seek mode
|
||||
- Optional. Set to 0 to seek to the previous keyframe. Set to 1 to seek to the exact frame. Seeks to previous keyframe by default.
|
||||
|
||||
@@ -1,236 +0,0 @@
|
||||
.. meta::
|
||||
:description: Using rocDecode
|
||||
:keywords: parse video, parse, decode, video decoder, video decoding, rocDecode, core APIs, AMD, ROCm
|
||||
|
||||
********************************************************************
|
||||
Using the rocDecode core APIs
|
||||
********************************************************************
|
||||
|
||||
rocDecode core APIs are available in the |apifolder|_ of the `rocDecode GitHub repository <https://github.com/ROCm/rocDecode>`_.
|
||||
|
||||
.. note::
|
||||
|
||||
The rocDecode samples use the utility classes in the |utilsfolder|_ instead of the core APIs. For information about using the utility classes, see :doc:`Using rocDecode with the FFmpeg decoder <./using-rocDecode-ffmpeg>` and :doc:`Using rocDecode with the bitstream decoder <./using-rocDecode-bitstream>`.
|
||||
|
||||
|
||||
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()``
|
||||
|
||||
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 returned to the caller.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
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;
|
||||
}
|
||||
|
||||
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()`` needs to 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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Please note that this API makes a non-blocking call and returns the status of the frame associated with nPicIdx at the time of the call,
|
||||
without waiting for the decoding to complete. The ``decode_status->decode_status`` can be either ``rocDecodeStatus_Success``, indicating that
|
||||
the decoding has been completed, or ``rocDecodeStatus_InProgress``, which means that the decoding is still in progress.
|
||||
|
||||
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. Please note that the ``rocDecGetVideoFrame()`` API is a blocking call.
|
||||
If the video frame associated with the pic_idx is not ready, the call will wait for the decoding to complete before mapping the video frame for use in HIP.
|
||||
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 need to 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 reuse 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.
|
||||
|
||||
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 need 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 in ``RocDecoderCreateInfo``. If you need to
|
||||
change these values, you have to destroy and recreate the session.
|
||||
|
||||
.. note::
|
||||
|
||||
You need to call ``rocDecReconfigureDecoder()`` during ``RocdecParserParams::pfn_sequence_callback``.
|
||||
|
||||
Destroy the decoder
|
||||
====================================================
|
||||
|
||||
You need to 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.
|
||||
|
||||
Destroy the parser
|
||||
====================================================
|
||||
|
||||
You need to call ``rocDecDestroyVideoParser()`` to destroy the parser object and free up all allocated
|
||||
resources at the end of video decoding.
|
||||
|
||||
Logging control
|
||||
====================================================
|
||||
rocDecode core components can generate various logs during the decode session. The logs can be critical status reports, error reports, warnings, etc.
|
||||
Each log has a significance level associated to it. The level can be from critical (0) to debug info related (4). Lower value has greater importance.
|
||||
An internal logging level threshold can be set to control the verbosity of logging output from each rocDecode component. If a log's level value is less
|
||||
than or equal to the logging level threshold, the log is output. Otherwise, the log is not output.
|
||||
|
||||
The logging level threshold can be set by the environment variable ROCDEC_LOG_LEVEL, or by calling the SetLogLevel method of the logger class. The default
|
||||
logging level is 0 (critical log only).
|
||||
|
||||
|
||||
.. |apifolder| replace:: ``api`` folder
|
||||
.. _apifolder: https://github.com/ROCm/rocDecode/tree/develop/api
|
||||
|
||||
.. |utilsfolder| replace:: ``utils`` folder
|
||||
.. _utilsfolder: https://github.com/ROCm/rocDecode/tree/develop/utils
|
||||
مرجع در شماره جدید
Block a user