From 06ed05304e46189f0db7fe09f341bb2ff86bf377 Mon Sep 17 00:00:00 2001 From: barrett Date: Thu, 5 Sep 2024 12:37:39 -0500 Subject: [PATCH 1/8] fix(features): compile_error! on clashing features this prevents users from accidentally using both features, as they are mutually exclusive. it also includes a fix to calm`rust-analyzer`, as it has an option to check all features at the same time. i have that feature enabled in my editor by default, which caused around 100 errors and prevented "true" lints from showing in my IDE --- src/lib.rs | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index fcbe19b..2881019 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -67,12 +67,19 @@ //! //! 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"` +#[cfg(all(feature = "v4l2", feature = "libv4l"))] +pub use v4l_sys; + pub mod v4l2; pub mod buffer; From 5115eef8a46c1581cf1959fee43b16bf5a792069 Mon Sep 17 00:00:00 2001 From: barrett Date: Thu, 5 Sep 2024 12:56:35 -0500 Subject: [PATCH 2/8] fix(v4l2/api): put user-facing features in #[cfg]s in case the dependencies ever change, it's preferable to have user-facing features in here this also defaults to using the `v4l2` module branch when both features are enabled, allowing for easier development when all features are being checked by the IDE. --- src/v4l2/api.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/v4l2/api.rs b/src/v4l2/api.rs index 70d3ff8..ed8e922 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(feature = "libv4l")] mod detail { use crate::v4l2::vidioc; use crate::v4l_sys::*; @@ -56,7 +56,7 @@ mod detail { } } -#[cfg(feature = "v4l2-sys")] +#[cfg(all(feature = "v4l2", not(feature = "libv4l")))] mod detail { use crate::v4l2::vidioc; From 7d29fb93a741f2e795d9f8fd03efebb1a8a50483 Mon Sep 17 00:00:00 2001 From: barrett Date: Thu, 5 Sep 2024 13:02:10 -0500 Subject: [PATCH 3/8] docs: update `README.md` to contain feature info this also has some minor formatting changes to abide by the CommonMark standard --- README.md | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 5c8206e..0de8922 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 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. From ab476524bbc58628b44dc9d674afbf428db55f8c Mon Sep 17 00:00:00 2001 From: barrett Date: Thu, 5 Sep 2024 18:23:09 -0500 Subject: [PATCH 4/8] fix(v4l2/api): correct the feature order --- src/v4l2/api.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/v4l2/api.rs b/src/v4l2/api.rs index ed8e922..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 = "libv4l")] +#[cfg(all(feature = "libv4l", not(feature = "v4l2")))] mod detail { use crate::v4l2::vidioc; use crate::v4l_sys::*; @@ -56,7 +56,7 @@ mod detail { } } -#[cfg(all(feature = "v4l2", not(feature = "libv4l")))] +#[cfg(feature = "v4l2")] mod detail { use crate::v4l2::vidioc; From adbc618b50a2d28dc6a5a5a6fc43c0945f39d48a Mon Sep 17 00:00:00 2001 From: barrett <66580279+onkoe@users.noreply.github.com> Date: Thu, 5 Sep 2024 18:29:16 -0500 Subject: [PATCH 5/8] docs(README): add missing backticks Co-authored-by: Marijn Suijten --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0de8922..e4e0c08 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ This crate provides safe bindings to the Video for Linux (V4L) stack. Modern dev ## Goals -This crate shall provide the v4l-sys package to enable full (but unsafe) access to `libv4l\*`. +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. From cd40d4f22747da52aff3a1d7d925e916dbc82c6b Mon Sep 17 00:00:00 2001 From: barrett <66580279+onkoe@users.noreply.github.com> Date: Thu, 5 Sep 2024 18:32:54 -0500 Subject: [PATCH 6/8] docs(lib): expand on r-a workaround --- src/lib.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index 2881019..d662432 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -76,7 +76,9 @@ pub use v4l_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"` +// 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; From f110a2ea6bc2ed6f112a7f010f47d389e7dd5737 Mon Sep 17 00:00:00 2001 From: barrett Date: Thu, 5 Sep 2024 18:39:46 -0500 Subject: [PATCH 7/8] docs(README): specify v4l2 for kernel headers --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e4e0c08..b3cca62 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ This crate has two primary features: * 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 kernel header directly. +* `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. From b6506608ffca2fcb6bb2ed5f9983439935881d95 Mon Sep 17 00:00:00 2001 From: barrett Date: Thu, 5 Sep 2024 18:40:11 -0500 Subject: [PATCH 8/8] chore: wrap the compile_error()! it was too long --- src/lib.rs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index d662432..2272aeb 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -68,7 +68,11 @@ //! Have a look at the examples to learn more about device and buffer management. #[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."); +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;