Image Encoder

Detailed Description

The NvMediaIEP object takes uncompressed image data and turns it into a codec specific bitstream. Only H.264, H.265 and VP9 encoding is supported.

Data Structures
struct	NvMediaIEPRec
	Holds the image encoder object created by NvMediaIEPCreate. More...

Macros
#define	NVMEDIA_IEP_VERSION_MAJOR   2
	Major Version number. More...
#define	NVMEDIA_IEP_VERSION_MINOR   12
	Minor Version number. More...

Typedefs
typedef struct NvMediaIEPRec	NvMediaIEP
	Holds the image encoder object created by NvMediaIEPCreate. More...

Enumerations
enum	NvMediaIEPType {   NVMEDIA_IMAGE_ENCODE_H264,   NVMEDIA_IMAGE_ENCODE_HEVC,   NVMEDIA_IMAGE_ENCODE_VP9,   NVMEDIA_IMAGE_ENCODE_VP8 }
	Image encode type. More...

Functions
NvMediaStatus	NvMediaIEPGetVersion (NvMediaVersion *version)
	Checks the version compatibility for the NvMedia IEP library. More...
NvMediaIEP *	NvMediaIEPCreate (const NvMediaDevice *device, NvMediaIEPType encodeType, const void *initParams, NvMediaSurfaceType inputFormat, uint8_t maxInputBuffering, uint8_t maxOutputBuffering, NvMediaEncoderInstanceId instanceId)
	Create an NvMediaIEP object instance. More...
void	NvMediaIEPDestroy (const NvMediaIEP *encoder)
	Destroys an NvMedia image encoder. More...
NvMediaStatus	NvMediaIEPFeedFrame (const NvMediaIEP *encoder, const NvMediaImage *frame, NvMediaRect *sourceRect, const void *picParams, NvMediaEncoderInstanceId instanceId)
	Submits the specified frame for encoding. More...
NvMediaStatus	NvMediaIEPSetConfiguration (const NvMediaIEP *encoder, const void *configuration)
	Sets the encoder configuration. More...
NvMediaStatus	NvMediaIEPGetBitsEx (const NvMediaIEP *encoder, uint32_t *numBytes, uint32_t numBitstreamBuffers, const NvMediaBitstreamBuffer *bitstreams, void *extradata)
	Returns the bitstream for a slice or frame. More...
NvMediaStatus	NvMediaIEPBitsAvailable (const NvMediaIEP *encoder, uint32_t *numBytesAvailable, NvMediaBlockingType blockingType, uint32_t millisecondTimeout)
	Returns the status of an encoding task submitted using NvMediaIEPFeedFrame, whose encoded output is to be retrieved next. More...
NvMediaStatus	NvMediaIEPGetAttribute (const NvMediaIEP *encoder, NvMediaEncAttrType attrType, uint32_t attrSize, void *AttributeData)
	Gets the encoder attribute for the current encoding session. More...
NvMediaStatus	NvMediaIEPImageRegister (const NvMediaIEP *encoder, const NvMediaImage *image, NvMediaAccessMode accessMode)
	Registers NvMediaImage for use with a NvMediaIEP handle. More...
NvMediaStatus	NvMediaIEPImageUnRegister (const NvMediaIEP *encoder, const NvMediaImage *image)
	Un-registers NvMediaImage which is registered with NvMediaIEP. More...

Macro Definition Documentation

NVMEDIA_IEP_VERSION_MAJOR

#define NVMEDIA_IEP_VERSION_MAJOR   2

Major Version number.

Definition at line 38 of file nvmedia_iep.h.

NVMEDIA_IEP_VERSION_MINOR

#define NVMEDIA_IEP_VERSION_MINOR   12

Minor Version number.

Definition at line 40 of file nvmedia_iep.h.

Typedef Documentation

NvMediaIEP

typedef struct NvMediaIEPRec NvMediaIEP

Holds the image encoder object created by NvMediaIEPCreate.

Enumeration Type Documentation

NvMediaIEPType

enum NvMediaIEPType

Image encode type.

Enumerator
NVMEDIA_IMAGE_ENCODE_H264	H.264 encode.
NVMEDIA_IMAGE_ENCODE_HEVC	HEVC codec.
NVMEDIA_IMAGE_ENCODE_VP9	VP9 codec.
NVMEDIA_IMAGE_ENCODE_VP8	VP8 codec.

Definition at line 45 of file nvmedia_iep.h.

Function Documentation

NvMediaIEPBitsAvailable()

NvMediaStatus NvMediaIEPBitsAvailable	(	const NvMediaIEP *	encoder,
		uint32_t *	numBytesAvailable,
		NvMediaBlockingType	blockingType,
		uint32_t	millisecondTimeout
	)

Returns the status of an encoding task submitted using NvMediaIEPFeedFrame, whose encoded output is to be retrieved next.

The number of bytes of encoded output that is available (if ready), is also retrieved along with the status. The specific behavior depends on the specified NvMediaBlockingType.

It is safe to call this function from a separate thread.

Precondition

NvMediaIEPFeedFrame()

Postcondition

Status of the submitted encoding task is retrieved.

Considerations for Safety:

• Operation Mode: Runtime

Parameters

[in]	encoder	The encoder to use.
[out]	numBytesAvailable	The number of bytes of encoded output that is available. This output corresponds to the next encoding task in the queue for which the output is yet to be retrieved. The value is valid only when the return value from this API is NVMEDIA_STATUS_OK.
[in]	blockingType	Blocking type. The following are supported blocking types: NVMEDIA_ENCODE_BLOCKING_TYPE_NEVER This type never blocks so millisecondTimeout is ignored. The following are possible return values: NVMEDIA_STATUS_OK NVMEDIA_STATUS_PENDING or NVMEDIA_STATUS_NONE_PENDING. NVMEDIA_ENCODE_BLOCKING_TYPE_IF_PENDING Blocks if an encoding task is pending, until it completes or till it times out. If no encoding task is pending, doesn't block and returns NVMEDIA_STATUS_NONE_PENDING. Possible return values: NVMEDIA_STATUS_OK, NVMEDIA_STATUS_NONE_PENDING, NVMEDIA_STATUS_TIMED_OUT.
[in]	millisecondTimeout	Timeout in milliseconds or NVMEDIA_VIDEO_ENCODER_TIMEOUT_INFINITE if a timeout is not desired.

Returns

NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameters are invalid.
NVMEDIA_STATUS_PENDING if an encode is in progress but not yet completed.
NVMEDIA_STATUS_NONE_PENDING if no encode is in progress.
NVMEDIA_STATUS_TIMED_OUT if the operation timed out.
NVMEDIA_STATUS_ERROR if there was an error during image encoding.

NvMediaIEPCreate()

NvMediaIEP* NvMediaIEPCreate	(	const NvMediaDevice *	device,
		NvMediaIEPType	encodeType,
		const void *	initParams,
		NvMediaSurfaceType	inputFormat,
		uint8_t	maxInputBuffering,
		uint8_t	maxOutputBuffering,
		NvMediaEncoderInstanceId	instanceId
	)

Create an NvMediaIEP object instance.

Precondition

NvMediaIEPGetVersion()

NvMediaIEPNvSciSyncGetVersion() [for use with IEP-NvSciSync APIs]

Postcondition

NvMediaIEP object is created

Considerations for Safety:

• Operation Mode: Init

Creates an encoder object capable of turning a stream of surfaces of the "inputFormat" into a bitstream of the specified "codec". Surfaces are feed to the encoder with NvMediaIEPFeedFrame and bitstream buffers are retrieved with NvMediaIEPGetBitsEx.

Parameters

[in]	device	The device this image encoder will use.
[in]	encodeType	The encode type, which can be: NVMEDIA_IMAGE_ENCODE_H264 NVMEDIA_IMAGE_ENCODE_HEVC NVMEDIA_IMAGE_ENCODE_VP9
[in]	initParams	The encode parameters, which can be: Supported encode parameter structures: NvMediaEncodeInitializeParamsH264 NvMediaEncodeInitializeParamsH265 NvMediaEncodeInitializeParamsVP9
[in]	inputFormat	Must be obtained by /ref NvMediaSurfaceFormatGetType with: NVM_SURF_FMT_SET_ATTR_YUV(attr, YUV, 420, SEMI_PLANAR, UINT, [8/10], BL) NVM_SURF_FMT_SET_ATTR_YUV(attr, YUV, 444, SEMI_PLANAR, UINT, [8/10], BL)
[in]	maxInputBuffering	Maximum number of frames in the encode pipeline at any time. This parameter is no longer in use and kept here to maintain backward compatibility.
[in]	maxOutputBuffering	Maximum number of frames of encoded bitstream that can be held by the NvMediaIEP before it must be retrieved using NvMediaIEPGetBitsEx. This number must be less than or equal to 16. If maxOutputBuffering frames worth of encoded bitstream is yet to be retrived, NvMediaIEPFeedFrame returns NVMEDIA_STATUS_INSUFFICIENT_BUFFERING. In this case, encoded output of one or more frames must be retrived with NvMediaIEPGetBitsEx before feeding more frames using NvMediaIEPFeedFrame
[in]	instanceId	The ID of the encoder engine instance. The following instances are supported: NVMEDIA_ENCODER_INSTANCE_0 NVMEDIA_ENCODER_INSTANCE_1 [Unsupported in safety build] NVMEDIA_ENCODER_INSTANCE_AUTO [Unsupported in safety build]

Returns

NvMediaIEP The new image encoder's handle or NULL if unsuccessful.

NvMediaIEPDestroy()

void NvMediaIEPDestroy

(

const NvMediaIEP *

encoder

)

Destroys an NvMedia image encoder.

Precondition

NvMediaIEPImageUnRegister()

NvMediaIEPUnregisterNvSciSyncObj() [for use with IEP-NvSciSync APIs]

Postcondition

NvMediaIEP object is destroyed

Considerations for Safety:

• Operation Mode: De-init

Parameters

[in]

encoder

The encoder to destroy.

NvMediaIEPFeedFrame()

NvMediaStatus NvMediaIEPFeedFrame	(	const NvMediaIEP *	encoder,
		const NvMediaImage *	frame,
		NvMediaRect *	sourceRect,
		const void *	picParams,
		NvMediaEncoderInstanceId	instanceId
	)

Submits the specified frame for encoding.

The encoding process is asynchronous, as a result, the encoded output may not be available when the API returns. Refer NvMediaIEPBitsAvailable and NvMediaIEPGetBitsEx for more details regarding how to retrieve the encoded output.

Precondition

NvMediaIEPImageRegister()

NvMediaIEPSetConfiguration() must be called at least once to configure NvMediaIEP

NvMediaIEPSetNvSciSyncObjforEOF() [optional - for use with IEP- NvSciSync APIs]

NvMediaIEPInsertPreNvSciSyncFence() [optional - for use with IEP- NvSciSync APIs]

Postcondition

Image encoding task is submitted

Considerations for Safety:

• Operation Mode: Runtime

Parameters

[in]	encoder	The encoder to use.
[in]	frame	The frame, which must be of the same sourceType as in the NvMediaIEP. The size of this surface should be similar to the configured encoding size passed in initialization parameter of NvMediaIEPCreate.
[in]	sourceRect	This parameter is not used anymore and kept here to maintain backward compatibility.
[in]	picParams	Picture parameters used for the frame. Supported picture parameter structures: NvMediaEncodePicParamsH264 NvMediaEncodePicParamsH265 NvMediaEncodePicParamsVP9
[in]	instanceId	The specific ID of the encoder engine instance. Note: NVMEDIA_ENCODER_INSTANCE_AUTO should not be passed to NvMediaIEPFeedFrame If NVMEDIA_ENCODER_INSTANCE_AUTO was not passed to NvMediaIEPCreate API, then the same instanceId passed to NvMediaIEPCreate API needs to be passed here as well. If NVMEDIA_ENCODER_INSTANCE_AUTO was passed to NvMediaIEPCreate API (non-safety build), then the following values of instanceId are supported for NvMediaIEPFeedFrame API: NVMEDIA_ENCODER_INSTANCE_0 NVMEDIA_ENCODER_INSTANCE_1

Returns

NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameters are invalid.
NVMEDIA_STATUS_INSUFFICIENT_BUFFERING if the rate at which the input frames are being fed to NvMediaIEP using NvMediaIEPFeedFrame is much greater than the rate at which the encoded output is being retrieved using NvMediaIEPGetBitsEx. This case typically happens when NvMediaIEPGetBitsEx has not been called frequently enough and the internal queue containing encoded/encoding frames awaiting to be retrieved is full. The maxOutputBuffering argument passed to NvMediaIEPCreate specifies the maximum number of calls that can be made to NvMediaIEPFeedFrame after which at least one or more calls to NvMediaIEPGetBitsEx has to be made.
NVMEDIA_STATUS_ERROR if there is a run-time error encountered during encoding

NvMediaIEPGetAttribute()

NvMediaStatus NvMediaIEPGetAttribute	(	const NvMediaIEP *	encoder,
		NvMediaEncAttrType	attrType,
		uint32_t	attrSize,
		void *	AttributeData
	)

Gets the encoder attribute for the current encoding session.

This function can be called after passing the first frame for encoding. It can be used to get header information (SPS/PPS/VPS) for the current encoding session. Additionally, it can be extended for further requirements, by implementing proper data structures.

Before calling this function, you must pass the first frame for encoding.

Precondition

NvMediaIEPFeedFrame() called at least once

Postcondition

Value of the required attribute is retrieved.

Considerations for Safety:

• Operation Mode: Runtime

Parameters

[in]	encoder	A pointer to the encoder to use.
[in]	attrType	Attribute type as defined in NvMediaEncAttrType.
[in]	attrSize	Size of the data structure associated with attribute.
[out]	AttributeData	A pointer to data structure associated with the attribute.

Returns

NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameters are invalid.

NvMediaIEPGetBitsEx()

NvMediaStatus NvMediaIEPGetBitsEx	(	const NvMediaIEP *	encoder,
		uint32_t *	numBytes,
		uint32_t	numBitstreamBuffers,
		const NvMediaBitstreamBuffer *	bitstreams,
		void *	extradata
	)

Returns the bitstream for a slice or frame.

It is safe to call this function from a separate thread.

The return value and behavior of NvMediaIEPGetBitsEx is the same as that of NvMediaIEPBitsAvailable when called with NVMEDIA_ENCODE_BLOCKING_TYPE_NEVER, except that when NVMEDIA_STATUS_OK is returned, bitstreams is filled in addition to numBytes.

Precondition

NvMediaIEPFeedFrame()

Postcondition

Encoded bitstream corresponding to the submitted task is retrieved.

Considerations for Safety:

• Operation Mode: Runtime

Parameters

[in]	encoder	A pointer to the encoder to use.
[out]	numBytes	Size of the filled bitstream.
[in]	numBitstreamBuffers	The length of the bitstreams array Range: 1 to 64 in steps of 1
[in,out]	bitstreams	A pointer to an array of type NvMediaBitstreamBuffer, the length of the array being passed in numBitstreamBuffers. Encoded bitstream data will be filled in the entries of the array, starting from index 0 to (numBitstreamBuffers - 1), as and when each entry in the array gets filled up. The minimum combined bitstream size needs to be at least equal to the numBytesAvailable returned by NvMediaIEPBitsAvailable call. Members of each NvMediaBitstreamBuffer are to be set as follows: NvMediaBitstreamBuffer::bitstream is assigned a pointer to an array of type uint8_t, where the encoded bitstream output will be written to by NvMediaIEP NvMediaBitstreamBuffer::bitstreamSize is assigned with the size of the NvMediaBitstreamBuffer::bitstream array NvMediaBitstreamBuffer::bitstreamBytes will be populated by NvMediaIEP to indicate the number of encoded bitstream bytes that are populated in NvMediaBitstreamBuffer::bitstream once the function call returns
[in,out]	extradata	This is an internal feature. This parameter can no longer be used in external applications and is retained only for backward compatibility. This should be set to NULL.

Returns

NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameters are invalid.
NVMEDIA_STATUS_PENDING if an encode is in progress but not yet completed.
NVMEDIA_STATUS_NONE_PENDING if no encode is in progress.
NVMEDIA_STATUS_INSUFFICIENT_BUFFERING if the size of the provided bitstream buffers are insufficient to hold the available output.
NVMEDIA_STATUS_ERROR if there was an error during image encoding.

NvMediaIEPGetVersion()

NvMediaStatus NvMediaIEPGetVersion

(

NvMediaVersion *

version

)

Checks the version compatibility for the NvMedia IEP library.

Precondition

None

Postcondition

None

Considerations for Safety:

• Operation Mode: Init

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 NULL.

NvMediaIEPImageRegister()

NvMediaStatus NvMediaIEPImageRegister	(	const NvMediaIEP *	encoder,
		const NvMediaImage *	image,
		NvMediaAccessMode	accessMode
	)

Registers NvMediaImage for use with a NvMediaIEP handle.

NvMediaIEP handle maintains a record of all the images registered using this API.

This is a mandatory API on QNX safety build to ensure deterministic execution time of NvMediaIEPFeedFrame. Although optional on other platform configurations, it is highly recommended to use this API.

To ensure deterministic execution time of NvMediaIEPFeedFrame API:

• NvMediaIEPImageRegister must be called for every input NvMediaImage that will be used with NvMediaIEP
• All NvMediaIEPImageRegister calls must be made before first NvMediaIEPFeedFrame API call.

Maximum of 32 NvMediaImage handles can be registered per access mode.

Precondition

NvMediaIEPCreate()

Postcondition

NvMediaImage is registered with NvMediaIEP object

Considerations for Safety:

• Operation Mode: Init

Parameters

[in]	encoder	: NvMedia IEP device handle.
[in]	image	: A pointer to NvMedia image
[in]	accessMode	: NvMediaAccessMode required for the image

Returns

NvMediaStatus, the completion status of operation:

• NVMEDIA_STATUS_OK if successful.
• NVMEDIA_STATUS_BAD_PARAMETER if encoder, image or accessMode is invalid
• NVMEDIA_STATUS_ERROR in following cases
  • user registers more than 32 images.
  • user registers same image with more than one accessModes.
  • user registers same image multiple times
• NVMEDIA_STATUS_NOT_SUPPORTED if API is not functional

NvMediaIEPImageUnRegister()

NvMediaStatus NvMediaIEPImageUnRegister	(	const NvMediaIEP *	encoder,
		const NvMediaImage *	image
	)

Un-registers NvMediaImage which is registered with NvMediaIEP.

For all NvMediaImage handles registered with NvMediaIEP using NvMediaIEPImageRegister API, NvMediaIEPImageUnRegister must be called before calling NvMediaIEPDestroy API. For unregistration to succeed, it should be ensured that none of the submitted tasks on the image are pending prior to calling NvMediaIEPImageUnRegister API. In order to ensure this, NvMediaIEPGetBitsEx API needs to be called prior to unregistration, untill the output of all the submitted tasks are available.

This is a mandatory API on QNX safety build to ensure deterministic execution time of NvMediaIEPFeedFrame. Although optional on other platform configurations, it is highly recommended to use this API.

To ensure deterministic execution time of NvMediaIEPFeedFrame API:

• NvMediaIEPImageUnRegister should be called only after the last NvMediaIEPFeedFrame call

Precondition

NvMediaIEPFeedFrame()

NvMediaIEPGetBitsEx() [verify that processing is complete]

Postcondition

NvMediaImage is un-registered from NvMediaIEP object

Considerations for Safety:

• Operation Mode: De-init

Parameters

[in]	encoder	: NvMedia IEP device handle.
[in]	image	: A pointer to NvMedia image

Returns

NvMediaStatus, the completion status of operation:

• NVMEDIA_STATUS_OK if successful.
• NVMEDIA_STATUS_BAD_PARAMETER if encoder is invalid or unregister is called for image which is not registered using NvMediaIEPImageRegister API
• NVMEDIA_STATUS_PENDING if the enqueued operations on the NvMediaImage are still pending. In this case, the application can choose to wait for all the operations to complete through calls to NvMediaIEPGetBitsEx API, or re-try the NvMediaIEPImageUnRegister API call, untill the status returned is not NVMEDIA_STATUS_PENDING
• NVMEDIA_STATUS_NOT_SUPPORTED if API is not functional

NvMediaIEPSetConfiguration()

NvMediaStatus NvMediaIEPSetConfiguration	(	const NvMediaIEP *	encoder,
		const void *	configuration
	)

Sets the encoder configuration.

The values in the configuration take effect only at the start of the next GOP.

Precondition

NvMediaIEPCreate()

Postcondition

NvMediaIEP object is configured

Considerations for Safety:

• Operation Mode: Runtime

Parameters

[in]	encoder	A pointer to the encoder to use.
[in]	configuration	Configuration data. Supported configuration structures: NvMediaEncodeConfigH264 NvMediaEncodeConfigH265 NvMediaEncodeConfigVP9

Returns

NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameters are invalid.