update readme with some comments about internals
MODIFY
README.md
README.md
@@ -7,18 +7,44 @@ Experimental Rust bindings for OpenCV 3.
The API is usable but unstable and not very battle-tested; use at your own risk.
-## API Docs
+## API
[API Documentation](https://docs.rs/opencv) is, to varying success,
translated from OpenCV's doxygen docs. Most likely you'll want to
refer to the official [OpenCV C++
documentation](https://docs.opencv.org/3.4.6/) as well.
+### Functionality
+
+Generally the crate tries to only wrap OpenCV API and provide some convenience functions
+to be able to use it in Rust easier. We try to avoid adding any functionality besides
+that.
+
+### Callbacks
+
+Some API functions accept callbacks, e.g. set_mouse_callback. While currently
+it's possible to successfully use those functions there are some limitations to
+keep in mind. Current implementation of callback handling keeps hold of the
+passed callback argument forever. That means that the closure used as a callback
+will never be freed during the lifetime of a program and moreover Drop will
+not be called for it (they are stored in global static [`Slab`](https://crates.io/crates/slab)).
+There is a plan to implement possibility to be able to free at least some of the
+closures.
+
+### Unsafety
+
+Although crate tries to provide ergonomic Rust interface for OpenCV, don't expect
+Rust safety guarantees at this stage. It's especially true for borrow checking and
+shared mutable ownership. Notable example would be `Mat` which is a reference counted
+object in its essence. You can own a seemingly separate `Mat` in Rust terms, but
+it's going to be a mutable reference to the other `Mat` under the hood. Treat safety
+of the crate's API as you would treat one of C++, use `clone()` when needed.
+
## Getting Started
The following external dependencies are required:
- python2.7
-- opencv 3.4.6 (other 3.4 versions may work, but development is done
+- OpenCV 3.4.6 (other 3.4 versions may work, but development is done
against this version)
OpenCV is a complicated dependency with a lot of different
@@ -28,7 +54,7 @@ if builds with this crate fail.
### See if you already have the right version of OpenCV installed
-if opencv is installed, its version can be checked with:
+if OpenCV is installed, its version can be checked with:
```sh
opencv_version
@@ -36,8 +62,8 @@ opencv_version
### Install OpenCV
-Install opencv 3.4.6. Check your platform's package manager or see the
-upstream opencv
+Install OpenCV 3.4.6. Check your platform's package manager or see the
+upstream OpenCV
[installation guides](https://docs.opencv.org/3.4/df/d65/tutorial_table_of_content_introduction.html).
### Compiling OpenCV
@@ -69,6 +95,7 @@ cmake \
-DOPENCV_EXTRA_MODULES_PATH=$PATH_TO_OPENCV_CONTRIB_MODULES \
$PATH_TO_OPENCV_SRC
```
+
## Contrib modules
The following modules require contrib installed:
* bioinspired
@@ -82,13 +109,13 @@ The following modules require contrib installed:
## OpenCV 2 support
-If you can't use opencv 3.4.6, the (no longer maintained) `0.2.4`
-version of this crate is known to work with opencv `2.4.7.13` (and probably other 2.4 versions).
+If you can't use OpenCV 3.4.6, the (no longer maintained) `0.2.4`
+version of this crate is known to work with OpenCV `2.4.7.13` (and probably other 2.4 versions).
## The binding strategy
-This crate works following the model of python and java's opencv
-wrappers - it parses the opencv C++ headers, generates a C interface
+This crate works following the model of python and java's OpenCV
+wrappers - it parses the OpenCV C++ headers, generates a C interface
to the C++ api, and wraps the C interface in Rust.
All the major modules in the C++ API are merged together in a huge
@@ -117,7 +144,7 @@ developing this crate, you can test changes to the binding generation
using `cargo build -vv --features buildtime_bindgen`. When changing
the codegen, be sure to push changes to the generated code!
-`hdr_parser.py` comes from opencv python/java generator. We've tried
+`hdr_parser.py` comes from OpenCV python/java generator. We've tried
not to mess too much with this file, but had to make a few changes.
`gen_rust.py` is initially a copy of gen_java, also from the OpenCV

update readme with some comments about internals