# libpvcam-sys

Rust bindings for Photometrics' PVCam C SDK. Highly experimental.

This has only been tested on Ubuntu so far.

## Dependencies

 * `rustup @ 1.22.1`
 * `libclang1-9`
 * `pvcam` from [Photometrics][pvcam]
   * only verified with versions: `3.8.4.3` and `3.9.4.0`

## Setup

It is assumed that pvcam is installed as per the installation instructions for
Ubuntu.

## Notes

This library uses the [bindgen][bindgen] which tries its best to navigate header
files and produce appropriate structs and FFI interfaces. You'll notice a lot of
casting too/from types in this binding. It may be likely that bindgen settings
could reduce that.

The PVCam SDK has a lot of deprecations in it, as such the bindgen invocation in
[build.rs](build.rs) aggressively does not import a range of functions. However,
it may be better to use the `whitelist` option instead and build the list from
a script similar to how [Photometrics' python binding][pyvcam] does this.

### Module Structure

```
o -- lib.rs
    `-- pvcam (public)
       `-- internal (private)
```

The public `pvcam` module re-exports internal concepts generated by bindgen and 
makes them minimally rusty. It's likely that some of these rust patterns are:

 1. incorrect
 2. too opinionated

On the first case: I (Mike Ossareh) am not clear enough on the semantics of when
to use various ptr types in a binding. The [Primitive Pointer Docs][primptr]
cover this. Also, I'm new to Rust ^_^.

On the second case: Rust Enum's mapping over PVCam SDK Enums probably
demonstrates this most clearly. These may be good candidates for lifting into
a higher level library which implements other niceties like a PVCamContext
which frees resources when it leaves scope. With the aim being to leave this
layer just as C-like as possible.

## TODO

 - [] verify dependencies documented in this readme
 - [] verify installation steps documented in this readme


[pvcam]: https://www.photometrics.com/support/software-and-drivers
[pyvcam]: https://github.com/Photometrics/PyVCAM
[bindgen]: https://rust-lang.github.io/rust-bindgen/
[primptr]: https://doc.rust-lang.org/std/primitive.pointer.html