venc_get_stream

Applicability

Product	Supported (√/x)
Atlas A3 training products / Atlas A3 inference products	√
Atlas A2 training products / Atlas A2 inference products	√
Atlas training products	x
Atlas inference products	√
Atlas 200I/500 A2 inference products	√

Function Usage

Fetches the encoded stream.

Prototype

C Prototype

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

Python Function

        
             stream, ret = acl.himpi.venc_get_stream(chn, stream, milli_sec)

Parameter Description

Parameter	Description
chn	Int, decoding channel ID. Atlas inference products : The value range of this parameter is [0, 256). The JPEGD and VDEC functions share the same channels, and the maximum number of channels is 256. Atlas A2 training products / Atlas A2 inference products : The value range of this parameter is [0, 256). The JPEGD and VDEC functions share the same channels, and the maximum number of channels is 256. Among them, a maximum of 256 JPEGD decoding channels and 32 VDEC decoding channels are supported. Atlas 200I/500 A2 inference products : The value range of this parameter is [0, 128). The JPEGD and VDEC functions share the same channels, and the maximum number of channels is 128. Atlas A3 training products / Atlas A3 inference products : The value range of this parameter is [0, 256). The JPEGD and VDEC functions share the same channels, and the maximum number of channels is 256. Among them, a maximum of 256 JPEGD decoding channels and 32 VDEC decoding channels are supported.
stream	Dict. After pack_cnt is passed to the cur_packs packet dictionary, the buffer is automatically allocated. For details, see hi_venc_stream.
milli_sec	Int, timeout interval, in milliseconds. -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

Description

chn

Int, decoding channel ID.

Atlas inference products : The value range of this parameter is [0, 256). The JPEGD and VDEC functions share the same channels, and the maximum number of channels is 256.
Atlas A2 training products / Atlas A2 inference products : The value range of this parameter is [0, 256). The JPEGD and VDEC functions share the same channels, and the maximum number of channels is 256. Among them, a maximum of 256 JPEGD decoding channels and 32 VDEC decoding channels are supported.
Atlas 200I/500 A2 inference products : The value range of this parameter is [0, 128). The JPEGD and VDEC functions share the same channels, and the maximum number of channels is 128.
Atlas A3 training products / Atlas A3 inference products : The value range of this parameter is [0, 256). The JPEGD and VDEC functions share the same channels, and the maximum number of channels is 256. Among them, a maximum of 256 JPEGD decoding channels and 32 VDEC decoding channels are supported.

stream

Dict. After pack_cnt is passed to the cur_packs packet dictionary, the buffer is automatically allocated. For details, see hi_venc_stream.

milli_sec

Int, timeout interval, in milliseconds.

-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.

Return Value Description

Return Value	Description
ret	Int, error code. 0: success. Other values: failures. For details, see VENC/JPEGE Return Codes.
stream	Dict, stream dictionary. The configured attribute addr must be a buffer address on the device, indicating that the output stream is stored in the device buffer. For the Atlas inference products in standard form, to access the output stream data after this API is called on the host, transfer the data on the device back to the host. For the Atlas A2 training products / Atlas A2 inference products , to access the output stream data after this API is called on the host, transfer the data on the device back to the host. For Atlas 200/500 A2 Inference Product in EP mode, to access the output stream data after this API is called on the host, transfer the data on the device back to the host. For the Atlas A3 training products / Atlas A3 inference products , to access the output stream data after this API is called on the host, transfer the data on the device back to the host.

Return Value

Description

ret

Int, error code.

0: success.
Other values: failures. For details, see VENC/JPEGE Return Codes.

stream

Dict, stream dictionary. The configured attribute addr must be a buffer address on the device, indicating that the output stream is stored in the device buffer.

For the Atlas inference products in standard form, to access the output stream data after this API is called on the host, transfer the data on the device back to the host.
For the Atlas A2 training products / Atlas A2 inference products , to access the output stream data after this API is called on the host, transfer the data on the device back to the host.
For Atlas 200/500 A2 Inference Product in EP mode, to access the output stream data after this API is called on the host, transfer the data on the device back to the host.
For the Atlas A3 training products / Atlas A3 inference products , to access the output stream data after this API is called on the host, transfer the data on the device back to the host.

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.
The stream dictionary hi_venc_stream consists of the following:
- pack: pointer to list of streams.
  After the function is called successfully, the stream dictionary in the return value is filled with a list of hi_venc_pack dictionaries.
- pack_cnt: number of packets.
  This parameter specifies the maximum number of hi_venc_pack dictionaries to be filled in the pack. When packets are obtained by packet, pack_cnt must be greater than or equal to 1. When packets are obtained by frame, pack_cnt must be greater than or equal to the number of packets in the current frame (which can be obtained by calling acl.himpi.venc_query_status).
  
  After the function is called successfully, pack_cnt of the stream dictionary in the return value is the number of packets filled in pack.
- seq: frame sequence number in frame mode or packet sequence number in packet mode.
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:
1. Call acl.himpi.venc_query_status to query the status of an encoding channel.
2. Ensure that both cur_packs and left_stream_frames are greater than 0.
3. Construct a stream dictionary.
```
stream["pack_cnt"] = cur_packs
```
4. Call acl.himpi.venc_get_stream to pass the stream dictionary and obtain the encoded streams.
```
stream, ret = acl.himpi.venc_get_stream(chn, stream)
```
5. Call acl.himpi.venc_release_stream to pass the stream dictionary returned in the previous step and release the stream buffer.
When the encoding module parameter one_stream_buf is set to 1, the address of only one stream packet (excluding user data) is obtained when a frame of streams is obtained, that is, pack_cnt is set to 1, and the address is pack[0]["addr"]. Add offset to the hi_venc_pack dictionary to specify the address of valid data in a 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 acl.himpi.venc_set_mod_param call.
- one_stream_buf = 1 indicates the single-packet mode. The JPEGE supports only the single-frame single-packet mode currently.
- one_stream_buf = 0 indicates the multi-packet mode, which is also the default setting.

Reference

For the API call sequence, see JPEGE and VENC.

Reference

Figure 1 Packet structure

Parent topic: VENC/JPEGE APIs