2D Surface and Synchronization

Detailed Description

The NvMedia 2D NvSci API encompasses all NvMedia 2D handling for NvSciBuf NvSciSync related functions.

6

Functions
NvMediaStatus	NvMedia2DFillNvSciBufAttrList (NvMedia2D *const handle, NvSciBufAttrList const attrList)
	Fills the NvMedia 2D specific NvSciBuf attributes. More...
NvMediaStatus	NvMedia2DFillNvSciSyncAttrList (NvMedia2D *const handle, NvSciSyncAttrList const attrList, NvMediaNvSciSyncClientType const clientType)
	Fills the NvMedia 2D specific NvSciSync attributes. More...
NvMediaStatus	NvMedia2DRegisterNvSciBufObj (NvMedia2D *const handle, NvSciBufObj const bufObj)
	Register an NvSciBufObj with NvMedia 2D. More...
NvMediaStatus	NvMedia2DRegisterNvSciSyncObj (NvMedia2D *const handle, NvMediaNvSciSyncObjType const syncObjType, NvSciSyncObj const syncObj)
	Register an NvSciSyncObj with NvMedia 2D. More...
NvMediaStatus	NvMedia2DUnregisterNvSciBufObj (NvMedia2D *const handle, NvSciBufObj bufObj)
	Unregisters an NvSciBufObj with NvMedia2D. More...
NvMediaStatus	NvMedia2DUnregisterNvSciSyncObj (NvMedia2D *const handle, NvSciSyncObj syncObj)
	Unregisters an NvSciSyncObj with NvMedia2D. More...
NvMediaStatus	NvMedia2DSetNvSciSyncObjforEOF (NvMedia2D *const handle, NvMedia2DComposeParameters const params, NvSciSyncObj syncObj)
	Specifies the NvSciSyncObj to be used for EOF event. More...
NvMediaStatus	NvMedia2DInsertPreNvSciSyncFence (NvMedia2D *const handle, NvMedia2DComposeParameters const params, NvSciSyncFence const *const syncFence)
	Insert an NvSciSyncFence as a pre-fence. More...
NvMediaStatus	NvMedia2DGetEOFNvSciSyncFence (NvMedia2D *const handle, NvMedia2DComposeResult const *const result, NvSciSyncFence *const syncFence)
	Gets an EOF NvSciSyncFence for an NvMedia2DCompose() operation. More...
NvMediaStatus	NvMedia2DSetSrcNvSciBufObj (NvMedia2D *const handle, NvMedia2DComposeParameters const params, uint32_t const index, NvSciBufObj srcSurface)
	Sets the surface for a source layer. More...
NvMediaStatus	NvMedia2DSetDstNvSciBufObj (NvMedia2D *const handle, NvMedia2DComposeParameters const params, NvSciBufObj dstSurface)
	Sets the surface for the destination. More...

Function Documentation

NvMedia2DFillNvSciBufAttrList()

NvMediaStatus NvMedia2DFillNvSciBufAttrList	(	NvMedia2D *const	handle,
		NvSciBufAttrList const	attrList
	)

Fills the NvMedia 2D specific NvSciBuf attributes.

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

NvSciBufGeneralAttrKey_PeerHwEngineArray set to

• engName: NvSciBufHwEngName_Vic
• platName: the platform this API is used on

Parameters

[in]	handle	Not used. Can be NULL.
[out]	attrList	Pointer to an NvSciBufAttrList struct that will be populated with the NvSciBuf attributes.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Attributes filled successfully.
NVMEDIA_STATUS_BAD_PARAMETER	The attributes have already been filled, or attrList is invalid.
NVMEDIA_STATUS_INVALID_STATE	The function was called in incorrect system state.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to populate the attribute list.

Precondition

• attrList must be valid NvSciBufAttrList handle.

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

NvMedia2DFillNvSciSyncAttrList()

NvMediaStatus NvMedia2DFillNvSciSyncAttrList	(	NvMedia2D *const	handle,
		NvSciSyncAttrList const	attrList,
		NvMediaNvSciSyncClientType const	clientType
	)

Fills the NvMedia 2D specific NvSciSync attributes.

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 for the same NvSciSyncAttrList that is passed to this function.

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[out]	attrList	Pointer to an NvSciSyncAttrList struct that will be populated with the NvSciSync attributes.
[in]	clientType	An NvMediaNvSciSyncClientType, to indicate whether the attributes filled should be for a waiter or a signaler. The value should be either: NVMEDIA_WAITER NVMEDIA_SIGNALER NVMEDIA_SIGNALER_WAITER.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Attributes filled successfully.
NVMEDIA_STATUS_BAD_PARAMETER	The attributes have already been filled, or one of the parameters has an invalid value. This could be: handle is NULL attrList is invalid clientType is invalid.
NVMEDIA_STATUS_INVALID_STATE	The function was called in incorrect system state.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to populate the attribute list.

Precondition

• handle must be valid NvMedia2D handle created with NvMedia2DCreate().
• attrList must be valid NvSciSyncAttrList handle.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Each thread uses different NvMedia2D handle
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: No

NvMedia2DGetEOFNvSciSyncFence()

NvMediaStatus NvMedia2DGetEOFNvSciSyncFence	(	NvMedia2D *const	handle,
		NvMedia2DComposeResult const *const	result,
		NvSciSyncFence *const	syncFence
	)

Gets an EOF NvSciSyncFence for an NvMedia2DCompose() operation.

The expiry of an EOF NvSciSyncFence associated with an NvMedia2DCompose() operation indicates that the corresponding NvMedia2DCompose() operation has finished.

To be able to get the EOF fence using this function, the NvSciSyncObj to be used for EOF event needs to have been set for the NvMedia2DComposeParameters handle used with the NvMedia2DCompose() operation with NvMedia2DSetNvSciSyncObjforEOF().

For example, in this sequence of code:

NvMedia2DSetNvSciSyncObjforEOF(handle, params, eofSyncObj);
NvMedia2DCompose(handle, params, &result);
NvMedia2DGetEOFNvSciSyncFence(handle, &result, &syncFence);

expiry of syncFence indicates that the preceding NvMedia2DCompose() operation has finished.

For a given NvSciSyncObj used for the EOF event, the EOF fence for an NvMedia2DCompose() operation can be queried using this function only until the next operation using the same NvSciSyncObj for the EOF event is submitted. When more operations are submitted, the NvMedia2DComposeResult structs for the previous operations are no longer considered valid by this function.

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	result	Pointer to the NvMedia2DComposeResult struct.
[out]	syncFence	Pointer to an NvSciSyncFence that will be populated with the EOF fence.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	EOF fence returned successfully.
NVMEDIA_STATUS_BAD_PARAMETER	No NvSciSyncObj was set for the operation EOF event, or one of the parameters has an invalid value. This could be: handle is NULL result is NULL or invalid syncFence is NULL.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to get the fence object.

Precondition

• handle must be valid NvMedia2D handle created with NvMedia2DCreate().
• result must be valid NvMedia2DComposeResult handle returned by NvMedia2DCompose().
• The compose operation that produced result must have had an EOF sync object configured with NvMedia2DSetNvSciSyncObjforEOF().

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Each thread uses different NvMedia2D handle
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: No
  • Runtime: Yes
  • De-Init: No

See also

NvMedia2DRegisterNvSciSyncObj()

NvMedia2DSetNvSciSyncObjforEOF()

NvMedia2DInsertPreNvSciSyncFence()

NvMediaStatus NvMedia2DInsertPreNvSciSyncFence	(	NvMedia2D *const	handle,
		NvMedia2DComposeParameters const	params,
		NvSciSyncFence const *const	syncFence
	)

Insert an NvSciSyncFence as a pre-fence.

This function inserts the specified NvSciSyncFence as a pre-fence to the compose operation. The NvMedia2DCompose() operation is started only after the expiry of the syncFence.

For example, in this sequence of code:

NvMedia2DInsertPreNvSciSyncFence(handle, params, syncFence);
NvMedia2DCompose(handle, params, NULL);

the NvMedia2DCompose () operation is assured to start only after the expiry of syncFence.

You can set a maximum of 16 prefences by calling NvMedia2DInsertPreNvSciSyncFence().

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	params	An NvMedia2DComposeParameters handle.
[in]	syncFence	Pointer to an NvSciSyncFence.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Pre-fence inserted successfully.
NVMEDIA_STATUS_BAD_PARAMETER	The sync object is not registered as an PRESYNC type with NvMedia 2D, or one of the parameters has an invalid value. This could be: handle is NULL params is invalid syncFence is NULL.
NVMEDIA_STATUS_INSUFFICIENT_BUFFERING	Maximum number of registered pre-fences has been reached.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to insert the pre-fence.

Precondition

• handle must be valid NvMedia2D handle created with NvMedia2DCreate().
• params must be valid NvMedia2DComposeParameters handle created with NvMedia2DGetComposeParameters().
• syncFence must be a valid NvSciSyncFence handle.
• The sync object associated with syncFence must have been previously registered with NvMedia2DRegisterNvSciSyncObj() using a PRESYNC event type.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Each thread uses different NvMedia2D handle
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: No
  • Runtime: Yes
  • De-Init: No

See also

NvMedia2DRegisterNvSciSyncObj()

NvMedia2DRegisterNvSciBufObj()

NvMediaStatus NvMedia2DRegisterNvSciBufObj	(	NvMedia2D *const	handle,
		NvSciBufObj const	bufObj
	)

Register an NvSciBufObj with NvMedia 2D.

Every NvSciBufObj (even duplicate objects) used by NvMedia 2D must be registered by a call to this function before it is used. Only the exact same registered NvSciBufObj can be passed to NvMedia2DSetSrcNvSciBufObj() and NvMedia2DSetDstNvSciBufObj() functions.

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	bufObj	The NvSciBufObj to be registered.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Buffer registered successfully.
NVMEDIA_STATUS_BAD_PARAMETER	Returned when: handle is NULL bufObj is invalid bufObj has already been registered duplicate of bufObj was previously registered with more strict read-only permissions.
NVMEDIA_STATUS_INSUFFICIENT_BUFFERING	Maximum number of registered buffers has been reached.
NVMEDIA_STATUS_INVALID_STATE	The function was called in incorrect system state.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to register the buffer.

Precondition

• handle must be valid NvMedia2D handle created with NvMedia2DCreate().
• bufObj must be valid NvSciBufObj handle.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Each thread uses different NvMedia2D handle
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: No

See also

NvMedia2DUnregisterNvSciBufObj()

NvMedia2DRegisterNvSciSyncObj()

NvMediaStatus NvMedia2DRegisterNvSciSyncObj	(	NvMedia2D *const	handle,
		NvMediaNvSciSyncObjType const	syncObjType,
		NvSciSyncObj const	syncObj
	)

Register an NvSciSyncObj with NvMedia 2D.

Every NvSciSyncObj (even duplicate objects) used by NvMedia 2D must be registered by a call to this function before it is used.

Only the exact same registered NvSciSyncObj can be passed to NvMedia2DSetNvSciSyncObjforEOF() or NvMedia2DUnregisterNvSciSyncObj(). Also the NvSciSyncObjs associated with any NvSciSyncFences passed to NvMedia2DInsertPreNvSciSyncFence() must be registered.

For a given NvMedia2D handle, one NvSciSyncObj can be registered as one NvMediaNvSciSyncObjType only.

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	syncObjType	An NvMediaNvSciSyncClientType, to indicate what event the sync object will represent.
[in]	syncObj	The NvSciSyncObj to be registered.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Sync object registered successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value. This could be: handle is NULL syncObjType is invalid syncObj is invalid, or the sync object has been already registered.
NVMEDIA_STATUS_INSUFFICIENT_BUFFERING	Maximum number of registered sync objects has been reached.
NVMEDIA_STATUS_INVALID_STATE	The function was called in incorrect system state.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to register the sync object.

Precondition

• handle must be valid NvMedia2D handle created with NvMedia2DCreate().
• syncObj must be valid NvSciSyncObj handle.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Each thread uses different NvMedia2D handle
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: No

See also

NvMedia2DUnregisterNvSciSyncObj()

NvMedia2DAttributes.maxRegisteredSyncs

NvMedia2DSetDstNvSciBufObj()

NvMediaStatus NvMedia2DSetDstNvSciBufObj	(	NvMedia2D *const	handle,
		NvMedia2DComposeParameters const	params,
		NvSciBufObj	dstSurface
	)

Sets the surface for the destination.

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	params	An NvMedia2DComposeParameters handle.
[in]	dstSurface	The NvSciBufObj to be used for the destination surface.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Parameters set successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value. This could be: handle is NULL params is invalid, or the buffer was not registered.

Precondition

• handle must be valid NvMedia2D handle created with NvMedia2DCreate().
• params must be valid NvMedia2DComposeParameters handle created with NvMedia2DGetComposeParameters().
• dstSurface must be valid NvSciBufObj handle.
• dstSurface must have been previously registered with NvMedia2DRegisterNvSciBufObj().

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Each thread uses different NvMedia2D handle
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: No
  • Runtime: Yes
  • De-Init: No

See also

NvMedia2DComposeParameters

NvMedia2DCompose()

NvMedia2DRegisterNvSciBufObj()

NvMedia2DSetNvSciSyncObjforEOF()

NvMediaStatus NvMedia2DSetNvSciSyncObjforEOF	(	NvMedia2D *const	handle,
		NvMedia2DComposeParameters const	params,
		NvSciSyncObj	syncObj
	)

Specifies the NvSciSyncObj to be used for EOF event.

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	params	An NvMedia2DComposeParameters handle.
[in]	syncObj	The NvSciSyncObj to be used for the EOF fence.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	EOF fence set successfully.
NVMEDIA_STATUS_BAD_PARAMETER	The sync object is not registered as an EOF event type with NvMedia 2D, or one of the parameters has an invalid value. This could be: handle is NULL params is invalid syncObj is invalid.

Precondition

• handle must be valid NvMedia2D handle created with NvMedia2DCreate().
• params must be valid NvMedia2DComposeParameters handle created with NvMedia2DGetComposeParameters().
• syncObj must be valid NvSciSyncObj handle.
• syncObj must have been previously registered with NvMedia2DRegisterNvSciSyncObj() using an EOF event type.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Each thread uses different NvMedia2D handle
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: No
  • Runtime: Yes
  • De-Init: No

See also

NvMedia2DRegisterNvSciSyncObj()

NvMedia2DSetSrcNvSciBufObj()

NvMediaStatus NvMedia2DSetSrcNvSciBufObj	(	NvMedia2D *const	handle,
		NvMedia2DComposeParameters const	params,
		uint32_t const	index,
		NvSciBufObj	srcSurface
	)

Sets the surface for a source layer.

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	params	An NvMedia2DComposeParameters handle.
[in]	index	Index of source layer to configure. Must be in range [0, 15].
[in]	srcSurface	The NvSciBufObj to be used for the source surface.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Parameters set successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value. This could be: handle is NULL params is invalid index is out of range, or the buffer was not registered.

Precondition

• handle must be valid NvMedia2D handle created with NvMedia2DCreate().
• params must be valid NvMedia2DComposeParameters handle created with NvMedia2DGetComposeParameters().
• srcSurface must be valid NvSciBufObj handle.
• srcSurface must have been previously registered with NvMedia2DRegisterNvSciBufObj().

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Each thread uses different NvMedia2D handle
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: No
  • Runtime: Yes
  • De-Init: No

See also

NvMedia2DComposeParameters

NvMedia2DCompose()

NvMedia2DRegisterNvSciBufObj()

NvMedia2DUnregisterNvSciBufObj()

NvMediaStatus NvMedia2DUnregisterNvSciBufObj	(	NvMedia2D *const	handle,
		NvSciBufObj	bufObj
	)

Unregisters an NvSciBufObj with NvMedia2D.

Every NvSciBufObj registered with NvMedia2D by NvMedia2DRegisterNvSciBufObj() must be unregistered before you call NvMedia2DDestroy().

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	bufObj	The NvSciBufObj to be unregistered.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Buffer unregistered successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value. This could be: handle is NULL bufObj is invalid, or the buffer was not registered.
NVMEDIA_STATUS_INVALID_STATE	The function was called in incorrect system state.
NVMEDIA_STATUS_PENDING	The buffer is still being used by a pending operation.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to unregister the buffer.

Precondition

• handle must be valid NvMedia2D handle created with NvMedia2DCreate().
• bufObj must be valid NvSciBufObj handle.
• bufObj must have been previously registered with NvMedia2DRegisterNvSciBufObj().

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Each thread uses different NvMedia2D handle
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: Yes

See also

NvMedia2DRegisterNvSciBufObj()

NvMedia2DUnregisterNvSciSyncObj()

NvMediaStatus NvMedia2DUnregisterNvSciSyncObj	(	NvMedia2D *const	handle,
		NvSciSyncObj	syncObj
	)

Unregisters an NvSciSyncObj with NvMedia2D.

Every NvSciSyncObj registered with NvMedia2D by NvMedia2DRegisterNvSciSyncObj() must be unregistered before you call NvMedia2DDestroy().

Before the application calls this function, it must ensure that any NvMedia2DCompose() operation that uses the NvSciSyncObj has completed. If this function is called while NvSciSyncObj is still in use by any NvMedia2DCompose() operation, behavior is undefined.

Parameters

[in]	handle	Pointer to the NvMedia2D context.
[in]	syncObj	The NvSciSyncObj to be unregistered.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Sync object unregistered successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value. This could be: handle is NULL syncObj is invalid, or the sync object was not registered.
NVMEDIA_STATUS_INVALID_STATE	The function was called in incorrect system state.
NVMEDIA_STATUS_PENDING	The sync object is still being used by a pending operation.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to unregister the sync object.

Precondition

• handle must be valid NvMedia2D handle created with NvMedia2DCreate().
• syncObj must be valid NvSciSyncObj handle.
• syncObj must have been previously registered with NvMedia2DRegisterNvSciSyncObj().

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Each thread uses different NvMedia2D handle
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: Yes

See also

NvMedia2DRegisterNvSciSyncObj()