[nihav-player.git] / nihed-cros-libva / README.md

# Libva Rust Wrapper

This crate provides lightweight and (hopefully) safe libva abstractions for use
within Rust code with minimal dependencies. It is developed for use in
ChromeOS, but has no ChromeOS specifics or dependencies and should thus be
usable anywhere.

The first version was written by Daniel Almeida and hosted in the [crosvm
repository](https://chromium.googlesource.com/crosvm/crosvm/) before being
split out here.

## Dependencies

The native [libva](https://github.com/intel/libva) library is required at link
time, so make sure to have the `libva-dev` or equivalent package for your
distribution installed. The VA-API driver corresponding to your hardware is
also required: for Intel hardware it will be
[intel-media-driver](https://github.com/intel/media-driver), whereas AMD
hardware relies on [Mesa](https://gitlab.freedesktop.org/mesa/mesa).

An easy way to see whether everything is in order is to run the `vainfo`
utility packaged with `libva-utils` or as a standalone package in some
distributions. `vainfo` will print the VA-API version, driver string, and a
list of supported profiles and endpoints, i.e.:

```
vainfo: VA-API version: 1.13 (libva 2.13.0)
vainfo: Driver version: Intel iHD driver for Intel(R) Gen Graphics - 22.2.2 ()
vainfo: Supported profile and entrypoints
      VAProfileNone                   : VAEntrypointVideoProc
      VAProfileNone                   : VAEntrypointStats
      VAProfileMPEG2Simple            : VAEntrypointVLD
      VAProfileMPEG2Simple            : VAEntrypointEncSlice
      VAProfileMPEG2Main              : VAEntrypointVLD
      VAProfileMPEG2Main              : VAEntrypointEncSlice
      VAProfileH264Main               : VAEntrypointVLD
      etc
```

For decoding, the desired profile must be supported under `VAEntrypointVLD`.
For example, in order to decode VP8 media, this line must be present in the
output of `vainfo`:

```
      VAProfileVP8Version0_3          : VAEntrypointVLD
```

Whereas to decode H264 Main profile media, this line must be present:

```
      VAProfileH264Main               : VAEntrypointVLD
```

For more information on VA-API and its usage within ChromeOS, see [this
guide](https://chromium.googlesource.com/chromium/src/+/master/docs/gpu/vaapi.md).

## Using

The name of this crate is `nihed-cros-libva` to highlight the fact that it
a custom fork of a library that originates
from ChromeOS and it not an official bindings. For ease of use, it is
recommended to rename it to just `libva` in your project by using the following
line in your `Cargo.toml`:

```
libva = { package = "nihed-cros-libva", version = "0.0.1" }
```

## Testing

For a brief introduction on how to use this crate, see the
`libva_utils_mpeg2vldemo` test under `src/lib.rs`. You can also quickly test
MPEG2 decoding by running it:

```
cargo test -- --ignored libva_utils_mpeg2vldemo
```
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
88067546 KS	59	The name of this crate is `nihed-cros-libva` to highlight the fact that it
88067546 KS	60	a custom fork of a library that originates
68362724 KS	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	```
88067546	66	libva = { package = "nihed-cros-libva", version = "0.0.1" }
68362724 KS	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	```