Video Encoder

Detailed Description

The NvMediaVideoEncoder object takes uncompressed video data and tuns it into a codec specific bitstream. Currently only H.264 encoding is supported.

Data Structures
struct	NvMediaVideoEncoder
	Video encoder object created by NvMediaVideoEncoderCreate. More...

Macros
#define	NVMEDIA_VEP_VERSION_MAJOR   2
	Major Version number. More...
#define	NVMEDIA_VEP_VERSION_MINOR   8
	Minor Version number. More...

Enumerations
enum	NvMediaVideoEncodeType {   NVMEDIA_VIDEO_ENCODE_CODEC_H264,   NVMEDIA_VIDEO_ENCODE_CODEC_HEVC,   NVMEDIA_VIDEO_ENCODE_CODEC_VP9,   NVMEDIA_VIDEO_ENCODE_CODEC_VP8 }
	Video encoder codec type. More...
enum	NvMediaEncodeParamsRCMode {   NVMEDIA_ENCODE_PARAMS_RC_CBR = 0,   NVMEDIA_ENCODE_PARAMS_RC_CONSTQP = 1,   NVMEDIA_ENCODE_PARAMS_RC_VBR = 2,   NVMEDIA_ENCODE_PARAMS_RC_VBR_MINQP = 3,   NVMEDIA_ENCODE_PARAMS_RC_CBR_MINQP = 4 }
	Rate Control Modes. More...
enum	NvMediaBlockingType {   NVMEDIA_ENCODE_BLOCKING_TYPE_NEVER,   NVMEDIA_ENCODE_BLOCKING_TYPE_IF_PENDING }
	Blocking type. More...

Functions
NvMediaStatus	NvMediaVideoEncoderGetVersion (NvMediaVersion *version)
	Gets the version information for the NvMedia Video Encoder library. More...
NvMediaVideoEncoder *	NvMediaVideoEncoderCreate (const NvMediaDevice *device, NvMediaVideoEncodeType codec, const void *initParams, NvMediaSurfaceType inputFormat, uint8_t maxInputBuffering, uint8_t maxOutputBuffering, NvMediaEncoderInstanceId instanceId)
	Create an NvMediaVideoEncoder object instance. More...
void	NvMediaVideoEncoderDestroy (const NvMediaVideoEncoder *encoder)
	Destroys an NvMediaVideoEncoder object. More...
NvMediaStatus	NvMediaVideoEncoderFeedFrame (const NvMediaVideoEncoder *encoder, const NvMediaVideoSurface *frame, const NvMediaRect *sourceRect, const void *picParams, NvMediaEncoderInstanceId instanceId)
	Submits the specified frame for encoding. More...
NvMediaStatus	NvMediaVideoEncoderSetConfiguration (const NvMediaVideoEncoder *encoder, const void *configuration)
	Sets the encoder configuration. More...
NvMediaStatus	NvMediaVideoEncoderGetBits (const NvMediaVideoEncoder *encoder, uint32_t *numBytes, void *buffer)
	Returns the bitstream for a frame. More...
NvMediaStatus	NvMediaVideoEncoderBitsAvailable (const NvMediaVideoEncoder *encoder, uint32_t *numBytesAvailable, NvMediaBlockingType blockingType, uint32_t millisecondTimeout)
	Returns the status of an encoding task submitted using NvMediaVideoEncoderFeedFrame, whose encoded output is to be retrieved next. More...
NvMediaStatus	NvMediaVideoEncoderSurfaceRegister (const NvMediaVideoEncoder *encoder, const NvMediaVideoSurface *frame, NvMediaAccessMode accessMode)
	Registers NvMediaVideoSurface for use with a NvMediaVideoEncoder handle. More...
NvMediaStatus	NvMediaVideoEncoderSurfaceUnRegister (const NvMediaVideoEncoder *encoder, const NvMediaVideoSurface *frame)
	Un-registers NvMediaVideoSurface which is registered with NvMediaVideoEncoder. More...

Macro Definition Documentation

NVMEDIA_VEP_VERSION_MAJOR

#define NVMEDIA_VEP_VERSION_MAJOR   2

Major Version number.

Definition at line 37 of file nvmedia_vep.h.

NVMEDIA_VEP_VERSION_MINOR

#define NVMEDIA_VEP_VERSION_MINOR   8

Minor Version number.

Definition at line 39 of file nvmedia_vep.h.

Enumeration Type Documentation

NvMediaBlockingType

enum NvMediaBlockingType

Blocking type.

Enumerator
NVMEDIA_ENCODE_BLOCKING_TYPE_NEVER	Never blocks.
NVMEDIA_ENCODE_BLOCKING_TYPE_IF_PENDING	Block only when operation is pending.

Definition at line 168 of file nvmedia_common_encode.h.

NvMediaEncodeParamsRCMode

enum NvMediaEncodeParamsRCMode

Rate Control Modes.

Enumerator
NVMEDIA_ENCODE_PARAMS_RC_CBR	Constant bitrate mode.
NVMEDIA_ENCODE_PARAMS_RC_CONSTQP	Constant QP mode.
NVMEDIA_ENCODE_PARAMS_RC_VBR	Variable bitrate mode.
NVMEDIA_ENCODE_PARAMS_RC_VBR_MINQP	Variable bitrate mode with MinQP. Not supported on QNX Safety build
NVMEDIA_ENCODE_PARAMS_RC_CBR_MINQP	Constant bitrate mode with MinQP. Not supported on QNX Safety build

Definition at line 75 of file nvmedia_common_encode.h.

NvMediaVideoEncodeType

enum NvMediaVideoEncodeType

Video encoder codec type.

Enumerator
NVMEDIA_VIDEO_ENCODE_CODEC_H264	H.264 codec.
NVMEDIA_VIDEO_ENCODE_CODEC_HEVC	HEVC codec.
NVMEDIA_VIDEO_ENCODE_CODEC_VP9	VP9 codec.
NVMEDIA_VIDEO_ENCODE_CODEC_VP8	VP8 codec.

Definition at line 45 of file nvmedia_vep.h.

Function Documentation

NvMediaVideoEncoderBitsAvailable()

NvMediaStatus NvMediaVideoEncoderBitsAvailable	(	const NvMediaVideoEncoder *	encoder,
		uint32_t *	numBytesAvailable,
		NvMediaBlockingType	blockingType,
		uint32_t	millisecondTimeout
	)

Returns the status of an encoding task submitted using NvMediaVideoEncoderFeedFrame, 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.

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

NvMediaVideoEncoderCreate()

NvMediaVideoEncoder* NvMediaVideoEncoderCreate	(	const NvMediaDevice *	device,
		NvMediaVideoEncodeType	codec,
		const void *	initParams,
		NvMediaSurfaceType	inputFormat,
		uint8_t	maxInputBuffering,
		uint8_t	maxOutputBuffering,
		NvMediaEncoderInstanceId	instanceId
	)

Create an NvMediaVideoEncoder object instance.

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 NvMediaVideoEncoderFeedFrame and bitstream buffers are retrieved with NvMediaVideoEncoderGetBits.

Parameters

[in]	device	The device this video encoder will use.
[in]	codec	The codec to be used, which can be: NVMEDIA_VIDEO_ENCODE_CODEC_H264 NVMEDIA_VIDEO_ENCODE_CODEC_HEVC NVMEDIA_VIDEO_ENCODE_CODEC_VP9
[in]	initParams	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 NvMediaVideoEncoder before it must be retrieved using NvMediaVideoEncoderGetBits. This number must be less than or equal to 16. If maxOutputBuffering frames worth of encoded bitstream is yet to be retrived, NvMediaVideoEncoderFeedFrame returns NVMEDIA_STATUS_INSUFFICIENT_BUFFERING. In this case, encoded output of one or more frames must be retrived with NvMediaVideoEncoderGetBits before feeding more frames using NvMediaVideoEncoderFeedFrame
[in]	instanceId	The ID of the encoder engine instance. The following instances are supported: NVMEDIA_ENCODER_INSTANCE_0 NVMEDIA_ENCODER_INSTANCE_1 NVMEDIA_ENCODER_INSTANCE_AUTO

Returns

NvMediaVideoEncoder The new video encoder's handle or NULL if unsuccessful.

NvMediaVideoEncoderDestroy()

void NvMediaVideoEncoderDestroy

(

const NvMediaVideoEncoder *

encoder

)

Destroys an NvMediaVideoEncoder object.

Parameters

[in]

encoder

A pointer to the encoder to destroy.

NvMediaVideoEncoderFeedFrame()

NvMediaStatus NvMediaVideoEncoderFeedFrame	(	const NvMediaVideoEncoder *	encoder,
		const NvMediaVideoSurface *	frame,
		const 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 NvMediaVideoEncoderBitsAvailable and NvMediaVideoEncoderGetBits for more details regarding how to retrieve the encoded output.

Parameters

[in]	encoder	The encoder to use.
[in]	frame	The frame, which must be of the same sourceType as in the NvMediaVideoEncoder. The size of this surface should be similar to the configured encoding size passed in initialization parameter of NvMediaVideoEncoderCreate.
[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 NvMediaVideoEncoderFeedFrame If NVMEDIA_ENCODER_INSTANCE_AUTO was not passed to NvMediaVideoEncoderCreate API, then the same instanceId passed to NvMediaVideoEncoderCreate API needs to be passed here as well. If NVMEDIA_ENCODER_INSTANCE_AUTO was passed to NvMediaVideoEncoderCreate API, then the following values of instanceId are supported for NvMediaVideoEncoderFeedFrame 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 NvMediaVideoEncoder using NvMediaVideoEncoderFeedFrame is much greater than the rate at which the encoded output is being retrieved using NvMediaVideoEncoderGetBits. This case typically happens when NvMediaVideoEncoderGetBits 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 NvMediaVideoEncoderCreate specifies the maximum number of calls that can be made to NvMediaVideoEncoderFeedFrame after which at least one or more calls to NvMediaVideoEncoderGetBits has to be made.
NVMEDIA_STATUS_ERROR if there is a run-time error encountered during encoding

NvMediaVideoEncoderGetBits()

NvMediaStatus NvMediaVideoEncoderGetBits	(	const NvMediaVideoEncoder *	encoder,
		uint32_t *	numBytes,
		void *	buffer
	)

Returns the bitstream for a frame.

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

Copies a frame's worth of bitstream into the provided buffer. numBytes returns the size of this bitstream.

The return value and behavior is the same as that of NvMediaVideoEncoderBitsAvailable when called with NVMEDIA_ENCODE_BLOCKING_TYPE_NEVER except that when NVMEDIA_STATUS_OK is returned, the "buffer" will be filled in addition to the numBytes.

Parameters

[in]	encoder	A pointer to the encoder to use.
[out]	numBytes	Size of the filled bitstream.
[in]	buffer	The buffer to be filled with the encoded data. Minimum Size: Size returned by NvMediaVideoEncoderBitsAvailable Maximum Size: 16*1024*1024 bytes

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

NvMediaVideoEncoderGetVersion()

NvMediaStatus NvMediaVideoEncoderGetVersion

(

NvMediaVersion *

version

)

Gets the version information for the NvMedia Video Encoder library.

Parameters

[in]

version

A pointer to a NvMediaVersion structure to be filled by the function.

Returns

NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if the pointer is NULL.

NvMediaVideoEncoderSetConfiguration()

NvMediaStatus NvMediaVideoEncoderSetConfiguration	(	const NvMediaVideoEncoder *	encoder,
		const void *	configuration
	)

Sets the encoder configuration.

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

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.

NvMediaVideoEncoderSurfaceRegister()

NvMediaStatus NvMediaVideoEncoderSurfaceRegister	(	const NvMediaVideoEncoder *	encoder,
		const NvMediaVideoSurface *	frame,
		NvMediaAccessMode	accessMode
	)

Registers NvMediaVideoSurface for use with a NvMediaVideoEncoder handle.

NvMediaVideoEncoder handle maintains a record of all the surfaces registered using this API.

This API needs to be called in order to ensure deterministic execution time of NvMediaIEPFeedFrame on QNX platform. Although optional on other platform configurations, it is highly recommended to use this API.

To ensure deterministic execution time of NvMediaIEPFeedFrame API:

• NvMediaVideoEncoderSurfaceRegister must be called for every input NvMediaVideoSurface that will be used with NvMediaVideoEncoder
• All NvMediaVideoEncoderSurfaceRegister calls must be made before first NvMediaVideoEncoderFeedFrame API call.

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

Parameters

[in]	encoder	- A pointer to the encoder to use.
[in]	frame	- A pointer to NvMediaVideoSurface
[in]	accessMode	: NvMediaAccessMode required for the surface

Returns

NvMediaStatus, the completion status of operation:

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

NvMediaVideoEncoderSurfaceUnRegister()

NvMediaStatus NvMediaVideoEncoderSurfaceUnRegister	(	const NvMediaVideoEncoder *	encoder,
		const NvMediaVideoSurface *	frame
	)

Un-registers NvMediaVideoSurface which is registered with NvMediaVideoEncoder.

For all NvMediaVideoSurface handles registered with NvMediaVideoEncoder using NvMediaVideoEncoderSurfaceRegister API, NvMediaVideoEncoderSurfaceUnRegister must be called before calling NvMediaVideoEncoderDestroy API. For unregistration to succeed, it should be ensured that none of the submitted tasks on the surfaces are pending prior to calling NvMediaVideoEncoderSurfaceUnRegister API. In order to ensure this, NvMediaVideoEncoderGetBits API needs to be called prior to unregistration, untill the output of all the submitted tasks are available.

This API needs to be called in order to ensure deterministic execution time of NvMediaIEPFeedFrame on QNX platform. Although optional on other platform configurations, it is highly recommended to use this API.

To ensure deterministic execution time of NvMediaIEPFeedFrame API:

• NvMediaVideoEncoderSurfaceUnRegister must be called only after last NvMediaVideoEncoderFeedFrame call.

Parameters

[in]	encoder	- A pointer to the encoder to use.
[in]	frame	- A pointer to NvMediaVideoSurface

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 surface which is not registered using NvMediaVideoEncoderSurfaceRegister API
• NVMEDIA_STATUS_PENDING if the enqueued operations on the NvMediaVideoSurface are still pending. In this case, the application can choose to wait for all the operations to complete through calls to NvMediaVideoEncoderGetBits API, or re-try the NvMediaVideoEncoderSurfaceUnRegister API call, untill the status returned is not NVMEDIA_STATUS_PENDING
• NVMEDIA_STATUS_NOT_SUPPORTED if API is not functional