Detailed Description

The NvMediaIofa object takes an uncompressed bufObj frame pair and turns them into optical flow / stereo disparity estimation data.

6

Data Structures
struct	NvMediaIofaEpipolarInfo
	Structure holds Epipolar information. More...

struct	NvMediaIofaROIRectParams
	Holds Co-ordinates for Region of Interest. More...

struct	NvMediaIofaROIParams
	Structure holds ROI information. More...

struct	NvMediaIofaCapability
	Nvmedia Iofa Capability structure. More...

struct	NvMediaIofa
	Holds an IOFA object created and returned by NvMediaIOFACreate(). More...

struct	NvMediaIofaInitParams
	Holds IOFA Initialization API parameters. More...

struct	NvMediaIofaSGMParams
	Holds SGM parameters TBD: Add more details about SGM Params with input range. More...

struct	NvMediaIofaBufArray
	Holds pointers to NvMedia bufObjs containing input and output surfaces. More...

struct	NvMediaIofaPydHintParams
	Parameters related to input pyramid hint surface. More...

struct	NvMediaIofaProcessParams
	Holds IOFA Process Frame API parameters. More...

Macros
#define	NVMEDIA_IOFA_VERSION_MAJOR 1
	Major version number. More...

#define	NVMEDIA_IOFA_VERSION_MINOR 3
	Minor version number. More...

#define	NVMEDIA_IOFA_VERSION_PATCH 0
	Patch version number. More...

#define	NVMEDIA_IOFA_MAX_PYD_LEVEL 5U
	Maximum number of Pyramid level supported in Pyramid OF mode. More...

#define	NVMEDIA_IOFA_MAX_ROI_SUPPORTED 32U
	Maximum number of Region of Interest supported on IOFA. More...

#define	NVMEDIA_IOFA_MAX_PRENVSCISYNCFENCES 16U
	Specifies the maximum number of times NvMediaIOFAInsertPreNvSciSyncFence() can be called before each call to NvMediaIOFAProcessFrame(). More...

Typedefs
typedef struct NvMediaIofa	NvMediaIofa
	Holds an IOFA object created and returned by NvMediaIOFACreate(). More...

Enumerations
enum	NvMediaIofaMode { NVMEDIA_IOFA_MODE_STEREO = 0U, NVMEDIA_IOFA_MODE_PYDOF = 1U, NVMEDIA_IOFA_MODE_EPIOF = 2U }
	Defines mode supported by IOFA Driver. More...

enum	NvMediaIofaGridSize { NVMEDIA_IOFA_GRIDSIZE_1X1 = 0U, NVMEDIA_IOFA_GRIDSIZE_2X2 = 1U, NVMEDIA_IOFA_GRIDSIZE_4X4 = 2U, NVMEDIA_IOFA_GRIDSIZE_8X8 = 3U }
	Defines the Output Grid Size. More...

enum	NvMediaIofaPydMode { NVMEDIA_IOFA_PYD_FRAME_MODE = 0U, NVMEDIA_IOFA_PYD_LEVEL_MODE = 1U }
	Modes for pyramid SGM Applicable to Pyramid SGM IOFA mode only. More...

enum	NvMediaIofaDisparityRange { NVMEDIA_IOFA_DISPARITY_RANGE_128 = 0U, NVMEDIA_IOFA_DISPARITY_RANGE_256 = 1U }
	Defines IOFA Stereo DISPARITY RANGE. More...

enum	NvMediaIofaEpiSearchRange { NVMEDIA_IOFA_EPI_SEARCH_RANGE_128 = 0U, NVMEDIA_IOFA_EPI_SEARCH_RANGE_256 = 1U }
	Defines IOFA Flow Epipolar Search Range. More...

enum	NvMediaIofaPreset { NVMEDIA_IOFA_PRESET_HQ = 0U, NVMEDIA_IOFA_PRESET_HP = 1U }
	Nvmedia Iofa Preset. More...

enum	NvSciSyncTaskStatusOFA { NvSciSyncTaskStatusOFA_Success = 0U, NvSciSyncTaskStatusOFA_Error = 1U, NvSciSyncTaskStatusOFA_Execution_Start = 2U, NvSciSyncTaskStatusOFA_Error_CRC_Mismatch = 3U, NvSciSyncTaskStatusOFA_Error_Timeout = 4U, NvSciSyncTaskStatusOFA_Error_HW = 5U, NvSciSyncTaskStatusOFA_Error_Input_TaskStatus = 6U, NvSciSyncTaskStatusOFA_Error_SW = 7U, NvSciSyncTaskStatusOFA_Invalid = 0XFFFFU }
	NvMedia Iofa task status error codes. More...

Functions
NvMediaStatus	NvMediaIOFAGetVersion (NvMediaVersion *version)
	Retrieves the version information for the NvMedia IOFA library. More...

NvMediaIofa *	NvMediaIOFACreate (void)
	Creates an NvMediaIofa object that can compute optical flow or stereo disparity using two bufObjs. More...

NvMediaStatus	NvMediaIOFAInit (NvMediaIofa ofaPubl, const NvMediaIofaInitParams initParams, const uint8_t maxInputBuffering)
	Initializes the parameters for optical flow and stereo estimation. More...

NvMediaStatus	NvMediaIOFAProcessFrame (const NvMediaIofa ofaPubl, const NvMediaIofaBufArray pSurfArray, const NvMediaIofaProcessParams pProcessParams, const NvMediaIofaEpipolarInfo pEpiInfo, const NvMediaIofaROIParams *pROIParams)
	Performs IOFA estimation on a specified frame pair. More...

NvMediaStatus	NvMediaIOFADestroy (const NvMediaIofa *ofaPubl)
	Destroys the created NvMediaIofa object and frees associated resources. More...

NvMediaStatus	NvMediaIOFARegisterNvSciBufObj (const NvMediaIofa *ofaPubl, NvSciBufObj bufObj)
	Registers an NvSciBufObj for use with an NvMediaIofa handle. More...

NvMediaStatus	NvMediaIOFAUnregisterNvSciBufObj (const NvMediaIofa *ofaPubl, NvSciBufObj bufObj)
	Un-registers NvSciBufObj which was previously registered with NvMediaIofa using NvMediaIOFARegisterNvSciBufObj(). More...

NvMediaStatus	NvMediaIOFAGetSGMConfigParams (const NvMediaIofa ofaPubl, NvMediaIofaSGMParams pSGMParams)
	Get the SGM configuration parameters being used. More...

NvMediaStatus	NvMediaIOFASetSGMConfigParams (const NvMediaIofa ofaPubl, const NvMediaIofaSGMParams pSGMParams)
	Set the SGM configuration parameters to be used. More...

NvMediaStatus	NvMediaIOFAGetCapability (const NvMediaIofa ofaPubl, const NvMediaIofaMode mode, NvMediaIofaCapability pCapability)
	Get IOFA Capability. More...

NvMediaStatus	NvMediaIOFAFillNvSciBufAttrList (NvSciBufAttrList attrlist)
	Fills the NvMediaIofa specific NvSciBuf attributes which than then be used to allocate an NvSciBufObj that NvMediaIofa can consume. More...

NvMediaStatus	NvMediaIOFAFillNvSciSyncAttrList (const NvMediaIofa *ofaPubl, NvSciSyncAttrList attrlist, NvMediaNvSciSyncClientType clienttype)
	Fills the NvMediaIofa specific NvSciSync attributes. More...

NvMediaStatus	NvMediaIOFARegisterNvSciSyncObj (const NvMediaIofa *ofaPubl, NvMediaNvSciSyncObjType syncobjtype, NvSciSyncObj syncObj)
	Registers an NvSciSyncObj with NvMediaIofa. More...

NvMediaStatus	NvMediaIOFAUnregisterNvSciSyncObj (const NvMediaIofa *ofaPubl, NvSciSyncObj syncObj)
	Unregisters an NvSciSyncObj with NvMediaIofa. More...

NvMediaStatus	NvMediaIOFASetNvSciSyncObjforEOF (const NvMediaIofa *ofaPubl, NvSciSyncObj nvscisyncEOF)
	Specifies the NvSciSyncObj to be used for an EOF NvSciSyncFence. More...

NvMediaStatus	NvMediaIOFAInsertPreNvSciSyncFence (const NvMediaIofa ofaPubl, const NvSciSyncFence prenvscisyncfence)
	Sets an NvSciSyncFence as a prefence for an NvMediaIOFAProcessFrame() NvSciSyncFence operation. More...

NvMediaStatus	NvMediaIOFAGetEOFNvSciSyncFence (const NvMediaIofa ofaPubl, NvSciSyncObj eofnvscisyncobj, NvSciSyncFence eofnvscisyncfence)
	Gets EOF NvSciSyncFence for an NvMediaIOFAProcessFrame() operation. More...

Macro Definition Documentation

◆ NVMEDIA_IOFA_MAX_PRENVSCISYNCFENCES

#define NVMEDIA_IOFA_MAX_PRENVSCISYNCFENCES 16U

Specifies the maximum number of times NvMediaIOFAInsertPreNvSciSyncFence() can be called before each call to NvMediaIOFAProcessFrame().

Definition at line 59 of file nvmedia_iofa.h.

◆ NVMEDIA_IOFA_MAX_PYD_LEVEL

#define NVMEDIA_IOFA_MAX_PYD_LEVEL 5U

Maximum number of Pyramid level supported in Pyramid OF mode.

Definition at line 51 of file nvmedia_iofa.h.

◆ NVMEDIA_IOFA_MAX_ROI_SUPPORTED

#define NVMEDIA_IOFA_MAX_ROI_SUPPORTED 32U

Maximum number of Region of Interest supported on IOFA.

Definition at line 53 of file nvmedia_iofa.h.

◆ NVMEDIA_IOFA_VERSION_MAJOR

#define NVMEDIA_IOFA_VERSION_MAJOR 1

Major version number.

Definition at line 44 of file nvmedia_iofa.h.

◆ NVMEDIA_IOFA_VERSION_MINOR

#define NVMEDIA_IOFA_VERSION_MINOR 3

Minor version number.

Definition at line 46 of file nvmedia_iofa.h.

◆ NVMEDIA_IOFA_VERSION_PATCH

#define NVMEDIA_IOFA_VERSION_PATCH 0

Patch version number.

Definition at line 48 of file nvmedia_iofa.h.

Typedef Documentation

◆ NvMediaIofa

typedef struct NvMediaIofa NvMediaIofa

Holds an IOFA object created and returned by NvMediaIOFACreate().

Enumeration Type Documentation

◆ NvMediaIofaDisparityRange

enum NvMediaIofaDisparityRange

Defines IOFA Stereo DISPARITY RANGE.

Enumerator
NVMEDIA_IOFA_DISPARITY_RANGE_128	Maximum Stereo Disparity Range of 128 pixels.
NVMEDIA_IOFA_DISPARITY_RANGE_256	Maximum Stereo Disparity Range of 256 pixels.

Definition at line 121 of file nvmedia_iofa.h.

◆ NvMediaIofaEpiSearchRange

enum NvMediaIofaEpiSearchRange

Defines IOFA Flow Epipolar Search Range.

Enumerator
NVMEDIA_IOFA_EPI_SEARCH_RANGE_128	Maximum Epipolar Flow Search Range of 128 pixels.
NVMEDIA_IOFA_EPI_SEARCH_RANGE_256	Maximum Epipolar Flow Search Range of 256 pixels.

Definition at line 132 of file nvmedia_iofa.h.

◆ NvMediaIofaGridSize

enum NvMediaIofaGridSize

Defines the Output Grid Size.

IOFA supports variable flow vector/disparity output density.
IOFA provides single output for each input region corrosponding to grid block size.
Grid Size controls flow vector/disparity map granularity.
Application can set any grid size from the list of Grid sizes supported by IOFA.

Enumerator
NVMEDIA_IOFA_GRIDSIZE_1X1	Grid Size 1x1.
NVMEDIA_IOFA_GRIDSIZE_2X2	Grid Size 2x2.
NVMEDIA_IOFA_GRIDSIZE_4X4	Grid Size 4x4.
NVMEDIA_IOFA_GRIDSIZE_8X8	Grid Size 8x8.

Definition at line 82 of file nvmedia_iofa.h.

◆ NvMediaIofaMode

enum NvMediaIofaMode

Defines mode supported by IOFA Driver.

Enumerator

NVMEDIA_IOFA_MODE_STEREO

IOFA stereo disparity mode.

NVMEDIA_IOFA_MODE_PYDOF

IOFA pyramid optical flow mode.

NVMEDIA_IOFA_MODE_EPIOF

OFA epipolar optical flow mode.

Epipolar OF support will be added in next release

Definition at line 64 of file nvmedia_iofa.h.

◆ NvMediaIofaPreset

enum NvMediaIofaPreset

Nvmedia Iofa Preset.

Enumerator
NVMEDIA_IOFA_PRESET_HQ	High Quality Preset.
NVMEDIA_IOFA_PRESET_HP	High Performance Preset.

Definition at line 143 of file nvmedia_iofa.h.

◆ NvMediaIofaPydMode

enum NvMediaIofaPydMode

Modes for pyramid SGM
Applicable to Pyramid SGM IOFA mode only.

Enumerator

NVMEDIA_IOFA_PYD_FRAME_MODE

All pyramid levels of a input and reference frame will be processed in single NvMediaIOFAProcessFrame call.

In this mode, the outSurface of previous pyramid level is directly (without any processing) provided as pydHintSurface to process current pyramid level by IOFA driver.
pydHintSurface[lvl] = outSurface[lvl+1]

NVMEDIA_IOFA_PYD_LEVEL_MODE

A single pyramid level of a input and reference frame will be processed by NvMediaIOFAProcessFrame API
In this mode, the outSurface of previous pyramid level can be processed/filtered by application and then provided as pydHinSurface to process current pyramid level.

NvMediaIOFAProcessFrame API accept pydHintSurface only in NVMEDIA_IOFA_PYD_LEVEL_MODE.
otherwise pydHintSurface is ignored by IOFA driver.
pydHintSurface[lvl] = filter(outSurface[lvl+1],....)

Definition at line 98 of file nvmedia_iofa.h.

◆ NvSciSyncTaskStatusOFA

enum NvSciSyncTaskStatusOFA

NvMedia Iofa task status error codes.

Enumerator
NvSciSyncTaskStatusOFA_Success	task is finished successully
NvSciSyncTaskStatusOFA_Error	task status error codes
NvSciSyncTaskStatusOFA_Execution_Start
NvSciSyncTaskStatusOFA_Error_CRC_Mismatch
NvSciSyncTaskStatusOFA_Error_Timeout
NvSciSyncTaskStatusOFA_Error_HW
NvSciSyncTaskStatusOFA_Error_Input_TaskStatus
NvSciSyncTaskStatusOFA_Error_SW
NvSciSyncTaskStatusOFA_Invalid	task status support is not enable

Definition at line 154 of file nvmedia_iofa.h.

Function Documentation

◆ NvMediaIOFACreate()

NvMediaIofa* NvMediaIOFACreate ( void )

Creates an NvMediaIofa object that can compute optical flow or stereo disparity using two bufObjs.

Precondition: NvMediaIOFAGetVersion()

Postcondition: NvMediaIofa object is created

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: No

Returns: Created NvMediaIofa estimator handle if successful, or NULL otherwise.

◆ NvMediaIOFADestroy()

NvMediaStatus NvMediaIOFADestroy ( const NvMediaIofa * ofaPubl )

Destroys the created NvMediaIofa object and frees associated resources.

Precondition: NvMediaIOFAUnregisterNvSciSyncObj(); NvMediaIOFAUnregisterNvSciBufObj()

Postcondition: NvMediaIofa object is destroyed

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions
  - Every thread should be invoked with relevant NvMediaIofa object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: Yes

Parameters

[in] ofaPubl Pointer to the NvMediaIofa object to destroy, returned by NvMediaIOFACreate(). Non-NULL - valid pointer address

Returns

The completion status of the operation:

NVMEDIA_STATUS_OK if the call is successful.
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameters are invalid.
NVMEDIA_STATUS_INVALID_STATE The function was called in incorrect system state.
NVMEDIA_STATUS_ERROR if there is an internal error in processing.

◆ NvMediaIOFAFillNvSciBufAttrList()

NvMediaStatus NvMediaIOFAFillNvSciBufAttrList ( NvSciBufAttrList attrlist )

Fills the NvMediaIofa specific NvSciBuf attributes which than then be used to allocate an NvSciBufObj that NvMediaIofa can consume.

This function updates the input NvSciBufAttrList with values equivalent to the following public attribute key-values: NvSciBufGeneralAttrKey_PeerHwEngineArray set to

NvSciBufHwEngName: NvSciBufHwEngName_OFA
NvSciBufPlatformName: NvSciBufPlatformName_Orin

This function assumes that attrlist is a valid NvSciBufAttrList created by the caller by a call to NvSciBufAttrListCreate.

Precondition: NvMediaIOFAGetVersion()

Postcondition: NvSciBufAttrList populated with NvMediaIofa specific NvSciBuf attributes. The caller can then set attributes specific to the type of surface, reconcile attribute lists and allocate an NvSciBufObj.

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: No

Parameters

[out] attrlist A pointer to an NvSciBufAttrList structure where NvMediaIofa places the NvSciBuf attributes.

Returns

NvMediaStatus The status of the operation. Possible values are:

NVMEDIA_STATUS_OK if the function is successful.
NVMEDIA_STATUS_INVALID_STATE The function was called in incorrect system state.
NVMEDIA_STATUS_BAD_PARAMETER if attrlist is NULL

◆ NvMediaIOFAFillNvSciSyncAttrList()

NvMediaStatus NvMediaIOFAFillNvSciSyncAttrList	(	const NvMediaIofa *	ofaPubl,
		NvSciSyncAttrList	attrlist,
		NvMediaNvSciSyncClientType	clienttype
	)

Fills the NvMediaIofa specific NvSciSync attributes.

This function assumes that attrlist is a valid NvSciSyncAttrList.

This function updates the input NvSciSyncAttrList with values equivalent to the following public attribute key-values: NvSciSyncAttrKey_RequiredPerm set to

NvSciSyncAccessPerm_WaitOnly for clienttype NVMEDIA_WAITER
NvSciSyncAccessPerm_SignalOnly for clienttype NVMEDIA_SIGNALER
NvSciSyncAccessPerm_WaitSignal for clienttype NVMEDIA_SIGNALER_WAITER NvSciSyncAttrKey_PrimitiveInfo set to
NvSciSyncAttrValPrimitiveType_Syncpoint

The application must not set these attributes in the NvSciSyncAttrList passed as an input to this function.

Precondition: NvMediaIOFACreate()

Postcondition: NvSciSyncAttrList populated with NvMediaIofa specific NvSciSync attributes

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions
  - Every thread should be invoked with relevant NvMediaIofa object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: No

Note: This API is mandatory when multiple engines are pipelined in order to achieve synchronization between the engines

Parameters

[in]	ofaPubl	A pointer to the NvMediaIofa object. Input range: Can be NULL or Non-NULL valid pointer address
[out]	attrlist	A pointer to an NvSciSyncAttrList structure where NvMedia places NvSciSync attributes.
[in]	clienttype	Indicates whether the NvSciSyncAttrList requested for an NvMediaIofa signaler or an NvMediaIofa waiter. Input range: Entries in NvMediaNvSciSyncClientType enumeration

Returns

NvMediaStatus The status of the operation. Possible values are:

NVMEDIA_STATUS_OK if the function is successful.
NVMEDIA_STATUS_BAD_PARAMETER if attrlist is NULL, or any of the public attributes listed above are already set.
NVMEDIA_STATUS_INVALID_STATE The function was called in incorrect system state.
NVMEDIA_STATUS_OUT_OF_MEMORY if there is not enough memory for the requested operation.

◆ NvMediaIOFAGetCapability()

NvMediaStatus NvMediaIOFAGetCapability	(	const NvMediaIofa *	ofaPubl,
		const NvMediaIofaMode	mode,
		NvMediaIofaCapability *	pCapability
	)

Get IOFA Capability.

This function returns ofa hw capabilities.

Precondition: NvMediaIOFACreate

Postcondition: hw capabilities are returned in structure NvMediaIofaCapability

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions
  - Every thread should be invoked with relevant NvMediaIofa object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: No

Considerations for Safety:

Operation Mode: Init

Parameters

[in]	ofaPubl	Pointer to the NvMediaIofa object to use. Non-NULL - valid pointer address
[in]	mode	one of the value from NvMediaIofaMode.
[out]	pCapability	A pointer to a structure that contains capability data

Returns

The completion status of the operation:

NVMEDIA_STATUS_OK if the call is successful.
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameters are invalid.
NVMEDIA_STATUS_INVALID_STATE The function was called in incorrect system state.
NVMEDIA_STATUS_ERROR if there is an internal error in processing.

◆ NvMediaIOFAGetEOFNvSciSyncFence()

NvMediaStatus NvMediaIOFAGetEOFNvSciSyncFence	(	const NvMediaIofa *	ofaPubl,
		NvSciSyncObj	eofnvscisyncobj,
		NvSciSyncFence *	eofnvscisyncfence
	)

Gets EOF NvSciSyncFence for an NvMediaIOFAProcessFrame() operation.

The EOF NvSciSyncFence associated with an NvMediaIOFAProcessFrame() operation is an NvSciSyncFence. Its expiry indicates that the corresponding NvMediaIOFAProcessFrame() operation has finished.

This function returns the EOF NvSciSyncFence associated with the last NvMediaIOFAProcessFrame() call. NvMediaIOFAGetEOFNvSciSyncFence() must be called after an NvMediaIOFAProcessFrame() call.

For example, in this sequence of code:

nvmstatus = NvMediaIOFAProcessFrame(handle, srcsurf, srcrect, picparams, instanceid);

nvmstatus = NvMediaIOFAGetEOFNvSciSyncFence(handle, nvscisyncEOF, eofnvscisyncfence);

expiry of eofnvscisyncfence indicates that the preceding NvMediaIOFAProcessFrame() operation has finished.

Precondition: NvMediaIOFASetNvSciSyncObjforEOF(); NvMediaIOFAProcessFrame()

Postcondition: EOF NvSciSync fence for a submitted task is obtained

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions
  - Every thread should be invoked with relevant NvMediaIofa object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

Note: This API is mandatory when multiple engines are pipelined in order to achieve synchronization between the engines

Parameters

[in]	ofaPubl	A pointer to the NvMediaIofa object. Input range: Non-NULL - valid pointer address
[in]	eofnvscisyncobj	An EOF NvSciSyncObj associated with the NvSciSyncFence which is being requested. Input range: A valid NvSciSyncObj
[out]	eofnvscisyncfence	A pointer to the EOF NvSciSyncFence.

Returns

NvMediaStatus The status of the operation. Possible values are:

NVMEDIA_STATUS_OK if the function is successful.
NVMEDIA_STATUS_BAD_PARAMETER if ofaPubl is not a valid NvMediaIofa handle, eofnvscisyncfence is NULL, or eofnvscisyncobj is not registered with ofaPubl as type NVMEDIA_EOFSYNCOBJ or NVMEDIA_EOF_PRESYNCOBJ.
NVMEDIA_STATUS_ERROR if the function was called before NvMediaIOFAProcessFrame() was called.

◆ NvMediaIOFAGetSGMConfigParams()

NvMediaStatus NvMediaIOFAGetSGMConfigParams	(	const NvMediaIofa *	ofaPubl,
		NvMediaIofaSGMParams *	pSGMParams
	)

Get the SGM configuration parameters being used.

Precondition: NvMediaIOFAInit()

Postcondition: SGM params are returned in structure NvMediaIofaSGMParams

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions
  - Every thread should be invoked with relevant NvMediaIofa object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

Parameters

[in]	ofaPubl	Pointer to the NvMediaIofa object to use. Non-NULL - valid pointer address
[out]	pSGMParams	A pointer to a structure that specifies SGM parameters.

Returns

The completion status of the operation:

NVMEDIA_STATUS_OK if the function call is successful.
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameters are invalid.
NVMEDIA_STATUS_ERROR if there is an internal error in processing.

◆ NvMediaIOFAGetVersion()

NvMediaStatus NvMediaIOFAGetVersion ( NvMediaVersion * version )

Retrieves the version information for the NvMedia IOFA library.

Precondition: None

Postcondition: None

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: Yes
- De-Init: Yes

Parameters

[out] version A pointer to a NvMediaVersion structure filled by the IOFA library.

Returns

NvMediaStatus, the completion status of the operation:

NVMEDIA_STATUS_OK if successful.
NVMEDIA_STATUS_BAD_PARAMETER if the version pointer is NULL.

◆ NvMediaIOFAInit()

NvMediaStatus NvMediaIOFAInit	(	NvMediaIofa *	ofaPubl,
		const NvMediaIofaInitParams *	initParams,
		const uint8_t	maxInputBuffering
	)

Initializes the parameters for optical flow and stereo estimation.

Precondition: NvMediaIOFAGetVersion(); NvMediaIOFACreate()

Postcondition: NvMediaIofa object is returned with initialized parameters

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: No

Parameters

[in]	ofaPubl	A pointer to the NvMediaIofa estimator to use. Non-NULL - valid pointer address
[in]	initParams	A pointer to a structure that specifies initialization parameters. Non-NULL - valid address. Ranges specific to each member in the structure can be found in NvMediaIofaInitParams.
[in]	maxInputBuffering	Maximum number of NvMediaIOFAProcessFrame() operations that can be queued by NvMediaIofa. If more than maxInputBuffering operations are queued, NvMediaIOFAProcessFrame() returns an error to indicate insufficient buffering. The values between 1 to 8, in increments of 1

Returns

The completion status of the operation:

NVMEDIA_STATUS_OK if the call is successful.
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameters are invalid.
NVMEDIA_STATUS_INVALID_STATE The function was called in incorrect system state.
NVMEDIA_STATUS_ERROR if there is an internal error in processing.

◆ NvMediaIOFAInsertPreNvSciSyncFence()

NvMediaStatus NvMediaIOFAInsertPreNvSciSyncFence	(	const NvMediaIofa *	ofaPubl,
		const NvSciSyncFence *	prenvscisyncfence
	)

Sets an NvSciSyncFence as a prefence for an NvMediaIOFAProcessFrame() NvSciSyncFence operation.

You must call NvMediaIOFAInsertPreNvSciSyncFence() before you call NvMediaIOFAProcessFrame(). The NvMediaIOFAProcessFrame() operation is started only after the expiry of the prenvscisyncfence.

For example, in this sequence of code:

nvmstatus = NvMediaIOFAInsertPreNvSciSyncFence(handle, prenvscisyncfence);

nvmstatus = NvMediaIOFAProcessFrame(handle, srcsurf, srcrect, picparams, instanceid);

the NvMediaIOFAProcessFrame() operation is assured to start only after the expiry of prenvscisyncfence.

You can set a maximum of NVMEDIA_IOFA_MAX_PRENVSCISYNCFENCES prefences by calling NvMediaIOFAInsertPreNvSciSyncFence() before NvMediaIOFAProcessFrame(). After the call to NvMediaIOFAProcessFrame(), all NvSciSyncFences previously inserted by NvMediaIOFAInsertPreNvSciSyncFence() are removed, and they are not reused for the subsequent NvMediaIOFAProcessFrame() calls.

Precondition: Pre-NvSciSync fence obtained from previous engine in the pipeline

Postcondition: Pre-NvSciSync fence is set

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions
  - Every thread should be invoked with relevant NvMediaIofa object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

Note: This API is mandatory when multiple engines are pipelined in order to achieve synchronization between the engines

Parameters

[in]	ofaPubl	A pointer to the NvMediaIofa object. Input range: Non-NULL - valid pointer address
[in]	prenvscisyncfence	A pointer to NvSciSyncFence. Input range: Non-NULL - valid pointer address

Returns

NvMediaStatus The status of the operation. Possible values are:

NVMEDIA_STATUS_OK if the function is successful.
NVMEDIA_STATUS_BAD_PARAMETER if ofaPubl is not a valid NvMediaIofa handle, or prenvscisyncfence is NULL, or if prenvscisyncfence was not generated with an NvSciSyncObj that was registered with ofaPubl as either NVMEDIA_PRESYNCOBJ or NVMEDIA_EOF_PRESYNCOBJ type.
NVMEDIA_STATUS_NOT_SUPPORTED if NvMediaIOFAInsertPreNvSciSyncFence() has already been called at least NVMEDIA_IOFA_MAX_PRENVSCISYNCFENCES times with the same ofaPubl handle before an NvMediaIOFAProcessFrame() call.

◆ NvMediaIOFAProcessFrame()

NvMediaStatus NvMediaIOFAProcessFrame	(	const NvMediaIofa *	ofaPubl,
		const NvMediaIofaBufArray *	pSurfArray,
		const NvMediaIofaProcessParams *	pProcessParams,
		const NvMediaIofaEpipolarInfo *	pEpiInfo,
		const NvMediaIofaROIParams *	pROIParams
	)

Performs IOFA estimation on a specified frame pair.

Estimation is based on the difference between refFrame and inputframe. The output of Optical Flow processing is motion vectors [X, Y Components], and that of Stereo Disparity processing is a disparity surface [X component].

Precondition: NvMediaIOFAInit(); NvMediaIOFARegisterNvSciBufObj(); NvMediaIOFARegisterNvSciSyncObj(); NvMediaIOFASetNvSciSyncObjforEOF(); NvMediaIOFAInsertPreNvSciSyncFence()

Postcondition: Optical Flow Accelerator estimation task is submitted

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions
  - Every thread should be invoked with relevant NvMediaIofa object.
- Re-entrant: No
- Async/Sync: Async
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

Parameters

[in]	ofaPubl	A pointer to the NvMediaIOFA estimator to use. Non-NULL - valid pointer address
[in]	surfArray	A pointer to a structure that specifies input and output surface parameters. Non-NULL - valid address. Ranges specific to each member in the structure can be found in NvMediaIofaBufArray.
[in]	processParams	A pointer to a structure that specifies process frame parameters. Non-NULL - valid address. Ranges specific to each member in the structure can be found in NvMediaIofaProcessParams.
[in]	pROIParams	A pointer to a structure that specifies ROI parameters. Note: HW will generate output for ROI region only and Single ROI should give best perf for pyramid SGM Mode. pROIParams are optional argument and can be NULL if ROI is not set by App. Ranges specific to each member in the structure can be found in NvMediaIofaROIParams.
[in]	pEpipolarInfo	A pointer to a structure that specifies Epipolar info parameters. pEpipolarInfo is required argument only when /ref ofaMode in /ref NvMediaIofaInitParams is set to /ref NVMEDIA_IOFA_MODE_EPIOF. Ranges specific to each member in the structure can be found in NvMediaIofaEpipolarInfo. Epipolar OF support will be added in next release. Ignored right now in driver. Set it to NULL till EpiPolar OF support is enabled.

Returns

The completion status of the operation:

NVMEDIA_STATUS_OK if the call is successful.
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameters are invalid.
NVMEDIA_STATUS_ERROR if there is an internal error in processing.

◆ NvMediaIOFARegisterNvSciBufObj()

NvMediaStatus NvMediaIOFARegisterNvSciBufObj	(	const NvMediaIofa *	ofaPubl,
		NvSciBufObj	bufObj
	)

Registers an NvSciBufObj for use with an NvMediaIofa handle.

The NvMediaIofa handle maintains a record of all the bufObjs registered using this API.

This is a mandatory API which needs to be called before NvMediaIOFAProcessFrame()
All NvMediaIOFANvSciBufRegister() API calls must be made before first NvMediaIOFAProcessFrame() API call. Registration of the buffer is done with the same access permission as that of the NvSciBufObj being registered. NvSciBufObj that need to be registered with a reduced permission (Eg: Input buffer accesses being set to read-only) can be done so by first duplicating the NvSciBufObj using NvSciBufObjDupWithReducePerm() followed by a call the register the duplicated NvSciBufObj.

Maximum of 192 NvSciBufObj handles can be registered using NvMediaIOFARegisterNvSciSyncObj() API.

Precondition: NvMediaIOFAInit(); NvMediaIOFARegisterNvSciSyncObj()

Postcondition: NvSciBufObj is registered with NvMediaIofa object

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions
  - Every thread should be invoked with relevant NvMediaIofa object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: No

Parameters

[in]	ofaPubl	NvMediaIofa handle. Input range: Non-NULL - valid pointer address
[in]	bufObj	An NvSciBufObj object. Input range: A valid NvSciBufObj

Returns

NvMediaStatus, the completion status of operation:

NVMEDIA_STATUS_OK if successful.
NVMEDIA_STATUS_BAD_PARAMETER if ofa, bufObj or accessMode is invalid.
NVMEDIA_STATUS_INVALID_STATE The function was called in incorrect system state.
NVMEDIA_STATUS_ERROR in following cases:
- User registers more than 192 bufObjs.
- User registers same bufObj with more than one accessModes.
- User registers same bufObj multiple times.

◆ NvMediaIOFARegisterNvSciSyncObj()

NvMediaStatus NvMediaIOFARegisterNvSciSyncObj	(	const NvMediaIofa *	ofaPubl,
		NvMediaNvSciSyncObjType	syncobjtype,
		NvSciSyncObj	syncObj
	)

Registers an NvSciSyncObj with NvMediaIofa.

Every NvSciSyncObj (even duplicate objects) used by NvMediaIofa must be registered by a call to this function before it is used. Only the exact same registered NvSciSyncObj can be passed to NvMediaIOFASetNvSciSyncObjforEOF(), NvMediaIOFAGetEOFNvSciSyncFence(), or NvMediaIOFAUnregisterNvSciSyncObj().

For a given NvMediaIofa handle, one NvSciSyncObj can be registered as one NvMediaNvSciSyncObjType only. For each NvMediaNvSciSyncObjType, a maximum of 16 NvSciSyncObjs can be registered.

Precondition: NvMediaIOFAFillNvSciSyncAttrList()

Postcondition: NvSciSyncObj registered with NvMediaIofa

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions
  - Every thread should be invoked with relevant NvMediaIofa object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: No

Note: This API is mandatory when multiple engines are pipelined in order to achieve synchronization between the engines

Parameters

[in]	ofaPubl	A pointer to the NvMediaIofa object. Input range: Non-NULL - valid pointer address
[in]	syncobjtype	Determines how nvscisync is used by ofaPubl. Input range: Entries in NvMediaNvSciSyncObjType enumeration
[in]	nvscisync	The NvSciSyncObj to be registered with ofaPubl. Input range: A valid NvSciSyncObj

Returns

NvMediaStatus The status of the operation. Possible values are:

NVMEDIA_STATUS_OK if the function is successful.
NVMEDIA_STATUS_BAD_PARAMETER if ofaPubl is NULL or syncobjtype is not a valid NvMediaNvSciSyncObjType. only NVMEDIA_EOFSYNCOBJ and NVMEDIA_PRESYNCOBJ supported.
NVMEDIA_STATUS_NOT_SUPPORTED if nvscisync is not a compatible NvSciSiyncObj which NvMediaIofa can support.
NVMEDIA_STATUS_INVALID_STATE The function was called in incorrect system state.
NVMEDIA_STATUS_ERROR if the maximum number of NvSciScynObjs are already registered for the given syncobjtype, or if nvscisync is already registered with the same ofaPubl handle for a different syncobjtype.

◆ NvMediaIOFASetNvSciSyncObjforEOF()

NvMediaStatus NvMediaIOFASetNvSciSyncObjforEOF	(	const NvMediaIofa *	ofaPubl,
		NvSciSyncObj	nvscisyncEOF
	)

Specifies the NvSciSyncObj to be used for an EOF NvSciSyncFence.

To use NvMediaIOFAGetEOFNvSciSyncFence(), the application must call NvMediaIOFASetNvSciSyncObjforEOF() before it calls NvMediaIOFAProcessFrame().

NvMediaIOFASetNvSciSyncObjforEOF() currently may be called only once before each call to NvMediaIOFAProcessFrame(). The application may choose to call this function only once before the first call to NvMediaIOFAProcessFrame().

Precondition: NvMediaIOFARegisterNvSciSyncObj()

Postcondition: NvSciSyncObj to be used as EOF NvSciSyncFence is set

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions
  - Every thread should be invoked with relevant NvMediaIofa object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

Note: This API is mandatory when multiple engines are pipelined in order to achieve synchronization between the engines

Parameters

[in]	ofaPubl	A pointer to the NvMediaIofa object. Input range: Non-NULL - valid pointer address
[in]	nvscisyncEOF	A registered NvSciSyncObj which is to be associated with EOF NvSciSyncFence. Input range: A valid NvSciSyncObj

Returns

NvMediaStatus The status of the operation. Possible values are:

NVMEDIA_STATUS_OK if the function is successful.
NVMEDIA_STATUS_BAD_PARAMETER if ofaPubl is NULL, or if nvscisyncEOF is not registered with ofaPubl as either type NVMEDIA_EOFSYNCOBJ or NVMEDIA_EOF_PRESYNCOBJ.

◆ NvMediaIOFASetSGMConfigParams()

NvMediaStatus NvMediaIOFASetSGMConfigParams	(	const NvMediaIofa *	ofaPubl,
		const NvMediaIofaSGMParams *	pSGMParams
	)

Set the SGM configuration parameters to be used.

Precondition: NvMediaIOFAInit()

Postcondition: SGM params are set in IOFA driver and will be used for next frame processing.

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions
  - Every thread should be invoked with relevant NvMediaIofa object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

Parameters

[in]	ofaPubl	Pointer to the NvMediaIofa object to use. Non-NULL - valid pointer address
[in]	pSGMParams	A pointer to a structure that specifies SGM parameters.

Returns

The completion status of the operation:

NVMEDIA_STATUS_OK if the function call is successful.
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameters are invalid.
NVMEDIA_STATUS_ERROR if there is an internal error in processing.

◆ NvMediaIOFAUnregisterNvSciBufObj()

NvMediaStatus NvMediaIOFAUnregisterNvSciBufObj	(	const NvMediaIofa *	ofaPubl,
		NvSciBufObj	bufObj
	)

Un-registers NvSciBufObj which was previously registered with NvMediaIofa using NvMediaIOFARegisterNvSciBufObj().

For all NvSciBufObj handles registered with NvMediaIofa using NvMediaIOFARegisterNvSciBufObj() API, NvMediaIOFAUnregisterNvSciBufObj() must be called before calling NvMediaIOFADestroy() API. For unregistration to succeed, it should be ensured that none of the submitted tasks on the bufObj are pending prior to calling NvMediaIOFAUnregisterNvSciBufObj(). In order to ensure this, NvMediaIOFAUnregisterNvSciSyncObj() should be called prior to this API on all registered NvSciSyncObj. Post this NvMediaIOFAUnregisterNvSciBufObj() can be successfully called on a valid NvSciBufObj.

For deterministic execution of NvMediaIOFAProcessFrame() API, NvMediaIOFAUnregisterNvSciBufObj() must be called only after last NvMediaIOFAProcessFrame() call.

Precondition: NvMediaIOFAUnregisterNvSciSyncObj() [verify that processing is complete]

Postcondition: NvSciBufObj is un-registered from NvMediaIofa object

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions
  - Every thread should be invoked with relevant NvMediaIofa object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: Yes

Parameters

[in]	ofaPubl	NvMediaIofa handle. Input range: Non-NULL - valid pointer address
[in]	bufObj	An NvSciBufObj object. Input range: A valid NvSciBufObj

Returns

NvMediaStatus, the completion status of operation:

NVMEDIA_STATUS_OK if successful.
NVMEDIA_STATUS_BAD_PARAMETER if ofa or bufObj is invalid NvMediaIOFARegisterNvSciBufObj() API.
NVMEDIA_STATUS_INVALID_STATE The function was called in incorrect system state.
NVMEDIA_STATUS_ERROR in following cases:
- User unregisters an NvSciBufObj which is not previously registered using NvMediaIOFARegisterNvSciBufObj() API.
- User unregisters an NvSciBufObj multiple times.

◆ NvMediaIOFAUnregisterNvSciSyncObj()

NvMediaStatus NvMediaIOFAUnregisterNvSciSyncObj	(	const NvMediaIofa *	ofaPubl,
		NvSciSyncObj	syncObj
	)

Unregisters an NvSciSyncObj with NvMediaIofa.

Every NvSciSyncObj registered with NvMediaIofa by NvMediaIOFARegisterNvSciSyncObj() must be unregistered before calling NvMediaIOFAUnregisterNvSciBufObj to unregister the NvSciBufObjs.

Before the application calls this function, it must ensure that any NvMediaIOFAProcessFrame() operation that uses the NvSciSyncObj has completed. If this function is called while NvSciSyncObj is still in use by any NvMediaIOFAProcessFrame() operation, the API returns NVMEDIA_STATUS_PENDING to indicate the same. NvSciSyncFenceWait() API can be called on the EOF NvSciSyncFence obtained post the last call to NvMediaIOFAProcessFrame() to wait for the associated tasks to complete. The EOF NvSciSyncFence would have been previously obtained via a call to NvMediaIOFAGetEOFNvSciSyncFence().

Precondition: NvMediaIOFAProcessFrame(); NvSciSyncFenceWait() [verify that processing is complete]

Postcondition: NvSciSyncObj un-registered with NvMediaIofa

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions
  - Every thread should be invoked with relevant NvMediaIofa object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: Yes

Note: This API is mandatory when multiple engines are pipelined in order to achieve synchronization between the engines

Parameters

[in]	ofaPubl	A pointer to the NvMediaIofa object. Input range: Non-NULL - valid pointer address
[in]	nvscisync	An NvSciSyncObj to be unregistered with ofaPubl. Input range: A valid NvSciSyncObj

Returns

NvMediaStatus The status of the operation. Possible values are:

NVMEDIA_STATUS_OK if the function is successful.
NVMEDIA_STATUS_BAD_PARAMETER if ofaPubl is NULL, or nvscisync is not registered with ofaPubl.
NVMEDIA_STATUS_PENDING if the NvSciSyncObj is still in use, i.e., the submitted task is still in progress. In this case, the application can choose to wait for operations to complete on the output surface using NvSciSyncFenceWait() or re-try the NvMediaIOFAUnregisterNvSciBufObj() API call, until the status returned is inot NVMEDIA_STATUS_PENDING.
NVMEDIA_STATUS_INVALID_STATE The function was called in incorrect system state.
NVMEDIA_STATUS_ERROR if ofaPubl was destroyed before this function was called.


NVIDIA DRIVE OS Linux SDK API Reference	6.0.9 Release

NVIDIA DRIVE OS Linux SDK API Reference

6.0.9 Release

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ NVMEDIA_IOFA_MAX_PRENVSCISYNCFENCES

◆ NVMEDIA_IOFA_MAX_PYD_LEVEL

◆ NVMEDIA_IOFA_MAX_ROI_SUPPORTED

◆ NVMEDIA_IOFA_VERSION_MAJOR

◆ NVMEDIA_IOFA_VERSION_MINOR

◆ NVMEDIA_IOFA_VERSION_PATCH

Typedef Documentation

◆ NvMediaIofa

Enumeration Type Documentation

◆ NvMediaIofaDisparityRange

◆ NvMediaIofaEpiSearchRange

◆ NvMediaIofaGridSize

◆ NvMediaIofaMode

◆ NvMediaIofaPreset

◆ NvMediaIofaPydMode

◆ NvSciSyncTaskStatusOFA

Function Documentation

◆ NvMediaIOFACreate()

◆ NvMediaIOFADestroy()

◆ NvMediaIOFAFillNvSciBufAttrList()

◆ NvMediaIOFAFillNvSciSyncAttrList()

◆ NvMediaIOFAGetCapability()

◆ NvMediaIOFAGetEOFNvSciSyncFence()

◆ NvMediaIOFAGetSGMConfigParams()

◆ NvMediaIOFAGetVersion()

◆ NvMediaIOFAInit()

◆ NvMediaIOFAInsertPreNvSciSyncFence()

◆ NvMediaIOFAProcessFrame()

◆ NvMediaIOFARegisterNvSciBufObj()

◆ NvMediaIOFARegisterNvSciSyncObj()

◆ NvMediaIOFASetNvSciSyncObjforEOF()

◆ NvMediaIOFASetSGMConfigParams()

◆ NvMediaIOFAUnregisterNvSciBufObj()

◆ NvMediaIOFAUnregisterNvSciSyncObj()