Using the rocDecode RocVideoDecoder

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.

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 api folder of the rocDecode GitHub repository. For information about the core APIs, see Using the rocDecode core APIs.

The RocVideoDecoder takes a demultiplexed coded picture as input. The picture can be demultiplexed from a video stream using the FFmpeg demultiplexer.

To use the rocDecode video decoder, import the roc_video_dec.h header file and instantiate RocVideoDecoder.

The RocVideoDecoder constructor takes the following parameters:

Parameter	Description	Default
`device_id`	`int` The 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.	0
`out_mem_type`	`OutputSurfaceMemoryType` The memory type where the surface data, such as the decoded frames, resides. 0: `OUT_SURFACE_MEM_DEV_INTERNAL`. The surface data is stored internally on memory shared by the GPU and CPU. 1: `OUT_SURFACE_MEM_DEV_COPIED`. The surface data resides on the GPU. 2: `OUT_SURFACE_MEM_HOST_COPIED`. The surface data resides on the CPU. See Surface data memory locations for more information.	0, OUT_SURFACE_MEM_DEV_INTERNAL
`codec`	`rocDecVideoCodec` The video file’s codec ID converted to `rocDecVideoCodec` using `AVCodec2RocDecVideoCodec`.	No default, a value must be provided
`force_zero_latency`	`bool` Set to `true` to flush decoded frames for immediate display.	`false`
`p_crop_rect`	`const Rect *` The rectangle to use for cropping.	No cropping
`extract_user_SEI_Message`	`bool` Set to `true` to extract Supplemental Enhancement Information (SEI) from the video stream.	`false`, no SEI will be extracted
`disp_delay`	`uint32_t` Delay the display by this number of frames.	0, no delay in displaying the frames
`max_width`	`int` Max width.	0
`max_height`	`int` Max height.	0
`clk_rate`	`uint32_t` Clock rate.	1000

For example, from videodecode.cpp:

RocVideoDecoder viddec(device_id, mem_type, rocdec_codec_id, b_force_zero_latency, p_crop_rect, b_extract_sei_messages, disp_delay);

RocVideoDecoder will create a parser and a decoder, and initialize HIP on the device.

The same decoder instance is reused when there’s a change to the video resolution without a change in the codec.

The decoder maintains a pool of frame buffers for decoded images that haven’t yet been displayed or processed. When the video stream resolution changes, the existing frame buffers in the buffer pool are deleted. The decoder is then reconfigured for the new resolution and new buffers are created.

To prevent the remaining frames in the buffers from being deleted along with the buffers, a callback function can be defined to consume the remaining frames.

The ReconfigParams_t 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.h in the rocDecode samples and then used in videodecode.cpp:

typedef enum ReconfigFlushMode_enum {
    RECONFIG_FLUSH_MODE_NONE = 0,               /**<  Just flush to get the frame count */
    RECONFIG_FLUSH_MODE_DUMP_TO_FILE = 1,       /**<  The remaining frames will be dumped to file in this mode */
    RECONFIG_FLUSH_MODE_CALCULATE_MD5 = 2,      /**<  Calculate the MD5 of the flushed frames */
} ReconfigFlushMode;

typedef struct ReconfigDumpFileStruct_t {
    bool b_dump_frames_to_file;
    std::string output_file_name;
    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;
if (dump_output_frames) {
    reconfig_params.reconfig_flush_mode = RECONFIG_FLUSH_MODE_DUMP_TO_FILE;
} else {
    reconfig_params.reconfig_flush_mode = RECONFIG_FLUSH_MODE_NONE;
}
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.