hi_mpi_venc_get_stream

Applicability

Product	Supported
Atlas 350 Accelerator Card	√
Atlas A3 training product / Atlas A3 inference product	√
Atlas A2 training product / Atlas A2 inference product	√
Atlas 200I/500 A2 inference product	√
Atlas inference product	√
Atlas training product	☓

Function Description

Fetches the encoded stream.

Prototype

hi_s32 hi_mpi_venc_get_stream(hi_venc_chn chn, hi_venc_stream *stream, hi_s32 milli_sec)

Parameters

Parameter	Input/Output	Description
chn	Input	Encoding channel ID. Atlas 350 Accelerator Card: encoding channel ID. The value range is as follows: [0, 256). The maximum number of JPEGE channels is 256. Atlas A3 training product / Atlas A3 inference product : The value range of the encoding channel ID is [0, 256). The maximum number of JPEGE channels is 256. Atlas A2 training product / Atlas A2 inference product : The value range of the encoding channel ID is [0, 256). The maximum number of JPEGE channels is 256. Atlas 200I/500 A2 inference product : The value range of this parameter is [0, 128). The JPEGE, and VENC functions share the same channels, and the maximum number of channels is 128. For the Atlas inference product , the value range of the encoding channel ID is [0, 256). The JPEGE and VENC functions share channels. The maximum number of channels is 256.
stream	Output	Pointer to the output stream. The configured addr address must be a memory address on the device, indicating that the output stream is stored in the device memory. For the following products, to access the output stream data on the host, transfer the data on the device back to the host: Atlas 350 Accelerator Card Atlas A3 training product / Atlas A3 inference product Atlas A2 training product / Atlas A2 inference product Ascend EP form of the Atlas 200I/500 A2 inference product Ascend EP form of Atlas inference product
milli_sec	Input	Timeout interval (ms). -1: blocking mode. 0: non-blocking mode. > 0: timeout interval (timeout mode). The timeout interval varies with the operating system. The deviation is generally within a time slice of an operating system. For example, if the time slice of an operating system is 4 ms and the value of milli_sec is set to 1, the actual timeout interval ranges from 1 ms to 5 ms. When the CPU load is high, the timeout interval may fluctuate.

Parameter

Input/Output

Description

chn

Input

Encoding channel ID.

Atlas 350 Accelerator Card: encoding channel ID. The value range is as follows: [0, 256). The maximum number of JPEGE channels is 256.

Atlas A3 training product / Atlas A3 inference product : The value range of the encoding channel ID is [0, 256). The maximum number of JPEGE channels is 256.

Atlas A2 training product / Atlas A2 inference product : The value range of the encoding channel ID is [0, 256). The maximum number of JPEGE channels is 256.

Atlas 200I/500 A2 inference product : The value range of this parameter is [0, 128). The JPEGE, and VENC functions share the same channels, and the maximum number of channels is 128.

For the Atlas inference product , the value range of the encoding channel ID is [0, 256). The JPEGE and VENC functions share channels. The maximum number of channels is 256.

stream

Output

Pointer to the output stream.

The configured addr address must be a memory address on the device, indicating that the output stream is stored in the device memory.

For the following products, to access the output stream data on the host, transfer the data on the device back to the host:

Atlas 350 Accelerator Card
Atlas A3 training product / Atlas A3 inference product
Atlas A2 training product / Atlas A2 inference product
Ascend EP form of the Atlas 200I/500 A2 inference product
Ascend EP form of Atlas inference product

milli_sec

Input

Timeout interval (ms).

-1: blocking mode.
0: non-blocking mode.
> 0: timeout interval (timeout mode). The timeout interval varies with the operating system. The deviation is generally within a time slice of an operating system. For example, if the time slice of an operating system is 4 ms and the value of milli_sec is set to 1, the actual timeout interval ranges from 1 ms to 5 ms. When the CPU load is high, the timeout interval may fluctuate.

Returns

0: success. After the encoding result data is obtained successfully, the hi_mpi_venc_release_stream interface needs to be invoked to release the stream cache resources.
Although a success message is returned, the data that fails to be encoded may be obtained. To check whether the encoding is successful, check the value of len under pack of the hi_venc_stream structure. If len is 0, the encoding fails.
Other values: failure. For details, see VENC/JPEGE Return Codes.

Restrictions

Ensure that a channel has been created. Otherwise, a failure is returned.
If stream is left empty, the error code HI_ERR_VENC_NULL_PTR is returned.
If milli_sec is less than –1, the error code HI_ERR_VENC_ILLEGAL_PARAM is returned.
Stream fetching in timeout mode is supported. The select and poll function calls are supported.
- milli_sec = 0 indicates the non-blocking mode. If there is no data in the buffer, the error code HI_ERR_VENC_BUF_EMPTY is returned.
- milli_sec = -1 indicates the blocking mode. If there is no data in the buffer, the API call waits for available data. A success is returned only when data is fetched.
- milli_sec > 0 indicates the timeout mode. If there is no data in the buffer, the API call waits for the specified period. A success is returned if data is fetched within the timeout interval. Otherwise, a timeout error is returned.
Stream fetching in packet mode or frame mode is supported. In packet mode:
- For JPEG encoding, a parameter packet or data packet is fetched each time.
- For H.265 encoding, one NAL unit is fetched each time.
hi_venc_stream consists of the following members:
- pack: pointer to packet information.
  The size of contiguous buffer space pointing to hi_venc_pack is allocated by the caller. If streams are obtained by packet, the size of this space must be greater than or equal to the value of sizeof (hi_venc_pack). If streams are obtained by frame, the size of this space must be greater than or equal to the value of N x sizeof (hi_venc_pack). N indicates the number of packets in the current frame, the value can be obtained through the hi_mpi_venc_query_status interface after the select operation.
- pack_cnt: number of packets.
  As input, this parameter specifies the number of hi_venc_pack in pack. In packet mode, pack_cnt must be at least 1. In frame mode, pack_cnt must be at least the number of packets of the current frame. In the outputs of the function call, pack_cnt indicates the actual number of packets for pack.
- seq: frame sequence number in frame mode or packet sequence number in packet mode.
- h264_info, jpeg_info, or h265_info: union of protocol-specific stream features.
- h264_adv_info or h265_adv_info: union of advanced protocol-specific stream features.
If streams are not fetched by the user for a long period of time, the stream buffer becomes full. In this case, encoding stops until the user fetches and releases streams to make room for encoding.
Use this API in pair with the release API. Release the stream buffer in a timely manner to avoid encoding suspension due to a full stream buffer.
You are advised to obtain streams by calling the select function as follows:
- Query the status of the encoding channel by calling hi_mpi_venc_query_status.
- Ensure that both cur_packs and left_stream_frames are greater than 0.
- Call malloc to allocate cur_packs packet information structs.
- Call hi_mpi_venc_get_stream to fetch the encoded stream.
- Call hi_mpi_venc_release_stream to release the stream cache.
When one_stream_buf is set to 1, the stream fetching call outputs only one packet (containing no user data). That is, pack_cnt = 1 with the packet address indicated by pack[0].addr. offset is added to hi_venc_pack to indicate the address of valid data in the frame and the offset of pack[0].addr. Figure 1 shows an example in H.264 single-packet encoding, where pack[0].data_num is 3, indicating three types of NAL packets: SPS, PPS, and SEI.
- pack[0].pack_info[0]. pack_type. h264_type = HI_VENC_H264_NALU_SPS
- pack[0].pack_info[1]. pack_type. h264_type = HI_VENC_H264_NALU_PPS
- pack[0].pack_info[2]. pack_type. h264_type = HI_VENC_H264_NALU_SEI
The same rule applies to other protocols. data_num and pack_info are valid only in single-packet mode.
To select between the single-packet and multi-packet modes, set the parameter one_stream_buf of the H.265E, H.264E, or JPEGE module by using the hi_mpi_venc_set_mod_param call.
- one_stream_buf = 1 (default in the system) indicates the single-packet mode. Note that the JPEGE supports only the single-frame single-packet mode currently.
- one_stream_buf = 0 indicates the multi-packet mode.

Packet structure

Figure 1 Packet structure

Parent topic: Video Encoding (VENC) and JPEG Encoder (JPEGE)