libgav1 -- an AV1 decoder

Clone this repo:

Branches

Tags

  1. b48796f libgav1,GetErrorString(): add missing LIBGAV1_PUBLIC by James Zern · 8 hours ago master
  2. 889a249 README.md: add av1 profile names for clarity by James Zern · 3 days ago
  3. 0e7e85d README.md: add bug reporting & m/l info by James Zern · 9 days ago
  4. 16b3088 Add vreinterpret casts to fix -flax-vector-conversions warnings by Wan-Teh Chang · 10 days ago
  5. 2db0515 libgav1,mask_blend_neon: fix lax vector conv in GetMask4x2 by James Zern · 12 days ago

libgav1 -- an AV1 decoder

libgav1 is a Main profile (0) & High profile (1) compliant AV1 decoder. More information on the AV1 video format can be found at aomedia.org.

Building

Prerequisites

  1. A C++11 compiler. gcc 6+, clang 7+ or Microsoft Visual Studio 2017+ are recommended.

  2. CMake >= 3.7.1

  3. Abseil

    From within the libgav1 directory:

      $ git clone https://github.com/abseil/abseil-cpp.git third_party/abseil-cpp
    

Compile

  $ mkdir build && cd build
  $ cmake -G "Unix Makefiles" ..
  $ make

Configuration options:

  • LIBGAV1_MAX_BITDEPTH: defines the maximum supported bitdepth (8, 10; default: 10).
  • 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_NEON: define to a non-zero value to enable NEON optimizations. Automatically defined in src/dsp/dsp.h if unset.
  • LIBGAV1_ENABLE_SSE4_1: define to a non-zero value to enable sse4.1 optimizations. Automatically defined in src/dsp/dsp.h if unset.
  • LIBGAV1_ENABLE_LOGGING: define to 0/1 to control debug logging. Automatically defined in src/utils/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.

For additional options see:

  $ cmake .. -LH

Testing

  • 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.

Development

Contributing

See CONTRIBUTING.md for details on how to submit patches.

Style

libgav1 follows the Google C++ style guide with formatting enforced by clang-format.

Comments

Comments of the form ‘// X.Y(.Z).’, ‘Section X.Y(.Z).’ or ‘... in the spec’ reference the relevant section(s) in the AV1 specification.

DSP structure

  • 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-detection
  • base implementations are located in src/dsp/*.{h,cc} with platform specific optimizations in sub-folders
  • unit tests define DISABLED_Speed test(s) to allow timing of individual functions

Symbol reduction

Based 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>_[sub-table-index1][...-indexN], e.g., 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
  ...

Bugs

Please report all bugs to the issue tracker: https://issuetracker.google.com/issues/new?component=750480&template=1355007

Discussion

Email: gav1-devel@googlegroups.com

Web: https://groups.google.com/forum/#!forum/gav1-devel