nvmedia_vpi.h

Go to the documentation of this file.

/*
 * Copyright (c) 2017-2020, NVIDIA CORPORATION. All rights reserved. All
 * information contained herein is proprietary and confidential to NVIDIA
 * Corporation.  Any use, reproduction, or disclosure without the written
 * permission of NVIDIA Corporation is prohibited.
 */
 
 
#ifndef NVMEDIA_VPI_H
#define NVMEDIA_VPI_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "nvmedia_core.h"
#include "nvmedia_image.h"
#include "nvmedia_array.h"
#include "nvmedia_image_pyramid.h"
#include "nvmedia_cvscratchpad.h"
#include "nvmedia_surface.h"
 
#define NVMEDIA_VPI_VERSION_MAJOR   (3u)
 
#define NVMEDIA_VPI_VERSION_MINOR   (3u)
 
#define NVMEDIA_VPI_MAX_QUEUED_TASKS (64u)
 
typedef struct NvMediaVPI NvMediaVPI;
 
typedef struct {
    float_t x;
    float_t y;
} NvMediaVPIPoint2Df;
 
typedef struct {
    uint32_t x;
    uint32_t y;
} NvMediaVPIPoint2DFrac;
 
typedef struct {
    float_t x;
    float_t y;
    float_t width;
    float_t height;
    uint8_t trackingStatus;
    uint8_t updateTemplate;
    uint8_t reserved1;
    uint8_t reserved2;
} NvMediaVPIAABB;
 
typedef struct {
    float_t mat3[3][3];
} NvMediaVPI2DTransform;
 
typedef struct {
    float_t deltaScale;
    float_t deltaX;
    float_t deltaY;
} NvMediaVPITranslationWithScale;
 
typedef struct {
    NvMediaVPI2DTransform transform;
    float_t width;
    float_t height;
    uint8_t trackingStatus;
    uint8_t templateStatus;
    uint8_t reserved1;
    uint8_t reserved2;
} NvMediaVPIBoundingBoxWithTransform;
 
NvMediaStatus
NvMediaVPIGetNumEngines(
    uint32_t *numEngines
);
 
NvMediaStatus
NvMediaVPIGetVersion(
    NvMediaVersion *version
);
 
NvMediaVPI *
NvMediaVPICreate(
    const uint32_t vpiId,
    const uint32_t maxQueuedTasks
);
 
NvMediaStatus
NvMediaVPIDestroy(
     NvMediaVPI *vpi
);
 
NvMediaStatus
NvMediaVPIFlush(
     NvMediaVPI *vpi
);
 
NvMediaStatus
NvMediaVPIImageRegister(
    const NvMediaVPI *vpi,
    const NvMediaImage *image
);
 
NvMediaStatus
NvMediaVPIImageUnregister(
    const NvMediaVPI *vpi,
    const NvMediaImage *image
);
 
NvMediaStatus
NvMediaVPIArrayRegister(
    const NvMediaVPI *vpi,
    NvMediaArray *array
);
 
NvMediaStatus
NvMediaVPIArrayUnregister(
    const NvMediaVPI *vpi,
    NvMediaArray *array
);
 
NvMediaStatus
NvMediaVPIScratchpadRegister(
    const NvMediaVPI *vpi,
    const NvMediaCVScratchpad *scratchpad
);
 
NvMediaStatus
NvMediaVPIScratchpadUnregister(
    const NvMediaVPI *vpi,
    const NvMediaCVScratchpad *scratchpad
);
 
NvMediaStatus
NvMediaVPIPyramidRegister(
    const NvMediaVPI *vpi,
    const NvMediaImagePyramid *pyramid
);
 
NvMediaStatus
NvMediaVPIPyramidUnregister(
    const NvMediaVPI *vpi,
    const NvMediaImagePyramid *pyramid
);
 
typedef struct NvMediaVPIProcessStereoDescriptor NvMediaVPIProcessStereoDescriptor;
 
typedef enum {
    NVMEDIA_VPI_STEREO_DISPARITY = 0,
    NVMEDIA_VPI_MV,
    NVMEDIA_VPI_MV_HINTS,
} NvMediaVPIOFSTOutputType;
 
typedef struct NvMediaVPIConvertMVDescriptor NvMediaVPIConvertMVDescriptor;
 
NvMediaVPIConvertMVDescriptor *
NvMediaVPICreateConvertMVDescriptor(
    const NvMediaVPI *vpi,
    const uint32_t width,
    const uint32_t height,
    const NvMediaSurfaceType type,
    const float_t strength,
    const float_t scale
);
 
NvMediaStatus
NvMediaVPIConvertMVDesc(
    NvMediaVPI *vpi,
    NvMediaVPIConvertMVDescriptor *descriptor,
    NvMediaImage *inputMVImage,
    const NvMediaImage *inputColor,
    NvMediaImage *output,
    const NvMediaVPIOFSTOutputType outputType
);
 
 
typedef struct NvMediaVPIStereoPostprocessDescriptor NvMediaVPIStereoPostprocessDescriptor;
 
NvMediaVPIStereoPostprocessDescriptor *
NvMediaVPICreateStereoPostprocessDescriptor(
    const NvMediaVPI *vpi,
    const uint32_t width,
    const uint32_t height,
    const float_t scale
);
 
typedef struct {
    uint16_t confidenceThresh;
    uint32_t windowDimension;
} NvMediaVPIStereoPostprocessParams;
 
NvMediaStatus
NvMediaVPIStereoPostprocessDesc(
    NvMediaVPI *vpi,
    NvMediaVPIStereoPostprocessDescriptor *descriptor,
    NvMediaVPIStereoPostprocessParams *params,
    NvMediaImage *disparityInput,
    NvMediaImage *confidenceInput,
    NvMediaImage *disparityOutput,
    NvMediaImage *confidenceOutput
);
 
typedef struct NvMediaVPIStereoPreprocessDescriptor NvMediaVPIStereoPreprocessDescriptor;
 
NvMediaVPIStereoPreprocessDescriptor *
NvMediaVPICreateStereoPreprocessDescriptor(
    const NvMediaVPI *vpi,
    const uint32_t width,
    const uint32_t height,
    const NvMediaVPIOFSTOutputType outputType
);
 
typedef struct {
    uint8_t numberOfHintsPerMB;
    uint8_t fractionalBits;
    uint8_t confidenceThresh;
    uint8_t disparityDiffToConfidenceShift;
} NvMediaVPIStereoPreprocessParams;
 
#define NVMEDIA_VPI_CONFIDENCE_TABLE_MIN_CAPACITY (128)
 
#define NVMEDIA_VPI_HINT_ARRAY_MIN_CAPACITY_BYTES (261376)
 
NvMediaStatus
NvMediaVPIStereoPreprocessDescEx(
    NvMediaVPI *vpi,
    NvMediaVPIStereoPreprocessDescriptor *descriptor,
    NvMediaVPIStereoPreprocessParams *params,
    NvMediaArray *confidenceTable,
    NvMediaImage *leftImage,
    NvMediaImage *rightImage,
    NvMediaImage *leftDisparity,
    NvMediaImage *rightDisparity,
    NvMediaImage *confidenceMap,
    NvMediaArray *hintsArray
);
 
typedef enum {
    /* Use a 2D grid of 8x8 cells with no minimal distance. */
    NVMEDIA_VPI_2D_GRID_8x8_CELL_NO_MIN_DISTANCE = 0
} NvMediaVPINonMaxSuppressionType;
 
typedef enum {
    NVMEDIA_VPI_HARRIS_FILTER_TYPE_DEFAULT = 0,
    NVMEDIA_VPI_HARRIS_FILTER_TYPE_USER
} NvMediaVPIHarrisGradientFilterType;
 
/*
 * \brief NvMediaVPIGetKeyPointsHarrisDescriptor.
 */
typedef struct NvMediaVPIGetKeyPointsHarrisDescriptor NvMediaVPIGetKeyPointsHarrisDescriptor;
 
NvMediaVPIGetKeyPointsHarrisDescriptor *
NvMediaVPICreateGetKeyPointsHarrisDescriptor(
    NvMediaVPI *vpi,
    const uint32_t width,
    const uint32_t height,
    const NvMediaVPINonMaxSuppressionType nonMaxSuppressionType);
 
typedef struct {
    const uint32_t gradientSize;
    const NvMediaVPIHarrisGradientFilterType gradientFilterType;
    const int16_t *horizontalFilterCoefficients;
    const uint16_t *verticalFilterCoefficients;
    const uint32_t blockSize;
    const float_t strengthThresh;
    const float_t sensitivity;
    const NvMediaVPINonMaxSuppressionType nonMaxSuppressionType;
    const float_t minDistance;
} NvMediaVPIGetKeyPointsHarrisParams;
 
NvMediaStatus
NvMediaVPIGetKeyPointsHarrisDesc(
    NvMediaVPI *vpi,
    NvMediaVPIGetKeyPointsHarrisDescriptor *descriptor,
    const NvMediaVPIGetKeyPointsHarrisParams *params,
    NvMediaImage *input,
    NvMediaImage *mask,
    NvMediaArray *trackedKeypoints,
    NvMediaArray *trackedScores,
    NvMediaArray *keypoints,
    NvMediaArray *scores
);
 
/*
 * \brief NvMediaVPIGetKeyPointsFastDescriptor.
 */
typedef struct NvMediaVPIGetKeyPointsFastDescriptor NvMediaVPIGetKeyPointsFastDescriptor;
 
NvMediaVPIGetKeyPointsFastDescriptor *
NvMediaVPICreateGetKeyPointsFastDescriptor(
    NvMediaVPI *vpi,
    const uint32_t width,
    const uint32_t height,
    const NvMediaSurfaceType type
);
 
NvMediaStatus
NvMediaVPIGetKeyPointsFastDesc(
    NvMediaVPI *vpi,
    NvMediaVPIGetKeyPointsFastDescriptor *descriptor,
    NvMediaImage *input,
    const uint32_t strengthThresh,
    const NvMediaBool nonmaxSupression,
    NvMediaArray *keypoints,
    NvMediaArray *scores
);
 
typedef enum {
    NVMEDIA_VPI_TERMINATION_CRITERION_ITERATIONS = 0,
    NVMEDIA_VPI_TERMINATION_CRITERION_EPSILON,
    NVMEDIA_VPI_TERMINATION_CRITERION_BOTH
} NvMediaVPITerminationCriterion;
 
typedef struct {
    const NvMediaVPITerminationCriterion termination;
    float_t epsilon;
    uint32_t numPoints;
    uint32_t numIterations;
    uint32_t windowDimension;
    int32_t calcError;
    uint32_t numLevels;
} NvMediaVPIGetSparseFlowPyrLKParams;
 
typedef struct NvMediaVPIGetSparseFlowPyrLKDescriptor NvMediaVPIGetSparseFlowPyrLKDescriptor;
 
NvMediaVPIGetSparseFlowPyrLKDescriptor *
NvMediaVPICreateGetSparseFlowPyrLKDescriptor(
    const NvMediaVPI *vpi,
    const NvMediaVPIGetSparseFlowPyrLKParams *params
);
 
NvMediaStatus NvMediaVPIGetSparseFlowPyrLKDesc(
    NvMediaVPI *vpi,
    NvMediaVPIGetSparseFlowPyrLKDescriptor *descriptor,
    const NvMediaVPIGetSparseFlowPyrLKParams *params,
    NvMediaImagePyramid *oldImages,
    NvMediaImagePyramid *newImages,
    NvMediaArray *oldPoints,
    NvMediaArray *newPoints,
    NvMediaArray *newStatus
);
 
typedef struct NvMediaVPIKLTDescriptor NvMediaVPIKLTDescriptor;
 
NvMediaVPIKLTDescriptor *
NvMediaVPICreateKLTDescriptor(
    const NvMediaVPI *vpi,
    const uint32_t width,
    const uint32_t height,
    const NvMediaSurfaceType type
);
 
typedef enum {
    NVMEDIA_VPI_KLT_INVERSE_COMPOSITIONAL = 0,
} NvMediaVPIKltTrackType;
 
typedef struct {
    uint32_t numIterationsScaling;
    uint32_t numIterationsTranslation;
    uint32_t numIterationsCoarse;
    uint32_t numIterationsFine;
    float_t maxPixelTolerance;
    float_t thresholdUpdate;
    float_t thresholdKill;
    float_t thresholdStop;
    float_t maxScaleChange;
    NvMediaVPIKltTrackType trackingType;
} NvMediaVPIKLTParams;
 
NvMediaStatus
NvMediaVPIKLTDesc(
    NvMediaVPI *vpi,
    NvMediaVPIKLTDescriptor *descriptor,
    const NvMediaVPIKLTParams *params,
    NvMediaImage *referenceImage,
    NvMediaImage *templateImage,
    NvMediaArray *inputBoxList,
    NvMediaArray *predictedBoxList,
    NvMediaArray *outputBoxList,
    NvMediaArray *estimationList
);
 
NvMediaStatus
NvMediaVPIGetScratchpadSize(
    const void *descriptor,
    uint32_t *scratchpadSizeBytes
);
 
NvMediaStatus
NvMediaVPIKLTFastDesc(
    NvMediaVPI *vpi,
    NvMediaVPIKLTDescriptor *descriptor,
    const NvMediaCVScratchpad *scratchpad,
    const NvMediaVPIKLTParams *params,
    NvMediaImage *referenceImage,
    NvMediaImage *templateImage,
    NvMediaArray *inputBoxList,
    NvMediaArray *predictedBoxList,
    NvMediaArray *outputBoxList,
    NvMediaArray *estimationList
);
 
NvMediaStatus
NvMediaVPIGetImagePyramid(
    NvMediaVPI *vpi,
    NvMediaImage *input,
    NvMediaImagePyramid *output
);
 
NvMediaStatus
NvMediaVPIConvolveImage(
    NvMediaVPI *vpi,
    NvMediaImage *input,
    const float_t *kernelData,
    const uint32_t kernelWidth,
    const uint32_t kernelHeight,
    NvMediaImage *output
);
 
NvMediaStatus
NvMediaVPIConvolveImageSeparable(
    NvMediaVPI *vpi,
    NvMediaImage *input,
    const float_t *kernelX,
    const uint32_t kernelXSize,
    const float_t *kernelY,
    const uint32_t kernelYSize,
    NvMediaImage *output
);
 
NvMediaStatus
NvMediaVPIFilterImageBox(
    NvMediaVPI *vpi,
    NvMediaImage *input,
    const uint32_t windowWidth,
    const uint32_t windowHeight,
    NvMediaImage *output
);
 
NvMediaStatus
NvMediaVPIDestroyDescriptor(
    const NvMediaVPI *vpi,
    void *descriptor
);
 
/*
 * \defgroup history_NvMediaVPI History
 * Provides change history for the NVIDIA VPI API.
 *
 * \section history_NvMediaVPI Version History
 *
 * <b> Version 1.0 </b> March 2, 2018
 * - Initial API definitions.
 *
 * <b> Version 2.0 </b> June 5, 2018
 * - Update Harris tracking API.
 *
 * <b> Version 2.1 </b> July 12, 2018
 * - Add KLT API, and array accessor API's.
 *
 * <b> Version 2.2 </b> July 12, 2018
 * - Add API to query number of available engines.
 *
 * <b> Version 2.3 </b> Sept 27, 2018
 * - Add KLT Fast API
 *
 * <b> Version 2.4 </b> Feb 21, 2019
 * - Add NvMediaVPIStereoPreprocessDescEx API
 *
 * <b> Version 2.5 </b> March 16, 2019
 * - Added required header include nvmedia_surface.h
 *
 * <b> Version 2.6 </b> March 22, 2019
 * - Unnecessary header include nvmedia_common.h has been removed
 *
 * <b> Version 3.0 </b> July 12, 2019
 * - Deprecate NvMediaVPICreateProcessStereoPairDescriptor, NvMediaVPIProcessStereoPairDesc,
 *   NvMediaVPIStereoPreprocessDesc, NvMediaVPIArrayCreate,
 *   NvMediaVPIArrayGetPoint2Df, NvMediaVPIArrayUpdatePoint2Df,
 *   NvMediaVPIArrayGetAABB, NvMediaVPIArrayUpdateAABB,
 *   NvMediaVPIArrayGetBoundingBoxWithTransform, NvMediaVPIArrayUpdateBoundingBoxWithTransform,
 *   NvMediaVPIArrayGetTranslationWithScale, NvMediaVPIArrayUpdateTranslationWithScale,
 *   NvMediaVPIArrayGet2DTransform, NvMediaVPIArrayUpdate2DTransform
 *
 * <b> Version 3.1 </b> July 26, 2019
 * - Update NVMEDIA_VPI_MAX_QUEUED_TASKS to be unsigned
 *
 * <b> Version 3.2 </b> April 13, 2020
 * - Replace all float instances with float_t
 * - Update NvMediaVPICreate, NvMediaVPIImageRegister, NvMediaVPIImageUnregister,
 *   NvMediaVPIArrayRegister, NvMediaVPIArrayUnregister, NvMediaVPIScratchpadRegister,
 *   NvMediaVPIScratchpadUnregister, NvMediaVPIPyramidRegister, NvMediaVPIPyramidUnregister,
 *   NvMediaVPICreateConvertMVDescriptor, NvMediaVPIConvertMVDesc,
 *   NvMediaVPICreateStereoPostprocessDescriptor, NvMediaVPICreateStereoPreprocessDescriptor,
 *   NvMediaVPIGetKeyPointsHarrisParams, NvMediaVPIGetSparseFlowPyrLKParams,
 *   NvMediaVPICreateGetSparseFlowPyrLKDescriptor, NvMediaVPICreateKLTDescriptor,
 *   NvMediaVPIGetScratchpadSize, NvMediaVPIGetScratchpadSize, NvMediaVPIKLTFastDesc,
 *   NvMediaVPIConvolveImage, NvMediaVPICreateConvolveImageSeparableDescriptor,
 *   NvMediaVPIConvolveImageSeparable, NvMediaVPIDestroyDescriptor function parameters to be
 *   const
 * - Fix minor MISRA violations
 *
 * <b> Version 3.3 </b> June 5, 2020
 * Remove NvMediaVPICreateConvolveImageSeparableDescriptor and NvMediaVPIConvolveImageSeparableDescriptor.
 *
 */
 
#ifdef __cplusplus
}
#endif
 
#endif /* NVMEDIA_VPI_H */