Detailed Description

Defines DNNTensor module for managing tensor content.

Data Structures
struct	dwDNNTensor
	Exposes the content of a dwDNNTensorHandle_t. More...

struct	dwDNNTensorProperties
	Specifies DNNTensor properties. More...

Macros
#define	DW_DNN_TENSOR_MAX_DIMENSIONS 8U
	Maximum number of dimensions a tensor can have including batch dimension (N). More...

Typedefs
typedef struct dwDNNTensorObject const *	dwConstDNNTensorHandle_t

typedef struct dwDNNTensorObject *	dwDNNTensorHandle_t
	Handles representing Deep Neural Network interface. More...

Enumerations
enum	dwDNNTensorColorSpace { DW_DNN_TENSOR_COLORSPACE_UNKNOWN = 0 , DW_DNN_TENSOR_COLORSPACE_RGB = 1 , DW_DNN_TENSOR_COLORSPACE_YUV = 2 }
	Represents the color space the data is represented in. If unknown, then its custom or non color data. More...

enum	dwDNNTensorLayout { DW_DNN_TENSOR_LAYOUT_NCHW = 0 , DW_DNN_TENSOR_LAYOUT_NHWC = 1 , DW_DNN_TENSOR_LAYOUT_NCHWx = 2 }
	Specifies the layout of a tensor Here the letters in the suffix define: More...

enum	dwDNNTensorType { DW_DNN_TENSOR_TYPE_CPU = 0 , DW_DNN_TENSOR_TYPE_CUDA = 1 , DW_DNN_TENSOR_TYPE_NVMEDIA = 2 }
	Speficies the type of a tensor. More...

Functions
DW_API_PUBLIC dwStatus	dwDNNTensor_create (dwDNNTensorHandle_t const tensorHandle, dwDNNTensorProperties const const properties, dwContextHandle_t const ctx)
	Creates and allocates resources for a dwDNNTensorHandle_t based on the properties. More...

DW_API_PUBLIC dwStatus	dwDNNTensor_createWithExtMem (dwDNNTensorHandle_t const tensorHandle, dwDNNTensorProperties const const properties, uint8_t *const extMem, size_t const stride)
	Creates a dwDNNTensorHandle_t with external memory resources based on the properties. More...

DW_API_PUBLIC dwStatus	dwDNNTensor_destroy (dwDNNTensorHandle_t const tensorHandle)
	Destroys the tensor handle and frees any memory created by dwDNNTensor_create() or dwDNNTensor_createWithExtMem(). More...

DW_API_PUBLIC dwStatus	dwDNNTensor_getLayoutView (size_t const offset, size_t const stride, size_t const numElements, const uint32_t const indices, uint32_t const numIndices, uint32_t const dimension, dwConstDNNTensorHandle_t const tensorHandle)
	Returns coefficients to facilitate traversing the given dimension. More...

DW_API_PUBLIC dwStatus	dwDNNTensor_getProperties (dwDNNTensorProperties *const properties, dwConstDNNTensorHandle_t const tensorHandle)
	Retrieves the properties of a dwDNNTensorHandle_t. More...

DW_API_PUBLIC dwStatus	dwDNNTensor_getTensor (dwDNNTensor *const tensor, dwDNNTensorHandle_t const tensorHandle)
	Retrieves the dwDNNTensor of a dwDNNTensorHandle_t. More...

DW_API_PUBLIC dwStatus	dwDNNTensor_getTimestamp (dwTime_t *const time, dwDNNTensorHandle_t const tensorHandle)
	Retrieves the timestamp of a dwDNNTensorHandle_t. More...

DW_API_PUBLIC dwStatus	dwDNNTensor_lock (void **const data, dwDNNTensorHandle_t const tensorHandle)
	Locks the tensor and retrieves pointer to the data with write access. More...

DW_API_PUBLIC dwStatus	dwDNNTensor_setTimestamp (dwTime_t time, dwDNNTensorHandle_t const tensorHandle)
	Set timestamp of a dwDNNTensorHandle_t. More...

DW_API_PUBLIC dwStatus	dwDNNTensor_tryLock (bool const isLocked, void *const data, dwDNNTensorHandle_t const tensorHandle)
	Tries to lock the tensor. More...

DW_API_PUBLIC dwStatus	dwDNNTensor_unlock (dwDNNTensorHandle_t const tensorHandle)
	Unlocks the tensor, enabling other threads to lock the tensor and modify the content. More...

Data Structure Documentation

◆ dwDNNTensor

struct dwDNNTensor

Data Fields
dwDNNTensorProperties	prop	Defines the properties of the tensor.
const void *	ptr	Pointer to the tensor content on CPU/GPU or NvMedia. Note NvMedia content cannot be traversed using this pointer. dwDNNTensorStreamer should be used to stream NvMedia to CPU or GPU to be able to access the content.
dwTime_t	timestamp_us	Specifies a timestamp, in microseconds, corresponding to this tensor data.

◆ dwDNNTensorProperties

struct dwDNNTensorProperties

Data Fields
dwDNNTensorColorSpace	colorSpace	Color space of the data in the tensor.
dwTrivialDataType	dataType	Data type of elements of the tensor.
uint32_t	dimensionSize[DW_DNN_TENSOR_MAX_DIMENSIONS]	Dimensions of the tensor to match the selected layout type. The order of dimensions is defined by the `dwDNNTensorLayout` by reading the last suffix of DW_DNN_TENSOR_LAYOUT_... in reverse order. For example given `DW_DNN_TENSOR_LAYOUT_NCHW`, `dimensionSize` should be set to: [0] = width, [1] = height, [2] = number of channels and [3] = batch size. Note Use `dwDNNTensor_getLayoutView()` to traverse the tensor in order to avoid having to compute the stride and offset for each dimension.
float32_t	dynamicRange[2]	Tensor scale value for reformatting fro m higher precision to lower precision. Values are min and max of dynamic range.
bool	isGPUMapped	Indicates whether the memory allocation should be mapped to GPU. This allocates memory using cudaHostAlloc with cudaHostAllocMapped flag. This argument is only valid if tensor type is DW_DNN_TENSOR_TYPE_CPU or DW_DNN_TENSOR_TYPE_CUDA.
uint32_t	numDimensions	Number of dimensions of the tensor.
dwDNNTensorLayout	tensorLayout	Tensor layout.
dwDNNTensorType	tensorType	Tensor type.

Macro Definition Documentation

◆ DW_DNN_TENSOR_MAX_DIMENSIONS

#define DW_DNN_TENSOR_MAX_DIMENSIONS 8U

Maximum number of dimensions a tensor can have including batch dimension (N).

Definition at line 61 of file Tensor.h.

Typedef Documentation

◆ dwConstDNNTensorHandle_t

typedef struct dwDNNTensorObject const* dwConstDNNTensorHandle_t

Definition at line 58 of file Tensor.h.

◆ dwDNNTensorHandle_t

typedef struct dwDNNTensorObject* dwDNNTensorHandle_t

Handles representing Deep Neural Network interface.

Definition at line 57 of file Tensor.h.

Enumeration Type Documentation

◆ dwDNNTensorColorSpace

enum dwDNNTensorColorSpace

Represents the color space the data is represented in. If unknown, then its custom or non color data.

Enumerator
DW_DNN_TENSOR_COLORSPACE_UNKNOWN
DW_DNN_TENSOR_COLORSPACE_RGB
DW_DNN_TENSOR_COLORSPACE_YUV

Definition at line 91 of file Tensor.h.

◆ dwDNNTensorLayout

enum dwDNNTensorLayout

Specifies the layout of a tensor Here the letters in the suffix define:

N: number of images in the batch
H: height of the image
W: width of the image
C: number of channels of the image

Enumerator

DW_DNN_TENSOR_LAYOUT_NCHW

Planar tensor. This is the most common tensor layout.

DW_DNN_TENSOR_LAYOUT_NHWC

Interleaved tensor.

DW_DNN_TENSOR_LAYOUT_NCHWx

Tensor with both interleaved and planar channels.

The interleaved channels are fixed and the dimension size at index 0 is the number of actual interleaved channels on the last plane.

Definition at line 79 of file Tensor.h.

◆ dwDNNTensorType

enum dwDNNTensorType

Speficies the type of a tensor.

Enumerator
DW_DNN_TENSOR_TYPE_CPU	CPU tensor.
DW_DNN_TENSOR_TYPE_CUDA	CUDA tensor.
DW_DNN_TENSOR_TYPE_NVMEDIA	NvMedia tensor.

Definition at line 64 of file Tensor.h.

Function Documentation

◆ dwDNNTensor_create()

DW_API_PUBLIC dwStatus dwDNNTensor_create	(	dwDNNTensorHandle_t *const	tensorHandle,
		dwDNNTensorProperties const *const	properties,
		dwContextHandle_t const	ctx
	)

Creates and allocates resources for a dwDNNTensorHandle_t based on the properties.

Parameters

[out]	tensorHandle	A tensor handle
[in]	properties	Pointer to the tensor properties
[in]	ctx	The DriveWorks context.

Returns: DW_SUCCESS if the tensor was created successfully,
DW_INVALID_ARGUMENT if any of the given parameters is invalid,
DW_INVALID_HANDLE if the given context handle is invalid.

◆ dwDNNTensor_createWithExtMem()

DW_API_PUBLIC dwStatus dwDNNTensor_createWithExtMem	(	dwDNNTensorHandle_t *const	tensorHandle,
		dwDNNTensorProperties const *const	properties,
		uint8_t *const	extMem,
		size_t const	stride
	)

Creates a dwDNNTensorHandle_t with external memory resources based on the properties.

Parameters

[out]	tensorHandle	A tensor handle
[in]	properties	Pointer to the tensor properties
[in]	extMem	Pointer to external memory resources.
[in]	stride	Stride size of external memory resources.

Returns: DW_SUCCESS if the tensor was created successfully,
DW_INVALID_ARGUMENT if any of the given parameters is invalid.

◆ dwDNNTensor_destroy()

DW_API_PUBLIC dwStatus dwDNNTensor_destroy ( dwDNNTensorHandle_t const tensorHandle )

Destroys the tensor handle and frees any memory created by dwDNNTensor_create() or dwDNNTensor_createWithExtMem().

Parameters

[in] tensorHandle A tensor handle

Returns: DW_SUCCESS if the tensor was destroyed successfully,
DW_INVALID_HANDLE if the given tensor handle is invalid.

◆ dwDNNTensor_getLayoutView()

DW_API_PUBLIC dwStatus dwDNNTensor_getLayoutView	(	size_t *const	offset,
		size_t *const	stride,
		size_t *const	numElements,
		const uint32_t *const	indices,
		uint32_t const	numIndices,
		uint32_t const	dimension,
		dwConstDNNTensorHandle_t const	tensorHandle
	)

Returns coefficients to facilitate traversing the given dimension.

The coefficients can be used to estimate the location in memory by: tensorData[idx * stride + offset] where idx is in [0, numElements)

Note: This function is not supported by NvMedia tensors. In order to access the content of the tensors in question, stream them to CPU or CUDA using dwDNNTensorStreamer.

Parameters

[out]	offset	Offset. Stored in CPU.
[out]	stride	Stride. Stored in CPU.
[out]	numElements	Number of elements in the given desired dimension. Stored in CPU.
[in]	indices	List of indices having the same size as dimensions of the tensor and indicating the starting position of the traversal
[in]	numIndices	Number of given indices
[in]	dimension	Dimension to be traversed
[in]	tensorHandle	A tensor handle

Returns: DW_SUCCESS if the tensor was destroyed successfully,
DW_INVALID_HANDLE if the given tensor handle is invalid.

◆ dwDNNTensor_getProperties()

DW_API_PUBLIC dwStatus dwDNNTensor_getProperties	(	dwDNNTensorProperties *const	properties,
		dwConstDNNTensorHandle_t const	tensorHandle
	)

Retrieves the properties of a dwDNNTensorHandle_t.

Parameters

[out]	properties	A pointer to the properties
[in]	tensorHandle	A tensor handle

Returns: DW_SUCCESS if the tensor properties are retrieved successfully,
DW_INVALID_HANDLE if the given tensor handle is invalid.

◆ dwDNNTensor_getTensor()

DW_API_PUBLIC dwStatus dwDNNTensor_getTensor	(	dwDNNTensor *const	tensor,
		dwDNNTensorHandle_t const	tensorHandle
	)

Retrieves the dwDNNTensor of a dwDNNTensorHandle_t.

Note: Any modification to the data pointed by the tensor retrieved will modify the content of the original handle

Parameters

[out]	tensor	A pointer to the dwDNNTensor pointer
[in]	tensorHandle	A tensor handle

Returns: DW_SUCCESS if the dwDNNTensor is successfully retrieved,
DW_INVALID_ARGUMENT if the given tensor pointer or tensor handle is invalid.

◆ dwDNNTensor_getTimestamp()

DW_API_PUBLIC dwStatus dwDNNTensor_getTimestamp	(	dwTime_t *const	time,
		dwDNNTensorHandle_t const	tensorHandle
	)

Retrieves the timestamp of a dwDNNTensorHandle_t.

Parameters

[out]	time	A pointer to the timestamp
[in]	tensorHandle	A tensor handle

Returns: DW_SUCCESS if the timestamp is successfully retrieved,
DW_INVALID_ARGUMENT if the given tensor pointer or tensor handle is invalid.

◆ dwDNNTensor_lock()

DW_API_PUBLIC dwStatus dwDNNTensor_lock	(	void **const	data,
		dwDNNTensorHandle_t const	tensorHandle
	)

Locks the tensor and retrieves pointer to the data with write access.

Read access can also be achieved by dwDNNTensor_getTensor(). Locking a tensor will block any operation that shall modify the content.

Note: This function will block if the tensor is locked by another thread.

Parameters

[out]	data	A pointer to the beginning of the tensor content.
[in]	tensorHandle	A tensor handle

Returns: DW_SUCCESS if the tensor is successfully locked and data is successfully retrieved,
DW_INVALID_ARGUMENT if the given data pointer or tensor handle is invalid.

◆ dwDNNTensor_setTimestamp()

DW_API_PUBLIC dwStatus dwDNNTensor_setTimestamp	(	dwTime_t	time,
		dwDNNTensorHandle_t const	tensorHandle
	)

Set timestamp of a dwDNNTensorHandle_t.

Parameters

[in]	time	Input timestamp
[in]	tensorHandle	A tensor handle

Returns: DW_SUCCESS if the timestamp is successfully set,
DW_INVALID_ARGUMENT if the given tensor pointer or tensor handle is invalid.

◆ dwDNNTensor_tryLock()

DW_API_PUBLIC dwStatus dwDNNTensor_tryLock	(	bool *const	isLocked,
		void **const	data,
		dwDNNTensorHandle_t const	tensorHandle
	)

Tries to lock the tensor.

Returns immediately. If the lock operation is successful, isLocked is set to true, and the data points to the beginning of the content of the tensor. Otherwise, isLocked is set to false and the data points to nullptr.

Note: If the tensor has already been locked by the same thread, the behavior is undefined.

Parameters

[out]	isLocked	A flag indicating if the lock operation is successful.
[out]	data	A pointer to the beginning of the tensor content if lock is successful.
[in]	tensorHandle	A tensor handle

Returns: DW_SUCCESS whether the lock is successful or not,
DW_INVALID_ARGUMENT if the given data pointer, isLocked or tensor handle is invalid.

◆ dwDNNTensor_unlock()

DW_API_PUBLIC dwStatus dwDNNTensor_unlock ( dwDNNTensorHandle_t const tensorHandle )

Unlocks the tensor, enabling other threads to lock the tensor and modify the content.

Parameters

[in] tensorHandle A tensor handle

Returns: DW_SUCCESS if the tensor is successfully unlocked,
DW_INVALID_ARGUMENT if the tensor handle is invalid.

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Data Structure Documentation

◆ dwDNNTensor

◆ dwDNNTensorProperties

Macro Definition Documentation

◆ DW_DNN_TENSOR_MAX_DIMENSIONS

Typedef Documentation

◆ dwConstDNNTensorHandle_t

◆ dwDNNTensorHandle_t

Enumeration Type Documentation

◆ dwDNNTensorColorSpace

◆ dwDNNTensorLayout

◆ dwDNNTensorType

Function Documentation

◆ dwDNNTensor_create()

◆ dwDNNTensor_createWithExtMem()

◆ dwDNNTensor_destroy()

◆ dwDNNTensor_getLayoutView()

◆ dwDNNTensor_getProperties()

◆ dwDNNTensor_getTensor()

◆ dwDNNTensor_getTimestamp()

◆ dwDNNTensor_lock()

◆ dwDNNTensor_setTimestamp()

◆ dwDNNTensor_tryLock()

◆ dwDNNTensor_unlock()