oni.hpp#

This file includes oni.h.

Version#

See https://semver.org/ for a complete explanation of these macro definitions.

CPPONI_VERSION_MAJOR#: MAJOR version for incompatible API changes.

CPPONI_VERSION_MINOR#: MINOR version for added functionality that is backwards compatible.

CPPONI_VERSION_PATCH#: PATCH version for backwards compatible bug fixes.

CPPONI_MAKE_VERSION(major, minor, patch)#

Defined as

MAJOR * 10000 + MINOR * 100 + PATCH

Provides compile-time access to the API version.

CPPONI_VERSION#

Compile-time API version. Defined as

CPPONI_MAKE_VERSION(CPPONI_VERSION_MAJOR CPPONI_VERSION_MINOR, CPPONI_VERSION_PATCH)

std::tuple<int, int, int> oni::version()#

Get the cpponi version.

Returns:: std::tuple<MAJOR, MINOR, PATCH>

Errors#

class oni::error_t : public std::exception#

std::exception wrapper for liboni Error Codes. These exceptions are thrown from cpponi in lieu of C return codes.

error_t(int errnum)#

Constructor. Not generally needed for cpponi use since oni::error_t is constructed and thrown from within cpponi and only needs to be handled by the host application.

Parameters:: errnum – liboni error code integer, generally resulting from a non-zero return value of an underlying liboni function.

const char *what() const noexcept override#

Wrapper for oni_error_str().

Returns:: Human-readable error code description.

Devices#

using oni::device_t = oni_device_t#: Type alias for oni_device_t.

using oni::device_map_t = std::unordered_map<oni_dev_idx_t, oni::device_t>#: oni::device_t table type. std::unordered_map replaces a minimal internal hash table used in liboni and allows fast device lookup based on device index.

Frames#

class oni::frame_t#

RAII-capable wrapper for oni_frame_t. User programs generally should not call the frame_t constructor directly but deal with frames created by a oni::context_t.

uint64_t time() const#

Returns:: Underlying oni_frame_t.time.

oni_dev_idx_t device_index() const#

Returns:: Underlying oni_frame_t.dev_idx.

template<typename raw_t> std::span<const raw_t> data() const#

std::vector<const raw_t> data() const#

Returns:: A type-cast view (or copy if stdlib < C++20) of the underlying oni_frame_t.data.

Note

std::span Automatically made available when compiled with stdlib >= C++20. Otherwise, this function reverts to returning a std::vector.

Context#

class oni::context_t#

RAII-capable wrapper for a liboni Acquisition Context as well as the majority of functions within the liboni API.

context_t(const char *driver_name, int host_idx)#

Constructor. Creates and initializes the underlying Acquisition Context.

Parameters:

drv_name – A string specifying the device driver used by the context to control hardware. This string corresponds a compiled implementation of onidriver.h that has the name onidriver_<drv_name>.<so/dll>. If this library is not on the dynamic library search path, the function will error.
host_idx – The index of the hardware we are going to manage using the initialized context and driver. A value of -1 will attempt to open the default host index and is useful if there is only a single ONIX host managed by driver selected in oni_create_ctx().

Throws:

std::system_error if underlying context cannot be allocated.

See also

oni_create_ctx(): Underlying context creation.
oni_init_ctx(): Underlying context initialization.

context_t(context_t &&rhs) noexcept#

Move constructor.

Parameters:: rhs – Existing context_t instance to move from.

context_t &operator=(context_t &&rhs) noexcept#

Move assignment operator.

Parameters:: rhs – Existing context_t instance to move from.

template<typename opt_t> opt_t get_opt(int option) const#

Get a context option.

Parameters:: option – [anonymous] option selection. See each option description for valid opt_t types.
Returns:: opt_t option value.

See also

oni_get_opt(): Underlying C function.

template<typename opt_t> void set_opt(int option, opt_t const &optval)#

Set a context option.

See also

oni_set_opt(): Underlying C function.

template<typename opt_t> opt_t get_driver_opt(int option) const#

Get a driver option.

See also

oni_get_driver_opt(): Underlying C function.

template<typename opt_t> void set_driver_opt(int option, opt_t const &optval)#

Set a driver option.

See also

oni_get_driver_opt(): Underlying C function.

oni_reg_val_t read_reg(oni_dev_idx_t dev_idx, oni_reg_addr_t addr)#

Read a device register.

See also

oni_read_reg(): Underlying C function.

void write_reg(oni_dev_idx_t dev_idx, oni_reg_addr_t addr, oni_reg_val_t value)#

Write a device register.

See also

oni_write_reg(): Underlying C function.

device_map_t device_map() const noexcept#

Convenience function to examine the context’s current device table as a std::unordered_map from table index to device instance. The raw device table can still be acquired using get_opt().

Returns:: device_map_t containing this’s device table.

See also

oni_get_opt()

Underlying C function when used in combination with ONI_OPT_DEVICETABLE.

frame_t read_frame() const#

Read a frame_t data from the acquisition context.

Returns:: frame_t from one of the devices in the device table.

Attention

This function must be called frequently enough to prevent overflow of the acquisition hardware buffer.

See also

oni_read_frame()

oni_destroy_frame()

Underlying C functions.

template<typename data_t> void write(size_t dev_idx, std::span<const data_t> data) const#

Write data to a device. This function wraps an entire oni_create_frame(), oni_write_frame(), and oni_destroy_frame() function call cycle.

Parameters:

dev_idx – Fully qualified oni_device_t.idx specifying the device to write data to.
data – Data block to write to the device.

Note

data.size() must be

An integer multiple of the selected dev_idx’s write size as indicated within the device table.
Smaller than the internal write block memory size (see ONI_OPT_BLOCKWRITESIZE and Setting Read and Write Buffer Sizes).

Note

std::span is automatically made available when compiled with stdlib >= C++20. Otherwise, this function reverts to returning a std::vector.

See also

oni_create_frame()

oni_write_frame()

oni_destroy_frame()

Underlying C functions.