v4l/
lib.rs

1//! This crate provides safe bindings for the Video4Linux (v4l) stack.
2//!
3//! The stack consists of three libraries written in C:
4//! * libv4l1       (v4l1 API, deprecated)
5//! * libv4l2       (v4l2 API, the primary target of this crate)
6//! * libv4lconvert (emulates common formats such as RGB3 in userspace)
7//!
8//! Additional documentation can currently also be found in the
9//! [README.md file which is most easily viewed on github](https://github.com/raymanfx/libv4l-rs/blob/master/README.md).
10//!
11//! [Jump forward to crate content](#reexports)
12//!
13//! # Overview
14//!
15//! Video devices on Linux can be accessed by path or by index (which then corresponds to a path),
16//! e.g. "/dev/video0" for the device which first became known to the system.
17//!
18//! There are three methods of dealing with (capture) device memory:
19//! * `MMAP` (memory region in device memory or kernel space, mapped into userspace)
20//! * `User` pointer (memory region allocated in host memory, written into by the kernel)
21//! * `DMA` (direct memory access for memory transfer without involving the CPU)
22//!
23//! The following schematic shows the `mmap` and `userptr` mechanisms:
24//!
25//! **mmap**
26//!
27//! 1. `device --[MAP]--> kernel --[MAP]--> user`
28//! 2. `device --[DMA]--> kernel --[MAP]--> user`
29//!
30//! **userptr**
31//!
32//! 3. `device --[DMA]-->                   user`
33//!
34//!
35//! It is important to note that user pointer is for device-to-user memory transfer whereas
36//! DMA is for device-to-device transfer, e.g. directly uploading a captured frame into GPU
37//! memory.
38//!
39//! As you can see, user pointer and DMA are potential candidates for zero-copy applications where
40//! buffers should be writable. If a read-only buffer is good enough, MMAP buffers are fine and
41//! do not incur any copy overhead either. Most (if not all) devices reporting streaming I/O
42//! capabilities support MMAP buffer sharing, but not all support user pointer access.
43//!
44//! The regular user of this crate will mainly be interested in frame capturing.
45//! Here is a very brief example of streaming I/O with memory mapped buffers:
46//!
47//! ```no_run
48//! use v4l::buffer::Type;
49//! use v4l::io::traits::CaptureStream;
50//! use v4l::prelude::*;
51//!
52//! let mut dev = Device::new(0).expect("Failed to open device");
53//!
54//! let mut stream =
55//!     MmapStream::with_buffers(&mut dev, Type::VideoCapture, 4).expect("Failed to create buffer stream");
56//!
57//! loop {
58//!     let (buf, meta) = stream.next().unwrap();
59//!     println!(
60//!         "Buffer size: {}, seq: {}, timestamp: {}",
61//!        buf.len(),
62//!        meta.sequence,
63//!        meta.timestamp
64//!    );
65//!}
66//!```
67//!
68//! Have a look at the examples to learn more about device and buffer management.
69
70#[cfg(feature = "v4l-sys")]
71pub use v4l_sys;
72
73#[cfg(feature = "v4l2-sys")]
74pub use v4l2_sys as v4l_sys;
75
76pub mod v4l2;
77
78pub mod buffer;
79pub mod capability;
80pub mod context;
81pub mod control;
82pub mod device;
83pub mod format;
84pub mod fraction;
85pub mod frameinterval;
86pub mod framesize;
87pub mod memory;
88pub mod parameters;
89pub mod timestamp;
90pub mod video;
91
92pub mod io;
93
94pub use {
95    capability::Capabilities,
96    control::Control,
97    device::Device,
98    format::{Format, FourCC},
99    fraction::Fraction,
100    frameinterval::FrameInterval,
101    framesize::FrameSize,
102    memory::Memory,
103    timestamp::Timestamp,
104};
105
106pub mod prelude {
107    pub use crate::device::Device;
108    pub use crate::io::{mmap::Stream as MmapStream, userptr::Stream as UserptrStream};
109}
v4l/lib.rs

v4l/
lib.rs
