Detailed Description

This file specifies the NvBufSurface management API.

The NvBufSurface API provides methods to allocate / deallocate, map / unmap and copy batched buffers.

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.
#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...

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_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_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...

Macro Definition Documentation

#define NVBUF_MAX_PLANES 4

Defines the maximum number of planes.

Definition at line 43 of file nvbufsurface.h.

#define STRUCTURE_PADDING 4

Defines the default padding length for reserved fields of structures.

Definition at line 40 of file nvbufsurface.h.

Typedef Documentation

typedef struct NvBufSurface NvBufSurface

Holds information about batched buffers.

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 NvBufSurfacePlaneParams NvBufSurfacePlaneParams

Holds the planewise parameters of a buffer.

Enumeration Type Documentation

enum NvBufSurfaceColorFormat

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_NV12_10LE_ER	Specifies BT.601 colorspace - Y/CbCr ER 4:2:0 10-bit multi-planar.
NVBUF_COLOR_FORMAT_NV12_10LE_709	Specifies BT.709 colorspace - Y/CbCr 4:2:0 10-bit multi-planar.
NVBUF_COLOR_FORMAT_NV12_10LE_709_ER	Specifies BT.709 colorspace - Y/CbCr ER 4:2:0 10-bit multi-planar.
NVBUF_COLOR_FORMAT_NV12_10LE_2020	Specifies BT.2020 colorspace - Y/CbCr 4:2:0 10-bit multi-planar.
NVBUF_COLOR_FORMAT_SIGNED_R16G16	Specifies color format for packed 2 signed shorts.
NVBUF_COLOR_FORMAT_LAST

Definition at line 60 of file nvbufsurface.h.

enum NvBufSurfaceLayout

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 153 of file nvbufsurface.h.

enum NvBufSurfaceMemMapFlags

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 48 of file nvbufsurface.h.

enum NvBufSurfaceMemType

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 164 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]	srcSurf	A pointer to the source NvBufSurface structure.
[in]	dstSurf	A 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]	surf	An indirect pointer to the allocated batched buffers.
[in]	batchSize	Batch size of buffers.
[in]	params	A 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] surf A 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_fd	DMABUF FD of the buffer.
[out]	buffer	A 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]	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.

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]	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.

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]	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.

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]	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.

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]	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.

Returns: 0 if successful, or -1 otherwise.

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

Unmaps previously mapped buffer(s).

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.

Returns: 0 if successful, or -1 otherwise.

int NvBufSurfaceUnMapEglImage	(	NvBufSurface *	surf,
		int	index
	)

Destroys the previously created EGLImage object(s).

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.

Returns: 0 if successful, or -1 otherwise.

NVIDIA DeepStream SDK API Reference

5.0 Release

Detailed Description

Data Structures

NvBufSurface types and functions.

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation