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