includes/nvbufsurface.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: Copyright (c) 2019-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 * SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#ifndef NVBUFSURFACE_H_
#define NVBUFSURFACE_H_
 
#include <stdint.h>
#include <stdbool.h>
 
#ifdef __cplusplus
extern "C"
{
#endif
 
#define STRUCTURE_PADDING  4
 
#define NVBUF_MAX_PLANES   4
 
#define NVBUFSURFACE_CHROMA_SUBSAMPLING_HORIZ_DEFAULT 0
#define NVBUFSURFACE_CHROMA_SUBSAMPLING_VERT_DEFAULT 1
 
#define NVBUFSURFACE_CHROMA_SUBSAMPLING_PARAMS_DEFAULT \
  { \
    NVBUFSURFACE_CHROMA_SUBSAMPLING_HORIZ_DEFAULT, \
    NVBUFSURFACE_CHROMA_SUBSAMPLING_VERT_DEFAULT \
  }
 
typedef enum
{
  NVBUF_MAP_READ,       
  NVBUF_MAP_WRITE,      
  NVBUF_MAP_READ_WRITE, 
} NvBufSurfaceMemMapFlags;
 
typedef enum
{
  NvBufSurfaceTag_NONE            = 0x0,
  NvBufSurfaceTag_CAMERA          = 0x200,
  NvBufSurfaceTag_JPEG            = 0x1500,
  NvBufSurfaceTag_PROTECTED       = 0x1504,
  NvBufSurfaceTag_VIDEO_ENC       = 0x1200,
  NvBufSurfaceTag_VIDEO_DEC       = 0x1400,
  NvBufSurfaceTag_VIDEO_CONVERT   = 0xf01,
} NvBufSurfaceTag;
 
typedef enum
{
  NVBUF_COLOR_FORMAT_INVALID,
  NVBUF_COLOR_FORMAT_GRAY8,
  NVBUF_COLOR_FORMAT_YUV420,
  NVBUF_COLOR_FORMAT_YVU420,
  NVBUF_COLOR_FORMAT_YUV420_ER,
  NVBUF_COLOR_FORMAT_YVU420_ER,
  NVBUF_COLOR_FORMAT_NV12,
  NVBUF_COLOR_FORMAT_NV12_ER,
  NVBUF_COLOR_FORMAT_NV21,
  NVBUF_COLOR_FORMAT_NV21_ER,
  NVBUF_COLOR_FORMAT_UYVY,
  NVBUF_COLOR_FORMAT_UYVY_ER,
  NVBUF_COLOR_FORMAT_VYUY,
  NVBUF_COLOR_FORMAT_VYUY_ER,
  NVBUF_COLOR_FORMAT_YUYV,
  NVBUF_COLOR_FORMAT_YUYV_ER,
  NVBUF_COLOR_FORMAT_YVYU,
  NVBUF_COLOR_FORMAT_YVYU_ER,
  NVBUF_COLOR_FORMAT_YUV444,
  NVBUF_COLOR_FORMAT_RGBA,
  NVBUF_COLOR_FORMAT_BGRA,
  NVBUF_COLOR_FORMAT_ARGB,
  NVBUF_COLOR_FORMAT_ABGR,
  NVBUF_COLOR_FORMAT_RGBx,
  NVBUF_COLOR_FORMAT_BGRx,
  NVBUF_COLOR_FORMAT_xRGB,
  NVBUF_COLOR_FORMAT_xBGR,
  NVBUF_COLOR_FORMAT_RGB,
  NVBUF_COLOR_FORMAT_BGR,
  NVBUF_COLOR_FORMAT_NV12_10LE,
  NVBUF_COLOR_FORMAT_NV12_12LE,
  NVBUF_COLOR_FORMAT_YUV420_709,
  NVBUF_COLOR_FORMAT_YUV420_709_ER,
  NVBUF_COLOR_FORMAT_NV12_709,
  NVBUF_COLOR_FORMAT_NV12_709_ER,
  NVBUF_COLOR_FORMAT_YUV420_2020,
  NVBUF_COLOR_FORMAT_NV12_2020,
  NVBUF_COLOR_FORMAT_NV12_10LE_ER,
  NVBUF_COLOR_FORMAT_NV12_10LE_709,
  NVBUF_COLOR_FORMAT_NV12_10LE_709_ER,
  NVBUF_COLOR_FORMAT_NV12_10LE_2020,
  NVBUF_COLOR_FORMAT_SIGNED_R16G16,
  NVBUF_COLOR_FORMAT_R8_G8_B8,
  NVBUF_COLOR_FORMAT_B8_G8_R8,
  NVBUF_COLOR_FORMAT_R32F_G32F_B32F,
  NVBUF_COLOR_FORMAT_B32F_G32F_R32F,
  NVBUF_COLOR_FORMAT_YUV422,
  NVBUF_COLOR_FORMAT_NV21_10LE,
  NVBUF_COLOR_FORMAT_NV21_12LE,
  NVBUF_COLOR_FORMAT_NV12_12LE_2020,
  NVBUF_COLOR_FORMAT_NV16,
  NVBUF_COLOR_FORMAT_NV16_10LE,
  NVBUF_COLOR_FORMAT_NV24,
  NVBUF_COLOR_FORMAT_NV24_10LE,
  NVBUF_COLOR_FORMAT_NV16_ER,
  NVBUF_COLOR_FORMAT_NV24_ER,
  NVBUF_COLOR_FORMAT_NV16_709,
  NVBUF_COLOR_FORMAT_NV24_709,
  NVBUF_COLOR_FORMAT_NV16_709_ER,
  NVBUF_COLOR_FORMAT_NV24_709_ER,
  NVBUF_COLOR_FORMAT_NV24_10LE_709,
  NVBUF_COLOR_FORMAT_NV24_10LE_709_ER,
  NVBUF_COLOR_FORMAT_NV24_10LE_2020,
  NVBUF_COLOR_FORMAT_NV24_12LE_2020,
  NVBUF_COLOR_FORMAT_RGBA_10_10_10_2_709,
  NVBUF_COLOR_FORMAT_RGBA_10_10_10_2_2020,
  NVBUF_COLOR_FORMAT_BGRA_10_10_10_2_709,
  NVBUF_COLOR_FORMAT_BGRA_10_10_10_2_2020,
  NVBUF_COLOR_FORMAT_A32,
  NVBUF_COLOR_FORMAT_UYVP,
  NVBUF_COLOR_FORMAT_UYVP_ER,
  NVBUF_COLOR_FORMAT_YUV444_ER,
  NVBUF_COLOR_FORMAT_YUV444_709,
  NVBUF_COLOR_FORMAT_YUV444_709_ER,
  NVBUF_COLOR_FORMAT_YUV444_2020,
  NVBUF_COLOR_FORMAT_YUV444_10LE,
  NVBUF_COLOR_FORMAT_YUV444_10LE_ER,
  NVBUF_COLOR_FORMAT_YUV444_10LE_709,
  NVBUF_COLOR_FORMAT_YUV444_10LE_709_ER,
  NVBUF_COLOR_FORMAT_YUV444_10LE_2020,
  NVBUF_COLOR_FORMAT_YUV444_12LE,
  NVBUF_COLOR_FORMAT_YUV444_12LE_ER,
  NVBUF_COLOR_FORMAT_YUV444_12LE_709,
  NVBUF_COLOR_FORMAT_YUV444_12LE_709_ER,
  NVBUF_COLOR_FORMAT_YUV444_12LE_2020,
  NVBUF_COLOR_FORMAT_NV12_12LE_ER,
  NVBUF_COLOR_FORMAT_NV12_12LE_709,
  NVBUF_COLOR_FORMAT_NV12_12LE_709_ER,
  NVBUF_COLOR_FORMAT_GRAY8_ER,
  NVBUF_COLOR_FORMAT_UYVY_709,
  NVBUF_COLOR_FORMAT_UYVY_709_ER,
  NVBUF_COLOR_FORMAT_UYVY_2020,
  NVBUF_COLOR_FORMAT_GRAY16_LE,
  NVBUF_COLOR_FORMAT_BGRA64_LE,
  NVBUF_COLOR_FORMAT_NV16_2020,
  NVBUF_COLOR_FORMAT_NV16_10LE_ER,
  NVBUF_COLOR_FORMAT_NV16_10LE_709,
  NVBUF_COLOR_FORMAT_NV16_10LE_709_ER,
  NVBUF_COLOR_FORMAT_NV16_10LE_2020,
  NVBUF_COLOR_FORMAT_NV16_12LE,
  NVBUF_COLOR_FORMAT_NV16_12LE_ER,
  NVBUF_COLOR_FORMAT_NV16_12LE_709,
  NVBUF_COLOR_FORMAT_NV16_12LE_709_ER,
  NVBUF_COLOR_FORMAT_NV16_12LE_2020,
  NVBUF_COLOR_FORMAT_NV24_2020,
  NVBUF_COLOR_FORMAT_NV24_10LE_ER,
  NVBUF_COLOR_FORMAT_NV24_12LE,
  NVBUF_COLOR_FORMAT_NV24_12LE_ER,
  NVBUF_COLOR_FORMAT_NV24_12LE_709,
  NVBUF_COLOR_FORMAT_NV24_12LE_709_ER,
  NVBUF_COLOR_FORMAT_UYVP_709,
  NVBUF_COLOR_FORMAT_UYVP_709_ER,
  NVBUF_COLOR_FORMAT_UYVP_2020,
  NVBUF_COLOR_FORMAT_LAST
} NvBufSurfaceColorFormat;
 
typedef enum
{
  NVBUF_LAYOUT_PITCH,
  NVBUF_LAYOUT_BLOCK_LINEAR,
} NvBufSurfaceLayout;
 
typedef enum
{
  NVBUF_MEM_DEFAULT,
  NVBUF_MEM_CUDA_PINNED,
  NVBUF_MEM_CUDA_DEVICE,
  NVBUF_MEM_CUDA_UNIFIED,
  NVBUF_MEM_SURFACE_ARRAY,
  NVBUF_MEM_HANDLE,
  NVBUF_MEM_SYSTEM,
  NVBUF_MEM_CUDA_ARRAY,
} NvBufSurfaceMemType;
 
typedef enum
{
  NVBUF_DISPLAYSCANFORMAT_PROGRESSIVE,
  NVBUF_DISPLAYSCANFORMAT_INTERLACED,
} NvBufSurfaceDisplayScanFormat;
 
typedef struct NvBufSurfacePlaneParamsEx
{
  NvBufSurfaceDisplayScanFormat scanformat[NVBUF_MAX_PLANES];
  uint32_t secondfieldoffset[NVBUF_MAX_PLANES];
  uint32_t blockheightlog2[NVBUF_MAX_PLANES];
  uint32_t physicaladdress[NVBUF_MAX_PLANES];
  uint64_t flags[NVBUF_MAX_PLANES];
  uint64_t drmModifier[NVBUF_MAX_PLANES];
  void * _reserved[STRUCTURE_PADDING * NVBUF_MAX_PLANES];
} NvBufSurfacePlaneParamsEx;
 
typedef struct NvBufSurfacePlaneParams
{
  uint32_t num_planes;
  uint32_t width[NVBUF_MAX_PLANES];
  uint32_t height[NVBUF_MAX_PLANES];
  uint32_t pitch[NVBUF_MAX_PLANES];
  uint32_t offset[NVBUF_MAX_PLANES];
  uint32_t psize[NVBUF_MAX_PLANES];
  uint32_t bytesPerPix[NVBUF_MAX_PLANES];
  void * _reserved[STRUCTURE_PADDING * NVBUF_MAX_PLANES];
} NvBufSurfacePlaneParams;
 
 
typedef struct NvBufSurfaceChromaSubsamplingParams
{
  uint8_t chromaLocHoriz;
  uint8_t chromaLocVert;
  uint8_t _reserved[6];
} NvBufSurfaceChromaSubsamplingParams;
 
typedef struct NvBufSurfaceCreateParams {
  uint32_t gpuId;
  uint32_t width;
  uint32_t height;
  uint32_t size;
  bool isContiguous;
  NvBufSurfaceColorFormat colorFormat;
  NvBufSurfaceLayout layout;
  NvBufSurfaceMemType memType;
  void * _reserved[STRUCTURE_PADDING];
} NvBufSurfaceCreateParams;
 
typedef struct NvBufSurfaceAllocateParams {
  NvBufSurfaceCreateParams params;
  NvBufSurfaceDisplayScanFormat displayscanformat;
  NvBufSurfaceChromaSubsamplingParams chromaSubsampling;
  NvBufSurfaceTag memtag;
  bool disablePitchPadding;
  uint32_t _reservedParam;
  void * _reserved[STRUCTURE_PADDING];
} NvBufSurfaceAllocateParams;
 
typedef struct NvBufSurfaceMappedAddr {
  void * addr[NVBUF_MAX_PLANES];
  void *eglImage;
  void *nvmmPtr;
  void *cudaPtr;
  void * _reserved[STRUCTURE_PADDING];
} NvBufSurfaceMappedAddr;
 
typedef struct NvBufSurfaceParamsEx {
  int32_t startofvaliddata;
  int32_t sizeofvaliddatainbytes;
  NvBufSurfaceChromaSubsamplingParams chromaSubsampling;
  bool is_protected;
  NvBufSurfacePlaneParamsEx planeParamsex;
 
  void * _reserved[STRUCTURE_PADDING];
} NvBufSurfaceParamsEx;
 
typedef struct NvBufSurfaceCudaBuffer {
  void *basePtr;
  void *dataPtr;
  void *extMem;
  void *mipmap;
  uint8_t reserved[64];
} NvBufSurfaceCudaBuffer;
 
typedef struct NvBufSurfaceParams {
  uint32_t width;
  uint32_t height;
  uint32_t pitch;
  NvBufSurfaceColorFormat colorFormat;
  NvBufSurfaceLayout layout;
  uint64_t bufferDesc;
  uint32_t dataSize;
  void * dataPtr;
  NvBufSurfacePlaneParams planeParams;
  NvBufSurfaceMappedAddr mappedAddr;
  NvBufSurfaceParamsEx *paramex;
  NvBufSurfaceCudaBuffer *cudaBuffer;
 
  void * _reserved[STRUCTURE_PADDING];
} NvBufSurfaceParams;
 
typedef struct NvBufSurface {
  uint32_t gpuId;
  uint32_t batchSize;
  uint32_t numFilled;
  bool isContiguous;
  NvBufSurfaceMemType memType;
  NvBufSurfaceParams *surfaceList;
  bool isImportedBuf;
 
  void * _reserved[STRUCTURE_PADDING];
} NvBufSurface;
 
typedef struct NvBufSurfaceMapPlaneParams
{
  uint32_t width;
  uint32_t height;
  uint32_t pitch;
  uint32_t offset;
  uint32_t psize;
  uint32_t secondfieldoffset;
  uint32_t blockheightlog2;
  uint64_t flags;
  uint8_t reserved[64];
} NvBufSurfaceMapPlaneParams;
 
typedef struct NvBufSurfaceCudaIpcMemHandle_t
{
  char reserved[64];
} NvBufSurfaceCudaIpcMemHandle;
 
typedef struct NvBufSurfaceExtendedMapParams_t
{
  NvBufSurfaceCudaIpcMemHandle memHandle;
  void *reserved[64];
} NvBufSurfaceExtendedMapParams;
 
typedef struct NvBufSurfaceMapParams {
  uint32_t num_planes;
  uint32_t gpuId;
  uint64_t fd;
  uint32_t totalSize;
  NvBufSurfaceMemType memType;
  NvBufSurfaceLayout layout;
  NvBufSurfaceDisplayScanFormat scanformat;
  NvBufSurfaceColorFormat colorFormat;
  NvBufSurfaceChromaSubsamplingParams chromaSubsampling;
  NvBufSurfaceMapPlaneParams planes[NVBUF_MAX_PLANES];
  void *extendedMapParams;
  void *_reserved[STRUCTURE_PADDING];
} NvBufSurfaceMapParams;
 
typedef struct NvBufSurfaceNvmmBuffer {
  void *dataPtr;
  uint64_t bufferDesc;
  uint8_t reserved[64];
} NvBufSurfaceNvmmBuffer;
 
typedef enum {
  NVBUF_DRIVER_TYPE_UNKNOWN = 0,
  NVBUF_DRIVER_TYPE_NVGPU,
  NVBUF_DRIVER_TYPE_RM
} NvBufSurfaceDriverType;
 
typedef enum {
  NVBUF_PLATFORM_TYPE_UNKNOWN = 0,
  NVBUF_PLATFORM_TYPE_T186 = 1,
  NVBUF_PLATFORM_TYPE_T194 = 2,
  NVBUF_PLATFORM_TYPE_T210 = 3,
  NVBUF_PLATFORM_TYPE_T234 = 4,
  NVBUF_PLATFORM_TYPE_T256 = 5,
  NVBUF_PLATFORM_TYPE_T264 = 6,
} NvBufSurfacePlatformType;
 
typedef struct NvBufSurfaceDeviceInfo {
  NvBufSurfaceDriverType driverType;
  bool isVicPresent;
  bool isIntegratedGpu;
  bool reserved1;
  bool reserved2;
  NvBufSurfacePlatformType platformType;
  uint8_t reserved[60];
} NvBufSurfaceDeviceInfo;
 
typedef enum NvBufSurfaceGPUL2SyncCacheOps
{
    NVBUF_GPU_L2_CACHE_INVALIDATE            = 1,
    NVBUF_GPU_L2_CACHE_FLUSH                 = 2,
    NVBUF_GPU_L2_CACHE_FLUSH_INVALIDATE      = NVBUF_GPU_L2_CACHE_FLUSH | NVBUF_GPU_L2_CACHE_INVALIDATE
} NvBufSurfaceGPUL2SyncCacheOps;
 
typedef struct NvBufSurfaceGPUL2SyncParams
{
  NvBufSurfaceGPUL2SyncCacheOps type;
  void *reserved[STRUCTURE_PADDING];
} NvBufSurfaceGPUL2SyncParams;
 
int NvBufSurfaceCreate (NvBufSurface **surf, uint32_t batchSize,
                        NvBufSurfaceCreateParams *params);
 
int NvBufSurfaceAllocate (NvBufSurface **surf, uint32_t batchSize,
                          NvBufSurfaceAllocateParams *paramsext);
 
int NvBufSurfaceDestroy (NvBufSurface *surf);
 
int NvBufSurfaceMap (NvBufSurface *surf, int index, int plane, NvBufSurfaceMemMapFlags type);
 
int NvBufSurfaceUnMap (NvBufSurface *surf, int index, int plane);
 
int NvBufSurfaceCopy (NvBufSurface *srcSurf, NvBufSurface *dstSurf);
 
int NvBufSurface2Raw (NvBufSurface *Surf, unsigned int index, unsigned int plane, unsigned int out_width, unsigned int out_height, unsigned char *ptr);
 
int Raw2NvBufSurface (unsigned char *ptr, unsigned int index, unsigned int plane, unsigned int in_width, unsigned int in_height, NvBufSurface *Surf);
 
int NvBufSurfaceSyncForCpu (NvBufSurface *surf, int index, int plane);
 
int NvBufSurfaceSyncForDevice (NvBufSurface *surf, int index, int plane);
 
int NvBufSurfaceFromFd (int dmabuf_fd, void **buffer);
 
int NvBufSurfaceMemSet (NvBufSurface *surf, int index, int plane, uint8_t value);
 
int NvBufSurfaceMapEglImage (NvBufSurface *surf, int index);
 
int NvBufSurfaceUnMapEglImage (NvBufSurface *surf, int index);
 
int NvBufSurfaceImport (NvBufSurface **out_nvbuf_surf, const NvBufSurfaceMapParams *in_params);
 
int NvBufSurfaceGetMapParams (const NvBufSurface *surf, int index, NvBufSurfaceMapParams *params);
 
int NvBufSurfaceMapCudaBuffer (NvBufSurface *surf, int index);
 
int NvBufSurfaceUnMapCudaBuffer (NvBufSurface *surf, int index);
 
int NvBufSurfaceMapNvmmBuffer (NvBufSurface *surf, int index);
 
int NvBufSurfaceUnMapNvmmBuffer (NvBufSurface *surf, int index);
 
int NvBufSurfaceGetDeviceInfo (NvBufSurfaceDeviceInfo *info);
 
int NvBufSurfaceSyncGpuL2CacheForDevice (NvBufSurface *surf, int index, NvBufSurfaceGPUL2SyncParams *params);
 
#ifdef __cplusplus
}
#endif
#endif /* NVBUFSURFACE_H_ */