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

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

Macros
#define	DW_ISP_MAX_COLOR_COMPONENT   (4U)
#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
typedef struct dwImageObject *	dwImageHandle_t
typedef uint32_t	GLenum
typedef uint32_t	GLuint

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

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_createAndBindNvMedia (dwImageHandle_t *image, NvMediaImage *nvmImage)
	Creates a dwImageHandle_t based on an nvmedia image. 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_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

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, when the image was acquired.

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, when the image was acquired.

dwImageDataLines

struct dwImageDataLines

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

dwImageMetaData

struct dwImageMetaData

Data Fields
dwImageAllocationAttrListHandle_t	allocAttrs	Allocation attributes used by internal drivers.
float32_t	analogGain	Specifies the analog Gain.
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[18U]	Holds the global tonemap block, containing a set of spline control points.
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
NvMediaImage *	img	Holds the pointer to the NvMedia image.
NvSciBufObj	imgBuf	Holds the pointer to the NvSciBufObj image.
dwImageProperties	prop	Holds image properties.
dwTime_t	timestamp_us	Specifies the time, in microseconds, when the image was acquired.

dwImagePool

struct dwImagePool

Data Fields
size_t	imageCount
dwImageHandle_t *	images

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.

dwImageSensorStatistics

struct dwImageSensorStatistics

Data Fields
float32_t	alpha	Holds power factor for isp statistics compression. Valid range: [0.5, 1.0].
float32_t	analogGain	Specifies the analog Gain.
float32_t	autoAwbGainGain[DW_ISP_MAX_COLOR_COMPONENT]	Holds the total white balance gains, which includes both sensor channel and ISP gains.
float32_t	brightnessKey	Holds the scene brightness key.
float32_t	cct	Holds the correlated color temperature.
float32_t	conversionGain	Specifies the conversion Gain.
float32_t	digitalGain	Specifies the digital Gain.
float32_t	exposureTime	Specifies the exposure time (microsecond)
float64_t	luminanceCalibrationFactor	Holds luminance constant (aperture^2/Kc) value for calibrated camera.
uint8_t	numTemperatures	Holds the number of active temperatures. Valid only if DW_IMAGE_FLAGS_SENSOR_TEMPERATURE is enabled. Value range: [1, DEVBLK_CDI_MAX_NUM_TEMPERATURES]. The DEVBLK_CDI_MAX_NUM_TEMPERATURES 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.
float32_t	rawImageMidTone	Holds the midtone value of the raw image.
float32_t	sensorTempCelsius[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 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)

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.

Macro Definition Documentation

DW_ISP_MAX_COLOR_COMPONENT

#define DW_ISP_MAX_COLOR_COMPONENT   (4U)

Definition at line 92 of file Image.h.

DW_MAX_IMAGE_PLANES

#define DW_MAX_IMAGE_PLANES   3

Definition at line 91 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 94 of file Image.h.

Typedef Documentation

dwConstImageHandle_t

typedef struct dwImageObject const* dwConstImageHandle_t

Definition at line 110 of file Image.h.

dwImageAllocationAttrListHandle_t

typedef struct dwImageAllocationAttrList* dwImageAllocationAttrListHandle_t

Definition at line 111 of file Image.h.

dwImageHandle_t

typedef struct dwImageObject* dwImageHandle_t

Definition at line 109 of file Image.h.

GLenum

typedef uint32_t GLenum

Definition at line 62 of file Image.h.

GLuint

typedef uint32_t GLuint

Definition at line 63 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
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_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 200 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.

Definition at line 224 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 97 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.

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.

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

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,
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)

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

dwImage_createAndBindNvMedia()

DW_API_PUBLIC dwStatus dwImage_createAndBindNvMedia	(	dwImageHandle_t *	image,
		NvMediaImage *	nvmImage
	)

Creates a dwImageHandle_t based on an nvmedia image.

Parameters

[out]	image	A handle to the image
[in]	nvmImage	The pointer to an NvMediaImage.

Returns

DW_SUCCESS if the image was created,
DW_INVALID_ARGUMENT if the given image types are invalid or the image pointer is null,

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

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 Note that any modification to the image retrieved will modify the content of the original handle

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

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. Note that any modification to the image retrieved will modify the content of the original handle

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,

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

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

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 Note that any modification to the image retrieved will modify the content of the original handle

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

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
DW_INVALID_ARGUMENT if the given pointer is null,

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
DW_INVALID_ARGUMENT if the given pointer is null,

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,
DW_INVALID_HANDLE if the given image handle is invalid, i.e null or of wrong type

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,
DW_INVALID_HANDLE if the given image handle is invalid,i.e null or of wrong type

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,
DW_INVALID_HANDLE if the given image handle is invalid, i.e null or of wrong type

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,
DW_INVALID_HANDLE if the given image handle is invalid,i.e null or of wrong type

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

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, DW_INVALID_ARGUMENT