Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-webp

Source of release 0.1.0

0.1.0 / README.md

# luce-webp

A WebP decoder for Luce/Base: a faithful port of libwebp 1.6.0's decoder (the version
Ladybird links), lossy, lossless, alpha and animation, giving libwebp's pixels bit for bit.
It depends on no other package: only the compiler's built-in modules. The browser engine
decodes WebP images through it.

```luce
from luce_webp import webp

let found = try webp.info(data)                # canvas, alpha, frames, loop count
let pixels = try new u8[found.width * found.height * 4] ---
try webp.decode_rgba8(data, pixels)            # straight RGBA, as WebPDecodeRGBAInto

var animation = try webp.Animation.open(data)  # `data` must outlive it
defer animation.release()
for (index, frame) in animation.frames().indexed():
    try animation.render(index, pixels)        # frame `index`, composited as WebPAnimDecoder does
    show(pixels, frame.duration)               # milliseconds, as written

if let profile = try webp.icc_profile(data):   # the ICCP chunk, as WebPMux reads it
    use(profile)                               # luce-color makes a color space of it
```

## API

- `features(data) -> Info!` (WebPGetFeatures): `width` and `height` of the canvas, `alpha`
  (the VP8X alpha flag, an ALPH chunk, or the VP8L header's alpha bit), `animated` (the VP8X
  animation flag), `format` (`lossy`, `lossless`, or `mixed` for an animation).
- `info(data) -> Info!`: the same, and for an animation `frame_count`, `loop_count` (0
  forever) and `background` (the ANIM chunk's color as written) from the demuxer; `plays()`
  is how many times it plays (0 forever, 1 for a still picture).
- `decode_rgba8(data, out, options)`: a still picture into `out` of at least
  `width * height * 4` bytes; an animation's first frame. libwebp's defaults, which Ladybird
  uses: fancy upsampling, no dithering. Alpha is straight; a picture whose `alpha` is false
  is still decoded with whatever alpha it stores (Ladybird draws such a picture opaque).
- `Animation.open(data, options) -> Animation!` (WebPAnimDecoderNew), then `frames()` and
  `render(index, out)` (WebPAnimDecoderGetNext): each `Frame` has its rectangle (`left`,
  `top`, `width`, `height`), `duration` (milliseconds as written), `disposal` (`keep`,
  `background`), `blend` and `alpha`. Frames render fastest in order; an earlier index starts
  again from the first. `release` frees the frame list and the two canvases. A still picture
  is an animation of one frame.
- `icc_profile(data) -> const u8[]?!`: the ICCP chunk's payload when the VP8X flags
  announce one; it fails where WebPMuxCreate refuses the file (inconsistent flags and
  chunks), which makes a browser refuse the image.
- `Options.max_pixels` (default 2^28) bounds the canvas.
- Errors: `corrupt` (not a WebP, damaged, or ending early), `limit`, `invalid` (an output
  buffer too small, a frame index past the last), `unsupported` (a VP8 frame that is not a
  shown key frame, an animation where a still picture is decoded).

## What is ported

From libwebp 1.6.0 (`src/dec`, `src/dsp`, `src/utils`, `src/demux`, `src/mux`): the RIFF
container and its header checks (`webp_dec.c`); VP8's boolean decoder, headers, segments,
quantizers, probabilities, intra modes and residuals, intra prediction, the inverse DCT and
WHT, the simple and complex loop filters (`vp8_dec.c`, `tree_dec.c`, `quant_dec.c`,
`frame_dec.c`, `dsp/dec.c`); the RGBA output with the fancy upsampler and alpha
(`io_dec.c`, `dsp/upsampling.c`, `dsp/yuv.h`); the ALPH chunk, raw or lossless, with its
filters (`alpha_dec.c`, `dsp/filters.c`); VP8L's bit reader, Huffman tables and groups (with
packed tables), color cache, LZ77 with 2D distances, the four transforms and byte-per-pixel
alpha (`vp8l_dec.c`, `huffman_utils.c`, `dsp/lossless.c`); the demuxer and WebPAnimDecoder
(`demux.c`, `anim_decode.c`); WebPMux's reading and validation (`muxread.c`,
`muxinternal.c`) for the ICC profile.

Left out, as Ladybird never asks for them: incremental decoding (`idec_dec.c`), cropping
and scaling (`rescaler`), YUV and premultiplied output modes, dithering (`random_utils`,
`quant_levels_dec_utils`; off by default), threads (which do not change the output), and
the encoder. EXIF and XMP chunks are skipped. libwebp decodes an ALPH chunk a few rows ahead
of the color rows; this decodes the plane at the first request, which gives the same plane
and fails where libwebp fails.

## Agreement with libwebp

`tests/run.py` compares every frame of tests/fixtures (Ladybird's 23 WebP test inputs and 83
files made with libwebp 1.6.0's cwebp, img2webp, gif2webp and webpmux, damaged ones among
them) with libwebp's output, through the C oracle in luce-browser-tools
(`oracles/luce-webp`): features, durations and an FNV-1a hash of every frame, in native, C
and diagnostic builds. Locally, the same holds on larger sets:

| Set | Files | Identical to libwebp's C build |
| --- | ---: | ---: |
| Ladybird's test inputs | 23 | 23 |
| cwebp/img2webp/gif2webp/webpmux corpus (`gen_corpus.py`) | 544 | 544 |
| Other WebP files on hand (Ladybird's other tests and UI, Krita, libvips, OIIO, resvg) | 66 | 66 |
| Mutations of the above (bytes changed, bits flipped, cut, inserted) | 4,000 | 4,000 |

The reference is libwebp's portable C code. Its NEON build (as Ladybird ships it on arm64)
agrees with it on every valid file; on 2 of the damaged files in the corpus, whose
coefficients leave the range VP8 encoders produce, NEON's saturating inverse transform gives
other pixels.

## Speed

On a 1024x772 picture (Apple M-series, native build), against libwebp built without SIMD:

| Picture | libwebp (C) | luce-webp |
| --- | ---: | ---: |
| lossy (Ladybird's 4.webp) | 9.5 ms | 17.6 ms |
| lossy with lossless alpha | 11.8 ms | 22.8 ms |
| lossless | 12.6 ms | 21.7 ms |

## Tests

```
./test.sh                                   # every compiler named: -W, fmt, tests, fixtures
LUCE_BASE_EXTRA=~/.local/bin/luce-base ./test.sh
python3 tests/run.py --expected ORACLE      # expected.txt again, from libwebp
```

## Licenses

luce-webp is MIT or Apache-2.0 (LICENSE-MIT, LICENSE-APACHE). It is a port of libwebp,
Copyright (c) 2010, Google Inc., BSD-3-Clause, with Google's patent grant (LICENSE-libwebp).
The fixtures under tests/fixtures/ladybird are Ladybird's (BSD-2-Clause, their LICENSE);
4.webp and 4-with-8-partitions.webp are a Wikimedia Commons photograph ("Frühling blühender
Kirschenbaum") under CC BY-SA 3.0, re-encoded by Google's WebP gallery.