Documentation

hi_mpi_venc_get_stream

The Atlas 200/300/500 Inference Product does not support this API.

The Atlas Training Series Product does not support this API.

Description

Fetches the encoded stream.

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

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.

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.

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

References

Figure 1 Packet structure
Parent topic: VENC/JPEGE