Documentation updates
5 files changed, 29 insertions(+), 112 deletions(-)

M FAQ.md => FAQ_QOIR.md
M README.md
R README_QUAIL.txt => 
M size_comparison/filesizes.txt => size_comparison/QOI-R/filesizes.txt
M size_comparison/parselog.py => size_comparison/QOI-R/parselog.py
M FAQ.md => FAQ_QOIR.md +0 -0

M README.md +29 -67
@@ 1,85 1,47 @@ 
-# Description
-
-QOI-Remix is an incompatible variant of Dominic Szablewski's excellent Quite OK Image Format (https://qoiformat.org) with the aim of providing a measurable density improvement with a moderate compute penalty.
+# QUAIL
 
-# What does QOI-R include?
+QUAIL - the Quite Advanced Image Library - is a new image codec drawing on experience with QOI and QOI-Remix. After I designed QOI-R, I decided to start from scratch on a new nibble-oriented spec rather than continuing to modify QOI; QUAIL is the result of that effort. It uses the QOI harness and infrastructure (qbench/qconv) but is a largely clean-sheet encoding.
 
-The QOI-R distribution includes both QOI and QOI-R support.
+QUAIL gets solid density improvements against QOI/QOI-R with a moderate performance hit (and remains drastically higher-throughput than PNG.) Optimization will be a focus in the coming months, so throughput may improve. Additionally, I've been working to address some of what I consider to be QOI pain points - lack of support for very large images being a big one.
 
-* qoi.h - the upstream QOI format, unmodified
-* qoir.h - the new QOI-R code, derived from qoi.h, heavily modified but largely using compatible interfaces
-* qoirbench - a tool for doing bulk benchmarking of performance and compression for QOI, QOI-R, and libpng (but not STB PNG, unlike upstream qoibench)
-* qoirconv - a tool for doing file conversions between QOI, QOI-R, and PNG (using STB PNG) in any direction
+The spec should be considered very cold but not quite frozen. I don't expect to break compatibility, but it's not impossible. The code itself should be considered to be in a much higher state of flux than the spec.
 
-# Dependencies
-
-The base qoir.h should be usable with no significant external dependencies except a "normal" system environment (a C99 compiler, 8-bit bytes, some concession to POSIX, etc.)
+QUAIL has been tested on Linux (Z, PPC64LE, ARM64, Itanium, x86_64) and HP-UX (Itanium.)
 
-qoirbench depends on libpng and the presence of stb_image.h (from the "stb" library by nothings, available at https://github.com/nothings/stb). qoirconv depends on stb_image.h and stb_image_write.h, but not libpng.
-
-# Platform Support
+## What about QOI-R?
 
-QOI-R is very new, and has been only tested and validated on a handful of platforms. That being said, it should compile on any system with a more or less sane POSIX environment. qoirbench, in particular, has had some small portability changes to make it less Linux-dependent than upstream QOI.
-
-QOI-R has been tested on:
+QOI-R remains present in the QUAIL tree, as does QOI. QOI-R work is effectively complete, with the exception that I intend to produce a spec at some point. The QOI-R format will not change.
 
-* Linux on x86-64, ARM64, IBM Z, and PPC64LE, with GCC
-* HP-UX 11i v3 on Itanium, with slight makefile tweaks to accomodate HP compiler parameters
+README-QOIR.md contains the original QOI-R readme.
 
-In the near future, I would like to test it on:
+## QUAIL Encoding
 
-* Embedded systems, including QNX (which will almost certainly work without significant changes), LynxOS, and light RTOS's like FreeRTOS and MQX
-* AIX, somewhat against my better judgment
-* NT
-* Mac OS
-* OpenVMS
-* OpenVOS
-* Nonstop
+This is extremely sparse right now and should be considered a work in progress. Much though I hate to say it, right now the code is the spec.
 
-I would welcome an email (sunset@arcanesciences.com) from anyone that compiles QOI-R on a platform I haven't validated.
+### Structures
 
-# Performance Notes
+#### Pixel
 
-The ratio of QOI-R to QOI performance varies between systems and compilers. I'm not going to publish concrete figures, because benchmarking methodology is a complex art and vendors often get prickly about how it's done, but I will list performance ratios based on megapixels per second, with libpng as the baseline, so that users can use to project performance on their hardware of choice.
+8-bit channels, optional alpha depending on source PNG.
 
-These numbers are using QOI's benchmark image set. Usual caveats regarding benchmarks apply. libpng is normalized to 1.0.
+#### Hash
 
-## x86-64 (Tiger Lake, Linux, gcc 13.1, nonvirtualized)
+r * 3 + g * 5 + b * 7 + a * 11 - this is the same hash used by QOI.
 
-```
-         Encode    Decode
-QOI      38.82     3.23
-QOIR     31.89     2.98
-```
-
-## ARM64 (Altra, Linux, gcc 8.5.0, virtualized)
+#### Indexes
 
-```
-         Encode    Decode
-QOI      32.83     3.39
-QOIR     27.70     2.93
-```
+QUAIL uses three indexes - Microindex (8 entries), Macroindex (256 entries), Last Level Index (4096 entries). Accessed via hash of pixel, modulo size of index. Pixel encoding is hashed index. Every index miss (ie, falling through to a longer word type) results in insertion of pixel into the index.
 
-## Z (z15 T02, Linux, gcc 9.3.0, virtualized)
+### Encoding Words
 
-```
-         Encode    Decode
-QOI      30.17     2.21
-QOIR     25.61     1.99
-```
-
-## PPC64LE (Power9, Linux, gcc 9.3.0, virtualized)
-```
-         Encode    Decode
-QOI      33.50     4.65
-QOIR     28.06     4.15
-```
-
-## Itanium (Itanium 95xx, HP-UX, aCC, nonvirtualized)
-```
-         Encode    Decode
-QOI      24.65*    3.32
-QOIR     28.50*    1.79
-```
-
-*This is not a typo. QOI-R encode outperforms QOI encode on this platform. I haven't had an opportunity to do a deep examination of the reason; it's also interesting that QOI-R decode is substantially slower than QOI.
+- 1iii - Index Into Microindex
+- 0010 llll - short run
+- 0100 iiii iiii - Index into Macroindex
+- 0011 llll llll - long run
+- 000r rrgg gbbb - Diff
+- 0110 gggg ggrr rbbb - Microluma; like Medium Luma with shrunken fields
+- 0101 0010 iiii iiii iiii - Index into pixel Last Level Index
+- 0111 gggg ggrr rrrb bbbb - Medium Luma, where g is difference green, r is (difference red - difference green), b is (difference blue - difference green)
+- 0101 1ggg gggg rrrr rrbb bbbb - Megaluma; like Medium Luma with expanded fields
+- 0101 0001 rrrr rrrr gggg gggg bbbb bbbb - Immediate RGB pixel
+- 0101 0000 rrrr rrrr gggg gggg bbbb bbbb aaaa aaaa - Immediate RGBA pixel

          
R README_QUAIL.txt =>  +0 -45
@@ 1,45 0,0 @@ 
-# QUAIL
-
-QUAIL - the Quite Advanced Image Library - is a new image codec drawing on experience with QOI and QOI-Remix. After I designed QOI-R, I decided to start from scratch on a new nibble-oriented spec rather than continuing to modify QOI; QUAIL is the result of that effort. It uses the QOI harness and infrastructure (qbench/qconv) but is a largely clean-sheet encoding.
-
-QUAIL gets solid density improvements against QOI/QOI-R with a moderate performance hit (and remains drastically higher-throughput than PNG.) Optimization will be a focus in the coming months, so throughput may improve. Additionally, I've been working to address some of what I consider to be QOI pain points - lack of support for very large images being a big one.
-
-The spec should be considered very cold but not quite frozen. I don't expect to break compatibility, but it's not impossible. The code itself should be considered to be in a much higher state of flux than the spec.
-
-QUAIL has been tested on Linux (Z, PPC64LE, ARM64, Itanium, x86_64) and HP-UX (Itanium.)
-
-## What about QOI-R?
-
-QOI-R remains present in the QUAIL tree, as does QOI. QOI-R work is effectively complete, with the exception that I intend to produce a spec at some point. The QOI-R format will not change.
-
-## QUAIL Encoding
-
-This is extremely sparse right now and should be considered a work in progress. Much though I hate to say it, right now the code is the spec.
-
-### Structures
-
-#### Pixel
-
-8-bit channels, optional alpha depending on source PNG.
-
-#### Hash
-
-r * 3 + g * 5 + b * 7 + a * 11 - this is the same hash used by QOI.
-
-#### Indexes
-
-QUAIL uses three indexes - Microindex (8 entries), Macroindex (256 entries), Last Level Index (4096 entries). Accessed via hash of pixel, modulo size of index. Pixel encoding is hashed index. Every index miss (ie, falling through to a longer word type) results in insertion of pixel into the index.
-
-### Encoding Words
-
-- 1iii - Index Into Microindex
-- 0010 llll - short run
-- 0100 iiii iiii - Index into Macroindex
-- 0011 llll llll - long run
-- 000r rrgg gbbb - Diff
-- 0110 gggg ggrr rbbb - Microluma; like Medium Luma with shrunken fields
-- 0101 0010 iiii iiii iiii - Index into pixel Last Level Index
-- 0111 gggg ggrr rrrb bbbb - Medium Luma, where g is difference green, r is (difference red - difference green), b is (difference blue - difference green)
-- 0101 1ggg gggg rrrr rrbb bbbb - Megaluma; like Medium Luma with expanded fields
-- 0101 0001 rrrr rrrr gggg gggg bbbb bbbb - Immediate RGB pixel
-- 0101 0000 rrrr rrrr gggg gggg bbbb bbbb aaaa aaaa - Immediate RGBA pixel

          
M size_comparison/filesizes.txt => size_comparison/QOI-R/filesizes.txt +0 -0

M size_comparison/parselog.py => size_comparison/QOI-R/parselog.py +0 -0