0/*
2Copyright (c) 2021, Dominic Szablewski - https://phoboslab.org
3SPDX-License-Identifier: MIT
6QOI - The "Quite OK Image" format for fast, lossless image compression
8-- About
10QOI encodes and decodes images in a lossless format. Compared to stb_image and
11stb_image_write QOI offers 20x-50x faster encoding, 3x-4x faster decoding and
1220% better compression.
15-- Synopsis
17// Define `QOI_IMPLEMENTATION` in *one* C/C++ file before including this
18// library to create the implementation.
20#define QOI_IMPLEMENTATION
21#include "qoi.h"
23// Encode and store an RGBA buffer to the file system. The qoi_desc describes
24// the input pixel data.
25qoi_write("image_new.qoi", rgba_pixels, &(qoi_desc){
26 .width = 1920,
27 .height = 1080,
28 .channels = 4,
29 .colorspace = QOI_SRGB
30});
32// Load and decode a QOI image from the file system into a 32bbp RGBA buffer.
33// The qoi_desc struct will be filled with the width, height, number of channels
34// and colorspace read from the file header.
35qoi_desc desc;
36void *rgba_pixels = qoi_read("image.qoi", &desc, 4);
40-- Documentation
42This library provides the following functions;
43- qoi_read -- read and decode a QOI file
44- qoi_decode -- decode the raw bytes of a QOI image from memory
45- qoi_write -- encode and write a QOI file
46- qoi_encode -- encode an rgba buffer into a QOI image in memory
48See the function declaration below for the signature and more information.
50If you don't want/need the qoi_read and qoi_write functions, you can define
51QOI_NO_STDIO before including this library.
53This library uses malloc() and free(). To supply your own malloc implementation
54you can define QOI_MALLOC and QOI_FREE before including this library.
56This library uses memset() to zero-initialize the index. To supply your own
57implementation you can define QOI_ZEROARR before including this library.
60-- Data Format
62A QOI file has a 14 byte header, followed by any number of data "chunks" and an
638-byte end marker.
65struct qoi_header_t {
66 char magic[4]; // magic bytes "qoif"
67 uint32_t width; // image width in pixels (BE)
68 uint32_t height; // image height in pixels (BE)
69 uint8_t channels; // 3 = RGB, 4 = RGBA
70 uint8_t colorspace; // 0 = sRGB with linear alpha, 1 = all channels linear
71};
73Images are encoded row by row, left to right, top to bottom. The decoder and
74encoder start with {r: 0, g: 0, b: 0, a: 255} as the previous pixel value. An
75image is complete when all pixels specified by width * height have been covered.
77Pixels are encoded as
78 - a run of the previous pixel
79 - an index into an array of previously seen pixels
80 - a difference to the previous pixel value in r,g,b
81 - full r,g,b or r,g,b,a values
83The color channels are assumed to not be premultiplied with the alpha channel
84("un-premultiplied alpha").
86A running array[64] (zero-initialized) of previously seen pixel values is
87maintained by the encoder and decoder. Each pixel that is seen by the encoder
88and decoder is put into this array at the position formed by a hash function of
89the color value. In the encoder, if the pixel value at the index matches the
90current pixel, this index position is written to the stream as QOI_OP_INDEX.
91The hash function for the index is:
93 index_position = (r * 3 + g * 5 + b * 7 + a * 11) % 64
95Each chunk starts with a 2- or 8-bit tag, followed by a number of data bits. The
96bit length of chunks is divisible by 8 - i.e. all chunks are byte aligned. All
97values encoded in these data bits have the most significant bit on the left.
99The 8-bit tags have precedence over the 2-bit tags. A decoder must check for the
100presence of an 8-bit tag first.
102The byte stream's end is marked with 7 0x00 bytes followed a single 0x01 byte.
105The possible chunks are:
108.- QOI_OP_INDEX ----------.
109| Byte[0] |
110| 7 6 5 4 3 2 1 0 |
111|-------+-----------------|
112| 0 0 | index |
113`-------------------------`
1142-bit tag b00
1156-bit index into the color index array: 0..63
117A valid encoder must not issue 2 or more consecutive QOI_OP_INDEX chunks to the
118same index. QOI_OP_RUN should be used instead.
121.- QOI_OP_DIFF -----------.
122| Byte[0] |
123| 7 6 5 4 3 2 1 0 |
124|-------+-----+-----+-----|
125| 0 1 | dr | dg | db |
126`-------------------------`
1272-bit tag b01
1282-bit red channel difference from the previous pixel between -2..1
1292-bit green channel difference from the previous pixel between -2..1
1302-bit blue channel difference from the previous pixel between -2..1
132The difference to the current channel values are using a wraparound operation,
133so "1 - 2" will result in 255, while "255 + 1" will result in 0.
135Values are stored as unsigned integers with a bias of 2. E.g. -2 is stored as
1360 (b00). 1 is stored as 3 (b11).
138The alpha value remains unchanged from the previous pixel.
141.- QOI_OP_LUMA -------------------------------------.
142| Byte[0] | Byte[1] |
143| 7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0 |
144|-------+-----------------+-------------+-----------|
145| 1 0 | green diff | dr - dg | db - dg |
146`---------------------------------------------------`
1472-bit tag b10
1486-bit green channel difference from the previous pixel -32..31
1494-bit red channel difference minus green channel difference -8..7
1504-bit blue channel difference minus green channel difference -8..7
152The green channel is used to indicate the general direction of change and is
153encoded in 6 bits. The red and blue channels (dr and db) base their diffs off
154of the green channel difference and are encoded in 4 bits. I.e.:
155 dr_dg = (cur_px.r - prev_px.r) - (cur_px.g - prev_px.g)
156 db_dg = (cur_px.b - prev_px.b) - (cur_px.g - prev_px.g)
158The difference to the current channel values are using a wraparound operation,
159so "10 - 13" will result in 253, while "250 + 7" will result in 1.
161Values are stored as unsigned integers with a bias of 32 for the green channel
162and a bias of 8 for the red and blue channel.
164The alpha value remains unchanged from the previous pixel.
167.- QOI_OP_RUN ------------.
168| Byte[0] |
169| 7 6 5 4 3 2 1 0 |
170|-------+-----------------|
171| 1 1 | run |
172`-------------------------`
1732-bit tag b11
1746-bit run-length repeating the previous pixel: 1..62
176The run-length is stored with a bias of -1. Note that the run-lengths 63 and 64
177(b111110 and b111111) are illegal as they are occupied by the QOI_OP_RGB and
178QOI_OP_RGBA tags.
181.- QOI_OP_RGB ------------------------------------------.
182| Byte[0] | Byte[1] | Byte[2] | Byte[3] |
183| 7 6 5 4 3 2 1 0 | 7 .. 0 | 7 .. 0 | 7 .. 0 |
184|-------------------------+---------+---------+---------|
185| 1 1 1 1 1 1 1 0 | red | green | blue |
186`-------------------------------------------------------`
1878-bit tag b11111110
1888-bit red channel value
1898-bit green channel value
1908-bit blue channel value
192The alpha value remains unchanged from the previous pixel.
195.- QOI_OP_RGBA ---------------------------------------------------.
196| Byte[0] | Byte[1] | Byte[2] | Byte[3] | Byte[4] |
197| 7 6 5 4 3 2 1 0 | 7 .. 0 | 7 .. 0 | 7 .. 0 | 7 .. 0 |
198|-------------------------+---------+---------+---------+---------|
199| 1 1 1 1 1 1 1 1 | red | green | blue | alpha |
200`-----------------------------------------------------------------`
2018-bit tag b11111111
2028-bit red channel value
2038-bit green channel value
2048-bit blue channel value
2058-bit alpha channel value
207*/
210/* -----------------------------------------------------------------------------
211Header - Public functions */
213#ifndef QOI_H
214#define QOI_H
216#ifdef __cplusplus
217extern "C" {
218#endif
220/* A pointer to a qoi_desc struct has to be supplied to all of qoi's functions.
221It describes either the input format (for qoi_write and qoi_encode), or is
222filled with the description read from the file header (for qoi_read and
223qoi_decode).
225The colorspace in this qoi_desc is an enum where
226 0 = sRGB, i.e. gamma scaled RGB channels and a linear alpha channel
227 1 = all channels are linear
228You may use the constants QOI_SRGB or QOI_LINEAR. The colorspace is purely
229informative. It will be saved to the file header, but does not affect
230how chunks are en-/decoded. */
232#define QOI_SRGB 0
233#define QOI_LINEAR 1
235typedef struct {
236 unsigned int width;
237 unsigned int height;
238 unsigned char channels;
239 unsigned char colorspace;
240} qoi_desc;
242#ifndef QOI_NO_STDIO
244/* Encode raw RGB or RGBA pixels into a QOI image and write it to the file
245system. The qoi_desc struct must be filled with the image width, height,
246number of channels (3 = RGB, 4 = RGBA) and the colorspace.
248The function returns 0 on failure (invalid parameters, or fopen or malloc
249failed) or the number of bytes written on success. */
251int qoi_write(const char *filename, const void *data, const qoi_desc *desc);
254/* Read and decode a QOI image from the file system. If channels is 0, the
255number of channels from the file header is used. If channels is 3 or 4 the
256output format will be forced into this number of channels.
258The function either returns NULL on failure (invalid data, or malloc or fopen
259failed) or a pointer to the decoded pixels. On success, the qoi_desc struct
260will be filled with the description from the file header.
262The returned pixel data should be free()d after use. */
264void *qoi_read(const char *filename, qoi_desc *desc, int channels);
266#endif /* QOI_NO_STDIO */
269/* Encode raw RGB or RGBA pixels into a QOI image in memory.
271The function either returns NULL on failure (invalid parameters or malloc
272failed) or a pointer to the encoded data on success. On success the out_len
273is set to the size in bytes of the encoded data.
275The returned qoi data should be free()d after use. */
277void *qoi_encode(const void *data, const qoi_desc *desc, int *out_len);
280/* Decode a QOI image from memory.
282The function either returns NULL on failure (invalid parameters or malloc
283failed) or a pointer to the decoded pixels. On success, the qoi_desc struct
284is filled with the description from the file header.
286The returned pixel data should be free()d after use. */
288void *qoi_decode(const void *data, int size, qoi_desc *desc, int channels);
291#ifdef __cplusplus
292}
293#endif
294#endif /* QOI_H */
297/* -----------------------------------------------------------------------------
298Implementation */
300#ifdef QOI_IMPLEMENTATION
301#include <stdlib.h>
302#include <string.h>
304#ifndef QOI_MALLOC
305 #define QOI_MALLOC(sz) malloc(sz)
306 #define QOI_FREE(p) free(p)
307#endif
308#ifndef QOI_ZEROARR
309 #define QOI_ZEROARR(a) memset((a),0,sizeof(a))
310#endif
312#define QOI_OP_INDEX 0x00 /* 00xxxxxx */
313#define QOI_OP_DIFF 0x40 /* 01xxxxxx */
314#define QOI_OP_LUMA 0x80 /* 10xxxxxx */
315#define QOI_OP_RUN 0xc0 /* 11xxxxxx */
316#define QOI_OP_RGB 0xfe /* 11111110 */
317#define QOI_OP_RGBA 0xff /* 11111111 */
319#define QOI_MASK_2 0xc0 /* 11000000 */
321#define QOI_COLOR_HASH(C) (C.rgba.r*3 + C.rgba.g*5 + C.rgba.b*7 + C.rgba.a*11)
322#define QOI_MAGIC \
323 (((unsigned int)'q') << 24 | ((unsigned int)'o') << 16 | \
324 ((unsigned int)'i') << 8 | ((unsigned int)'f'))
325#define QOI_HEADER_SIZE 14
327/* 2GB is the max file size that this implementation can safely handle. We guard
328against anything larger than that, assuming the worst case with 5 bytes per
329pixel, rounded down to a nice clean value. 400 million pixels ought to be
330enough for anybody. */
331#define QOI_PIXELS_MAX ((unsigned int)400000000)
333typedef union {
334 struct { unsigned char r, g, b, a; } rgba;
335 unsigned int v;
336} qoi_rgba_t;
338static const unsigned char qoi_padding[8] = {0,0,0,0,0,0,0,1};
340static void qoi_write_32(unsigned char *bytes, int *p, unsigned int v) {
341 bytes[(*p)++] = (0xff000000 & v) >> 24;
342 bytes[(*p)++] = (0x00ff0000 & v) >> 16;
343 bytes[(*p)++] = (0x0000ff00 & v) >> 8;
344 bytes[(*p)++] = (0x000000ff & v);
345}
347static unsigned int qoi_read_32(const unsigned char *bytes, int *p) {
348 unsigned int a = bytes[(*p)++];
349 unsigned int b = bytes[(*p)++];
350 unsigned int c = bytes[(*p)++];
351 unsigned int d = bytes[(*p)++];
352 return a << 24 | b << 16 | c << 8 | d;
353}
355void *qoi_encode(const void *data, const qoi_desc *desc, int *out_len) {
356 int i, max_size, p, run;
357 int px_len, px_end, px_pos, channels;
358 unsigned char *bytes;
359 const unsigned char *pixels;
360 qoi_rgba_t index[64];
361 qoi_rgba_t px, px_prev;
363 if (
364 data == NULL || out_len == NULL || desc == NULL ||
365 desc->width == 0 || desc->height == 0 ||
366 desc->channels < 3 || desc->channels > 4 ||
367 desc->colorspace > 1 ||
368 desc->height >= QOI_PIXELS_MAX / desc->width
369 ) {
370 return NULL;
371 }
373 max_size =
374 desc->width * desc->height * (desc->channels + 1) +
375 QOI_HEADER_SIZE + sizeof(qoi_padding);
377 p = 0;
378 bytes = (unsigned char *) QOI_MALLOC(max_size);
379 if (!bytes) {
380 return NULL;
381 }
383 qoi_write_32(bytes, &p, QOI_MAGIC);
384 qoi_write_32(bytes, &p, desc->width);
385 qoi_write_32(bytes, &p, desc->height);
386 bytes[p++] = desc->channels;
387 bytes[p++] = desc->colorspace;
390 pixels = (const unsigned char *)data;
392 QOI_ZEROARR(index);
394 run = 0;
395 px_prev.rgba.r = 0;
396 px_prev.rgba.g = 0;
397 px_prev.rgba.b = 0;
398 px_prev.rgba.a = 255;
399 px = px_prev;
401 px_len = desc->width * desc->height * desc->channels;
402 px_end = px_len - desc->channels;
403 channels = desc->channels;
405 for (px_pos = 0; px_pos < px_len; px_pos += channels) {
406 px.rgba.r = pixels[px_pos + 0];
407 px.rgba.g = pixels[px_pos + 1];
408 px.rgba.b = pixels[px_pos + 2];
410 if (channels == 4) {
411 px.rgba.a = pixels[px_pos + 3];
412 }
414 if (px.v == px_prev.v) {
415 run++;
416 if (run == 62 || px_pos == px_end) {
417 bytes[p++] = QOI_OP_RUN | (run - 1);
418 run = 0;
419 }
420 }
421 else {
422 int index_pos;
424 if (run > 0) {
425 bytes[p++] = QOI_OP_RUN | (run - 1);
426 run = 0;
427 }
429 index_pos = QOI_COLOR_HASH(px) % 64;
431 if (index[index_pos].v == px.v) {
432 bytes[p++] = QOI_OP_INDEX | index_pos;
433 }
434 else {
435 index[index_pos] = px;
437 if (px.rgba.a == px_prev.rgba.a) {
438 signed char vr = px.rgba.r - px_prev.rgba.r;
439 signed char vg = px.rgba.g - px_prev.rgba.g;
440 signed char vb = px.rgba.b - px_prev.rgba.b;
442 signed char vg_r = vr - vg;
443 signed char vg_b = vb - vg;
445 if (
446 vr > -3 && vr < 2 &&
447 vg > -3 && vg < 2 &&
448 vb > -3 && vb < 2
449 ) {
450 bytes[p++] = QOI_OP_DIFF | (vr + 2) << 4 | (vg + 2) << 2 | (vb + 2);
451 }
452 else if (
453 vg_r > -9 && vg_r < 8 &&
454 vg > -33 && vg < 32 &&
455 vg_b > -9 && vg_b < 8
456 ) {
457 bytes[p++] = QOI_OP_LUMA | (vg + 32);
458 bytes[p++] = (vg_r + 8) << 4 | (vg_b + 8);
459 }
460 else {
461 bytes[p++] = QOI_OP_RGB;
462 bytes[p++] = px.rgba.r;
463 bytes[p++] = px.rgba.g;
464 bytes[p++] = px.rgba.b;
465 }
466 }
467 else {
468 bytes[p++] = QOI_OP_RGBA;
469 bytes[p++] = px.rgba.r;
470 bytes[p++] = px.rgba.g;
471 bytes[p++] = px.rgba.b;
472 bytes[p++] = px.rgba.a;
473 }
474 }
475 }
476 px_prev = px;
477 }
479 for (i = 0; i < (int)sizeof(qoi_padding); i++) {
480 bytes[p++] = qoi_padding[i];
481 }
483 *out_len = p;
484 return bytes;
485}
487void *qoi_decode(const void *data, int size, qoi_desc *desc, int channels) {
488 const unsigned char *bytes;
489 unsigned int header_magic;
490 unsigned char *pixels;
491 qoi_rgba_t index[64];
492 qoi_rgba_t px;
493 int px_len, chunks_len, px_pos;
494 int p = 0, run = 0;
496 if (
497 data == NULL || desc == NULL ||
498 (channels != 0 && channels != 3 && channels != 4) ||
499 size < QOI_HEADER_SIZE + (int)sizeof(qoi_padding)
500 ) {
501 return NULL;
502 }
504 bytes = (const unsigned char *)data;
506 header_magic = qoi_read_32(bytes, &p);
507 desc->width = qoi_read_32(bytes, &p);
508 desc->height = qoi_read_32(bytes, &p);
509 desc->channels = bytes[p++];
510 desc->colorspace = bytes[p++];
512 if (
513 desc->width == 0 || desc->height == 0 ||
514 desc->channels < 3 || desc->channels > 4 ||
515 desc->colorspace > 1 ||
516 header_magic != QOI_MAGIC ||
517 desc->height >= QOI_PIXELS_MAX / desc->width
518 ) {
519 return NULL;
520 }
522 if (channels == 0) {
523 channels = desc->channels;
524 }
526 px_len = desc->width * desc->height * channels;
527 pixels = (unsigned char *) QOI_MALLOC(px_len);
528 if (!pixels) {
529 return NULL;
530 }
532 QOI_ZEROARR(index);
533 px.rgba.r = 0;
534 px.rgba.g = 0;
535 px.rgba.b = 0;
536 px.rgba.a = 255;
538 chunks_len = size - (int)sizeof(qoi_padding);
539 for (px_pos = 0; px_pos < px_len; px_pos += channels) {
540 if (run > 0) {
541 run--;
542 }
543 else if (p < chunks_len) {
544 int b1 = bytes[p++];
546 if (b1 == QOI_OP_RGB) {
547 px.rgba.r = bytes[p++];
548 px.rgba.g = bytes[p++];
549 px.rgba.b = bytes[p++];
550 }
551 else if (b1 == QOI_OP_RGBA) {
552 px.rgba.r = bytes[p++];
553 px.rgba.g = bytes[p++];
554 px.rgba.b = bytes[p++];
555 px.rgba.a = bytes[p++];
556 }
557 else if ((b1 & QOI_MASK_2) == QOI_OP_INDEX) {
558 px = index[b1];
559 }
560 else if ((b1 & QOI_MASK_2) == QOI_OP_DIFF) {
561 px.rgba.r += ((b1 >> 4) & 0x03) - 2;
562 px.rgba.g += ((b1 >> 2) & 0x03) - 2;
563 px.rgba.b += ( b1 & 0x03) - 2;
564 }
565 else if ((b1 & QOI_MASK_2) == QOI_OP_LUMA) {
566 int b2 = bytes[p++];
567 int vg = (b1 & 0x3f) - 32;
568 px.rgba.r += vg - 8 + ((b2 >> 4) & 0x0f);
569 px.rgba.g += vg;
570 px.rgba.b += vg - 8 + (b2 & 0x0f);
571 }
572 else if ((b1 & QOI_MASK_2) == QOI_OP_RUN) {
573 run = (b1 & 0x3f);
574 }
576 index[QOI_COLOR_HASH(px) % 64] = px;
577 }
579 pixels[px_pos + 0] = px.rgba.r;
580 pixels[px_pos + 1] = px.rgba.g;
581 pixels[px_pos + 2] = px.rgba.b;
583 if (channels == 4) {
584 pixels[px_pos + 3] = px.rgba.a;
585 }
586 }
588 return pixels;
589}
591#ifndef QOI_NO_STDIO
592#include <stdio.h>
594int qoi_write(const char *filename, const void *data, const qoi_desc *desc) {
595 FILE *f = fopen(filename, "wb");
596 int size, err;
597 void *encoded;
599 if (!f) {
600 return 0;
601 }
603 encoded = qoi_encode(data, desc, &size);
604 if (!encoded) {
605 fclose(f);
606 return 0;
607 }
609 fwrite(encoded, 1, size, f);
610 fflush(f);
611 err = ferror(f);
612 fclose(f);
614 QOI_FREE(encoded);
615 return err ? 0 : size;
616}
618void *qoi_read(const char *filename, qoi_desc *desc, int channels) {
619 FILE *f = fopen(filename, "rb");
620 int size, bytes_read;
621 void *pixels, *data;
623 if (!f) {
624 return NULL;
625 }
627 fseek(f, 0, SEEK_END);
628 size = ftell(f);
629 if (size <= 0 || fseek(f, 0, SEEK_SET) != 0) {
630 fclose(f);
631 return NULL;
632 }
634 data = QOI_MALLOC(size);
635 if (!data) {
636 fclose(f);
637 return NULL;
638 }
640 bytes_read = fread(data, 1, size, f);
641 fclose(f);
642 pixels = (bytes_read != size) ? NULL : qoi_decode(data, bytes_read, desc, channels);
643 QOI_FREE(data);
644 return pixels;
645}
647#endif /* QOI_NO_STDIO */
648#endif /* QOI_IMPLEMENTATION */
index : raylib-jai
Bindings from https://solarium.technology