Zivid::DeviceArrayView< Format > Class Template Reference

Non-owning view of a device buffer. More...

#include <Zivid/DeviceArray.h>

Public Member 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.
Array2D< Format >	toArray2D (StreamOrQueue streamOrQueue) const
	Enqueue a device-to-host copy and return as Array2D without synchronizing.
Array1D< Format >	toArray1D (StreamOrQueue streamOrQueue) const
	Enqueue a device-to-host copy and return as Array1D without synchronizing.

Detailed Description

template<typename Format>
class Zivid::DeviceArrayView< Format >

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.

Constructor & Destructor Documentation

DeviceArrayView() [1/4]

template<typename Format>

Zivid::DeviceArrayView< Format >::DeviceArrayView ( )

default

Default constructor - creates an empty view.

DeviceArrayView() [2/4]

template<typename Format>

Zivid::DeviceArrayView< Format >::DeviceArrayView

(

const DeviceArray< Format > &

source

)

Borrow a view from an owning DeviceArray.

~DeviceArrayView()

template<typename Format>

Zivid::DeviceArrayView< Format >::~DeviceArrayView ( )

default

Destructor.

DeviceArrayView() [3/4]

template<typename Format>

Zivid::DeviceArrayView< Format >::DeviceArrayView ( const DeviceArrayView< Format > & other )

default

Copy constructor - shares the view.

DeviceArrayView() [4/4]

template<typename Format>

Zivid::DeviceArrayView< Format >::DeviceArrayView ( DeviceArrayView< Format > && other )

defaultnoexcept

Move constructor.

Member Function Documentation

backend()

template<typename Format>

ComputeBackend Zivid::DeviceArrayView< Format >::backend

(

)

const

Get the GPU compute backend type of this buffer.

copyToHost()

template<typename Format>

void Zivid::DeviceArrayView< Format >::copyToHost	(	Format *	destination,
		size_t	sizeInBytes,
		StreamOrQueue	streamOrQueue ) const

Enqueue a device-to-host copy without synchronizing.

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

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

devicePointer()

template<typename Format>

void * Zivid::DeviceArrayView< Format >::devicePointer

(

)

const

Get the raw GPU device pointer to the data.

isEmpty()

template<typename Format>

bool Zivid::DeviceArrayView< Format >::isEmpty

(

)

const

Check if the buffer is empty.

isValid()

template<typename Format>

bool Zivid::DeviceArrayView< Format >::isValid

(

)

const

Check if the buffer is valid (not empty)

operator=() [1/2]

template<typename Format>

DeviceArrayView & Zivid::DeviceArrayView< Format >::operator= ( const DeviceArrayView< Format > & other )

default

Copy assignment.

operator=() [2/2]

template<typename Format>

DeviceArrayView & Zivid::DeviceArrayView< Format >::operator= ( DeviceArrayView< Format > && other )

defaultnoexcept

Move assignment.

shape()

template<typename Format>

std::vector< int > Zivid::DeviceArrayView< Format >::shape

(

)

const

Get the shape of the data.

size()

template<typename Format>

size_t Zivid::DeviceArrayView< Format >::size

(

)

const

Get the total number of elements in the data.

sizeInBytes()

template<typename Format>

size_t Zivid::DeviceArrayView< Format >::sizeInBytes

(

)

const

Get the total size of the data in bytes.

strides()

template<typename Format>

std::vector< int > Zivid::DeviceArrayView< Format >::strides

(

)

const

Get the strides of the data in element count.

stridesInBytes()

template<typename Format>

std::vector< int > Zivid::DeviceArrayView< Format >::stridesInBytes

(

)

const

Get the strides of the data in bytes.

toArray1D()

template<typename Format>

Array1D< Format > Zivid::DeviceArrayView< Format >::toArray1D

(

StreamOrQueue

streamOrQueue

)

const

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

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

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

toArray2D()

template<typename Format>

Array2D< Format > Zivid::DeviceArrayView< Format >::toArray2D

(

StreamOrQueue

streamOrQueue

)

const

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

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

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

---

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

• Zivid/DeviceArray.h