Advanced: Data Access

        %%{init: {'themeVariables': {'fontSize': '18px'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 35}}}%%
flowchart LR
  Camera
  subgraph outputs [Outputs]
    PointCloud
    Frame
    Frame2D
  end
  subgraph cpu [Copy to CPU]
    copyPointsXYZOp(["copyPointsXYZ()"])
    copyColorsRGBAOp(["copyColorsRGBA()"])
    copyImageRGBA_SRGBOp(["copyImageRGBA_SRGB()"])
    morePCOp["…"]
    imageRGBAOp(["imageRGBA()"])
    Array2D["Array2D<T>"]
    Image["Image<T>"]
  end
  subgraph gpuBuf [GPU device buffers]
    imageDeviceArrayOp(["imageDeviceArray()"])
    devicePointsOp(["devicePointsXYZ()"])
    DeviceArray
  end

  Camera --> Frame
  PointCloud --> copyPointsXYZOp --> Array2D
  PointCloud --> copyColorsRGBAOp --> Array2D
  PointCloud --> copyImageRGBA_SRGBOp --> Image
  PointCloud --> morePCOp
  Frame2D --> imageRGBAOp --> Image
  Frame2D --> imageDeviceArrayOp --> DeviceArray
  Frame --> devicePointsOp --> DeviceArray

  classDef zividClass fill:#4A8FA4,stroke:#34323D,color:#FFFFFF
  classDef api fill:#91D2C8,stroke:#4A8FA4,color:#000000
  classDef moreClass fill:#FFFFFF,stroke:#4A8FA4,color:#4A8FA4,stroke-dasharray:5 5
  class Camera,PointCloud,Frame,Frame2D,Array2D,Image,DeviceArray zividClass
  class copyPointsXYZOp,copyColorsRGBAOp,copyImageRGBA_SRGBOp,imageRGBAOp,imageDeviceArrayOp,devicePointsOp api
  class morePCOp moreClass
    

Copy to CPU

After a capture, data lives in GPU memory. PointCloud exposes many copyPointsXYZ(), copyColorsRGBA(), copyImageRGBA(), and related methods to transfer selected channels to CPU-accessible buffers. Frame2D provides imageRGBA() for pure 2D captures. The full list of copy APIs is on the Applications Basic page.

GPU Device buffers

GPU device buffers for zero-copy interop with CUDA libraries such as CuPy, PyTorch, OpenCV CUDA, and OpenGL. Use these types after capture on Camera Basic when data should stay on the GPU instead of copying through host memory. Mirrors the GPU interop samples under {cpp,python}/source/camera/advanced/.

ComputeDevice

The compute device (CPU or GPU) used for SDK processing. Select a CUDA backend before requesting DeviceArray views of capture data.

C++

class ComputeDevice

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

Public Functions

ComputeDevice()

Constructor.

~ComputeDevice()

Destructor.

ComputeDevice(const ComputeDevice &other)

Copy constructor.

ComputeDevice &operator=(const ComputeDevice &other)

Assignment operator.

ComputeDevice(ComputeDevice &&other) noexcept

Move constructor.

ComputeDevice &operator=(ComputeDevice &&other) noexcept

Move assignment operator.

std::string model() const

Returns the model name of this compute device.

std::string vendor() const

Returns the vendor of this compute device.

ComputeBackend backend() const

Returns the backend type of this compute device.

void *nativeContext() const

Get native context handle for interop with GPU APIs.

void *nativeStreamHandle() const

Get native stream/queue handle for advanced GPU interop.

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.

Returns:

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

StreamOrQueue sdkStreamOrQueue() const

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

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

Returns:

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

template<typename Format, typename = std::enable_if_t<Detail::SupportedDeviceArrayViewFormat<Format>::value>>
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.

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; the 3-channel ColorRGB, ColorRGB_SRGB, ColorBGR, ColorBGR_SRGB; and the single-channel ColorGray8, ColorGray16, and Disparity. The single-channel formats are 2D (height * width), Disparity with strides in bytes [width * sizeof(Disparity), sizeof(Disparity)]; the multi-channel color formats are 3D (height * width * channels).

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

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

template<typename Format, typename = std::enable_if_t<Detail::SupportedDeviceArrayViewFormat<Format>::value>>
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.

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; the 3-channel ColorRGB, ColorRGB_SRGB, ColorBGR, ColorBGR_SRGB; and the single-channel ColorGray8, ColorGray16, and Disparity. The single-channel formats are 2D (height * width), Disparity with strides in bytes [width * sizeof(Disparity), sizeof(Disparity)]; the multi-channel color formats are 3D (height * width * channels).

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

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

std::string cudaRuntimeLibraryName() const

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

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.

Returns:

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

Throws:

std::runtime_error – If the compute backend is not CUDA

std::string toString() const

Get string representation of the compute device.

Returns:

Compute device info as string

C#

class ComputeDevice

Contains information about the ComputeDevice used by Application.

Public Functions

System::String ^ ToString () override

Get string representation of the application.

Returns:

Application info as string

DeviceArrayView< ColorRGBAf > ^ CreateDeviceArrayViewColorRGBAf (CUDADevicePointer cudaPointer, size_t width, size_t height, CUDAStreamPtr stream)

Create a non-owning DeviceArrayView of ColorRGBAf over an externally-owned CUDA device pointer.

The device pointer must be created using the same CUDA context used by the Zivid SDK. The memory must contain tightly packed (interleaved) RGBA float32 pixel data. The returned DeviceArrayView does not take ownership of the CUDA memory; the caller must keep the pointer valid for the lifetime of the view and any copies of it.

The stream exists solely so the SDK does not use the buffer before it is ready: an event is recorded on it and the SDK’s internal compute stream waits on it. The stream is not stored on the view. When the view is later passed to a fill variant, that method takes its own StreamOrQueue; it need not be the same stream.

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

Parameters:

• cudaPointer – Non-null CUDA device pointer to RGBA float32 data

• width – Width of the image in pixels

• height – Height of the image in pixels

• stream – The CUDA stream the buffer’s preparation work (allocation and any data production) was enqueued on

Returns:

A non-owning DeviceArrayView of ColorRGBAf referencing the provided CUDA memory

DeviceArrayView< ColorRGBAf > ^ CreateDeviceArrayViewColorRGBAf (OpenCLMemPointer openCLBuffer, size_t width, size_t height, OpenCLCommandQueuePtr queue)

Create a non-owning DeviceArrayView of ColorRGBAf over an externally-owned OpenCL memory object.

The memory object must be created using the same OpenCL context used by the Zivid SDK. The memory must contain tightly packed (interleaved) RGBA float32 pixel data. The returned DeviceArrayView does not take ownership of the OpenCL memory; the caller must keep the object valid for the lifetime of the view and any copies of it.

The queue exists solely so the SDK does not use the buffer before it is ready: an event is recorded on it and the SDK’s internal command queue waits on it. The queue is not stored on the view. When the view is later passed to a fill variant, that method takes its own StreamOrQueue; it need not be the same queue.

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

Parameters:

• openCLBuffer – Non-null OpenCL memory object (cl_mem) containing RGBA float32 data

• width – Width of the image in pixels

• height – Height of the image in pixels

• queue – The OpenCL command queue the buffer’s preparation work (allocation and any data production) was enqueued on

Returns:

A non-owning DeviceArrayView of ColorRGBAf referencing the provided OpenCL memory

Properties

System::String^ Vendor

Returns the vendor of this compute device.

System::String^ Model

Returns the model name of this compute device.

StreamOrQueue SdkStreamOrQueue

The SDK’s internal stream/queue as a backend-agnostic StreamOrQueue.

Pass this to the device-array accessors (e.g. PointCloud.DevicePointsXYZ) and to DeviceArray.ToArray2D / CopyToHost when you do not have your own user stream or queue.

Python

The Python API exposes zivid.ComputeDevice. See zivid-python for the full reference.

DeviceArray

A buffer that lives on the compute device. Obtain it from Frame2D, Frame, or PointCloud accessors such as imageDeviceArray() and devicePointsXYZ(), then pass the device pointer into your CUDA library without a host round-trip.

C++

template<typename Format>
class DeviceArray

Reference-counted handle to data on a GPU device.

The underlying device buffer is reference counted and will remain valid as long as any DeviceArray instance references it.

The buffer provides access to a raw device pointer that can be used with GPU compute frameworks (such as CUDA), compute libraries, or other GPU frameworks for efficient processing without CPU transfers.

Obtain a DeviceArray from a PointCloud using methods like devicePointsXYZ(), devicePointsXYZW(), deviceSNRs(), deviceNormalsXYZ(), deviceImageRGBA(), etc. The acquisition method takes a user stream or queue and synchronizes the SDK’s compute stream into it before returning. The returned DeviceArray is therefore already ordered against the caller’s stream/queue, and devicePointer() is a plain accessor.

Lifetime: a DeviceArray allocated by the SDK must not outlive the Zivid Application that produced it. For device memory that needs to outlive the Application, allocate the buffer yourself and pass it into the fill variant of the acquisition method (e.g. imageDeviceArray<Format>(streamOrQueue, destinationBuffer)).

Example usage:

// Acquire an XYZ buffer synchronized on the user's CUDA stream
auto xyzBuffer = pointCloud.devicePointsXYZ(Zivid::CUDAStreamPtr{ cudaStream });

// Access the raw device pointer - no additional sync needed
void *ptr = xyzBuffer.devicePointer();

Public Functions

DeviceArray() = default

Default constructor - creates an empty DeviceArray.

~DeviceArray() = default

Destructor - releases reference to the underlying buffer.

DeviceArray(const DeviceArray &other) = default

Copy constructor - shares ownership of the buffer.

DeviceArray &operator=(const DeviceArray &other) = default

Copy assignment - shares ownership of the buffer.

DeviceArray(DeviceArray &&other) noexcept = default

Move constructor.

DeviceArray &operator=(DeviceArray &&other) noexcept = default

Move assignment.

void *devicePointer() const

Get the raw GPU device pointer to the data.

No synchronization is performed. The DeviceArray was already synchronized against the caller’s stream/queue at acquisition time by the method that produced it (e.g. Frame2D::imageDeviceArray, PointCloud::devicePointsXYZ). Callers can use the pointer on that same stream/queue immediately.

The returned pointer is only valid as long as this DeviceArray (or a copy) exists, and only while the Zivid Application that produced the DeviceArray is alive.

Returns:

Raw device pointer (CUstream-typed for CUDA builds, cl_mem cast to void* for OpenCL).

std::vector<int> shape() const

Get the shape of the data.

std::vector<int> strides() const

Get the strides of the data in element count.

std::vector<int> stridesInBytes() const

Get the strides of the data in bytes.

size_t size() const

Get the total number of elements in the data.

size_t sizeInBytes() const

Get the total size of the data in bytes.

ComputeBackend backend() const

Get the GPU compute backend type of this buffer.

Returns:

The GPU compute backend (CUDA or OpenCL)

bool isValid() const

Check if the buffer is valid (not empty)

bool isEmpty() const

Check if the buffer is empty.

Array2D<Format> toArray2D(StreamOrQueue streamOrQueue) const

Copy device buffer data to host and return as Array2D.

Valid for all DeviceArray formats: PointXYZ, PointXYZW, PointZ, SNR, NormalXYZ, ColorRGBA, ColorRGBA_SRGB, ColorBGRA, ColorBGRA_SRGB, and ColorRGBAf. Throws an exception if the DeviceArray is not from an organized point cloud or from Frame2D.

The D2H copy is enqueued on streamOrQueue and the function returns immediately; the host memory behind the returned Array2D is NOT safe to read until the caller synchronizes streamOrQueue (e.g. via Zivid::synchronizeStream). Pass the same stream/queue that was used at acquisition (e.g. with PointCloud::devicePointsXYZ or Frame2D::imageDeviceArray) so the D2H copy is correctly ordered against the SDK’s compute.

If you don’t want to manage stream synchronization yourself, use the parameterless host accessors on the originating Frame2D / PointCloud (e.g. PointCloud::pointXYZArray, Frame2D::imageRGBA); those return host-ready Array2D / Image using the SDK’s internal stream.

Parameters:

streamOrQueue – The CUDA stream / OpenCL command queue to enqueue the D2H copy on

Returns:

Array2D of the Format type, holding host memory that has not yet been synchronized

Array1D<Format> toArray1D(StreamOrQueue streamOrQueue) const

Copy device buffer data to host and return as Array1D.

Valid for all DeviceArray formats: PointXYZ, PointXYZW, PointZ, SNR, NormalXYZ, ColorRGBA, ColorRGBA_SRGB, ColorBGRA, ColorBGRA_SRGB, and ColorRGBAf. Throws an exception if the DeviceArray is not from an unorganized point cloud.

The D2H copy is enqueued on streamOrQueue and the function returns immediately; the host memory behind the returned Array1D is NOT safe to read until the caller synchronizes streamOrQueue (e.g. via Zivid::synchronizeStream). For a blocking copy, use the parameterless host accessors on the originating UnorganizedPointCloud (e.g. UnorganizedPointCloud::pointsXYZ).

Parameters:

streamOrQueue – The CUDA stream / OpenCL command queue to enqueue the D2H copy on

Returns:

Array1D of the Format type, holding host memory that has not yet been synchronized

void copyToHost(Format *destination, size_t sizeInBytes, StreamOrQueue streamOrQueue) const

Copy device buffer data to host memory.

Enqueues the device-to-host copy on streamOrQueue and returns immediately. The caller is responsible for synchronizing streamOrQueue (e.g. via Zivid::synchronizeStream) before reading from destination. The caller must also ensure that the destination buffer is large enough to hold the data.

Pass the same stream/queue that was used at acquisition so the D2H copy is correctly ordered against the SDK’s compute. For a blocking copy that does the sync internally, use the parameterless host accessors on the originating Frame2D / PointCloud.

Parameters:

• destination – Pointer to host memory where data will be copied

• sizeInBytes – Size of the destination buffer in bytes

• streamOrQueue – The CUDA stream / OpenCL command queue to enqueue the D2H copy on

C#

GPU device buffers are exposed through the C++ and Python APIs. See the C++ and C# API reference for the full namespace reference.

Python

The Python API exposes zivid.DeviceArray and frame accessors such as image_device_array_rgba_float(). See zivid-python and the gpu_interop_with_cupy sample under python/source/camera/advanced/.

DeviceArrayView

A non-owning view over a caller-provided device buffer, used to copy data into your own GPU allocation without a host round-trip.

C++

template<typename Format>
class DeviceArrayView

Non-owning view of a device buffer.

A DeviceArrayView references device memory without expressing ownership over it. The underlying memory is either owned by an SDK DeviceArray (the view borrows its reference-counted handle) or externally by the caller (when the view was constructed via createDeviceArrayView).

Views are the parameter type for the fill variants of acquisition methods, for example Frame2D::imageDeviceArray<Format>(streamOrQueue, destinationBuffer). At the call site, a DeviceArray<Format> converts implicitly to a view for cases where the caller wants the SDK to write into previously allocated SDK memory; a user-supplied device pointer is wrapped via createDeviceArrayView<Format>(…).

The view does not extend the lifetime of externally owned memory - the caller must keep that memory valid while any view referencing it is in use.

A DeviceArrayView stores neither a CUDA stream nor an OpenCL queue and does not know about the SDK’s ComputeDevice. Every host-side accessor (copyToHost, toArray2D, toArray1D, toImage) therefore takes a StreamOrQueue, and the caller is responsible for passing the same stream/queue that was used when the view was filled by the SDK.

All host-side accessors are sync-free: they enqueue the device-to-host copy on the caller’s stream/queue and return immediately. The caller must synchronize the stream/queue (e.g. via Zivid::synchronizeStream) before reading the returned host buffer, Array2D, Array1D, or Image. For a blocking copy, use the parameterless host accessors on the originating Frame2D / PointCloud instead.

Public Functions

DeviceArrayView() = default

Default constructor - creates an empty view.

DeviceArrayView(const DeviceArray<Format> &source)

Borrow a view from an owning DeviceArray.

~DeviceArrayView() = default

Destructor.

DeviceArrayView(const DeviceArrayView &other) = default

Copy constructor - shares the view.

DeviceArrayView &operator=(const DeviceArrayView &other) = default

Copy assignment.

DeviceArrayView(DeviceArrayView &&other) noexcept = default

Move constructor.

DeviceArrayView &operator=(DeviceArrayView &&other) noexcept = default

Move assignment.

void *devicePointer() const

Get the raw GPU device pointer to the data.

std::vector<int> shape() const

Get the shape of the data.

std::vector<int> strides() const

Get the strides of the data in element count.

std::vector<int> stridesInBytes() const

Get the strides of the data in bytes.

size_t size() const

Get the total number of elements in the data.

size_t sizeInBytes() const

Get the total size of the data in bytes.

ComputeBackend backend() const

Get the GPU compute backend type of this buffer.

bool isValid() const

Check if the buffer is valid (not empty)

bool isEmpty() const

Check if the buffer is empty.

void copyToHost(Format *destination, size_t sizeInBytes, StreamOrQueue streamOrQueue) const

Enqueue a device-to-host copy without synchronizing.

Enqueues the copy and returns immediately. The caller is responsible for synchronizing streamOrQueue (e.g. via Zivid::synchronizeStream) before reading from destination.

Parameters:

• destination – Pointer to host memory where data will be copied

• sizeInBytes – Size of the destination buffer in bytes

• streamOrQueue – The CUDA stream / OpenCL command queue to enqueue the D2H copy on

Array2D<Format> toArray2D(StreamOrQueue streamOrQueue) const

Enqueue a device-to-host copy and return as Array2D without synchronizing.

Caller must synchronize streamOrQueue (e.g. via Zivid::synchronizeStream) before reading the returned Array2D’s data.

Parameters:

streamOrQueue – The CUDA stream / OpenCL command queue to enqueue the D2H copy on

Returns:

Array2D whose host memory is NOT safe to read until streamOrQueue is synchronized

Array1D<Format> toArray1D(StreamOrQueue streamOrQueue) const

Enqueue a device-to-host copy and return as Array1D without synchronizing.

Caller must synchronize streamOrQueue (e.g. via Zivid::synchronizeStream) before reading the returned Array1D’s data.

Parameters:

streamOrQueue – The CUDA stream / OpenCL command queue to enqueue the D2H copy on

Returns:

Array1D whose host memory is NOT safe to read until streamOrQueue is synchronized

C#

template<typename NETFormat>
class DeviceArrayView

A non-owning view over device memory of NETFormat .

Returned by ComputeDevice over caller-owned GPU memory. The view does not own or extend the lifetime of the underlying memory.

Public Functions

inline cli::array< int > ^ Shape ()

Get the shape of the view as a list of dimension extents.

inline cli::array< int > ^ Strides ()

Get the strides of the view in element count.

inline cli::array< int > ^ StridesInBytes ()

Get the strides of the view in bytes.

inline System::IntPtr DevicePointer()

Get the device pointer to the view data. No synchronization is performed.

inline cli::array< NETFormat, 2 > ^ ToArray2D (StreamOrQueue streamOrQueue)

Copy the view data to host as a 2D array, enqueued on the given stream/queue and synchronized before returning.

inline cli::array< NETFormat, 1 > ^ ToArray1D (StreamOrQueue streamOrQueue)

Copy the view data to host as a 1D array, enqueued on the given stream/queue and synchronized before returning.

inline void CopyToHost(System::IntPtr destination, size_t sizeInBytes, StreamOrQueue streamOrQueue)

Enqueue a copy of the view data to a host buffer on the given stream/queue. Non-blocking.

Properties

size_t Size

Get the number of elements in the view.

size_t SizeInBytes

Get the size of the view in bytes.

ComputeBackend Backend

Get the GPU compute backend that owns the underlying device memory.

bool IsValid

Check whether the view is valid (non-empty)

bool IsEmpty

Check whether the view is empty.

Python

See zivid-python.

StreamOrQueue and backend pointers

The synchronization handle passed to device-array accessors. StreamOrQueue wraps either a CUDA stream or an OpenCL command queue; the active backend (set at SDK build time) selects which one is used.

C++

struct StreamOrQueue

A user CUDA stream or OpenCL command queue, selected by which member is populated.

Used by SDK acquisition methods (e.g. Frame2D::imageDeviceArray, PointCloud::devicePointsXYZ) so that callers pass either a CUDAStreamPtr or an OpenCLCommandQueuePtr through a single method signature. Both wrapper types convert implicitly to StreamOrQueue. The active backend (set at SDK build time) picks the corresponding member; the other must be left null or the call throws:

• CUDA build: reads stream.stream as the destination CUDA stream (nullptr is allowed and means CUDA’s default/legacy stream); commandQueue.commandQueue must be null.

• OpenCL build: reads commandQueue.commandQueue as the destination OpenCL queue (must be non-null); stream.stream must be null. A default-constructed StreamOrQueue (both members null) is therefore valid only against a CUDA build, where it means “sync to the CUDA default stream”.

struct CUDAStreamPtr

Wrapper for user-provided CUDA stream for synchronization.

Used with DeviceArray::devicePointer() to synchronize SDK operations with user’s CUDA stream before accessing device memory.

struct CUDADevicePointer

Wrapper for a CUDA device pointer.

Used with createDeviceArrayView<Format>() to wrap externally-owned CUDA device memory in a DeviceArrayView. The SDK does not take ownership of the memory.

struct OpenCLCommandQueuePtr

Wrapper for user-provided OpenCL command queue for synchronization.

Used with DeviceArray::devicePointer() to synchronize SDK operations with user’s OpenCL command queue before accessing device memory.

struct OpenCLMemPointer

Wrapper for an OpenCL memory object (cl_mem)

Used with createDeviceArrayView<Format>() to wrap externally-owned OpenCL device memory in a DeviceArrayView. The SDK does not take ownership of the memory.

struct CUDAContextPtr

Wrapper for user-provided CUDA context pointer (CUcontext)

struct OpenCLContextPtr

Wrapper for user-provided OpenCL context pointer (cl_context)

C#

struct StreamOrQueue

A user CUDA stream or OpenCL command queue, selected by which member is populated.

Mirrors the native Zivid::StreamOrQueue. A CUDAStreamPtr or OpenCLCommandQueuePtr converts implicitly. On a CUDA build the Stream member is used (a zero handle means the CUDA default stream) and CommandQueue must be zero; on an OpenCL build the CommandQueue member is used (must be non-zero) and Stream must be zero.

Public Members

CUDAStreamPtr Stream

The CUDA stream wrapper (used on CUDA builds)

OpenCLCommandQueuePtr CommandQueue

The OpenCL command queue wrapper (used on OpenCL builds)

struct CUDAStreamPtr

Wrapper for a user-provided CUDA stream for synchronization.

Used with device array classes to synchronize SDK GPU operations with the user’s CUDA stream before accessing device memory.

Public Members

System::IntPtr Stream

The CUDA stream handle (CUstream cast to IntPtr)

struct CUDADevicePointer

Wrapper for a user-provided CUDA device pointer.

Used with ComputeDevice.CreateDeviceArrayViewColorRGBAf to wrap externally-owned CUDA device memory in a device array. The SDK does not take ownership of the memory.

Public Members

System::IntPtr Pointer

The CUDA device pointer.

struct OpenCLCommandQueuePtr

Wrapper for a user-provided OpenCL command queue for synchronization.

Used with device array classes to synchronize SDK GPU operations with the user’s OpenCL command queue before accessing device memory.

Public Members

System::IntPtr CommandQueue

The OpenCL command queue handle (cl_command_queue cast to IntPtr)

struct OpenCLMemPointer

Wrapper for a user-provided OpenCL memory object (cl_mem)

Used with ComputeDevice.CreateDeviceArrayViewColorRGBAf to wrap externally-owned OpenCL device memory in a device array. The SDK does not take ownership of the memory.

Public Members

System::IntPtr Memory

The OpenCL memory object handle (cl_mem cast to IntPtr)

Python

See zivid-python.

synchronizeStream

Blocks the host thread until all work previously enqueued on a StreamOrQueue has completed, so the device-array data is safe to read.

C++

void Zivid::synchronizeStream(StreamOrQueue streamOrQueue)

Block the host thread until all work previously enqueued on streamOrQueue has completed.

Equivalent to cudaStreamSynchronize on CUDA builds and clFinish on OpenCL builds.

The sync-free host-side accessors on DeviceArray and DeviceArrayView (copyToHost, toArray2D, toArray1D, and the free toImage(buffer, streamOrQueue) overloads) enqueue the device-to-host copy on the provided stream/queue and return immediately. Call synchronizeStream on the same stream/queue before reading the resulting host buffer, Array2D, Array1D, or Image.

For callers who do not want to manage the stream/queue themselves, prefer the parameterless host accessors on Frame2D, Sensor::Frame2D, Stereo::Frame2D, and PointCloud (e.g. imageRGBA(), image<Format>(), imageLeft<Format>(), copyPointsXYZ()) - those use the SDK’s internal stream/queue and synchronize before returning.

Parameters:

streamOrQueue – The CUDA stream or OpenCL command queue to synchronize on.

C#

class Compute

Compute-related free functions mirrored from the native Zivid namespace.

Public Static Functions

static inline void SynchronizeStream(StreamOrQueue streamOrQueue)

Block the host thread until all work previously enqueued on the stream/queue completes.

Equivalent to cudaStreamSynchronize on CUDA builds and clFinish on OpenCL builds. Call this on the same stream/queue passed to DeviceArray.CopyToHost before reading the destination buffer.

Python

See zivid-python.

See also

• Camera Basic

• Applications Basic