Image Interface

Detailed Description

Defines image abstractions, and streamer and format conversion APIs.

Unless explicitly specified, all errors returned by DW APIs are non recoverable and the user application should transition to fail safe mode. In addition, any error code not described in this documentation should be consider as fatal and the user application should also transition to fail safe mode.

Data Structures
struct	dwExposureDuration
struct	dwImageCPU
	Defines a CPU-based image. More...
struct	dwImageCUDA
	Defines a CUDA image. More...
struct	dwImageDataLines
	Container for data lines from the camera. More...
struct	dwImageMetaData
	Additional meta information stored with each image. More...
struct	dwImageNvMedia
	Defines an NvMedia image. More...
struct	dwImagePool
	Specifies a pool of images. More...
struct	dwImageProperties
	Defines the properties of the image. More...
struct	dwImageRawProperties
struct	dwImageSensorStatistics
	Sensor statistics associated with the image. More...
struct	dwImageSplineControlPoint
struct	dwImageTimestamps
	Image timestamps. More...
struct	dwSensorTemperature

Modules
	Image Streamer
	Defines the image streamer function, enabling streaming images between different APIs.

Macros
#define	DW_DEVBLK_CDI_MAX_EXPOSURES   4
#define	DW_IMAGE_NUM_SPLINE_COMPONENTS   18U
#define	DW_ISP_MAX_COLOR_COMPONENT   (4U)
#define	DW_LUMINANCE_CALIB_MATRIX_SIZE   4
	Defines the length(M) of a MxM luminance calibration matrix. More...
#define	DW_MAX_IMAGE_PLANES   3
#define	DW_MAX_NUM_TEMPERATURES   4
	should be the same as the DEVBLK_CDI_MAX_NUM_TEMPERATURES in NvSIPLCDICommon.h of NvSIPL More...

Typedefs
typedef struct dwImageObject const *	dwConstImageHandle_t
typedef struct dwImageAllocationAttrList *	dwImageAllocationAttrListHandle_t
	dwImage Allocation Attributes List More...
typedef struct dwImageObject *	dwImageHandle_t

Enumerations
enum	dwImageFormat {   DW_IMAGE_FORMAT_UNKNOWN = 0 ,   DW_IMAGE_FORMAT_R_INT16 = 900 ,   DW_IMAGE_FORMAT_R_UINT8 = 1000 ,   DW_IMAGE_FORMAT_R_UINT16 ,   DW_IMAGE_FORMAT_R_UINT32 ,   DW_IMAGE_FORMAT_R_FLOAT16 ,   DW_IMAGE_FORMAT_R_FLOAT32 ,   DW_IMAGE_FORMAT_RG_INT16 ,   DW_IMAGE_FORMAT_RG_UINT8 ,   DW_IMAGE_FORMAT_RG_FLOAT32 ,   DW_IMAGE_FORMAT_RGB_UINT8 ,   DW_IMAGE_FORMAT_RGB_UINT16 ,   DW_IMAGE_FORMAT_RGB_FLOAT16 ,   DW_IMAGE_FORMAT_RGB_FLOAT32 ,   DW_IMAGE_FORMAT_RGBA_UINT8 ,   DW_IMAGE_FORMAT_RGBA_UINT16 ,   DW_IMAGE_FORMAT_RGBA_FLOAT16 ,   DW_IMAGE_FORMAT_RGBA_FLOAT32 ,   DW_IMAGE_FORMAT_RGBX_FLOAT16 = 1200 ,   DW_IMAGE_FORMAT_VUYX_UINT8 ,   DW_IMAGE_FORMAT_VUYX_UINT16 ,   DW_IMAGE_FORMAT_RGB_UINT8_PLANAR = 2000 ,   DW_IMAGE_FORMAT_RGB_UINT16_PLANAR ,   DW_IMAGE_FORMAT_RGB_FLOAT16_PLANAR ,   DW_IMAGE_FORMAT_RGB_FLOAT32_PLANAR ,   DW_IMAGE_FORMAT_RCB_FLOAT16_PLANAR ,   DW_IMAGE_FORMAT_RCB_FLOAT32_PLANAR ,   DW_IMAGE_FORMAT_RCC_FLOAT16_PLANAR ,   DW_IMAGE_FORMAT_RCC_FLOAT32_PLANAR ,   DW_IMAGE_FORMAT_YUV420_UINT8_PLANAR = 3000 ,   DW_IMAGE_FORMAT_YUV420_UINT8_SEMIPLANAR ,   DW_IMAGE_FORMAT_YUV420_UINT16_SEMIPLANAR ,   DW_IMAGE_FORMAT_YUV422_UINT8_SEMIPLANAR = 3100 ,   DW_IMAGE_FORMAT_YUV_UINT8_PLANAR ,   DW_IMAGE_FORMAT_YUV_UINT16_PLANAR ,   DW_IMAGE_FORMAT_YUV422_UINT8_PACKED = 3200 ,   DW_IMAGE_FORMAT_RAW_UINT16 = 4000 ,   DW_IMAGE_FORMAT_RAW_FLOAT16 }
	Format of the image represented as DW_IMAGE_FORMAT_COLORSPACE(_PIXELTYPE)(_PIXELORDER) More...
enum	dwImageMemoryType {   DW_IMAGE_MEMORY_TYPE_DEFAULT = 0 ,   DW_IMAGE_MEMORY_TYPE_PITCH = 1 ,   DW_IMAGE_MEMORY_TYPE_BLOCK = 2 }
	Specifies memory type layout. More...
enum	dwImageMetaDataFlags {   DW_IMAGE_FLAGS_EMBEDDED_LINES = (1 << 2) ,   DW_IMAGE_FLAGS_SENSOR_SETTINGS = (1 << 3) ,   DW_IMAGE_FLAGS_FRAME_SEQUENCE_NUMBER = (1 << 4) ,   DW_IMAGE_FLAGS_SYSMEM = (1 << 5) ,   DW_IMAGE_FLAGS_HAS_RAW_ORDER_DESCRIPTOR = (1 << 6) ,   DW_IMAGE_FLAGS_CONTROLINFO = (1 << 7) ,   DW_IMAGE_FLAGS_LUMINANCE_CALIBRATED = (1 << 8) ,   DW_IMAGE_FLAGS_TOTAL_WHITE_BALANCE_GAIN = (1 << 9) ,   DW_IMAGE_FLAGS_GTM_SPLINE_INFO = (1 << 10) ,   DW_IMAGE_FLAGS_SENSOR_TEMPERATURE = (1 << 11) ,   DW_IMAGE_FLAGS_NVSCI_SURF_ATTR = (1 << 12) ,   DW_IMAGE_FLAGS_MAPS_CUPVA = (1 << 13) }
	Flags defining the meta information available in an image. More...
enum	dwImageType {   DW_IMAGE_CPU = 0 ,   DW_IMAGE_CUDA = 2 ,   DW_IMAGE_NVMEDIA = 3 ,   DW_IMAGE_GL = 0xFF }
	Specifies the image type. More...
enum	dwSyncType {   DW_SYNC_TYPE_WAITER ,   DW_SYNC_TYPE_SIGNALER }
	Enum representing a sync type. More...

Functions
DW_API_PUBLIC dwStatus	dwImage_copyConvert (dwImageHandle_t const output, dwConstImageHandle_t const input, dwContextHandle_t const context)
	Converts CUDA or NvMedia images by copying into an output image, following the properties in the output image. More...
DW_API_PUBLIC dwStatus	dwImage_copyConvertAsync (dwImageHandle_t const output, dwConstImageHandle_t const input, cudaStream_t const stream, dwContextHandle_t const context)
	Converts CUDA or NvMedia images by copying into an output image, following the properties in the output image. More...
DW_API_PUBLIC dwStatus	dwImage_create (dwImageHandle_t *const image, dwImageProperties properties, dwContextHandle_t const ctx)
	Creates and allocates resources for a dwImageHandle_t based on the properties passed as input. More...
DW_API_PUBLIC dwStatus	dwImage_createAndBindBuffer (dwImageHandle_t *const image, dwImageProperties properties, void *const buffersIn[DW_MAX_IMAGE_PLANES], size_t const pitches[DW_MAX_IMAGE_PLANES], size_t const bufferCount, dwContextHandle_t const ctx)
	Creates a dwImageHandle_t based on the properties passed and binds a memory buffer provided by the application. More...
DW_API_PUBLIC dwStatus	dwImage_createAndBindCUDAArray (dwImageHandle_t *const image, dwImageProperties properties, cudaArray_t const buffers[DW_MAX_IMAGE_PLANES], size_t const bufferCount, dwContextHandle_t const ctx)
	Creates a dwImageHandle_t based on the properties passed and binds a cudaArray_t to it. More...
DW_API_PUBLIC dwStatus	dwImage_createAndBindNvSciBuf (dwImageHandle_t *const image, dwImageProperties const *properties, NvSciBufObj nvscibufObj, dwContextHandle_t const ctx)
	Creates a dwImageHandle_t based on the properties passed and binds a memory buffer provided by the application. More...
DW_API_PUBLIC dwStatus	dwImage_destroy (dwImageHandle_t const image)
	Destroys the image handle and frees any memory created by dwImage_create(). More...
DW_API_PUBLIC dwStatus	dwImage_getCPU (dwImageCPU **const imageCPU, dwImageHandle_t const image)
	Retrieves the dwImageCPU of a dwImageHandle_t. More...
DW_API_PUBLIC dwStatus	dwImage_getCUDA (dwImageCUDA **const imageCUDA, dwImageHandle_t const image)
	Retrieves the dwImageCUDA of a dwImageHandle_t. More...
DW_API_PUBLIC dwStatus	dwImage_getDataLayout (size_t *const elementSize, size_t *const planeCount, uint32_t planeChannelCount[DW_MAX_IMAGE_PLANES], dwVector2ui planeSize[DW_MAX_IMAGE_PLANES], dwImageProperties const *const prop)
	Returns the expected data layout of an image given its properties. More...
DW_API_PUBLIC dwStatus	dwImage_getMetaData (dwImageMetaData *const metaData, dwConstImageHandle_t const image)
	Retrieves the metadata of a dwImageHandle_t. More...
DW_API_PUBLIC dwStatus	dwImage_getNvMedia (dwImageNvMedia **imageNvMedia, dwImageHandle_t image)
	Retrieves the dwImageNvMedia of a dwImageHandle_t. More...
DW_API_PUBLIC dwStatus	dwImage_getNvSciBuf (NvSciBufObj *nvSciBufObj, dwImageHandle_t image)
	Retrieve the NvSciBufObj backing the image allocation. More...
DW_API_PUBLIC dwStatus	dwImage_getPixelType (dwTrivialDataType *const type, dwImageFormat const format)
	Retrieves dwTrivialDataType associated with a specific format. More...
DW_API_PUBLIC dwStatus	dwImage_getPlaneCount (size_t *const planeCount, dwImageFormat const format)
	Retrieves number of planes of the image format. More...
DW_API_PUBLIC dwStatus	dwImage_getProperties (dwImageProperties *const properties, dwConstImageHandle_t const image)
	Retrieves the properties of a dwImageHandle_t. More...
DW_API_PUBLIC dwStatus	dwImage_getTimestamp (dwTime_t *const timestamp, dwConstImageHandle_t const image)
	Retrieves the timestamp of acquisition of a dwImageHandle_t. More...
DW_API_PUBLIC dwStatus	dwImage_setMetaData (dwImageMetaData const *const metaData, dwImageHandle_t const image)
	Sets the metadata of a dwImageHandle_t. More...
DW_API_PUBLIC dwStatus	dwImage_setTimestamp (dwTime_t const timestamp, dwImageHandle_t const image)
	Sets the timestamp of a dwImageHandle_t. More...
DW_API_PUBLIC dwStatus	dwImageCUDA_getPlaneAsImage (dwImageCUDA *const planeImage, dwImageCUDA const *const srcImage, uint32_t const planeIdx)
	Returns a specific plane of a CUDA image as its own single-plane CUDA image. More...
DW_API_PUBLIC dwStatus	dwImageCUDA_mapToROI (dwImageCUDA *const dstImg, dwImageCUDA const *const srcImg, dwRect const roi)
	Returns a dwImageCUDA that is mapped to a region of interest in the data of the srcImg. More...

---

Data Structure Documentation

dwExposureDuration

struct dwExposureDuration

Data Fields
float32_t	data[DW_DEVBLK_CDI_MAX_EXPOSURES]	Specifies the exposure duration (microsecond) Each row of the image is captured using DW_DEVBLK_CDI_MAX_EXPOSURES of HDR exposures which are constant per row within the image.

dwImageCPU

struct dwImageCPU

Data Fields
uint8_t *	data[DW_MAX_IMAGE_PLANES]	Specifies the raw image data.
size_t	pitch[DW_MAX_IMAGE_PLANES]	Specifies the pitch of the image in bytes.
dwImageProperties	prop	Specifies the properites of the image.
dwTime_t	timestamp_us	Specifies the time in microseconds from system time epoch, when the image content was updated (ie EOF GMSL acquisition, USB camera processed frame, copied over from converted image etc...)

dwImageCUDA

struct dwImageCUDA

Data Fields
cudaArray_t	array[DW_MAX_IMAGE_PLANES]	Holds the CUDA image plane data.
void *	dptr[DW_MAX_IMAGE_PLANES]	Holds the pointer to the image planes.
size_t	pitch[DW_MAX_IMAGE_PLANES]	Defines the pitch of each plane in bytes.
dwImageProperties	prop	Defines the properties of the image.
dwTime_t	timestamp_us	Specifies the time in microseconds from system time epoch, when the image content was updated (ie EOF GMSL acquisition, USB camera processed frame, copied over from converted image etc...)

dwImageDataLines

struct dwImageDataLines

Data Fields
uint8_t *	bottomLineData	pointer to the beginning of bottom lines
uint32_t	bytesPerLine	Number of bytes for each line.
dwVector2ui	embeddedDataSize	this defines the number of rows before and after the image
uint8_t *	topLineData	pointer to the beginning of top lines

dwImageMetaData

struct dwImageMetaData

Data Fields
dwImageAllocationAttrListHandle_t	allocAttrs	Allocation attributes used by internal drivers.
float32_t	analogGain	Specifies the analog Gain.
int32_t	colorStdPriv	ColorStd attributes used by internal drivers.
float32_t	conversionGain	Specifies the conversion Gain.
dwImageDataLines	dataLines	embedded data lines. This is where the meta data defined above are parsed from A RAW image coming from a sensor often contains this information arranged as extra lines before and after the image. The full image is stored in a buffer structured as [TOP DATA][IMAGE][BOTTOM DATA] (top * W) + (H * W) + (bott * W)
float32_t	digitalGain	Specifies the digital Gain.
float32_t	exposureTime	Specifies the exposure time (microsecond)
uint32_t	flags	combination of multiple flags 'dwImageMetaDataFlags' defining which of the meta fields are valid
uint32_t	frameSequenceNumber	Holds a frame sequence number, that is, a monotonically increasing frame counter.
dwImageSplineControlPoint	gtmSplineControlPoint[DW_IMAGE_NUM_SPLINE_COMPONENTS]	Holds the global tonemap block, containing a set of spline control points.
dwImageTimestamps	imageTimestamps	Specifies image timestamps.
uint32_t	msbPosition	Specifies the msb of the pixel data.
dwImageRawProperties	rawProperties
dwImageSensorStatistics	sensorStatistics	Holds info on sensor statistics at the time of the image capture.
float32_t	wbGain[4]	Specifies the sensor white balance gains : R(0) G1(1) G2(2) B(3)

dwImageNvMedia

struct dwImageNvMedia

Data Fields
NvSciBufObj	imgBuf	Holds the pointer to the NvSciBufObj image.
dwImageProperties	prop	Holds image properties.
dwTime_t	timestamp_us	Specifies the time in microseconds from system time epoch, when the image content was updated (ie EOF GMSL acquisition, USB camera processed frame, copied over from converted image etc...)

dwImagePool

struct dwImagePool

Data Fields
size_t	imageCount	Number of images in the pool.
dwImageHandle_t *	images	Pointer to image handles.

dwImageProperties

struct dwImageProperties

Data Fields
dwImageFormat	format	Specifies the format of the image.
uint32_t	height	Specifies the height of the image in pixels.
dwImageMemoryType	memoryLayout	Memory layout type.
dwImageMetaData	meta	additional meta information stored with the image. Not all images might provide it
dwImageType	type	Specifies the type of image.
uint32_t	width	Specifies the width of the image in pixels.

dwImageRawProperties

struct dwImageRawProperties

Data Fields
uint32_t	msbPosition	Specifies the msb of the pixel data.
uint32_t	rawBitDataType	Describes the raw pixel depth, specified like the above format descriptor by 1 - NVM_SURF_ATTR_BITS_PER_COMPONENT_XX (PDK < 6.0.4.0) 2 - integer bit depth (PDK >= 6.0.4.0)
uint32_t	rawFormatDescriptor	Describes the raw order and used when explicitly creating a DW_IMAGE_NVMEDIA if DW_IMAGE_FLAGS_HAS_RAW_ORDER_DESCRIPTOR is enabled This is represented by the define integers of the form: 1 - NVM_SURF_ATTR_COMPONENT_ORDER_XXX in nvmedia_surface.h (PDK < 6.0.4.0) 2 - NVSIPL_PIXEL_ORDER_XXX in NvSIPLCapStructs.h (PDK >= 6.0.4.0) If the flag is not specified, this value is ignored and a default RGGB order will be chosen.
bool	rawFormatRJ	Describes if raw order alignment is left justified(msb alligned) or right justified (lsb allignment) and used when explicitly creating a DW_IMAGE_NVMEDIA if DW_IMAGE_FLAGS_HAS_RAW_ORDER_DESCRIPTOR is enabled If the flag is not specified, this value is false and a default msb alligned order will be chosen.

dwImageSensorStatistics

struct dwImageSensorStatistics

Data Fields
float32_t	alpha	Holds power factor for isp statistics compression. Valid range: [0.5, 1.0] (scalar value)
float32_t	analogGain	Specifies the analog Gain (scalar value)
float32_t	autoAwbGain[DW_ISP_MAX_COLOR_COMPONENT]	Holds the total white balance gains, which includes both sensor channel and ISP gains. (scalar value)
float32_t	brightnessKey	Holds the scene brightness key. (scalar value)
float32_t	cct	Holds the correlated color temperature. (scalar value)
float32_t	conversionGain	Specifies the conversion Gain (scalar value)
float32_t	digitalGain	Specifies the digital Gain (scalar value)
dwExposureDuration	exposureDurationUs	Specifies the exposure duration (microsecond)
float32_t	exposureTime	Specifies the exposure time (microsecond) This variable is deprecated and will be removed in the next major release. Please use exposureDurationUs in this struct
float64_t	luminanceCalibrationFactor	(note: parameter to be deprecated starting 6.0.7.0) Holds a luminance calibration factor ( K / f^2 ) for luminance calibrated sensors. Definition: N = K * (t*S / (f^2)) * L N: pixel value (e.g. RGGB channel average value) K: calibration constant t: sensor exposure time in seconds (if number of exposures > 1, use long exposure time value) S: sensor gain (if number of exposures > 1, use long exposure gain value) f: aperture number (f-stop) L: Luminance Let luminanceCalibrationFactor = K / (f^2) = N / (t*S*L)
float64_t	luminanceCalibrationMatrix[DW_LUMINANCE_CALIB_MATRIX_SIZE][DW_LUMINANCE_CALIB_MATRIX_SIZE]	Holds the luminance calibration matrix for the sensor. (scalar value) Supported values [1E-12, 1E12]
bool	nightMode	Holds day-night mode (true: Night mode, false: Day mode)
float32_t	rawImageMidTone	Holds the midtone value of the raw image. (scalar value)
float32_t	sceneBrightness	Holds the scene brightness level. (scalar value)
float32_t	sceneDynamicRange	Holds the scene dynamic range. (scalar value)
dwSensorTemperature	sensorTemperature	Holds the values of active sensor temperatures in degrees Celsius. Valid only if DW_IMAGE_FLAGS_SENSOR_TEMPERATURE is enabled. Indexes are in the range [0, numTemperatures - 1]. These values are obtained from the mapped registers of image sensor by NvSIPL and the detailed implemetation is depending on the camera module and camera driver.
float32_t	wbGain[4]	Specifies the sensor white balance gains : R(0) G1(1) G2(2) B(3) (scalar value)

dwImageSplineControlPoint

struct dwImageSplineControlPoint

Data Fields
float64_t	slope	Holds slope of the spline curve at the control point.
float32_t	x	Holds X coordinate of the control point.
float32_t	y	Holds Y coordinate of the control point.

dwImageTimestamps

struct dwImageTimestamps

Data Fields
dwTime_t	eofTimestampUs	Specifies the time, in microseconds, when the last row of the image was fully exposed, i.e., the time at the end of the last row’s exposure.
dwTime_t	moeTimestampUs	This time indicates the middle of the image frame exposure. Note that this is the recommended timestamp to use for sensor fusion without rolling shutter compensation, i.e., the whole image frame is treated as a single time event. For the most precise sensor fusion, rolling shutter compensation is necessary
dwTime_t	sofTimestampUs	Rolling shutter timestamp fields: startOfFrameTimestampUs and endOfFrameTimestampUs can be used to compute precise per row timestamps for rolling shutter correction for use in sensor fusion. Specifies the time, in microseconds, when the first row of the image was fully exposed, i.e., the time at the end of the first row’s exposure.
dwTime_t	subExposureStartTimestampUs[DW_DEVBLK_CDI_MAX_EXPOSURES]	Sub exposure start timestamps in microseconds.
dwTime_t	tscEofTimestampUs	Specifies the TSC time, in microseconds, when the last row of the image was fully exposed in TSC time domain, i.e., the time at the end of the last row’s exposure.

dwSensorTemperature

struct dwSensorTemperature

Data Fields
float32_t	dataCelsius[DW_MAX_NUM_TEMPERATURES]	Holds the values of active sensor temperatures in degrees Celsius. Valid only if DW_IMAGE_FLAGS_SENSOR_TEMPERATURE is enabled. Indexes are in the range [0, numTemperatures - 1]. These values are obtained from the mapped registers of image sensor by NvSIPL and the detailed implementation is depending on the camera module and camera driver.
uint8_t	numTemperatures	Holds the number of active temperatures. Valid only if DW_IMAGE_FLAGS_SENSOR_TEMPERATURE is enabled. Value range: [1, DW_MAX_NUM_TEMPERATURES]. DW_MAX_NUM_TEMPERATURES is same as DEVBLK_CDI_MAX_NUM_TEMPERATURES which is defined in NvSIPLCDICommon.h of NvSIPL. The value is equal to the number of the temperature sensors in the specific image sensor being used.

Macro Definition Documentation

DW_DEVBLK_CDI_MAX_EXPOSURES

#define DW_DEVBLK_CDI_MAX_EXPOSURES   4

Definition at line 281 of file Image.h.

DW_IMAGE_NUM_SPLINE_COMPONENTS

#define DW_IMAGE_NUM_SPLINE_COMPONENTS   18U

Definition at line 93 of file Image.h.

DW_ISP_MAX_COLOR_COMPONENT

#define DW_ISP_MAX_COLOR_COMPONENT   (4U)

Definition at line 90 of file Image.h.

DW_LUMINANCE_CALIB_MATRIX_SIZE

#define DW_LUMINANCE_CALIB_MATRIX_SIZE   4

Defines the length(M) of a MxM luminance calibration matrix.

Definition at line 305 of file Image.h.

DW_MAX_IMAGE_PLANES

#define DW_MAX_IMAGE_PLANES   3

Definition at line 89 of file Image.h.

DW_MAX_NUM_TEMPERATURES

#define DW_MAX_NUM_TEMPERATURES   4

should be the same as the DEVBLK_CDI_MAX_NUM_TEMPERATURES in NvSIPLCDICommon.h of NvSIPL

Definition at line 92 of file Image.h.

Typedef Documentation

dwConstImageHandle_t

typedef struct dwImageObject const* dwConstImageHandle_t

Definition at line 106 of file Image.h.

dwImageAllocationAttrListHandle_t

typedef struct dwImageAllocationAttrList* dwImageAllocationAttrListHandle_t

dwImage Allocation Attributes List

Definition at line 109 of file Image.h.

dwImageHandle_t

typedef struct dwImageObject* dwImageHandle_t

Definition at line 105 of file Image.h.

Enumeration Type Documentation

dwImageFormat

enum dwImageFormat

Format of the image represented as DW_IMAGE_FORMAT_COLORSPACE(_PIXELTYPE)(_PIXELORDER)

Note

The default memory allocation is via NvSciBuf but certain legacy formats are not compatible as listed below. These formats will continue to use API specific memory allocation based on dwImageType

Enumerator
DW_IMAGE_FORMAT_UNKNOWN	Normal formats.
DW_IMAGE_FORMAT_R_INT16
DW_IMAGE_FORMAT_R_UINT8
DW_IMAGE_FORMAT_R_UINT16
DW_IMAGE_FORMAT_R_UINT32
DW_IMAGE_FORMAT_R_FLOAT16
DW_IMAGE_FORMAT_R_FLOAT32	Not backed by NvSci.
DW_IMAGE_FORMAT_RG_INT16
DW_IMAGE_FORMAT_RG_UINT8	Not backed by NvSci.
DW_IMAGE_FORMAT_RG_FLOAT32	Not backed by NvSci.
DW_IMAGE_FORMAT_RGB_UINT8	Not backed by NvSci.
DW_IMAGE_FORMAT_RGB_UINT16	Not backed by NvSci.
DW_IMAGE_FORMAT_RGB_FLOAT16	Not backed by NvSci.
DW_IMAGE_FORMAT_RGB_FLOAT32	Not backed by NvSci.
DW_IMAGE_FORMAT_RGBA_UINT8
DW_IMAGE_FORMAT_RGBA_UINT16
DW_IMAGE_FORMAT_RGBA_FLOAT16
DW_IMAGE_FORMAT_RGBA_FLOAT32	Not backed by NvSci.
DW_IMAGE_FORMAT_RGBX_FLOAT16
DW_IMAGE_FORMAT_VUYX_UINT8
DW_IMAGE_FORMAT_VUYX_UINT16
DW_IMAGE_FORMAT_RGB_UINT8_PLANAR	Not backed by NvSci.
DW_IMAGE_FORMAT_RGB_UINT16_PLANAR
DW_IMAGE_FORMAT_RGB_FLOAT16_PLANAR	Not backed by NvSci.
DW_IMAGE_FORMAT_RGB_FLOAT32_PLANAR	Not backed by NvSci.
DW_IMAGE_FORMAT_RCB_FLOAT16_PLANAR	Not backed by NvSci.
DW_IMAGE_FORMAT_RCB_FLOAT32_PLANAR	Not backed by NvSci.
DW_IMAGE_FORMAT_RCC_FLOAT16_PLANAR	Not backed by NvSci.
DW_IMAGE_FORMAT_RCC_FLOAT32_PLANAR	Not backed by NvSci.
DW_IMAGE_FORMAT_YUV420_UINT8_PLANAR	YUV encoding formats from camera.
DW_IMAGE_FORMAT_YUV420_UINT8_SEMIPLANAR
DW_IMAGE_FORMAT_YUV420_UINT16_SEMIPLANAR
DW_IMAGE_FORMAT_YUV422_UINT8_SEMIPLANAR
DW_IMAGE_FORMAT_YUV_UINT8_PLANAR
DW_IMAGE_FORMAT_YUV_UINT16_PLANAR
DW_IMAGE_FORMAT_YUV422_UINT8_PACKED
DW_IMAGE_FORMAT_RAW_UINT16	RAW for images directly from sensory.
DW_IMAGE_FORMAT_RAW_FLOAT16	for debayered images

Definition at line 122 of file Image.h.

dwImageMemoryType

enum dwImageMemoryType

Specifies memory type layout.

Enumerator
DW_IMAGE_MEMORY_TYPE_DEFAULT	the default memory layout for a given image type, can be either pitch or block
DW_IMAGE_MEMORY_TYPE_PITCH	pitch linear memory layout
DW_IMAGE_MEMORY_TYPE_BLOCK	block memory layout

Definition at line 201 of file Image.h.

dwImageMetaDataFlags

enum dwImageMetaDataFlags

Flags defining the meta information available in an image.

Enumerator
DW_IMAGE_FLAGS_EMBEDDED_LINES	If an image was extracted from a camera, additional embedded data lines might be provided The data lines are stored before and after the actual image content in memory Note manually setting this flag will influence the image creation by allocating the specified number of datalines in dwImageDatalines.
DW_IMAGE_FLAGS_SENSOR_SETTINGS	Image contains valid sensor settings information, such as exposure, gain, whitebalance, etc.
DW_IMAGE_FLAGS_FRAME_SEQUENCE_NUMBER	Image contains valid frame sequence number.
DW_IMAGE_FLAGS_SYSMEM	By default CUDA images are created in vidmem on DGPU, this flag forces CUDA image to sysmem Note manually setting this flag will influence the image allocation as per description.
DW_IMAGE_FLAGS_HAS_RAW_ORDER_DESCRIPTOR	Image contains details of raw order descriptor. This is valid only if the image has format DW_IMAGE_FORMAT_RAW_X. Note manually setting this flag will influence the image creation, selecting the raw order described for a DW_IMAGE_FORMAT_RAW
DW_IMAGE_FLAGS_CONTROLINFO	Holds a flag to determine whether or not the control info is valid. If no ISP processing occurs this value is false.
DW_IMAGE_FLAGS_LUMINANCE_CALIBRATED	Holds a flag to indicating if the luminance is calibrated.
DW_IMAGE_FLAGS_TOTAL_WHITE_BALANCE_GAIN	Holds the total white balance gains, which includes both sensor channel and ISP gains.
DW_IMAGE_FLAGS_GTM_SPLINE_INFO	Image contains valid global tone map block.
DW_IMAGE_FLAGS_SENSOR_TEMPERATURE	Image contains valid sensor temperature info.
DW_IMAGE_FLAGS_NVSCI_SURF_ATTR	Image contains NvSci surface based attributes.
DW_IMAGE_FLAGS_MAPS_CUPVA	Image maps pointer to CUPVA.

Definition at line 227 of file Image.h.

dwImageType

enum dwImageType

Specifies the image type.

Enumerator
DW_IMAGE_CPU
DW_IMAGE_CUDA
DW_IMAGE_NVMEDIA
DW_IMAGE_GL	This type is provided here for completeness only. It will not function on any image API as provided by this SDK. For DW_IMAGE_GL images to function properly APIs from dwgl library are required.

Definition at line 96 of file Image.h.

dwSyncType

enum dwSyncType

Enum representing a sync type.

Currently it represents synchronization methods for NvSci based buffers with HW engines like GPU or Drive platform VIC

Enumerator
DW_SYNC_TYPE_WAITER
DW_SYNC_TYPE_SIGNALER

Definition at line 84 of file Image.h.

Function Documentation

dwImage_copyConvert()

DW_API_PUBLIC dwStatus dwImage_copyConvert	(	dwImageHandle_t const	output,
		dwConstImageHandle_t const	input,
		dwContextHandle_t const	context
	)

Converts CUDA or NvMedia images by copying into an output image, following the properties in the output image.

The output image must have been memory allocated (see 'dwImage_create'). Note that both images must be of the same type. If the properties and memory layout of both images are the same, an identical copy of the input image onto the output image is performed. The sizes must match (for conversion with resize, see dwImageTransformation under dw/imageprocessing/geometry). The conversion is performed, for both image types using DW's GPU kernel implementations. For use of the VIC engine via NvMedia2D, refer to dwImageTransformation.

Parameters

[out]	output	A pointer to the output image.
[in]	input	A pointer to the input image.
[in]	context	The sdk context.

Returns

DW_INVALID_ARGUMENT if the provided pointers are null, or the provided images cannot be used.
DW_BAD_CAST if the image is not a cuda/nvmedia image
DW_CUDA_ERROR if the CUDA conversion fails, it is possible to recover this situation by switching to DW_IMAGE_NVMEDIA as input images
or DW_SUCCESS otherwise.

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwImage_copyConvertAsync()

DW_API_PUBLIC dwStatus dwImage_copyConvertAsync	(	dwImageHandle_t const	output,
		dwConstImageHandle_t const	input,
		cudaStream_t const	stream,
		dwContextHandle_t const	context
	)

Converts CUDA or NvMedia images by copying into an output image, following the properties in the output image.

The output image must have been memory allocated (see 'dwImage_create'). Note that both images must be of the same type. If the properties and memory layout of both images are the same, an identical copy of the input image onto the output image is performed. The sizes must match (for conversion with resize, see dwImageTransformation under dw/imageprocessing/geometry). The conversion is performed, for both image types using DW's GPU kernel implementations. For use of the VIC engine via NvMedia2D, refer to dwImageTransformation.

Parameters

[out]	output	A pointer to the output image.
[in]	input	A pointer to the input image.
[in]	stream	The CUDA stream for executing the conversion kernel. Note this is ignored in case of NvMedia
[in]	context	The sdk context.

Returns

DW_INVALID_ARGUMENT if the provided pointers are null,
DW_BAD_CAST if the image is not a cuda/nvmedia image
DW_CUDA_ERROR if the CUDA conversion fails,
or DW_SUCCESS otherwise.

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwImage_create()

DW_API_PUBLIC dwStatus dwImage_create	(	dwImageHandle_t *const	image,
		dwImageProperties	properties,
		dwContextHandle_t const	ctx
	)

Creates and allocates resources for a dwImageHandle_t based on the properties passed as input.

Parameters

[out]	image	A handle to the image
[in]	properties	The image properties.
[in]	ctx	The DriveWorks context.

Returns

DW_SUCCESS if the image was created successfully
DW_INVALID_ARGUMENT if the given image types are invalid or the streamer pointer is null
DW_INVALID_HANDLE if the given context handle is invalid, i.e null or of wrong type

API Group

• Init: Yes
• Runtime: No
• De-Init: No

dwImage_createAndBindBuffer()

DW_API_PUBLIC dwStatus dwImage_createAndBindBuffer	(	dwImageHandle_t *const	image,
		dwImageProperties	properties,
		void *const	buffersIn[DW_MAX_IMAGE_PLANES],
		size_t const	pitches[DW_MAX_IMAGE_PLANES],
		size_t const	bufferCount,
		dwContextHandle_t const	ctx
	)

Creates a dwImageHandle_t based on the properties passed and binds a memory buffer provided by the application.

Valid only for types of DW_IMAGE_CPU and DW_IMAGE_CUDA with DW_IMAGE_LAYOUT_PITCH (or DEFAULT) layout.

Parameters

[out]	image	A handle to the image
[in]	properties	The image properties.
[in]	buffersIn	An array of pointers to individual buffers.
[in]	pitches	An array of pitches for each buffer.
[in]	bufferCount	The number of buffers (maximum is DW_MAX_IMAGE_PLANES).
[in]	ctx	The DriveWorks context.

Returns

DW_SUCCESS if the image was created successfully
DW_INVALID_ARGUMENT if the given image properties are invalid or the image pointer is null or the buffer count is not equal to plane count
DW_INVALID_HANDLE if the given context handle is invalid, i.e null or of wrong type
DW_NOT_SUPPORTED if given image type is not supported (expecting only DW_IMAGE_CPU an DW_IMAGE_CUDA)

API Group

• Init: Yes
• Runtime: No
• De-Init: No

dwImage_createAndBindCUDAArray()

DW_API_PUBLIC dwStatus dwImage_createAndBindCUDAArray	(	dwImageHandle_t *const	image,
		dwImageProperties	properties,
		cudaArray_t const	buffers[DW_MAX_IMAGE_PLANES],
		size_t const	bufferCount,
		dwContextHandle_t const	ctx
	)

Creates a dwImageHandle_t based on the properties passed and binds a cudaArray_t to it.

Valid only for types of DW_IMAGE_CUDA with DW_IMAGE_LAYOUT_BLOCK layout

Parameters

[out]	image	A handle to the image
[in]	properties	The image properties.
[in]	buffers	An array of pointers to cudaArray_t.
[in]	bufferCount	The number of buffers (maximum is DW_MAX_IMAGE_PLANES).
[in]	ctx	The DriveWorks context.

Returns

DW_SUCCESS if the image was created successfully
DW_INVALID_ARGUMENT if the given image types are invalid or the buffer is null
DW_INVALID_HANDLE if the given context handle is invalid, i.e null or of wrong type

API Group

• Init: Yes
• Runtime: No
• De-Init: No

dwImage_createAndBindNvSciBuf()

DW_API_PUBLIC dwStatus dwImage_createAndBindNvSciBuf	(	dwImageHandle_t *const	image,
		dwImageProperties const *	properties,
		NvSciBufObj	nvscibufObj,
		dwContextHandle_t const	ctx
	)

Creates a dwImageHandle_t based on the properties passed and binds a memory buffer provided by the application.

The given NvSciBufObj must have been allocated with attributes compatible with the given image properties.

Note

The memory buffer lifetime is still controlled by the application. The application must take care that the buffer is not freed until the returned dwImageHandle_t is freed.

Parameters

[out]	image	A handle to the image
[in]	properties	The image properties.
[in]	nvscibufObj	The NvSciBufObj to bind to.
[in]	ctx	The DriveWorks context.

Returns

DW_SUCCESS if the image was created,
DW_NOT_SUPPORTED if the platform does not support this API
DW_INVALID_ARGUMENT if the given image types are invalid or the image pointer is null.

API Group

• Init: Yes
• Runtime: No
• De-Init: No

dwImage_destroy()

DW_API_PUBLIC dwStatus dwImage_destroy

(

dwImageHandle_t const

image

)

Destroys the image handle and frees any memory created by dwImage_create().

If the image was created with createAndBindX, it will unbind the memory and delete the handle without freeing the buffers

Parameters

[in]

image

A handle to the image

Returns

DW_SUCCESS if the image was destroyed
DW_INVALID_HANDLE if the given image handle is invalid, i.e null or of wrong type

API Group

• Init: Yes
• Runtime: No
• De-Init: Yes

dwImage_getCPU()

DW_API_PUBLIC dwStatus dwImage_getCPU	(	dwImageCPU **const	imageCPU,
		dwImageHandle_t const	image
	)

Retrieves the dwImageCPU of a dwImageHandle_t.

The image must have been created as a DW_IMAGE_CPU type.

Parameters

[out]	imageCPU	A pointer to the dwImageCPU pointer
[in]	image	A handle to the image

Returns

DW_SUCCESS if the dwImageCPU is successfully retrieved,
DW_INVALID_ARGUMENT if the given image pointer is null,
DW_INVALID_HANDLE if the given image handle is invalid, i.e null or of wrong type

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwImage_getCUDA()

DW_API_PUBLIC dwStatus dwImage_getCUDA	(	dwImageCUDA **const	imageCUDA,
		dwImageHandle_t const	image
	)

Retrieves the dwImageCUDA of a dwImageHandle_t.

The image must have been created as a DW_IMAGE_CUDA type.

Parameters

[out]	imageCUDA	A pointer to the dwImageCUDA pointer
[in]	image	A handle to the image

Returns

DW_SUCCESS if the dwImageCUDA is successfully retrieved,
DW_INVALID_ARGUMENT if the given image pointer or image handle is null

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwImage_getDataLayout()

DW_API_PUBLIC dwStatus dwImage_getDataLayout	(	size_t *const	elementSize,
		size_t *const	planeCount,
		uint32_t	planeChannelCount[DW_MAX_IMAGE_PLANES],
		dwVector2ui	planeSize[DW_MAX_IMAGE_PLANES],
		dwImageProperties const *const	prop
	)

Returns the expected data layout of an image given its properties.

The byte size for plane i's row is:

elementSize*planeChannelCount[i]*planeWidth[i]

Parameters

[out]	elementSize	Size in bytes of the pixel type
[out]	planeCount	Number of planes
[out]	planeChannelCount	Number of channels within each plane
[out]	planeSize	Size of each plane
[in]	prop	A pointer to the image properties to compute data layout from.

Returns

DW_INVALID_ARGUMENT - if channel count or plane size or properties are invalid or NULL
DW_SUCCESS - if operation completed successfully

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwImage_getMetaData()

DW_API_PUBLIC dwStatus dwImage_getMetaData	(	dwImageMetaData *const	metaData,
		dwConstImageHandle_t const	image
	)

Retrieves the metadata of a dwImageHandle_t.

Parameters

[out]	metaData	A pointer to the metadata
[in]	image	A handle to the image

Returns

DW_SUCCESS if operation completed successfully
DW_INVALID_ARGUMENT if the given metadaa pointer is null,
DW_INVALID_HANDLE if the given image handle is invalid,i.e null or of wrong type

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwImage_getNvMedia()

DW_API_PUBLIC dwStatus dwImage_getNvMedia	(	dwImageNvMedia **	imageNvMedia,
		dwImageHandle_t	image
	)

Retrieves the dwImageNvMedia of a dwImageHandle_t.

The image must have been created as a DW_IMAGE_NVEMDIA type.

Parameters

[out]	imageNvMedia	A pointer to the dwImageNvMedia pointer
[in]	image	A handle to the image

Returns

DW_SUCCESS if the dwImageNvMedia is successfully retrieved,
DW_INVALID_ARGUMENT if the given image pointer is null,
DW_INVALID_HANDLE if the given image handle is invalid,null or of wrong type

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwImage_getNvSciBuf()

DW_API_PUBLIC dwStatus dwImage_getNvSciBuf	(	NvSciBufObj *	nvSciBufObj,
		dwImageHandle_t	image
	)

Retrieve the NvSciBufObj backing the image allocation.

Parameters

[out]	nvSciBufObj	pointer to output NvSciBufObj.
[in]	image	A handle to the image.

Returns

DW_SUCCESS if operation succeeded. DW_INVALID_ARGUMENT if nvSciBufObj or image is null. DW_NOT_AVAILABLE if image is not backed by NvSciBufObj.

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwImage_getPixelType()

DW_API_PUBLIC dwStatus dwImage_getPixelType	(	dwTrivialDataType *const	type,
		dwImageFormat const	format
	)

Retrieves dwTrivialDataType associated with a specific format.

Parameters

[out]	type	The datatype
[in]	format	The format

Returns

DW_SUCCESS if operation completed successfully
DW_INVALID_ARGUMENT if the given pointer is null

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwImage_getPlaneCount()

DW_API_PUBLIC dwStatus dwImage_getPlaneCount	(	size_t *const	planeCount,
		dwImageFormat const	format
	)

Retrieves number of planes of the image format.

Parameters

[out]	planeCount	The plane count
[in]	format	The format

Returns

DW_SUCCESS if operation completed successfully
DW_INVALID_ARGUMENT if the given pointer is null

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwImage_getProperties()

DW_API_PUBLIC dwStatus dwImage_getProperties	(	dwImageProperties *const	properties,
		dwConstImageHandle_t const	image
	)

Retrieves the properties of a dwImageHandle_t.

Parameters

[out]	properties	A pointer to the properties
[in]	image	A handle to the image

Returns

DW_SUCCESS if operation completed successfully
DW_INVALID_HANDLE if the given image handle is invalid, i.e null or of wrong type

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwImage_getTimestamp()

DW_API_PUBLIC dwStatus dwImage_getTimestamp	(	dwTime_t *const	timestamp,
		dwConstImageHandle_t const	image
	)

Retrieves the timestamp of acquisition of a dwImageHandle_t.

Parameters

[out]	timestamp	A pointer to the timestamp
[in]	image	A handle to the image

Returns

DW_SUCCESS if operation completed successfully
DW_INVALID_HANDLE if the given image handle is invalid,i.e null or of wrong type

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwImage_setMetaData()

DW_API_PUBLIC dwStatus dwImage_setMetaData	(	dwImageMetaData const *const	metaData,
		dwImageHandle_t const	image
	)

Sets the metadata of a dwImageHandle_t.

Parameters

[in]	metaData	A pointer to the metadata
[in]	image	A handle to the image

Returns

DW_SUCCESS if operation completed successfully
DW_INVALID_HANDLE if the given image handle is invalid, i.e null or of wrong type

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwImage_setTimestamp()

DW_API_PUBLIC dwStatus dwImage_setTimestamp	(	dwTime_t const	timestamp,
		dwImageHandle_t const	image
	)

Sets the timestamp of a dwImageHandle_t.

Parameters

[out]	timestamp	Timestamp to be set
[in]	image	A handle to the image

Returns

DW_SUCCESS if operation completed successfully
DW_INVALID_HANDLE if the given image handle is invalid,i.e null or of wrong type

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwImageCUDA_getPlaneAsImage()

DW_API_PUBLIC dwStatus dwImageCUDA_getPlaneAsImage	(	dwImageCUDA *const	planeImage,
		dwImageCUDA const *const	srcImage,
		uint32_t const	planeIdx
	)

Returns a specific plane of a CUDA image as its own single-plane CUDA image.

No data is copied, only the pointers are duplicated.

Parameters

[out]	planeImage	'dwImageCUDA' to be filled with a single plane from 'srcImage'
[in]	srcImage	Source image to extract plane from
[in]	planeIdx	Index of the plane to extract

Returns

DW_INVALID_ARGUMENT - if planeImage or srcImage are NULL, or if planeIdx is invalid
DW_SUCCESS - if operation completed successfully

dwImageCUDA_mapToROI()

DW_API_PUBLIC dwStatus dwImageCUDA_mapToROI	(	dwImageCUDA *const	dstImg,
		dwImageCUDA const *const	srcImg,
		dwRect const	roi
	)

Returns a dwImageCUDA that is mapped to a region of interest in the data of the srcImg.

NOTE: only single plane images are supported.

Parameters

[out]	dstImg	A pointer to the dwImageCUDA containing the roi. NOTE: the properties will reflect the size of the roi. (NOTE: this is not a copy)
[in]	srcImg	A pointer to the source dwImageCUDA.
[in]	roi	A dwRect specifying the coordinates of the region of interest.

Returns

DW_SUCCESS - if operation completed successfully
DW_INVALID_ARGUMENT - if any of the passed pointers are null