Detailed Description

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

Data Structures
struct	dwImageStreamerCrossProcessModeParams
	Sets of parameters for cross-process image streamer creation. More...

Typedefs
typedef struct dwImageStreamerObject *	dwImageStreamerHandle_t

Enumerations
enum	dwImageStreamerCrossProcessMode { DW_IMAGE_STREAMER_CROSS_PROCESS_PRODUCER, DW_IMAGE_STREAMER_CROSS_PROCESS_CONSUMER }

Functions
DW_API_PUBLIC dwStatus	dwImageStreamer_consumerReceive (dwImageHandle_t *image, dwTime_t const timeoutUs, dwImageStreamerHandle_t const streamer)
	Receive a pointer to a dwImageHandle_t from the streamer, acting as a consumer. More...

DW_API_PUBLIC dwStatus	dwImageStreamer_consumerReturn (dwImageHandle_t *image, dwImageStreamerHandle_t const streamer)
	Return the received image back to the producer. More...

DW_API_PUBLIC dwStatus	dwImageStreamer_getCUDAStream (cudaStream_t *stream, dwImageStreamerHandle_t streamer)
	Get CUDA stream used by the image streamer. More...

DW_API_PUBLIC dwStatus	dwImageStreamer_getOutputProperties (dwImageProperties *props, dwImageStreamerHandle_t const streamer)
	Get image properties of the image received from the streamer. More...

DW_API_PUBLIC dwStatus	dwImageStreamer_initialize (dwImageStreamerHandle_t streamer, const dwImageProperties from, dwImageType to, dwContextHandle_t ctx)
	Creates and initializes the image streamer capable of moving images between different API types. More...

DW_API_PUBLIC dwStatus	dwImageStreamer_initializeCrossProcess (dwImageStreamerHandle_t streamer, const dwImageProperties from, dwImageType to, dwImageStreamerCrossProcessModeParams params, dwContextHandle_t ctx)
	Creates and initializes the image streamer capable of moving images between different API types across processes. More...

DW_API_PUBLIC dwStatus	dwImageStreamer_producerReturn (dwImageHandle_t *const image, dwTime_t const timeoutUs, dwImageStreamerHandle_t const streamer)
	The producer streamer waits for the image sent to be returned by the consumer. More...

DW_API_PUBLIC dwStatus	dwImageStreamer_producerSend (dwImageHandle_t image, dwImageStreamerHandle_t const streamer)
	Sends an image through the streamer acting as the producer. More...

DW_API_PUBLIC dwStatus	dwImageStreamer_release (dwImageStreamerHandle_t streamer)
	Releases the image streamer. More...

DW_API_PUBLIC dwStatus	dwImageStreamer_setCUDAStream (cudaStream_t stream, dwImageStreamerHandle_t streamer)
	Sets the CUDA stream for CUDA related streaming operations such as post and receive. More...

Data Structure Documentation

◆ dwImageStreamerCrossProcessModeParams

struct dwImageStreamerCrossProcessModeParams

Data Fields

dwImageStreamerCrossProcessMode mode Operation mode of the cross-process image streamer.

const char *

parameters

Array to additional parameters provided to cross-process image streamer creation.

In general, this array has a form of key/value pairs separated by commas, i.e., mode=socket,file=/tmp/file.socket.

If no key=value pair is found, the default behavior is to assume file socket based streamer with the parameters string indicating the file name of the file socket.

Typedef Documentation

◆ dwImageStreamerHandle_t

typedef struct dwImageStreamerObject* dwImageStreamerHandle_t

Definition at line 61 of file ImageStreamer.h.

Enumeration Type Documentation

◆ dwImageStreamerCrossProcessMode

enum dwImageStreamerCrossProcessMode

Cross-process image streamer operation modes.

Enumerator
DW_IMAGE_STREAMER_CROSS_PROCESS_PRODUCER
DW_IMAGE_STREAMER_CROSS_PROCESS_CONSUMER

Definition at line 66 of file ImageStreamer.h.

Function Documentation

◆ dwImageStreamer_consumerReceive()

DW_API_PUBLIC dwStatus dwImageStreamer_consumerReceive	(	dwImageHandle_t *	image,
		dwTime_t const	timeoutUs,
		dwImageStreamerHandle_t const	streamer
	)

Receive a pointer to a dwImageHandle_t from the streamer, acting as a consumer.

Can wait until timeout before failing.

Parameters

[out]	image	A pointer to a dwImageHandle_t sent by the producer, not null if successfully converted.
[in]	timeout_us	Timeout in milliseconds before interrupting the waiting for producer.
[in]	streamer	A handle to the image streamer.

Returns: DW_INVALID_ARGUMENT if the given image handle is NULL
DW_INVALID_HANDLE if the given streamer handle (consumer) is invalid, i.e. null or of wrong type
DW_TIME_OUT if times out
or DW_SUCCESS otherwise.

◆ dwImageStreamer_consumerReturn()

DW_API_PUBLIC dwStatus dwImageStreamer_consumerReturn	(	dwImageHandle_t *	image,
		dwImageStreamerHandle_t const	streamer
	)

Return the received image back to the producer.

Ownership is given back and image goes back to null

Parameters

[in]	image	A pointer to the dwImageHandle_t to return to the producer.
[in]	streamer	A handle to the image streamer.

Returns: DW_INVALID_HANDLE if the given streamer handle (consumer) is invalid, i.e. null or of wrong type
DW_INTERNAL_ERROR if the image has been received yet or an underlying error depending on the producer/consumer combination has occurred
or DW_SUCCESS otherwise.

◆ dwImageStreamer_getCUDAStream()

DW_API_PUBLIC dwStatus dwImageStreamer_getCUDAStream	(	cudaStream_t *	stream,
		dwImageStreamerHandle_t	streamer
	)

Get CUDA stream used by the image streamer.

Parameters

[out]	stream	CUDA stream used by the streamer
[in]	streamer	A handle to the image streamer.

Returns: DW_INVALID_HANDLE if the given context handle is invalid,i.e null or of wrong type
DW_NOT_SUPPORTED if the streamer does not work with CUDA images,
or DW_SUCCESS otherwise.

◆ dwImageStreamer_getOutputProperties()

DW_API_PUBLIC dwStatus dwImageStreamer_getOutputProperties	(	dwImageProperties *	props,
		dwImageStreamerHandle_t const	streamer
	)

Get image properties of the image received from the streamer.

Parameters

[out]	props	Properties of the resulting images
[in]	streamer	A handle to the image streamer.

Returns: DW_INVALID_HANDLE if the given context handle is invalid,i.e null or of wrong type
DW_SUCCESS if successful.

Note: An image streamer does not modify the pixel format or pixel type, however, meta information as well as sizes might differ. For example an image containing embedded lines, will be most probably unfolded, i.e. the datalines will become part of the image in the new domain.

◆ dwImageStreamer_initialize()

DW_API_PUBLIC dwStatus dwImageStreamer_initialize	(	dwImageStreamerHandle_t *	streamer,
		const dwImageProperties *	from,
		dwImageType	to,
		dwContextHandle_t	ctx
	)

Creates and initializes the image streamer capable of moving images between different API types.

For example an image can be moved from NvMedia API into GL textured type or from CPU memory to CUDA.

In general an image streamer does not perform any modifications on the format of the stored pixel data. However, in certain cases when going between APIs some meta information might be lost or transformed. Especially if an image contains embedded data lines, in some cases the embedded information is lost, while in others it became part of the image. To find all supported src/dst pairs as well as supported formats refer to the user guide. After successful streamer creation 'dwImageStreamer_getOutputProperties()' will return the expected properties of resulting images.

Parameters

[out]	streamer	A handle to the image streamer (if successfully initialized.)
[in]	from	The properties of the source image for streaming.
[in]	to	The type of the destination image.
[in]	ctx	The DriveWorks context.

Returns: DW_SUCCESS if the translator 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
DW_NOT_IMPLEMENTED if the desired streamer between given types is not implemented,
DW_NOT_AVAILABLE if the desired streamer between given two types is currently not available due to missing resources or non-initialized APIs,
or DW_NOT_SUPPORTED if the desired streamer cannot work with given pixel format or type.

◆ dwImageStreamer_initializeCrossProcess()

DW_API_PUBLIC dwStatus dwImageStreamer_initializeCrossProcess	(	dwImageStreamerHandle_t *	streamer,
		const dwImageProperties *	from,
		dwImageType	to,
		dwImageStreamerCrossProcessModeParams	params,
		dwContextHandle_t	ctx
	)

Creates and initializes the image streamer capable of moving images between different API types across processes.

Note: DW_IMAGE_STREAMER_CROSS_PROCESS_CONSUMER must be initialized before DW_IMAGE_STREAMER_CROSS_PROCESS_PRODUCER.

Parameters

[out]	streamer	A handle to the image streamer (if successfully initialized.)
[in]	from	The type of the source image and the expected image properties.
[in]	to	The type of the destination image.
[in]	params	Specifies the parameters for cross-process image streamer creation.
[in]	ctx	The DriveWorks context.

Returns: DW_SUCCESS if the translator 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
DW_NOT_IMPLEMENTED if the desired streamer between given types is not implemented,
DW_NOT_AVAILABLE if the desired streamer between given two types is currently not available due to missing resources or non-initialized APIs,
or DW_NOT_SUPPORTED if the desired streamer cannot work with given pixel format or type.

◆ dwImageStreamer_producerReturn()

DW_API_PUBLIC dwStatus dwImageStreamer_producerReturn	(	dwImageHandle_t *const	image,
		dwTime_t const	timeoutUs,
		dwImageStreamerHandle_t const	streamer
	)

The producer streamer waits for the image sent to be returned by the consumer.

Waits for a max timeout. Returns a pointer to the dwImageHandle of the returned image, if the pointer passed is not null, otherwise it does not return a pointer

Parameters

[out]	image	A pointer to a dwImageHandle_t returned by the producer
[in]	timeout_us	Timeout in milliseconds before interrupting the waiting and return a timeout error. Image was not returned
[in]	streamer	A handle to the image streamer.

Returns: DW_INVALID_ARGUMENT if the given streamer handle (producer) is null
DW_INVALID_HANDLE if the given streamer handle (producer) is invalid,i.e. of wrong type
DW_TIME_OUT if times out
or DW_SUCCESS otherwise.

◆ dwImageStreamer_producerSend()

DW_API_PUBLIC dwStatus dwImageStreamer_producerSend	(	dwImageHandle_t	image,
		dwImageStreamerHandle_t const	streamer
	)

Sends an image through the streamer acting as the producer.

Note: The ownership of the image remains by the caller.

Parameters

[in]	image	A dwImageHandle_t to send through the streamer
[in]	streamer	A handle to the image streamer.

Returns: DW_INVALID_HANDLE if the given streamer handle (producer) is invalid,i.e. of wrong type
DW_INVALID_ARGUMENT if the given streamer handle (producer) or the image handle is NULL
DW_INVALID_HANDLE if the dwImageType of the input image doesn't match the streamer's
DW_BUSY_WAITING if the image cannot be sent. Non fatal error, it is possible to retry
or DW_SUCCESS otherwise.

◆ dwImageStreamer_release()

DW_API_PUBLIC dwStatus dwImageStreamer_release ( dwImageStreamerHandle_t streamer )

Releases the image streamer.

This releases all memory and closes all related resources. The handle is set to null.

Parameters

[in] streamer A handle to the image streamer.

Returns: DW_SUCCESS if successful.

◆ dwImageStreamer_setCUDAStream()

DW_API_PUBLIC dwStatus dwImageStreamer_setCUDAStream	(	cudaStream_t	stream,
		dwImageStreamerHandle_t	streamer
	)

Sets the CUDA stream for CUDA related streaming operations such as post and receive.

Note: The ownership of the stream remains by the callee.

Parameters

[in]	stream	The CUDA stream to be used. Default is 0.
[in]	streamer	A handle to the image streamer.

Returns: DW_INVALID_HANDLE if the given context handle is invalid,i.e null or of wrong type
DW_NOT_SUPPORTED if the streamer does not work with CUDA images,
or DW_SUCCESS otherwise.

Detailed Description

Data Structures

Typedefs

Enumerations

Functions

Data Structure Documentation

◆ dwImageStreamerCrossProcessModeParams

Typedef Documentation

◆ dwImageStreamerHandle_t

Enumeration Type Documentation

◆ dwImageStreamerCrossProcessMode

Function Documentation

◆ dwImageStreamer_consumerReceive()

◆ dwImageStreamer_consumerReturn()

◆ dwImageStreamer_getCUDAStream()

◆ dwImageStreamer_getOutputProperties()

◆ dwImageStreamer_initialize()

◆ dwImageStreamer_initializeCrossProcess()

◆ dwImageStreamer_producerReturn()

◆ dwImageStreamer_producerSend()

◆ dwImageStreamer_release()

◆ dwImageStreamer_setCUDAStream()