NVIDIA DeepStream SDK API Reference

4.0 Release

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups
Buffer Surface Management API

Detailed Description

Describes types and functions of the DeepStream buffer surface management API.

Data Structures

struct  NvBufSurfacePlaneParams
 Holds the planewise parameters of a buffer. More...
 
struct  NvBufSurfaceCreateParams
 Holds parameters required to allocate an NvBufSurface. More...
 
struct  NvBufSurfaceMappedAddr
 Holds pointers for a mapped buffer. More...
 
struct  NvBufSurfaceParams
 Holds information about a single buffer in a batch. More...
 
struct  NvBufSurface
 Holds information about batched buffers. More...
 

NvBufSurface types and functions.

This section describes types and functions of NvBufSurface application programming interface.

enum  NvBufSurfaceMemMapFlags {
  NVBUF_MAP_READ,
  NVBUF_MAP_WRITE,
  NVBUF_MAP_READ_WRITE
}
 Specifies mapping types for NvBufSurface. More...
 
enum  NvBufSurfaceColorFormat {
  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_LAST
}
 Specifies color formats for NvBufSurface. More...
 
enum  NvBufSurfaceLayout {
  NVBUF_LAYOUT_PITCH,
  NVBUF_LAYOUT_BLOCK_LINEAR
}
 Specifies layout formats for NvBufSurface video planes. More...
 
enum  NvBufSurfaceMemType {
  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
}
 Specifies memory types for NvBufSurface. More...
 
typedef struct
NvBufSurfacePlaneParams 
NvBufSurfacePlaneParams
 Holds the planewise parameters of a buffer. More...
 
typedef struct
NvBufSurfaceCreateParams 
NvBufSurfaceCreateParams
 Holds parameters required to allocate an NvBufSurface. More...
 
typedef struct
NvBufSurfaceMappedAddr 
NvBufSurfaceMappedAddr
 Holds pointers for a mapped buffer. More...
 
typedef struct NvBufSurfaceParams NvBufSurfaceParams
 Holds information about a single buffer in a batch. More...
 
typedef struct NvBufSurface NvBufSurface
 Holds information about batched buffers. More...
 
int NvBufSurfaceCreate (NvBufSurface **surf, uint32_t batchSize, NvBufSurfaceCreateParams *params)
 Allocates a batch of buffers. More...
 
int NvBufSurfaceDestroy (NvBufSurface *surf)
 Frees batched buffers previously allocated by NvBufSurfaceCreate(). More...
 
int NvBufSurfaceMap (NvBufSurface *surf, int index, int plane, NvBufSurfaceMemMapFlags type)
 Maps hardware batched buffers to the HOST or CPU address space. More...
 
int NvBufSurfaceUnMap (NvBufSurface *surf, int index, int plane)
 Unmaps previously mapped buffer(s). More...
 
int NvBufSurfaceCopy (NvBufSurface *srcSurf, NvBufSurface *dstSurf)
 Copies the content of source batched buffer(s) to destination batched buffer(s). More...
 
int NvBufSurfaceSyncForCpu (NvBufSurface *surf, int index, int plane)
 Syncs the hardware memory cache for the CPU. More...
 
int NvBufSurfaceSyncForDevice (NvBufSurface *surf, int index, int plane)
 Syncs the hardware memory cache for the device. More...
 
int NvBufSurfaceFromFd (int dmabuf_fd, void **buffer)
 Gets the NvBufSurface from the DMABUF FD. More...
 
int NvBufSurfaceMemSet (NvBufSurface *surf, int index, int plane, uint8_t value)
 Fills each byte of the buffer(s) in an NvBufSurface with a provided value. More...
 
int NvBufSurfaceMapEglImage (NvBufSurface *surf, int index)
 Creates an EGLImage from the memory of one or more NvBufSurface buffers. More...
 
int NvBufSurfaceUnMapEglImage (NvBufSurface *surf, int index)
 Destroys the previously created EGLImage object(s). More...
 
#define STRUCTURE_PADDING   4
 Defines the default padding length for reserved fields of structures. More...
 
#define NVBUF_MAX_PLANES   4
 Defines the maximum number of planes. More...
 

Macro Definition Documentation

#define NVBUF_MAX_PLANES   4

Defines the maximum number of planes.

Definition at line 58 of file nvbufsurface.h.

#define STRUCTURE_PADDING   4

Defines the default padding length for reserved fields of structures.

Definition at line 55 of file nvbufsurface.h.

Typedef Documentation

typedef struct NvBufSurface NvBufSurface

Holds information about batched buffers.

Holds parameters required to allocate an NvBufSurface.

Holds pointers for a mapped buffer.

Holds information about a single buffer in a batch.

Holds the planewise parameters of a buffer.

Enumeration Type Documentation

Specifies color formats for NvBufSurface.

Enumerator
NVBUF_COLOR_FORMAT_INVALID 

Specifies an invalid color format.

NVBUF_COLOR_FORMAT_GRAY8 

Specifies 8 bit GRAY scale - single plane.

NVBUF_COLOR_FORMAT_YUV420 

Specifies BT.601 colorspace - YUV420 multi-planar.

NVBUF_COLOR_FORMAT_YVU420 

Specifies BT.601 colorspace - YUV420 multi-planar.

NVBUF_COLOR_FORMAT_YUV420_ER 

Specifies BT.601 colorspace - YUV420 ER multi-planar.

NVBUF_COLOR_FORMAT_YVU420_ER 

Specifies BT.601 colorspace - YVU420 ER multi-planar.

NVBUF_COLOR_FORMAT_NV12 

Specifies BT.601 colorspace - Y/CbCr 4:2:0 multi-planar.

NVBUF_COLOR_FORMAT_NV12_ER 

Specifies BT.601 colorspace - Y/CbCr ER 4:2:0 multi-planar.

NVBUF_COLOR_FORMAT_NV21 

Specifies BT.601 colorspace - Y/CbCr 4:2:0 multi-planar.

NVBUF_COLOR_FORMAT_NV21_ER 

Specifies BT.601 colorspace - Y/CbCr ER 4:2:0 multi-planar.

NVBUF_COLOR_FORMAT_UYVY 

Specifies BT.601 colorspace - YUV 4:2:2 planar.

NVBUF_COLOR_FORMAT_UYVY_ER 

Specifies BT.601 colorspace - YUV ER 4:2:2 planar.

NVBUF_COLOR_FORMAT_VYUY 

Specifies BT.601 colorspace - YUV 4:2:2 planar.

NVBUF_COLOR_FORMAT_VYUY_ER 

Specifies BT.601 colorspace - YUV ER 4:2:2 planar.

NVBUF_COLOR_FORMAT_YUYV 

Specifies BT.601 colorspace - YUV 4:2:2 planar.

NVBUF_COLOR_FORMAT_YUYV_ER 

Specifies BT.601 colorspace - YUV ER 4:2:2 planar.

NVBUF_COLOR_FORMAT_YVYU 

Specifies BT.601 colorspace - YUV 4:2:2 planar.

NVBUF_COLOR_FORMAT_YVYU_ER 

Specifies BT.601 colorspace - YUV ER 4:2:2 planar.

NVBUF_COLOR_FORMAT_YUV444 

Specifies BT.601 colorspace - YUV444 multi-planar.

NVBUF_COLOR_FORMAT_RGBA 

Specifies RGBA-8-8-8-8 single plane.

NVBUF_COLOR_FORMAT_BGRA 

Specifies BGRA-8-8-8-8 single plane.

NVBUF_COLOR_FORMAT_ARGB 

Specifies ARGB-8-8-8-8 single plane.

NVBUF_COLOR_FORMAT_ABGR 

Specifies ABGR-8-8-8-8 single plane.

NVBUF_COLOR_FORMAT_RGBx 

Specifies RGBx-8-8-8-8 single plane.

NVBUF_COLOR_FORMAT_BGRx 

Specifies BGRx-8-8-8-8 single plane.

NVBUF_COLOR_FORMAT_xRGB 

Specifies xRGB-8-8-8-8 single plane.

NVBUF_COLOR_FORMAT_xBGR 

Specifies xBGR-8-8-8-8 single plane.

NVBUF_COLOR_FORMAT_RGB 

Specifies RGB-8-8-8 single plane.

NVBUF_COLOR_FORMAT_BGR 

Specifies BGR-8-8-8 single plane.

NVBUF_COLOR_FORMAT_NV12_10LE 

Specifies BT.601 colorspace - Y/CbCr 4:2:0 10-bit multi-planar.

NVBUF_COLOR_FORMAT_NV12_12LE 

Specifies BT.601 colorspace - Y/CbCr 4:2:0 12-bit multi-planar.

NVBUF_COLOR_FORMAT_YUV420_709 

Specifies BT.709 colorspace - YUV420 multi-planar.

NVBUF_COLOR_FORMAT_YUV420_709_ER 

Specifies BT.709 colorspace - YUV420 ER multi-planar.

NVBUF_COLOR_FORMAT_NV12_709 

Specifies BT.709 colorspace - Y/CbCr 4:2:0 multi-planar.

NVBUF_COLOR_FORMAT_NV12_709_ER 

Specifies BT.709 colorspace - Y/CbCr ER 4:2:0 multi-planar.

NVBUF_COLOR_FORMAT_YUV420_2020 

Specifies BT.2020 colorspace - YUV420 multi-planar.

NVBUF_COLOR_FORMAT_NV12_2020 

Specifies BT.2020 colorspace - Y/CbCr 4:2:0 multi-planar.

NVBUF_COLOR_FORMAT_LAST 

Definition at line 75 of file nvbufsurface.h.

Specifies layout formats for NvBufSurface video planes.

Enumerator
NVBUF_LAYOUT_PITCH 

Specifies pitch layout.

NVBUF_LAYOUT_BLOCK_LINEAR 

Specifies block linear layout.

Definition at line 158 of file nvbufsurface.h.

Specifies mapping types for NvBufSurface.

Enumerator
NVBUF_MAP_READ 

Specifies NvBufSurface mapping type "read.".

NVBUF_MAP_WRITE 

Specifies NvBufSurface mapping type "write.".

NVBUF_MAP_READ_WRITE 

Specifies NvBufSurface mapping type "read/write.".

Definition at line 63 of file nvbufsurface.h.

Specifies memory types for NvBufSurface.

Enumerator
NVBUF_MEM_DEFAULT 

Specifies the default memory type, i.e.

NVBUF_MEM_CUDA_DEVICE for dGPU, NVBUF_MEM_SURFACE_ARRAY for Jetson. Use NVBUF_MEM_DEFAULT to allocate whichever type of memory is appropriate for the platform.

NVBUF_MEM_CUDA_PINNED 

Specifies CUDA Host memory type.

NVBUF_MEM_CUDA_DEVICE 

Specifies CUDA Device memory type.

NVBUF_MEM_CUDA_UNIFIED 

Specifies CUDA Unified memory type.

NVBUF_MEM_SURFACE_ARRAY 

Specifies NVRM Surface Array type.

Valid only for Jetson.

NVBUF_MEM_HANDLE 

Specifies NVRM Handle type.

Valid only for Jetson.

NVBUF_MEM_SYSTEM 

Specifies memory allocated by malloc().

Definition at line 169 of file nvbufsurface.h.

Function Documentation

int NvBufSurfaceCopy ( NvBufSurface srcSurf,
NvBufSurface dstSurf 
)

Copies the content of source batched buffer(s) to destination batched buffer(s).

You can use this function to copy source buffer(s) of one memory type to destination buffer(s) of another memory type, e.g. CUDA host to CUDA device, malloc'ed memory to CUDA device, etc.

The source and destination NvBufSurface objects must have same buffer and batch size.

Parameters
[in]srcSurfA pointer to the source NvBufSurface structure.
[in]dstSurfA pointer to the destination NvBufSurface structure.
Returns
0 if successful, or -1 otherwise.
int NvBufSurfaceCreate ( NvBufSurface **  surf,
uint32_t  batchSize,
NvBufSurfaceCreateParams params 
)

Allocates a batch of buffers.

Allocates memory for batchSize buffers and returns a pointer to an allocated NvBufSurface. The params structure must have the allocation parameters of a single buffer. If params.size is set, a buffer of that size is allocated, and all other parameters (width, height, color format, etc.) are ignored.

Call NvBufSurfaceDestroy() to free resources allocated by this function.

Parameters
[out]surfAn indirect pointer to the allocated batched buffers.
[in]batchSizeBatch size of buffers.
[in]paramsA pointer to an NvBufSurfaceCreateParams structure.
Returns
0 if successful, or -1 otherwise.
int NvBufSurfaceDestroy ( NvBufSurface surf)

Frees batched buffers previously allocated by NvBufSurfaceCreate().

Parameters
[in]surfA pointer to an NvBufSurface to be freed.
Returns
0 if successful, or -1 otherwise.
int NvBufSurfaceFromFd ( int  dmabuf_fd,
void **  buffer 
)

Gets the NvBufSurface from the DMABUF FD.

Parameters
[in]dmabuf_fdDMABUF FD of the buffer.
[out]bufferA pointer to the NvBufSurface.
Returns
0 for success, or -1 otherwise.
int NvBufSurfaceMap ( NvBufSurface surf,
int  index,
int  plane,
NvBufSurfaceMemMapFlags  type 
)

Maps hardware batched buffers to the HOST or CPU address space.

Valid for NVBUF_MEM_CUDA_UNIFIED type memory for dGPU and NVBUF_MEM_SURFACE_ARRAY and NVBUF_MEM_HANDLE type memory for Jetson.

This function fills an array of pointers at surf->surfaceList->mappedAddr->addr. surf is a pointer to an NvBufSurface. surfaceList is a pointer to an NvBufSurfaceParams. mappedAddr is a pointer to an NvBufSurfaceMappedAddr. addr is declared as an array of pointers to void, and holds pointers to the buffers.

The client must call NvBufSurfaceSyncForCpu() with the virtual address populated by this function before accessing mapped memory in the CPU.

After memory mapping is complete, mapped memory modification must be coordinated between the CPU and the hardware device as follows:

  • CPU: If the CPU modifies mapped memory, the client must call NvBufSurfaceSyncForDevice() before any hardware device accesses the memory.
  • Hardware device: If a hardware device modifies mapped memory, the client must call NvBufSurfaceSyncForCpu() before the CPU accesses the memory.

Use NvBufSurfaceUnMap() to unmap buffer(s) and release any resource.

Parameters
[in,out]surfA pointer to an NvBufSurface structure. The function stores pointers to the buffers in a descendant of this structure; see the notes above.
[in]indexIndex of a buffer in the batch. -1 refers to all buffers in the batch.
[in]planeIndex of a plane in buffer. -1 refers to all planes in the buffer.
[in]typeA flag for mapping type.
Returns
0 if successful, or -1 otherwise.
int NvBufSurfaceMapEglImage ( NvBufSurface surf,
int  index 
)

Creates an EGLImage from the memory of one or more NvBufSurface buffers.

Only memory type NVBUF_MEM_SURFACE_ARRAY is supported.

This function returns the created EGLImage by storing its address at surf->surfaceList->mappedAddr->eglImage. (surf is a pointer to an NvBufSurface. surfaceList is a pointer to an NvBufSurfaceParams. mappedAddr is a pointer to an NvBufSurfaceMappedAddr. eglImage is declared as a pointer to void, and holds an EGLImageKHR.)

You can use this function in scenarios where a CUDA operation on Jetson hardware memory (identified by NVBUF_MEM_SURFACE_ARRAY) is required. The EGLImageKHR struct provided by this function can then be registered with CUDA for further CUDA operations.

Parameters
[in,out]surfA pointer to an NvBufSurface structure. The function stores a pointer to the created EGLImage in a descendant of this structure; see the notes above.
[in]indexIndex of a buffer in the batch. -1 specifies all buffers in the batch.
Returns
0 for success, or -1 otherwise.
int NvBufSurfaceMemSet ( NvBufSurface surf,
int  index,
int  plane,
uint8_t  value 
)

Fills each byte of the buffer(s) in an NvBufSurface with a provided value.

You can also use this function to reset the buffer(s) in the batch.

Parameters
[in]surfA pointer to the NvBufSurface structure.
[in]indexIndex of a buffer in the batch. -1 refers to all buffers in the batch.
[in]planeIndex of a plane in the buffer. -1 refers to all planes in the buffer.
[in]valueThe value to be used as fill.
Returns
0 if successful, or -1 otherwise.
int NvBufSurfaceSyncForCpu ( NvBufSurface surf,
int  index,
int  plane 
)

Syncs the hardware memory cache for the CPU.

Valid only for memory types NVBUF_MEM_SURFACE_ARRAY and NVBUF_MEM_HANDLE.

Parameters
[in]surfA pointer to an NvBufSurface structure.
[in]indexIndex of the buffer in the batch. -1 refers to all buffers in the batch.
[in]planeIndex of a plane in the buffer. -1 refers to all planes in the buffer.
Returns
0 if successful, or -1 otherwise.
int NvBufSurfaceSyncForDevice ( NvBufSurface surf,
int  index,
int  plane 
)

Syncs the hardware memory cache for the device.

Valid only for memory types NVBUF_MEM_SURFACE_ARRAY and NVBUF_MEM_HANDLE.

Parameters
[in]surfA pointer to an NvBufSurface structure.
[in]indexIndex of a buffer in the batch. -1 refers to all buffers in the batch.
[in]planeIndex of a plane in the buffer. -1 refers to all planes in the buffer.
Returns
0 if successful, or -1 otherwise.
int NvBufSurfaceUnMap ( NvBufSurface surf,
int  index,
int  plane 
)

Unmaps previously mapped buffer(s).

Parameters
[in]surfA pointer to an NvBufSurface structure.
[in]indexIndex of a buffer in the batch. -1 indicates all buffers in the batch.
[in]planeIndex of a plane in the buffer. -1 indicates all planes in the buffer.
Returns
0 if successful, or -1 otherwise.
int NvBufSurfaceUnMapEglImage ( NvBufSurface surf,
int  index 
)

Destroys the previously created EGLImage object(s).

Parameters
[in]surfA pointer to an NvBufSurface structure.
[in]indexThe index of a buffer in the batch. -1 specifies all buffers in the batch.
Returns
0 if successful, or -1 otherwise.