How arthenica/libaom works
Project type and purpose
• This is an open-source, cross-platform C/C++ library implementing the AV1 video codec, plus command-line applications (aomenc, aomdec), examples, tools, and tests.
• Key use cases: encode/decode AV1 streams, integrate with other media frameworks (e.g., libwebm, libyuv), cross-compile for various targets.
Top-level components
a. Build System (CMake)
• CMakeLists.txt & build/cmake/** – orchestrates configuration, toolchain selection, feature flags, cross-compile support, sanitizer support, build of library, apps, tests, docs.
b. Core Library (libaom)
• aom/ – public API headers, codec entry points, internal dispatch.
• av1/ – AV1-specific encoder and decoder implementations, each subdivided into:
– encoder/ (rate control, motion search, transforms, quantization, threading, syntax, output bitstream)
– decoder/ (parsing OBU, inverse transforms, loopfilter, synthesis, multithread)
– common/ (shared algorithms: transforms, loop-filters, entropy coding, frame buffers, SIMD dispatch)
• aom_dsp/, aom_scale/, aom_mem/, aom_ports/, aom_util/ – modular building blocks for DSP routines, image scaling, memory allocation, platform abstraction (CPU detection, aligned loads, endianness), threading and debug utilities.
c. Applications & Examples
• apps/ (aomenc, aomdec) – CLI front ends that link against libaom APIs to perform real-world encoding/decoding.
• examples/ – sample code illustrating how to invoke the API (e.g., simple encoder/decoder, two-pass, scalable decoding).
d. Third-Party Libraries
• third_party/googletest – unit-testing framework (gtest) used by test/
e. Test Infrastructure
• test/ – unit & integration tests organized by feature; scripts (.sh, CMake targets) to download test data and run shards via gtest.
f. Tools & Scripts
• tools/ – code-generation scripts (Perl, Python, JS), linters, OBU parsers, auto-refactoring utilities, commit-hooks.
g. Documentation
• doc/, usage*.dox, mainpage.dox – design docs, developer guides, algorithm descriptions.
Interactions & Data Flow
• Apps/examples → invoke public API in aom/, av1/ → internally call into DSP, scale, mem, ports, util modules → perform encode/decode pipelines → output bitstream or raw frames.
• CMake build system reads CMakeLists.txt, includes toolchain files (build/cmake/toolchains) → compiles modules into static/shared libs → links apps, tests.
• Tests link against built libaom + googletest → load test data (downloaded via testdata target) → exercise API → report pass/fail.
• Third-party code is included via source trees, compiled alongside core modules under unified build.
Architectural patterns & design principles
• Layered design: public API layer (aom/), codec algorithm layer (av1/), low-level DSP/port abstraction, platform-specific SIMD backends.
• SIMD dispatch and code-generation: run-time CPU detection (aom_ports) + compile-time dispatch (rtcd) for optimized kernels in aom_dsp, av1/common.
• Plugin-like toolchain files: CMake toolchain architecture supports cross-compiling by injecting target-specific flags.
• Test-driven: gtest integration, automated testdata download, sharded test runs.
• Clear labels for components (e.g., “av1/encoder”, “aom_dsp”, “build/cmake”).