Functions

The following table describes each of the libxcoder API functions. For more details please see the Appendix Section.

API Description Details

The following tables describes the API functions from the following files

ni_device_api.h
ni_av_codec.h
ni_util.h

ni_device_api.h Functions

API Functions in ni_device_api.h	Description
ni_device_session_context_alloc_init	Allocate and initialize a new ni_session_context_t struct
ni_device_session_context_init	Initialize already allocated session context to a known state
ni_device_session_context_clear	Clear already allocated session context
ni_device_session_context_free	Free previously allocated session context
ni_create_event	Create event and return event handle if successful (Windows only)
ni_close_event	Close event and releases resources (Windows only)
ni_device_open	Open device and return device device_handle if successful.It had been deprecated.
ni_device_open2	Open device and return device device_handle if successful.
ni_device_close	Close device and release resources
ni_device_capability_query	Query device and return device capability structure
ni_device_capability_query2	Query device and return device capability structure
ni_device_session_open	Open a new device session depending on the device_type parameter
ni_device_session_close	Close device session that was previously opened by calling ni_device_session_open
ni_device_session_flush	Send a flush command to the device
ni_device_dec_session_save_hdrs	Save a stream's headers in a decoder session that can be used later for continuous decoding from the same source. This usually works with ni_device_dec_session_flush.
ni_device_dec_session_flush	Flush a decoder session to get ready to continue decoding. This is different from ni_device_session_flush in that it closes the current decode session and opens a new one for continuous decoding.
ni_device_session_write	Send data to the device
ni_device_session_read	Read data from the device
ni_device_session_query	Query session data from the device
ni_frame_buffer_alloc	Allocate preliminary memory for the frame buffer for hwdownload or HWframe descriptor storage based on provided parameters. Applicable to YUV420 or nv12 semiplanar pixel format only, 8 or 10 bit/pixel.

ni_frame_buffer_alloc_dl	Allocate preliminary memory for the frame buffer for hwdownload or HWframe descriptor storage based on provided parameters. Applicable to all supported pixel formats.
ni_decoder_frame_buffer_alloc	Allocate memory for decoder frame buffer based on provided parameters; the memory is retrieved from a memory buffer pool and will be returned to the same buffer pool by ni_decoder_frame_buffer_free.
ni_encoder_frame_buffer_alloc	Allocate memory for the frame buffer for encoder input based on provided parameters taking into account pic line size, extra data, and alignment 2 pass requirements. Applicable to YUV420 only. Cb/Cr size matches that of Y.
ni_scaler_dest_frame_alloc	Allocate device destination frame from scaler hwframe pool. Applicable to scale, crop, pad, overlay operations.
ni_scaler_input_frame_alloc	Allocate device input frame by hw descriptor. This API won’t actually allocate a frame but sends the incoming hardware frame index to the scaler manager.
ni_scaler_frame_pool_alloc	Init output hardware frames pool for scaler. Default pool size is 1.
ni_scaler_p2p_frame_acquire	Get p2p buffer address of a frame of scaler.
ni_frame_buffer_alloc_nv	Allocate memory for the frame buffer for encoder input based on provided parameters taking into account pic line size, extra data, and alignment 2 pass requirements . Applicable to NV12 only. Cb/Cr size matches that of Y.
ni_encoder_sw_frame_buffer_alloc	This API is a wrapper for ni_encoder_frame_buffer_alloc(), used for planar pixel formats, and ni_frame_buffer_alloc_nv(), used for semi-planar pixel formats. This API is meant to combine the functionality for both individual format APIs.
ni_frame_buffer_free	Free frame buffer that was previously allocated with ni_frame_buffer_alloc or ni_frame_buffer_alloc_nv or ni_encoder_frame_buffer_alloc or ni_frame_buffer_alloc_dl
ni_decoder_frame_buffer_free	Free decoder frame buffer that was previously allocated with ni_decoder_frame_buffer_alloc, returning memory to a buffer pool.
ni_decoder_frame_buffer_pool_return_buf	Return a memory buffer to memory buffer pool, for a decoder frame.
ni_packet_buffer_alloc	Allocate memory for the packet buffer based on provided packet size
ni_custom_packet_buffer_alloc	Allocate packet buffer using a user provided pointer
ni_packet_buffer_free	Free packet buffer that was previously allocated with ni_packet_buffer_alloc
ni_packet_buffer_free_av1	Free packet buffer that was previously allocated with ni_packet_buffer_alloc for AV1 packets merge
ni_packet_copy	Copy video packet accounting for alignment and padding
ni_frame_new_aux_data	Add a new auxiliary data to a frame for encoding. Auxiliary data is non-video data associated with the frame such as closed captions, HDR metadata, ROI info, etc.
ni_frame_new_aux_data_from_raw_data	Add a new auxiliary data to a frame and copy in the raw data
ni_frame_get_aux_data	Retrieve from the frame auxiliary data of a given type if exists
ni_frame_free_aux_data	If auxiliary data of the given type exists in the frame, free it and remove it from the frame.
ni_frame_wipe_aux_data	Free and remove all auxiliary data from the frame.
ni_encoder_init_default_params	Initialize default encoder parameters
ni_decoder_init_default_params	Initialize default decoder parameters
ni_encoder_params_set_value	Set value referenced by name in encoder parameters structure
ni_decoder_params_set_value	Set value referenced by name in decoder parameters structure
ni_encoder_gop_params_set_value	Set GOP parameter value referenced by name in encoder parameters structure
ni_device_session_copy	Copy source session params into target session
ni_device_session_init_framepool	Send frame pool setup info to device for uploader instance creation
ni_device_session_update_framepool	Adjust uploader instance frame pool
ni_device_session_read_hwdesc	Read HW descriptor from decoder or 2D engine instance.
ni_device_session_hwdl	Read raw YUV data stored on device based on provided HW descriptor
ni_device_session_hwup	Send raw YUV to uploader instance and update the HW descriptor structure with new corresponding descriptor information
ni_frame_buffer_alloc_hwenc	Allocates memory for HW descriptor buffer used for encoder input based on provided parameters
ni_hwframe_buffer_recycle	Free the memory buffer used for HW descriptor buffer and send the command to device to recycle the corresponding memory bin it referred to
ni_hwframe_buffer_recycle2	Provide same function of ni_hwframe_buffer_recycle, but without device handle parameter
ni_scaler_set_params	Set parameters on the device for the 2D engine
ni_device_config_frame	Configure a frame on the device for 2D engine to work on based on provided parameters
ni_device_multi_config_frame	Configure multiple frames on the device for 2D engine to work on based on provided parameters
ni_device_alloc_frame	Allocate an input or output frame on the device for 2D engine based on provided parameters
ni_device_alloc_dst_frame	Allocate a frame on the device and return the frame index with a hw frame surface
ni_device_clone_hwframe	Copy the data of src hw frame to dst hw frame
ni_frame_buffer_alloc_pixfmt	Allocate memory for the frame buffer to be used for HW upload or 2D engine i/o frames based on provided parameters taking into account pixel format, width, height, format, stride, alignment, and extra data
ni_ai_config_network_binary	Configure a network context based with the network binary provided
ni_ai_frame_buffer_alloc	Allocate input layers memory for AI frame buffer based on provided parameters
ni_ai_packet_buffer_alloc	Allocate output layers memory for the packet buffer based on provided network
ni_reconfig_bitrate	Reconfigure bitrate dynamically during encoding.
ni_reconfig_intraprd	Reconfigure intra period dynamically during encoding. NOTE - the frame upon which intra period is reconfigured is encoded as IDR frame NOTE - reconfigure intra period is not allowed if intraRefreshMode is enabled or if gopPresetIdx is 1
ni_reconfig_vui	Reconfigure VUI parameters dynamically during encoding.
ni_force_idr_frame_type	Force next frame to be IDR frame during encoding.
ni_set_ltr	Set a frame's support of Long Term Reference frame during encoding.
ni_set_ltr_interval	Set Long Term Reference interval
ni_set_frame_ref_invalid	Set frame reference invalidation
ni_reconfig_framerate	Reconfigure framerate dynamically during encoding
ni_reconfig_max_frame_size	Reconfigure maxFrameSize_Bytes parameter setting during encoding (for details regarding maxFrameSize_Bytes parameter, please refer to Integration Programming Guide) NOTE - maxFrameSize_Bytes value less than ((bitrate / 8) / framerate) will be rejected, refer to Integration Programming Guide maxFrameSize_Bytes descriptions for range of supported values
ni_reconfig_crf	Reconfigure crf value dynamically during encoding (for details regarding crf parameter and its reconfiguration, please refer to Integration Programming Guide section 8.4 “Encoding Parameters” for crf and ReconfDemoMode descriptions)
ni_reconfig_vbv_value	Reconfigure vbv buffer size and vbv max rate dynamically during encoding.
ni_reconfig_max_frame_size_ratio	Reconfigure maxFrameSizeRatio parameter setting during encoding (for details regarding maxFrameSizeRatio parameter, please refer to Integration Programming Guide)
ni_reconfig_slice_arg	Reconfigure sliceArg dynamically during encoding
ni_device_session_acquire	Acquire a frame buffer from a P2P hwupload session
ni_uploader_frame_buffer_lock	Lock a frame from a P2P hwupload session
ni_uploader_frame_buffer_unlock	Unlock a frame from a P2P hwupload session
ni_uploader_p2p_test_send	Special P2P test API call. Copy YUV data from the software frame to the hardware P2P frame on the Quadra device
ni_encoder_set_input_frame_format	Set the input frame format for the encoder
ni_uploader_set_frame_format	Set the frame format for the hwupload session
ni_hwframe_p2p_buffer_recycle	Recycle a frame from the P2P hwupload session
ni_scaler_set_drawbox_params	Send box paramters to drawbox session
ni_device_session_sequence_change	Send sequence / resolution change information to device NOTE - this API is only for changing from large to small resolution – changing from small to large resolution requires application to close existing session and open new session with large resolution
ni_query_nvme_status	Query NVMe and TP load from the device
ni_encoder_session_read_stream_header	A convenience function that may be used to read the initial stream header from the encoder.
ni_get_dma_buf_file_descriptor	Get DMA buffer file descriptor from HW frame (P2P only)
ni_device_config_namespace_num	Config Namespace number for different SRIOV
ni_encoder_frame_zerocopy_check	Check if incoming frame is encoder zero copy compatible or not Applicable to YUV420 8 or 10 bit with planar or semi-planar pixel format, or RGBA / BGRA / ABGR / ARGB pixel format
ni_encoder_frame_zerocopy_buffer_alloc	Allocate memory for encoder zero copy (metadata, etc.) based on given parameters, taking into account pic linesize and extra data Applicable to YUV420 8 or 10 bit with planar or semi-planar pixel format, or RGBA / BGRA / ABGR / ARGB pixel format
ni_uploader_frame_zerocopy_check	Check if input frame is hwupload zero copy compatible or not. Zero copy can be enabled if the incoming frame meets the following requirements - Input frame is in YUV420 8 or 10 bit + planar or semi-planar pixel format, or in RGBA / BGRA / ABGR / ARGB pixel format Input frame resolution >= 1080p For YUV420 8 / 10-bit with planar / semi-planar pixel formats: Zero copy is applicable only if frame buffer linesize is 128 bytes aligned For RGBA / BGRA / ABGR / ARGB pixel formats: Zero copy is applicable only if frame buffer linesize is 64 bytes aligned
ni_query_temperature	Query CompositeTemp from device
ni_query_extra_info	Query CompositeTemp and power from device
ni_device_alloc_and_get_firmware_logs	Allocate log buffer if needed and retrieve firmware logs from device. Also write firmware logs to files if requested.
ni_device_alloc_and_get_firmware_logs	Send a p_config command to reconfigure decoding ppu params.

ni_util.h Functions

API Functions in ni_util.h	Description
ni_get_hw_yuv420p_dim	Get dimension information of NETINT HW YUV420p frame to be sent to encoder for encoding.
ni_copy_hw_yuv420p	Copy YUV data to NETINT HW YUV420p frame layout to be sent to encoder for encoding.
ni_copy_yuv_444p_to_420p	Copy yuv444p data to two pieces of NETINT HW yuv420p frame layout to be sent to encoder for encoding
ni_insert_emulation_prevent_bytes	Insert emulation prevention byte(s) as needed into the data buffer
ni_remove_emulation_present_bytes	Remove emulation prevention byte(s) as needed from the data buffer
ni_copy_hw_descriptors	Copy HW descriptor structure from source to destination
ni_get_libxcoder_api_ver	Get libxcoder API version
ni_get_compat_fw_api_ver	Get FW API version libxcoder is compatible with
ni_get_libxcoder_release_ver	Get libxcoder SW release version
ni_network_layer_convert_output	Helper function to convert one layer’s output raw data in binary format to data in tensor format.
ni_ai_network_layer_size	Get one layer’s raw size in byte
ni_ai_network_layer_dims	Get one layer’s number of dimensions
ni_network_layer_convert_tensor	Helper function to convert one layer’s input file in tensor format to hardware raw input data in binary format.
ni_network_convert_tensor_to_data	Helper function to convert one layer’s input data in tensor format to hardware raw input data in binary format.
ni_network_convert_data_to_tensor	Helper function to convert one layer’s output raw data in binary format to data in tensor format with general buffers
ni_get_rc_txt	Get text string for the provided error
ni_param_get_key_value	Retrieve key and value from 'key=value' pair
ni_retrieve_xcoder_params	Retrieve encoder config parameter values
ni_retrieve_decoder_params	Retrieve decoder config parameter values
ni_calculate_sha256	Calculate the SHA256 value from data
ni_gettimeofday	Retrieve time for logs with microsecond timestamps
ni_gettime_ns	Retrieve the system clock time in nanoseconds
ni_usleep	Suspend execution for microsecond intervals
ni_posix_memalign	Allocate aligned memory
ni_pthread_mutex_init	Initialize a mutex which can be recursive.
ni_pthread_mutex_destroy	Destroy a mutex.
ni_pthread_mutex_lock	Thread mutex lock.
ni_pthread_mutex_unlock	Thread mutex unlock.
ni_pthread_create	Create a new thread.
ni_pthread_join	Join with a terminated thread.
ni_pthread_cond_init	Initialize a condition variable.
ni_pthread_cond_destroy	Destroy a condition variable.
ni_pthread_cond_broadcast	Broadcast a condition.
ni_pthread_cond_wait	Wait on a condition.
ni_pthread_cond_signal	Signal a condition.
ni_pthread_cond_timedwait	Wait on a condition with timeout.
ni_pthread_sigmask	Examine and change mask of blocked signals.

ni_av_codec.h Functions

API Functions in ni_av_codec.h	Description
ni_should_send_sei_with_frame	Whether SEI should be sent together with this frame to encoder
ni_dec_retrieve_aux_data	Retrieve auxiliary data (close caption, various SEI) associated with this frame returned by decoder, convert them to appropriate format and save in the frame's auxiliary data storage for future use by encoding.
ni_enc_prep_aux_data	Prepare auxiliary data to send with this frame to the encoder based on the auxiliary data of the decoded frame.
ni_enc_copy_aux_data	Copy auxiliary data that should be sent together with this frame to encoder
ni_enc_insert_timecode	Insert time code info into picture timing SEI (for H264) or time code SEI (for H265) which is sent together with a frame to encoder
ni_enc_write_from_yuv_buffer	Send an input data frame to the encoder with YUV data given in the inputs.
ni_device_session_restart	Send a restart command after flush command. Only support Encoder now.
ni_dec_reconfig_ppu_params	Send a p_config command to reconfigure decoding ppu params.