/*
-QOI - The “Quite OK Image” format for fast, lossless image compression
+QOI - The "Quite OK Image" format for fast, lossless image compression
Dominic Szablewski - https://phoboslab.org
usually around 10--30% larger than a decently optimized PNG image.
QOI outperforms simpler PNG encoders in compression ratio and performance. QOI
-images are typically 20% smaller than PNGs written with stbi_image but 10%
-larger than with libpng. Encoding is 25-50x faster and decoding is 3-4x faster
-than stbi_image or libpng.
+images are typically 20% smaller than PNGs written with stbi_image. Encoding is
+25-50x faster and decoding is 3-4x faster than stbi_image or libpng.
-- Synopsis
#define QOI_IMPLEMENTATION
#include "qoi.h"
-// Load and decode a QOI image from the file system into a 32bbp RGBA buffer
-int width, height;
-void *rgba_pixels = qoi_read("image.qoi", &width, &height, 4);
+// Encode and store an RGBA buffer to the file system. The qoi_desc describes
+// the input pixel data.
+qoi_write("image_new.qoi", rgba_pixels, &(qoi_desc){
+ .width = 1920,
+ .height = 1080,
+ .channels = 4,
+ .colorspace = QOI_SRGB
+});
+
+// Load and decode a QOI image from the file system into a 32bbp RGBA buffer.
+// The qoi_desc struct will be filled with the width, height, number of channels
+// and colorspace read from the file header.
+qoi_desc desc;
+void *rgba_pixels = qoi_read("image.qoi", &desc, 4);
-// Encode and store an RGBA buffer to the file system
-qoi_write("image_new.qoi", rgba_pixels, width, height, 4);
-- Documentation
-- Data Format
-A QOI file has a 12 byte header, followed by any number of data "chunks".
+A QOI file has a 14 byte header, followed by any number of data "chunks".
struct qoi_header_t {
- char [4]; // magic bytes "qoif"
- unsigned short width; // image width in pixels (BE)
- unsigned short height; // image height in pixels (BE)
- unsigned int size; // number of data bytes following this header (BE)
+ char magic[4]; // magic bytes "qoif"
+ uint32_t width; // image width in pixels (BE)
+ uint32_t height; // image height in pixels (BE)
+ uint8_t channels; // must be 3 (RGB) or 4 (RGBA)
+ uint8_t colorspace; // a bitmap 0000rgba where
+ // - a zero bit indicates sRGBA,
+ // - a one bit indicates linear (user interpreted)
+ // colorspace for each channel
};
The decoder and encoder start with {r: 0, g: 0, b: 0, a: 255} as the previous
Each chunk starts with a 2, 3 or 4 bit tag, followed by a number of data bits.
The bit length of chunks is divisible by 8 - i.e. all chunks are byte aligned.
+All values encoded in these data bits have the most significant bit (MSB) on the
+left.
-QOI_INDEX {
- u8 tag : 2; // b00
- u8 idx : 6; // 6-bit index into the color index array: 0..63
-}
+The possible chunks are:
-QOI_RUN_8 {
- u8 tag : 3; // b010
- u8 run : 5; // 5-bit run-length repeating the previous pixel: 1..32
-}
+ - QOI_INDEX -------------
+| Byte[0] |
+| 7 6 5 4 3 2 1 0 |
+|-------+-----------------|
+| 0 0 | index |
-QOI_RUN_16 {
- u8 tag : 3; // b011
- u16 run : 13; // 13-bit run-length repeating the previous pixel: 33..8224
-}
+2-bit tag b00
+6-bit index into the color index array: 0..63
-QOI_DIFF_8 {
- u8 tag : 2; // b10
- u8 dr : 2; // 2-bit red channel difference: -1..2
- u8 dg : 2; // 2-bit green channel difference: -1..2
- u8 db : 2; // 2-bit blue channel difference: -1..2
-}
-QOI_DIFF_16 {
- u8 tag : 3; // b110
- u8 dr : 5; // 5-bit red channel difference: -15..16
- u8 dg : 4; // 4-bit green channel difference: -7.. 8
- u8 db : 4; // 4-bit blue channel difference: -7.. 8
-}
+ - QOI_RUN_8 -------------
+| Byte[0] |
+| 7 6 5 4 3 2 1 0 |
+|----------+--------------|
+| 0 1 0 | run |
-QOI_DIFF_24 {
- u8 tag : 4; // b1110
- u8 dr : 5; // 5-bit red channel difference: -15..16
- u8 dg : 5; // 5-bit green channel difference: -15..16
- u8 db : 5; // 5-bit blue channel difference: -15..16
- u8 da : 5; // 5-bit alpha channel difference: -15..16
-}
+3-bit tag b010
+5-bit run-length repeating the previous pixel: 1..32
-QOI_COLOR {
- u8 tag : 4; // b1111
- u8 has_r: 1; // red byte follows
- u8 has_g: 1; // green byte follows
- u8 has_b: 1; // blue byte follows
- u8 has_a: 1; // alpha byte follows
- u8 r; // red value if has_r == 1: 0..255
- u8 g; // green value if has_g == 1: 0..255
- u8 b; // blue value if has_b == 1: 0..255
- u8 a; // alpha value if has_a == 1: 0..255
-}
-The byte stream is padded with 4 zero bytes. Size the longest chunk we can
-encounter is 5 bytes (QOI_COLOR with RGBA set), with this padding we just have
-to check for an overrun once per decode loop iteration.
+ - QOI_RUN_16 --------------------------------------
+| Byte[0] | Byte[1] |
+| 7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0 |
+|----------+----------------------------------------|
+| 0 1 1 | run |
+
+3-bit tag b011
+13-bit run-length repeating the previous pixel: 33..8224
+
+
+ - QOI_DIFF_8 ------------
+| Byte[0] |
+| 7 6 5 4 3 2 1 0 |
+|-------+-----+-----+-----|
+| 1 0 | dr | db | bg |
+
+2-bit tag b10
+2-bit red channel difference from the previous pixel between -2..1
+2-bit green channel difference from the previous pixel between -2..1
+2-bit blue channel difference from the previous pixel between -2..1
+
+The difference to the current channel values are using a wraparound operation,
+so "1 - 2" will result in 255, while "255 + 1" will result in 0.
+
+
+ - QOI_DIFF_16 -------------------------------------
+| Byte[0] | Byte[1] |
+| 7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0 |
+|----------+--------------|------------ +-----------|
+| 1 1 0 | red diff | green diff | blue diff |
+
+3-bit tag b110
+5-bit red channel difference from the previous pixel between -16..15
+4-bit green channel difference from the previous pixel between -8..7
+4-bit blue channel difference from the previous pixel between -8..7
+
+The difference to the current channel values are using a wraparound operation,
+so "10 - 13" will result in 253, while "250 + 7" will result in 1.
+
+
+ - QOI_DIFF_24 ---------------------------------------------------------------
+| Byte[0] | Byte[1] | Byte[2] |
+| 7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0 |
+|-------------+----------------+--------------+----------------+--------------|
+| 1 1 1 0 | red diff | green diff | blue diff | alpha diff |
+
+4-bit tag b1110
+5-bit red channel difference from the previous pixel between -16..15
+5-bit green channel difference from the previous pixel between -16..15
+5-bit blue channel difference from the previous pixel between -16..15
+5-bit alpha channel difference from the previous pixel between -16..15
+
+The difference to the current channel values are using a wraparound operation,
+so "10 - 13" will result in 253, while "250 + 7" will result in 1.
+
+
+ - QOI_COLOR -------------
+| Byte[0] |
+| 7 6 5 4 3 2 1 0 |
+|-------------+--+--+--+--|
+| 1 1 1 1 |hr|hg|hb|ha|
+
+4-bit tag b1111
+1-bit red byte follows
+1-bit green byte follows
+1-bit blue byte follows
+1-bit alpha byte follows
+
+For each set bit hr, hg, hb and ha another byte follows in this order. If such a
+byte follows, it will replace the current color channel value with the value of
+this byte.
+
+
+The byte stream is padded at the end with 4 zero bytes. Size the longest chunk
+we can encounter is 5 bytes (QOI_COLOR with RGBA set), with this padding we just
+have to check for an overrun once per decode loop iteration.
*/
extern "C" {
#endif
+// A pointer to qoi_desc struct has to be supplied to all of qoi's functions. It
+// describes either the input format (for qoi_write, qoi_encode), or is filled
+// with the description read from the file header (for qoi_read, qoi_decode).
+
+// The colorspace in this qoi_desc is a bitmap with 0000rgba where a 0-bit
+// indicates sRGB and a 1-bit indicates linear colorspace for each channel. You
+// may use one of the predefined constants: QOI_SRGB, QOI_SRGB_LINEAR_ALPHA or
+// QOI_LINEAR. The colorspace is purely informative. It will be saved to the
+// file header, but does not affect en-/decoding in any way.
+
+#define QOI_SRGB 0x00
+#define QOI_SRGB_LINEAR_ALPHA 0x01
+#define QOI_LINEAR 0x0f
+
+typedef struct {
+ unsigned int width;
+ unsigned int height;
+ unsigned char channels;
+ unsigned char colorspace;
+} qoi_desc;
+
#ifndef QOI_NO_STDIO
-// Encode raw RGB or RGBA pixels into a QOI image write it to the file system.
-// w and h denote the the width and height of the pixel data. channels must be
-// either 3 for RGB data or 4 for RGBA.
+// Encode raw RGB or RGBA pixels into a QOI image and write it to the file
+// system. The qoi_desc struct must be filled with the image width, height,
+// number of channels (3 = RGB, 4 = RGBA) and the colorspace.
+
// The function returns 0 on failure (invalid parameters, or fopen or malloc
// failed) or the number of bytes written on success.
-int qoi_write(const char *filename, const void *data, int w, int h, int channels);
+int qoi_write(const char *filename, const void *data, const qoi_desc *desc);
+
+// Read and decode a QOI image from the file system. If channels is 0, the
+// number of channels from the file header is used. If channels is 3 or 4 the
+// output format will be forced into this number of channels.
-// Read and decode a QOI image from the file system into either raw RGB
-// (channels=3) or RGBA (channels=4) pixel data.
// The function either returns NULL on failure (invalid data, or malloc or fopen
-// failed) or a pointer to the decoded pixels. On success out_w and out_h will
-// be set to the width and height of the decoded image.
+// failed) or a pointer to the decoded pixels. On success, the qoi_desc struct
+// will be filled with the description from the file header.
+
// The returned pixel data should be free()d after use.
-void *qoi_read(const char *filename, int *out_w, int *out_h, int channels);
+void *qoi_read(const char *filename, qoi_desc *desc, int channels);
#endif // QOI_NO_STDIO
-// Encode raw RGB or RGBA pixels into a QOI image in memory. w and h denote the
-// width and height of the pixel data. channels must be either 3 for RGB data
-// or 4 for RGBA.
+// Encode raw RGB or RGBA pixels into a QOI image in memory.
+
// The function either returns NULL on failure (invalid parameters or malloc
-// failed) or a pointer to the encoded data on success. On success the out_len
+// failed) or a pointer to the encoded data on success. On success the out_len
// is set to the size in bytes of the encoded data.
-// The returned qoi data should be free()d after user.
-void *qoi_encode(const void *data, int w, int h, int channels, int *out_len);
+// The returned qoi data should be free()d after use.
+
+void *qoi_encode(const void *data, const qoi_desc *desc, int *out_len);
+
+// Decode a QOI image from memory.
-// Decode a QOI image from memory into either raw RGB (channels=3) or RGBA
-// (channels=4) pixel data.
// The function either returns NULL on failure (invalid parameters or malloc
-// failed) or a pointer to the decoded pixels. On success out_w and out_h will
-// be set to the width and height of the decoded image.
+// failed) or a pointer to the decoded pixels. On success, the qoi_desc struct
+// is filled with the description from the file header.
+
// The returned pixel data should be free()d after use.
-void *qoi_decode(const void *data, int size, int *out_w, int *out_h, int channels);
+void *qoi_decode(const void *data, int size, qoi_desc *desc, int channels);
+
#ifdef __cplusplus
}
#define QOI_MAGIC \
(((unsigned int)'q') << 24 | ((unsigned int)'o') << 16 | \
((unsigned int)'i') << 8 | ((unsigned int)'f'))
-#define QOI_HEADER_SIZE 12
+#define QOI_HEADER_SIZE 14
#define QOI_PADDING 4
typedef union {
unsigned int v;
} qoi_rgba_t;
-void qoi_write_16(unsigned char *bytes, int *p, unsigned short v) {
- bytes[(*p)++] = (0xff00 & v) >> 8;
- bytes[(*p)++] = (0xff & v);
-}
-
void qoi_write_32(unsigned char *bytes, int *p, unsigned int v) {
- qoi_write_16(bytes, p, (v & 0xffff0000) >> 16);
- qoi_write_16(bytes, p, (v & 0xffff));
+ bytes[(*p)++] = (0xff000000 & v) >> 24;
+ bytes[(*p)++] = (0x00ff0000 & v) >> 16;
+ bytes[(*p)++] = (0x0000ff00 & v) >> 8;
+ bytes[(*p)++] = (0x000000ff & v);
}
-unsigned int qoi_read_16(const unsigned char *bytes, int *p) {
+unsigned int qoi_read_32(const unsigned char *bytes, int *p) {
unsigned int a = bytes[(*p)++];
unsigned int b = bytes[(*p)++];
- return (a << 8) | b;
-}
-
-unsigned int qoi_read_32(const unsigned char *bytes, int *p) {
- unsigned int a = qoi_read_16(bytes, p);
- unsigned int b = qoi_read_16(bytes, p);
- return (a << 16) | b;
+ unsigned int c = bytes[(*p)++];
+ unsigned int d = bytes[(*p)++];
+ return (a << 24) | (b << 16) | (c << 8) | d;
}
-void *qoi_encode(const void *data, int w, int h, int channels, int *out_len) {
+void *qoi_encode(const void *data, const qoi_desc *desc, int *out_len) {
if (
- data == NULL || out_len == NULL ||
- w <= 0 || w >= (1 << 16) ||
- h <= 0 || h >= (1 << 16) ||
- channels < 3 || channels > 4
+ data == NULL || out_len == NULL || desc == NULL ||
+ desc->width == 0 || desc->height == 0 ||
+ desc->channels < 3 || desc->channels > 4 ||
+ (desc->colorspace & 0xf0) != 0
) {
return NULL;
}
- int max_size = w * h * (channels + 1) + QOI_HEADER_SIZE + QOI_PADDING;
+ int max_size =
+ desc->width * desc->height * (desc->channels + 1) +
+ QOI_HEADER_SIZE + QOI_PADDING;
+
int p = 0;
unsigned char *bytes = QOI_MALLOC(max_size);
if (!bytes) {
}
qoi_write_32(bytes, &p, QOI_MAGIC);
- qoi_write_16(bytes, &p, w);
- qoi_write_16(bytes, &p, h);
- qoi_write_32(bytes, &p, 0); // size, will be set later
+ qoi_write_32(bytes, &p, desc->width);
+ qoi_write_32(bytes, &p, desc->height);
+ bytes[p++] = desc->channels;
+ bytes[p++] = desc->colorspace;
+
const unsigned char *pixels = (const unsigned char *)data;
int run = 0;
qoi_rgba_t px_prev = {.rgba = {.r = 0, .g = 0, .b = 0, .a = 255}};
qoi_rgba_t px = px_prev;
+
+ int px_len = desc->width * desc->height * desc->channels;
+ int px_end = px_len - desc->channels;
+ int channels = desc->channels;
- int px_len = w * h * channels;
- int px_end = px_len - channels;
for (int px_pos = 0; px_pos < px_len; px_pos += channels) {
if (channels == 4) {
px = *(qoi_rgba_t *)(pixels + px_pos);
run++;
}
- if (run > 0 && (run == 0x2020 || px.v != px_prev.v || px_pos == px_end)) {
+ if (
+ run > 0 &&
+ (run == 0x2020 || px.v != px_prev.v || px_pos == px_end)
+ ) {
if (run < 33) {
run -= 1;
bytes[p++] = QOI_RUN_8 | run;
int vg = px.rgba.g - px_prev.rgba.g;
int vb = px.rgba.b - px_prev.rgba.b;
int va = px.rgba.a - px_prev.rgba.a;
-
+
if (
- vr > -16 && vr < 17 && vg > -16 && vg < 17 &&
- vb > -16 && vb < 17 && va > -16 && va < 17
+ vr > -17 && vr < 16 &&
+ vg > -17 && vg < 16 &&
+ vb > -17 && vb < 16 &&
+ va > -17 && va < 16
) {
if (
- va == 0 && vr > -2 && vr < 3 &&
- vg > -2 && vg < 3 && vb > -2 && vb < 3
+ va == 0 &&
+ vr > -3 && vr < 2 &&
+ vg > -3 && vg < 2 &&
+ vb > -3 && vb < 2
) {
- bytes[p++] = QOI_DIFF_8 | ((vr + 1) << 4) | (vg + 1) << 2 | (vb + 1);
+ bytes[p++] = QOI_DIFF_8 | ((vr + 2) << 4) | (vg + 2) << 2 | (vb + 2);
}
else if (
- va == 0 && vr > -16 && vr < 17 &&
- vg > -8 && vg < 9 && vb > -8 && vb < 9
+ va == 0 &&
+ vr > -17 && vr < 16 &&
+ vg > -9 && vg < 8 &&
+ vb > -9 && vb < 8
) {
- bytes[p++] = QOI_DIFF_16 | (vr + 15);
- bytes[p++] = ((vg + 7) << 4) | (vb + 7);
+ bytes[p++] = QOI_DIFF_16 | (vr + 16);
+ bytes[p++] = (vg + 8) << 4 | (vb + 8);
}
else {
- bytes[p++] = QOI_DIFF_24 | ((vr + 15) >> 1);
- bytes[p++] = ((vr + 15) << 7) | ((vg + 15) << 2) | ((vb + 15) >> 3);
- bytes[p++] = ((vb + 15) << 5) | (va + 15);
+ bytes[p++] = QOI_DIFF_24 | (vr + 16) >> 1;
+ bytes[p++] = (vr + 16) << 7 | (vg + 16) << 2 | (vb + 16) >> 3;
+ bytes[p++] = (vb + 16) << 5 | (va + 16);
}
}
else {
- bytes[p++] = QOI_COLOR | (vr?8:0)|(vg?4:0)|(vb?2:0)|(va?1:0);
+ bytes[p++] = QOI_COLOR | (vr ? 8 : 0) | (vg ? 4 : 0) | (vb ? 2 : 0) | (va ? 1 : 0);
if (vr) { bytes[p++] = px.rgba.r; }
if (vg) { bytes[p++] = px.rgba.g; }
if (vb) { bytes[p++] = px.rgba.b; }
bytes[p++] = 0;
}
- int data_len = p - QOI_HEADER_SIZE;
*out_len = p;
-
- p = 8;
- qoi_write_32(bytes, &p, data_len);
return bytes;
}
-void *qoi_decode(const void *data, int size, int *out_w, int *out_h, int channels) {
- if (channels < 3 || channels > 4 || size < QOI_HEADER_SIZE) {
+void *qoi_decode(const void *data, int size, qoi_desc *desc, int channels) {
+ if (
+ data == NULL || desc == NULL ||
+ (channels != 0 && channels != 3 && channels != 4) ||
+ size < QOI_HEADER_SIZE + QOI_PADDING
+ ) {
return NULL;
}
const unsigned char *bytes = (const unsigned char *)data;
int p = 0;
- int magic = qoi_read_32(bytes, &p);
- int w = qoi_read_16(bytes, &p);
- int h = qoi_read_16(bytes, &p);
- int data_len = qoi_read_32(bytes, &p);
+ unsigned int header_magic = qoi_read_32(bytes, &p);
+ desc->width = qoi_read_32(bytes, &p);
+ desc->height = qoi_read_32(bytes, &p);
+ desc->channels = bytes[p++];
+ desc->colorspace = bytes[p++];
if (
- w == 0 || h == 0 || magic != QOI_MAGIC ||
- size != data_len + QOI_HEADER_SIZE
+ desc->width == 0 || desc->height == 0 ||
+ desc->channels < 3 || desc->channels > 4 ||
+ header_magic != QOI_MAGIC
) {
return NULL;
}
- int px_len = w * h * channels;
+ if (channels == 0) {
+ channels = desc->channels;
+ }
+
+ int px_len = desc->width * desc->height * channels;
unsigned char *pixels = QOI_MALLOC(px_len);
if (!pixels) {
return NULL;
run = (((b1 & 0x1f) << 8) | (b2)) + 32;
}
else if ((b1 & QOI_MASK_2) == QOI_DIFF_8) {
- px.rgba.r += ((b1 >> 4) & 0x03) - 1;
- px.rgba.g += ((b1 >> 2) & 0x03) - 1;
- px.rgba.b += ( b1 & 0x03) - 1;
+ px.rgba.r += ((b1 >> 4) & 0x03) - 2;
+ px.rgba.g += ((b1 >> 2) & 0x03) - 2;
+ px.rgba.b += ( b1 & 0x03) - 2;
}
else if ((b1 & QOI_MASK_3) == QOI_DIFF_16) {
int b2 = bytes[p++];
- px.rgba.r += (b1 & 0x1f) - 15;
- px.rgba.g += (b2 >> 4) - 7;
- px.rgba.b += (b2 & 0x0f) - 7;
+ px.rgba.r += (b1 & 0x1f) - 16;
+ px.rgba.g += (b2 >> 4) - 8;
+ px.rgba.b += (b2 & 0x0f) - 8;
}
else if ((b1 & QOI_MASK_4) == QOI_DIFF_24) {
int b2 = bytes[p++];
int b3 = bytes[p++];
- px.rgba.r += (((b1 & 0x0f) << 1) | (b2 >> 7)) - 15;
- px.rgba.g += ((b2 & 0x7c) >> 2) - 15;
- px.rgba.b += (((b2 & 0x03) << 3) | ((b3 & 0xe0) >> 5)) - 15;
- px.rgba.a += (b3 & 0x1f) - 15;
+ px.rgba.r += (((b1 & 0x0f) << 1) | (b2 >> 7)) - 16;
+ px.rgba.g += ((b2 & 0x7c) >> 2) - 16;
+ px.rgba.b += (((b2 & 0x03) << 3) | ((b3 & 0xe0) >> 5)) - 16;
+ px.rgba.a += (b3 & 0x1f) - 16;
}
else if ((b1 & QOI_MASK_4) == QOI_COLOR) {
if (b1 & 8) { px.rgba.r = bytes[p++]; }
}
}
- *out_w = w;
- *out_h = h;
return pixels;
}
#ifndef QOI_NO_STDIO
#include <stdio.h>
-int qoi_write(const char *filename, const void *data, int w, int h, int channels) {
- int size;
- void *encoded = qoi_encode(data, w, h, channels, &size);
- if (!encoded) {
- return 0;
- }
-
+int qoi_write(const char *filename, const void *data, const qoi_desc *desc) {
FILE *f = fopen(filename, "wb");
if (!f) {
- QOI_FREE(encoded);
return 0;
}
+
+ int size;
+ void *encoded = qoi_encode(data, desc, &size);
+ if (!encoded) {
+ fclose(f);
+ return 0;
+ }
fwrite(encoded, 1, size, f);
fclose(f);
+
QOI_FREE(encoded);
return size;
}
-void *qoi_read(const char *filename, int *out_w, int *out_h, int channels) {
+void *qoi_read(const char *filename, qoi_desc *desc, int channels) {
FILE *f = fopen(filename, "rb");
if (!f) {
return NULL;
void *data = QOI_MALLOC(size);
if (!data) {
+ fclose(f);
return NULL;
}
int bytes_read = fread(data, 1, size, f);
fclose(f);
- void *pixels = qoi_decode(data, bytes_read, out_w, out_h, channels);
+ void *pixels = qoi_decode(data, bytes_read, desc, channels);
QOI_FREE(data);
return pixels;
}
#endif // QOI_NO_STDIO
#endif // QOI_IMPLEMENTATION
+
projects / fishladder.git / commitdiff