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

cpponi

onix.hpp