third_party/dav1d/README.md

   1 ![dav1d logo](doc/dav1d_logo.png)
   2
   3 # dav1d
   4
   5 **dav1d** is an **AV1** cross-platform **d**ecoder, open-source, and focused on speed and correctness.
   6
   7 It is now battle-tested and production-ready and can be used everywhere.
   8
   9 The canonical repository URL for this repo is https://code.videolan.org/videolan/dav1d
  10
  11 This project was partially funded by the *Alliance for Open Media*/**AOM**.
  12
  13 ## Goal and Features
  14
  15 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.
  16
  17 It supports all features from AV1, including all subsampling and bit-depth parameters.
  18
  19 In the future, this project will host simple tools or simple wrappings *(like, for example, an MFT transform)*.
  20
  21 ## License
  22
  23 **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.
  24
  25 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).
  26
  27 # Roadmap
  28
  29 The plan is the following:
  30
  31 ### Reached
  32 1. Complete C implementation of the decoder,
  33 2. Provide a usable API,
  34 3. Port to most platforms,
  35 4. Make it fast on desktop, by writing asm for AVX2 chips.
  36 5. Make it fast on mobile, by writing asm for ARMv8 chips,
  37 6. Make it fast on older desktop, by writing asm for SSSE3+ chips,
  38 7. Make high bit-depth fast on mobile, by writing asm for ARMv8 chips.
  39 8. Make it fast on older mobile, by writing asm for ARMv7 chips,
  40 9. Make high bit-depth fast on older mobile, by writing asm for ARMv7 chips,
  41 10. Make high bit-depth fast on desktop, by writing asm for AVX2 chips,
  42 11. Make high bit-depth fast on older desktop, by writing asm for SSSE3+ chips,
  43 12. Improve threading.
  44
  45 ### On-going
  46 13. Improve C code base with [various tweaks](https://code.videolan.org/videolan/dav1d/wikis/task-list),
  47 14. Accelerate for less common architectures, like PPC, SSE2, RISC-V or AVX-512.
  48
  49 ### After
  50 15. Use more GPU decoding, when possible.
  51
  52 # Contribute
  53
  54 Currently, we are looking for help from:
  55 - C developers,
  56 - asm developers,
  57 - platform-specific developers,
  58 - GPGPU developers,
  59 - testers.
  60
  61 Our contributions guidelines are quite strict. We want to build a coherent codebase to simplify maintenance and achieve the highest possible speed.
  62
  63 Notably, the codebase is in pure C and asm.
  64
  65 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).
  66
  67 See the [contributions document](CONTRIBUTING.md).
  68
  69 ## CLA
  70
  71 There is no CLA.
  72
  73 People will keep their copyright and their authorship rights, while adhering to the BSD 2-clause license.
  74
  75 VideoLAN will only have the collective work rights.
  76
  77 ## CoC
  78
  79 The [VideoLAN Code of Conduct](https://wiki.videolan.org/CoC) applies to this project.
  80
  81 # Compile
  82
  83 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)
  84 2. Run `mkdir build && cd build` to create a build directory and enter it
  85 3. Run `meson setup ..` to configure meson, add `--default-library=static` if static linking is desired
  86 4. Run `ninja` to compile
  87
  88 ## Cross-Compilation for 32- or 64-bit Windows, 32-bit Linux
  89
  90 If you're on a linux build machine trying to compile .exe for a Windows target/host machine, run
  91
  92 ```
  93 meson setup build --cross-file=package/crossfiles/x86_64-w64-mingw32.meson
  94 ```
  95
  96 or, for 32-bit:
  97
  98 ```
  99 meson setup build --cross-file=package/crossfiles/i686-w64-mingw32.meson
 100 ```
 101
 102 `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.
 103
 104 For 32-bit linux, run
 105
 106 ```
 107 meson setup build --cross-file=package/crossfiles/i686-linux32.meson
 108 ```
 109
 110 ## Build documentation
 111
 112 1. Install [doxygen](https://www.doxygen.nl/) and [graphviz](https://www.graphviz.org/)
 113 2. Run `meson setup build -Denable_docs=true` to create the build directory
 114 3. Run `ninja -C build doc/html` to build the docs
 115
 116 The result can be found in `build/doc/html/`. An online version built from master can be found [here](https://videolan.videolan.me/dav1d/).
 117
 118 # Run tests
 119
 120 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
 121 2. During meson configuration, specify `-Dtestdata_tests=true`
 122 3. Run `meson test -v` after compiling
 123
 124 # Support
 125
 126 This project is partially funded by the *Alliance for Open Media*/**AOM** and is supported by TwoOrioles and VideoLabs.
 127
 128 These companies can provide support and integration help, should you need it.
 129
 130
 131 # FAQ
 132
 133 ## Why do you not improve libaom rather than starting a new project?
 134
 135 - We believe that libaom is a very good library. It was however developed for research purposes during AV1 design.
 136 We think that an implementation written from scratch can achieve faster decoding, in the same way that *ffvp9* was faster than *libvpx*.
 137
 138 ## Is dav1d a recursive acronym?
 139
 140 - Yes.
 141
 142 ## Can I help?
 143
 144 - Yes. See the [contributions document](CONTRIBUTING.md).
 145
 146 ## I am not a developer. Can I help?
 147
 148 - Yes. We need testers, bug reporters and documentation writers.
 149
 150 ## What about the AV1 patent license?
 151
 152 - This project is an implementation of a decoder. It gives you no special rights on the AV1 patents.
 153
 154 Please read the [AV1 patent license](doc/PATENTS) that applies to the AV1 specification and codec.
 155
 156 ## Will you care about <my_arch>? <my_os>?
 157
 158 - We do, but we don't have either the time or the knowledge. Therefore, patches and contributions welcome.