1# Libva Rust Wrapper
2
3This crate provides lightweight and (hopefully) safe libva abstractions for use
4within Rust code with minimal dependencies. It is developed for use in
5ChromeOS, but has no ChromeOS specifics or dependencies and should thus be
6usable anywhere.
7
8## Dependencies
9
10The native [libva](https://github.com/intel/libva) library is required at link
11time, so make sure to have the `libva-dev` or equivalent package for your
12distribution installed. The compatible libva version is 1.22.0. The VA-API
13driver corresponding to your hardware is also required: for Intel hardware it
14will be [intel-media-driver](https://github.com/intel/media-driver), whereas AMD
15hardware relies on [Mesa](https://gitlab.freedesktop.org/mesa/mesa).
16
17An easy way to see whether everything is in order is to run the `vainfo`
18utility packaged with `libva-utils` or as a standalone package in some
19distributions. `vainfo` will print the VA-API version, driver string, and a
20list of supported profiles and endpoints, i.e.:
21
22```
23vainfo: VA-API version: 1.13 (libva 2.13.0)
24vainfo: Driver version: Intel iHD driver for Intel(R) Gen Graphics - 22.2.2 ()
25vainfo: Supported profile and entrypoints
26      VAProfileNone                   : VAEntrypointVideoProc
27      VAProfileNone                   : VAEntrypointStats
28      VAProfileMPEG2Simple            : VAEntrypointVLD
29      VAProfileMPEG2Simple            : VAEntrypointEncSlice
30      VAProfileMPEG2Main              : VAEntrypointVLD
31      VAProfileMPEG2Main              : VAEntrypointEncSlice
32      VAProfileH264Main               : VAEntrypointVLD
33      etc
34```
35
36For decoding, the desired profile must be supported under `VAEntrypointVLD`.
37For example, in order to decode VP8 media, this line must be present in the
38output of `vainfo`:
39
40```
41      VAProfileVP8Version0_3          : VAEntrypointVLD
42```
43
44Whereas to decode H264 Main profile media, this line must be present:
45
46```
47      VAProfileH264Main               : VAEntrypointVLD
48```
49
50For more information on VA-API and its usage within ChromeOS, see [this
51guide](https://chromium.googlesource.com/chromium/src/+/master/docs/gpu/vaapi.md).
52
53cros-libva can also be built in Android. Android.bp files are provided that
54should work on AOSP >= 15. Just check this repository into
55external/rust/crates/cros-libva and the libcros_libva library target will be
56 available.
57
58## Using
59
60The name of this crate is `cros-libva` to highlight the fact that it originates
61from ChromeOS and it not an official bindings. For ease of use, it is
62recommended to rename it to just `libva` in your project by using the following
63line in your `Cargo.toml`:
64
65```
66libva = { package = "cros-libva", version = "0.0.1" }
67```
68
69## Testing
70
71For a brief introduction on how to use this crate, see the
72`libva_utils_mpeg2vldemo` test under `src/lib.rs`. You can also quickly test
73MPEG2 decoding by running it:
74
75```
76cargo test -- --ignored libva_utils_mpeg2vldemo
77```
78
79## Credits
80
81The first version of this crate was written by Daniel Almeida and hosted in the
82[crosvm repository](https://chromium.googlesource.com/crosvm/crosvm/) before
83being split.
84