进阶：数据访问

APIs for copying capture data to CPU-accessible buffers or GPU device buffers, for zero-copy interop with CUDA/OpenCL libraries.

        %%{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
  PointCloud --> 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
    

复制到 CPU

捕获后，数据存放在 GPU 内存中。PointCloud 提供了许多方法，如 copyPointsXYZ()、copyColorsRGBA()、copyImageRGBA() 等，用于将选定的通道传输到 CPU 可访问的缓冲区。Frame2D 为纯 2D 捕获提供了 imageRGBA()。完整的复制 API 列表请参见 基础应用 页面。

GPU 设备缓冲区

GPU 设备缓冲区可与 CuPy、PyTorch、OpenCV CUDA 和 OpenGL 等 CUDA 库实现零复制互操作。当数据应保留在 GPU 上而不是通过主机内存复制时，请在 Camera Basic 中捕获后使用这些类型。这对应于 {cpp,python}/source/camera/advanced/ 下的 GPU 互操作示例。

ComputeDevice

用于 SDK 处理的计算设备（CPU 或 GPU）。在请求捕获数据的 DeviceArray 视图之前，请选择 CUDA 后端。

C++

ComputeDeviceclass

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

Public Functions

ComputeDevice()

Constructor.

~ComputeDevice()

Destructor.

ComputeDevice( ComputeDevice&const other)

Copy constructor.

ComputeDevice&=operator( ComputeDevice&const other)

Assignment operator.

ComputeDevice(ComputeDevice&other &)noexcept

Move constructor.

ComputeDevice&=operator(ComputeDevice&other &)noexcept

Move assignment operator.

stdstringmodel()const::

Returns the model name of this compute device.

stdstringvendor()const::

Returns the vendor of this compute device.

ComputeBackendbackend()const

Returns the backend type of this compute device.

nativeContext()constvoid*

Get native context handle for interop with GPU APIs.

nativeStreamHandle()constvoid*

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.

返回:

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

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

返回:

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

< Format stdenable_if_tDetailSupportedDeviceArrayViewFormatFormat::value>templatetypename,typename=::<::<>>
DeviceArrayViewFormat createDeviceArrayView(CUDADevicePointercudaPointer , size_twidth , size_theight , CUDAStreamPtrstream )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; 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.

参数:

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

返回:

A DeviceArrayView<Format> referencing the provided CUDA memory

< Format stdenable_if_tDetailSupportedDeviceArrayViewFormatFormat::value>templatetypename,typename=::<::<>>
DeviceArrayViewFormat createDeviceArrayView(OpenCLMemPointeropenCLBuffer , size_twidth , size_theight , OpenCLCommandQueuePtrqueue )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; 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.

参数:

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

返回:

A DeviceArrayView<Format> referencing the provided OpenCL memory

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

返回:

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

抛出:

-- stdruntime_error::If the compute backend is not CUDA

stdstringtoString()const::

Get string representation of the compute device.

返回:

Compute device info as string

C#

ComputeDeviceclass

Contains information about the ComputeDevice used by Application.

Public Functions

System::String ^ ToString () override

Get string representation of the application.

返回:

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.

参数:

• 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

返回:

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.

参数:

• 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

返回:

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.

StreamOrQueueSdkStreamOrQueue

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

classComputeDevice(impl)

The GPU compute device used by the SDK.

Get it with zivid.Application.compute_device.

Initialization

Initialize ComputeDevice wrapper.

This constructor is only used internally, and should not be called by the end-user.

参数:

impl -- Reference to internal/back-end instance.

抛出:

TypeError -- If argument does not match the expected internal class.

propertymodel str:

Get the model name of the compute device.

返回:

The model name

propertyvendor str:

Get the vendor of the compute device.

返回:

The vendor

propertybackend ComputeBackend:

Get the compute backend of the compute device.

返回:

The compute backend

propertycuda_runtime_library_name str:

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

This is useful for loading the CUDA runtime with ctypes or similar foreign function interfaces for GPU interop, such as CUDA-OpenGL interop. The name is guaranteed to match the CUDA version that the SDK was compiled against.

返回:

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

抛出:

RuntimeError -- If the compute backend is not CUDA

native_context() → int

Get the native context handle, for interop with GPU APIs.

返回:

The CUcontext with the CUDA backend, or the cl_context with the OpenCL backend, as an integer

native_stream_handle() → int

Get the native stream or queue handle, for advanced GPU interop.

Use the handle to synchronize with your own GPU operations, to submit custom kernels on the same stream, or to check whether the stream has completed. It stays valid for the lifetime of the compute device. Do not destroy it.

With a user-provided context or stream this is the user-provided handle, otherwise the handle of the stream or queue the SDK created.

返回:

The CUstream with the CUDA backend, or the cl_command_queue with the OpenCL backend, as an integer

sdk_stream_or_queue() → StreamOrQueue

Get the stream or queue of the SDK, as a backend-agnostic StreamOrQueue.

A portable alternative to wrapping native_stream_handle in a CUDAStreamPtr or an OpenCLCommandQueuePtr. Pass it to functions that take a stream_or_queue when you do not have a stream or queue of your own. The synchronization is then with the SDK's own stream or queue, which costs nothing.

返回:

A StreamOrQueue holding the stream or queue of the SDK

create_device_array_view_rgba(

:intcuda_pointer ,

:intwidth ,

:intheight ,

stream_or_queue,

) → DeviceArrayView

Create a DeviceArrayView in the RGBA format over an externally-owned CUDA device pointer.

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 buffer filled through it, is in use. The device pointer must be created using the same CUDA context that the Zivid SDK uses. Only available when the compute backend is CUDA.

参数:

• cuda_pointer -- Non-null CUDA device pointer, as an integer

• width -- Width of the image in pixels

• height -- Height of the image in pixels

• stream_or_queue -- The CUDA stream that the preparation work of the buffer (allocation and any data production) was enqueued on

返回:

A DeviceArrayView referencing the provided CUDA memory

create_device_array_view_bgra(

:intcuda_pointer ,

:intwidth ,

:intheight ,

stream_or_queue,

) → DeviceArrayView

Create a DeviceArrayView in the BGRA format over an externally-owned CUDA device pointer.

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 buffer filled through it, is in use. The device pointer must be created using the same CUDA context that the Zivid SDK uses. Only available when the compute backend is CUDA.

参数:

• cuda_pointer -- Non-null CUDA device pointer, as an integer

• width -- Width of the image in pixels

• height -- Height of the image in pixels

• stream_or_queue -- The CUDA stream that the preparation work of the buffer (allocation and any data production) was enqueued on

返回:

A DeviceArrayView referencing the provided CUDA memory

create_device_array_view_rgba_srgb(

:intcuda_pointer ,

:intwidth ,

:intheight ,

stream_or_queue,

) → DeviceArrayView

Create a DeviceArrayView in the RGBA_SRGB format over an externally-owned CUDA device pointer.

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 buffer filled through it, is in use. The device pointer must be created using the same CUDA context that the Zivid SDK uses. Only available when the compute backend is CUDA.

参数:

• cuda_pointer -- Non-null CUDA device pointer, as an integer

• width -- Width of the image in pixels

• height -- Height of the image in pixels

• stream_or_queue -- The CUDA stream that the preparation work of the buffer (allocation and any data production) was enqueued on

返回:

A DeviceArrayView referencing the provided CUDA memory

create_device_array_view_bgra_srgb(

:intcuda_pointer ,

:intwidth ,

:intheight ,

stream_or_queue,

) → DeviceArrayView

Create a DeviceArrayView in the BGRA_SRGB format over an externally-owned CUDA device pointer.

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 buffer filled through it, is in use. The device pointer must be created using the same CUDA context that the Zivid SDK uses. Only available when the compute backend is CUDA.

参数:

• cuda_pointer -- Non-null CUDA device pointer, as an integer

• width -- Width of the image in pixels

• height -- Height of the image in pixels

• stream_or_queue -- The CUDA stream that the preparation work of the buffer (allocation and any data production) was enqueued on

返回:

A DeviceArrayView referencing the provided CUDA memory

create_device_array_view_rgbaf(

:intcuda_pointer ,

:intwidth ,

:intheight ,

stream_or_queue,

) → DeviceArrayView

Create a DeviceArrayView in the RGBAF format over an externally-owned CUDA device pointer.

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 buffer filled through it, is in use. The device pointer must be created using the same CUDA context that the Zivid SDK uses. Only available when the compute backend is CUDA.

参数:

• cuda_pointer -- Non-null CUDA device pointer, as an integer

• width -- Width of the image in pixels

• height -- Height of the image in pixels

• stream_or_queue -- The CUDA stream that the preparation work of the buffer (allocation and any data production) was enqueued on

返回:

A DeviceArrayView referencing the provided CUDA memory

create_device_array_view_rgb(

:intcuda_pointer ,

:intwidth ,

:intheight ,

stream_or_queue,

) → DeviceArrayView

Create a DeviceArrayView in the RGB format over an externally-owned CUDA device pointer.

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 buffer filled through it, is in use. The device pointer must be created using the same CUDA context that the Zivid SDK uses. Only available when the compute backend is CUDA.

参数:

• cuda_pointer -- Non-null CUDA device pointer, as an integer

• width -- Width of the image in pixels

• height -- Height of the image in pixels

• stream_or_queue -- The CUDA stream that the preparation work of the buffer (allocation and any data production) was enqueued on

返回:

A DeviceArrayView referencing the provided CUDA memory

create_device_array_view_rgb_srgb(

:intcuda_pointer ,

:intwidth ,

:intheight ,

stream_or_queue,

) → DeviceArrayView

Create a DeviceArrayView in the RGB_SRGB format over an externally-owned CUDA device pointer.

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 buffer filled through it, is in use. The device pointer must be created using the same CUDA context that the Zivid SDK uses. Only available when the compute backend is CUDA.

参数:

• cuda_pointer -- Non-null CUDA device pointer, as an integer

• width -- Width of the image in pixels

• height -- Height of the image in pixels

• stream_or_queue -- The CUDA stream that the preparation work of the buffer (allocation and any data production) was enqueued on

返回:

A DeviceArrayView referencing the provided CUDA memory

create_device_array_view_bgr(

:intcuda_pointer ,

:intwidth ,

:intheight ,

stream_or_queue,

) → DeviceArrayView

Create a DeviceArrayView in the BGR format over an externally-owned CUDA device pointer.

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 buffer filled through it, is in use. The device pointer must be created using the same CUDA context that the Zivid SDK uses. Only available when the compute backend is CUDA.

参数:

• cuda_pointer -- Non-null CUDA device pointer, as an integer

• width -- Width of the image in pixels

• height -- Height of the image in pixels

• stream_or_queue -- The CUDA stream that the preparation work of the buffer (allocation and any data production) was enqueued on

返回:

A DeviceArrayView referencing the provided CUDA memory

create_device_array_view_bgr_srgb(

:intcuda_pointer ,

:intwidth ,

:intheight ,

stream_or_queue,

) → DeviceArrayView

Create a DeviceArrayView in the BGR_SRGB format over an externally-owned CUDA device pointer.

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 buffer filled through it, is in use. The device pointer must be created using the same CUDA context that the Zivid SDK uses. Only available when the compute backend is CUDA.

参数:

• cuda_pointer -- Non-null CUDA device pointer, as an integer

• width -- Width of the image in pixels

• height -- Height of the image in pixels

• stream_or_queue -- The CUDA stream that the preparation work of the buffer (allocation and any data production) was enqueued on

返回:

A DeviceArrayView referencing the provided CUDA memory

classComputeBackend(args*, kwds**)

GPU compute backend type.

Initialization

cuda=0

opencl=1

DeviceArray

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

有关每种格式的数据布局，请参见 DeviceArray 参考；有关流/队列排序模型，请参见 DeviceArray — Stream、Queue 和 Context。

C++

< Formattemplatetypename>
DeviceArrayclass

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( DeviceArray&const other)=default

Copy constructor - shares ownership of the buffer.

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

Copy assignment - shares ownership of the buffer.

DeviceArray(DeviceArray&other &)noexcept=default

Move constructor.

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

Move assignment.

devicePointer()constvoid*

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.

返回:

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

stdvectorint shape()const::<>

Get the shape of the data.

stdvectorint strides()const::<>

Get the strides of the data in element count.

stdvectorint stridesInBytes()const::<>

Get the strides of the data in bytes.

size_tsize()const

Get the total number of elements in the data.

size_tsizeInBytes()const

Get the total size of the data in bytes.

ComputeBackendbackend()const

Get the GPU compute backend type of this buffer.

返回:

The GPU compute backend (CUDA or OpenCL)

isValid()constbool

Check if the buffer is valid (not empty)

isEmpty()constbool

Check if the buffer is empty.

Array2DFormat toArray2D(StreamOrQueuestreamOrQueue )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.

参数:

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

返回:

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

Array1DFormat toArray1D(StreamOrQueuestreamOrQueue )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).

参数:

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

返回:

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

copyToHost(Format* destination, size_tsizeInBytes , StreamOrQueuestreamOrQueue )constvoid

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.

参数:

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

< NETFormattemplatetypename>
DeviceArrayclass

A reference-counted handle to GPU memory containing data of NETFormat .

ToArray2D throws System::InvalidOperationException when called on an unorganized device array (use ToArray1D instead), and vice versa. The shape of the underlying buffer determines which call is valid.

Instances are obtained from PointCloud, UnorganizedPointCloud, Frame2D, or ComputeDevice.

Public Functions

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

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

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

Get the strides of the array in element count.

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

Get the strides of the array in bytes.

SystemIntPtrDevicePointer()inline::

Get the device pointer to the array data.

No synchronization is performed; the array was already synchronized against the acquisition stream/queue when it was produced.

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

Copy the device array data to host as a 2D array [height, width], enqueued on the given stream/queue and synchronized before returning.

Throws System::InvalidOperationException if the array is unorganized.

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

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

Throws System::InvalidOperationException if the array is organized.

CopyToHost(SystemIntPtrdestination:: , size_tsizeInBytes , StreamOrQueuestreamOrQueue )inlinevoid

Enqueue a copy of the device array data to a host buffer on the given stream/queue.

Non-blocking; call Zivid::NET::Compute::SynchronizeStream on the same stream/queue before reading the destination.

inline DeviceArray< NETFormat > ^ ShallowCopy ()

Return a shallow copy of the array sharing the underlying device memory.

Properties

size_tSize

Get the number of elements in the array.

size_tSizeInBytes

Get the size of the array in bytes.

ComputeBackendBackend

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

IsValidbool

Check whether the array is valid (non-empty)

IsEmptybool

Check whether the array is empty.

Python

classDeviceArray(impl)

A 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. SDK-created DeviceArrays are bound to the lifetime of the Zivid Application that produced them — they must not outlive it. For device memory that needs to outlive the Application, allocate it yourself and pass it into the fill variant of the acquisition method (not yet exposed at the Python layer).

A DeviceArray is already synchronized against the stream/queue that was passed to the acquisition method (for example Frame2D.image_device_array(stream_or_queue, color_format)), so device_pointer() is a plain accessor that does no additional sync.

Initialization

Initialize DeviceArray wrapper.

This constructor is only used internally, and should not be called by the end-user.

参数:

impl -- Reference to internal/back-end instance.

抛出:

TypeError -- If argument does not match the expected internal class.

propertyshape tuple:

Get the shape of the device array.

返回:

A tuple representing the shape of the array.

propertystrides tuple:

Get the strides of the device array in element count.

返回:

A tuple representing the strides of the array in element count.

propertystrides_in_bytes tuple:

Get the strides of the device array in bytes.

返回:

A tuple representing the strides of the array in bytes.

propertysize_bytes int:

Get the size of the device array in bytes.

返回:

The size of the array in bytes.

propertybackend ComputeBackend:

Get the compute backend of the device array.

返回:

The compute backend of the array.

propertyis_valid bool:

Check if the device array is valid.

返回:

True if the array is valid, False otherwise.

propertyis_empty bool:

Check if the device array is empty.

返回:

True if the array is empty, False otherwise.

device_pointer() → int

Get the raw device pointer for the array data.

No synchronization is performed. The DeviceArray was already synchronized against the caller's stream or queue at acquisition time (by the method that produced it, e.g. Frame2D.image_device_array(stream_or_queue, color_format)). Consumer work can be enqueued on that same stream or queue immediately.

返回:

An integer representing the device pointer to the array data (cudaPtr for CUDA builds, cl_mem cast to an integer for OpenCL builds).

copy_to_host_organized_array(stream_or_queue) → ndarray

Enqueue a device-to-host copy and return a numpy array WITHOUT synchronizing.

Use this for device arrays obtained from organized point clouds, or from 2D frames.

参数:

stream_or_queue -- The CUDA stream or OpenCL command queue used when the array was acquired. The D2H copy is enqueued on this stream/queue and this function returns immediately. The caller is responsible for synchronizing stream_or_queue (e.g. via zivid.synchronize_stream) before reading the returned numpy array's data.

返回:

A 3D numpy array whose underlying memory is NOT safe to read until the caller synchronizes stream_or_queue.

抛出:

• TypeError -- If the device array type is ImageDeviceArrayRGBAf, which does not support copy_to_host_organized_array.

• RuntimeError -- If the device array is not from an organized point cloud or 2D frame.

备注

If you don't want to manage stream synchronization yourself, use the parameterless host accessors on Frame2D / PointCloud (e.g. frame_2d.image_rgba(), point_cloud.copy_data("xyz")) instead — those return host-ready data using the SDK's internal stream.

copy_to_host_unorganized_array(stream_or_queue) → ndarray

Enqueue a device-to-host copy and return a numpy array WITHOUT synchronizing.

Use this for device arrays obtained from unorganized point clouds.

参数:

stream_or_queue -- The CUDA stream or OpenCL command queue used when the array was acquired. The D2H copy is enqueued on this stream/queue and this function returns immediately. The caller is responsible for synchronizing stream_or_queue (e.g. via zivid.synchronize_stream) before reading the returned numpy array's data.

抛出:

• TypeError -- If the device array type is ImageDeviceArrayRGBAf, which does not support copy_to_host_unorganized_array.

• RuntimeError -- If the device array is not from an unorganized point cloud.

返回:

A numpy array whose underlying memory is NOT safe to read until the caller synchronizes stream_or_queue.

备注

If you don't want to manage stream synchronization yourself, use the parameterless host accessors on UnorganizedPointCloud instead.

to_image(stream_or_queue) → Image

Enqueue a device-to-host copy and return it as an Image, WITHOUT synchronizing.

Only valid for the 8-bit color formats. The device-to-host copy is enqueued on stream_or_queue and this function returns immediately. The caller must synchronize stream_or_queue (e.g. via zivid.synchronize_stream) before reading the returned Image.

参数:

stream_or_queue -- The CUDA stream or OpenCL command queue to enqueue the copy on.

返回:

An Image whose host memory is NOT safe to read until stream_or_queue is synchronized.

抛出:

TypeError -- If the device array is not in an 8-bit color format.

DeviceArrayView

一种非拥有型视图，用于呈现调用方提供的设备缓冲区，可将数据复制到您自己的 GPU 分配空间中，而无需经过主机往返。

C++

< Formattemplatetypename>
DeviceArrayViewclass

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( DeviceArrayFormat sourceconst<>&)

Borrow a view from an owning DeviceArray.

~DeviceArrayView()=default

Destructor.

DeviceArrayView( DeviceArrayView&const other)=default

Copy constructor - shares the view.

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

Copy assignment.

DeviceArrayView(DeviceArrayView&other &)noexcept=default

Move constructor.

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

Move assignment.

devicePointer()constvoid*

Get the raw GPU device pointer to the data.

stdvectorint shape()const::<>

Get the shape of the data.

stdvectorint strides()const::<>

Get the strides of the data in element count.

stdvectorint stridesInBytes()const::<>

Get the strides of the data in bytes.

size_tsize()const

Get the total number of elements in the data.

size_tsizeInBytes()const

Get the total size of the data in bytes.

ComputeBackendbackend()const

Get the GPU compute backend type of this buffer.

isValid()constbool

Check if the buffer is valid (not empty)

isEmpty()constbool

Check if the buffer is empty.

copyToHost(Format* destination, size_tsizeInBytes , StreamOrQueuestreamOrQueue )constvoid

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.

参数:

• 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

Array2DFormat toArray2D(StreamOrQueuestreamOrQueue )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.

参数:

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

返回:

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

Array1DFormat toArray1D(StreamOrQueuestreamOrQueue )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.

参数:

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

返回:

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

C#

< NETFormattemplatetypename>
DeviceArrayViewclass

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.

SystemIntPtrDevicePointer()inline::

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.

CopyToHost(SystemIntPtrdestination:: , size_tsizeInBytes , StreamOrQueuestreamOrQueue )inlinevoid

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

Properties

size_tSize

Get the number of elements in the view.

size_tSizeInBytes

Get the size of the view in bytes.

ComputeBackendBackend

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

IsValidbool

Check whether the view is valid (non-empty)

IsEmptybool

Check whether the view is empty.

Python

classDeviceArrayView(impl)

A non-owning view over caller-owned GPU memory that the Zivid SDK can read or fill.

Created via zivid.create_device_array_view(...). The SDK does not take ownership of the underlying buffer; the caller must keep the source array alive while the view (and any consumer of it) is in use. Pass to APIs that take a DeviceArrayView, such as the destination_buffer of the Frame2D.image_device_array_* accessors (a color view to fill in place).

Initialization

Initialize DeviceArrayView wrapper.

This constructor is only used internally; use zivid.create_device_array_view(...) instead.

参数:

impl -- Reference to internal/back-end instance.

抛出:

TypeError -- If argument does not match the expected internal class.

propertyshape tuple:

Tuple of view dimensions.

propertystrides tuple:

Tuple of view strides in element count.

propertystrides_in_bytes tuple:

Tuple of view strides in bytes.

propertysize_bytes int:

Size of the view in bytes.

propertybackend ComputeBackend:

Compute backend of the view (CUDA or OpenCL).

propertyis_valid bool:

True if the view is valid (not empty).

propertyis_empty bool:

True if the view is empty.

device_pointer() → int

Get the raw device pointer to the viewed memory.

返回:

An integer device pointer (cudaPtr for CUDA builds, cl_mem cast to an integer for OpenCL builds).

to_image(stream_or_queue) → Image

Enqueue a device-to-host copy and return it as an Image, WITHOUT synchronizing.

Only valid for the 8-bit color formats. The device-to-host copy is enqueued on stream_or_queue and this function returns immediately. The caller must synchronize stream_or_queue (e.g. via zivid.synchronize_stream) before reading the returned Image.

参数:

stream_or_queue -- The CUDA stream or OpenCL command queue used when the view was filled.

返回:

An Image whose host memory is NOT safe to read until stream_or_queue is synchronized.

抛出:

TypeError -- If the view is not in an 8-bit color format.

copy_to_host_organized_array(stream_or_queue) → ndarray

Enqueue a device-to-host copy and return a numpy array WITHOUT synchronizing.

Only available for color views. The D2H copy is enqueued on stream_or_queue and this function returns immediately; the caller must synchronize stream_or_queue (e.g. via zivid.synchronize_stream) before reading the returned numpy array.

参数:

stream_or_queue -- The CUDA stream or OpenCL command queue to enqueue the D2H copy on.

返回:

A 3D numpy array whose memory is NOT safe to read until stream_or_queue is synchronized.

StreamOrQueue 与后端指针

传递给设备数组访问器的同步句柄。StreamOrQueue 封装了 CUDA 流或 OpenCL 命令队列；具体使用哪一种由当前后端（在 SDK 构建时设置）决定。

C++

StreamOrQueuestruct

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

CUDAStreamPtrstruct

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.

CUDADevicePointerstruct

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.

OpenCLCommandQueuePtrstruct

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.

OpenCLMemPointerstruct

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.

CUDAContextPtrstruct

Wrapper for user-provided CUDA context pointer (CUcontext)

OpenCLContextPtrstruct

Wrapper for user-provided OpenCL context pointer (cl_context)

C#

StreamOrQueuestruct

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

CUDAStreamPtrStream

The CUDA stream wrapper (used on CUDA builds)

OpenCLCommandQueuePtrCommandQueue

The OpenCL command queue wrapper (used on OpenCL builds)

CUDAStreamPtrstruct

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

SystemIntPtrStream::

The CUDA stream handle (CUstream cast to IntPtr)

CUDADevicePointerstruct

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

SystemIntPtrPointer::

The CUDA device pointer.

OpenCLCommandQueuePtrstruct

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

SystemIntPtrCommandQueue::

The OpenCL command queue handle (cl_command_queue cast to IntPtr)

OpenCLMemPointerstruct

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

SystemIntPtrMemory::

The OpenCL memory object handle (cl_mem cast to IntPtr)

Python

classStreamOrQueue(

:CUDAStreamPtr | OpenCLCommandQueuePtr | None=Nonestream_or_queue ,

/,

*,

:CUDAStreamPtr | None=Nonestream ,

:OpenCLCommandQueuePtr | None=Nonecommand_queue ,

)

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

Functions that take a stream_or_queue accept a CUDAStreamPtr, an OpenCLCommandQueuePtr or a StreamOrQueue. The compute backend of the SDK picks the matching member, and the other must be left null, or the call raises:

• CUDA: stream is the CUDA stream to synchronize with. A null stream means the CUDA default stream. command_queue must be null.

• OpenCL: command_queue is the OpenCL command queue to synchronize with, and must not be null. stream must be null.

Initialization

Initialize a StreamOrQueue from either a CUDA stream or an OpenCL command queue.

Pass exactly one of the arguments.

参数:

• stream_or_queue -- A CUDAStreamPtr or an OpenCLCommandQueuePtr

• stream -- The CUDA stream, for the CUDA backend

• command_queue -- The OpenCL command queue, for the OpenCL backend

抛出:

TypeError -- If not exactly one argument is given, or if it has the wrong type

propertystream CUDAStreamPtr:

Get the CUDA stream member.

返回:

The CUDA stream, which is null unless the CUDA backend is selected

propertycommand_queue OpenCLCommandQueuePtr:

Get the OpenCL command queue member.

返回:

The OpenCL command queue, which is null unless the OpenCL backend is selected

classCUDAStreamPtr(:int=0stream )

Wrapper for a user-provided CUDA stream (CUstream), for synchronization.

Pass it wherever a function takes a stream_or_queue, to synchronize SDK operations with that CUDA stream before device memory is accessed.

Initialization

Initialize a CUDAStreamPtr.

参数:

stream -- The CUstream handle, as an integer. 0 is the CUDA default stream.

propertystream int:

Get the CUstream handle.

返回:

The CUstream handle, as an integer

classOpenCLCommandQueuePtr(:int=0command_queue )

Wrapper for a user-provided OpenCL command queue (cl_command_queue), for synchronization.

Pass it wherever a function takes a stream_or_queue, to synchronize SDK operations with that OpenCL command queue before device memory is accessed.

Initialization

Initialize an OpenCLCommandQueuePtr.

参数:

command_queue -- The cl_command_queue handle, as an integer

propertycommand_queue int:

Get the cl_command_queue handle.

返回:

The cl_command_queue handle, as an integer

classCUDAContextPtr(:int=0context )

Wrapper for a user-provided CUDA context (CUcontext).

Pass it to zivid.Application to make the SDK use that CUDA context.

Initialization

Initialize a CUDAContextPtr.

参数:

context -- The CUcontext handle, as an integer

propertycontext int:

Get the CUcontext handle.

返回:

The CUcontext handle, as an integer

synchronizeStream

阻塞主机线程，直到之前在 StreamOrQueue 上排入队列的所有工作完成，从而确保设备数组数据可以安全读取。

C++

synchronizeStream(StreamOrQueuestreamOrQueue )void

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 and PointCloud (e.g. imageRGBA(), copyPointsXYZ()) - those use the SDK's internal stream/queue and synchronize before returning.

参数:

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

C#

Computeclass

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

Public Static Functions

SynchronizeStream(StreamOrQueuestreamOrQueue )staticinlinevoid

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

synchronize_stream(stream_or_queue) → None

Block until all work previously enqueued on a CUDA stream or OpenCL command queue has completed.

Equivalent to cudaStreamSynchronize with the CUDA backend and clFinish with the OpenCL backend.

The host accessors of DeviceArray and DeviceArrayView, such as copy_to_host_organized_array and to_image, enqueue the device-to-host copy on the given stream or queue and return without waiting for it. Call this function on the same stream or queue before reading their results.

参数:

stream_or_queue -- A CUDAStreamPtr, OpenCLCommandQueuePtr or StreamOrQueue

另请参阅

• 点云教程

• Camera Basic

• 基础应用

• DeviceArray 参考