README.md
1# libgav1 -- an AV1 decoder
2
3libgav1 is a Main profile (0), High profile (1) & Professional profile (2)
4compliant AV1 decoder. More information on the AV1 video format can be found at
5[aomedia.org](https://aomedia.org).
6
7[TOC]
8
9## Building
10
11### Prerequisites
12
131. A C++11 compiler. gcc 6+, clang 7+ or Microsoft Visual Studio 2017+ are
14 recommended.
15
162. [CMake >= 3.7.1](https://cmake.org/download/)
17
183. [Abseil](https://abseil.io)
19
20 From within the libgav1 directory:
21
22 ```shell
23 $ git clone -b 20220623.0 --depth 1 \
24 https://github.com/abseil/abseil-cpp.git third_party/abseil-cpp
25 ```
26
27 Note: Abseil is required by the examples and tests. libgav1 will depend on
28 it if `LIBGAV1_THREADPOOL_USE_STD_MUTEX` is set to `0` (see below).
29
304. (Optional) [GoogleTest](https://github.com/google/googletest)
31
32 From within the libgav1 directory:
33
34 ```shell
35 $ git clone -b release-1.12.1 --depth 1 \
36 https://github.com/google/googletest.git third_party/googletest
37 ```
38
39### Compile
40
41```shell
42 $ mkdir build && cd build
43 $ cmake -G "Unix Makefiles" ..
44 $ make
45```
46
47Configuration options:
48
49* `LIBGAV1_MAX_BITDEPTH`: defines the maximum supported bitdepth (8, 10, 12;
50 default: 12).
51* `LIBGAV1_ENABLE_ALL_DSP_FUNCTIONS`: define to a non-zero value to disable
52 [symbol reduction](#symbol-reduction) in an optimized build to keep all
53 versions of dsp functions available. Automatically defined in
54 `src/dsp/dsp.h` if unset.
55* `LIBGAV1_ENABLE_AVX2`: define to a non-zero value to enable avx2
56 optimizations. Automatically defined in `src/utils/cpu.h` if unset.
57* `LIBGAV1_ENABLE_NEON`: define to a non-zero value to enable NEON
58 optimizations. Automatically defined in `src/utils/cpu.h` if unset.
59* `LIBGAV1_ENABLE_SSE4_1`: define to a non-zero value to enable sse4.1
60 optimizations. Automatically defined in `src/utils/cpu.h` if unset. Note
61 setting this to 0 will also disable AVX2.
62* `LIBGAV1_ENABLE_LOGGING`: define to 0/1 to control debug logging.
63 Automatically defined in `src/utils/logging.h` if unset.
64* `LIBGAV1_EXAMPLES_ENABLE_LOGGING`: define to 0/1 to control error logging in
65 the examples. Automatically defined in `examples/logging.h` if unset.
66* `LIBGAV1_ENABLE_TRANSFORM_RANGE_CHECK`: define to 1 to enable transform
67 coefficient range checks.
68* `LIBGAV1_LOG_LEVEL`: controls the maximum allowed log level, see `enum
69 LogSeverity` in `src/utils/logging.h`. Automatically defined in
70 `src/utils/logging.cc` if unset.
71* `LIBGAV1_THREADPOOL_USE_STD_MUTEX`: controls use of std::mutex and
72 absl::Mutex in ThreadPool. Defining this to 1 will remove any Abseil
73 dependency from the core library. Automatically defined in
74 `src/utils/threadpool.h` if unset. Defaults to 1 on Android & iOS, 0
75 otherwise.
76* `LIBGAV1_MAX_THREADS`: sets the number of threads that the library is
77 allowed to create. Has to be an integer > 0. Otherwise this is ignored. The
78 default value is 128.
79* `LIBGAV1_FRAME_PARALLEL_THRESHOLD_MULTIPLIER`: the threshold multiplier that
80 is used to determine when to use frame parallel decoding. Frame parallel
81 decoding will be used if |threads| > |tile_count| * this multiplier. Has to
82 be an integer > 0. The default value is 4. This is an advanced setting
83 intended for testing purposes.
84* `CHROMIUM`: apply Chromium-specific changes if set.
85
86For additional options see:
87
88```shell
89 $ cmake .. -LH
90```
91
92## Testing
93
94* `gav1_decode` can be used to decode IVF files, see `gav1_decode --help` for
95 options. Note: tools like [FFmpeg](https://ffmpeg.org) can be used to
96 convert other container formats to IVF.
97
98* Unit tests are built when `LIBGAV1_ENABLE_TESTS` is set to `1`. The binaries
99 can be invoked directly or with
100 [`ctest`](https://cmake.org/cmake/help/latest/manual/ctest.1.html).
101
102 * The test input location can be given by setting the
103 `LIBGAV1_TEST_DATA_PATH` environment variable; it defaults to
104 `<libgav1_src>/tests/data`, where `<libgav1_src>` is `/data/local/tmp`
105 on Android platforms or the source directory configured with cmake
106 otherwise.
107
108 * Output is written to the value of the `TMPDIR` or `TEMP` environment
109 variables in that order if set, otherwise `/data/local/tmp` on Android
110 platforms, the value of `LIBGAV1_FLAGS_TMPDIR` if defined during
111 compilation or the current directory if not.
112
113## Development
114
115### Contributing
116
117See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to submit patches.
118
119### Style
120
121libgav1 follows the
122[Google C++ style guide](https://google.github.io/styleguide/cppguide.html) with
123formatting enforced by `clang-format`.
124
125### Comments
126
127Comments of the form '`// X.Y(.Z).`', '`Section X.Y(.Z).`' or '`... in the
128spec`' reference the relevant section(s) in the
129[AV1 specification](http://aomediacodec.github.io/av1-spec/av1-spec.pdf).
130
131### DSP structure
132
133* `src/dsp/dsp.cc` defines the main entry point: `libgav1::dsp::DspInit()`.
134 This handles cpu-detection and initializing each logical unit which populate
135 `libgav1::dsp::Dsp` function tables.
136* `src/dsp/dsp.h` contains function and type definitions for all logical units
137 (e.g., intra-predictors)
138* `src/utils/cpu.h` contains definitions for cpu-detection
139* base implementations are located in `src/dsp/*.{h,cc}` with platform
140 specific optimizations in sub-folders
141* unit tests define `DISABLED_Speed` test(s) to allow timing of individual
142 functions
143
144#### Symbol reduction
145
146Based on the build configuration unneeded lesser optimizations are removed using
147a hierarchical include and define system. Each logical unit in `src/dsp` should
148include all platform specific headers in descending order to allow higher level
149optimizations to disable lower level ones. See `src/dsp/loop_filter.h` for an
150example.
151
152Each function receives a new define which can be checked in platform specific
153headers. The format is: `LIBGAV1_<Dsp-table>_FunctionName` or
154`LIBGAV1_<Dsp-table>_[sub-table-index1][...-indexN]`, e.g.,
155`LIBGAV1_Dsp8bpp_AverageBlend`,
156`LIBGAV1_Dsp8bpp_TransformSize4x4_IntraPredictorDc`. The Dsp-table name is of
157the form `Dsp<bitdepth>bpp` e.g. `Dsp10bpp` for bitdepth == 10 (bpp stands for
158bits per pixel). The indices correspond to enum values used as lookups with
159leading 'k' removed. Platform specific headers then should first check if the
160symbol is defined and if not set the value to the corresponding
161`LIBGAV1_CPU_<arch>` value from `src/utils/cpu.h`.
162
163```
164 #ifndef LIBGAV1_Dsp8bpp_TransformSize4x4_IntraPredictorDc
165 #define LIBGAV1_Dsp8bpp_TransformSize4x4_IntraPredictorDc LIBGAV1_CPU_SSE4_1
166 #endif
167```
168
169Within each module the code should check if the symbol is defined to its
170specific architecture or forced via `LIBGAV1_ENABLE_ALL_DSP_FUNCTIONS` before
171defining the function. The `DSP_ENABLED_(8|10)BPP_*` macros are available to
172simplify this check for optimized code.
173
174```
175 #if DSP_ENABLED_8BPP_SSE4_1(TransformSize4x4_IntraPredictorDc)
176 ...
177
178 // In unoptimized code use the following structure; there's no equivalent
179 // define for LIBGAV1_CPU_C as it would require duplicating the function
180 // defines used in optimized code for only a small benefit to this
181 // boilerplate.
182 #if LIBGAV1_ENABLE_ALL_DSP_FUNCTIONS
183 ...
184 #else // !LIBGAV1_ENABLE_ALL_DSP_FUNCTIONS
185 #ifndef LIBGAV1_Dsp8bpp_TransformSize4x4_IntraPredictorDcFill
186 ...
187```
188
189## Bugs
190
191Please report all bugs to the issue tracker:
192https://issuetracker.google.com/issues/new?component=750480&template=1355007
193
194## Discussion
195
196Email: gav1-devel@googlegroups.com
197
198Web: https://groups.google.com/forum/#!forum/gav1-devel
199