1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103

//! This crate provides safe bindings for the Video4Linux (v4l) stack.
//!
//! The stack consists of three libraries written in C:
//! * libv4l1       (v4l1 API, deprecated)
//! * libv4l2       (v4l2 API, the primary target of this crate)
//! * libv4lconvert (emulates common formats such as RGB3 in userspace)
//!
//! Additional documentation can currently also be found in the
//! [README.md file which is most easily viewed on github](https://github.com/raymanfx/libv4l-rs/blob/master/README.md).
//!
//! [Jump forward to crate content](#reexports)
//!
//! # Overview
//!
//! Video devices on Linux can be accessed by path or by index (which then corresponds to a path),
//! e.g. "/dev/video0" for the device which first became known to the system.
//!
//! There are three methods of dealing with (capture) device memory:
//! * MMAP (memory region in device memory or kernel space, mapped into userspace)
//! * User pointer (memory region allocated in host memory, written into by the kernel)
//! * DMA (direct memory access for memory transfer without involving the CPU)
//!
//! The following schematic shows the mmap and userptr mechanisms:
//!
//! **mmap**
//!
//! 1. device --[MAP]--> kernel --[MAP]--> user
//! 2. device --[DMA]--> kernel --[MAP]--> user
//!
//! **userptr**
//!
//! 3. device --[DMA]-->                   user
//!
//!
//! It is important to note that user pointer is for device-to-user memory transfer whereas
//! DMA is for device-to-device transfer, e.g. directly uploading a captured frame into GPU
//! memory.
//!
//! As you can see, user pointer and DMA are potential candidates for zero-copy applications where
//! buffers should be writable. If a read-only buffer is good enough, MMAP buffers are fine and
//! do not incur any copy overhead either. Most (if not all) devices reporting streaming I/O
//! capabilites support MMAP buffer sharing, but not all support user pointer access.
//!
//! The regular user of this crate will mainly be interested in frame capturing.
//! Here is a very brief example of streaming I/O with memory mapped buffers:
//!
//! ```no_run
//! use v4l::prelude::*;
//!
//! let mut dev = CaptureDevice::new(0).expect("Failed to open device");
//!
//! let stream =
//!     MmapStream::with_buffers(&mut dev, 4).expect("Failed to create buffer stream");
//!
//! for frame in stream {
//!     println!(
//!         "Buffer size: {}, seq: {}, timestamp: {}",
//!        frame.len(),
//!        frame.meta().seq,
//!        frame.meta().timestamp
//!    );
//!}
//!```
//!
//! Have a look at the examples to learn more about device and buffer management.

#[cfg(feature = "v4l-sys")]
pub use v4l_sys;

#[cfg(feature = "v4l2-sys")]
pub use v4l2_sys as v4l_sys;

pub mod v4l2;

pub mod buffer;
pub mod capability;
pub mod capture;
pub mod control;
pub mod device;
pub mod format;
pub mod fourcc;
pub mod fraction;
pub mod frameinterval;
pub mod framesize;
pub mod memory;
pub mod timestamp;

pub mod io;

pub use {
    buffer::Buffer, capability::Capabilities, control::Control, format::Description,
    fourcc::FourCC, fraction::Fraction, frameinterval::FrameInterval, framesize::FrameSize,
    memory::Memory, timestamp::Timestamp,
};

pub mod prelude {
    pub use crate::io::{mmap::Stream as MmapStream, userptr::Stream as UserptrStream};
    pub use crate::{
        buffer::{Arena, Buffer, Stream},
        capture::Device as CaptureDevice,
        device::{Device, QueryDevice},
    };
}