NVIDIA DRIVE 5.0 Linux SDK API Reference

5.0.5.0 Release

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

Detailed Description

The NvMediaIEP object takes uncompressed image data and turns it into a codec specific bitstream.

Only H.264, H.265 and VP9 encoding is supported.

Data Structures

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

Macros

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

Enumerations

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

Functions

NvMediaStatus NvMediaIEPGetVersion (NvMediaVersion *version)
 Checks the version compatibility for the NvMedia IEP library. More...
 
NvMediaIEPNvMediaIEPCreate (NvMediaDevice *device, NvMediaIEPType encodeType, 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 NvMediaIEPDestroy (NvMediaIEP *encoder)
 Destroys an NvMedia image encoder. More...
 
NvMediaStatus NvMediaIEPFeedFrame (NvMediaIEP *encoder, NvMediaImage *frame, NvMediaRect *sourceRect, void *picParams, NvMediaEncoderInstanceId instanceId)
 Encodes the specified frame. More...
 
NvMediaStatus NvMediaIEPSetConfiguration (NvMediaIEP *encoder, void *configuration)
 Sets the encoder configuration. More...
 
NvMediaStatus NvMediaIEPGetBitsEx (NvMediaIEP *encoder, uint32_t *numBytes, uint32_t numBitstreamBuffers, NvMediaBitstreamBuffer *bitstreams, void *extradata)
 Returns the bitstream for a slice or frame. More...
 
NvMediaStatus NvMediaIEPBitsAvailable (NvMediaIEP *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...
 
NvMediaStatus NvMediaIEPGetAttribute (NvMediaIEP *encoder, NvMediaEncAttrType attrType, uint32_t attrSize, void *AttributeData)
 Gets the encoder attribute for the current encoding session. More...
 

Macro Definition Documentation

#define NVMEDIA_IEP_VERSION_MAJOR   2

Major Version number.

Definition at line 36 of file nvmedia_iep.h.

#define NVMEDIA_IEP_VERSION_MINOR   2

Minor Version number.

Definition at line 38 of file nvmedia_iep.h.

Enumeration Type Documentation

Image encode type.

Enumerator
NVMEDIA_IMAGE_ENCODE_H264 

H.264 encode.

NVMEDIA_IMAGE_ENCODE_HEVC 
NVMEDIA_IMAGE_ENCODE_VP9 
NVMEDIA_IMAGE_ENCODE_VP8 

Definition at line 43 of file nvmedia_iep.h.

Function Documentation

NvMediaStatus NvMediaIEPBitsAvailable ( NvMediaIEP 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]encoderThe encoder to use.
[in]numBytesAvailableThe number of bytes available in the next encoded frame. This is valid only when the return value is NVMEDIA_STATUS_OK.
[in]blockingTypeBlocking type. The following are supported blocking types:
NVMEDIA_ENCODE_BLOCKING_TYPE_NEVER This type never blocks so millisecondTimeout is ignored. The following are possible return values: NVMEDIA_STATUS_OK NVMEDIA_STATUS_PENDING or NVMEDIA_STATUS_NONE_PENDING.

NVMEDIA_ENCODE_BLOCKING_TYPE_IF_PENDING 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 returns only when NVMEDIA_STATUS_OK or NVMEDIA_STATUS_TIMED_OUT. It blocks until those conditions are satisfied.
[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.
NvMediaIEP* NvMediaIEPCreate ( NvMediaDevice device,
NvMediaIEPType  encodeType,
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 NvMediaIEPFeedFrame and bitstream buffers are retrieved with NvMediaIEPGetBitsEx.

Parameters
[in]deviceThe device this image encoder will use.
[in]encodeTypeThe encode type, which can be:
NVMEDIA_IMAGE_ENCODE_H264
NVMEDIA_IMAGE_ENCODE_HEVC
NVMEDIA_IMAGE_ENCODE_VP9
[in]initParamsThe encode parameters, which can be:
Supported encode parameter structures:
NvMediaEncodeInitializeParamsH264
NvMediaEncodeInitializeParamsH265
NvMediaEncodeInitializeParamsVP9
[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]maxInputBufferingMaximum number of frames in the encode pipeline at any time. For example, if maxInputBuffering==1, NvMediaIEPFeedFrame is blocked until the previous encode completes. If maxInputBuffering==2, NvMediaIEPFeedFrame accepts one frame while another is still being encoded by the hardware, but will block if two are still being encoded. maxInputBuffering is clamped between 1 and 16. This field is ignored for YUV inputs which do not require a pre-processing pipeline before the encode hardware.
[in]maxOutputBufferingMaximum number of frames of encoded bitstream that can be held by the NvMediaIEP before it must be retrieved using NvMediaIEPGetBitsEx(). 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 unretrived by NvMediaIEPGetBitsEx NvMediaIEPFeedFrame returns NVMEDIA_STATUS_INSUFFICIENT_BUFFERING. One or more frames must be retrived with NvMediaIEPGetBitsEx() 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
NvMediaIEP The new image encoder's handle or NULL if unsuccessful.
void NvMediaIEPDestroy ( NvMediaIEP encoder)

Destroys an NvMedia image encoder.

Parameters
[in]encoderThe encoder to destroy.
NvMediaStatus NvMediaIEPFeedFrame ( NvMediaIEP encoder,
NvMediaImage frame,
NvMediaRect sourceRect,
void *  picParams,
NvMediaEncoderInstanceId  instanceId 
)

Encodes the specified frame.

This function returns NVMEDIA_STATUS_INSUFFICIENT_BUFFERING if NvMediaIEPGetBitsEx has not been called frequently enough and the maximum internal bitstream buffering has been exhausted. The MaxOutputBuffering argument passed to NvMediaIEPCreate() specifies the maximum buffering.

Parameters
[in]encoderThe encoder to use.
[in]frameThe frame, which must be of the same sourceType as in the NvMediaIEP. There is no limit on the size of this surface. The source rectangle specified by sourceRect is scaled to the stream dimensions.
[in]sourceRectThe rectangle on the source, which is scaled to the stream dimensions. A value of NULL specifies a rectangle the full size of the source surface. The source can 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.
Supported picture parameter structures:
NvMediaEncodePicParamsH264
NvMediaEncodePicParamsH265
NvMediaEncodePicParamsVP9
[in]instanceIdThe ID of the encoder engine instance. The following instances are supported if NVMEDIA_ENCODER_INSTANCE_AUTO was used in NvMediaIEPCreate 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 NvMediaIEPGetAttribute ( NvMediaIEP encoder,
NvMediaEncAttrType  attrType,
uint32_t  attrSize,
void *  AttributeData 
)

Gets the encoder attribute for the current encoding session.

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

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

Parameters
[in]encoderA pointer to the encoder to use.
[in]attrTypeAttribute type as defined in NvMediaEncAttrType.
[in]attrSizeSize of the data structure associated with attribute.
[out]AttributeDataA pointer to data structure associated with the attribute.
Returns
NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameters are NULL.
NvMediaStatus NvMediaIEPGetBitsEx ( NvMediaIEP encoder,
uint32_t *  numBytes,
uint32_t  numBitstreamBuffers,
NvMediaBitstreamBuffer bitstreams,
void *  extradata 
)

Returns the bitstream for a slice or frame.

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

When slice Level output is enabled, this function must be called repeatedly. until the output extradata field bEndOfFrame is not set to NVMEDIA_TRUE. With every call to NvMediaIEPGetBitsEx, the function returns the bitstream for a slice or frame.

When slice level output is not enabled, the return value and behavior is the same as that of NvMediaIEPBitsAvailable() when called with NVMEDIA_ENCODE_BLOCKING_TYPE_NEVER, except that when NVMEDIA_STATUS_OK is returned, the buffer is filled in addition to the numBytes.

Parameters
[in]encoderA pointer to the encoder to use.
[out]numBytesSize of the filled bitstream.
[in]numBitstreamBuffersThe number of bitstreams.
[in,out]bitstreamsA pointer to the buffer to be filled with the encoded data.
[out]extradataOutput extradata required by application. The output extra data buffer to be filled by the encoder.
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 NvMediaIEPGetVersion ( NvMediaVersion version)

Checks the version compatibility for the NvMedia IEP library.

Parameters
[in]versionA pointer to a NvMediaVersion structure of the client.
Returns
NvMediaStatus The status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if the pointer is invalid.
NvMediaStatus NvMediaIEPSetConfiguration ( NvMediaIEP encoder,
void *  configuration 
)

Sets the encoder configuration.

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

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