hi_mpi_venc_get_stream

Applicability

Product	Supported
Atlas A3 training products / Atlas A3 inference products	√
Atlas A2 training products / Atlas A2 inference products	√
Atlas 200I/500 A2 inference products	√
Atlas inference products	√
Atlas training products	☓

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 A3 training products / Atlas A3 inference products : The value range of the encoding channel ID is [0, 256). The maximum number of JPEGE channels is 256. Atlas A2 training products / Atlas A2 inference products : The value range of the encoding channel ID is [0, 256). The maximum number of JPEGE channels is 256. Atlas 200I/500 A2 inference products : The value range of the encoding channel ID is [0, 128). The JPEGE and VENC functions share the same channels, and the maximum number of channels is 128. Atlas inference products : The value range of the encoding channel ID is [0, 256). The JPEGE and VENC functions share the same channels, and 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 A3 training products / Atlas A3 inference products Atlas A2 training products / Atlas A2 inference products Atlas 200I/500 A2 inference products in Ascend EP form Atlas inference products in Ascend EP form
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 A3 training products / Atlas A3 inference products : The value range of the encoding channel ID is [0, 256). The maximum number of JPEGE channels is 256.

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

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

Atlas inference products : The value range of the encoding channel ID is [0, 256). The JPEGE and VENC functions share the same channels, and 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 A3 training products / Atlas A3 inference products
Atlas A2 training products / Atlas A2 inference products
Atlas 200I/500 A2 inference products in Ascend EP form
Atlas inference products in Ascend EP form

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, call hi_mpi_venc_release_stream to release the stream buffer 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. In packet mode, the space must be at least sizeof(hi_venc_pack). In frame mode, the space must be at least N times sizeof(hi_venc_pack), where N indicates the number of packets in the current frame, which can be obtained by using the select and hi_mpi_venc_query_status calls.
- 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:
- Call hi_mpi_venc_query_status to query the status of an encoding channel.
- 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 free the stream buffer.
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 calling hi_mpi_venc_set_mod_param.
- 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.

Stream Packet Structure

Figure 1 Stream packet structure

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

hi_mpi_venc_get_stream

Applicability

Description

Prototype

Parameters

Returns

Restrictions

See Also

Stream Packet Structure