Zivid::ComputeDevice Class Reference

Contains information about the compute device used by Zivid::Application. More...

#include <Zivid/ComputeDevice.h>

Public Member Functions
ZIVID_CORE_EXPORT	ComputeDevice ()
	Constructor.
ZIVID_CORE_EXPORT	~ComputeDevice ()
	Destructor.
ZIVID_CORE_EXPORT	ComputeDevice (const ComputeDevice &other)
	Copy constructor.
ZIVID_CORE_EXPORT ComputeDevice &	operator= (const ComputeDevice &other)
	Assignment operator.
ZIVID_CORE_EXPORT	ComputeDevice (ComputeDevice &&other) noexcept
	Move constructor.
ZIVID_CORE_EXPORT ComputeDevice &	operator= (ComputeDevice &&other) noexcept
	Move assignment operator.
ZIVID_CORE_EXPORT std::string	model () const
	Returns the model name of this compute device.
ZIVID_CORE_EXPORT std::string	vendor () const
	Returns the vendor of this compute device.
ZIVID_CORE_EXPORT ComputeBackend	backend () const
	Returns the backend type of this compute device.
ZIVID_CORE_EXPORT void *	nativeContext () const
	Get native context handle for interop with GPU APIs.
ZIVID_CORE_EXPORT void *	nativeStreamHandle () const
	Get native stream/queue handle for advanced GPU interop.
ZIVID_CORE_EXPORT StreamOrQueue	sdkStreamOrQueue () const
	Get the SDK's internal stream/queue as a backend-agnostic StreamOrQueue.
template<typename Format, typename = std::enable_if_t<Detail::SupportedDeviceArrayViewFormat<Format>::value>>
ZIVID_CORE_EXPORT DeviceArrayView< Format >	createDeviceArrayView (CUDADevicePointer cudaPointer, size_t width, size_t height, CUDAStreamPtr stream) const
	Create a DeviceArrayView<Format> over an externally-owned CUDA device pointer.
template<typename Format, typename = std::enable_if_t<Detail::SupportedDeviceArrayViewFormat<Format>::value>>
ZIVID_CORE_EXPORT DeviceArrayView< Format >	createDeviceArrayView (OpenCLMemPointer openCLBuffer, size_t width, size_t height, OpenCLCommandQueuePtr queue) const
	Create a DeviceArrayView<Format> over an externally-owned OpenCL memory object.
ZIVID_CORE_EXPORT std::string	cudaRuntimeLibraryName () const
	Get the shared library name of the CUDA runtime that the SDK was built against.
ZIVID_CORE_EXPORT std::string	toString () const
	Get string representation of the compute device.

Detailed Description

Contains information about the compute device used by Zivid::Application.

Constructor & Destructor Documentation

ComputeDevice() [1/3]

ZIVID_CORE_EXPORT Zivid::ComputeDevice::ComputeDevice

(

)

Constructor.

~ComputeDevice()

ZIVID_CORE_EXPORT Zivid::ComputeDevice::~ComputeDevice

(

)

Destructor.

ComputeDevice() [2/3]

ZIVID_CORE_EXPORT Zivid::ComputeDevice::ComputeDevice

(

const ComputeDevice &

other

)

Copy constructor.

ComputeDevice() [3/3]

ZIVID_CORE_EXPORT Zivid::ComputeDevice::ComputeDevice ( ComputeDevice && other )

noexcept

Move constructor.

Member Function Documentation

backend()

ZIVID_CORE_EXPORT ComputeBackend Zivid::ComputeDevice::backend

(

)

const

Returns the backend type of this compute device.

createDeviceArrayView() [1/2]

template<typename Format, typename = std::enable_if_t<Detail::SupportedDeviceArrayViewFormat<Format>::value>>

ZIVID_CORE_EXPORT DeviceArrayView< Format > Zivid::ComputeDevice::createDeviceArrayView	(	CUDADevicePointer	cudaPointer,
		size_t	width,
		size_t	height,
		CUDAStreamPtr	stream ) const

Create a DeviceArrayView<Format> over an externally-owned CUDA device pointer.

Parameters

cudaPointer	Non-null CUDA device pointer
width	Width of the image in pixels
height	Height of the image in pixels
stream	The CUDA stream that the buffer's preparation work (allocation and any data production) was enqueued on.

Returns

A DeviceArrayView<Format> referencing the provided CUDA memory

The device pointer must be created using the same CUDA context that the Zivid SDK uses. The memory must contain tightly packed (interleaved) pixel data of width * height * sizeof(Format) bytes, with strides [width * sizeof(Format), sizeof(Format), sizeof(Format::ValueType)].

The view does not take ownership of the CUDA memory. The caller must keep the pointer valid for as long as the view (and any copies of it, or any buffer filled through it) is in use.

The stream exists solely so the SDK does not use the buffer before it is ready: this method records an event on stream and makes the SDK's internal compute stream wait on it, so any work already enqueued on stream (for example a stream-ordered cudaMallocAsync of the buffer) completes before the SDK touches the memory. The stream is not stored on the view; only this ordering is established. Pass the stream the buffer's preparation work is on. When the view is later passed to a fill variant (e.g. Frame2D::imageDeviceArray), that method takes its own StreamOrQueue for the result; it need not be the same stream.

Supported formats: the 4-channel ColorRGBA, ColorRGBA_SRGB, ColorBGRA, ColorBGRA_SRGB, ColorRGBAf; and the 3-channel ColorRGB, ColorRGB_SRGB, ColorBGR, ColorBGR_SRGB. The color formats are 3D (height * width * channels).

Only available when the compute backend is CUDA. Throws if called with an OpenCL backend.

createDeviceArrayView() [2/2]

template<typename Format, typename = std::enable_if_t<Detail::SupportedDeviceArrayViewFormat<Format>::value>>

ZIVID_CORE_EXPORT DeviceArrayView< Format > Zivid::ComputeDevice::createDeviceArrayView	(	OpenCLMemPointer	openCLBuffer,
		size_t	width,
		size_t	height,
		OpenCLCommandQueuePtr	queue ) const

Create a DeviceArrayView<Format> over an externally-owned OpenCL memory object.

Parameters

openCLBuffer	Non-null OpenCL memory object (cl_mem)
width	Width of the image in pixels
height	Height of the image in pixels
queue	The OpenCL command queue that the buffer's preparation work (allocation and any data production) was enqueued on.

Returns

A DeviceArrayView<Format> referencing the provided OpenCL memory

The OpenCL memory object must be created using the same OpenCL context that the Zivid SDK uses. The object must contain tightly packed (interleaved) pixel data of width * height * sizeof(Format) bytes, with strides [width * sizeof(Format), sizeof(Format), sizeof(Format::ValueType)].

The view does not take ownership of the OpenCL memory. The caller must keep the object valid for as long as the view (and any copies of it, or any buffer filled through it) is in use.

The queue exists solely so the SDK does not use the buffer before it is ready: this method records an event on queue and makes the SDK's internal command queue wait on it, so any work already enqueued on queue completes before the SDK touches the memory. The queue is not stored on the view; only this ordering is established. Pass the queue the buffer's preparation work is on. When the view is later passed to a fill variant, that method takes its own StreamOrQueue for the result; it need not be the same queue.

Supported formats: the 4-channel ColorRGBA, ColorRGBA_SRGB, ColorBGRA, ColorBGRA_SRGB, ColorRGBAf; and the 3-channel ColorRGB, ColorRGB_SRGB, ColorBGR, ColorBGR_SRGB. The color formats are 3D (height * width * channels).

Only available when the compute backend is OpenCL. Throws if called with a CUDA backend.

cudaRuntimeLibraryName()

ZIVID_CORE_EXPORT std::string Zivid::ComputeDevice::cudaRuntimeLibraryName

(

)

const

Get the shared library name of the CUDA runtime that the SDK was built against.

Returns

The platform-specific library name, e.g. "libcudart.so" on Linux or "cudart64_12.dll" on Windows

This is useful for loading the CUDA runtime via ctypes or similar foreign function interfaces when performing GPU interop (e.g. CUDA-OpenGL interop). The returned name is guaranteed to match the CUDA version that the SDK was compiled against.

Only available when the compute backend is CUDA.

Exceptions

std::runtime_error

If the compute backend is not CUDA

model()

ZIVID_CORE_EXPORT std::string Zivid::ComputeDevice::model

(

)

const

Returns the model name of this compute device.

nativeContext()

ZIVID_CORE_EXPORT void * Zivid::ComputeDevice::nativeContext

(

)

const

Get native context handle for interop with GPU APIs.

nativeStreamHandle()

ZIVID_CORE_EXPORT void * Zivid::ComputeDevice::nativeStreamHandle

(

)

const

Get native stream/queue handle for advanced GPU interop.

Returns

CUDA backend: Returns CUstream (cast to void*) OpenCL backend: Returns cl_command_queue (cast to void*)

This handle can be used for:

• Synchronizing with user GPU operations
• Submitting custom kernels on the same stream
• Checking stream completion status

The returned handle remains valid for the lifetime of the ComputeDevice. Users should NOT destroy this handle.

For user-provided contexts/streams, this returns the user-provided handle. For internally created contexts/streams, this returns the internal handle.

operator=() [1/2]

ZIVID_CORE_EXPORT ComputeDevice & Zivid::ComputeDevice::operator= ( ComputeDevice && other )

noexcept

Move assignment operator.

operator=() [2/2]

ZIVID_CORE_EXPORT ComputeDevice & Zivid::ComputeDevice::operator=

(

const ComputeDevice &

other

)

Assignment operator.

sdkStreamOrQueue()

ZIVID_CORE_EXPORT StreamOrQueue Zivid::ComputeDevice::sdkStreamOrQueue

(

)

const

Get the SDK's internal stream/queue as a backend-agnostic StreamOrQueue.

Returns

A StreamOrQueue whose backend-matching member wraps the native handle.

Portable alternative to constructing CUDAStreamPtr{ nativeStreamHandle() } or OpenCLCommandQueuePtr{ nativeStreamHandle() } directly. Use at acquisition sites (e.g. frame.imageDeviceArray<Format>(computeDevice.sdkStreamOrQueue())) when the caller does not have a user stream or queue and just wants the SDK's own stream/queue - the resulting sync is a self-sync on the SDK stream (cheap no-op).

toString()

ZIVID_CORE_EXPORT std::string Zivid::ComputeDevice::toString

(

)

const

Get string representation of the compute device.

Returns

Compute device info as string

vendor()

ZIVID_CORE_EXPORT std::string Zivid::ComputeDevice::vendor

(

)

const

Returns the vendor of this compute device.

---

The documentation for this class was generated from the following file:

• Zivid/ComputeDevice.h