From fc9c2916f524f35b287de6db226ec681abf179c7 Mon Sep 17 00:00:00 2001 From: Nigel Tao Date: Sun, 26 May 2019 09:27:17 +1000 Subject: [PATCH] Add more commentary about quirks --- std/gif/decode_gif.wuffs | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/std/gif/decode_gif.wuffs b/std/gif/decode_gif.wuffs index 902fb1c8..92511622 100644 --- a/std/gif/decode_gif.wuffs +++ b/std/gif/decode_gif.wuffs @@ -30,12 +30,31 @@ pub const decoder_workbuf_len_max_incl_worst_case base.u64 = 1 // -------- -// 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 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. // -// 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 can be used for -// package-specific quirk constants: the base38 value acts as a namespace. - // The base38 encoding of "gif " is 0xF8586. // When this quirk is enabled, when skipping over frames, the number of frames