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