Detailed Description

This file specifies the NvBufSurface management APIs.

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

Data Structures
struct	NvBufSurfacePlaneParams
	Holds plane wise parameters of a buffer. More...

struct	NvBufSurfaceCreateParams
	Hold parameters required to allocate NvBufSurface. More...

struct	NvBufSurfaceMappedAddr
	Hold the pointers of mapped buffer. More...

struct	NvBufSurfaceParams
	Hold the information of single buffer in the batch. More...

struct	NvBufSurface
	Hold the information of batched buffers. More...

NvBufSurface types and functions.
This section describes types and functions of NvBufSurface application programming interface.
#define	STRUCTURE_PADDING 4
	Default padding for reserved fields of structures. More...

#define	NVBUF_MAX_PLANES 4
	Maximum number of planes. More...

enum	NvBufSurfaceMemMapFlags { NVBUF_MAP_READ, NVBUF_MAP_WRITE, NVBUF_MAP_READ_WRITE }
	Defines mapping types of 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 }
	Defines color formats for NvBufSurface. More...

enum	NvBufSurfaceLayout { NVBUF_LAYOUT_PITCH, NVBUF_LAYOUT_BLOCK_LINEAR }
	Defines 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 }
	Defines memory types of NvBufSurface. More...

typedef struct NvBufSurfacePlaneParams	NvBufSurfacePlaneParams
	Holds plane wise parameters of a buffer. More...

typedef struct NvBufSurfaceCreateParams	NvBufSurfaceCreateParams
	Hold parameters required to allocate NvBufSurface. More...

typedef struct NvBufSurfaceMappedAddr	NvBufSurfaceMappedAddr
	Hold the pointers of mapped buffer. More...

typedef struct NvBufSurfaceParams	NvBufSurfaceParams
	Hold the information of single buffer in the batch. More...

typedef struct NvBufSurface	NvBufSurface
	Hold the information of batched buffers. More...

int	NvBufSurfaceCreate (NvBufSurface *surf, uint32_t batchSize, NvBufSurfaceCreateParams params)
	Allocate batch of buffers. More...

int	NvBufSurfaceDestroy (NvBufSurface *surf)
	Free the batched buffers previously allocated through NvBufSurfaceCreate. More...

int	NvBufSurfaceMap (NvBufSurface *surf, int index, int plane, NvBufSurfaceMemMapFlags type)
	Map HW batched buffers to HOST / CPU address space. More...

int	NvBufSurfaceUnMap (NvBufSurface *surf, int index, int plane)
	Unmap the previously mapped buffer(s). More...

int	NvBufSurfaceCopy (NvBufSurface srcSurf, NvBufSurface dstSurf)
	Copy the memory content of source batched buffer(s) to memory of destination batched buffer(s). More...

int	NvBufSurfaceSyncForCpu (NvBufSurface *surf, int index, int plane)
	Syncs the HW memory cache for the CPU. More...

int	NvBufSurfaceSyncForDevice (NvBufSurface *surf, int index, int plane)
	Syncs the HW memory cache for the device. More...

int	NvBufSurfaceFromFd (int dmabuf_fd, void **buffer)
	Get the NvBufSurface from the dmabuf fd. More...

int	NvBufSurfaceMemSet (NvBufSurface *surf, int index, int plane, uint8_t value)
	Fill each byte of buffer(s) in NvBufSurface with provided value. More...

int	NvBufSurfaceMapEglImage (NvBufSurface *surf, int index)
	Creates an EGLImage from memory of NvBufSurface buffer(s). More...

int	NvBufSurfaceUnMapEglImage (NvBufSurface *surf, int index)
	Destroy the previously created EGLImage(s). More...

Macro Definition Documentation

#define NVBUF_MAX_PLANES 4

Maximum number of planes.

Definition at line 43 of file nvbufsurface.h.

#define STRUCTURE_PADDING 4

Default padding for reserved fields of structures.

Definition at line 40 of file nvbufsurface.h.

Typedef Documentation

typedef struct NvBufSurface NvBufSurface

Hold the information of batched buffers.

typedef struct NvBufSurfaceCreateParams NvBufSurfaceCreateParams

Hold parameters required to allocate NvBufSurface.

typedef struct NvBufSurfaceMappedAddr NvBufSurfaceMappedAddr

Hold the pointers of mapped buffer.

typedef struct NvBufSurfaceParams NvBufSurfaceParams

Hold the information of single buffer in the batch.

typedef struct NvBufSurfacePlaneParams NvBufSurfacePlaneParams

Holds plane wise parameters of a buffer.

Enumeration Type Documentation

enum NvBufSurfaceColorFormat

Defines color formats for NvBufSurface.

Enumerator
NVBUF_COLOR_FORMAT_INVALID	Invalid color format.
NVBUF_COLOR_FORMAT_GRAY8	8 bit GRAY scale - single plane
NVBUF_COLOR_FORMAT_YUV420	BT.601 colorspace - YUV420 multi-planar.
NVBUF_COLOR_FORMAT_YVU420	BT.601 colorspace - YUV420 multi-planar.
NVBUF_COLOR_FORMAT_YUV420_ER	BT.601 colorspace - YUV420 ER multi-planar.
NVBUF_COLOR_FORMAT_YVU420_ER	BT.601 colorspace - YVU420 ER multi-planar.
NVBUF_COLOR_FORMAT_NV12	BT.601 colorspace - Y/CbCr 4:2:0 multi-planar.
NVBUF_COLOR_FORMAT_NV12_ER	BT.601 colorspace - Y/CbCr ER 4:2:0 multi-planar.
NVBUF_COLOR_FORMAT_NV21	BT.601 colorspace - Y/CbCr 4:2:0 multi-planar.
NVBUF_COLOR_FORMAT_NV21_ER	BT.601 colorspace - Y/CbCr ER 4:2:0 multi-planar.
NVBUF_COLOR_FORMAT_UYVY	BT.601 colorspace - YUV 4:2:2 planar.
NVBUF_COLOR_FORMAT_UYVY_ER	BT.601 colorspace - YUV ER 4:2:2 planar.
NVBUF_COLOR_FORMAT_VYUY	BT.601 colorspace - YUV 4:2:2 planar.
NVBUF_COLOR_FORMAT_VYUY_ER	BT.601 colorspace - YUV ER 4:2:2 planar.
NVBUF_COLOR_FORMAT_YUYV	BT.601 colorspace - YUV 4:2:2 planar.
NVBUF_COLOR_FORMAT_YUYV_ER	BT.601 colorspace - YUV ER 4:2:2 planar.
NVBUF_COLOR_FORMAT_YVYU	BT.601 colorspace - YUV 4:2:2 planar.
NVBUF_COLOR_FORMAT_YVYU_ER	BT.601 colorspace - YUV ER 4:2:2 planar.
NVBUF_COLOR_FORMAT_YUV444	BT.601 colorspace - YUV444 multi-planar.
NVBUF_COLOR_FORMAT_RGBA	RGBA-8-8-8-8 single plane.
NVBUF_COLOR_FORMAT_BGRA	BGRA-8-8-8-8 single plane.
NVBUF_COLOR_FORMAT_ARGB	ARGB-8-8-8-8 single plane.
NVBUF_COLOR_FORMAT_ABGR	ABGR-8-8-8-8 single plane.
NVBUF_COLOR_FORMAT_RGBx	RGBx-8-8-8-8 single plane.
NVBUF_COLOR_FORMAT_BGRx	BGRx-8-8-8-8 single plane.
NVBUF_COLOR_FORMAT_xRGB	xRGB-8-8-8-8 single plane.
NVBUF_COLOR_FORMAT_xBGR	xBGR-8-8-8-8 single plane.
NVBUF_COLOR_FORMAT_RGB	RGB-8-8-8 single plane.
NVBUF_COLOR_FORMAT_BGR	BGR-8-8-8 single plane.
NVBUF_COLOR_FORMAT_NV12_10LE	BT.601 colorspace - Y/CbCr 4:2:0 10-bit multi-planar.
NVBUF_COLOR_FORMAT_NV12_12LE	BT.601 colorspace - Y/CbCr 4:2:0 12-bit multi-planar.
NVBUF_COLOR_FORMAT_YUV420_709	BT.709 colorspace - YUV420 multi-planar.
NVBUF_COLOR_FORMAT_YUV420_709_ER	BT.709 colorspace - YUV420 ER multi-planar.
NVBUF_COLOR_FORMAT_NV12_709	BT.709 colorspace - Y/CbCr 4:2:0 multi-planar.
NVBUF_COLOR_FORMAT_NV12_709_ER	BT.709 colorspace - Y/CbCr ER 4:2:0 multi-planar.
NVBUF_COLOR_FORMAT_YUV420_2020	BT.2020 colorspace - YUV420 multi-planar.
NVBUF_COLOR_FORMAT_NV12_2020	BT.2020 colorspace - Y/CbCr 4:2:0 multi-planar.
NVBUF_COLOR_FORMAT_LAST

Definition at line 58 of file nvbufsurface.h.

enum NvBufSurfaceLayout

Defines Layout formats for NvBufSurface video planes.

Enumerator
NVBUF_LAYOUT_PITCH	Pitch Layout.
NVBUF_LAYOUT_BLOCK_LINEAR	Block Linear Layout.

Definition at line 141 of file nvbufsurface.h.

enum NvBufSurfaceMemMapFlags

Defines mapping types of NvBufSurface.

Enumerator
NVBUF_MAP_READ
NVBUF_MAP_WRITE
NVBUF_MAP_READ_WRITE

Definition at line 48 of file nvbufsurface.h.

enum NvBufSurfaceMemType

Defines memory types of NvBufSurface.

Enumerator
NVBUF_MEM_DEFAULT	NVBUF_MEM_CUDA_DEVICE type for dGpu and NVBUF_MEM_SURFACE_ARRAY type for Jetson.
NVBUF_MEM_CUDA_PINNED	CUDA Host memory type.
NVBUF_MEM_CUDA_DEVICE	CUDA Device memory type.
NVBUF_MEM_CUDA_UNIFIED	CUDA Unified memory type.
NVBUF_MEM_SURFACE_ARRAY	NVRM Surface Array type - valid only for Jetson.
NVBUF_MEM_HANDLE	NVRM Handle type - valid only for Jetson.
NVBUF_MEM_SYSTEM	malloced memory

Definition at line 152 of file nvbufsurface.h.

Function Documentation

int NvBufSurfaceCopy	(	NvBufSurface *	srcSurf,
		NvBufSurface *	dstSurf
	)

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

This function can be used to copy source buffer(s) of one memory type to destination buffer(s) of different memory type. e.g. CUDA Host to CUDA Device or malloced memory to CUDA device etc.

Both source and destination NvBufSurface must have same buffer and batch size.

Parameters

[in]	srcSurf	pointer to source NvBufSurface structure.
[in]	dstSurf	pointer to destination NvBufSurface structure.

Returns: 0 for success, -1 for failure.

int NvBufSurfaceCreate	(	NvBufSurface **	surf,
		uint32_t	batchSize,
		NvBufSurfaceCreateParams *	params
	)

Allocate batch of buffers.

Allocates memory for batchSize buffers and returns in *surf a pointer to allocated NvBufSurface. params structure should have allocation parameters of single buffer. If size field in params is set, buffer of that size will be allocated and all other parameters (w, h, color format etc.) will be ignored.

Use NvBufSurfaceDestroy to free all the resources.

Parameters

[out]	surf	pointer to allocated batched buffers.
[in]	batchSize	batch size of buffers.
[in]	params	pointer to NvBufSurfaceCreateParams structure.

Returns: 0 for success, -1 for failure.

int NvBufSurfaceDestroy ( NvBufSurface * surf )

Free the batched buffers previously allocated through NvBufSurfaceCreate.

Parameters

[in] surf pointer to NvBufSurface to free.

Returns: 0 for success, -1 for failure.

int NvBufSurfaceFromFd	(	int	dmabuf_fd,
		void **	buffer
	)

Get the NvBufSurface from the dmabuf fd.

Parameters

[in]	dmabuf_fd	dmabuf fd of the buffer.
[out]	buffer	pointer to NvBufSurface.

Returns: 0 for success, -1 for failure.

int NvBufSurfaceMap	(	NvBufSurface *	surf,
		int	index,
		int	plane,
		NvBufSurfaceMemMapFlags	type
	)

Map HW batched buffers to HOST / CPU address space.

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

This function will fill addr array of NvBufSurfaceMappedAddr field of NvBufSurfaceParams with the CPU mapped memory pointers.

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

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

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

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

Parameters

[in]	surf	pointer to NvBufSurface structure.
[in]	index	index of buffer in the batch. -1 for all buffers in batch.
[in]	plane	index of plane in buffer. -1 for all planes in buffer.
[in]	type	flag for mapping type.

Returns: 0 for success, -1 for failure.

int NvBufSurfaceMapEglImage	(	NvBufSurface *	surf,
		int	index
	)

Creates an EGLImage from memory of NvBufSurface buffer(s).

Only memory type NVBUF_MEM_SURFACE_ARRAY is supported. This function will set eglImage pointer of NvBufSurfaceMappedAddr field of NvBufSurfaceParams with EGLImageKHR.

This function can be used in scenarios where CUDA operation on Jetson HW memory (NVBUF_MEM_SURFACE_ARRAY) is required. EGLImageKHR provided by this function can then be register with CUDA for further CUDA operations.

Parameters

[in]	surf	pointer to NvBufSurface structure.
[in]	index	index of buffer in the batch. -1 for all buffers in batch.

Returns: 0 for success, -1 for failure.

int NvBufSurfaceMemSet	(	NvBufSurface *	surf,
		int	index,
		int	plane,
		uint8_t	value
	)

Fill each byte of buffer(s) in NvBufSurface with provided value.

This function can also be used to reset the buffer(s) in the batch.

Parameters

[in]	surf	pointer to NvBufSurface structure.
[in]	index	index of buffer in the batch. -1 for all buffers in batch.
[in]	plane	index of plane in buffer. -1 for all planes in buffer.
[in]	value	value to be set.

Returns: 0 for success, -1 for failure.

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

Syncs the HW memory cache for the CPU.

Valid only for NVBUF_MEM_SURFACE_ARRAY and NVBUF_MEM_HANDLE memory types.

Parameters

[in]	surf	pointer to NvBufSurface structure.
[in]	index	index of buffer in the batch. -1 for all buffers in batch.
[in]	plane	index of plane in buffer. -1 for all planes in buffer.

Returns: 0 for success, -1 for failure.

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

Syncs the HW memory cache for the device.

Valid only for NVBUF_MEM_SURFACE_ARRAY and NVBUF_MEM_HANDLE memory types.

Parameters

[in]	surf	pointer to NvBufSurface structure.
[in]	index	index of buffer in the batch. -1 for all buffers in batch.
[in]	plane	index of plane in buffer. -1 for all planes in buffer.

Returns: 0 for success, -1 for failure.

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

Unmap the previously mapped buffer(s).

Parameters

[in]	surf	pointer to NvBufSurface structure.
[in]	index	index of buffer in the batch. -1 for all buffers in batch.
[in]	plane	index of plane in buffer. -1 for all planes in buffer.

Returns: 0 for success, -1 for failure.

int NvBufSurfaceUnMapEglImage	(	NvBufSurface *	surf,
		int	index
	)

Destroy the previously created EGLImage(s).

Parameters

[in]	surf	pointer to NvBufSurface structure.
[in]	index	index of buffer in the batch. -1 for all buffers in batch.

Returns: 0 for success, -1 for failure.

NVIDIA DeepStream SDK API Reference

4.0.2 Release

Detailed Description

Data Structures

NvBufSurface types and functions.

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation