1# Rust bindings for V4L2
2
3[![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
4[![Build Status](https://github.com/Gnurou/v4l2r/actions/workflows/rust.yml/badge.svg)](https://github.com/Gnurou/v4l2r/actions)
5[![Crates.io](https://img.shields.io/crates/v/v4l2r.svg)](https://crates.io/crates/v4l2r)
6[![dependency status](https://deps.rs/repo/github/Gnurou/v4l2r/status.svg)](https://deps.rs/repo/github/Gnurou/v4l2r)
7[![Documentation](https://docs.rs/v4l2r/badge.svg)](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## How to use
53
54Check `lib/examples/vicodec_test/device_api.rs` for a short example of how to
55use the `device`-level interface, or `lib/examples/vicodec_test/ioctl_api.rs`
56for the same example using the lower-level `ioctl` API. Both examples encode
57generated frames into the `FWHT` format using the `vicodec` kernel driver
58(which must be inserted beforehand, using e.g. `modprobe vicodec
59multiplanar=1`).
60
61You can try these examples with
62
63    cargo run --example vicodec_test -- /dev/video0
64
65for running the `device` API example, or
66
67    cargo run --example vicodec_test -- /dev/video0 --use_ioctl
68
69for the `ioctl` example, assuming `/dev/video0` is the path to the `vicodec`
70encoder.
71
72`lib/examples/fwht_encoder` contains another example program implementing a
73higher-level vicodec encoder running in its own thread. It can be run as
74follows:
75
76    cargo run --example fwht_encoder -- /dev/video0 --stop_after 20 --save test_encoder.fwht
77
78This invocation will encode 20 generated frames and save the resulting stream in
79`test_encoder.fwht`. Pass `--help` to the program for further options.
80
81`lib/examples/simple_decoder` is a decoder example able to decode the streams
82produced by the `fwht_encoder` example above, as well as simple Annex-B H.264
83streams. For instance, to decode the FWHT stream we just created above:
84
85    cargo run --example simple_decoder -- test_encoder.fwht /dev/video1 --save test_decoder.bgr
86
87`test_decoder.bgr` can be checked with e.g.
88[YUView](https://github.com/IENT/YUView). The format will be 640x480 BGR, as
89reported by the decoding program.
90
91Finally, `ffi/examples/c_fwht_decode/` contains a C program demonstrating how
92to use the C FFI to decode a FWHT stream. See the `Makefile` in that directory
93for build and use instructions. The program is purely for demonstration
94purposes of the C FII: it is hardcoded to decode the `sample.fwht` file in the
95same directory and doesn't support any other output.
96
97## Using in Android
98
99`Android.bp` files are provided that should work on AOSP >= 15. Just check this
100repository into `external/rust/crates/v4l2r` and the `libv4l2r` library target
101will be available.
102