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