summaryrefslogtreecommitdiffstats
path: root/third_party/dav1d/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/dav1d/README.md')
-rw-r--r--third_party/dav1d/README.md158
1 files changed, 158 insertions, 0 deletions
diff --git a/third_party/dav1d/README.md b/third_party/dav1d/README.md
new file mode 100644
index 0000000000..580382eeea
--- /dev/null
+++ b/third_party/dav1d/README.md
@@ -0,0 +1,158 @@
+![dav1d logo](doc/dav1d_logo.png)
+
+# dav1d
+
+**dav1d** is an **AV1** cross-platform **d**ecoder, open-source, and focused on speed and correctness.
+
+It is now battle-tested and production-ready and can be used everywhere.
+
+The canonical repository URL for this repo is https://code.videolan.org/videolan/dav1d
+
+This project was partially funded by the *Alliance for Open Media*/**AOM**.
+
+## Goal and Features
+
+The goal of this project is to provide a decoder for **most platforms**, and achieve the **highest speed** possible to overcome the temporary lack of AV1 hardware decoder.
+
+It supports all features from AV1, including all subsampling and bit-depth parameters.
+
+In the future, this project will host simple tools or simple wrappings *(like, for example, an MFT transform)*.
+
+## License
+
+**dav1d** is released under a very liberal license, a contrario from the other VideoLAN projects, so that it can be embedded anywhere, including non-open-source software; or even drivers, to allow the creation of hybrid decoders.
+
+The reasoning behind this decision is the same as for libvorbis, see [RMS on vorbis](https://lwn.net/2001/0301/a/rms-ov-license.php3).
+
+# Roadmap
+
+The plan is the following:
+
+### Reached
+1. Complete C implementation of the decoder,
+2. Provide a usable API,
+3. Port to most platforms,
+4. Make it fast on desktop, by writing asm for AVX2 chips.
+5. Make it fast on mobile, by writing asm for ARMv8 chips,
+6. Make it fast on older desktop, by writing asm for SSSE3+ chips,
+7. Make high bit-depth fast on mobile, by writing asm for ARMv8 chips.
+8. Make it fast on older mobile, by writing asm for ARMv7 chips,
+9. Make high bit-depth fast on older mobile, by writing asm for ARMv7 chips,
+10. Make high bit-depth fast on desktop, by writing asm for AVX2 chips,
+11. Make high bit-depth fast on older desktop, by writing asm for SSSE3+ chips,
+12. Improve threading.
+
+### On-going
+13. Improve C code base with [various tweaks](https://code.videolan.org/videolan/dav1d/wikis/task-list),
+14. Accelerate for less common architectures, like PPC, SSE2, RISC-V or AVX-512.
+
+### After
+15. Use more GPU decoding, when possible.
+
+# Contribute
+
+Currently, we are looking for help from:
+- C developers,
+- asm developers,
+- platform-specific developers,
+- GPGPU developers,
+- testers.
+
+Our contributions guidelines are quite strict. We want to build a coherent codebase to simplify maintenance and achieve the highest possible speed.
+
+Notably, the codebase is in pure C and asm.
+
+We are on IRC, on the **#dav1d** channel on [*Libera.chat*](http://libera.chat/). If you do not have an IRC Client at hand, use [IRC Web Interface](https://web.libera.chat/#dav1d).
+
+See the [contributions document](CONTRIBUTING.md).
+
+## CLA
+
+There is no CLA.
+
+People will keep their copyright and their authorship rights, while adhering to the BSD 2-clause license.
+
+VideoLAN will only have the collective work rights.
+
+## CoC
+
+The [VideoLAN Code of Conduct](https://wiki.videolan.org/CoC) applies to this project.
+
+# Compile
+
+1. Install [Meson](https://mesonbuild.com/) (0.49 or higher), [Ninja](https://ninja-build.org/), and, for x86\* targets, [nasm](https://nasm.us/) (2.14 or higher)
+2. Run `mkdir build && cd build` to create a build directory and enter it
+3. Run `meson setup ..` to configure meson, add `--default-library=static` if static linking is desired
+4. Run `ninja` to compile
+
+## Cross-Compilation for 32- or 64-bit Windows, 32-bit Linux
+
+If you're on a linux build machine trying to compile .exe for a Windows target/host machine, run
+
+```
+meson setup build --cross-file=package/crossfiles/x86_64-w64-mingw32.meson
+```
+
+or, for 32-bit:
+
+```
+meson setup build --cross-file=package/crossfiles/i686-w64-mingw32.meson
+```
+
+`mingw-w64` is a pre-requisite and should be installed on your linux machine via your preferred method or package manager. Note the binary name formats may differ between distributions. Verify the names, and use `alias` if certain binaries cannot be found.
+
+For 32-bit linux, run
+
+```
+meson setup build --cross-file=package/crossfiles/i686-linux32.meson
+```
+
+## Build documentation
+
+1. Install [doxygen](https://www.doxygen.nl/) and [graphviz](https://www.graphviz.org/)
+2. Run `meson setup build -Denable_docs=true` to create the build directory
+3. Run `ninja -C build doc/html` to build the docs
+
+The result can be found in `build/doc/html/`. An online version built from master can be found [here](https://videolan.videolan.me/dav1d/).
+
+# Run tests
+
+1. In the root directory, run `git clone https://code.videolan.org/videolan/dav1d-test-data.git tests/dav1d-test-data` to fetch the test data repository
+2. During meson configuration, specify `-Dtestdata_tests=true`
+3. Run `meson test -v` after compiling
+
+# Support
+
+This project is partially funded by the *Alliance for Open Media*/**AOM** and is supported by TwoOrioles and VideoLabs.
+
+These companies can provide support and integration help, should you need it.
+
+
+# FAQ
+
+## Why do you not improve libaom rather than starting a new project?
+
+- We believe that libaom is a very good library. It was however developed for research purposes during AV1 design.
+We think that an implementation written from scratch can achieve faster decoding, in the same way that *ffvp9* was faster than *libvpx*.
+
+## Is dav1d a recursive acronym?
+
+- Yes.
+
+## Can I help?
+
+- Yes. See the [contributions document](CONTRIBUTING.md).
+
+## I am not a developer. Can I help?
+
+- Yes. We need testers, bug reporters and documentation writers.
+
+## What about the AV1 patent license?
+
+- This project is an implementation of a decoder. It gives you no special rights on the AV1 patents.
+
+Please read the [AV1 patent license](doc/PATENTS) that applies to the AV1 specification and codec.
+
+## Will you care about <my_arch>? <my_os>?
+
+- We do, but we don't have either the time or the knowledge. Therefore, patches and contributions welcome.