README.md
1# Intel(R) Media Driver for VAAPI
2
3
4## Introduction
5
6The Intel(R) Media Driver for VAAPI is a new VA-API (Video Acceleration API)
7user mode driver supporting hardware accelerated decoding, encoding, and
8video post processing for GEN based graphics hardware.
9
10## License
11
12The Intel(R) Media Driver for VAAPI is distributed under the MIT license with
13portions covered under the BSD 3-clause "New" or "Revised" License.
14You may obtain a copy of the License at [MIT](https://opensource.org/licenses/MIT) & [BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause)
15
16## Prerequisites
17
18For Ubuntu 16.04+
19
20```
21apt install autoconf libtool libdrm-dev xorg xorg-dev openbox libx11-dev libgl1-mesa-glx libgl1-mesa-dev
22```
23
24Equivalents for other distributions should work.
25
26## Dependencies
27
28* [Libva](https://github.com/intel/libva)
29* [GmmLib](https://github.com/intel/gmmlib)(Please check [comparability with GmmLib](https://github.com/intel/media-driver/wiki/Comparability-with-GmmLib))
30
31## Building
32
331. Build and install libva master
342. Build and install gmmlib master
353. Get media repo and format the workspace folder as below (suggest the workspace to be a dedicated one for media driver build):
36```
37<workspace>
38 |- media-driver
39```
404.
41```
42$ mkdir <workspace>/build_media
43```
445.
45```
46$ cd <workspace>/build_media
47```
486.
49```
50$ cmake ../media-driver
51```
527.
53```
54$ make -j"$(nproc)"
55```
56
57## Install
58
59```
60$ sudo make install
61```
62This will install the following files (e.g. on Ubuntu):
63```
64-- Installing: /usr/lib/x86_64-linux-gnu/dri/iHD_drv_video.so
65-- Installing: /etc/profile.d/intel-media.sh
66-- Installing: /usr/lib/x86_64-linux-gnu/igfxcmrt64.so
67```
68
69For iHD_drv_video.so please export related LIBVA environment variables.
70```
71export LIBVA_DRIVERS_PATH=<path-contains-iHD_drv_video.so>
72export LIBVA_DRIVER_NAME=iHD
73```
74
75
76## Supported Platforms
77
78* BDW (Broadwell)
79* SKL (Skylake)
80* BXT (Broxton) / APL (Apollo Lake)
81* KBLx (KBL/Kaby Lake; CFL/Coffe Lake; WHL/Whiskey Lake; CML/Comet Lake; AML/Amber Lake)
82* ICL (Ice Lake)
83* JSL (Jasper Lake)/EHL (Elkhart Lake)
84* TGL (Tiger Lake)
85
86
87## Components and Features
88
89Media driver contains three components as below
90* **Video decoding** calls hardware-based decoder([VDBox](https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-kbl-vol08-media_vdbox.pdf)) which provides fully-accelerated hardware video decoding to release the graphics engine for other operations.
91* **Video encoding** supports two modes, one calls hardware-based encoder([VDEnc](https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-kbl-vol08-media_vdbox.pdf)/[Huc](https://01.org/linuxgraphics/downloads/firmware?langredirect=1)) to provide low power encoding, another one is hardware([PAK](https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-kbl-vol08-media_vdbox.pdf))+shader(media kernel+[VME](https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-kbl-vol04-configurations.pdf)) based encoding. User could choose the mode through VA-API.
92* **Video processing** supports several popular features by hardware-based video processor([VEBox/SFC](https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-kbl-vol09-media_vebox.pdf)) and shader(media kernel) based solution together.
93
94Media driver supports two build types as below
95* **Full Feature Build** is default driver build, which supports all feature by hardware accelerator and close source shaders(media kernel binaries). Ubuntu [intel-media-va-driver-non-free](https://packages.ubuntu.com/disco/intel-media-va-driver-non-free) package is generated from this build type.
96* **Free Kernel Build**, enables fully open source shaders(media kernels) and hardware features but the features would be limited. Ubuntu [intel-media-va-driver](https://packages.ubuntu.com/disco/intel-media-va-driver) package is generated from this build type.
97
98
99### Decoding/Encoding Features
100
101| CODEC | Build Types | BDW | SKL | BXT/APL | KBLx | ICL | EHL/JSL | TGL* |
102|---|---|---|---|---|---|---|----|---|
103| AVC | <u>Full Feature</u><br><i>Free Kernel</i> | <u>D/Es</u><br><i>D<i> | <u>D/E/Es</u><br><i>D/E<i> | <u>D/E/Es</u><br><i>D/E<i> | <u>D/E/Es</u><br><i>D/E<i> | <u>D/E/Es</u><br><i>D/E<i> | <u>D/E</u><br><i>D/E<i> | <u>D/E/Es</u><br><i>D/E<i>|
104| MPEG-2 | <u>Full Feature</u><br><i>Free Kernel</i> | <u>D/Es</u><br><i>D<i> | <u>D/Es</u><br><i>D<i> | <u>D</u><br><i>D<i> | <u>D/Es</u><br><i>D<i> | <u>D/Es</u><br><i>D<i> | <u>D</u><br><i>D<i> |<u>D/Es</u><br><i>D<i>|
105| VC-1 | <u>Full Feature</u><br><i>Free Kernel</i> | <u>D</u><br><i> <i> | <u>D</u><br><i> <i> | <u>D</u><br><i> <i> | <u>D</u><br><i> <i> | <u>D</u><br><i> <i> | <u>D</u><br><i> <i> |<u>D</u><br><i> <i>|
106| JPEG | <u>Full Feature</u><br><i>Free Kernel</i> | <u>D</u><br><i>D<i> | <u>D/E</u><br><i>D/E<i> | <u>D/E</u><br><i>D/E<i> | <u>D/E</u><br><i>D/E<i> | <u>D/E</u><br><i>D/E<i> | <u>D/E</u><br><i>D/E<i> |<u>D/E</u><br><i>D/E<i>|
107| VP8 | <u>Full Feature</u><br><i>Free Kernel</i> | <u>D</u><br><i>D<i> | <u>D</u><br><i>D<i> | <u>D</u><br><i>D<i> | <u>D/Es</u><br><i>D<i> | <u>D/Es</u><br><i>D<i> | <u>D</u><br><i>D<i> | |
108| HEVC 8bit | <u>Full Feature</u><br><i>Free Kernel</i> | | <u>D/Es</u><br><i>D<i> | <u>D/Es</u><br><i>D<i> | <u>D/Es</u><br><i>D<i> | <u>D/E/Es</u><br><i>D/E<i> | <u>D/E</u><br><i>D/E<i> |<u>D/E/Es</u><br><i>D/E<i> |
109| HEVC 8bit 422 | <u>Full Feature</u><br><i>Free Kernel</i> | | | | | <u>D/Es</u><br><i>D<i> | <u>D</u><br><i>D<i> |<u>D/Es</u><br><i>D<i>|
110| HEVC 8bit 444 | <u>Full Feature</u><br><i>Free Kernel</i> | | | | | <u>D/E</u><br><i>D/E<i> | <u>D/E</u><br><i>D/E<i> | <u>D/E</u><br><i>D/E<i> |
111| HEVC 10bit | <u>Full Feature</u><br><i>Free Kernel</i> | | | <u>D</u><br><i>D<i> | <u>D/Es</u><br><i>D<i> | <u>D/E/Es</u><br><i>D/E<i> | <u>D/E</u><br><i>D/E<i> | <u>D/E/Es</u><br><i>D/E<i> |
112| HEVC 10bit 422 | <u>Full Feature</u><br><i>Free Kernel</i> | | | | | <u>D/Es</u><br><i>D<i> | <u>D</u><br><i>D<i>| <u>D/Es</u><br><i>D<i> |
113| HEVC 10bit 444 | <u>Full Feature</u><br><i>Free Kernel</i> | | | | | <u>D/E</u><br><i>D/E<i> | <u>D/E</u><br><i>D/E<i> |<u>D/E</u><br><i>D/E<i> |
114| HEVC 12bit | <u>Full Feature</u><br><i>Free Kernel</i> | | | | | | |<u>D/Es</u><br><i>D<i> |
115| HEVC 12bit 422 | <u>Full Feature</u><br><i>Free Kernel</i> | | | | | | |<u>D</u><br><i>D<i> |
116| HEVC 12bit 444 | <u>Full Feature</u><br><i>Free Kernel</i> | | | | | | |<u>D</u><br><i>D<i> |
117| VP9 8bit | <u>Full Feature</u><br><i>Free Kernel</i> | | | <u>D</u><br><i>D<i> | <u>D</u><br><i>D<i> | <u>D/E</u><br><i>D/E<i> | <u>D/E</u><br><i>D/E<i> |<u>D/E</u><br><i>D/E<i> |
118| VP9 8bit 444 | <u>Full Feature</u><br><i>Free Kernel</i> | | | | | <u>D/E</u><br><i>D/E<i> | <u>D/E</u><br><i>D/E<i> |<u>D/E</u><br><i>D/E<i> |
119| VP9 10bit | <u>Full Feature</u><br><i>Free Kernel</i> | | | | <u>D</u><br><i>D<i> | <u>D/E</u><br><i>D/E<i> | <u>D/E</u><br><i>D/E<i> |<u>D/E</u><br><i>D/E<i> |
120| VP9 10bit 444 | <u>Full Feature</u><br><i>Free Kernel</i> | | | | | <u>D/E</u><br><i>D/E<i> | <u>D/E</u><br><i>D/E<i> |<u>D/E</u><br><i>D/E<i> |
121| VP9 12bit | <u>Full Feature</u><br><i>Free Kernel</i> | | | | | | |<u>D</u><br><i>D<i> |
122| VP9 12bit 444 | <u>Full Feature</u><br><i>Free Kernel</i> | | | | | | |<u>D</u><br><i>D<i> |
123* D - Hardware Decoding
124* E - Hardware Encoding, Low Power Encoding(VDEnc/Huc)
125* Es - Hardware(PAK) + Shader(media kernel+VME) Encoding
126
127\* TGL encoding is pending on i915 support on upstream, for more information, please check [Known Issues and Limitations #4, #5](https://github.com/intel/media-driver/blob/master/README.md#known-issues-and-limitations).
128
129For more information, please refer to
130* [Media Features Summary](https://github.com/intel/media-driver/blob/master/docs/media_features.md#media-features-summary)
131 * [Supported Decoding Output Format and Max Resolution](https://github.com/intel/media-driver/blob/master/docs/media_features.md#supported-decoding-output-format-and-max-resolution)
132 * [Supported Encoding Input Format and Max Resolution](https://github.com/intel/media-driver/blob/master/docs/media_features.md#supported-encoding-input-format-and-max-resolution)
133
134### Video Processing Features
135
136| Features | Build Types | BDW | SKL | BXT/APL | KBLx | ICL |EHL/JSL |TGL |
137|---|---|---|---|---|----|---|---|---|
138| Blending | <u>Full Feature</u><br><i>Free Kernel</i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |
139| CSC<br>(Color Space Conversion) | <u>Full Feature</u><br><i>Free Kernel</i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |
140| De-interlace | <u>Full Feature</u><br><i>Free Kernel</i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i>Yes</i> |<u>Yes*</u><br><i>Yes*</i> |<u>Yes</u><br><i>Yes</i> |
141| De-noise | <u>Full Feature</u><br><i>Free Kernel</i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> |<u>No</u><br><i> </i> |<u>Yes</u><br><i> </i> |
142| Luma Key | <u>Full Feature</u><br><i>Free Kernel</i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |
143| Mirroring | <u>Full Feature</u><br><i>Free Kernel</i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |
144| ProcAmp<br>(brightness,contrast,hue,saturation) | <u>Full Feature</u><br><i>Free Kernel</i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |
145| Rotation | <u>Full Feature</u><br><i>Free Kernel</i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |
146| Scaling | <u>Full Feature</u><br><i>Free Kernel</i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |
147| Sharpening | <u>Full Feature</u><br><i>Free Kernel</i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i>Yes</i> |<u>No</u><br><i>No</i> |<u>Yes</u><br><i>Yes</i> |
148| STD/E<br>(Skin Tone Detect & Enhancement) | <u>Full Feature</u><br><i>Free Kernel</i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> |<u>No</u><br><i> </i> |<u>Yes</u><br><i> </i> |
149| TCC<br>(Total Color Control) | <u>Full Feature</u><br><i>Free Kernel</i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> |<u>No</u><br><i> </i> |<u>Yes</u><br><i> </i> |
150| Color fill | <u>Full Feature</u><br><i>Free Kernel</i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i>Yes</i> | <u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |
151| Chroma Siting | <u>Full Feature</u><br><i>Free Kernel</i> | <br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i> </i> | <u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |<u>Yes</u><br><i>Yes</i> |
152| HDR10 Tone Mapping | <u>Full Feature</u><br><i>Free Kernel</i> | <br><i> </i> | <br><i> </i> | <br><i> </i> | <br><i> </i> | <u>Yes</u><br><i> </i> |<u>No</u><br><i> </i> |<u>Yes</u><br><i> </i> |
153
154For more feature information, please refer to [Supported video processing csc/scaling format](https://github.com/intel/media-driver/blob/master/docs/media_features.md#supported-video-processing-cscscaling-format)
155
156
157### Build Options
158
159You could follow below build options to enable these two builds.
160* **Full Feature Build**: ENABLE_KERNELS=ON(Default) ENABLE_NONFREE_KERNELS=ON(Default)
161* **Free Kernel Build**: ENABLE_KERNELS=ON ENABLE_NONFREE_KERNELS=OFF
162 * If trying to use pre-built open source kernel binaries, please add BUILD_KERNELS=OFF(Default).
163 * If trying to rebuild open source kernel from source code, please add BUILD_KERNELS=ON.
164
165\* EHL/JSL only support BOB DI
166
167## Known Issues and Limitations
168
1691. Intel(R) Media Driver for VAAPI is recommended to be built against gcc compiler v6.1
170or later, which officially supported C++11.
171
1722. SKL: Green or other incorrect color will be observed in output frames when using YV12/I420 as input format for csc/scaling/blending/rotation, etc. on Ubuntu 16.04 stock (with kernel 4.10). The issue can be addressed with the kernel patch: [WaEnableYV12BugFixInHalfSliceChicken7](https://cgit.freedesktop.org/drm-tip/commit/?id=0b71cea29fc29bbd8e9dd9c641fee6bd75f68274)
173
1743. HuC firmware is needed for AVC/HEVC/VP9 low power encoding bitrate control, including CBR, VBR, etc. As of now, HuC firmware support is disabled in Linux kernels by default. Please, refer to i915 kernel mode driver documentation to learn how to enable it. Mind that HuC firmware support presents in the following kernels for the specified platforms:
175 * APL/KBL: starting from kernel 4.11
176 * CFL: starting from kernel 4.15
177 * ICL: starting from kernel 5.2
178 * EHL/JSL/TGL: [drm-tip](https://cgit.freedesktop.org/drm-tip), missed in <=5.4.3 kernels
179
1804. TGL: preliminary support and may not be fully functional. It requires Linux kernel 5.4+ loaded with i915.force_probe=* parameter to be tried. [drm-tip] (https://cgit.freedesktop.org/drm-tip) should work with more support and bug fixes.
181
1825. TGL VME encode has known issue [112377](https://bugs.freedesktop.org/show_bug.cgi?id=112377) with [drm-tip](https://cgit.freedesktop.org/drm-tip)
183
184##### (*) Other names and brands may be claimed as property of others.
185