🎉 Initial: QOI

.gitignore

···
+img-inspect
+img2ppm
+TestImages/*.ppm

LICENSE

···
+BSD 3-Clause License
+
+Copyright (c) 2025, qeaml
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

···
+# img
+
+A very small library for reading images.

build-img-inspect.sh

···
+#!/bin/sh
+
+cc img-inspect.c img.c -o img-inspect

build-img2ppm.sh

···
+#!/bin/sh
+
+cc img2ppm.c img.c -o img2ppm "$@"

img-inspect.c

···
+#include "img.h"
+#include <stdio.h>
+
+struct Ctx {
+  FILE *file;
+};
+
+static ImgStatus ctxRead(ImgAny user, ImgAny buf, ImgSz bufSz)
+{
+  struct Ctx *ctx = user;
+  if(fread(buf, bufSz, 1, ctx->file) != 1) {
+    return ImgErrIO;
+  }
+  return ImgOK;
+}
+
+static ImgStatus ctxSeek(ImgAny user, ImgOff off)
+{
+  struct Ctx *ctx = user;
+  fseek(ctx->file, off, SEEK_CUR);
+  return ImgOK;
+}
+
+static ImgStatus ctxClose(ImgAny user)
+{
+  struct Ctx *ctx = user;
+  fclose(ctx->file);
+  return ImgOK;
+}
+
+int main(int argc, char **argv)
+{
+  if(argc < 2) {
+    printf("Usage: %s <file>\n", argv[0]);
+    return 1;
+  }
+
+  FILE *file = fopen(argv[1], "rb");
+  if(file == NULL) {
+    perror("Could not open file");
+    return 1;
+  }
+
+  struct Ctx ctx;
+  ctx.file = file;
+  ImgFuncs funcs;
+  funcs.user = &ctx;
+  funcs.read = &ctxRead;
+  funcs.seek = &ctxSeek;
+  funcs.close = &ctxClose;
+
+  Img img;
+  ImgStatus status = imgOpen(&img, &funcs);
+  if(status != ImgOK) {
+    printf("Could not open image: %s\n", imgStatusMessage(status));
+    return 1;
+  }
+
+  printf(
+    "Detected %s\n"
+    "Size: %ux%u\n"
+    "Channel count: %u\n",
+    imgFormatName(img.format),
+    img.width, img.height,
+    img.channelCount);
+  status = imgClose(&img);
+  if(status != ImgOK) {
+    printf("Could not close image: %s\n", imgStatusMessage(status));
+    return 1;
+  }
+
+  return 0;
+}

img.c

···
+#include "img.h"
+
+static ImgStatus determineFormat(Img *img);
+static ImgStatus openQoi(Img *img);
+static ImgStatus readQoi(Img *img, ImgAny buf, ImgSz bufSz);
+
+ImgStatus imgOpen(Img *img, const ImgFuncs *funcs)
+{
+  img->funcs = *funcs;
+  ImgStatus status = determineFormat(img);
+  if(status != ImgOK) { return status; }
+  switch(img->format) {
+  case ImgFormatUnknown:
+    return ImgErrUnknownFormat;
+  case ImgFormatQoi:
+    return openQoi(img);
+  }
+}
+
+ImgStatus imgRead(Img *img, ImgAny buf, ImgSz bufSz)
+{
+  if(img->width == 0 || img->height == 0 || img->channelCount == 0) {
+    return ImgErrUnopened;
+  }
+  switch(img->format) {
+  case ImgFormatUnknown:
+    return ImgErrUnknownFormat;
+  case ImgFormatQoi:
+    return readQoi(img, buf, bufSz);
+  }
+}
+
+ImgStatus imgClose(Img *img)
+{
+  img->format = ImgFormatUnknown;
+  img->width = 0;
+  img->height = 0;
+  img->channelCount = 0;
+  if(img->funcs.close) {
+    return img->funcs.close(img->funcs.user);
+  }
+  return ImgOK;
+}
+
+const char *imgFormatName(ImgFormat format) {
+  switch(format) {
+  case ImgFormatUnknown:
+    return "Unknown";
+  case ImgFormatQoi:
+    return "QOI";
+  }
+}
+
+const char *imgStatusMessage(ImgStatus status) {
+  switch(status) {
+  case ImgOK:
+    return "OK";
+  case ImgErrIO:
+    return "I/O error";
+  case ImgErrUnknownFormat:
+    return "Unknown image format";
+  case ImgErrUnopened:
+    return "No image opened";
+  case ImgErrQoiInvalidChannelCount:
+    return "QOI: Invalid channel count";
+  case ImgErrQoiInvalidColorSpace:
+    return "QOI: Invalid color space";
+  case ImgErrQoiBufferTooSmall:
+    return "QOI: Buffer to small to decode into";
+  }
+}
+
+static ImgStatus read(Img *img, ImgAny buf, ImgSz bufSz)
+{
+  return img->funcs.read(img->funcs.user, buf, bufSz);
+}
+
+static ImgStatus readU32(Img *img, ImgU32 *out)
+{
+  return img->funcs.read(img->funcs.user, out, 4);
+}
+
+static ImgStatus readU32BE(Img *img, ImgU32 *out)
+{
+  ImgStatus status = img->funcs.read(img->funcs.user, out, 4);
+  if(status != ImgOK) { return status; }
+  #if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
+  *out = __builtin_bswap32(*out);
+  #endif
+  return ImgOK;
+}
+
+static ImgStatus seek(Img *img, ImgOff off)
+{
+  return img->funcs.seek(img->funcs.user, off);
+}
+
+static ImgStatus determineFormat(Img *img)
+{
+  ImgStatus status;
+  char magic[4];
+  status = read(img, magic, 4);
+  if(status != ImgOK) { return status; }
+  status = seek(img, -4);
+  if(status != ImgOK) { return status; }
+  if(magic[0] == 'q' && magic[1] == 'o' && magic[2] == 'i' && magic[3] == 'f') {
+    img->format = ImgFormatQoi;
+    return ImgOK;
+  }
+  return ImgErrUnknownFormat;
+}
+
+struct RGBAS {
+  ImgU8 r;
+  ImgU8 g;
+  ImgU8 b;
+  ImgU8 a;
+};
+
+typedef struct RGBAS RGBA;
+
+ImgStatus openQoi(Img *img)
+{
+  ImgStatus status = seek(img, 4);
+  if(status != ImgOK) { return status; }
+  status = readU32BE(img, &img->width);
+  if(status != ImgOK) { return status; }
+  status = readU32BE(img, &img->height);
+  if(status != ImgOK) { return status; }
+  status = read(img, &img->channelCount, 1);
+  if(status != ImgOK) { return status; }
+  ImgU8 colorSpace;
+  status = read(img, &colorSpace, 1);
+  if(status != ImgOK) { return status; }
+
+  if(img->channelCount != 3 && img->channelCount != 4) {
+    return ImgErrQoiInvalidChannelCount;
+  }
+  if(colorSpace != 0 && colorSpace != 1) {
+    return ImgErrQoiInvalidColorSpace;
+  }
+
+  return ImgOK;
+}
+
+static ImgU32 qoiIndex(RGBA color) {
+  return (color.r * 3 + color.g * 5 + color.b * 7 + color.a * 11) % 64;
+}
+
+/* FIXME: doesn't decode 4-chanel images correctly */
+ImgStatus readQoi(Img *img, ImgAny buf, ImgSz bufSz)
+{
+  ImgSz expectedSize = (ImgSz)img->width * img->height * img->channelCount;
+  if(bufSz < expectedSize) {
+    return ImgErrQoiBufferTooSmall;
+  }
+
+  RGBA memory[64];
+  for(ImgSz i = 0; i < 64; ++i) {
+    memory[i].r = 0;
+    memory[i].g = 0;
+    memory[i].b = 0;
+    memory[i].a = 0;
+  }
+  RGBA pixel;
+  pixel.r = 0;
+  pixel.g = 0;
+  pixel.b = 0;
+  pixel.a = 255;
+
+  ImgU8 *curr = buf;
+  ImgU8 *end = curr + bufSz;
+  ImgSz run = 0;
+  ImgU8 chunk;
+  ImgStatus status;
+  ImgS8 dr;
+  ImgS8 dg;
+  ImgS8 db;
+
+  while(curr < end) {
+    if(run > 0) {
+      --run;
+      *curr++ = pixel.r;
+      *curr++ = pixel.g;
+      *curr++ = pixel.b;
+      if(img->channelCount == 4) {
+        *curr++ = pixel.a;
+      }
+    }
+
+    status = read(img, &chunk, 1);
+    if(status != ImgOK) { return status; }
+
+    if(chunk == 0xFF) {
+      status = read(img, &pixel.r, 1);
+      if(status != ImgOK) { return status; }
+      status = read(img, &pixel.g, 1);
+      if(status != ImgOK) { return status; }
+      status = read(img, &pixel.b, 1);
+      if(status != ImgOK) { return status; }
+      status = read(img, &pixel.a, 1);
+      if(status != ImgOK) { return status; }
+    } else if(chunk == 0xFE) {
+      status = read(img, &pixel.r, 1);
+      if(status != ImgOK) { return status; }
+      status = read(img, &pixel.g, 1);
+      if(status != ImgOK) { return status; }
+      status = read(img, &pixel.b, 1);
+      if(status != ImgOK) { return status; }
+    } else if((chunk & 0xC0) == 0x00) {
+      pixel = memory[chunk];
+    } else if((chunk & 0xC0) == 0x40) {
+      dr = (ImgS8)((chunk & 0x30) >> 4) - 2;
+      dg = (ImgS8)((chunk & 0x0C) >> 2) - 2;
+      db = (ImgS8)(chunk & 0x03) - 2;
+      pixel.r += dr;
+      pixel.g += dg;
+      pixel.b += db;
+    } else if((chunk & 0xC0) == 0x80) {
+      dg = (ImgS8)(chunk & 0x3F) - 32;
+      status = read(img, &chunk, 1);
+      if(status != ImgOK) { return status; }
+      dr = (ImgS8)(chunk >> 4) - 8 + dg;
+      db = (ImgS8)(chunk & 0xF) - 8 + dg;
+      pixel.r += dr;
+      pixel.g += dg;
+      pixel.b += db;
+    } else if((chunk & 0xC0) == 0xC0) {
+      run = chunk & 0x3F;
+    }
+
+    memory[qoiIndex(pixel)] = pixel;
+    *curr++ = pixel.r;
+    *curr++ = pixel.g;
+    *curr++ = pixel.b;
+    if(img->channelCount == 4) {
+      *curr++ = pixel.a;
+    }
+  }
+
+  return ImgOK;
+}

img.h

···
+#pragma once
+
+typedef unsigned long int ImgSz;
+typedef signed long int ImgOff;
+typedef unsigned int ImgU32;
+typedef signed char ImgS8;
+typedef unsigned char ImgU8;
+typedef void *ImgAny;
+
+enum ImgStatusE {
+  ImgOK,
+  ImgErrIO,
+  ImgErrUnknownFormat,
+  ImgErrUnopened,
+  ImgErrQoiInvalidChannelCount,
+  ImgErrQoiInvalidColorSpace,
+  ImgErrQoiBufferTooSmall,
+};
+
+typedef enum ImgStatusE ImgStatus;
+
+typedef ImgStatus(*ImgReadFunc)(ImgAny user, ImgAny buf, ImgSz size);
+typedef ImgStatus(*ImgSeekFunc)(ImgAny user, ImgOff off);
+typedef ImgStatus(*ImgCloseFunc)(ImgAny user);
+
+struct ImgFuncsS {
+  ImgAny user;
+  ImgReadFunc read;
+  ImgSeekFunc seek;
+  ImgCloseFunc close;
+};
+
+typedef struct ImgFuncsS ImgFuncs;
+
+enum ImgFormatE {
+  ImgFormatUnknown,
+  ImgFormatQoi,
+};
+
+typedef enum ImgFormatE ImgFormat;
+
+struct ImgS {
+  ImgFormat format;
+  ImgU32 width;
+  ImgU32 height;
+  ImgU8 channelCount;
+  ImgFuncs funcs;
+};
+
+typedef struct ImgS Img;
+
+ImgStatus imgOpen(Img *img, const ImgFuncs *funcs);
+ImgStatus imgRead(Img *img, ImgAny buf, ImgSz bufSz);
+ImgStatus imgClose(Img *img);
+
+const char *imgFormatName(ImgFormat format);
+const char *imgStatusMessage(ImgStatus status);

img2ppm.c

···
+#include "img.h"
+#include <stdio.h>
+#include <stdlib.h>
+
+struct Ctx {
+  FILE *file;
+};
+
+static ImgStatus ctxRead(ImgAny user, ImgAny buf, ImgSz bufSz)
+{
+  struct Ctx *ctx = user;
+  if(fread(buf, bufSz, 1, ctx->file) != 1) {
+    return ImgErrIO;
+  }
+  return ImgOK;
+}
+
+static ImgStatus ctxSeek(ImgAny user, ImgOff off)
+{
+  struct Ctx *ctx = user;
+  fseek(ctx->file, off, SEEK_CUR);
+  return ImgOK;
+}
+
+static ImgStatus ctxClose(ImgAny user)
+{
+  struct Ctx *ctx = user;
+  fclose(ctx->file);
+  return ImgOK;
+}
+
+static void saveToPPM_RGB(const Img *img, const ImgU8 *pixels, const char *filename)
+{
+  FILE *file = fopen(filename, "wb");
+  if(file == NULL) {
+    perror("Could not open output file");
+    return;
+  }
+
+  fprintf(file, "P6\n%u %u\n255\n", img->width, img->height);
+  fwrite(pixels, 3, (ImgSz)img->width * img->height, file);
+  fclose(file);
+}
+
+static void saveToPPM_RGBA(const Img *img, const ImgU8 *pixels, const char *filename)
+{
+  FILE *file = fopen(filename, "wb");
+  if(file == NULL) {
+    perror("Could not open output file");
+    return;
+  }
+
+  fprintf(file, "P6\n%u %u\n255\n", img->width, img->height);
+  for(ImgSz i = 0; i < (ImgSz)img->width * img->height; ++i) {
+    fwrite(&pixels[i * 4], 1, 3, file);
+  }
+  fclose(file);
+}
+
+int main(int argc, char **argv)
+{
+  if(argc < 3) {
+    printf("Usage: %s <input file> <output PPM file>\n", argv[0]);
+    return 1;
+  }
+
+  FILE *file = fopen(argv[1], "rb");
+  if(file == NULL) {
+    perror("Could not open file");
+    return 1;
+  }
+
+  struct Ctx ctx;
+  ctx.file = file;
+  ImgFuncs funcs;
+  funcs.user = &ctx;
+  funcs.read = &ctxRead;
+  funcs.seek = &ctxSeek;
+  funcs.close = &ctxClose;
+
+  Img img;
+  ImgStatus status = imgOpen(&img, &funcs);
+  if(status != ImgOK) {
+    printf("Could not open image: %s\n", imgStatusMessage(status));
+    return 1;
+  }
+
+  printf(
+    "Detected %s\n"
+    "Size: %ux%u\n"
+    "Channel count: %u\n",
+    imgFormatName(img.format),
+    img.width, img.height,
+    img.channelCount);
+
+  ImgSz size = (ImgSz)img.width * img.height * img.channelCount;
+  ImgU8 *pixels = (ImgU8*)malloc(size);
+  status = imgRead(&img, pixels, size);
+  if(status != ImgOK) {
+    printf("Could not decode image: %s\n", imgStatusMessage(status));
+    // return 1;
+  }
+
+  if(img.channelCount == 3) {
+    saveToPPM_RGB(&img, pixels, argv[2]);
+  } else if(img.channelCount == 4) {
+    saveToPPM_RGBA(&img, pixels, argv[2]);
+  } else {
+    printf("Image must have 3 or 4 channels. Not converting.\n");
+  }
+
+  status = imgClose(&img);
+  if(status != ImgOK) {
+    printf("Could not close image: %s\n", imgStatusMessage(status));
+    return 1;
+  }
+
+  return 0;
+}