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

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