3 QOI - The "Quite OK Image" format for fast, lossless image compression
5 Dominic Szablewski - https://phoboslab.org
8 -- LICENSE: The MIT License(MIT)
10 Copyright(c) 2021 Dominic Szablewski
12 Permission is hereby granted, free of charge, to any person obtaining a copy of
13 this software and associated documentation files(the "Software"), to deal in
14 the Software without restriction, including without limitation the rights to
15 use, copy, modify, merge, publish, distribute, sublicense, and / or sell copies
16 of the Software, and to permit persons to whom the Software is furnished to do
17 so, subject to the following conditions :
18 The above copyright notice and this permission notice shall be included in all
19 copies or substantial portions of the Software.
20 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
23 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
31 QOI encodes and decodes images in a lossless format. An encoded QOI image is
32 usually around 10--30% larger than a decently optimized PNG image.
34 QOI outperforms simpler PNG encoders in compression ratio and performance. QOI
35 images are typically 20% smaller than PNGs written with stbi_image. Encoding is
36 25-50x faster and decoding is 3-4x faster than stbi_image or libpng.
41 // Define `QOI_IMPLEMENTATION` in *one* C/C++ file before including this
42 // library to create the implementation.
44 #define QOI_IMPLEMENTATION
47 // Encode and store an RGBA buffer to the file system. The qoi_desc describes
48 // the input pixel data.
49 qoi_write("image_new.qoi", rgba_pixels, &(qoi_desc){
53 .colorspace = QOI_SRGB
56 // Load and decode a QOI image from the file system into a 32bbp RGBA buffer.
57 // The qoi_desc struct will be filled with the width, height, number of channels
58 // and colorspace read from the file header.
60 void *rgba_pixels = qoi_read("image.qoi", &desc, 4);
66 This library provides the following functions;
67 - qoi_read -- read and decode a QOI file
68 - qoi_decode -- decode the raw bytes of a QOI image from memory
69 - qoi_write -- encode and write a QOI file
70 - qoi_encode -- encode an rgba buffer into a QOI image in memory
72 See the function declaration below for the signature and more information.
74 If you don't want/need the qoi_read and qoi_write functions, you can define
75 QOI_NO_STDIO before including this library.
77 This library uses malloc() and free(). To supply your own malloc implementation
78 you can define QOI_MALLOC and QOI_FREE before including this library.
83 A QOI file has a 14 byte header, followed by any number of data "chunks".
86 char magic[4]; // magic bytes "qoif"
87 uint32_t width; // image width in pixels (BE)
88 uint32_t height; // image height in pixels (BE)
89 uint8_t channels; // must be 3 (RGB) or 4 (RGBA)
90 uint8_t colorspace; // a bitmap 0000rgba where
91 // - a zero bit indicates sRGBA,
92 // - a one bit indicates linear (user interpreted)
93 // colorspace for each channel
96 The decoder and encoder start with {r: 0, g: 0, b: 0, a: 255} as the previous
97 pixel value. Pixels are either encoded as
98 - a run of the previous pixel
99 - an index into a previously seen pixel
100 - a difference to the previous pixel value in r,g,b,a
101 - full r,g,b,a values
103 A running array[64] of previously seen pixel values is maintained by the encoder
104 and decoder. Each pixel that is seen by the encoder and decoder is put into this
105 array at the position (r^g^b^a) % 64. In the encoder, if the pixel value at this
106 index matches the current pixel, this index position is written to the stream.
108 Each chunk starts with a 2, 3 or 4 bit tag, followed by a number of data bits.
109 The bit length of chunks is divisible by 8 - i.e. all chunks are byte aligned.
110 All values encoded in these data bits have the most significant bit (MSB) on the
113 The possible chunks are:
115 - QOI_INDEX -------------
118 |-------+-----------------|
122 6-bit index into the color index array: 0..63
125 - QOI_RUN_8 -------------
128 |----------+--------------|
132 5-bit run-length repeating the previous pixel: 1..32
135 - QOI_RUN_16 --------------------------------------
136 | Byte[0] | Byte[1] |
137 | 7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0 |
138 |----------+----------------------------------------|
142 13-bit run-length repeating the previous pixel: 33..8224
145 - QOI_DIFF_8 ------------
148 |-------+-----+-----+-----|
149 | 1 0 | dr | db | bg |
152 2-bit red channel difference from the previous pixel between -2..1
153 2-bit green channel difference from the previous pixel between -2..1
154 2-bit blue channel difference from the previous pixel between -2..1
156 The difference to the current channel values are using a wraparound operation,
157 so "1 - 2" will result in 255, while "255 + 1" will result in 0.
160 - QOI_DIFF_16 -------------------------------------
161 | Byte[0] | Byte[1] |
162 | 7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0 |
163 |----------+--------------|------------ +-----------|
164 | 1 1 0 | red diff | green diff | blue diff |
167 5-bit red channel difference from the previous pixel between -16..15
168 4-bit green channel difference from the previous pixel between -8..7
169 4-bit blue channel difference from the previous pixel between -8..7
171 The difference to the current channel values are using a wraparound operation,
172 so "10 - 13" will result in 253, while "250 + 7" will result in 1.
175 - QOI_DIFF_24 ---------------------------------------------------------------
176 | Byte[0] | Byte[1] | Byte[2] |
177 | 7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0 |
178 |-------------+----------------+--------------+----------------+--------------|
179 | 1 1 1 0 | red diff | green diff | blue diff | alpha diff |
182 5-bit red channel difference from the previous pixel between -16..15
183 5-bit green channel difference from the previous pixel between -16..15
184 5-bit blue channel difference from the previous pixel between -16..15
185 5-bit alpha channel difference from the previous pixel between -16..15
187 The difference to the current channel values are using a wraparound operation,
188 so "10 - 13" will result in 253, while "250 + 7" will result in 1.
191 - QOI_COLOR -------------
194 |-------------+--+--+--+--|
195 | 1 1 1 1 |hr|hg|hb|ha|
198 1-bit red byte follows
199 1-bit green byte follows
200 1-bit blue byte follows
201 1-bit alpha byte follows
203 For each set bit hr, hg, hb and ha another byte follows in this order. If such a
204 byte follows, it will replace the current color channel value with the value of
208 The byte stream is padded at the end with 4 zero bytes. Size the longest chunk
209 we can encounter is 5 bytes (QOI_COLOR with RGBA set), with this padding we just
210 have to check for an overrun once per decode loop iteration.
215 // -----------------------------------------------------------------------------
216 // Header - Public functions
225 // A pointer to qoi_desc struct has to be supplied to all of qoi's functions. It
226 // describes either the input format (for qoi_write, qoi_encode), or is filled
227 // with the description read from the file header (for qoi_read, qoi_decode).
229 // The colorspace in this qoi_desc is a bitmap with 0000rgba where a 0-bit
230 // indicates sRGB and a 1-bit indicates linear colorspace for each channel. You
231 // may use one of the predefined constants: QOI_SRGB, QOI_SRGB_LINEAR_ALPHA or
232 // QOI_LINEAR. The colorspace is purely informative. It will be saved to the
233 // file header, but does not affect en-/decoding in any way.
235 #define QOI_SRGB 0x00
236 #define QOI_SRGB_LINEAR_ALPHA 0x01
237 #define QOI_LINEAR 0x0f
242 unsigned char channels
;
243 unsigned char colorspace
;
248 // Encode raw RGB or RGBA pixels into a QOI image and write it to the file
249 // system. The qoi_desc struct must be filled with the image width, height,
250 // number of channels (3 = RGB, 4 = RGBA) and the colorspace.
252 // The function returns 0 on failure (invalid parameters, or fopen or malloc
253 // failed) or the number of bytes written on success.
255 int qoi_write(const char *filename
, const void *data
, const qoi_desc
*desc
);
258 // Read and decode a QOI image from the file system. If channels is 0, the
259 // number of channels from the file header is used. If channels is 3 or 4 the
260 // output format will be forced into this number of channels.
262 // The function either returns NULL on failure (invalid data, or malloc or fopen
263 // failed) or a pointer to the decoded pixels. On success, the qoi_desc struct
264 // will be filled with the description from the file header.
266 // The returned pixel data should be free()d after use.
268 void *qoi_read(const char *filename
, qoi_desc
*desc
, int channels
);
270 #endif // QOI_NO_STDIO
273 // Encode raw RGB or RGBA pixels into a QOI image in memory.
275 // The function either returns NULL on failure (invalid parameters or malloc
276 // failed) or a pointer to the encoded data on success. On success the out_len
277 // is set to the size in bytes of the encoded data.
279 // The returned qoi data should be free()d after use.
281 void *qoi_encode(const void *data
, const qoi_desc
*desc
, int *out_len
);
284 // Decode a QOI image from memory.
286 // The function either returns NULL on failure (invalid parameters or malloc
287 // failed) or a pointer to the decoded pixels. On success, the qoi_desc struct
288 // is filled with the description from the file header.
290 // The returned pixel data should be free()d after use.
292 void *qoi_decode(const void *data
, int size
, qoi_desc
*desc
, int channels
);
301 // -----------------------------------------------------------------------------
304 #ifdef QOI_IMPLEMENTATION
308 #define QOI_MALLOC(sz) malloc(sz)
309 #define QOI_FREE(p) free(p)
312 #define QOI_INDEX 0x00 // 00xxxxxx
313 #define QOI_RUN_8 0x40 // 010xxxxx
314 #define QOI_RUN_16 0x60 // 011xxxxx
315 #define QOI_DIFF_8 0x80 // 10xxxxxx
316 #define QOI_DIFF_16 0xc0 // 110xxxxx
317 #define QOI_DIFF_24 0xe0 // 1110xxxx
318 #define QOI_COLOR 0xf0 // 1111xxxx
320 #define QOI_MASK_2 0xc0 // 11000000
321 #define QOI_MASK_3 0xe0 // 11100000
322 #define QOI_MASK_4 0xf0 // 11110000
324 #define QOI_COLOR_HASH(C) (C.rgba.r ^ C.rgba.g ^ C.rgba.b ^ C.rgba.a)
326 (((unsigned int)'q') << 24 | ((unsigned int)'o') << 16 | \
327 ((unsigned int)'i') << 8 | ((unsigned int)'f'))
328 #define QOI_HEADER_SIZE 14
329 #define QOI_PADDING 4
332 struct { unsigned char r
, g
, b
, a
; } rgba
;
336 void qoi_write_32(unsigned char *bytes
, int *p
, unsigned int v
) {
337 bytes
[(*p
)++] = (0xff000000 & v
) >> 24;
338 bytes
[(*p
)++] = (0x00ff0000 & v
) >> 16;
339 bytes
[(*p
)++] = (0x0000ff00 & v
) >> 8;
340 bytes
[(*p
)++] = (0x000000ff & v
);
343 unsigned int qoi_read_32(const unsigned char *bytes
, int *p
) {
344 unsigned int a
= bytes
[(*p
)++];
345 unsigned int b
= bytes
[(*p
)++];
346 unsigned int c
= bytes
[(*p
)++];
347 unsigned int d
= bytes
[(*p
)++];
348 return (a
<< 24) | (b
<< 16) | (c
<< 8) | d
;
351 void *qoi_encode(const void *data
, const qoi_desc
*desc
, int *out_len
) {
353 data
== NULL
|| out_len
== NULL
|| desc
== NULL
||
354 desc
->width
== 0 || desc
->height
== 0 ||
355 desc
->channels
< 3 || desc
->channels
> 4 ||
356 (desc
->colorspace
& 0xf0) != 0
362 desc
->width
* desc
->height
* (desc
->channels
+ 1) +
363 QOI_HEADER_SIZE
+ QOI_PADDING
;
366 unsigned char *bytes
= QOI_MALLOC(max_size
);
371 qoi_write_32(bytes
, &p
, QOI_MAGIC
);
372 qoi_write_32(bytes
, &p
, desc
->width
);
373 qoi_write_32(bytes
, &p
, desc
->height
);
374 bytes
[p
++] = desc
->channels
;
375 bytes
[p
++] = desc
->colorspace
;
378 const unsigned char *pixels
= (const unsigned char *)data
;
380 qoi_rgba_t index
[64] = {0};
383 qoi_rgba_t px_prev
= {.rgba
= {.r
= 0, .g
= 0, .b
= 0, .a
= 255}};
384 qoi_rgba_t px
= px_prev
;
386 int px_len
= desc
->width
* desc
->height
* desc
->channels
;
387 int px_end
= px_len
- desc
->channels
;
388 int channels
= desc
->channels
;
390 for (int px_pos
= 0; px_pos
< px_len
; px_pos
+= channels
) {
392 px
= *(qoi_rgba_t
*)(pixels
+ px_pos
);
395 px
.rgba
.r
= pixels
[px_pos
];
396 px
.rgba
.g
= pixels
[px_pos
+1];
397 px
.rgba
.b
= pixels
[px_pos
+2];
400 if (px
.v
== px_prev
.v
) {
406 (run
== 0x2020 || px
.v
!= px_prev
.v
|| px_pos
== px_end
)
410 bytes
[p
++] = QOI_RUN_8
| run
;
414 bytes
[p
++] = QOI_RUN_16
| run
>> 8;
420 if (px
.v
!= px_prev
.v
) {
421 int index_pos
= QOI_COLOR_HASH(px
) % 64;
423 if (index
[index_pos
].v
== px
.v
) {
424 bytes
[p
++] = QOI_INDEX
| index_pos
;
427 index
[index_pos
] = px
;
429 int vr
= px
.rgba
.r
- px_prev
.rgba
.r
;
430 int vg
= px
.rgba
.g
- px_prev
.rgba
.g
;
431 int vb
= px
.rgba
.b
- px_prev
.rgba
.b
;
432 int va
= px
.rgba
.a
- px_prev
.rgba
.a
;
435 vr
> -17 && vr
< 16 &&
436 vg
> -17 && vg
< 16 &&
437 vb
> -17 && vb
< 16 &&
446 bytes
[p
++] = QOI_DIFF_8
| ((vr
+ 2) << 4) | (vg
+ 2) << 2 | (vb
+ 2);
450 vr
> -17 && vr
< 16 &&
454 bytes
[p
++] = QOI_DIFF_16
| (vr
+ 16);
455 bytes
[p
++] = (vg
+ 8) << 4 | (vb
+ 8);
458 bytes
[p
++] = QOI_DIFF_24
| (vr
+ 16) >> 1;
459 bytes
[p
++] = (vr
+ 16) << 7 | (vg
+ 16) << 2 | (vb
+ 16) >> 3;
460 bytes
[p
++] = (vb
+ 16) << 5 | (va
+ 16);
464 bytes
[p
++] = QOI_COLOR
| (vr
? 8 : 0) | (vg
? 4 : 0) | (vb
? 2 : 0) | (va
? 1 : 0);
465 if (vr
) { bytes
[p
++] = px
.rgba
.r
; }
466 if (vg
) { bytes
[p
++] = px
.rgba
.g
; }
467 if (vb
) { bytes
[p
++] = px
.rgba
.b
; }
468 if (va
) { bytes
[p
++] = px
.rgba
.a
; }
475 for (int i
= 0; i
< QOI_PADDING
; i
++) {
483 void *qoi_decode(const void *data
, int size
, qoi_desc
*desc
, int channels
) {
485 data
== NULL
|| desc
== NULL
||
486 (channels
!= 0 && channels
!= 3 && channels
!= 4) ||
487 size
< QOI_HEADER_SIZE
+ QOI_PADDING
492 const unsigned char *bytes
= (const unsigned char *)data
;
495 unsigned int header_magic
= qoi_read_32(bytes
, &p
);
496 desc
->width
= qoi_read_32(bytes
, &p
);
497 desc
->height
= qoi_read_32(bytes
, &p
);
498 desc
->channels
= bytes
[p
++];
499 desc
->colorspace
= bytes
[p
++];
502 desc
->width
== 0 || desc
->height
== 0 ||
503 desc
->channels
< 3 || desc
->channels
> 4 ||
504 header_magic
!= QOI_MAGIC
510 channels
= desc
->channels
;
513 int px_len
= desc
->width
* desc
->height
* channels
;
514 unsigned char *pixels
= QOI_MALLOC(px_len
);
519 qoi_rgba_t px
= {.rgba
= {.r
= 0, .g
= 0, .b
= 0, .a
= 255}};
520 qoi_rgba_t index
[64] = {0};
523 int chunks_len
= size
- QOI_PADDING
;
524 for (int px_pos
= 0; px_pos
< px_len
; px_pos
+= channels
) {
528 else if (p
< chunks_len
) {
531 if ((b1
& QOI_MASK_2
) == QOI_INDEX
) {
532 px
= index
[b1
^ QOI_INDEX
];
534 else if ((b1
& QOI_MASK_3
) == QOI_RUN_8
) {
537 else if ((b1
& QOI_MASK_3
) == QOI_RUN_16
) {
539 run
= (((b1
& 0x1f) << 8) | (b2
)) + 32;
541 else if ((b1
& QOI_MASK_2
) == QOI_DIFF_8
) {
542 px
.rgba
.r
+= ((b1
>> 4) & 0x03) - 2;
543 px
.rgba
.g
+= ((b1
>> 2) & 0x03) - 2;
544 px
.rgba
.b
+= ( b1
& 0x03) - 2;
546 else if ((b1
& QOI_MASK_3
) == QOI_DIFF_16
) {
548 px
.rgba
.r
+= (b1
& 0x1f) - 16;
549 px
.rgba
.g
+= (b2
>> 4) - 8;
550 px
.rgba
.b
+= (b2
& 0x0f) - 8;
552 else if ((b1
& QOI_MASK_4
) == QOI_DIFF_24
) {
555 px
.rgba
.r
+= (((b1
& 0x0f) << 1) | (b2
>> 7)) - 16;
556 px
.rgba
.g
+= ((b2
& 0x7c) >> 2) - 16;
557 px
.rgba
.b
+= (((b2
& 0x03) << 3) | ((b3
& 0xe0) >> 5)) - 16;
558 px
.rgba
.a
+= (b3
& 0x1f) - 16;
560 else if ((b1
& QOI_MASK_4
) == QOI_COLOR
) {
561 if (b1
& 8) { px
.rgba
.r
= bytes
[p
++]; }
562 if (b1
& 4) { px
.rgba
.g
= bytes
[p
++]; }
563 if (b1
& 2) { px
.rgba
.b
= bytes
[p
++]; }
564 if (b1
& 1) { px
.rgba
.a
= bytes
[p
++]; }
567 index
[QOI_COLOR_HASH(px
) % 64] = px
;
571 *(qoi_rgba_t
*)(pixels
+ px_pos
) = px
;
574 pixels
[px_pos
] = px
.rgba
.r
;
575 pixels
[px_pos
+1] = px
.rgba
.g
;
576 pixels
[px_pos
+2] = px
.rgba
.b
;
586 int qoi_write(const char *filename
, const void *data
, const qoi_desc
*desc
) {
587 FILE *f
= fopen(filename
, "wb");
593 void *encoded
= qoi_encode(data
, desc
, &size
);
599 fwrite(encoded
, 1, size
, f
);
606 void *qoi_read(const char *filename
, qoi_desc
*desc
, int channels
) {
607 FILE *f
= fopen(filename
, "rb");
612 fseek(f
, 0, SEEK_END
);
614 fseek(f
, 0, SEEK_SET
);
616 void *data
= QOI_MALLOC(size
);
622 int bytes_read
= fread(data
, 1, size
, f
);
625 void *pixels
= qoi_decode(data
, bytes_read
, desc
, channels
);
630 #endif // QOI_NO_STDIO
631 #endif // QOI_IMPLEMENTATION