mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-20 16:47:28 +01:00
Put the q10/q11 variable region before the ring buffer (now the last region), growing it (and moving the ring buffer) at the first transform_io call to use a workbuf longer than workbuf_len's minimum. Large window now also works at qualities 10 and 11.
47 lines
2.0 KiB
Markdown
47 lines
2.0 KiB
Markdown
# Compression Encoders
|
|
|
|
Compression encoders read from one input stream (an `io_reader` called `src`)
|
|
and write to an output stream (an `io_writer` called `dst`). Like
|
|
[compression decoders](/doc/std/compression-decoders.md), they implement the
|
|
`base.io_transformer` interface, whose key method is `transform_io`. It
|
|
incrementally compresses the source data.
|
|
|
|
This method is a [coroutine](/doc/note/coroutines.md), and does not require
|
|
either all of the input or all of the output to fit in a single contiguous
|
|
buffer. It suspends with the `$short_read` status when it has consumed all of
|
|
`src` (and `src` is not closed) and with `$short_write` when `dst` is full. It
|
|
returns ok once `src` is closed and all of the compressed data has been
|
|
written. Encoder parameters (e.g. the compression quality) are set with
|
|
`set_quirk` before the first `transform_io` call.
|
|
|
|
|
|
## API Listing
|
|
|
|
In Wuffs syntax, the `base.io_transformer` methods are:
|
|
|
|
- `dst_history_retain_length() u64`
|
|
- `get_quirk(key: u32) u64`
|
|
- `set_quirk!(key: u32, value: u64) status`
|
|
- `transform_io?(dst: io_writer, src: io_reader, workbuf: slice u8)`
|
|
- `workbuf_len() range_ii_u64`
|
|
|
|
A workbuf of `workbuf_len().max_incl` bytes always suffices. Some encoders
|
|
(e.g. brotli at qualities 10 and 11) have a smaller `min_incl`, which is
|
|
enough for realistic inputs: with a workbuf shorter than `max_incl`, an
|
|
unusual input can make `transform_io` return `"#bad workbuf length"`.
|
|
|
|
Encoders may have further, format-specific methods. For example, the brotli
|
|
encoder has `request_flush`, `request_emit_metadata` and
|
|
`max_compressed_size`.
|
|
|
|
|
|
## Implementations
|
|
|
|
- [std/brotli](/std/brotli/README.md#encoder) (qualities 0 to 11, without
|
|
encoder dictionaries, including large-window brotli, with windows of up to
|
|
1 GiB, at qualities 3 to 11). Its `workbuf_len` is the worst case for the
|
|
parameters (more than 2 GiB for large-window brotli at lgwin 30; at
|
|
qualities 10 and 11, `min_incl` is a smaller practical bound), but a
|
|
shorter workbuf works for short inputs: see the README's "Encoder Workbuf
|
|
Layout" section.
|