REVIEWED: Updated QOI to first official release

src/external/qoi.h

@@ -45,12 +45,21 @@ than stbi_image or libpng.
 #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
@@ -72,13 +81,17 @@ you can define QOI_MALLOC and QOI_FREE before including this library.
 
 -- 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
@@ -113,24 +126,24 @@ QOI_RUN_16 {
 
 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
+	u8 dr   :  2;   // 2-bit   red channel difference: -2..1
+	u8 dg   :  2;   // 2-bit green channel difference: -2..1
+	u8 db   :  2;   // 2-bit  blue channel difference: -2..1
 }
 
 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
+	u8 dr   :  5;   // 5-bit   red channel difference: -16..15
+	u8 dg   :  4;   // 4-bit green channel difference:  -8.. 7
+	u8 db   :  4;   // 4-bit  blue channel difference:  -8.. 7
 }
 
 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
+	u8 dr   :  5;   // 5-bit   red channel difference: -16..15
+	u8 dg   :  5;   // 5-bit green channel difference: -16..15
+	u8 db   :  5;   // 5-bit  blue channel difference: -16..15
+	u8 da   :  5;   // 5-bit alpha channel difference: -16..15
 }
 
 QOI_COLOR {
@@ -162,48 +175,75 @@ 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 into either raw RGB 
-// (channels=3) or RGBA (channels=4) pixel data.
+// 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.
+
 // 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);
+void *qoi_encode(const void *data, const qoi_desc *desc, int *out_len);
 
 
-// Decode a QOI image from memory into either raw RGB (channels=3) or RGBA 
-// (channels=4) pixel data.
+// Decode a QOI image from memory.
+
 // 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
 }
@@ -238,7 +278,7 @@ void *qoi_decode(const void *data, int size, int *out_w, int *out_h, int channel
 #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 {
@@ -246,39 +286,35 @@ 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) {
@@ -286,9 +322,11 @@ void *qoi_encode(const void *data, int w, int h, int channels, int *out_len) {
 	}
 
 	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;
 
@@ -297,11 +335,11 @@ void *qoi_encode(const void *data, int w, int h, int channels, int *out_len) {
 	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 = w * h * channels;
-	int px_end = px_len - channels;
-	for (int px_pos = 0; px_pos < px_len; px_pos += channels) {
-		if (channels == 4) {
+	
+	int px_len = desc->width * desc->height * desc->channels;
+	int px_end = px_len - desc->channels;
+	for (int px_pos = 0; px_pos < px_len; px_pos += desc->channels) {
+		if (desc->channels == 4) {
 			px = *(qoi_rgba_t *)(pixels + px_pos);
 		}
 		else {
@@ -342,26 +380,26 @@ void *qoi_encode(const void *data, int w, int h, int channels, int *out_len) {
 				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 {
@@ -380,35 +418,41 @@ void *qoi_encode(const void *data, int w, int h, int channels, int *out_len) {
 		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;
@@ -437,23 +481,23 @@ void *qoi_decode(const void *data, int size, int *out_w, int *out_h, int channel
 				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++]; }
@@ -475,17 +519,15 @@ void *qoi_decode(const void *data, int size, int *out_w, int *out_h, int channel
 		}
 	}
 
-	*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 qoi_write(const char *filename, const void *data, const qoi_desc *desc) {
 	int size;
-	void *encoded = qoi_encode(data, w, h, channels, &size);
+	void *encoded = qoi_encode(data, desc, &size);
 	if (!encoded) {
 		return 0;
 	}
@@ -502,7 +544,7 @@ int qoi_write(const char *filename, const void *data, int w, int h, int channels
 	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;
@@ -514,13 +556,14 @@ void *qoi_read(const char *filename, int *out_w, int *out_h, int channels) {
 
 	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;
 }

src/rtextures.c

@@ -375,7 +375,10 @@ Image LoadImageFromMemory(const char *fileType, const unsigned char *fileData, i
 #if defined(SUPPORT_FILEFORMAT_QOI)
     else if (TextIsEqual(fileExtLower, ".qoi")) 
     {
-        image.data = qoi_decode(fileData, dataSize, &image.width, &image.height, 4);
+        qoi_desc desc = { 0 };
+        image.data = qoi_decode(fileData, dataSize, &desc, 4);
+        image.width = desc.width;
+        image.height = desc.height;
         image.format = PIXELFORMAT_UNCOMPRESSED_R8G8B8A8;
         image.mipmaps = 1;
     }
@@ -505,7 +508,16 @@ bool ExportImage(Image image, const char *fileName)
         else if (image.format == PIXELFORMAT_UNCOMPRESSED_R8G8B8A8) channels = 4;
         else TRACELOG(LOG_WARNING, "IMAGE: Image pixel format must be R8G8B8 or R8G8B8A8");
         
-        if ((channels == 3) || (channels == 4)) success = qoi_write(fileName, imgData, image.width, image.height, channels);
+        if ((channels == 3) || (channels == 4))
+        {
+            qoi_desc desc = { 0 };
+            desc.width = image.width; 
+            desc.height = image.height;
+            desc.channels = channels;
+            desc.colorspace = QOI_SRGB;
+
+            success = qoi_write(fileName, imgData, &desc);
+        }
     }
 #endif
 #if defined(SUPPORT_FILEFORMAT_KTX)