nvmedia_parser.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: Copyright (c) 2021-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 * SPDX-License-Identifier: LicenseRef-NvidiaProprietary
 *
 * NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
 * property and proprietary rights in and to this material, related
 * documentation and any modifications thereto. Any use, reproduction,
 * disclosure or distribution of this material and related documentation
 * without an express license agreement from NVIDIA CORPORATION or
 * its affiliates is strictly prohibited.
 */
 
 
#ifndef NVMEDIA_PARSER_H
#define NVMEDIA_PARSER_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <stdint.h>
#include <stdbool.h>
 
#include "nvmedia_common_decode.h"
#include "nvmedia_core.h"
#include "nvmedia_drm.h"
 
// RVCT compiler doesn't allow anonymous structures or unions by default.
#if defined(__CC_ARM)
#pragma anon_unions
#endif
 
typedef enum {
    NvMVideoFormat_Component     = 0,
    NvMVideoFormat_PAL,
    NvMVideoFormat_NTSC,
    NvMVideoFormat_SECAM,
    NvMVideoFormat_MAC,
    NvMVideoFormat_Unspecified,
    NvMVideoFormat_Reserved6,
    NvMVideoFormat_Reserved7
} NvMediaVideoFormatType;
 
typedef enum {
    NvMColorRange_Reduced    = 0,
    NvMColorRange_Full
} NvMediaColorRangeType;
 
typedef enum {
    NvMColorPrimaries_Forbidden      = 0,
    NvMColorPrimaries_BT709,
    NvMColorPrimaries_Unspecified,
    NvMColorPrimaries_Reserved,
    NvMColorPrimaries_BT470M,
    NvMColorPrimaries_BT470BG,
    NvMColorPrimaries_SMPTE170M,
    NvMColorPrimaries_SMPTE240M,
    NvMColorPrimaries_GenericFilm,
    NvMColorPrimaries_BT2020
} NvMediaColorPrimariesType;
 
typedef enum {
    NvMMatrixCoeffs_Forbidden=0,
    NvMMatrixCoeffs_BT709,
    NvMMatrixCoeffs_Unspecified,
    NvMMatrixCoeffs_Reserved,
    NvMMatrixCoeffs_FCC,
    NvMMatrixCoeffs_BT470BG,
    NvMMatrixCoeffs_SMPTE170M,
    NvMMatrixCoeffs_SMPTE240M,
    NvMMatrixCoeffs_YCgCo,
    NvMMatrixCoeffs_BT2020_nc,
    NvMMatrixCoeffs_BT2020_c,
} NvMediaMatrixCoeffsType;
 
typedef enum {
    NvMTransferCharacteristics_Forbidden=0,
    NvMTransferCharacteristics_BT709,
    NvMTransferCharacteristics_Unspecified,
    NvMTransferCharacteristics_Reserved,
    NvMTransferCharacteristics_BT470M,
    NvMTransferCharacteristics_BT470BG,
    NvMTransferCharacteristics_SMPTE170M,
    NvMTransferCharacteristics_SMPTE240M,
    NvMTransferCharacteristics_Linear,
    NvMTransferCharacteristics_Log100,
    NvMTransferCharacteristics_Log316,
    NvMTransferCharacteristics_IEC61966_2_4,
    NvMTransferCharacteristics_BT1361,
    NvMTransferCharacteristics_IEC61966_2_1,
    NvMTransferCharacteristics_BT2020_1,
    NvMTransferCharacteristics_BT2020_2,
    NvMTransferCharacteristics_SMPTE2084,
    NvMTransferCharacteristics_ST418_1,
    NvMTransferCharacteristics_HLG
} NvMediaTransferCharacteristicsType;
 
typedef enum
{
    NvMParserDecodeMode_Normal = 0,
    NvMParserDecodeMode_SyncToKeyFrame
} NvMediaParserDecodeMode;
 
typedef enum
{
    NvMediaParserChromaFormat_400 = 0,
    NvMediaParserChromaFormat_420,
    NvMediaParserChromaFormat_422,
    NvMediaParserChromaFormat_444
} NvMediaParserChromaFormat;
 
typedef enum
{
    NvMParseAttr_h264DisableDpb = 100,
    NvMParseAttr_DecodeIDRFrameOnly,
    NvMParseAttr_DecodeMode,
    NvMParseAttr_DropMPEG2BFrames,
    NvMParseAttr_MaxDecFrameBuffering,
    NvMParseAttr_AbortDecodeOnParserError,
    NvMParseAttr_h265DisableDpb,
    NvMParseAttr_DpbSize_SetTo_MaxRefFrames,
    NvMParseAttr_GDREnabled,
 
    NvMParseAttr_FilterTimestamps = 200,
    NvMParseAttr_UseFrameTimingInfo,
    NvMParseAttr_SetFramerate,
    NvMParseAttr_SetDefaultFramerate,
 
    /* Security group */
 
    NvMParseAttr_SecureDecode = 300,
 
    NvMParseAttr_EnableVC1APInterlaced = 400,
    NvMParseAttr_SetMaxRes,
    /* Other: Generate slice offsets with CompletePicture mode. */
    NvMParseAttr_GenerateSliceOffsets,
    NvMParseAttr_ErrorStatusReporting,
    NvMParseAttr_GetBitstreamError,
    NvMParseAttr_PrevFrameLostFlag,
    NvMParseAttr_SliceLevelDecode,
    NvMParseAttr_av1SetOperatingPoint,
    NvMParseAttr_av1SetOutputAllLayers,
    NvMParseAttr_av1AnnexBDecode,
} NvMediaParserAttr;
 
typedef struct
{
    const uint8_t *pByteStream;
    uint32_t uDataLength;
    int64_t llPts;
    uint32_t bEOS;
    uint32_t bPTSValid;
    uint32_t bDiscontinuity;
    uint32_t bCompletePicture;
    uint32_t bCompleteSlice;
    uint32_t bDecodeNextSlice;
    uint32_t uRTP_NALUSizeFieldWidthInBytes;
} NvMediaBitStreamPkt;
 
typedef struct
{
    uint8_t uPresentFlag;
    uint8_t uIDRFrame;
    uint8_t uLTRefFrame;
    uint8_t uPredicted;
    uint32_t uPictureOrderCnt;
    uint32_t uFrameNum;
    uint32_t uLTRFrameIdx;
} NvMediaDecRefFrame;
 
typedef struct
{
    uint8_t uRefFrame;
    uint8_t uIDRFrame;
    uint8_t uLTRefFrame;
    uint8_t uReserve0;
    uint32_t uPictureOrderCnt;
    uint32_t uFrameNum;
    uint32_t uLTRFrameIdx;
} NvMediaDecCurrFrame;
 
typedef struct
{
    uint32_t poc_fn_bits;
    NvMediaDecCurrFrame currentFrame;
    uint32_t uActiveRefFrames;
    NvMediaDecRefFrame RPSList[16];
} NvMediaDPBInfo;
 
#define MAX_SEQ_HDR_LEN   512U
 
typedef struct
{
    /* Codec information */
 
    NvMediaVideoCodec eCodec;
 
    /* Frame information */
 
    double fFrameRate;
    uint32_t uDecodeBuffers;
    uint8_t bProgSeq;
    uint32_t uBitrate;
 
    /* Sequence information */
 
    uint32_t uSequenceHeaderSize;
    uint32_t uMaxBitstreamSize;
    uint8_t SequenceHeaderData[MAX_SEQ_HDR_LEN];
 
    /* Frame size information */
 
    uint16_t uCodedWidth;
    uint16_t uCodedHeight;
    uint16_t uDisplayWidth;
    uint16_t uDisplayHeight;
    uint16_t uActualWidth;
    uint16_t uActualHeight;
    uint16_t uDisplayLeftOffset;
    uint16_t uDisplayTopOffset;
 
    /* Aspect ratio information */
 
    uint16_t uDARWidth;
    uint16_t uDARHeight;
    uint16_t uSARWidth;
    uint16_t uSARHeight;
 
    /* Color information */
 
    NvMediaParserChromaFormat eChromaFormat;
    uint8_t uBitDepthLumaMinus8;
    uint8_t uBitDepthChromaMinus8;
    NvMediaVideoFormatType eVideoFormat;
    NvMediaColorRangeType eVideoFullRangeFlag;
    NvMediaColorPrimariesType eColorPrimaries;
    NvMediaTransferCharacteristicsType eTransferCharacteristics;
    NvMediaMatrixCoeffsType eMatrixCoefficients;
    uint32_t bMasteringDispDataPresent;
    NvMediaMasteringDisplayData MasteringDispData;
    uint32_t bContentLightLevelInfoPresent;
    NvMediaContentLightLevelInfo ContentLightLevelInfo;
    uint8_t uChromaLocTopField;
    uint8_t uChromaLocBottomField;
} NvMediaParserSeqInfo;
 
 
typedef struct
{
    uint16_t uDARWidth;
    uint16_t uDARHeight;
 
    uint16_t uDisplayLeftOffset;
    uint16_t uDisplayTopOffset;
 
    uint16_t uDisplayWidth;
    uint16_t uDisplayHeight;
 
    int64_t llFrameTime;
    int64_t llTimeBase;
 
    NvMediaRefSurface *pCurrPic;
 
    int32_t field_pic_flag;
    int32_t bottom_field_flag;
    int32_t second_field;
    int32_t progressive_frame;
    int32_t top_field_first;
    int32_t repeat_first_field;
    int32_t ref_pic_flag;
    int32_t intra_pic_flag;
    int32_t chroma_format;
    int32_t picture_order_count;
 
    uint32_t uBitstreamDataLen;
    uint8_t *pBitstreamData;
    uint32_t uNumSlices;
    uint32_t *pSliceDataOffsets;
    uint32_t nal_ref_idc;
    uint32_t bSliceDecode;
 
    union {
        NvMediaPictureInfoMPEG1Or2 mpeg2;
        NvMediaPictureInfoMPEG4Part2 mpeg4;
        NvMediaPictureInfoH264 h264;
        NvMediaPictureInfoVC1 vc1;
        NvMediaPictureInfoVP8 vp8;
        NvMediaPictureInfoH265 hevc;
        NvMediaPictureInfoVP9 vp9;
        /* picture parameter information for av1 @ref NvMediaPictureInfoAV1*/
        NvMediaPictureInfoAV1 av1;
    } CodecSpecificInfo;
 
    NvMediaSliceDecodeData SliceData;
 
    NvMediaAESMetaData AesMetaData;
    NvMediaEncryptParams encryptParams;
} NvMediaParserPictureData;
 
typedef int32_t (*pfnCbNvMediaBeginSequence)(void *, const NvMediaParserSeqInfo *);
typedef NvMediaStatus (*pfnCbNvMediaDecodePicture)(void *, NvMediaParserPictureData *);
typedef NvMediaStatus (*pfnCbNvMediaDisplayPicture)(void *, NvMediaRefSurface *, int64_t);
typedef void          (*pfnCbNvMediaUnhandledNALU)(void *, const uint8_t *, int32_t);
typedef NvMediaStatus (*pfnCbNvMediaAllocPictureBuffer)(void *, NvMediaRefSurface **);
typedef void          (*pfnCbNvMediaRelease)(void *, NvMediaRefSurface *);
typedef void          (*pfnCbNvMediaAddRef)(void *, NvMediaRefSurface *);
typedef NvMediaStatus (*pfnCbNvMediaCreateDecrypter)(void *, uint16_t width, uint16_t height);
typedef NvMediaStatus (*pfnCbNvMediaDecryptHdr)(void *, NvMediaParserPictureData *);
typedef NvMediaStatus (*pfnCbNvMediaSliceDecode)(void *, NvMediaSliceDecodeData *);
typedef NvMediaStatus (*pfnCbNvMediaGetClearHdr)(void *, NvMediaParserPictureData *);
typedef NvMediaStatus (*pfnCbNvMediaGetBackwardUpdates)(void *, NvMediaVP9BackwardUpdates *);
typedef void          (*pfnCbNvMediaGetDpbInfoForMetadata)(void *, NvMediaRefSurface *, NvMediaDPBInfo *);
typedef bool          (*pfncbNvMediaChooseOperatingPoint)(void *ptr, uint8_t numOperatingPoints);
typedef void          (*pfncbNvMediaCopyBuffer) (void *ptr, NvMediaRefSurface *destbuf, NvMediaRefSurface *srcbuf);
 
typedef struct
{
    pfnCbNvMediaBeginSequence          BeginSequence;
    pfnCbNvMediaDecodePicture          DecodePicture;
    pfnCbNvMediaDisplayPicture         DisplayPicture;
    pfnCbNvMediaUnhandledNALU          UnhandledNALU;
    pfnCbNvMediaAllocPictureBuffer     AllocPictureBuffer;
    pfnCbNvMediaRelease                Release;
    pfnCbNvMediaAddRef                 AddRef;
    pfnCbNvMediaCreateDecrypter        CreateDecrypter;
    pfnCbNvMediaDecryptHdr             DecryptHdr;
    pfnCbNvMediaSliceDecode          SliceDecode;
    pfnCbNvMediaGetClearHdr            GetClearHdr;
    pfnCbNvMediaGetBackwardUpdates     GetBackwardUpdates;
    pfnCbNvMediaGetDpbInfoForMetadata  GetDpbInfoForMetadata;
    pfncbNvMediaChooseOperatingPoint   ChooseOperatingPoint;
    pfncbNvMediaCopyBuffer             CopyBuffer;
    
} NvMediaParserClientCb;
 
typedef struct
{
    NvMediaParserClientCb *pClient;
    void *pClientCtx;
    uint32_t uReferenceClockRate;
    uint16_t uErrorThreshold;
    NvMediaVideoCodec eCodec;
    NvMediaParserSeqInfo *pExternalSeqInfo;
} NvMediaParserParams;
 
typedef void NvMediaParser;
 
NvMediaParser *
NvMediaParserCreate(
    const NvMediaParserParams *pParserParams
);
 
void
NvMediaParserDestroy(
    NvMediaParser *pParser
);
 
NvMediaStatus
NvMediaParserParse(
    const NvMediaParser *pParser,
    const NvMediaBitStreamPkt *pStreamPacket
);
 
NvMediaStatus
NvMediaParserScan(
    const NvMediaParser *pParser,
    const NvMediaBitStreamPkt *pStreamPacket
);
 
NvMediaStatus
NvMediaParserSetEncryption(
    const NvMediaParser *pParser,
    const NvMediaAESParams *pAesParams
);
 
void
NvMediaParserFlush(
    const NvMediaParser *pParser
);
 
NvMediaStatus
NvMediaParserSetAttribute(
    NvMediaParser *pParser,
    NvMediaParserAttr eAttributeType,
    uint32_t uAttributeSize,
    void *pAttribute
);
 
NvMediaStatus
NvMediaParserGetAttribute(
    const NvMediaParser *pParser,
    NvMediaParserAttr eAttributeType,
    uint32_t uAttributeSize,
    void *pAttribute
);
 
#ifdef __cplusplus
}     /* extern "C" */
#endif
 
#endif /* NVMEDIA_PARSER_H */