nvmedia_surface.h

Go to the documentation of this file.

/*
 * Copyright (c) 2017-2022, 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_SURFACE_H
#define NVMEDIA_SURFACE_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "nvmedia_core.h"
 
#define NVMEDIA_SURFACE_VERSION_MAJOR   (1u)
 
#define NVMEDIA_SURFACE_VERSION_MINOR   (18u)
 
 
typedef enum {
    NVM_SURF_ATTR_SURF_TYPE = 0u,
    NVM_SURF_ATTR_LAYOUT,
    NVM_SURF_ATTR_DATA_TYPE,
    NVM_SURF_ATTR_MEMORY,
    NVM_SURF_ATTR_SUB_SAMPLING_TYPE,
    NVM_SURF_ATTR_BITS_PER_COMPONENT,
    NVM_SURF_ATTR_COMPONENT_ORDER,
    NVM_SURF_FMT_ATTR_MAX,
} NvMediaSurfFormatAttrType;
 
#define NVM_SURF_ATTR_SURF_TYPE_YUV                       (0x00000001u)
 
#define NVM_SURF_ATTR_SURF_TYPE_RGBA                      (0x00000002u)
 
#define NVM_SURF_ATTR_SURF_TYPE_RAW                       (0x00000003u)
 
#define NVM_SURF_ATTR_LAYOUT_BL                           (0x00000001u)
 
#define NVM_SURF_ATTR_LAYOUT_PL                           (0x00000002u)
 
#define NVM_SURF_ATTR_DATA_TYPE_UINT                      (0x00000001u)
 
#define NVM_SURF_ATTR_DATA_TYPE_INT                       (0x00000002u)
 
#define NVM_SURF_ATTR_DATA_TYPE_FLOAT                     (0x00000003u)
 
#define NVM_SURF_ATTR_DATA_TYPE_FLOATISP                  (0x00000004u)
 
#define NVM_SURF_ATTR_MEMORY_PLANAR                       (0x00000001u)
 
#define NVM_SURF_ATTR_MEMORY_SEMI_PLANAR                  (0x00000002u)
 
#define NVM_SURF_ATTR_MEMORY_PACKED                       (0x00000003u)
 
#define NVM_SURF_ATTR_SUB_SAMPLING_TYPE_420               (0x00000001u)
 
#define NVM_SURF_ATTR_SUB_SAMPLING_TYPE_422               (0x00000002u)
 
#define NVM_SURF_ATTR_SUB_SAMPLING_TYPE_444               (0x00000003u)
 
#define NVM_SURF_ATTR_SUB_SAMPLING_TYPE_422R              (0x00000004u)
 
#define NVM_SURF_ATTR_SUB_SAMPLING_TYPE_NONE              (0x00000000u)
 
#define NVM_SURF_ATTR_BITS_PER_COMPONENT_8                 (0x00000001u)
 
#define NVM_SURF_ATTR_BITS_PER_COMPONENT_10                (0x00000002u)
 
#define NVM_SURF_ATTR_BITS_PER_COMPONENT_12                (0x00000003u)
 
#define NVM_SURF_ATTR_BITS_PER_COMPONENT_14                (0x00000004u)
 
#define NVM_SURF_ATTR_BITS_PER_COMPONENT_16                (0x00000005u)
 
#define NVM_SURF_ATTR_BITS_PER_COMPONENT_32                (0x00000006u)
 
#define NVM_SURF_ATTR_BITS_PER_COMPONENT_LAYOUT_16_8_8     (0x00000007u)
 
#define NVM_SURF_ATTR_BITS_PER_COMPONENT_LAYOUT_10_8_8     (0x00000008u)
 
#define NVM_SURF_ATTR_BITS_PER_COMPONENT_LAYOUT_2_10_10_10 (0x00000009u)
 
#define NVM_SURF_ATTR_BITS_PER_COMPONENT_20                (0x0000000Au)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_LUMA                (0x00000001u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_YUV                 (0x00000002u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_YVU                 (0x00000003u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_YUYV                (0x00000004u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_YVYU                (0x00000005u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_VYUY                (0x00000006u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_UYVY                (0x00000007u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_XUYV                (0x00000008u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_XYUV                (0x00000009u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_VUYX                (0x0000000Au)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_ALPHA               (0x00000011u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_RGBA                (0x00000012u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_ARGB                (0x00000013u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_BGRA                (0x00000014u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_RG                  (0x00000015u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_RGGB                (0x00000021u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_BGGR                (0x00000022u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_GRBG                (0x00000023u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_GBRG                (0x00000024u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_RCCB                (0x00000025u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_BCCR                (0x00000026u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_CRBC                (0x00000027u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_CBRC                (0x00000028u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_RCCC                (0x00000029u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_CCCR                (0x0000002Au)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_CRCC                (0x0000002Bu)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_CCRC                (0x0000002Cu)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_CCCC                (0x0000002Du)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_BGGI_RGGI                (0x0000002Eu)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_GBIG_GRIG                (0x0000002Fu)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_GIBG_GIRG                (0x00000030u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_IGGB_IGGR                (0x00000031u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_RGGI_BGGI                (0x00000032u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_GRIG_GBIG                (0x00000033u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_GIRG_GIBG                (0x00000034u)
 
#define NVM_SURF_ATTR_COMPONENT_ORDER_IGGR_IGGB                (0x00000035u)
 
typedef struct {
    NvMediaSurfFormatAttrType type;
    uint32_t value;
} NvMediaSurfFormatAttr;
 
#define NVM_SURF_FMT_DEFINE_ATTR(x)                                                   \
    NvMediaSurfFormatAttr x[7] = {                                                    \
        {                                                                             \
            .type = NVM_SURF_ATTR_SURF_TYPE,                                          \
            .value = 0u,                                                               \
        },                                                                            \
        {                                                                             \
            .type = NVM_SURF_ATTR_LAYOUT,                                             \
            .value = 0u,                                                               \
        },                                                                            \
        {                                                                             \
            .type = NVM_SURF_ATTR_DATA_TYPE,                                          \
            .value = 0u,                                                               \
        },                                                                            \
        {                                                                             \
            .type = NVM_SURF_ATTR_MEMORY,                                             \
            .value = 0u,                                                               \
        },                                                                            \
        {                                                                             \
            .type = NVM_SURF_ATTR_SUB_SAMPLING_TYPE,                                  \
            .value = 0u,                                                               \
        },                                                                            \
        {                                                                             \
            .type = NVM_SURF_ATTR_BITS_PER_COMPONENT,                                 \
            .value = 0u,                                                               \
        },                                                                            \
        {                                                                             \
            .type = NVM_SURF_ATTR_COMPONENT_ORDER,                                    \
            .value = 0u,                                                               \
        },                                                                            \
    };                                                                                \
 
 
#define NVM_SURF_FMT_SET_ATTR_YUV(attr, order, samplingtype, memory, datatype, bpc, layout)       \
{                                                                                                 \
    attr[0].type = NVM_SURF_ATTR_SURF_TYPE;                                                       \
    attr[0].value = NVM_SURF_ATTR_SURF_TYPE_YUV;                                                  \
                                                                                                  \
    attr[1].type = NVM_SURF_ATTR_LAYOUT;                                                          \
    attr[1].value = NVM_SURF_ATTR_LAYOUT_##layout;                                                \
                                                                                                  \
    attr[2].type = NVM_SURF_ATTR_DATA_TYPE;                                                       \
    attr[2].value = NVM_SURF_ATTR_DATA_TYPE_##datatype;                                           \
                                                                                                  \
    attr[3].type = NVM_SURF_ATTR_MEMORY;                                                          \
    attr[3].value = NVM_SURF_ATTR_MEMORY_##memory;                                                \
                                                                                                  \
    attr[4].type = NVM_SURF_ATTR_SUB_SAMPLING_TYPE;                                               \
    attr[4].value = NVM_SURF_ATTR_SUB_SAMPLING_TYPE_##samplingtype;                               \
                                                                                                  \
    attr[5].type = NVM_SURF_ATTR_BITS_PER_COMPONENT;                                              \
    attr[5].value = NVM_SURF_ATTR_BITS_PER_COMPONENT_##bpc;                                       \
                                                                                                  \
    attr[6].type = NVM_SURF_ATTR_COMPONENT_ORDER;                                                 \
    attr[6].value = NVM_SURF_ATTR_COMPONENT_ORDER_##order;                                        \
}
 
#define NVM_SURF_FMT_SET_ATTR_RGBA(attr, order, datatype, bpc, layout)                            \
{                                                                                                 \
    attr[0].type = NVM_SURF_ATTR_SURF_TYPE;                                                       \
    attr[0].value = NVM_SURF_ATTR_SURF_TYPE_RGBA;                                                 \
                                                                                                  \
    attr[1].type = NVM_SURF_ATTR_LAYOUT;                                                          \
    attr[1].value = NVM_SURF_ATTR_LAYOUT_##layout;                                                \
                                                                                                  \
    attr[2].type = NVM_SURF_ATTR_DATA_TYPE;                                                       \
    attr[2].value = NVM_SURF_ATTR_DATA_TYPE_##datatype;                                           \
                                                                                                  \
    attr[3].type = NVM_SURF_ATTR_MEMORY;                                                          \
    attr[3].value = NVM_SURF_ATTR_MEMORY_PACKED;                                                  \
                                                                                                  \
    attr[4].type = NVM_SURF_ATTR_SUB_SAMPLING_TYPE;                                               \
    attr[4].value = NVM_SURF_ATTR_SUB_SAMPLING_TYPE_NONE;                                         \
                                                                                                  \
    attr[5].type = NVM_SURF_ATTR_BITS_PER_COMPONENT;                                              \
    attr[5].value = NVM_SURF_ATTR_BITS_PER_COMPONENT_##bpc;                                       \
                                                                                                  \
    attr[6].type = NVM_SURF_ATTR_COMPONENT_ORDER;                                                 \
    attr[6].value = NVM_SURF_ATTR_COMPONENT_ORDER_##order;                                        \
}
 
#define NVM_SURF_FMT_SET_ATTR_RAW(attr, order, datatype, bpc, layout)                             \
{                                                                                                 \
    attr[0].type = NVM_SURF_ATTR_SURF_TYPE;                                                       \
    attr[0].value = NVM_SURF_ATTR_SURF_TYPE_RAW;                                                  \
                                                                                                  \
    attr[1].type = NVM_SURF_ATTR_LAYOUT;                                                          \
    attr[1].value = NVM_SURF_ATTR_LAYOUT_##layout;                                                \
                                                                                                  \
    attr[2].type = NVM_SURF_ATTR_DATA_TYPE;                                                       \
    attr[2].value = NVM_SURF_ATTR_DATA_TYPE_##datatype;                                           \
                                                                                                  \
    attr[3].type = NVM_SURF_ATTR_MEMORY;                                                          \
    attr[3].value = NVM_SURF_ATTR_MEMORY_PACKED;                                                  \
                                                                                                  \
    attr[4].type = NVM_SURF_ATTR_SUB_SAMPLING_TYPE;                                               \
    attr[4].value = NVM_SURF_ATTR_SUB_SAMPLING_TYPE_NONE;                                         \
                                                                                                  \
    attr[5].type = NVM_SURF_ATTR_BITS_PER_COMPONENT;                                              \
    attr[5].value = NVM_SURF_ATTR_BITS_PER_COMPONENT_##bpc;                                       \
                                                                                                  \
    attr[6].type = NVM_SURF_ATTR_COMPONENT_ORDER;                                                 \
    attr[6].value = NVM_SURF_ATTR_COMPONENT_ORDER_##order;                                        \
}
 
typedef enum {
    NVM_SURF_ATTR_WIDTH = 0u,
    NVM_SURF_ATTR_HEIGHT,
    NVM_SURF_ATTR_EMB_LINES_TOP,
    NVM_SURF_ATTR_EMB_LINES_BOTTOM,
    NVM_SURF_ATTR_CPU_ACCESS,
    NVM_SURF_ATTR_ALLOC_TYPE,
    NVM_SURF_ATTR_PEER_VM_ID,
    NVM_SURF_ATTR_SCAN_TYPE,
    NVM_SURF_ATTR_COLOR_STD_TYPE,
    NVM_SURF_ALLOC_ATTR_MAX,
} NvMediaSurfAllocAttrType;
 
#define NVM_SURF_ATTR_MIN_WIDTH (16U)
 
#define NVM_SURF_ATTR_MAX_WIDTH (16384U)
 
#define NVM_SURF_ATTR_MIN_HEIGHT (16U)
 
#define NVM_SURF_ATTR_MAX_HEIGHT (16384U)
 
#define NVM_SURF_ATTR_MIN_EMB_LINES_TOP (0U)
 
#define NVM_SURF_ATTR_MAX_EMB_LINES_TOP (128U)
 
#define NVM_SURF_ATTR_MIN_EMB_LINES_BOTTOM (0U)
 
#define NVM_SURF_ATTR_MAX_EMB_LINES_BOTTOM (128U)
 
#define NVM_SURF_ATTR_CPU_ACCESS_UNCACHED                 (0x00000001u)
 
#define NVM_SURF_ATTR_CPU_ACCESS_CACHED                   (0x00000002u)
 
#define NVM_SURF_ATTR_CPU_ACCESS_UNMAPPED                 (0x00000003u)
 
#define NVM_SURF_ATTR_ALLOC_DEFAULT                       (0x00000000u)
 
#define NVM_SURF_ATTR_ALLOC_ISOCHRONOUS                   (0x00000001u)
 
#define NVM_SURF_ATTR_ALLOC_SECURED                       (0x00000002u)
 
#define NVM_SURF_ATTR_ALLOC_DEFAULT                       (0x00000000u)
 
#define NVM_SURF_ATTR_SCAN_PROGRESSIVE                    (0x00000001u)
 
#if !defined(NV_IS_SAFETY) || (!NV_IS_SAFETY)
 
#define NVM_SURF_ATTR_SCAN_INTERLACED                     (0x00000002u)
#endif
 
#define NVM_SURF_ATTR_COLOR_STD_SRGB                      (0x00000001u)
 
#define NVM_SURF_ATTR_COLOR_STD_REC601_SR                 (0x00000002u)
 
#define NVM_SURF_ATTR_COLOR_STD_REC601_ER                 (0x00000003u)
 
#define NVM_SURF_ATTR_COLOR_STD_REC709_SR                 (0x00000004u)
 
#define NVM_SURF_ATTR_COLOR_STD_REC709_ER                 (0x00000005u)
 
#define NVM_SURF_ATTR_COLOR_STD_REC2020_RGB               (0x00000006u)
 
#define NVM_SURF_ATTR_COLOR_STD_REC2020_SR                (0x00000007u)
 
#define NVM_SURF_ATTR_COLOR_STD_REC2020_ER                (0x00000008u)
 
#define NVM_SURF_ATTR_COLOR_STD_YcCbcCrc_SR               (0x00000009u)
 
#define NVM_SURF_ATTR_COLOR_STD_YcCbcCrc_ER               (0x0000000Au)
 
#define NVM_SURF_ATTR_COLOR_STD_SENSOR_RGBA               (0x0000000Bu)
 
#define NVM_SURF_ATTR_COLOR_STD_REC2020PQ_ER              (0x0000000Cu)
 
typedef struct {
    NvMediaSurfAllocAttrType type;
    uint32_t value;
} NvMediaSurfAllocAttr;
 
#define NvMediaSurfaceType    uint32_t
 
#define NvMediaSurfaceType_Unsupported                                (99999u)
 
#if (NV_IS_SAFETY == 0)
 
#define NvMediaSurfaceType_Video_420                                  (1000u)
#define NvMediaSurfaceType_Video_420_10bit                            (1001u)
#define NvMediaSurfaceType_Video_420_12bit                            (1002u)
 
#define NvMediaSurfaceType_Video_422                                  (1003u)
#define NvMediaSurfaceType_Video_422_10bit                            (1004u)
#define NvMediaSurfaceType_Video_422_12bit                            (1005u)
 
#define NvMediaSurfaceType_Video_444                                  (1006u)
#define NvMediaSurfaceType_Video_444_10bit                            (1007u)
#define NvMediaSurfaceType_Video_444_12bit                            (1008u)
 
#define NvMediaSurfaceType_VideoCapture_422                           (1009u)
 
#define NvMediaSurfaceType_VideoCapture_YUYV_422                      (1010u)
 
#define NvMediaSurfaceType_R8G8B8A8                                   (1011u)
 
#define NvMediaSurfaceType_R8G8B8A8_BottomOrigin                      (1012u)
 
#define NvMediaSurfaceType_Image_Monochrome                           (1013u)
 
#define NvMediaSurfaceType_Image_YUV_420                              (1014u)
 
#define NvMediaSurfaceType_Image_YUV_422                              (1015u)
 
#define NvMediaSurfaceType_Image_YUV_444                              (1016u)
 
#define NvMediaSurfaceType_Image_YUYV_422                             (1017u)
 
#define NvMediaSurfaceType_Image_RGBA                                 (1018u)
 
#define NvMediaSurfaceType_Image_RAW                                  (1019u)
 
#define NvMediaSurfaceType_Image_V16Y16U16X16                         (1020u)
 
#define NvMediaSurfaceType_Image_Y16                                  (1021u)
 
#define NvMediaSurfaceType_Image_X2U10Y10V10                          (1022u)
 
#define NvMediaSurfaceType_Image_Y10U8V8_420                          (1023u)
 
#define NvMediaSurfaceType_Image_Y10                                  (1024u)
 
#define NvMediaSurfaceType_A8                                         (1025u)
 
#define NvMediaSurfaceType_YV12 NvMediaSurfaceType_Video_420
 
#define NvMediaSurfaceType_YV16 NvMediaSurfaceType_Video_422
 
#define NvMediaSurfaceType_YV24 NvMediaSurfaceType_Video_444
 
#define NvMediaSurfaceType_YV16x2 NvMediaSurfaceType_VideoCapture_422
#endif
 
NvMediaSurfaceType
NvMediaSurfaceFormatGetType(
    const NvMediaSurfFormatAttr *attrs,
    uint32_t numAttrs
);
 
NvMediaStatus
NvMediaSurfaceFormatGetAttrs(
    NvMediaSurfaceType type,
    NvMediaSurfFormatAttr *attrs,
    uint32_t numAttrs
);
 
NvMediaStatus
NvMediaSurfaceGetVersion(
    NvMediaVersion *version
);
 
/*
 * \defgroup history_nvmedia_surface History
 * Provides change history for the NvMedia Surface API.
 *
 * \section history_nvmedia_surface Version History
 *
 * <b> Version 1.0 </b> March 1, 2017
 * - Initial release
 *
 *
 * <b> Version 1.1 </b> April 24, 2017
 * - Added NVM_SURF_ATTR_COMPONENT_ORDER_XYUV and
 *   NVM_SURF_ATTR_COMPONENT_ORDER_RG component order flags
 *
 * <b> Version 1.2 </b> May 18, 2017
 * - Added NVM_SURF_ATTR_COLOR_STD_TYPE and
 *   NVM_SURF_ATTR_COLOR_STD flags
 *
 * <b> Version 1.3 </b> June 08, 2017
 * - Removed NvMediaSurfaceType_Image_NonColor_S16_XY and
 *   NvMediaSurfaceType_Image_NonColor_S16_X surface types
 *
 * <b> Version 1.4 </b> June 12, 2017
 * - Added NVM_SURF_ATTR_COMPONENT_ORDER_VUYX flag
 *
 * <b> Version 1.5 </b> October 09, 2017
 * - Added NVM_SURF_ATTR_COLOR_STD_SENSOR_RGBA and
 *   NVM_SURF_ATTR_COLOR_STD_REC2020PQ_ER flags
 *
 * <b> Version 1.6 </b> October 31, 2017
 * - Added NVM_SURF_ATTR_DATA_TYPE_FLOATISP type
 *
 * <b> Version 1.7 </b> November 07, 2017
 * - Added NVM_SURF_ATTR_BITS_PER_COMPONENT_20
 *
 * <b> Version 1.8 </b> June 04, 2018
 * - Added NVM_SURF_ATTR_COMPONENT_ORDER_CCCC component order
 *
 * <b> Version 1.9 </b> July 10, 2018
 * - Added NvMediaSurfaceGetVersion API
 *
 * <b> Version 1.10 </b> December 11, 2018
 * - Fixed MISRA-C rule 10.4, 20.7 and 21.1 violations
 *   resulting from this header.
 *
 * <b> Version 1.11 </b> December 03, 2019
 * - Updated the comments to deprecate old NvMediaSurfaceType_ macros
 *
 * <b> Version 1.12 </b> March 22, 2019
 * - Fixed MISRA-C rule 8.13 violations
 *   resulting from this header.
 *
 * <b> Version 1.13 </b> November 27, 2019
 * - Fixed MISRA-C rule 4.6 violations by changing unsigned int
 *   arguments and struct members to uint32_t type.
 *
 * <b> Version 1.14 </b> December 4, 2019
 * - Fixed MISRA-C rule 2.5 violations by defining non-safety
 *   surface types under non-safety conditional compilation macro.
 *
 * <b> Version 1.15 </b> September 2, 2020
 * - Added 8 component flags for RAW RGB-IR surface type
 *
 * <b> Version 1.16 </b> February 25, 2021
 * - Added array size for NvMediaSurfFormatAttr
 *
 * <b> Version 1.17 </b> August 30, 2021
 * - Update doxygen comments for all APIs to have Thread safety information and API Group information
 *
 * <b> Version 1.18 </b> September 13, 2021
 * - SWUD Update for 5.2 Release.
 */
#ifdef __cplusplus
}     /* extern "C" */
#endif
 
#endif /* NVMEDIA_SURFACE_H */