Image.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: Copyright (c) 2016-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 DW_IMAGE_IMAGE_H_
#define DW_IMAGE_IMAGE_H_
 
#include <dw/core/base/Config.h>
#include <dw/core/base/Exports.h>
#include <dw/core/base/Types.h>
#include <dw/core/base/Status.h>
#include <dw/core/context/Context.h>
 
#if (defined(__cplusplus) && (defined(LINUX) || defined(VIBRANTE)))
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wold-style-cast"
#endif
 
#if (defined(__cplusplus) && (defined(LINUX) || defined(VIBRANTE)))
#pragma GCC diagnostic pop
#endif
 
#include <sys/time.h>
 
#include <nvscibuf.h>
 
#ifdef DW_SDK_BUILD_PVA
#include <cupva_host_scheduling.h>
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef enum dwSyncType {
    DW_SYNC_TYPE_WAITER,   // The sync will wait for a signaler
    DW_SYNC_TYPE_SIGNALER, // The sync will notify the waiters
} dwSyncType;
 
#define DW_MAX_IMAGE_PLANES 3
#define DW_ISP_MAX_COLOR_COMPONENT (4U)
#define DW_MAX_NUM_TEMPERATURES 4
#define DW_IMAGE_NUM_SPLINE_COMPONENTS 18U
 
typedef enum dwImageType {
    DW_IMAGE_CPU     = 0,
    DW_IMAGE_CUDA    = 2,
    DW_IMAGE_NVMEDIA = 3,
    DW_IMAGE_GL = 0xFF
} dwImageType;
 
typedef struct dwImageObject* dwImageHandle_t;
typedef struct dwImageObject const* dwConstImageHandle_t;
 
typedef struct dwImageAllocationAttrList* dwImageAllocationAttrListHandle_t;
 
typedef struct dwImagePool
{
    dwImageHandle_t* images;
    size_t imageCount;
} dwImagePool;
 
typedef enum dwImageFormat {
    DW_IMAGE_FORMAT_UNKNOWN = 0,
 
    // Interleaved formats
    DW_IMAGE_FORMAT_R_INT16 = 900,
 
    DW_IMAGE_FORMAT_R_UINT8 = 1000,
    DW_IMAGE_FORMAT_R_UINT16,
    DW_IMAGE_FORMAT_R_UINT32,
    DW_IMAGE_FORMAT_R_FLOAT16,
    DW_IMAGE_FORMAT_R_FLOAT32,
 
    DW_IMAGE_FORMAT_RG_INT16,
    DW_IMAGE_FORMAT_RG_UINT8,
    DW_IMAGE_FORMAT_RG_FLOAT32,
 
    DW_IMAGE_FORMAT_RGB_UINT8,
    DW_IMAGE_FORMAT_RGB_UINT16,
    DW_IMAGE_FORMAT_RGB_FLOAT16,
    DW_IMAGE_FORMAT_RGB_FLOAT32,
 
    DW_IMAGE_FORMAT_RGBA_UINT8,
    DW_IMAGE_FORMAT_RGBA_UINT16,
    DW_IMAGE_FORMAT_RGBA_FLOAT16,
    DW_IMAGE_FORMAT_RGBA_FLOAT32,
 
    DW_IMAGE_FORMAT_RGBX_FLOAT16 = 1200,
 
    // interleaved YUV444 format
    DW_IMAGE_FORMAT_VUYX_UINT8,
    DW_IMAGE_FORMAT_VUYX_UINT16,
 
    // Planar formats
    DW_IMAGE_FORMAT_RGB_UINT8_PLANAR = 2000,
    DW_IMAGE_FORMAT_RGB_UINT16_PLANAR,
    DW_IMAGE_FORMAT_RGB_FLOAT16_PLANAR,
    DW_IMAGE_FORMAT_RGB_FLOAT32_PLANAR,
 
    DW_IMAGE_FORMAT_RCB_FLOAT16_PLANAR,
    DW_IMAGE_FORMAT_RCB_FLOAT32_PLANAR,
 
    DW_IMAGE_FORMAT_RCC_FLOAT16_PLANAR,
    DW_IMAGE_FORMAT_RCC_FLOAT32_PLANAR,
 
    DW_IMAGE_FORMAT_YUV420_UINT8_PLANAR = 3000,
    DW_IMAGE_FORMAT_YUV420_UINT8_SEMIPLANAR,
    DW_IMAGE_FORMAT_YUV420_UINT16_SEMIPLANAR,
    DW_IMAGE_FORMAT_YUV422_UINT8_SEMIPLANAR = 3100,
 
    // planar YUV 444
    DW_IMAGE_FORMAT_YUV_UINT8_PLANAR,
    DW_IMAGE_FORMAT_YUV_UINT16_PLANAR,
    DW_IMAGE_FORMAT_YUV422_UINT8_PACKED = 3200,
    DW_IMAGE_FORMAT_RAW_UINT16 = 4000,
    DW_IMAGE_FORMAT_RAW_FLOAT16,
 
} dwImageFormat;
 
typedef enum {
    DW_IMAGE_MEMORY_TYPE_DEFAULT = 0,
    DW_IMAGE_MEMORY_TYPE_PITCH = 1,
    DW_IMAGE_MEMORY_TYPE_BLOCK = 2,
 
} dwImageMemoryType;
 
typedef struct dwImageDataLines
{
    uint32_t bytesPerLine;
 
    dwVector2ui embeddedDataSize;
 
    uint8_t* topLineData;
    uint8_t* bottomLineData;
} dwImageDataLines;
 
typedef enum {
 
    DW_IMAGE_FLAGS_EMBEDDED_LINES = (1 << 2),
 
    DW_IMAGE_FLAGS_SENSOR_SETTINGS = (1 << 3),
 
    DW_IMAGE_FLAGS_FRAME_SEQUENCE_NUMBER = (1 << 4),
 
    DW_IMAGE_FLAGS_SYSMEM = (1 << 5),
 
    DW_IMAGE_FLAGS_HAS_RAW_ORDER_DESCRIPTOR = (1 << 6),
 
    DW_IMAGE_FLAGS_CONTROLINFO = (1 << 7),
 
    DW_IMAGE_FLAGS_LUMINANCE_CALIBRATED = (1 << 8),
 
    DW_IMAGE_FLAGS_TOTAL_WHITE_BALANCE_GAIN = (1 << 9),
 
    DW_IMAGE_FLAGS_GTM_SPLINE_INFO = (1 << 10),
 
    DW_IMAGE_FLAGS_SENSOR_TEMPERATURE = (1 << 11),
 
    DW_IMAGE_FLAGS_NVSCI_SURF_ATTR = (1 << 12),
 
    DW_IMAGE_FLAGS_MAPS_CUPVA = (1 << 13),
} dwImageMetaDataFlags;
 
typedef struct dwImageSplineControlPoint
{
    float32_t x;
    float32_t y;
    float64_t slope;
} dwImageSplineControlPoint;
 
// This is the max number of exposures supported currently
#define DW_DEVBLK_CDI_MAX_EXPOSURES 4
 
typedef struct dwExposureDuration
{
    float32_t data[DW_DEVBLK_CDI_MAX_EXPOSURES];
} dwExposureDuration;
 
typedef struct dwSensorTemperature
{
    uint8_t numTemperatures;
    float32_t dataCelsius[DW_MAX_NUM_TEMPERATURES];
} dwSensorTemperature;
 
#define DW_LUMINANCE_CALIB_MATRIX_SIZE 4
typedef struct dwImageSensorStatistics
{
    dwExposureDuration exposureDurationUs;
 
    float32_t exposureTime;
 
    float32_t analogGain;
 
    float32_t conversionGain;
 
    float32_t digitalGain;
 
    float32_t wbGain[4];
 
    float32_t alpha;
 
    float64_t luminanceCalibrationFactor DW_DEPRECATED("This structure variable is deprecated and will be removed in the next major release. Please use the new variable in luminanceCalibrationMatrix in this struct");
 
    float64_t luminanceCalibrationMatrix[DW_LUMINANCE_CALIB_MATRIX_SIZE][DW_LUMINANCE_CALIB_MATRIX_SIZE];
 
    float32_t autoAwbGain[DW_ISP_MAX_COLOR_COMPONENT];
 
    float32_t cct;
 
    float32_t brightnessKey;
 
    float32_t sceneDynamicRange;
 
    float32_t sceneBrightness;
 
    float32_t rawImageMidTone;
 
    dwSensorTemperature sensorTemperature;
 
    bool nightMode;
} dwImageSensorStatistics;
 
typedef struct dwImageRawProperties
{
    uint32_t msbPosition;
 
    uint32_t rawFormatDescriptor;
 
    uint32_t rawBitDataType;
 
    bool rawFormatRJ;
} dwImageRawProperties;
 
typedef struct dwImageTimestamps
{
    dwTime_t sofTimestampUs;
    dwTime_t moeTimestampUs;
    dwTime_t eofTimestampUs;
    dwTime_t tscEofTimestampUs;
    dwTime_t subExposureStartTimestampUs[DW_DEVBLK_CDI_MAX_EXPOSURES];
} dwImageTimestamps;
 
typedef struct dwImageMetaData
{
    uint32_t flags;
 
    dwImageTimestamps imageTimestamps;
 
    float32_t exposureTime
        DW_DEPRECATED("This structure variable is deprecated and will be removed in the next major release. Please use the new variable in sensorStatistics in this struct");
 
    float32_t analogGain
        DW_DEPRECATED("This structure variable is deprecated and will be removed in the next major release. Please use the new variable in sensorStatistics in this struct");
 
    float32_t conversionGain
        DW_DEPRECATED("This structure variable is deprecated and will be removed in the next major release. Please use the new variable in sensorStatistics in this struct");
 
    float32_t digitalGain
        DW_DEPRECATED("This structure variable is deprecated and will be removed in the next major release. Please use the new variable in sensorStatistics in this struct");
 
    float32_t wbGain[4] DW_DEPRECATED("This structure variable is deprecated and will be removed in the next major release. Please use the new variable in sensorStatistics in this struct");
 
    uint32_t msbPosition
        DW_DEPRECATED("This structure variable is deprecated and will be removed in the next major release. Please use the new variable in rawProperties in this struct");
 
    uint32_t frameSequenceNumber;
 
    dwImageDataLines dataLines;
 
    // Holds properties unique to raw images
    dwImageRawProperties rawProperties;
 
    // All paramters from here are read-only
 
    dwImageSensorStatistics sensorStatistics;
 
    dwImageSplineControlPoint gtmSplineControlPoint[DW_IMAGE_NUM_SPLINE_COMPONENTS];
 
    dwImageAllocationAttrListHandle_t allocAttrs;
 
    int32_t colorStdPriv;
} dwImageMetaData;
 
typedef struct dwImageProperties
{
    dwImageType type;
    uint32_t width;
    uint32_t height;
    dwImageFormat format;
    dwImageMetaData meta;
    dwImageMemoryType memoryLayout;
} dwImageProperties;
 
typedef struct dwImageCPU
{
    dwImageProperties prop;
    size_t pitch[DW_MAX_IMAGE_PLANES];
    void* data[DW_MAX_IMAGE_PLANES];
    dwTime_t timestamp_us;
} dwImageCPU;
 
typedef struct dwImageCUDA
{
    dwImageProperties prop;
    size_t pitch[DW_MAX_IMAGE_PLANES]; // pitch in bytes
    void* dptr[DW_MAX_IMAGE_PLANES];
    cudaArray_t array[DW_MAX_IMAGE_PLANES];
    dwTime_t timestamp_us;
} dwImageCUDA;
 
typedef struct dwImageNvMedia
{
    dwImageProperties prop;
 
    NvSciBufObj imgBuf;
    dwTime_t timestamp_us;
} dwImageNvMedia;
 
DW_API_PUBLIC
dwStatus dwImage_create(dwImageHandle_t* const image,
                        dwImageProperties properties,
                        dwContextHandle_t const ctx);
 
DW_API_PUBLIC
dwStatus dwImage_createAndBindBuffer(dwImageHandle_t* const image,
                                     dwImageProperties properties,
                                     void* const buffersIn[DW_MAX_IMAGE_PLANES],
                                     size_t const pitches[DW_MAX_IMAGE_PLANES], size_t const bufferCount,
                                     dwContextHandle_t const ctx);
 
DW_API_PUBLIC
dwStatus dwImage_createAndBindCUDAArray(dwImageHandle_t* const image,
                                        dwImageProperties properties,
                                        cudaArray_t const buffers[DW_MAX_IMAGE_PLANES], size_t const bufferCount,
                                        dwContextHandle_t const ctx);
 
DW_API_PUBLIC
dwStatus dwImage_destroy(dwImageHandle_t const image);
 
// specifiers
 
DW_API_PUBLIC
dwStatus dwImage_getProperties(dwImageProperties* const properties, dwConstImageHandle_t const image);
 
DW_API_PUBLIC
dwStatus dwImage_getTimestamp(dwTime_t* const timestamp, dwConstImageHandle_t const image);
 
DW_API_PUBLIC
dwStatus dwImage_setTimestamp(dwTime_t const timestamp, dwImageHandle_t const image);
 
DW_API_PUBLIC
dwStatus dwImage_getMetaData(dwImageMetaData* const metaData, dwConstImageHandle_t const image);
 
DW_API_PUBLIC
dwStatus dwImage_setMetaData(dwImageMetaData const* const metaData, dwImageHandle_t const image);
 
DW_API_PUBLIC
dwStatus dwImage_getCPU(dwImageCPU** const imageCPU, dwImageHandle_t const image);
 
DW_API_PUBLIC
dwStatus dwImage_getCUDA(dwImageCUDA** const imageCUDA, dwImageHandle_t const image);
 
DW_API_PUBLIC
dwStatus dwImage_getNvMedia(dwImageNvMedia** imageNvMedia, dwImageHandle_t image);
 
DW_API_PUBLIC
dwStatus dwImage_getPixelType(dwTrivialDataType* const type, dwImageFormat const format);
 
DW_API_PUBLIC
dwStatus dwImage_getPlaneCount(size_t* const planeCount, dwImageFormat const format);
 
DW_API_PUBLIC
dwStatus dwImage_copyConvert(dwImageHandle_t const output, dwConstImageHandle_t const input, dwContextHandle_t const context);
 
DW_API_PUBLIC
dwStatus dwImage_copyConvertAsync(dwImageHandle_t const output, dwConstImageHandle_t const input, cudaStream_t const stream, dwContextHandle_t const context);
 
DW_API_PUBLIC dwStatus dwImage_getDataLayout(size_t* const elementSize,
                                             size_t* const planeCount,
                                             uint32_t planeChannelCount[DW_MAX_IMAGE_PLANES],
                                             dwVector2ui planeSize[DW_MAX_IMAGE_PLANES],
                                             dwImageProperties const* const prop);
 
#ifdef DW_SDK_BUILD_PVA
 
DW_API_PUBLIC dwStatus dwImage_getCUPVA(void** ptr, dwImageHandle_t image);
#endif
 
DW_API_PUBLIC
dwStatus dwImage_createAndBindNvSciBuf(dwImageHandle_t* const image,
                                       dwImageProperties const* properties,
                                       NvSciBufObj nvscibufObj,
                                       dwContextHandle_t const ctx);
 
DW_API_PUBLIC
dwStatus dwImage_getNvSciBuf(NvSciBufObj* nvSciBufObj, dwImageHandle_t image);
 
#ifdef __cplusplus
}
#endif
 
#endif // DW_IMAGE_IMAGE_H_