FFmpeg
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Functions
NvEncodeAPI Functions

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]encoderPointer to the NvEncodeAPI interface.
[out]encodeGUIDCountNumber 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]encoderPointer to the NvEncodeAPI interface.
[in]guidArraySizeNumber of GUIDs to retrieved. Should be set to the number retrieved using NvEncGetEncodeGUIDCount.
[out]GUIDsArray of supported Encode GUIDs.
[out]GUIDCountNumber 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]encoderPointer to the NvEncodeAPI interface.
[in]encodeGUIDThe codec guid for which the profile guids are being enumerated.
[out]encodeProfileGUIDCountNumber 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]encoderPointer to the NvEncodeAPI interface.
[in]encodeGUIDThe encode guid whose profile guids are being enumerated.
[in]guidArraySizeNumber of GUIDs to be retrieved. Should be set to the number retrieved using NvEncGetEncodeProfileGUIDCount.
[out]profileGUIDsArray of supported Encode Profile GUIDs
[out]GUIDCountNumber 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]encoderPointer to the NvEncodeAPI interface.
[in]encodeGUIDEncode GUID, corresponding to which the number of supported input formats is to be retrieved.
[out]inputFmtCountNumber 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]encoderPointer to the NvEncodeAPI interface.
[in]encodeGUIDEncode GUID, corresponding to which the number of supported input formats is to be retrieved.
[in]inputFmtArraySizeSize input format count array passed in inputFmts.
[out]inputFmtsArray of input formats supported for this Encode GUID.
[out]inputFmtCountThe 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]encoderPointer to the NvEncodeAPI interface.
[in]encodeGUIDEncode GUID, corresponding to which the capability attribute is to be retrieved.
[in]capsParamUsed to specify attribute being queried. Refer NV_ENC_CAPS_PARAM for more details.
[out]capsValThe 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]encoderPointer to the NvEncodeAPI interface.
[in]encodeGUIDEncode GUID, corresponding to which the number of supported presets is to be retrieved.
[out]encodePresetGUIDCountReceives 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]encoderPointer to the NvEncodeAPI interface.
[in]encodeGUIDEncode GUID, corresponding to which the list of supported presets is to be retrieved.
[in]guidArraySizeSize of array of preset guids passed in preset GUIDs
[out]presetGUIDsArray of supported Encode preset GUIDs from the NvEncodeAPI interface to client.
[out]encodePresetGUIDCountReceives 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]encoderPointer to the NvEncodeAPI interface.
[in]encodeGUIDEncode GUID, corresponding to which the list of supported presets is to be retrieved.
[in]presetGUIDPreset GUID, corresponding to which the Encoding configurations is to be retrieved.
[out]presetConfigThe 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]encoderPointer to the NvEncodeAPI interface.
[in]createEncodeParamsRefer _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]encoderPointer to the NvEncodeAPI interface.
[in,out]createInputBufferParamsPointer 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]encoderPointer to the NvEncodeAPI interface.
[in]inputBufferPointer 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]encoderPointer to the NvEncodeAPI interface.
[in,out]createBitstreamBufferParamsPointer 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]encoderPointer to the NvEncodeAPI interface.
[in]bitstreamBufferPointer 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.

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
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]encoderPointer to the NvEncodeAPI interface.
[in,out]encodePicParamsPointer 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]encoderPointer to the NvEncodeAPI interface.
[in,out]lockBitstreamBufferParamsPointer 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]encoderPointer to the NvEncodeAPI interface.
[in,out]bitstreamBufferbitstream 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]encoderPointer to the NvEncodeAPI interface.
[in,out]lockInputBufferParamsPointer 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]encoderPointer to the NvEncodeAPI interface.
[in]inputBufferPointer 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]encoderPointer to the NvEncodeAPI interface.
[in,out]encodeStatsPointer 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]encoderPointer to the NvEncodeAPI interface.
[in,out]sequenceParamPayloadPointer 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]encoderPointer to the NvEncodeAPI interface.
[in]eventParamsPointer 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]encoderPointer to the NvEncodeAPI interface.
[in]eventParamsPointer 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]encoderPointer to the NvEncodeAPI interface.
[in,out]mapInputResParamsPointer 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]encoderPointer to the NvEncodeAPI interface.
[in]mappedInputBufferPointer 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]encoderPointer 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]encoderPointer to the NvEncodeAPI interface.
[in]invalidRefFrameTimeStampTimestamp 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]openSessionExParamsPointer to a NV_ENC_OPEN_ENCODE_SESSION_EX_PARAMS structure.
[out]encoderEncode 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]encoderPointer to the NVEncodeAPI interface.
[in]registerResParamsPointer 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]encoderPointer to the NVEncodeAPI interface.
[in]registeredResourceThe 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]encoderPointer to the NVEncodeAPI interface.
[in]reInitEncodeParamsPointer 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]encoderPointer to the NvEncodeAPI interface.
[in,out]createMVBufferParamsPointer 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]encoderPointer to the NvEncodeAPI interface.
[in]mvBufferPointer 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]encoderPointer to the NvEncodeAPI interface.
[in]meOnlyParamsPointer 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]versionPointer 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