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

1. An integer multiple of the selected dev_idx’s write size as indicated within the device table.

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