| // Copyright 2024 The Wuffs Authors. |
| // |
| // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or |
| // https://www.apache.org/licenses/LICENSE-2.0> or the MIT license |
| // <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your |
| // option. This file may not be copied, modified, or distributed |
| // except according to those terms. |
| // |
| // SPDX-License-Identifier: Apache-2.0 OR MIT |
| |
| // -------- |
| |
| // Quirks are discussed in (/doc/note/quirks.md). |
| // |
| // The base38 encoding of "jpeg" is 0x122FF6. Left shifting by 10 gives |
| // 0x48BF_D800. |
| pri const QUIRKS_BASE : base.u32 = 0x48BF_D800 |
| |
| // -------- |
| |
| // When this quirk value is non-zero, the decoder will not support progressive |
| // JPEG images. When combined with setting base.QUIRK_QUALITY to "lower |
| // quality", this means that decoding will never require any temporary "work |
| // buffer" memory: decoder.workbuf_len will always return a range (a min and |
| // max pair) whose minimum value is zero. |
| // |
| // The maximum value can still be positive, as using more memory might lead to |
| // faster decoding, but a zero minimum means that it's valid for the caller to |
| // not allocate any memory for a work buffer. |
| // |
| // When opted into lower quality decoding, the workbuf_len minimum will be zero |
| // and positive for sequential and progressive JPEGs respectively, regardless |
| // of this QUIRK_REJECT_PROGRESSIVE_JPEGS key's value. But setting this quirk |
| // explicitly will produce a "#rejected progressive JPEG" error when |
| // encountering a progressive JPEG. This results in more readable calling code, |
| // instead of commenting about "positive work buffer minimum length implies a |
| // progressive JPEG". |
| pub const QUIRK_REJECT_PROGRESSIVE_JPEGS : base.u32 = 0x48BF_D800 | 0x00 |
| |
| // -------- |
| |
| // The base.QUIRK_QUALITY key is defined in the base package, not this package. |
| // Still, here's some documentation on how this package responds to that (key, |
| // value) quirk pair. |
| // |
| // If decoder.set_quirk is passed a base.QUIRK_QUALITY as the key argument |
| // then, when re-interpreting the u64 value argument as a signed i64 number, a |
| // negative number opts the decoder in to a slightly worse quality but leaner |
| // (less memory required) chroma upsampling algorithm. |
| // |
| // Negative (in i64 space) means >= 0x8000_0000_0000_0000 (in u64 space). |
| // base.QUIRK_QUALITY__VALUE__LOWER_QUALITY is one such value. |
| // |
| // Specifically, a negative quirk value uses a box filter. A non-negative quirk |
| // value (including the default value, zero) uses the same triangle filter that |
| // libjpeg-turbo also uses by default, which requires chroma upsampling on the |
| // edges of a MCU (Minimum Coded Unit) to remember adjacent MCU's values. |
| // |
| // Leaner means that for common (sequential) JPEG images, the range returned by |
| // decoder.workbuf_len will have a minimum value of zero, meaning that no work |
| // buffer memory needs to be allocated. Decoding rarer (progressive) JPEGs will |
| // still always require a positive amount of work buffer memory, for reasons |
| // unrelated to chroma upsampling. The exact amount required depends on factors |
| // like the JPEG image's width, height, component count and subsampling ratios. |
| // |
| // Regardless of the quirk value, as always, the workbuf_len method returns a |
| // range, whose min and max can be different. The caller is able to choose |
| // between providing the minimal amount of work buffer memory (for slightly |
| // slower decoding) or the maximal amount (for slightly faster decoding). |
| // |
| // Callers that never wish to allocate work buffer memory can simply reject |
| // progressive JPEGs (where "workbuf_len().min_incl > 0" despite setting the |
| // base.QUIRK_QUALITY key to a negative quirk value) as unsupported. See also |
| // QUIRK_REJECT_PROGRESSIVE_JPEGS. |
| // |
| // For some pictures comparing box and triangle filter decodings, see |
| // https://nigeltao.github.io/blog/2024/jpeg-chroma-upsampling.html |