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
Video Decoder

Detailed Description

Defines and manages objects that decode video.

The NvMediaVideoDecoder object decodes compressed video data, writing the results to a NvMediaVideoSurface.

A specific NvMedia implementation may support decoding multiple types of compressed video data. However, NvMediaVideoDecoder objects are able to decode a specific type of compressed video data. This type must be specified during creation.

Data Structures

struct  NvMediaVideoDecodeFrameStatus
 To Get the decoding status from HW decoder. More...
 
struct  NvMediaMotionVectorMB_Metadata
 Per Macroblock header information. More...
 
struct  NvMediaMotionVectorFrameMetaData
 Motion vector array to get the required current frame stats. More...
 
struct  NvMediaVideoDecodeStats
 Frame stats structure to get get ring entry idx and motion vector dump. More...
 
struct  NvMediaVideoDecoder
 A handle representing a video decoder object. More...
 

Modules

 Decoder Creation Flag
 Defines decoder flag bit masks for constructing the decoder.
 

Macros

#define NVMEDIA_VIDEODEC_VERSION_MAJOR   1
 Major Version number. More...
 
#define NVMEDIA_VIDEODEC_VERSION_MINOR   6
 Minor Version number. More...
 

Enumerations

enum  NvMediaMacroBlockType {
  NVMEDIA_MBTYPE_B,
  NVMEDIA_MBTYPE_P_FORWARD,
  NVMEDIA_MBTYPE_P_BACKWARD,
  NVMEDIA_MBTYPE_I
}
 Macroblock types. More...
 
enum  NvMedia_MB_Type_enum {
  NVMEDIA_SKIP,
  NVMEDIA_P,
  NVMEDIA_B,
  NVMEDIA_I,
  NVMEDIA_UNKNOWN_TYPE
}
 MB types. More...
 
enum  NvMedia_MB_Part_enum {
  NVMEDIA_PART_16x16,
  NVMEDIA_PART_16x8,
  NVMEDIA_PART_8x16,
  NVMEDIA_PART_8x8,
  NVMEDIA_UNKNOWN_PART
}
 MB part. More...
 

Functions

NvMediaStatus NvMediaVideoDecoderGetVersion (NvMediaVersion *version)
 Gets the version information for the NvMedia Video Decoder library. More...
 
NvMediaVideoDecoderNvMediaVideoDecoderCreateEx (NvMediaDevice *device, NvMediaVideoCodec codec, uint16_t width, uint16_t height, uint16_t maxReferences, uint64_t maxBitstreamSize, uint8_t inputBuffering, uint32_t flags, NvMediaDecoderInstanceId instanceId)
 Creates a video decoder object. More...
 
void NvMediaVideoDecoderDestroy (NvMediaVideoDecoder *decoder)
 Destroys a video decoder object. More...
 
NvMediaStatus NvMediaVideoDecoderRenderEx (NvMediaVideoDecoder *decoder, NvMediaVideoSurface *target, NvMediaPictureInfo *pictureInfo, void *encryptParams, uint32_t numBitstreamBuffers, const NvMediaBitstreamBuffer *bitstreams, NvMediaVideoDecodeStats *FrameStatsDump, NvMediaDecoderInstanceId instanceId)
 Decodes a compressed field/frame and render the result into a NvMediaVideoSurface. More...
 
NvMediaStatus NvMediaVideoDecoderSliceDecode (NvMediaVideoDecoder *decoder, NvMediaVideoSurface *target, NvMediaSliceDecodeData *sliceDecData)
 This function is intended for use in low-latency decode mode. More...
 
NvMediaStatus NvMediaVideoDecoderGetFrameDecodeStatus (NvMediaVideoDecoder *decoder, uint32_t ringEntryIdx, NvMediaVideoDecodeFrameStatus *FrameStatus)
 Retrieves the HW decode status available. More...
 
NvMediaStatus NvMediaVideoDecoderGetBackwardUpdates (NvMediaVideoDecoder *decoder, void *backupdates)
 NvMediaVideoDecoder get backward updates counters for VP9 adaptive entropy contexts. More...
 

Macro Definition Documentation

#define NVMEDIA_VIDEODEC_VERSION_MAJOR   1

Major Version number.

Definition at line 42 of file nvmedia_viddec.h.

#define NVMEDIA_VIDEODEC_VERSION_MINOR   6

Minor Version number.

Definition at line 44 of file nvmedia_viddec.h.

Enumeration Type Documentation

MB part.

Enumerator
NVMEDIA_PART_16x16 

MB part 16x16.

NVMEDIA_PART_16x8 

MB part 16x8.

NVMEDIA_PART_8x16 

MB part 8x16.

NVMEDIA_PART_8x8 

MB part 8x8.

NVMEDIA_UNKNOWN_PART 

invalid option

Definition at line 97 of file nvmedia_viddec.h.

MB types.

Enumerator
NVMEDIA_SKIP 

MB type SKIP.

NVMEDIA_P 

MB type P.

NVMEDIA_B 

MB type B.

NVMEDIA_I 

MB type I.

NVMEDIA_UNKNOWN_TYPE 

invalid option

Definition at line 81 of file nvmedia_viddec.h.

Macroblock types.

Enumerator
NVMEDIA_MBTYPE_B 

macroblock type B

NVMEDIA_MBTYPE_P_FORWARD 

macroblock type P forward

NVMEDIA_MBTYPE_P_BACKWARD 

macroblock type P backward

NVMEDIA_MBTYPE_I 

macroblock type I

Definition at line 67 of file nvmedia_viddec.h.

Function Documentation

NvMediaVideoDecoder* NvMediaVideoDecoderCreateEx ( NvMediaDevice device,
NvMediaVideoCodec  codec,
uint16_t  width,
uint16_t  height,
uint16_t  maxReferences,
uint64_t  maxBitstreamSize,
uint8_t  inputBuffering,
uint32_t  flags,
NvMediaDecoderInstanceId  instanceId 
)

Creates a video decoder object.

Creates a NvMediaVideoDecoder object for the specified codec. Each decoder object may be accessed by a separate thread. The object must be destroyed with NvMediaVideoDecoderDestroy(). All surfaces used with the NvMediaVideoDecoder must be must obtained by /ref NvMediaSurfaceFormatGetType with:

Parameters
[in]deviceThe device this video decoder will use.
[in]codecCodec type. The following types are supported:
[in]widthDecoder width in luminance pixels.
[in]heightDecoder height in luminance pixels.
[in]maxReferencesThe maximum number of reference frames used. This limits internal allocations.
[in]maxBitstreamSizeThe maximum size for bitstream. This limits internal allocations.
[in]inputBufferingHow many frames can be in flight at any given time. If this value is 1, NvMediaVideoDecoderRenderEx() blocks until the previous frame has finished decoding. If this is 2, NvMediaVideoDecoderRenderEx blocks if two frames are pending but does not block if one is pending. This value is clamped internally to between 1 and 8.
[in]flagsSet the flags of the decoder. The following flags are supported:
NVMEDIA_VIDEO_DECODER_10BIT_DECODE
[in]instanceIdThe ID of the engine instance. The following instances are supported:
NVMEDIA_DECODER_INSTANCE_0
NVMEDIA_DECODER_INSTANCE_1
NVMEDIA_DECODER_INSTANCE_AUTO
Returns
NvMediaVideoDecoder The new video decoder's handle or NULL if unsuccessful.
void NvMediaVideoDecoderDestroy ( NvMediaVideoDecoder decoder)

Destroys a video decoder object.

Parameters
[in]decoderThe decoder to be destroyed.
NvMediaStatus NvMediaVideoDecoderGetBackwardUpdates ( NvMediaVideoDecoder decoder,
void *  backupdates 
)

NvMediaVideoDecoder get backward updates counters for VP9 adaptive entropy contexts.

Parameters
[in]decoderA pointer to the decoder object that performs the decoding operation.
[in]backupdatesA pointer to a structure that holds the backward update counters.
NvMediaStatus NvMediaVideoDecoderGetFrameDecodeStatus ( NvMediaVideoDecoder decoder,
uint32_t  ringEntryIdx,
NvMediaVideoDecodeFrameStatus FrameStatus 
)

Retrieves the HW decode status available.

This is to be used to get the decoding status. If application does not need decoding status then no need to call this function. This function should be called in decode order once decode is complete for target surface. This can be called from separate thread in decode order before the same index getting used. Syncronization can be acheived for NvMediaVideoDecoderRenderEx and NvMediaVideoDecoderGetFrameDecodeStatus using Semaphore. Semaphore can be signalled at the begining with inputBuffering times. Then client can wait on Semaphore before every NvMediaVideoDecoderRenderEx This Semaphore will be signalled from thread after calling NvMediaVideoDecoderGetFrameDecodeStatus for frame in decode order. For example: if inputBuffering is 3 when creating decoder using NvMediaVideoDecoderCreateEx then following sequence should be followed. NvMediaVideoDecoderRenderEx(DecodeOrder:0) : ringEntryIdx=0 NvMediaVideoDecoderRenderEx(DecodeOrder:1) : ringEntryIdx=1 NvMediaVideoDecoderRenderEx(DecodeOrder:2) : ringEntryIdx=2 NvMediaVideoDecoderGetFrameDecodeStatus(0) NvMediaVideoDecoderRenderEx() : ringEntryIdx=0 NvMediaVideoDecoderGetFrameDecodeStatus(1) NvMediaVideoDecoderRenderEx() : ringEntryIdx=1 NvMediaVideoDecoderGetFrameDecodeStatus(2) NvMediaVideoDecoderRenderEx() : ringEntryIdx=2 NvMediaVideoDecoderGetFrameDecodeStatus(0) Another example could be like this for above case NvMediaVideoDecoderRenderEx(DecodeOrder:0) : ringEntryIdx=0 NvMediaVideoDecoderRenderEx(DecodeOrder:1) : ringEntryIdx=1 NvMediaVideoDecoderGetFrameDecodeStatus(0) NvMediaVideoDecoderRenderEx(DecodeOrder:2) : ringEntryIdx=2 NvMediaVideoDecoderGetFrameDecodeStatus(1) NvMediaVideoDecoderRenderEx() : ringEntryIdx=0 NvMediaVideoDecoderRenderEx() : ringEntryIdx=1 NvMediaVideoDecoderGetFrameDecodeStatus(2) NvMediaVideoDecoderRenderEx() : ringEntryIdx=2 NvMediaVideoDecoderGetFrameDecodeStatus(0)

Parameters
[in]decoderThe decoder object that will perform the decode operation.
[in]ringEntryIdxThis is decoder order index. decode operation.
[out]FrameStatusA pointer to NvMediaVideoDecodeFrameStatus structure which will store current decoded frame status.
Returns
NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER
NvMediaStatus NvMediaVideoDecoderGetVersion ( NvMediaVersion version)

Gets the version information for the NvMedia Video Decoder 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 NvMediaVideoDecoderRenderEx ( NvMediaVideoDecoder decoder,
NvMediaVideoSurface target,
NvMediaPictureInfo pictureInfo,
void *  encryptParams,
uint32_t  numBitstreamBuffers,
const NvMediaBitstreamBuffer bitstreams,
NvMediaVideoDecodeStats FrameStatsDump,
NvMediaDecoderInstanceId  instanceId 
)

Decodes a compressed field/frame and render the result into a NvMediaVideoSurface.

Parameters
[in]decoderThe decoder object that will perform the decode operation.
[in]targetThe video surface to render to.
[in]pictureInfoA (pointer to a) structure containing information about the picture to be decoded. Note that the appropriate type of NvMediaPictureInfo* structure must be provided to match to profile that the decoder was created for.
[in]encryptParamsA (pointer to a) structure containing information about encryption parameter used to decrypt the video content on the fly.
[in]numBitstreamBuffersThe number of bitstream buffers containing compressed data for this picture.
[in]bitstreamsAn array of bitstream buffers.
[out]FrameStatsDumpA (pointer to a) structure containing frame coding specific informations. This includes frame type, motion vector dumps,macroblock types and other details.
Returns
NvMediaStatus The completion status of the operation.
Parameters
[in]instanceIdThe ID of the engine instance. The following instances are supported if NVMEDIA_DECODER_INSTANCE_AUTO was used in NvMediaVideoDecoderCreateEx API, else this parameter is ignored:
NVMEDIA_DECODER_INSTANCE_0
NVMEDIA_DECODER_INSTANCE_1 Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER
NvMediaStatus NvMediaVideoDecoderSliceDecode ( NvMediaVideoDecoder decoder,
NvMediaVideoSurface target,
NvMediaSliceDecodeData sliceDecData 
)

This function is intended for use in low-latency decode mode.

It is implemented only for H264 decoder. Error will be returned if it is called for any other codec.

Each set of buffers should contain exactly 1 slice data. For first slice of every frame, NvMediaVideoDecoderRenderEx() function should be called. NvMediaVideoDecoderSliceDecode() function should be called for all subsequent slices of the frame.

Note that the ucode expects next slice data to be available within certain time (= 100msec). If data is not available within this time, it is assumed that the data is lost and error-concealment may be performed on the remaining portion of the frame.

Parameters
[in]decoderThe decoder object that will perform the decode operation.
[in]targetThe video surface to render to.
[in]sliceDecDataSliceDecode data info.
Returns
NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER