nihed-cros-libva/README.md

   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 ```