Functions
NVENCSTATUS NVENCAPI	NvEncOpenEncodeSession (void device, uint32_t deviceType, void *encoder)
	Opens an encoding session. More...

NVENCSTATUS NVENCAPI	NvEncGetEncodeGUIDCount (void encoder, uint32_t encodeGUIDCount)
	Retrieves the number of supported encode GUIDs. More...

NVENCSTATUS NVENCAPI	NvEncGetEncodeGUIDs (void encoder, GUID GUIDs, uint32_t guidArraySize, uint32_t *GUIDCount)
	Retrieves an array of supported encoder codec GUIDs. More...

NVENCSTATUS NVENCAPI	NvEncGetEncodeProfileGUIDCount (void encoder, GUID encodeGUID, uint32_t encodeProfileGUIDCount)
	Retrieves the number of supported profile GUIDs. More...

NVENCSTATUS NVENCAPI	NvEncGetEncodeProfileGUIDs (void encoder, GUID encodeGUID, GUID profileGUIDs, uint32_t guidArraySize, uint32_t *GUIDCount)
	Retrieves an array of supported encode profile GUIDs. More...

NVENCSTATUS NVENCAPI	NvEncGetInputFormatCount (void encoder, GUID encodeGUID, uint32_t inputFmtCount)
	Retrieve the number of supported Input formats. More...

NVENCSTATUS NVENCAPI	NvEncGetInputFormats (void encoder, GUID encodeGUID, NV_ENC_BUFFER_FORMAT inputFmts, uint32_t inputFmtArraySize, uint32_t *inputFmtCount)
	Retrieves an array of supported Input formats. More...

NVENCSTATUS NVENCAPI	NvEncGetEncodeCaps (void encoder, GUID encodeGUID, NV_ENC_CAPS_PARAM capsParam, int *capsVal)
	Retrieves the capability value for a specified encoder attribute. More...

NVENCSTATUS NVENCAPI	NvEncGetEncodePresetCount (void encoder, GUID encodeGUID, uint32_t encodePresetGUIDCount)
	Retrieves the number of supported preset GUIDs. More...

NVENCSTATUS NVENCAPI	NvEncGetEncodePresetGUIDs (void encoder, GUID encodeGUID, GUID presetGUIDs, uint32_t guidArraySize, uint32_t *encodePresetGUIDCount)
	Receives an array of supported encoder preset GUIDs. More...

NVENCSTATUS NVENCAPI	NvEncGetEncodePresetConfig (void encoder, GUID encodeGUID, GUID presetGUID, NV_ENC_PRESET_CONFIG presetConfig)
	Returns a preset config structure supported for given preset GUID. More...

NVENCSTATUS NVENCAPI	NvEncInitializeEncoder (void encoder, NV_ENC_INITIALIZE_PARAMS createEncodeParams)
	Initialize the encoder. More...

NVENCSTATUS NVENCAPI	NvEncCreateInputBuffer (void encoder, NV_ENC_CREATE_INPUT_BUFFER createInputBufferParams)
	Allocates Input buffer. More...

NVENCSTATUS NVENCAPI	NvEncDestroyInputBuffer (void *encoder, NV_ENC_INPUT_PTR inputBuffer)
	Release an input buffers. More...

NVENCSTATUS NVENCAPI	NvEncCreateBitstreamBuffer (void encoder, NV_ENC_CREATE_BITSTREAM_BUFFER createBitstreamBufferParams)
	Allocates an output bitstream buffer. More...

NVENCSTATUS NVENCAPI	NvEncDestroyBitstreamBuffer (void *encoder, NV_ENC_OUTPUT_PTR bitstreamBuffer)
	Release a bitstream buffer. More...

NVENCSTATUS NVENCAPI	NvEncEncodePicture (void encoder, NV_ENC_PIC_PARAMS encodePicParams)
	Submit an input picture for encoding. More...

NVENCSTATUS NVENCAPI	NvEncLockBitstream (void encoder, NV_ENC_LOCK_BITSTREAM lockBitstreamBufferParams)
	Lock output bitstream buffer. More...

NVENCSTATUS NVENCAPI	NvEncUnlockBitstream (void *encoder, NV_ENC_OUTPUT_PTR bitstreamBuffer)
	Unlock the output bitstream buffer. More...

NVENCSTATUS NVENCAPI	NvEncLockInputBuffer (void encoder, NV_ENC_LOCK_INPUT_BUFFER lockInputBufferParams)
	Locks an input buffer. More...

NVENCSTATUS NVENCAPI	NvEncUnlockInputBuffer (void *encoder, NV_ENC_INPUT_PTR inputBuffer)
	Unlocks the input buffer. More...

NVENCSTATUS NVENCAPI	NvEncGetEncodeStats (void encoder, NV_ENC_STAT encodeStats)
	Get encoding statistics. More...

NVENCSTATUS NVENCAPI	NvEncGetSequenceParams (void encoder, NV_ENC_SEQUENCE_PARAM_PAYLOAD sequenceParamPayload)
	Get encoded sequence and picture header. More...

NVENCSTATUS NVENCAPI	NvEncRegisterAsyncEvent (void encoder, NV_ENC_EVENT_PARAMS eventParams)
	Register event for notification to encoding completion. More...

NVENCSTATUS NVENCAPI	NvEncUnregisterAsyncEvent (void encoder, NV_ENC_EVENT_PARAMS eventParams)
	Unregister completion event. More...

NVENCSTATUS NVENCAPI	NvEncMapInputResource (void encoder, NV_ENC_MAP_INPUT_RESOURCE mapInputResParams)
	Map an externally created input resource pointer for encoding. More...

NVENCSTATUS NVENCAPI	NvEncUnmapInputResource (void *encoder, NV_ENC_INPUT_PTR mappedInputBuffer)
	UnMaps a NV_ENC_INPUT_PTR which was mapped for encoding. More...

NVENCSTATUS NVENCAPI	NvEncDestroyEncoder (void *encoder)
	Destroy Encoding Session. More...

NVENCSTATUS NVENCAPI	NvEncInvalidateRefFrames (void *encoder, uint64_t invalidRefFrameTimeStamp)
	Invalidate reference frames. More...

NVENCSTATUS NVENCAPI	NvEncOpenEncodeSessionEx (NV_ENC_OPEN_ENCODE_SESSION_EX_PARAMS openSessionExParams, void *encoder)
	Opens an encoding session. More...

NVENCSTATUS NVENCAPI	NvEncRegisterResource (void encoder, NV_ENC_REGISTER_RESOURCE registerResParams)
	Registers a resource with the Nvidia Video Encoder Interface. More...

NVENCSTATUS NVENCAPI	NvEncUnregisterResource (void *encoder, NV_ENC_REGISTERED_PTR registeredResource)
	Unregisters a resource previously registered with the Nvidia Video Encoder Interface. More...

NVENCSTATUS NVENCAPI	NvEncReconfigureEncoder (void encoder, NV_ENC_RECONFIGURE_PARAMS reInitEncodeParams)
	Reconfigure an existing encoding session. More...

NVENCSTATUS NVENCAPI	NvEncCreateMVBuffer (void encoder, NV_ENC_CREATE_MV_BUFFER createMVBufferParams)
	Allocates output MV buffer for ME only mode. More...

NVENCSTATUS NVENCAPI	NvEncDestroyMVBuffer (void *encoder, NV_ENC_OUTPUT_PTR mvBuffer)
	Release an output MV buffer for ME only mode. More...

NVENCSTATUS NVENCAPI	NvEncRunMotionEstimationOnly (void encoder, NV_ENC_MEONLY_PARAMS meOnlyParams)
	Submit an input picture and reference frame for motion estimation in ME only mode. More...

NVENCSTATUS NVENCAPI	NvEncodeAPIGetMaxSupportedVersion (uint32_t *version)
	Get the largest NvEncodeAPI version supported by the driver. More...

NVENCSTATUS NVENCAPI	NvEncodeAPICreateInstance (NV_ENCODE_API_FUNCTION_LIST *functionList)
	Entry Point to the NvEncodeAPI interface. More...

Detailed Description

Function Documentation

NVENCSTATUS NVENCAPI NvEncOpenEncodeSession	(	void *	device,
		uint32_t	deviceType,
		void **	encoder
	)

Opens an encoding session.

Deprecated.

Returns: NV_ENC_ERR_INVALID_CALL

NVENCSTATUS NVENCAPI NvEncGetEncodeGUIDCount	(	void *	encoder,
		uint32_t *	encodeGUIDCount
	)

Retrieves the number of supported encode GUIDs.

The function returns the number of codec guids supported by the NvEncodeAPI interface.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[out]	encodeGUIDCount	Number of supported encode GUIDs.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncGetEncodeGUIDs	(	void *	encoder,
		GUID *	GUIDs,
		uint32_t	guidArraySize,
		uint32_t *	GUIDCount
	)

Retrieves an array of supported encoder codec GUIDs.

The function returns an array of codec guids supported by the NvEncodeAPI interface. The client must allocate an array where the NvEncodeAPI interface can fill the supported guids and pass the pointer in *GUIDs parameter. The size of the array can be determined by using NvEncGetEncodeGUIDCount() API. The Nvidia Encoding interface returns the number of codec guids it has actually filled in the guid array in the GUIDCount parameter.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	guidArraySize	Number of GUIDs to retrieved. Should be set to the number retrieved using NvEncGetEncodeGUIDCount.
[out]	GUIDs	Array of supported Encode GUIDs.
[out]	GUIDCount	Number of supported Encode GUIDs.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncGetEncodeProfileGUIDCount	(	void *	encoder,
		GUID	encodeGUID,
		uint32_t *	encodeProfileGUIDCount
	)

Retrieves the number of supported profile GUIDs.

The function returns the number of profile GUIDs supported for a given codec. The client must first enumerate the codec guids supported by the NvEncodeAPI interface. After determining the codec guid, it can query the NvEncodeAPI interface to determine the number of profile guids supported for a particular codec guid.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	encodeGUID	The codec guid for which the profile guids are being enumerated.
[out]	encodeProfileGUIDCount	Number of encode profiles supported for the given encodeGUID.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncGetEncodeProfileGUIDs	(	void *	encoder,
		GUID	encodeGUID,
		GUID *	profileGUIDs,
		uint32_t	guidArraySize,
		uint32_t *	GUIDCount
	)

Retrieves an array of supported encode profile GUIDs.

The function returns an array of supported profile guids for a particular codec guid. The client must allocate an array where the NvEncodeAPI interface can populate the profile guids. The client can determine the array size using NvEncGetEncodeProfileGUIDCount() API. The client must also validiate that the NvEncodeAPI interface supports the GUID the client wants to pass as encodeGUID parameter.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	encodeGUID	The encode guid whose profile guids are being enumerated.
[in]	guidArraySize	Number of GUIDs to be retrieved. Should be set to the number retrieved using NvEncGetEncodeProfileGUIDCount.
[out]	profileGUIDs	Array of supported Encode Profile GUIDs
[out]	GUIDCount	Number of valid encode profile GUIDs in `profileGUIDs` array.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncGetInputFormatCount	(	void *	encoder,
		GUID	encodeGUID,
		uint32_t *	inputFmtCount
	)

Retrieve the number of supported Input formats.

The function returns the number of supported input formats. The client must query the NvEncodeAPI interface to determine the supported input formats before creating the input surfaces.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	encodeGUID	Encode GUID, corresponding to which the number of supported input formats is to be retrieved.
[out]	inputFmtCount	Number of input formats supported for specified Encode GUID.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncGetInputFormats	(	void *	encoder,
		GUID	encodeGUID,
		NV_ENC_BUFFER_FORMAT *	inputFmts,
		uint32_t	inputFmtArraySize,
		uint32_t *	inputFmtCount
	)

Retrieves an array of supported Input formats.

Returns an array of supported input formats The client must use the input format to create input surface using NvEncCreateInputBuffer() API.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	encodeGUID	Encode GUID, corresponding to which the number of supported input formats is to be retrieved.
[in]	inputFmtArraySize	Size input format count array passed in `inputFmts`.
[out]	inputFmts	Array of input formats supported for this Encode GUID.
[out]	inputFmtCount	The number of valid input format types returned by the NvEncodeAPI interface in `inputFmts` array.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncGetEncodeCaps	(	void *	encoder,
		GUID	encodeGUID,
		NV_ENC_CAPS_PARAM *	capsParam,
		int *	capsVal
	)

Retrieves the capability value for a specified encoder attribute.

The function returns the capability value for a given encoder attribute. The client must validate the encodeGUID using NvEncGetEncodeGUIDs() API before calling this function. The encoder attribute being queried are enumerated in NV_ENC_CAPS_PARAM enum.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	encodeGUID	Encode GUID, corresponding to which the capability attribute is to be retrieved.
[in]	capsParam	Used to specify attribute being queried. Refer NV_ENC_CAPS_PARAM for more details.
[out]	capsVal	The value corresponding to the capability attribute being queried.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncGetEncodePresetCount	(	void *	encoder,
		GUID	encodeGUID,
		uint32_t *	encodePresetGUIDCount
	)

Retrieves the number of supported preset GUIDs.

The function returns the number of preset GUIDs available for a given codec. The client must validate the codec guid using NvEncGetEncodeGUIDs() API before calling this function.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	encodeGUID	Encode GUID, corresponding to which the number of supported presets is to be retrieved.
[out]	encodePresetGUIDCount	Receives the number of supported preset GUIDs.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncGetEncodePresetGUIDs	(	void *	encoder,
		GUID	encodeGUID,
		GUID *	presetGUIDs,
		uint32_t	guidArraySize,
		uint32_t *	encodePresetGUIDCount
	)

Receives an array of supported encoder preset GUIDs.

The function returns an array of encode preset guids available for a given codec. The client can directly use one of the preset guids based upon the use case or target device. The preset guid chosen can be directly used in NV_ENC_INITIALIZE_PARAMS::presetGUID parameter to NvEncEncodePicture() API. Alternately client can also use the preset guid to retrieve the encoding config parameters being used by NvEncodeAPI interface for that given preset, using NvEncGetEncodePresetConfig() API. It can then modify preset config parameters as per its use case and send it to NvEncodeAPI interface as part of NV_ENC_INITIALIZE_PARAMS::encodeConfig parameter for NvEncInitializeEncoder() API.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	encodeGUID	Encode GUID, corresponding to which the list of supported presets is to be retrieved.
[in]	guidArraySize	Size of array of preset guids passed in `preset` GUIDs
[out]	presetGUIDs	Array of supported Encode preset GUIDs from the NvEncodeAPI interface to client.
[out]	encodePresetGUIDCount	Receives the number of preset GUIDs returned by the NvEncodeAPI interface.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncGetEncodePresetConfig	(	void *	encoder,
		GUID	encodeGUID,
		GUID	presetGUID,
		NV_ENC_PRESET_CONFIG *	presetConfig
	)

Returns a preset config structure supported for given preset GUID.

The function returns a preset config structure for a given preset guid. Before using this function the client must enumerate the preset guids available for a given codec. The preset config structure can be modified by the client depending upon its use case and can be then used to initialize the encoder using NvEncInitializeEncoder() API. The client can use this function only if it wants to modify the NvEncodeAPI preset configuration, otherwise it can directly use the preset guid.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	encodeGUID	Encode GUID, corresponding to which the list of supported presets is to be retrieved.
[in]	presetGUID	Preset GUID, corresponding to which the Encoding configurations is to be retrieved.
[out]	presetConfig	The requested Preset Encoder Attribute set. Refer _NV_ENC_CONFIG for more details.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncInitializeEncoder	(	void *	encoder,
		NV_ENC_INITIALIZE_PARAMS *	createEncodeParams
	)

Initialize the encoder.

This API must be used to initialize the encoder. The initialization parameter is passed using *createEncodeParams The client must send the following fields of the _NV_ENC_INITIALIZE_PARAMS structure with a valid value.

The client can pass a preset guid directly to the NvEncodeAPI interface using NV_ENC_INITIALIZE_PARAMS::presetGUID field. If the client doesn't pass NV_ENC_INITIALIZE_PARAMS::encodeConfig structure, the codec specific parameters will be selected based on the preset guid. The preset guid must have been validated by the client using NvEncGetEncodePresetGUIDs() API. If the client passes a custom _NV_ENC_CONFIG structure through NV_ENC_INITIALIZE_PARAMS::encodeConfig , it will override the codec specific parameters based on the preset guid. It is recommended that even if the client passes a custom config, it should also send a preset guid. In this case, the preset guid passed by the client will not override any of the custom config parameters programmed by the client, it is only used as a hint by the NvEncodeAPI interface to determine certain encoder parameters which are not exposed to the client.

There are two modes of operation for the encoder namely:

Asynchronous mode
Synchronous mode

The client can select asynchronous or synchronous mode by setting the enableEncodeAsync field in _NV_ENC_INITIALIZE_PARAMS to 1 or 0 respectively.

Asynchronous mode of operation:: The Asynchronous mode can be enabled by setting NV_ENC_INITIALIZE_PARAMS::enableEncodeAsync to 1. The client operating in asynchronous mode must allocate completion event object for each output buffer and pass the completion event object in the NvEncEncodePicture() API. The client can create another thread and wait on the event object to be signalled by NvEncodeAPI interface on completion of the encoding process for the output frame. This should unblock the main thread from submitting work to the encoder. When the event is signalled the client can call NvEncodeAPI interfaces to copy the bitstream data using NvEncLockBitstream() API. This is the preferred mode of operation.

NOTE: Asynchronous mode is not supported on Linux.

Synchronous mode of operation:: The client can select synchronous mode by setting NV_ENC_INITIALIZE_PARAMS::enableEncodeAsync to 0. The client working in synchronous mode can work in a single threaded or multi threaded mode. The client need not allocate any event objects. The client can only lock the bitstream data after NvEncodeAPI interface has returned NV_ENC_SUCCESS from encode picture. The NvEncodeAPI interface can return NV_ENC_ERR_NEED_MORE_INPUT error code from NvEncEncodePicture() API. The client must not lock the output buffer in such case but should send the next frame for encoding. The client must keep on calling NvEncEncodePicture() API until it returns NV_ENC_SUCCESS.
The client must always lock the bitstream data in order in which it has submitted. This is true for both asynchronous and synchronous mode.

Picture type decision:: If the client is taking the picture type decision and it must disable the picture type decision module in NvEncodeAPI by setting NV_ENC_INITIALIZE_PARAMS::enablePTD to 0. In this case the client is required to send the picture in encoding order to NvEncodeAPI by doing the re-ordering for B frames.
If the client doesn't want to take the picture type decision it can enable picture type decision module in the NvEncodeAPI interface by setting NV_ENC_INITIALIZE_PARAMS::enablePTD to 1 and send the input pictures in display order.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	createEncodeParams	Refer _NV_ENC_INITIALIZE_PARAMS for details.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncCreateInputBuffer	(	void *	encoder,
		NV_ENC_CREATE_INPUT_BUFFER *	createInputBufferParams
	)

Allocates Input buffer.

This function is used to allocate an input buffer. The client must enumerate the input buffer format before allocating the input buffer resources. The NV_ENC_INPUT_PTR returned by the NvEncodeAPI interface in the NV_ENC_CREATE_INPUT_BUFFER::inputBuffer field can be directly used in NvEncEncodePicture() API. The number of input buffers to be allocated by the client must be at least 4 more than the number of B frames being used for encoding.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in,out]	createInputBufferParams	Pointer to the NV_ENC_CREATE_INPUT_BUFFER structure.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncDestroyInputBuffer	(	void *	encoder,
		NV_ENC_INPUT_PTR	inputBuffer
	)

Release an input buffers.

This function is used to free an input buffer. If the client has allocated any input buffer using NvEncCreateInputBuffer() API, it must free those input buffers by calling this function. The client must release the input buffers before destroying the encoder using NvEncDestroyEncoder() API.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	inputBuffer	Pointer to the input buffer to be released.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncCreateBitstreamBuffer	(	void *	encoder,
		NV_ENC_CREATE_BITSTREAM_BUFFER *	createBitstreamBufferParams
	)

Allocates an output bitstream buffer.

This function is used to allocate an output bitstream buffer and returns a NV_ENC_OUTPUT_PTR to bitstream buffer to the client in the NV_ENC_CREATE_BITSTREAM_BUFFER::bitstreamBuffer field. The client can only call this function after the encoder session has been initialized using NvEncInitializeEncoder() API. The minimum number of output buffers allocated by the client must be at least 4 more than the number of B B frames being used for encoding. The client can only access the output bitsteam data by locking the bitstreamBuffer using the NvEncLockBitstream() function.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in,out]	createBitstreamBufferParams	Pointer NV_ENC_CREATE_BITSTREAM_BUFFER for details.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncDestroyBitstreamBuffer	(	void *	encoder,
		NV_ENC_OUTPUT_PTR	bitstreamBuffer
	)

Release a bitstream buffer.

This function is used to release the output bitstream buffer allocated using the NvEncCreateBitstreamBuffer() function. The client must release the output bitstreamBuffer using this function before destroying the encoder session.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	bitstreamBuffer	Pointer to the bitstream buffer being released.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncEncodePicture	(	void *	encoder,
		NV_ENC_PIC_PARAMS *	encodePicParams
	)

Submit an input picture for encoding.

This function is used to submit an input picture buffer for encoding. The encoding parameters are passed using *encodePicParams which is a pointer to the _NV_ENC_PIC_PARAMS structure.

If the client has set NV_ENC_INITIALIZE_PARAMS::enablePTD to 0, then it must send a valid value for the following fields.

NV_ENC_PIC_PARAMS::pictureType
NV_ENC_PIC_PARAMS_H264::displayPOCSyntax (H264 only)
NV_ENC_PIC_PARAMS_H264::frameNumSyntax(H264 only)
NV_ENC_PIC_PARAMS_H264::refPicFlag(H264 only)

Asynchronous Encoding: If the client has enabled asynchronous mode of encoding by setting NV_ENC_INITIALIZE_PARAMS::enableEncodeAsync to 1 in the NvEncInitializeEncoder() API ,then the client must send a valid NV_ENC_PIC_PARAMS::completionEvent. Incase of asynchronous mode of operation, client can queue the NvEncEncodePicture() API commands from the main thread and then queue output buffers to be processed to a secondary worker thread. Before the locking the output buffers in the secondary thread , the client must wait on NV_ENC_PIC_PARAMS::completionEvent it has queued in NvEncEncodePicture() API call. The client must always process completion event and the output buffer in the same order in which they have been submitted for encoding. The NvEncodeAPI interface is responsible for any re-ordering required for B frames and will always ensure that encoded bitstream data is written in the same order in which output buffer is submitted.
The below example shows how asynchronous encoding in case of 1 B frames

------------------------------------------------------------------------

Suppose the client allocated 4 input buffers(I1,I2..), 4 output buffers(O1,O2..)

and 4 completion events(E1, E2, ...). The NvEncodeAPI interface will need to

keep a copy of the input buffers for re-ordering and it allocates following

internal buffers (NvI1, NvI2...). These internal buffers are managed by NvEncodeAPI

and the client is not responsible for the allocating or freeing the memory of

the internal buffers.

a) The client main thread will queue the following encode frame calls.

Note the picture type is unknown to the client, the decision is being taken by

NvEncodeAPI interface. The client should pass ::_NV_ENC_PIC_PARAMS parameter

consisting of allocated input buffer, output buffer and output events in successive

::NvEncEncodePicture() API calls along with other required encode picture params.

For example:

1st EncodePicture parameters - (I1, O1, E1)

2nd EncodePicture parameters - (I2, O2, E2)

3rd EncodePicture parameters - (I3, O3, E3)

b) NvEncodeAPI SW will receive the following encode Commands from the client.

The left side shows input from client in the form (Input buffer, Output Buffer,

Output Event). The right hand side shows a possible picture type decision take by

the NvEncodeAPI interface.

(I1, O1, E1) ---P1 Frame

(I2, O2, E2) ---B2 Frame

(I3, O3, E3) ---P3 Frame

c) NvEncodeAPI interface will make a copy of the input buffers to its internal

buffersfor re-ordering. These copies are done as part of nvEncEncodePicture

function call from the client and NvEncodeAPI interface is responsible for

synchronization of copy operation with the actual encoding operation.

I1 --> NvI1

I2 --> NvI2

I3 --> NvI3

d) After returning from ::NvEncEncodePicture() call , the client must queue the output

bitstream processing work to the secondary thread. The output bitstream processing

for asynchronous mode consist of first waiting on completion event(E1, E2..)

and then locking the output bitstream buffer(O1, O2..) for reading the encoded

data. The work queued to the secondary thread by the client is in the following order

(I1, O1, E1)

(I2, O2, E2)

(I3, O3, E3)

Note they are in the same order in which client calls ::NvEncEncodePicture() API

in \p step a).

e) NvEncodeAPI interface will do the re-ordering such that Encoder HW will receive

the following encode commands:

(NvI1, O1, E1) ---P1 Frame

(NvI3, O2, E2) ---P3 Frame

(NvI2, O3, E3) ---B2 frame

f) After the encoding operations are completed, the events will be signalled

by NvEncodeAPI interface in the following order :

(O1, E1) ---P1 Frame ,output bitstream copied to O1 and event E1 signalled.

(O2, E2) ---P3 Frame ,output bitstream copied to O2 and event E2 signalled.

(O3, E3) ---B2 Frame ,output bitstream copied to O3 and event E3 signalled.

g) The client must lock the bitstream data using ::NvEncLockBitstream() API in

the order O1,O2,O3 to read the encoded data, after waiting for the events

to be signalled in the same order i.e E1, E2 and E3.The output processing is

done in the secondary thread in the following order:

Waits on E1, copies encoded bitstream from O1

Waits on E2, copies encoded bitstream from O2

Waits on E3, copies encoded bitstream from O3

-Note the client will receive the events signalling and output buffer in the

same order in which they have submitted for encoding.

-Note the LockBitstream will have picture type field which will notify the

output picture type to the clients.

-Note the input, output buffer and the output completion event are free to be

reused once NvEncodeAPI interfaced has signalled the event and the client has

copied the data from the output buffer.

Synchronous Encoding: The client can enable synchronous mode of encoding by setting NV_ENC_INITIALIZE_PARAMS::enableEncodeAsync to 0 in NvEncInitializeEncoder() API. The NvEncodeAPI interface may return NV_ENC_ERR_NEED_MORE_INPUT error code for some NvEncEncodePicture() API calls when NV_ENC_INITIALIZE_PARAMS::enablePTD is set to 1, but the client must not treat it as a fatal error. The NvEncodeAPI interface might not be able to submit an input picture buffer for encoding immediately due to re-ordering for B frames. The NvEncodeAPI interface cannot submit the input picture which is decided to be encoded as B frame as it waits for backward reference from temporally subsequent frames. This input picture is buffered internally and waits for more input picture to arrive. The client must not call NvEncLockBitstream() API on the output buffers whose NvEncEncodePicture() API returns NV_ENC_ERR_NEED_MORE_INPUT. The client must wait for the NvEncodeAPI interface to return NV_ENC_SUCCESS before locking the output bitstreams to read the encoded bitstream data. The following example explains the scenario with synchronous encoding with 2 B frames.
The below example shows how synchronous encoding works in case of 1 B frames

-----------------------------------------------------------------------------

Suppose the client allocated 4 input buffers(I1,I2..), 4 output buffers(O1,O2..)

and 4 completion events(E1, E2, ...). The NvEncodeAPI interface will need to

keep a copy of the input buffers for re-ordering and it allocates following

internal buffers (NvI1, NvI2...). These internal buffers are managed by NvEncodeAPI

and the client is not responsible for the allocating or freeing the memory of

the internal buffers.

The client calls ::NvEncEncodePicture() API with input buffer I1 and output buffer O1.

The NvEncodeAPI decides to encode I1 as P frame and submits it to encoder

HW and returns ::NV_ENC_SUCCESS.

The client can now read the encoded data by locking the output O1 by calling

NvEncLockBitstream API.

The client calls ::NvEncEncodePicture() API with input buffer I2 and output buffer O2.

The NvEncodeAPI decides to encode I2 as B frame and buffers I2 by copying it

to internal buffer and returns ::NV_ENC_ERR_NEED_MORE_INPUT.

The error is not fatal and it notifies client that it cannot read the encoded

data by locking the output O2 by calling ::NvEncLockBitstream() API without submitting

more work to the NvEncodeAPI interface.

The client calls ::NvEncEncodePicture() with input buffer I3 and output buffer O3.

The NvEncodeAPI decides to encode I3 as P frame and it first submits I3 for

encoding which will be used as backward reference frame for I2.

The NvEncodeAPI then submits I2 for encoding and returns ::NV_ENC_SUCESS. Both

the submission are part of the same ::NvEncEncodePicture() function call.

The client can now read the encoded data for both the frames by locking the output

O2 followed by O3 ,by calling ::NvEncLockBitstream() API.

The client must always lock the output in the same order in which it has submitted

to receive the encoded bitstream in correct encoding order.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in,out]	encodePicParams	Pointer to the _NV_ENC_PIC_PARAMS structure.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_ENCODER_BUSY
NV_ENC_ERR_NEED_MORE_INPUT
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncLockBitstream	(	void *	encoder,
		NV_ENC_LOCK_BITSTREAM *	lockBitstreamBufferParams
	)

Lock output bitstream buffer.

This function is used to lock the bitstream buffer to read the encoded data. The client can only access the encoded data by calling this function. The pointer to client accessible encoded data is returned in the NV_ENC_LOCK_BITSTREAM::bitstreamBufferPtr field. The size of the encoded data in the output buffer is returned in the NV_ENC_LOCK_BITSTREAM::bitstreamSizeInBytes The NvEncodeAPI interface also returns the output picture type and picture structure of the encoded frame in NV_ENC_LOCK_BITSTREAM::pictureType and NV_ENC_LOCK_BITSTREAM::pictureStruct fields respectively. If the client has set NV_ENC_LOCK_BITSTREAM::doNotWait to 1, the function might return NV_ENC_ERR_LOCK_BUSY if client is operating in synchronous mode. This is not a fatal failure if NV_ENC_LOCK_BITSTREAM::doNotWait is set to 1. In the above case the client can retry the function after few milliseconds.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in,out]	lockBitstreamBufferParams	Pointer to the _NV_ENC_LOCK_BITSTREAM structure.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_LOCK_BUSY
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncUnlockBitstream	(	void *	encoder,
		NV_ENC_OUTPUT_PTR	bitstreamBuffer
	)

Unlock the output bitstream buffer.

This function is used to unlock the output bitstream buffer after the client has read the encoded data from output buffer. The client must call this function to unlock the output buffer which it has previously locked using NvEncLockBitstream() function. Using a locked bitstream buffer in NvEncEncodePicture() API will cause the function to fail.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in,out]	bitstreamBuffer	bitstream buffer pointer being unlocked

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncLockInputBuffer	(	void *	encoder,
		NV_ENC_LOCK_INPUT_BUFFER *	lockInputBufferParams
	)

Locks an input buffer.

This function is used to lock the input buffer to load the uncompressed YUV pixel data into input buffer memory. The client must pass the NV_ENC_INPUT_PTR it had previously allocated using NvEncCreateInputBuffer()in the NV_ENC_LOCK_INPUT_BUFFER::inputBuffer field. The NvEncodeAPI interface returns pointer to client accessible input buffer memory in NV_ENC_LOCK_INPUT_BUFFER::bufferDataPtr field.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in,out]	lockInputBufferParams	Pointer to the _NV_ENC_LOCK_INPUT_BUFFER structure

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_LOCK_BUSY
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncUnlockInputBuffer	(	void *	encoder,
		NV_ENC_INPUT_PTR	inputBuffer
	)

Unlocks the input buffer.

This function is used to unlock the input buffer memory previously locked for uploading YUV pixel data. The input buffer must be unlocked before being used again for encoding, otherwise NvEncodeAPI will fail the NvEncEncodePicture()

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	inputBuffer	Pointer to the input buffer that is being unlocked.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncGetEncodeStats	(	void *	encoder,
		NV_ENC_STAT *	encodeStats
	)

Get encoding statistics.

This function is used to retrieve the encoding statistics. This API is not supported when encode device type is CUDA.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in,out]	encodeStats	Pointer to the _NV_ENC_STAT structure.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncGetSequenceParams	(	void *	encoder,
		NV_ENC_SEQUENCE_PARAM_PAYLOAD *	sequenceParamPayload
	)

Get encoded sequence and picture header.

This function can be used to retrieve the sequence and picture header out of band. The client must call this function only after the encoder has been initialized using NvEncInitializeEncoder() function. The client must allocate the memory where the NvEncodeAPI interface can copy the bitstream header and pass the pointer to the memory in NV_ENC_SEQUENCE_PARAM_PAYLOAD::spsppsBuffer. The size of buffer is passed in the field NV_ENC_SEQUENCE_PARAM_PAYLOAD::inBufferSize. The NvEncodeAPI interface will copy the bitstream header payload and returns the actual size of the bitstream header in the field NV_ENC_SEQUENCE_PARAM_PAYLOAD::outSPSPPSPayloadSize. The client must call NvEncGetSequenceParams() function from the same thread which is being used to call NvEncEncodePicture() function.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in,out]	sequenceParamPayload	Pointer to the _NV_ENC_SEQUENCE_PARAM_PAYLOAD structure.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncRegisterAsyncEvent	(	void *	encoder,
		NV_ENC_EVENT_PARAMS *	eventParams
	)

Register event for notification to encoding completion.

This function is used to register the completion event with NvEncodeAPI interface. The event is required when the client has configured the encoder to work in asynchronous mode. In this mode the client needs to send a completion event with every output buffer. The NvEncodeAPI interface will signal the completion of the encoding process using this event. Only after the event is signalled the client can get the encoded data using NvEncLockBitstream() function.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	eventParams	Pointer to the ::_NV_ENC_EVENT_PARAMS structure.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncUnregisterAsyncEvent	(	void *	encoder,
		NV_ENC_EVENT_PARAMS *	eventParams
	)

Unregister completion event.

This function is used to unregister completion event which has been previously registered using NvEncRegisterAsyncEvent() function. The client must unregister all events before destroying the encoder using NvEncDestroyEncoder() function.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	eventParams	Pointer to the ::_NV_ENC_EVENT_PARAMS structure.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncMapInputResource	(	void *	encoder,
		NV_ENC_MAP_INPUT_RESOURCE *	mapInputResParams
	)

Map an externally created input resource pointer for encoding.

Maps an externally allocated input resource [using and returns a NV_ENC_INPUT_PTR which can be used for encoding in the NvEncEncodePicture() function. The mapped resource is returned in the field NV_ENC_MAP_INPUT_RESOURCE::outputResourcePtr. The NvEncodeAPI interface also returns the buffer format of the mapped resource in the field NV_ENC_MAP_INPUT_RESOURCE::outbufferFmt. This function provides synchronization guarantee that any direct3d or cuda work submitted on the input buffer is completed before the buffer is used for encoding. The client should not access any input buffer while they are mapped by the encoder.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in,out]	mapInputResParams	Pointer to the _NV_ENC_MAP_INPUT_RESOURCE structure.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_RESOURCE_NOT_REGISTERED
NV_ENC_ERR_MAP_FAILED
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncUnmapInputResource	(	void *	encoder,
		NV_ENC_INPUT_PTR	mappedInputBuffer
	)

UnMaps a NV_ENC_INPUT_PTR which was mapped for encoding.

UnMaps an input buffer which was previously mapped using NvEncMapInputResource() API. The mapping created using NvEncMapInputResource() should be invalidated using this API before the external resource is destroyed by the client. The client must unmap the buffer after NvEncLockBitstream() API returns succuessfully for encode work submitted using the mapped input buffer.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	mappedInputBuffer	Pointer to the NV_ENC_INPUT_PTR

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_RESOURCE_NOT_REGISTERED
NV_ENC_ERR_RESOURCE_NOT_MAPPED
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncDestroyEncoder ( void * encoder )

Destroy Encoding Session.

Destroys the encoder session previously created using NvEncOpenEncodeSession() function. The client must flush the encoder before freeing any resources. In order to flush the encoder the client must pass a NULL encode picture packet and either wait for the NvEncEncodePicture() function to return in synchronous mode or wait for the flush event to be signaled by the encoder in asynchronous mode. The client must free all the input and output resources created using the NvEncodeAPI interface before destroying the encoder. If the client is operating in asynchronous mode, it must also unregister the completion events previously registered.

Parameters

[in] encoder Pointer to the NvEncodeAPI interface.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncInvalidateRefFrames	(	void *	encoder,
		uint64_t	invalidRefFrameTimeStamp
	)

Invalidate reference frames.

Invalidates reference frame based on the time stamp provided by the client. The encoder marks any reference frames or any frames which have been reconstructed using the corrupt frame as invalid for motion estimation and uses older reference frames for motion estimation. The encoded forces the current frame to be encoded as an intra frame if no reference frames are left after invalidation process. This is useful for low latency application for error resiliency. The client is recommended to set NV_ENC_CONFIG_H264::maxNumRefFrames to a large value so that encoder can keep a backup of older reference frames in the DPB and can use them for motion estimation when the newer reference frames have been invalidated. This API can be called multiple times.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	invalidRefFrameTimeStamp	Timestamp of the invalid reference frames which needs to be invalidated.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncOpenEncodeSessionEx	(	NV_ENC_OPEN_ENCODE_SESSION_EX_PARAMS *	openSessionExParams,
		void **	encoder
	)

Opens an encoding session.

Opens an encoding session and returns a pointer to the encoder interface in the **encoder parameter. The client should start encoding process by calling this API first. The client must pass a pointer to IDirect3DDevice9/CUDA interface in the *device parameter. If the creation of encoder session fails, the client must call NvEncDestroyEncoder API before exiting.

Parameters

[in]	openSessionExParams	Pointer to a NV_ENC_OPEN_ENCODE_SESSION_EX_PARAMS structure.
[out]	encoder	Encode Session pointer to the NvEncodeAPI interface.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_NO_ENCODE_DEVICE
NV_ENC_ERR_UNSUPPORTED_DEVICE
NV_ENC_ERR_INVALID_DEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncRegisterResource	(	void *	encoder,
		NV_ENC_REGISTER_RESOURCE *	registerResParams
	)

Registers a resource with the Nvidia Video Encoder Interface.

Registers a resource with the Nvidia Video Encoder Interface for book keeping. The client is expected to pass the registered resource handle as well, while calling NvEncMapInputResource API. This API is not implemented for the DirectX Interface. DirectX based clients need not change their implementation.

Parameters

[in]	encoder	Pointer to the NVEncodeAPI interface.
[in]	registerResParams	Pointer to a _NV_ENC_REGISTER_RESOURCE structure

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_RESOURCE_REGISTER_FAILED
NV_ENC_ERR_GENERIC
NV_ENC_ERR_UNIMPLEMENTED

NVENCSTATUS NVENCAPI NvEncUnregisterResource	(	void *	encoder,
		NV_ENC_REGISTERED_PTR	registeredResource
	)

Unregisters a resource previously registered with the Nvidia Video Encoder Interface.

Unregisters a resource previously registered with the Nvidia Video Encoder Interface. The client is expected to unregister any resource that it has registered with the Nvidia Video Encoder Interface before destroying the resource. This API is not implemented for the DirectX Interface. DirectX based clients need not change their implementation.

Parameters

[in]	encoder	Pointer to the NVEncodeAPI interface.
[in]	registeredResource	The registered resource pointer that was returned in NvEncRegisterResource.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_RESOURCE_NOT_REGISTERED
NV_ENC_ERR_GENERIC
NV_ENC_ERR_UNIMPLEMENTED

NVENCSTATUS NVENCAPI NvEncReconfigureEncoder	(	void *	encoder,
		NV_ENC_RECONFIGURE_PARAMS *	reInitEncodeParams
	)

Reconfigure an existing encoding session.

Reconfigure an existing encoding session. The client should call this API to change/reconfigure the parameter passed during NvEncInitializeEncoder API call. Currently Reconfiguration of following are not supported. Change in GOP structure. Change in sync-Async mode. Change in MaxWidth & MaxHeight. Change in PTDmode.

Resolution change is possible only if maxEncodeWidth & maxEncodeHeight of NV_ENC_INITIALIZE_PARAMS is set while creating encoder session.

Parameters

[in]	encoder	Pointer to the NVEncodeAPI interface.
[in]	reInitEncodeParams	Pointer to a NV_ENC_RECONFIGURE_PARAMS structure.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_NO_ENCODE_DEVICE
NV_ENC_ERR_UNSUPPORTED_DEVICE
NV_ENC_ERR_INVALID_DEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncCreateMVBuffer	(	void *	encoder,
		NV_ENC_CREATE_MV_BUFFER *	createMVBufferParams
	)

Allocates output MV buffer for ME only mode.

This function is used to allocate an output MV buffer. The size of the mvBuffer is dependent on the frame height and width of the last NvEncCreateInputBuffer() call. The NV_ENC_OUTPUT_PTR returned by the NvEncodeAPI interface in the NV_ENC_CREATE_MV_BUFFER::mvBuffer field should be used in NvEncRunMotionEstimationOnly() API. Client must lock NV_ENC_CREATE_MV_BUFFER::mvBuffer using NvEncLockBitstream() API to get the motion vector data.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in,out]	createMVBufferParams	Pointer to the NV_ENC_CREATE_MV_BUFFER structure.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncDestroyMVBuffer	(	void *	encoder,
		NV_ENC_OUTPUT_PTR	mvBuffer
	)

Release an output MV buffer for ME only mode.

This function is used to release the output MV buffer allocated using the NvEncCreateMVBuffer() function. The client must release the output mvBuffer using this function before destroying the encoder session.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	mvBuffer	Pointer to the mvBuffer being released.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncRunMotionEstimationOnly	(	void *	encoder,
		NV_ENC_MEONLY_PARAMS *	meOnlyParams
	)

Submit an input picture and reference frame for motion estimation in ME only mode.

This function is used to submit the input frame and reference frame for motion estimation. The ME parameters are passed using *meOnlyParams which is a pointer to _NV_ENC_MEONLY_PARAMS structure. Client must lock NV_ENC_CREATE_MV_BUFFER::mvBuffer using NvEncLockBitstream() API to get the motion vector data. to get motion vector data.

Parameters

[in]	encoder	Pointer to the NvEncodeAPI interface.
[in]	meOnlyParams	Pointer to the _NV_ENC_MEONLY_PARAMS structure.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR
NV_ENC_ERR_INVALID_ENCODERDEVICE
NV_ENC_ERR_DEVICE_NOT_EXIST
NV_ENC_ERR_UNSUPPORTED_PARAM
NV_ENC_ERR_OUT_OF_MEMORY
NV_ENC_ERR_INVALID_PARAM
NV_ENC_ERR_INVALID_VERSION
NV_ENC_ERR_NEED_MORE_INPUT
NV_ENC_ERR_ENCODER_NOT_INITIALIZED
NV_ENC_ERR_GENERIC

NVENCSTATUS NVENCAPI NvEncodeAPIGetMaxSupportedVersion ( uint32_t * version )

Get the largest NvEncodeAPI version supported by the driver.

This function can be used by clients to determine if the driver supports the NvEncodeAPI header the application was compiled with.

Parameters

[out] version Pointer to the requested value. The 4 least significant bits in the returned indicate the minor version and the rest of the bits indicate the major version of the largest supported version.

Returns: NV_ENC_SUCCESS
NV_ENC_ERR_INVALID_PTR

NVENCSTATUS NVENCAPI NvEncodeAPICreateInstance ( NV_ENCODE_API_FUNCTION_LIST * functionList )

Entry Point to the NvEncodeAPI interface.

Creates an instance of the NvEncodeAPI interface, and populates the pFunctionList with function pointers to the API routines implemented by the NvEncodeAPI interface.

Parameters

[out] functionList

Returns: NV_ENC_SUCCESS NV_ENC_ERR_INVALID_PTR

Functions

Detailed Description

Function Documentation