diff --git a/doc/note/quirks.md b/doc/note/quirks.md new file mode 100644 index 00000000..f919da3f --- /dev/null +++ b/doc/note/quirks.md @@ -0,0 +1,34 @@ +# Quirks + +Quirks are configuration options that let Wuffs more closely match other codec +implementations. + +Some codecs and file formats are more tightly specified than others. When a +spec doesn't fully dictate how to treat malformed files, different codec +implementations have disagreed on whether to accept it (e.g. whether they +follow Postel's Principle of "be liberal in what you accept") and if so, how to +interpret it. Some implementations also raise those decisions to the +application level, not the library level: "provide mechanism, not policy". + +For example, in an animated GIF image, the first frame might not fill out the +entire image, and different implementations choose a different default color +for the outside pixels: opaque black, transparent black, or something else. + +Wuffs, out of the box, makes particular choices (typically mimicking the de +facto canonical implementation), but enabling various quirks result in +different choices. In particular, quirks are useful in regression testing that +Wuffs and another implementation produce the same output for the same input, +even for malformed input. + + +## Wuffs API + +Each quirk is assigned a `uint32_t` value, packed using the [base38 namespace +convention](/doc/note/base38-and-fourcc.md). Decoders and encoders can have a +`set_quirk_enabled!(quirk base.u32, enabled base.bool)` method whose first +argument is this `uint32_t` value. + +For example, the base38 encoding of `"gif "` is `0xF8586`, so that the +GIF-specific quirks have a `uint32_t` value of `((0xF8586 << 10) | n)`, for +some small integer `n`. The generated `C` language file defines human-readable +names for those constant values. diff --git a/std/gif/decode_gif.wuffs b/std/gif/decode_gif.wuffs index 252071fd..b96ccee8 100644 --- a/std/gif/decode_gif.wuffs +++ b/std/gif/decode_gif.wuffs @@ -31,30 +31,7 @@ pub const decoder_workbuf_len_max_incl_worst_case base.u64 = 1 // -------- -// Quirks are configuration options that let Wuffs more closely match other -// codec implementations. -// -// Some codecs and file formats are more tightly specified than others. When a -// spec doesn't fully dictate how to treat malformed files, different codec -// implementations have disagreed on whether to accept it (e.g. whether they -// follow Postel's Principle of "be liberal in what you accept") and if so, how -// to interpret it. Some implementations also raise those decisions to the -// application level, not the library level: "provide mechanism, not policy". -// -// For example, in an animated image, the first frame might not fill out the -// entire image, and different implementations choose a different default color -// for the outside pixels: opaque black, transparent black, or something else. -// -// Wuffs, out of the box, makes particular choices (typically mimicking the de -// facto canonical implementation), but enabling various quirks result in -// different choices. In particular, quirks are useful in regression testing -// that Wuffs and another implementation produce the same output for the same -// input, even for malformed input. -// -// In terms of the Wuffs API, each quirk is assigned a uint32 value. A base38 -// (github.com/google/wuffs/lib/base38) value can fit in 21 bits. Leaving the -// high bit of a uint32 reserved, the low 10 bits hold a package-specific -// enumeration: the base38 value acts as a namespace. +// Quirks are discussed in (/doc/note/quirks.md). // // The base38 encoding of "gif " is 0xF8586.