Add doc/note/quirks.md

This commit is contained in:
Nigel Tao committed 2019-06-29 18:44:41 +10:00
1 parent 4c27fa664a
commit 944b9fb008
2 files changed
+35 -24

No files matched your search

+1 -24
View File
@@ -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.