NvDsBufSurface API

group ds_aaa

Defines types and functions of NvBufSurface application programming interface.

Defines

STRUCTURE_PADDING

Defines the default padding length for reserved fields of structures.

NVBUF_MAX_PLANES

Defines the maximum number of planes.

Typedefs

typedef struct NvBufSurfacePlaneParams NvBufSurfacePlaneParams

Holds the planewise parameters of a buffer.

typedef struct NvBufSurfaceCreateParams NvBufSurfaceCreateParams

Holds parameters required to allocate an NvBufSurface.

typedef struct NvBufSurfaceMappedAddr NvBufSurfaceMappedAddr

Holds pointers for a mapped buffer.

typedef struct NvBufSurfaceParams NvBufSurfaceParams

Holds information about a single buffer in a batch.

typedef struct NvBufSurface NvBufSurface

Holds information about batched buffers.

Enums

enum NvBufSurfaceMemMapFlags

Specifies mapping types for NvBufSurface.

Values:

enumerator NVBUF_MAP_READ

Specifies NvBufSurface mapping type “read.”.

enumerator NVBUF_MAP_WRITE

Specifies NvBufSurface mapping type “write.”.

enumerator NVBUF_MAP_READ_WRITE

Specifies NvBufSurface mapping type “read/write.”.

enum NvBufSurfaceColorFormat

Specifies color formats for NvBufSurface.

Values:

enumerator NVBUF_COLOR_FORMAT_INVALID

Specifies an invalid color format.

enumerator NVBUF_COLOR_FORMAT_GRAY8

Specifies 8 bit GRAY scale - single plane.

enumerator NVBUF_COLOR_FORMAT_YUV420

Specifies BT.601 colorspace - YUV420 multi-planar.

enumerator NVBUF_COLOR_FORMAT_YVU420

Specifies BT.601 colorspace - YUV420 multi-planar.

enumerator NVBUF_COLOR_FORMAT_YUV420_ER

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

enumerator NVBUF_COLOR_FORMAT_YVU420_ER

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

enumerator NVBUF_COLOR_FORMAT_NV12

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

enumerator NVBUF_COLOR_FORMAT_NV12_ER

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

enumerator NVBUF_COLOR_FORMAT_NV21

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

enumerator NVBUF_COLOR_FORMAT_NV21_ER

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

enumerator NVBUF_COLOR_FORMAT_UYVY

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

enumerator NVBUF_COLOR_FORMAT_UYVY_ER

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

enumerator NVBUF_COLOR_FORMAT_VYUY

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

enumerator NVBUF_COLOR_FORMAT_VYUY_ER

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

enumerator NVBUF_COLOR_FORMAT_YUYV

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

enumerator NVBUF_COLOR_FORMAT_YUYV_ER

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

enumerator NVBUF_COLOR_FORMAT_YVYU

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

enumerator NVBUF_COLOR_FORMAT_YVYU_ER

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

enumerator NVBUF_COLOR_FORMAT_YUV444

Specifies BT.601 colorspace - YUV444 multi-planar.

enumerator NVBUF_COLOR_FORMAT_RGBA

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

enumerator NVBUF_COLOR_FORMAT_BGRA

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

enumerator NVBUF_COLOR_FORMAT_ARGB

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

enumerator NVBUF_COLOR_FORMAT_ABGR

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

enumerator NVBUF_COLOR_FORMAT_RGBx

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

enumerator NVBUF_COLOR_FORMAT_BGRx

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

enumerator NVBUF_COLOR_FORMAT_xRGB

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

enumerator NVBUF_COLOR_FORMAT_xBGR

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

enumerator NVBUF_COLOR_FORMAT_RGB

Specifies RGB-8-8-8 single plane.

enumerator NVBUF_COLOR_FORMAT_BGR

Specifies BGR-8-8-8 single plane.

enumerator NVBUF_COLOR_FORMAT_NV12_10LE

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

enumerator NVBUF_COLOR_FORMAT_NV12_12LE

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

enumerator NVBUF_COLOR_FORMAT_YUV420_709

Specifies BT.709 colorspace - YUV420 multi-planar.

enumerator NVBUF_COLOR_FORMAT_YUV420_709_ER

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

enumerator NVBUF_COLOR_FORMAT_NV12_709

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

enumerator NVBUF_COLOR_FORMAT_NV12_709_ER

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

enumerator NVBUF_COLOR_FORMAT_YUV420_2020

Specifies BT.2020 colorspace - YUV420 multi-planar.

enumerator NVBUF_COLOR_FORMAT_NV12_2020

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

enumerator NVBUF_COLOR_FORMAT_NV12_10LE_ER

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

enumerator NVBUF_COLOR_FORMAT_NV12_10LE_709

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

enumerator NVBUF_COLOR_FORMAT_NV12_10LE_709_ER

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

enumerator NVBUF_COLOR_FORMAT_NV12_10LE_2020

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

enumerator NVBUF_COLOR_FORMAT_SIGNED_R16G16

Specifies color format for packed 2 signed shorts.

enumerator NVBUF_COLOR_FORMAT_LAST
enum NvBufSurfaceLayout

Specifies layout formats for NvBufSurface video planes.

Values:

enumerator NVBUF_LAYOUT_PITCH

Specifies pitch layout.

enumerator NVBUF_LAYOUT_BLOCK_LINEAR

Specifies block linear layout.

enum NvBufSurfaceMemType

Specifies memory types for NvBufSurface.

Values:

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.

enumerator NVBUF_MEM_CUDA_PINNED

Specifies CUDA Host memory type.

enumerator NVBUF_MEM_CUDA_DEVICE

Specifies CUDA Device memory type.

enumerator NVBUF_MEM_CUDA_UNIFIED

Specifies CUDA Unified memory type.

enumerator NVBUF_MEM_SURFACE_ARRAY

Specifies NVRM Surface Array type.

Valid only for Jetson.

enumerator NVBUF_MEM_HANDLE

Specifies NVRM Handle type.

Valid only for Jetson.

enumerator NVBUF_MEM_SYSTEM

Specifies memory allocated by malloc().

Functions

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.

Return

0 if successful, or -1 otherwise.

Parameters

  • [out] surf: An indirect pointer to the allocated batched buffers.

  • [in] batchSize: Batch size of buffers.

  • [in] params: A pointer to an NvBufSurfaceCreateParams structure.

int NvBufSurfaceDestroy(NvBufSurface *surf)

Frees batched buffers previously allocated by NvBufSurfaceCreate().

Return

0 if successful, or -1 otherwise.

Parameters

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.

Return

0 if successful, or -1 otherwise.

Parameters

  • [inout] surf: A pointer to an NvBufSurface structure. The function stores pointers to the buffers in a descendant of this structure; see the notes above.

  • [in] index: Index of a buffer in the batch. -1 refers to all buffers in the batch.

  • [in] plane: Index of a plane in buffer. -1 refers to all planes in the buffer.

  • [in] type: A flag for mapping type.

int NvBufSurfaceUnMap(NvBufSurface *surf, int index, int plane)

Unmaps previously mapped buffer(s).

Return

0 if successful, or -1 otherwise.

Parameters

  • [in] surf: A pointer to an NvBufSurface structure.

  • [in] index: Index of a buffer in the batch. -1 indicates all buffers in the batch.

  • [in] plane: Index of a plane in the buffer. -1 indicates all planes in the buffer.

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.

Return

0 if successful, or -1 otherwise.

Parameters

  • [in] srcSurf: A pointer to the source NvBufSurface structure.

  • [in] dstSurf: A pointer to the destination NvBufSurface structure.

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.

Return

0 if successful, or -1 otherwise.

Parameters

  • [in] surf: A pointer to an NvBufSurface structure.

  • [in] index: Index of the buffer in the batch. -1 refers to all buffers in the batch.

  • [in] plane: Index of a plane in the buffer. -1 refers to all planes in the buffer.

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.

Return

0 if successful, or -1 otherwise.

Parameters

  • [in] surf: A pointer to an NvBufSurface structure.

  • [in] index: Index of a buffer in the batch. -1 refers to all buffers in the batch.

  • [in] plane: Index of a plane in the buffer. -1 refers to all planes in the buffer.

int NvBufSurfaceFromFd(int dmabuf_fd, void **buffer)

Gets the NvBufSurface from the DMABUF FD.

Return

0 for success, or -1 otherwise.

Parameters

  • [in] dmabuf_fd: DMABUF FD of the buffer.

  • [out] buffer: A pointer to the NvBufSurface.

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.

Return

0 if successful, or -1 otherwise.

Parameters

  • [in] surf: A pointer to the NvBufSurface structure.

  • [in] index: Index of a buffer in the batch. -1 refers to all buffers in the batch.

  • [in] plane: Index of a plane in the buffer. -1 refers to all planes in the buffer.

  • [in] value: The value to be used as fill.

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.

Return

0 for success, or -1 otherwise.

Parameters

  • [inout] surf: A 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] index: Index of a buffer in the batch. -1 specifies all buffers in the batch.

int NvBufSurfaceUnMapEglImage(NvBufSurface *surf, int index)

Destroys the previously created EGLImage object(s).

Return

0 if successful, or -1 otherwise.

Parameters

  • [in] surf: A pointer to an NvBufSurface structure.

  • [in] index: The index of a buffer in the batch. -1 specifies all buffers in the batch.

struct NvBufSurfacePlaneParams
#include <nvbufsurface.h>

Holds the planewise parameters of a buffer.

struct NvBufSurfaceCreateParams
#include <nvbufsurface.h>

Holds parameters required to allocate an NvBufSurface.

struct NvBufSurfaceMappedAddr
#include <nvbufsurface.h>

Holds pointers for a mapped buffer.

struct NvBufSurfaceParams
#include <nvbufsurface.h>

Holds information about a single buffer in a batch.

struct NvBufSurface
#include <nvbufsurface.h>

Holds information about batched buffers.