| 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 `nihed-cros-libva` to highlight the fact that it |
| 60 | a custom fork of a library that originates |
| 61 | from ChromeOS and it not an official bindings. For ease of use, it is |
| 62 | recommended to rename it to just `libva` in your project by using the following |
| 63 | line in your `Cargo.toml`: |
| 64 | |
| 65 | ``` |
| 66 | libva = { package = "nihed-cros-libva", version = "0.0.1" } |
| 67 | ``` |
| 68 | |
| 69 | ## Testing |
| 70 | |
| 71 | For 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 |
| 73 | MPEG2 decoding by running it: |
| 74 | |
| 75 | ``` |
| 76 | cargo test -- --ignored libva_utils_mpeg2vldemo |
| 77 | ``` |