mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-18 00:32:11 +01:00
Add doc/note/quirks.md
This commit is contained in:
1 parent
4c27fa664a
commit
944b9fb008
2 files changed
+35
-24
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
|
||||
Reference in new issue
Block a user