NVIDIA DRIVE OS Linux API Reference

5.1.0.2 Release

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

Detailed Description

The NvMediaVideoEncoder object takes uncompressed video data and tuns it into a codec specific bitstream.

Currently only H.264 encoding is supported.

Data Structures

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

Macros

#define NVMEDIA_VEP_VERSION_MAJOR   2
 Major Version number. More...
 
#define NVMEDIA_VEP_VERSION_MINOR   1
 Minor Version number. More...
 

Enumerations

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

Functions

NvMediaStatus NvMediaVideoEncoderGetVersion (NvMediaVersion *version)
 Gets the version information for the NvMedia Video Encoder library. More...
 
NvMediaVideoEncoderNvMediaVideoEncoderCreate (NvMediaDevice *device, NvMediaVideoEncodeType codec, void *initParams, NvMediaSurfaceType inputFormat, uint8_t maxInputBuffering, uint8_t maxOutputBuffering, NvMediaEncoderInstanceId instanceId)
 Creates an encoder object capable of turning a stream of surfaces of the "inputFormat" into a bitstream of the specified "codec". More...
 
void NvMediaVideoEncoderDestroy (NvMediaVideoEncoder *encoder)
 Destroys an NvMediaEncoder object. More...
 
NvMediaStatus NvMediaVideoEncoderFeedFrame (NvMediaVideoEncoder *encoder, NvMediaVideoSurface *frame, NvMediaRect *sourceRect, void *picParams, NvMediaEncoderInstanceId instanceId)
 Encodes the specified "frame". More...
 
NvMediaStatus NvMediaVideoEncoderSetConfiguration (NvMediaVideoEncoder *encoder, void *configuration)
 Sets the encoder configuration. More...
 
NvMediaStatus NvMediaVideoEncoderGetBits (NvMediaVideoEncoder *encoder, uint32_t *numBytes, void *buffer)
 NvMediaVideoEncoderGetBits returns a frame's worth of bitstream into the provided "buffer". More...
 
NvMediaStatus NvMediaVideoEncoderBitsAvailable (NvMediaVideoEncoder *encoder, uint32_t *numBytesAvailable, NvMediaBlockingType blockingType, uint32_t millisecondTimeout)
 Returns the encode status and number of bytes available for the next frame (if any). More...
 

Macro Definition Documentation

#define NVMEDIA_VEP_VERSION_MAJOR   2

Major Version number.

Definition at line 35 of file nvmedia_vep.h.

#define NVMEDIA_VEP_VERSION_MINOR   1

Minor Version number.

Definition at line 37 of file nvmedia_vep.h.

Enumeration Type Documentation

Blocking type.

Enumerator
NVMEDIA_ENCODE_BLOCKING_TYPE_NEVER 

Never blocks.

NVMEDIA_ENCODE_BLOCKING_TYPE_IF_PENDING 

Block only when operation is pending.

NVMEDIA_ENCODE_BLOCKING_TYPE_ALWAYS 

Always blocks.

Definition at line 1538 of file nvmedia_common.h.

Rate Control Modes.

Enumerator
NVMEDIA_ENCODE_PARAMS_RC_CBR 

Constant bitrate mode.

NVMEDIA_ENCODE_PARAMS_RC_CONSTQP 

Constant QP mode.

NVMEDIA_ENCODE_PARAMS_RC_VBR 

Variable bitrate mode.

NVMEDIA_ENCODE_PARAMS_RC_VBR_MINQP 

Variable bitrate mode with MinQP.

NVMEDIA_ENCODE_PARAMS_RC_CBR_MINQP 

Constant bitrate mode with MinQP.

Definition at line 1448 of file nvmedia_common.h.

Video encoder codec type.

Enumerator
NVMEDIA_VIDEO_ENCODE_CODEC_H264 

H.264 codec.

NVMEDIA_VIDEO_ENCODE_CODEC_HEVC 
NVMEDIA_VIDEO_ENCODE_CODEC_VP9 
NVMEDIA_VIDEO_ENCODE_CODEC_VP8 

Definition at line 43 of file nvmedia_vep.h.

Function Documentation

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

Returns the encode status and number of bytes available for the next frame (if any).

The specific behavior depends on the specified NvMediaBlockingType. It is safe to call this function from a separate thread.

Parameters
[in]encoderA pointer to the encoder to use.
[out]numBytesAvailableA pointer to the number of bytes available in the next encoded frame. This is valid only when the return value is NVMEDIA_STATUS_OK.
[in]blockingTypeThe blocking types. The following are supported blocking types:
NVMEDIA_ENCODE_BLOCKING_TYPE_NEVER This type never blocks so "millisecondTimeout" is ignored. The following are possible return values: NVMEDIA_STATUS_OK NVMEDIA_STATUS_PENDING or NVMEDIA_STATUS_NONE_PENDING.

NVMEDIA_ENCODE_BLOCKING_TYPE_IF_PENDING Same as NVMEDIA_ENCODE_BLOCKING_TYPE_NEVER except that NVMEDIA_STATUS_PENDING will never be returned. If an encode is pending this function will block until the status changes to NVMEDIA_STATUS_OK or until the timeout has occurred. Possible return values: NVMEDIA_STATUS_OK, NVMEDIA_STATUS_NONE_PENDING, NVMEDIA_STATUS_TIMED_OUT.

NVMEDIA_ENCODE_BLOCKING_TYPE_ALWAYS This function will return only NVMEDIA_STATUS_OK or NVMEDIA_STATUS_TIMED_OUT. It will block until those conditions.
[in]millisecondTimeoutTimeout in milliseconds or NVMEDIA_VIDEO_ENCODER_TIMEOUT_INFINITE if a timeout is not desired.
Returns
NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameter is NULL.
NVMEDIA_STATUS_PENDING if an encode is in progress but not yet completed.
NVMEDIA_STATUS_NONE_PENDING if no encode is in progress.
NVMEDIA_STATUS_NONE_PENDING if no encode is in progress.
NVMEDIA_STATUS_TIMED_OUT if the operation timed out.
NvMediaVideoEncoder* NvMediaVideoEncoderCreate ( NvMediaDevice device,
NvMediaVideoEncodeType  codec,
void *  initParams,
NvMediaSurfaceType  inputFormat,
uint8_t  maxInputBuffering,
uint8_t  maxOutputBuffering,
NvMediaEncoderInstanceId  instanceId 
)

Creates an encoder object capable of turning a stream of surfaces of the "inputFormat" into a bitstream of the specified "codec".

Surfaces are feed to the encoder with NvMediaVideoEncoderFeedFrame and bitstream buffers are retrieved with NvMediaVideoEncoderGetBits.

Parameters
[in]deviceThe device this video encoder will use.
[in]codecCurrently only NVMEDIA_VIDEO_ENCODE_CODEC_H264 is supported.
[in]initParamsEncode parameters.
[in]inputFormatMust be obtained by /ref NvMediaSurfaceFormatGetType with:
NVM_SURF_FMT_SET_ATTR_YUV(attr, YUV, 420, SEMI_PLANAR, UINT, 8/10, BL)
NVM_SURF_FMT_SET_ATTR_YUV(attr, YUV, 444, SEMI_PLANAR, UINT, 8/10, BL)
[in]maxInputBufferingThis determines how many frames may be in the encode pipeline at any time. For example, if maxInputBuffering==1, NvMediaVideoEncoderFeedFrame will block until the previous encode has completed. If maxInputBuffering==2, NvMediaVideoEncoderFeedFrame will accept one frame while another is still being encoded by the hardware, but will block if two are still being encoded. maxInputBuffering will be clamped between 1 and 16. This field is ignored for YUV inputs which don't require a pre-processing pipeline before the encode hardware.
[in]maxOutputBufferingThis determines how many frames of encoded bitstream can be held by the NvMediaVideoEncoder before it must be retrieved using NvMediaVideoEncoderGetBits(). This number must be greater than or equal to maxInputBuffering and is clamped to between maxInputBuffering and 16. If maxOutputBuffering frames worth of encoded bitstream are yet unretrieved by NvMediaVideoEncoderGetBits NvMediaVideoEncoderFeedFrame will return NVMEDIA_STATUS_INSUFFICIENT_BUFFERING. One or more frames need to be retrieved with NvMediaVideoEncoderGetBits() before frame feeding can continue.
[in]instanceIdThe ID of the encoder engine instance. The following instances are supported:
NVMEDIA_ENCODER_INSTANCE_0
NVMEDIA_ENCODER_INSTANCE_1
NVMEDIA_ENCODER_INSTANCE_AUTO
Returns
NvMediaVideoEncoder The new video encoder's handle or NULL if unsuccessful.
void NvMediaVideoEncoderDestroy ( NvMediaVideoEncoder encoder)

Destroys an NvMediaEncoder object.

Parameters
[in]encoderA pointer to the encoder to destroy.
NvMediaStatus NvMediaVideoEncoderFeedFrame ( NvMediaVideoEncoder encoder,
NvMediaVideoSurface frame,
NvMediaRect sourceRect,
void *  picParams,
NvMediaEncoderInstanceId  instanceId 
)

Encodes the specified "frame".

NvMediaVideoEncoderFeedFrame returns NVMEDIA_STATUS_INSUFFICIENT_BUFFERING if NvMediaVideoEncoderGetBits has not been called frequently enough and the maximum internal bitstream buffering (determined by "maxOutputBuffering" passed to NvMediaVideoEncoderCreate) has been exhausted.

Parameters
[in]encoderA pointer to the encoder to use.
[in]frameThis must be of the same sourceType as the NvMediaEncoder. There is no limit on the size of this surface. The source rectangle specified by "sourceRect" will be scaled to the stream dimensions.
[in]sourceRectThis rectangle on the source will be scaled to the stream dimensions. If NULL, a rectangle the full size of the source surface is implied. The source may be flipped horizontally or vertically by swapping the left and right or top and bottom coordinates. This parameter is valid only for RGB type input surfaces.
[in]picParamsPicture parameters used for the frame.
[in]instanceIdThe ID of the encoder engine instance. The following instances are supported if NVMEDIA_ENCODER_INSTANCE_AUTO was used in NvMediaVideoEncoderCreate API, else this parameter is ignored:
NVMEDIA_ENCODER_INSTANCE_0
NVMEDIA_ENCODER_INSTANCE_1
Returns
NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameter is NULL.
NvMediaStatus NvMediaVideoEncoderGetBits ( NvMediaVideoEncoder encoder,
uint32_t *  numBytes,
void *  buffer 
)

NvMediaVideoEncoderGetBits returns a frame's worth of bitstream into the provided "buffer".

"numBytes" returns the size of this bitstream. It is safe to call this function from a separate thread. The return value and behavior is the same as that of NvMediaVideoEncoderBitsAvailable when called with NVMEDIA_ENCODE_BLOCKING_TYPE_NEVER except that when NVMEDIA_STATUS_OK is returned, the "buffer" will be filled in addition to the "numBytes".

Parameters
[in]encoderA pointer to the encoder to use.
[in]numBytesReturns the size of the filled bitstream.
[in]bufferThe buffer to be filled with the encoded data.
Returns
NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameter is NULL.
NVMEDIA_STATUS_PENDING if an encode is in progress but not yet completed.
NVMEDIA_STATUS_NONE_PENDING if no encode is in progress.
NvMediaStatus NvMediaVideoEncoderGetVersion ( NvMediaVersion version)

Gets the version information for the NvMedia Video Encoder library.

Parameters
[in]versionA pointer to a NvMediaVersion structure to be filled by the function.
Returns
NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if the pointer is invalid.
NvMediaStatus NvMediaVideoEncoderSetConfiguration ( NvMediaVideoEncoder encoder,
void *  configuration 
)

Sets the encoder configuration.

This configuration goes into effect only at the start of the next GOP.

Parameters
[in]encoderA pointer to the encoder to use.
[in]configurationConfiguration data.
Returns
NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameter is NULL.