diff --git a/README.md b/README.md index 5c8206e..b3cca62 100644 --- a/README.md +++ b/README.md @@ -7,28 +7,33 @@ This crate provides safe bindings to the Video for Linux (V4L) stack. Modern device drivers will usually implement the `v4l2` API while older ones may depend on the legacy `v4l` API. Such legacy devices may be used with this crate by choosing the `libv4l` feature for this crate. ## Goals -This crate shall provide the v4l-sys package to enable full (but unsafe) access to libv4l\*. -On top of that, there will be a high level, more idiomatic API to use video capture devices in Linux. + +This crate shall provide the `v4l-sys` package to enable full (but unsafe) access to `libv4l\*`. +On top of that, there will be a high level, more idiomatic API to use video capture devices on Linux. There will be simple utility applications to list devices and capture frames. A minimalistic OpenGL/Vulkan viewer to display frames is planned for the future. ## Changelog + See [CHANGELOG.md](https://github.com/raymanfx/libv4l-rs/blob/master/CHANGELOG.md) -## Dependencies -You have the choice between two dependencies (both provided by this crate internally): - * libv4l-sys - > Link against the libv4l* stack including libv4l1, libv4l2, libv4lconvert. - > This has the advantage of emulating common capture formats such as RGB3 in userspace through libv4lconvert and more. - > However, some features like userptr buffers are not supported in libv4l. - * v4l2-sys - > Use only the Linux kernel provided v4l2 API provided by videodev2.h. - > You get support for all v4l2 features such as userptr buffers, but may need to do format conversion yourself if you require e.g. RGB/BGR buffers which may not be supported by commodity devices such as webcams. +## Cargo Features + +This crate has two primary features: -Enable either the `libv4l` or the `v4l2` backend by choosing the it as feature for this crate. +* `libv4l`: uses the `libv4l` wrapper libraries. + * Links against the `libv4l*` stack, including `libv4l1`, `libv4l2`, and `libv4lconvert`. + * Has the advantage of emulating common capture formats such as RGB3 in userspace through `libv4lconvert` and more. + * However, some features, like `userptr` buffers, are not supported in `libv4l`. +* `v4l2` (DEFAULT): uses the kernel's Video4Linux 2 kernel header directly. + * Only uses the Linux kernel provided v4l2 API provided by `videodev2.h`. + * You get support for all v4l2 features such as `userptr` buffers, but may need to do format conversion yourself if you require certain constructs (e.g. RGB/BGR buffers), which may not be supported by commodity devices such as webcams. + +You must select exactly one of these features. Note that the `v4l2` feature is on by default. To use `libv4l` instead, you'll need to also use the `default-features = false` dependency key. ## Usage + Below you can find a quick example usage of this crate. It introduces the basics necessary to do frame capturing from a streaming device (e.g. webcam). ```rust @@ -93,4 +98,4 @@ fn main() { } ``` -Have a look at the provided `examples` for more sample applications. +Have a look at the provided [`examples`](./examples/) for more sample applications. diff --git a/src/lib.rs b/src/lib.rs index fcbe19b..2272aeb 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -67,12 +67,25 @@ //! //! Have a look at the examples to learn more about device and buffer management. -#[cfg(feature = "v4l-sys")] +#[cfg(all(feature = "libv4l", feature = "v4l2"))] +compile_error!( + "You may not enable both `v4l-sys` and `v4l2-sys` features at the same time.\ + Try disabling one of them. If you only specified one feature, you may wish to\ + add `default-features = false` as a dependency key." +); + +#[cfg(all(feature = "libv4l", not(feature = "v4l2")))] pub use v4l_sys; -#[cfg(feature = "v4l2-sys")] +#[cfg(all(feature = "v4l2", not(feature = "libv4l")))] pub use v4l2_sys as v4l_sys; +// calms down rust-analyzer when `rust-analyzer.cargo.features = "all"`, +// though the `compile_error!()` above prevents this from being a valid, +// compilable configuration. +#[cfg(all(feature = "v4l2", feature = "libv4l"))] +pub use v4l_sys; + pub mod v4l2; pub mod buffer; diff --git a/src/v4l2/api.rs b/src/v4l2/api.rs index 70d3ff8..51fe5d0 100644 --- a/src/v4l2/api.rs +++ b/src/v4l2/api.rs @@ -4,7 +4,7 @@ use std::{io, path::Path}; use crate::v4l2::vidioc; -#[cfg(feature = "v4l-sys")] +#[cfg(all(feature = "libv4l", not(feature = "v4l2")))] mod detail { use crate::v4l2::vidioc; use crate::v4l_sys::*; @@ -56,7 +56,7 @@ mod detail { } } -#[cfg(feature = "v4l2-sys")] +#[cfg(feature = "v4l2")] mod detail { use crate::v4l2::vidioc;