Detailed Description

6

Defines and manages objects that decode video.

The NvMediaIDE object decodes compressed video data, writing the results to a target

A specific NvMedia implementation may support decoding multiple types of compressed video data. However, NvMediaIDE objects are able to decode a specific type of compressed video data. This type must be specified during creation.

Modules
	Data types for AV1 Decoding

	Data types for H.264 Decoding

	Data types for H.265 Decoding

	Data types for MPEG-1 and MPEG-2 Decoding

	Data types for MPEG4 Part 2 Decoding

	Data types for VC1 Decoding

	Data types for VP8 Decoding

	Data types for VP9 Decoding

	Decoder Creation Flag
	Defines decoder flag bit masks for constructing the decoder.

	Image Decoder: Common Types

Macros
#define	NVMEDIA_IDE_VERSION_MAJOR 1
	Major Version number. More...

#define	NVMEDIA_IDE_VERSION_MINOR 0
	Minor Version number. More...

#define	NVMEDIA_IDE_VERSION_PATCH 0
	Patch Version number. More...

#define	NVMEDIA_IDE_MAX_PRENVSCISYNCFENCES (16U)
	Specifies the maximum number of times NvMediaIDEInsertPreNvSciSyncFence() can be called before each call to NvMediaIDEFeedFrame(). More...

Typedefs
typedef struct NvMediaIDE	NvMediaIDE
	An opaque NvMediaIDE object created by NvMediaIDECreate. More...

Functions
NvMediaStatus	NvMediaIDEGetVersion (NvMediaVersion *version)
	Retrieves the version information for the NvMediaIDE library. More...

NvMediaIDE *	NvMediaIDECreate (NvMediaVideoCodec codec, uint16_t width, uint16_t height, uint16_t maxReferences, uint64_t maxBitstreamSize, uint8_t inputBuffering, uint32_t flags, NvMediaDecoderInstanceId instanceId)
	Creates an NvMediaIDE object. More...

NvMediaIDE *	NvMediaIDECreateCtx (void)
	Create an NvMediaIDE object instance. More...

NvMediaStatus	NvMediaIDEInit (NvMediaIDE *decoder, NvMediaVideoCodec codec, uint16_t width, uint16_t height, uint16_t maxReferences, uint64_t maxBitstreamSize, uint8_t inputBuffering, uint32_t flags, NvMediaDecoderInstanceId instanceId)
	Initialize an NvMediaIDE object instance. More...

NvMediaStatus	NvMediaIDEDestroy (const NvMediaIDE *decoder)
	Destroys an NvMediaIDE object. More...

NvMediaStatus	NvMediaIDERegisterNvSciBufObj (NvMediaIDE *decoder, NvSciBufObj bufObj)
	Registers an NvSciBufObj for use with an NvMediaIde handle. More...

NvMediaStatus	NvMediaIDEUnregisterNvSciBufObj (const NvMediaIDE *decoder, NvSciBufObj bufObj)
	Un-registers NvSciBufObj which was previously registered with NvMediaIde using NvMediaIDERegisterNvSciBufObj(). More...

NvMediaStatus	NvMediaIDEDecoderRender (const NvMediaIDE decoder, NvSciBufObj target, const NvMediaPictureInfo pictureInfo, const void encryptParams, uint32_t numBitstreamBuffers, const NvMediaBitstreamBuffer bitstreams, NvMediaIDEFrameStats *FrameStatsDump, NvMediaDecoderInstanceId instanceId)
	Decodes a compressed field/frame and render the result into a target. More...

NvMediaStatus	NvMediaIDESliceDecode (const NvMediaIDE decoder, const NvSciBufObj target, const NvMediaSliceDecodeData sliceDecData)
	This function is intended for use in low-latency decode mode. More...

NvMediaStatus	NvMediaIDEGetFrameDecodeStatus (const NvMediaIDE decoder, uint32_t ringEntryIdx, NvMediaIDEFrameStatus FrameStatus)
	Retrieves the HW decode status available. More...

NvMediaStatus	NvMediaIDEFillNvSciBufAttrList (NvMediaDecoderInstanceId instanceId, NvSciBufAttrList attrlist)
	Fills the NvMediaIDE specific NvSciBuf attributes which than then be used to allocate an NvSciBufObj that NvMediaIDE can consume. More...

NvMediaStatus	NvMediaIDEFillNvSciSyncAttrList (const NvMediaIDE *decoder, NvSciSyncAttrList attrlist, NvMediaNvSciSyncClientType clienttype)
	Fills the NvMediaIDE specific NvSciSync attributes. More...

NvMediaStatus	NvMediaIDEGetBackwardUpdates (const NvMediaIDE decoder, void backupdates)
	NvMediaIDE get backward updates counters for VP9 adaptive entropy contexts. More...

NvMediaStatus	NvMediaIDERegisterNvSciSyncObj (const NvMediaIDE *decoder, NvMediaNvSciSyncObjType syncobjtype, NvSciSyncObj nvscisync)
	Registers an NvSciSyncObj with NvMediaIDE. More...

NvMediaStatus	NvMediaIDEUnregisterNvSciSyncObj (const NvMediaIDE *decoder, NvSciSyncObj nvscisync)
	Unregisters an NvSciSyncObj with NvMediaIDE. More...

NvMediaStatus	NvMediaIDESetNvSciSyncObjforEOF (const NvMediaIDE *decoder, NvSciSyncObj nvscisyncEOF)
	Specifies the NvSciSyncObj to be used for an EOF NvSciSyncFence. More...

NvMediaStatus	NvMediaIDEInsertPreNvSciSyncFence (const NvMediaIDE decoder, const NvSciSyncFence prenvscisyncfence)
	Sets an NvSciSyncFence as a prefence for an NvMediaIDERender() NvSciSyncFence operation. More...

NvMediaStatus	NvMediaIDEGetEOFNvSciSyncFence (const NvMediaIDE decoder, NvSciSyncObj eofnvscisyncobj, NvSciSyncFence eofnvscisyncfence)
	Gets EOF NvSciSyncFence for an NvMediaIDERender() operation. More...

Macro Definition Documentation

◆ NVMEDIA_IDE_MAX_PRENVSCISYNCFENCES

#define NVMEDIA_IDE_MAX_PRENVSCISYNCFENCES (16U)

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

Definition at line 62 of file nvmedia_ide.h.

◆ NVMEDIA_IDE_VERSION_MAJOR

#define NVMEDIA_IDE_VERSION_MAJOR 1

Major Version number.

Definition at line 52 of file nvmedia_ide.h.

◆ NVMEDIA_IDE_VERSION_MINOR

#define NVMEDIA_IDE_VERSION_MINOR 0

Minor Version number.

Definition at line 54 of file nvmedia_ide.h.

◆ NVMEDIA_IDE_VERSION_PATCH

#define NVMEDIA_IDE_VERSION_PATCH 0

Patch Version number.

Definition at line 56 of file nvmedia_ide.h.

Typedef Documentation

◆ NvMediaIDE

typedef struct NvMediaIDE NvMediaIDE

An opaque NvMediaIDE object created by NvMediaIDECreate.

Definition at line 70 of file nvmedia_ide.h.

Function Documentation

◆ NvMediaIDECreate()

NvMediaIDE* NvMediaIDECreate	(	NvMediaVideoCodec	codec,
		uint16_t	width,
		uint16_t	height,
		uint16_t	maxReferences,
		uint64_t	maxBitstreamSize,
		uint8_t	inputBuffering,
		uint32_t	flags,
		NvMediaDecoderInstanceId	instanceId
	)

Creates an NvMediaIDE object.

Creates a NvMediaIDE object for the specified codec. Each decoder object may be accessed by a separate thread. The object must be destroyed with NvMediaIDEDestroy().

Precondition: NvMediaIDEGetVersion()

Postcondition: NvMediaIDE 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

Parameters

[in]	codec	Codec type. The following types are supported: NVMEDIA_VIDEO_CODEC_HEVC NVMEDIA_VIDEO_CODEC_H264 NVMEDIA_VIDEO_CODEC_VC1 NVMEDIA_VIDEO_CODEC_VC1_ADVANCED NVMEDIA_VIDEO_CODEC_MPEG1 NVMEDIA_VIDEO_CODEC_MPEG2 NVMEDIA_VIDEO_CODEC_MPEG4 NVMEDIA_VIDEO_CODEC_MJPEG NVMEDIA_VIDEO_CODEC_VP8 NVMEDIA_VIDEO_CODEC_VP9 NVMEDIA_VIDEO_CODEC_AV1 [Supported only on T234 and further chips]
[in]	width	Decoder width in luminance pixels.
[in]	height	Decoder height in luminance pixels.
[in]	maxReferences	The maximum number of reference frames used. This limits internal allocations.
[in]	maxBitstreamSize	The maximum size for bitstream. This limits internal allocations.
[in]	inputBuffering	How many frames can be in flight at any given time. If this value is 1, NvMediaIDERender() blocks until the previous frame has finished decoding. If this is 2, `NvMediaIDERender` blocks if two frames are pending but does not block if one is pending. This value is clamped internally to between 1 and 8.
[in]	flags	Set the flags of the decoder. The following flags are supported: NVMEDIA_IDE_10BIT_DECODE
[in]	instanceId	The ID of the engine instance. The following instances are supported: NVMEDIA_DECODER_INSTANCE_0 NVMEDIA_DECODER_INSTANCE_1 [Supported only on T194] NVMEDIA_DECODER_INSTANCE_AUTO [Supported only on T194]

Returns: NvMediaIDE The created NvMediaIDE handle or NULL if unsuccessful.

◆ NvMediaIDECreateCtx()

NvMediaIDE* NvMediaIDECreateCtx ( void )

Create an NvMediaIDE object instance.

Precondition: NvMediaIDEGetVersion(); NvMediaIDENvSciSyncGetVersion() [for use with IMGDEC-NvSciSync APIs]

Postcondition: NvMediaIDE 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: NvMediaIDE The created NvMediaIDE handle or NULL if unsuccessful.

◆ NvMediaIDEDecoderRender()

NvMediaStatus NvMediaIDEDecoderRender	(	const NvMediaIDE *	decoder,
		NvSciBufObj	target,
		const NvMediaPictureInfo *	pictureInfo,
		const void *	encryptParams,
		uint32_t	numBitstreamBuffers,
		const NvMediaBitstreamBuffer *	bitstreams,
		NvMediaIDEFrameStats *	FrameStatsDump,
		NvMediaDecoderInstanceId	instanceId
	)

Decodes a compressed field/frame and render the result into a target.

Precondition: NvMediaIDERegisterNvSciSyncObj(); NvMediaIDESetNvSciSyncObjforEOF(); NvMediaIDEInsertPreNvSciSyncFence()

Postcondition: Decoding 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 NvMediaIDE object.
- Re-entrant: No
- Async/Sync: Async
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

Parameters

[in]	decoder	The decoder object that will perform the decode operation.
[in]	target	NvSciBufObj that contains the decoded content, allocated with a call to NvSciBufObjAlloc. characterizes the output surface into which the Decoded output is obtained Supported surface format attributes (common to all codecs): For content with bitdepth 10/12 Bit the output is MSB Aligned Non-safety build: H.264, MPEG2, MPEG4, VP8, VC1: Sub-sampling type: YUV420, (Block Linear semi-planar) Bit Depth: 8 H.265/HEVC: Sub-sampling type: YUV420, YUV444 (Block Linear semi-planar) Bit Depth: 8, 10, 12 VP9: Sub-sampling type: YUV420, (Block Linear semi-planar) Bit Depth: 8, 10, 12 AV1: [Supported only on T234 and further chips] Sub-sampling type: YUV420, (Block Linear semi-planar) Bit Depth: 8, 10
[in]	pictureInfo	A (pointer to a) structure containing information about the picture to be decoded. Note that the appropriate type of NvMediaPictureInfo* structure must be provided to match to profile that the decoder was created for.
[in]	encryptParams	A (pointer to a) structure containing information about encryption parameter used to decrypt the video content on the fly.
[in]	numBitstreamBuffers	The number of bitstream buffers containing compressed data for this picture.
[in]	bitstreams	An array of bitstream buffers.
[out]	FrameStatsDump	A (pointer to a) structure containing frame coding specific informations. This includes frame type, motion vector dumps,macroblock types and other details.
[in]	instanceId	The ID of the engine instance. The following instances are supported if NVMEDIA_DECODER_INSTANCE_AUTO was used in NvMediaIDECreate API, else this parameter is ignored: NVMEDIA_DECODER_INSTANCE_0 NVMEDIA_DECODER_INSTANCE_1 [Supported only on T194]

Returns

NvMediaStatus The completion status of the operation. Possible values are:

◆ NvMediaIDEDestroy()

NvMediaStatus NvMediaIDEDestroy ( const NvMediaIDE * decoder )

Destroys an NvMediaIDE object.

Parameters

[in] decoder The decoder to be destroyed.

Precondition: NvMediaIDEUnregisterNvSciBufObj(); NvMediaIDEUnregisterNvSciSyncObj()

Postcondition: NvMediaIDE 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 NvMediaIDE object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: No
- De-Init: Yes

Returns: void

◆ NvMediaIDEFillNvSciBufAttrList()

NvMediaStatus NvMediaIDEFillNvSciBufAttrList	(	NvMediaDecoderInstanceId	instanceId,
		NvSciBufAttrList	attrlist
	)

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

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

NvSciBufHwEngName: NvSciBufHwEngName_NVDEC
NvSciBufPlatformName: The platform this API is used on

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

Precondition: NvMediaIDEGetVersion()

Postcondition: NvSciBufAttrList populated with NvMediaIDE 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

[in]	instanceId	The ID of the engine instance. Input range: The following instances are supported: NVMEDIA_DECODER_INSTANCE_0 NVMEDIA_DECODER_INSTANCE_1 [Supported only on T194] NVMEDIA_DECODER_INSTANCE_AUTO [Supported only on T194]
[out]	attrlist	An NvSciBufAttrList where NvMediaIDE places the NvSciBuf attributes.

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

◆ NvMediaIDEFillNvSciSyncAttrList()

NvMediaStatus NvMediaIDEFillNvSciSyncAttrList	(	const NvMediaIDE *	decoder,
		NvSciSyncAttrList	attrlist,
		NvMediaNvSciSyncClientType	clienttype
	)

Fills the NvMediaIDE 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: NvMediaIDECreate()

Postcondition: NvSciSyncAttrList populated with NvMediaIDE 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 NvMediaIDE object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: No

@noteThis API is mandatory when multiple engines are pipelined in order to achieve synchronization between the engines

Parameters

[in]	decoder	A pointer to the NvMediaIDE object. Input range: 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 NvMediaIDE signaler or an NvMediaIDE 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_OUT_OF_MEMORY if there is not enough memory for the requested operation.

◆ NvMediaIDEGetBackwardUpdates()

NvMediaStatus NvMediaIDEGetBackwardUpdates	(	const NvMediaIDE *	decoder,
		void *	backupdates
	)

NvMediaIDE get backward updates counters for VP9 adaptive entropy contexts.

Precondition: NvMediaIDECreate() and only for VP9

Postcondition: Updates VP9 Entropy context.

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 NvMediaIDE object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: No

Parameters

[in]	decoder	A pointer to the decoder object that performs the decoding operation.
[in]	backupdates	A pointer to a structure that holds the backward update counters.

◆ NvMediaIDEGetEOFNvSciSyncFence()

NvMediaStatus NvMediaIDEGetEOFNvSciSyncFence	(	const NvMediaIDE *	decoder,
		NvSciSyncObj	eofnvscisyncobj,
		NvSciSyncFence *	eofnvscisyncfence
	)

Gets EOF NvSciSyncFence for an NvMediaIDERender() operation.

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

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

For example, in this sequence of code:

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

nvmstatus = NvMediaIDEGetEOFNvSciSyncFence(handle, nvscisyncEOF, eofnvscisyncfence);

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

Precondition: NvMediaIDESetNvSciSyncObjforEOF(); NvMediaIDERender()

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 NvMediaIDE object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

@noteThis API is mandatory when multiple engines are pipelined in order to achieve synchronization between the engines

Parameters

[in]	decoder	A pointer to the NvMediaIDE 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 decoder is not a valid NvMediaIDE handle, eofnvscisyncfence is NULL, or eofnvscisyncobj is not registered with decoder as type NVMEDIA_EOFSYNCOBJ or NVMEDIA_EOF_PRESYNCOBJ.
NVMEDIA_STATUS_ERROR if the function was called before NvMediaIDERender() was called.

◆ NvMediaIDEGetFrameDecodeStatus()

NvMediaStatus NvMediaIDEGetFrameDecodeStatus	(	const NvMediaIDE *	decoder,
		uint32_t	ringEntryIdx,
		NvMediaIDEFrameStatus *	FrameStatus
	)

Retrieves the HW decode status available.

This is to be used to get the decoding status. If application does not need decoding status then no need to call this function. This function should be called in decode order once decode is complete for target surface. This can be called from separate thread in decode order before the same index getting used. Syncronization can be acheived for NvMediaIDERender and NvMediaIDEGetFrameDecodeStatus using Semaphore. Semaphore can be signalled at the begining with inputBuffering times. Then client can wait on Semaphore before every NvMediaIDERender This Semaphore will be signalled from thread after calling NvMediaIDEGetFrameDecodeStatus for frame in decode order. For example: if inputBuffering is 3 when creating decoder using NvMediaIDECreate then following sequence should be followed. NvMediaIDERender(DecodeOrder:0) : ringEntryIdx=0 NvMediaIDERender(DecodeOrder:1) : ringEntryIdx=1 NvMediaIDERender(DecodeOrder:2) : ringEntryIdx=2 NvMediaIDEGetFrameDecodeStatus(0) NvMediaIDERender() : ringEntryIdx=0 NvMediaIDEGetFrameDecodeStatus(1) NvMediaIDERender() : ringEntryIdx=1 NvMediaIDEGetFrameDecodeStatus(2) NvMediaIDERender() : ringEntryIdx=2 NvMediaIDEGetFrameDecodeStatus(0) Another example could be like this for above case NvMediaIDERender(DecodeOrder:0) : ringEntryIdx=0 NvMediaIDERender(DecodeOrder:1) : ringEntryIdx=1 NvMediaIDEGetFrameDecodeStatus(0) NvMediaIDERender(DecodeOrder:2) : ringEntryIdx=2 NvMediaIDEGetFrameDecodeStatus(1) NvMediaIDERender() : ringEntryIdx=0 NvMediaIDERender() : ringEntryIdx=1 NvMediaIDEGetFrameDecodeStatus(2) NvMediaIDERender() : ringEntryIdx=2 NvMediaIDEGetFrameDecodeStatus(0)

Precondition: NvMediaIDERegisterNvSciSyncObj(); NvMediaIDESetNvSciSyncObjforEOF(); NvMediaIDEInsertPreNvSciSyncFence()

Postcondition: Decoding task status is returned.

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 NvMediaIDE object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

Parameters

[in]	decoder	The decoder object that will perform the decode operation.
[in]	ringEntryIdx	This is decoder order index. decode operation.
[out]	FrameStatus	A pointer to NvMediaIDEFrameStatus structure which will store current decoded frame status.

Returns

NvMediaStatus The completion status of the operation. Possible values are:

◆ NvMediaIDEGetVersion()

NvMediaStatus NvMediaIDEGetVersion ( NvMediaVersion * version )

Retrieves the version information for the NvMediaIDE 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: No
- De-Init: No

Parameters

[in] version A pointer to a NvMediaVersion structure of the client.

Returns

NvMediaStatus The status of the operation. Possible values are:

NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if the pointer is invalid.

◆ NvMediaIDEInit()

NvMediaStatus NvMediaIDEInit	(	NvMediaIDE *	decoder,
		NvMediaVideoCodec	codec,
		uint16_t	width,
		uint16_t	height,
		uint16_t	maxReferences,
		uint64_t	maxBitstreamSize,
		uint8_t	inputBuffering,
		uint32_t	flags,
		NvMediaDecoderInstanceId	instanceId
	)

Initialize an NvMediaIDE object instance.

Precondition: NvMediaIDECreateCtx()

Postcondition: NvMediaIDE object is initialized.

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 NvMediaIDE object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: No

Initializes a NvMediaIDE object for the specified codec. Each decoder object may be accessed by a separate thread. The object must be destroyed with NvMediaIDEDestroy().

Parameters

[in]	decoder	The decoder to use.
[in]	codec	Codec type. The following types are supported: NVMEDIA_VIDEO_CODEC_HEVC NVMEDIA_VIDEO_CODEC_H264 NVMEDIA_VIDEO_CODEC_VC1 NVMEDIA_VIDEO_CODEC_VC1_ADVANCED NVMEDIA_VIDEO_CODEC_MPEG1 NVMEDIA_VIDEO_CODEC_MPEG2 NVMEDIA_VIDEO_CODEC_MPEG4 NVMEDIA_VIDEO_CODEC_MJPEG NVMEDIA_VIDEO_CODEC_VP8 NVMEDIA_VIDEO_CODEC_VP9 NVMEDIA_VIDEO_CODEC_AV1 [Supported only on T234 and further chips]
[in]	width	Decoder width in luminance pixels.
[in]	height	Decoder height in luminance pixels.
[in]	maxReferences	The maximum number of reference frames used. This limits internal allocations.
[in]	maxBitstreamSize	The maximum size for bitstream. This limits internal allocations.
[in]	inputBuffering	How many frames can be in flight at any given time. If this value is 1, NvMediaIDERender() blocks until the previous frame has finished decoding. If this is 2, `NvMediaIDERender` blocks if two frames are pending but does not block if one is pending. This value is clamped internally to between 1 and 8.
[in]	flags	Set the flags of the decoder. The following flags are supported: NVMEDIA_IDE_10BIT_DECODE
[in]	instanceId	The ID of the engine instance. The following instances are supported: NVMEDIA_DECODER_INSTANCE_0 NVMEDIA_DECODER_INSTANCE_1 [Supported only on T194] NVMEDIA_DECODER_INSTANCE_AUTO [Supported only on T194]

Returns

NVMEDIA_STATUS_OK

NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameters are invalid.
NVMEDIA_STATUS_ERROR if it is called after initialization of decoder.

◆ NvMediaIDEInsertPreNvSciSyncFence()

NvMediaStatus NvMediaIDEInsertPreNvSciSyncFence	(	const NvMediaIDE *	decoder,
		const NvSciSyncFence *	prenvscisyncfence
	)

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

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

For example, in this sequence of code:

nvmstatus = NvMediaIDEInsertPreNvSciSyncFence(handle, prenvscisyncfence);

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

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

You can set a maximum of NVMEDIA_IDE_MAX_PRENVSCISYNCFENCES prefences by calling NvMediaIDEInsertPreNvSciSyncFence() before NvMediaIDERender(). After the call to NvMediaIDERender(), all NvSciSyncFences previously inserted by NvMediaIDEInsertPreNvSciSyncFence() are removed, and they are not reused for the subsequent NvMediaIDERender() 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 NvMediaIDE object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

@noteThis API is mandatory when multiple engines are pipelined in order to achieve synchronization between the engines

Parameters

[in]	decoder	A pointer to the NvMediaIDE 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 decoder is not a valid NvMediaIDE handle, or prenvscisyncfence is NULL, or if prenvscisyncfence was not generated with an NvSciSyncObj that was registered with decoder as either NVMEDIA_PRESYNCOBJ or NVMEDIA_EOF_PRESYNCOBJ type.
NVMEDIA_STATUS_NOT_SUPPORTED if NvMediaIDEInsertPreNvSciSyncFence() has already been called at least NVMEDIA_IDE_MAX_PRENVSCISYNCFENCES times with the same decoder handle before an NvMediaIDERender() call.

◆ NvMediaIDERegisterNvSciBufObj()

NvMediaStatus NvMediaIDERegisterNvSciBufObj	(	NvMediaIDE *	decoder,
		NvSciBufObj	bufObj
	)

Registers an NvSciBufObj for use with an NvMediaIde handle.

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

This is a optional API which needs to be called before NvMediaIDEProcessFrame()
All NvMediaIDENvSciBufRegister() API calls must be made before first NvMediaIDEProcessFrame() 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 NvMediaIDERegisterNvSciSyncObj() API.

Precondition: NvMediaIDEInit(); NvMediaIDERegisterNvSciSyncObj()

Postcondition: NvSciBufObj is registered with NvMediaIde 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 NvMediaIde object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: No

Parameters

[in]	decoder	NvMediaIde 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_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.

◆ NvMediaIDERegisterNvSciSyncObj()

NvMediaStatus NvMediaIDERegisterNvSciSyncObj	(	const NvMediaIDE *	decoder,
		NvMediaNvSciSyncObjType	syncobjtype,
		NvSciSyncObj	nvscisync
	)

Registers an NvSciSyncObj with NvMediaIDE.

Every NvSciSyncObj (even duplicate objects) used by NvMediaIDE must be registered by a call to this function before it is used. Only the exact same registered NvSciSyncObj can be passed to NvMediaIDESetNvSciSyncObjforEOF(), NvMediaIDEGetEOFNvSciSyncFence(), or NvMediaIDEUnregisterNvSciSyncObj().

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

Precondition: NvMediaIDEFillNvSciSyncAttrList()

Postcondition: NvSciSyncObj registered with NvMediaIDE

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 NvMediaIDE object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: No

@noteThis API is mandatory when multiple engines are pipelined in order to achieve synchronization between the engines

Parameters

[in]	decoder	A pointer to the NvMediaIDE object. Input range: Non-NULL - valid pointer address
[in]	syncobjtype	Determines how nvscisync is used by decoder. Input range: Entries in NvMediaNvSciSyncObjType enumeration
[in]	nvscisync	The NvSciSyncObj to be registered with decoder. 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 decoder is NULL or syncobjtype is not a valid NvMediaNvSciSyncObjType.
NVMEDIA_STATUS_NOT_SUPPORTED if nvscisync is not a compatible NvSciSyncObj which NvMediaIDE can support.
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 decoder handle for a different syncobjtype.

◆ NvMediaIDESetNvSciSyncObjforEOF()

NvMediaStatus NvMediaIDESetNvSciSyncObjforEOF	(	const NvMediaIDE *	decoder,
		NvSciSyncObj	nvscisyncEOF
	)

Specifies the NvSciSyncObj to be used for an EOF NvSciSyncFence.

To use NvMediaIDEGetEOFNvSciSyncFence(), the application must call NvMediaIDESetNvSciSyncObjforEOF() before it calls NvMediaIDERender().

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

Precondition: NvMediaIDERegisterNvSciSyncObj()

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 NvMediaIDE object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

@noteThis API is mandatory when multiple engines are pipelined in order to achieve synchronization between the engines

Parameters

[in]	decoder	A pointer to the NvMediaIDE 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 decoder is NULL, or if nvscisyncEOF is not registered with decoder as either type NVMEDIA_EOFSYNCOBJ or NVMEDIA_EOF_PRESYNCOBJ.

◆ NvMediaIDESliceDecode()

NvMediaStatus NvMediaIDESliceDecode	(	const NvMediaIDE *	decoder,
		const NvSciBufObj	target,
		const NvMediaSliceDecodeData *	sliceDecData
	)

This function is intended for use in low-latency decode mode.

It is implemented only for H265 decoder. Error will be returned if it is called for any other codec.

Each set of buffers should contain exactly 1 slice data. For first slice of every frame, NvMediaIDERender() function should be called. NvMediaIDESliceDecode() function should be called for all subsequent slices of the frame.

Note that the ucode expects next slice data to be available within certain time (= 100msec). If data is not available within this time, it is assumed that the data is lost and error-concealment may be performed on the remaining portion of the frame.

Precondition: NvMediaIDERegisterNvSciSyncObj(); NvMediaIDESetNvSciSyncObjforEOF(); NvMediaIDEInsertPreNvSciSyncFence()

Postcondition: Decoding 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 NvMediaIDE object.
- Re-entrant: No
- Async/Sync: Async
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

Parameters

[in]	decoder	The decoder object that will perform the decode operation.
[in]	target	NvSciBufObj that contains the decoded content, allocated with a call to NvSciBufObjAlloc.
[in]	sliceDecData	SliceDecode data info.

Returns

NvMediaStatus The completion status of the operation. Possible values are:

◆ NvMediaIDEUnregisterNvSciBufObj()

NvMediaStatus NvMediaIDEUnregisterNvSciBufObj	(	const NvMediaIDE *	decoder,
		NvSciBufObj	bufObj
	)

Un-registers NvSciBufObj which was previously registered with NvMediaIde using NvMediaIDERegisterNvSciBufObj().

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

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

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

Postcondition: NvSciBufObj is un-registered from NvMediaIde 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 NvMediaIde object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: No
- De-Init: Yes

Parameters

[in]	decoder	NvMediaIde 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 NvMediaIDERegisterNvSciBufObj() API.
NVMEDIA_STATUS_ERROR in following cases:
- User unregisters an NvSciBufObj which is not previously registered using NvMediaIDERegisterNvSciBufObj() API.
- User unregisters an NvSciBufObj multiple times.

◆ NvMediaIDEUnregisterNvSciSyncObj()

NvMediaStatus NvMediaIDEUnregisterNvSciSyncObj	(	const NvMediaIDE *	decoder,
		NvSciSyncObj	nvscisync
	)

Unregisters an NvSciSyncObj with NvMediaIDE.

Every NvSciSyncObj registered with NvMediaIDE by NvMediaIDERegisterNvSciSyncObj() must be unregistered before calling NvMediaIDEUnregisterNvSciBufObj() to unregister the NvSciBufObjs.

Before the application calls this function, it must ensure that any NvMediaIDERender() operation that uses the NvSciSyncObj has completed. If this function is called while NvSciSyncObj is still in use by any NvMediaIDERender() 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 NvMediaIDERender() to wait for the associated tasks to complete. The EOF NvSciSyncFence would have been previously obtained via a call to NvMediaIDEGetEOFNvSciSyncFence(). The other option would be to call NvMediaIDEGetBits() till there is no more output to retrieve.

Precondition: NvMediaIDERender(); NvMediaIDEGetBits() or NvSciSyncFenceWait() [verify that processing is complete]

Postcondition: NvSciSyncObj un-registered with NvMediaIDE

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 NvMediaIDE object.
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: No
- De-Init: Yes

@noteThis API is mandatory when multiple engines are pipelined in order to achieve synchronization between the engines

Parameters

[in]	decoder	A pointer to the NvMediaIDE object. Input range: Non-NULL - valid pointer address
[in]	nvscisync	An NvSciSyncObj to be unregistered with decoder. 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 decoder is NULL, or nvscisync is not registered with decoder.
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 NvMediaIDEUnregisterNvSciBufObj() API call, until the status returned is not NVMEDIA_STATUS_PENDING.
NVMEDIA_STATUS_ERROR if decoder was destroyed before this function was called.

NVIDIA DRIVE OS Linux SDK API Reference

6.0.9 Release

Detailed Description

Modules

Macros

Typedefs

Functions

Macro Definition Documentation

◆ NVMEDIA_IDE_MAX_PRENVSCISYNCFENCES

◆ NVMEDIA_IDE_VERSION_MAJOR

◆ NVMEDIA_IDE_VERSION_MINOR

◆ NVMEDIA_IDE_VERSION_PATCH

Typedef Documentation

◆ NvMediaIDE

Function Documentation

◆ NvMediaIDECreate()

◆ NvMediaIDECreateCtx()

◆ NvMediaIDEDecoderRender()

◆ NvMediaIDEDestroy()

◆ NvMediaIDEFillNvSciBufAttrList()

◆ NvMediaIDEFillNvSciSyncAttrList()

◆ NvMediaIDEGetBackwardUpdates()

◆ NvMediaIDEGetEOFNvSciSyncFence()

◆ NvMediaIDEGetFrameDecodeStatus()

◆ NvMediaIDEGetVersion()

◆ NvMediaIDEInit()

◆ NvMediaIDEInsertPreNvSciSyncFence()

◆ NvMediaIDERegisterNvSciBufObj()

◆ NvMediaIDERegisterNvSciSyncObj()

◆ NvMediaIDESetNvSciSyncObjforEOF()

◆ NvMediaIDESliceDecode()

◆ NvMediaIDEUnregisterNvSciBufObj()

◆ NvMediaIDEUnregisterNvSciSyncObj()