venc_get_stream

Applicability

Description

Fetches the encoded stream.

Prototype

• C Prototype

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

• Python Function

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

Parameters

Return Value

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 details about the API call sequence, see JPEGE and VENC.

Reference

Figure 1 Packet structure