libgav1 is a Main profile (0), High profile (1) & Professional profile (2) compliant AV1 decoder. More information on the AV1 video format can be found at aomedia.org.
A C++11 compiler. gcc 6+, clang 7+ or Microsoft Visual Studio 2017+ are recommended.
From within the libgav1 directory:
$ git clone -b 20220623.0 --depth 1 \ https://github.com/abseil/abseil-cpp.git third_party/abseil-cpp
Note: Abseil is required by the examples and tests. libgav1 will depend on it if LIBGAV1_THREADPOOL_USE_STD_MUTEX is set to 0 (see below).
(Optional) GoogleTest
From within the libgav1 directory:
$ git clone -b release-1.12.1 --depth 1 \ https://github.com/google/googletest.git third_party/googletest
$ mkdir build && cd build $ cmake -G "Unix Makefiles" .. $ make
Configuration options:
LIBGAV1_MAX_BITDEPTH: defines the maximum supported bitdepth (8, 10, 12; default: 12).LIBGAV1_ENABLE_ALL_DSP_FUNCTIONS: define to a non-zero value to disable symbol reduction in an optimized build to keep all versions of dsp functions available. Automatically defined in src/dsp/dsp.h if unset.LIBGAV1_ENABLE_AVX2: define to a non-zero value to enable avx2 optimizations. Automatically defined in src/utils/cpu.h if unset.LIBGAV1_ENABLE_NEON: define to a non-zero value to enable NEON optimizations. Automatically defined in src/utils/cpu.h if unset.LIBGAV1_ENABLE_SSE4_1: define to a non-zero value to enable sse4.1 optimizations. Automatically defined in src/utils/cpu.h if unset. Note setting this to 0 will also disable AVX2.LIBGAV1_ENABLE_LOGGING: define to 0/1 to control debug logging. Automatically defined in src/utils/logging.h if unset.LIBGAV1_EXAMPLES_ENABLE_LOGGING: define to 0/1 to control error logging in the examples. Automatically defined in examples/logging.h if unset.LIBGAV1_ENABLE_TRANSFORM_RANGE_CHECK: define to 1 to enable transform coefficient range checks.LIBGAV1_LOG_LEVEL: controls the maximum allowed log level, see enum LogSeverity in src/utils/logging.h. Automatically defined in src/utils/logging.cc if unset.LIBGAV1_THREADPOOL_USE_STD_MUTEX: controls use of std::mutex and absl::Mutex in ThreadPool. Defining this to 1 will remove any Abseil dependency from the core library. Automatically defined in src/utils/threadpool.h if unset. Defaults to 1 on Android & iOS, 0 otherwise.LIBGAV1_MAX_THREADS: sets the number of threads that the library is allowed to create. Has to be an integer > 0. Otherwise this is ignored. The default value is 128.LIBGAV1_FRAME_PARALLEL_THRESHOLD_MULTIPLIER: the threshold multiplier that is used to determine when to use frame parallel decoding. Frame parallel decoding will be used if |threads| > |tile_count| * this multiplier. Has to be an integer > 0. The default value is 4. This is an advanced setting intended for testing purposes.CHROMIUM: apply Chromium-specific changes if set.For additional options see:
$ cmake .. -LH
gav1_decode can be used to decode IVF files, see gav1_decode --help for options. Note: tools like FFmpeg can be used to convert other container formats to IVF.
Unit tests are built when LIBGAV1_ENABLE_TESTS is set to 1. The binaries can be invoked directly or with ctest.
The test input location can be given by setting the LIBGAV1_TEST_DATA_PATH environment variable; it defaults to <libgav1_src>/tests/data, where <libgav1_src> is /data/local/tmp on Android platforms or the source directory configured with cmake otherwise.
Output is written to the value of the TMPDIR or TEMP environment variables in that order if set, otherwise /data/local/tmp on Android platforms, the value of LIBGAV1_FLAGS_TMPDIR if defined during compilation or the current directory if not.
See CONTRIBUTING.md for details on how to submit patches.
libgav1 follows the Google C++ style guide with formatting enforced by clang-format.
Comments of the form ‘// X.Y(.Z).’, ‘Section X.Y(.Z).’ or ‘... in the spec’ reference the relevant section(s) in the AV1 specification.
src/dsp/dsp.cc defines the main entry point: libgav1::dsp::DspInit(). This handles cpu-detection and initializing each logical unit which populate libgav1::dsp::Dsp function tables.src/dsp/dsp.h contains function and type definitions for all logical units (e.g., intra-predictors)src/utils/cpu.h contains definitions for cpu-detectionsrc/dsp/*.{h,cc} with platform specific optimizations in sub-foldersDISABLED_Speed test(s) to allow timing of individual functionsBased on the build configuration unneeded lesser optimizations are removed using a hierarchical include and define system. Each logical unit in src/dsp should include all platform specific headers in descending order to allow higher level optimizations to disable lower level ones. See src/dsp/loop_filter.h for an example.
Each function receives a new define which can be checked in platform specific headers. The format is: LIBGAV1_<Dsp-table>_FunctionName or LIBGAV1_<Dsp-table>_[sub-table-index1][...-indexN], e.g., LIBGAV1_Dsp8bpp_AverageBlend, LIBGAV1_Dsp8bpp_TransformSize4x4_IntraPredictorDc. The Dsp-table name is of the form Dsp<bitdepth>bpp e.g. Dsp10bpp for bitdepth == 10 (bpp stands for bits per pixel). The indices correspond to enum values used as lookups with leading ‘k’ removed. Platform specific headers then should first check if the symbol is defined and if not set the value to the corresponding LIBGAV1_CPU_<arch> value from src/utils/cpu.h.
#ifndef LIBGAV1_Dsp8bpp_TransformSize4x4_IntraPredictorDc #define LIBGAV1_Dsp8bpp_TransformSize4x4_IntraPredictorDc LIBGAV1_CPU_SSE4_1 #endif
Within each module the code should check if the symbol is defined to its specific architecture or forced via LIBGAV1_ENABLE_ALL_DSP_FUNCTIONS before defining the function. The DSP_ENABLED_(8|10)BPP_* macros are available to simplify this check for optimized code.
#if DSP_ENABLED_8BPP_SSE4_1(TransformSize4x4_IntraPredictorDc) ... // In unoptimized code use the following structure; there's no equivalent // define for LIBGAV1_CPU_C as it would require duplicating the function // defines used in optimized code for only a small benefit to this // boilerplate. #if LIBGAV1_ENABLE_ALL_DSP_FUNCTIONS ... #else // !LIBGAV1_ENABLE_ALL_DSP_FUNCTIONS #ifndef LIBGAV1_Dsp8bpp_TransformSize4x4_IntraPredictorDcFill ...
Please report all bugs to the issue tracker: https://issuetracker.google.com/issues/new?component=750480&template=1355007
Email: gav1-devel@googlegroups.com