README.md
1# Rust bindings for V4L2
2
3[](LICENSE)
4[](https://github.com/Gnurou/v4l2r/actions)
5[](https://crates.io/crates/v4l2r)
6[](https://deps.rs/repo/github/Gnurou/v4l2r)
7[](https://docs.rs/v4l2r/)
8
9This is a work-in-progress library to implement safe Rust bindings and high-level
10interfaces for V4L2.
11
12Currently the following is implemented:
13
14- Safe low-level abstractions to manage `OUTPUT` and `CAPTURE` queues, as well as
15 buffers allocation/queueing/dequeuing for `MMAP`, `USERPTR` and `DMABUF` memory
16 types,
17- High-level abstraction of the [stateful video decoder
18 interface](https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/dev-decoder.html),
19- High-level abstraction of the [stateful video encoder
20 interface](https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/dev-encoder.html),
21- C FFI for using the video decoder interface from C programs.
22
23The library provides several levels of abstraction over V4L2:
24
25- At the lowest level is a very thin layer over the V4L2 ioctls, that stays as
26 close as possible to the actual kernel API while adding extra safety and
27 removing some of the historical baggage like the difference in format for
28 single-planar and multi-planar queues.
29
30- A higher-level abstraction exposes devices, queues, and other V4L2 concepts as
31 strongly typed objects. The goal here is to provide an nice-to-use interface
32 that remains generic enough to be used for any kind of V4L2 device.
33
34- Finally, more specialized abstractions can be used by applications for
35 performing specific tasks, like decoding a video using hardware acceleration.
36 For these abstractions, a C FFI is usually provided so their use is not
37 limited to Rust.
38
39Dependencies shall be kept to a minimum: this library talks directly to the
40kernel using ioctls, and only depends on a few small, well-established crates.
41
42## Project Layout
43
44`lib` contains the Rust library (`v4l2r`), including the thin `ioctl`
45abstraction, the more usable `device` abstraction, and task-specific modules for
46e.g. video decoding and encoding.
47
48`ffi` contains the C FFI (`v4l2r-ffi`) which is currently exposed as a static
49library other projects can link against. A `v4l2r.h` header file with the public
50API is generated upon build.
51
52## Build options
53
54`cargo build` will attempt to generate the V4L2 bindings from
55`/usr/include/linux/videodev2.h` by default. The `V4L2R_VIDEODEV2_H_PATH`
56environment variable can be set to a different location that contains a
57`videodev2.h` file if you need to generate the bindings from a different
58location.
59
60## How to use
61
62Check `lib/examples/vicodec_test/device_api.rs` for a short example of how to
63use the `device`-level interface, or `lib/examples/vicodec_test/ioctl_api.rs`
64for the same example using the lower-level `ioctl` API. Both examples encode
65generated frames into the `FWHT` format using the `vicodec` kernel driver
66(which must be inserted beforehand, using e.g. `modprobe vicodec
67multiplanar=1`).
68
69You can try these examples with
70
71 cargo run --example vicodec_test -- /dev/video0
72
73for running the `device` API example, or
74
75 cargo run --example vicodec_test -- /dev/video0 --use_ioctl
76
77for the `ioctl` example, assuming `/dev/video0` is the path to the `vicodec`
78encoder.
79
80`lib/examples/fwht_encoder` contains another example program implementing a
81higher-level vicodec encoder running in its own thread. It can be run as
82follows:
83
84 cargo run --example fwht_encoder -- /dev/video0 --stop_after 20 --save test_encoder.fwht
85
86This invocation will encode 20 generated frames and save the resulting stream in
87`test_encoder.fwht`. Pass `--help` to the program for further options.
88
89`lib/examples/simple_decoder` is a decoder example able to decode the streams
90produced by the `fwht_encoder` example above, as well as simple Annex-B H.264
91streams. For instance, to decode the FWHT stream we just created above:
92
93 cargo run --example simple_decoder -- test_encoder.fwht /dev/video1 --save test_decoder.bgr
94
95`test_decoder.bgr` can be checked with e.g.
96[YUView](https://github.com/IENT/YUView). The format will be 640x480 BGR, as
97reported by the decoding program.
98
99Finally, `ffi/examples/c_fwht_decode/` contains a C program demonstrating how
100to use the C FFI to decode a FWHT stream. See the `Makefile` in that directory
101for build and use instructions. The program is purely for demonstration
102purposes of the C FII: it is hardcoded to decode the `sample.fwht` file in the
103same directory and doesn't support any other output.
104
105## Using in Android
106
107`Android.bp` files are provided that should work on AOSP >= 15. Just check this
108repository into `external/rust/crates/v4l2r` and the `libv4l2r` library target
109will be available.
110
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}