Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/gnurou/v4l2r

Rust bindings for V4L2
https://github.com/gnurou/v4l2r

linux rust v4l2 v4l2-m2m

Last synced: 3 days ago
JSON representation

Rust bindings for V4L2

Awesome Lists containing this project

README 

        
# Rust bindings for V4L2



[![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

[![Build Status](https://github.com/Gnurou/v4l2r/actions/workflows/rust.yml/badge.svg)](https://github.com/Gnurou/v4l2r/actions)

[![Crates.io](https://img.shields.io/crates/v/v4l2r.svg)](https://crates.io/crates/v4l2r)

[![dependency status](https://deps.rs/repo/github/Gnurou/v4l2r/status.svg)](https://deps.rs/repo/github/Gnurou/v4l2r)

[![Documentation](https://docs.rs/v4l2r/badge.svg)](https://docs.rs/v4l2r/)



This is a work-in-progress library to implement safe Rust bindings and high-level

interfaces for V4L2.



Currently the following is implemented:



- Safe low-level abstractions to manage `OUTPUT` and `CAPTURE` queues, as well as

  buffers allocation/queueing/dequeuing for `MMAP`, `USERPTR` and `DMABUF` memory

  types,

- High-level abstraction of the [stateful video decoder

  interface](https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/dev-decoder.html),

- High-level abstraction of the [stateful video encoder

  interface](https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/dev-encoder.html),

- C FFI for using the video decoder interface from C programs.



The library provides several levels of abstraction over V4L2:



- At the lowest level is a very thin layer over the V4L2 ioctls, that stays as

  close as possible to the actual kernel API while adding extra safety and

  removing some of the historical baggage like the difference in format for

  single-planar and multi-planar queues.



- A higher-level abstraction exposes devices, queues, and other V4L2 concepts as

  strongly typed objects. The goal here is to provide an nice-to-use interface

  that remains generic enough to be used for any kind of V4L2 device.



- Finally, more specialized abstractions can be used by applications for

  performing specific tasks, like decoding a video using hardware acceleration.

  For these abstractions, a C FFI is usually provided so their use is not

  limited to Rust.



Dependencies shall be kept to a minimum: this library talks directly to the

kernel using ioctls, and only depends on a few small, well-established crates.



## Project Layout



`lib` contains the Rust library (`v4l2r`), including the thin `ioctl`

abstraction, the more usable `device` abstraction, and task-specific modules for

e.g. video decoding and encoding.



`ffi` contains the C FFI (`v4l2r-ffi`) which is currently exposed as a static

library other projects can link against. A `v4l2r.h` header file with the public

API is generated upon build.



## Build options



`cargo build` will attempt to generate the V4L2 bindings from

`/usr/include/linux/videodev2.h` by default. The `V4L2R_VIDEODEV2_H_PATH`

environment variable can be set to a different location that contains a

`videodev2.h` file if you need to generate the bindings from a different

location.



## How to use



Check `lib/examples/vicodec_test/device_api.rs` for a short example of how to

use the `device`-level interface, or `lib/examples/vicodec_test/ioctl_api.rs`

for the same example using the lower-level `ioctl` API. Both examples encode

generated frames into the `FWHT` format using the `vicodec` kernel driver

(which must be inserted beforehand, using e.g. `modprobe vicodec

multiplanar=1`).



You can try these examples with



    cargo run --example vicodec_test -- /dev/video0



for running the `device` API example, or



    cargo run --example vicodec_test -- /dev/video0 --use_ioctl



for the `ioctl` example, assuming `/dev/video0` is the path to the `vicodec`

encoder.



`lib/examples/fwht_encoder` contains another example program implementing a

higher-level vicodec encoder running in its own thread. It can be run as

follows:



    cargo run --example fwht_encoder -- /dev/video0 --stop_after 20 --save test_encoder.fwht



This invocation will encode 20 generated frames and save the resulting stream in

`test_encoder.fwht`. Pass `--help` to the program for further options.



`lib/examples/simple_decoder` is a decoder example able to decode the streams

produced by the `fwht_encoder` example above, as well as simple Annex-B H.264

streams. For instance, to decode the FWHT stream we just created above:



    cargo run --example simple_decoder -- test_encoder.fwht /dev/video1 --save test_decoder.bgr



`test_decoder.bgr` can be checked with e.g.

[YUView](https://github.com/IENT/YUView). The format will be 640x480 BGR, as

reported by the decoding program.



Finally, `ffi/examples/c_fwht_decode/` contains a C program demonstrating how

to use the C FFI to decode a FWHT stream. See the `Makefile` in that directory

for build and use instructions. The program is purely for demonstration

purposes of the C FII: it is hardcoded to decode the `sample.fwht` file in the

same directory and doesn't support any other output.



## Using in Android



`Android.bp` files are provided that should work on AOSP >= 15. Just check this

repository into `external/rust/crates/v4l2r` and the `libv4l2r` library target

will be available.