From ba8e98a9f6fde36b5aef70e45dadd22238fc552f Mon Sep 17 00:00:00 2001 From: Anthony Merrill Date: Wed, 2 Nov 2022 17:32:58 +0000 Subject: [PATCH] Resolve KASM-2948 "Feature/ qoi support" --- .gitmodules | 2 +- common/rfb/CMakeLists.txt | 1 + common/rfb/ConnParams.cxx | 10 +- common/rfb/ConnParams.h | 1 + common/rfb/EncodeManager.cxx | 43 ++- common/rfb/ServerCore.cxx | 1 + common/rfb/TightConstants.h | 3 +- common/rfb/TightQOIEncoder.cxx | 274 +++++++++++++ common/rfb/TightQOIEncoder.h | 46 +++ common/rfb/encodings.h | 1 + common/rfb/qoi.h | 681 +++++++++++++++++++++++++++++++++ 11 files changed, 1054 insertions(+), 9 deletions(-) create mode 100644 common/rfb/TightQOIEncoder.cxx create mode 100644 common/rfb/TightQOIEncoder.h create mode 100644 common/rfb/qoi.h diff --git a/.gitmodules b/.gitmodules index e43a13a..9a0005f 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,4 +1,4 @@ [submodule "kasmweb"] path = kasmweb url = https://github.com/kasmtech/noVNC.git - branch = master + branch = qoi-rebase-2 diff --git a/common/rfb/CMakeLists.txt b/common/rfb/CMakeLists.txt index dea5f35..01ce5cb 100644 --- a/common/rfb/CMakeLists.txt +++ b/common/rfb/CMakeLists.txt @@ -59,6 +59,7 @@ set(RFB_SOURCES TightEncoder.cxx TightJPEGEncoder.cxx TightWEBPEncoder.cxx + TightQOIEncoder.cxx UpdateTracker.cxx VNCSConnectionST.cxx VNCServerST.cxx diff --git a/common/rfb/ConnParams.cxx b/common/rfb/ConnParams.cxx index 123b330..177ab73 100644 --- a/common/rfb/ConnParams.cxx +++ b/common/rfb/ConnParams.cxx @@ -42,7 +42,7 @@ ConnParams::ConnParams() supportsDesktopResize(false), supportsExtendedDesktopSize(false), supportsDesktopRename(false), supportsLastRect(false), supportsLEDState(false), supportsQEMUKeyEvent(false), - supportsWEBP(false), + supportsWEBP(false), supportsQOI(false), supportsSetDesktopSize(false), supportsFence(false), supportsContinuousUpdates(false), supportsExtendedClipboard(false), supportsUdp(false), @@ -132,6 +132,7 @@ void ConnParams::setEncodings(int nEncodings, const rdr::S32* encodings) supportsLastRect = false; supportsQEMUKeyEvent = false; supportsWEBP = false; + supportsQOI = false; compressLevel = -1; qualityLevel = -1; fineQualityLevel = -1; @@ -183,6 +184,9 @@ void ConnParams::setEncodings(int nEncodings, const rdr::S32* encodings) case pseudoEncodingWEBP: supportsWEBP = true; break; + case pseudoEncodingQOI: + supportsQOI = true; + break; case pseudoEncodingFence: supportsFence = true; break; @@ -277,6 +281,10 @@ void ConnParams::setEncodings(int nEncodings, const rdr::S32* encodings) if (encodings[i] > 0) encodings_.insert(encodings[i]); } + + // QOI-specific overrides + if (supportsQOI) + useCopyRect = false; } void ConnParams::setLEDState(unsigned int state) diff --git a/common/rfb/ConnParams.h b/common/rfb/ConnParams.h index 304a614..0f25055 100644 --- a/common/rfb/ConnParams.h +++ b/common/rfb/ConnParams.h @@ -111,6 +111,7 @@ namespace rfb { bool supportsLEDState; bool supportsQEMUKeyEvent; bool supportsWEBP; + bool supportsQOI; bool supportsSetDesktopSize; bool supportsFence; diff --git a/common/rfb/EncodeManager.cxx b/common/rfb/EncodeManager.cxx index c28de1c..47f770a 100644 --- a/common/rfb/EncodeManager.cxx +++ b/common/rfb/EncodeManager.cxx @@ -42,6 +42,7 @@ #include #include #include +#include using namespace rfb; @@ -70,6 +71,7 @@ enum EncoderClass { encoderTight, encoderTightJPEG, encoderTightWEBP, + encoderTightQOI, encoderZRLE, encoderClassMax, }; @@ -112,6 +114,8 @@ static const char *encoderClassName(EncoderClass klass) return "Tight (JPEG)"; case encoderTightWEBP: return "Tight (WEBP)"; + case encoderTightQOI: + return "Tight (QOI)"; case encoderZRLE: return "ZRLE"; case encoderClassMax: @@ -172,6 +176,7 @@ EncodeManager::EncodeManager(SConnection* conn_, EncCache *encCache_) : conn(con encoders[encoderTight] = new TightEncoder(conn); encoders[encoderTightJPEG] = new TightJPEGEncoder(conn); encoders[encoderTightWEBP] = new TightWEBPEncoder(conn); + encoders[encoderTightQOI] = new TightQOIEncoder(conn); encoders[encoderZRLE] = new ZRLEEncoder(conn); webpBenchResult = ((TightWEBPEncoder *) encoders[encoderTightWEBP])->benchmark(); @@ -414,7 +419,7 @@ void EncodeManager::doUpdate(bool allowLossy, const Region& changed_, * We start by searching for solid rects, which are then removed * from the changed region. */ - if (conn->cp.supportsLastRect) + if (conn->cp.supportsLastRect && !conn->cp.supportsQOI) writeSolidRects(&changed, pb); writeRects(changed, pb, @@ -451,7 +456,10 @@ void EncodeManager::prepareEncoders(bool allowLossy) bitmapRLE = indexedRLE = fullColour = encoderHextile; break; case encodingTight: - if (encoders[encoderTightWEBP]->isSupported() && + if (encoders[encoderTightQOI]->isSupported() && + (conn->cp.pf().bpp >= 16)) + fullColour = encoderTightQOI; + else if (encoders[encoderTightWEBP]->isSupported() && (conn->cp.pf().bpp >= 16) && allowLossy) fullColour = encoderTightWEBP; else if (encoders[encoderTightJPEG]->isSupported() && @@ -472,7 +480,10 @@ void EncodeManager::prepareEncoders(bool allowLossy) // Any encoders still unassigned? if (fullColour == encoderRaw) { - if (encoders[encoderTightWEBP]->isSupported() && + if (encoders[encoderTightQOI]->isSupported() && + (conn->cp.pf().bpp >= 16)) + fullColour = encoderTightQOI; + else if (encoders[encoderTightWEBP]->isSupported() && (conn->cp.pf().bpp >= 16) && allowLossy) fullColour = encoderTightWEBP; else if (encoders[encoderTightJPEG]->isSupported() && @@ -1221,7 +1232,7 @@ void EncodeManager::writeRects(const Region& changed, const PixelBuffer* pb, if (isWebp[i]) webpstats.ms += ms[i]; else - jpegstats.ms += ms[i]; + jpegstats.ms += ms[i]; // Also covers QOI for now } } @@ -1247,7 +1258,8 @@ void EncodeManager::writeRects(const Region& changed, const PixelBuffer* pb, activeEncoders[encoderFullColour] = encoderTightJPEG; for (i = 0; i < subrects.size(); ++i) { - if (encCache->enabled && compresseds[i].size() && !fromCache[i]) { + if (encCache->enabled && compresseds[i].size() && !fromCache[i] && + !encoders[encoderTightQOI]->isSupported()) { void *tmp = malloc(compresseds[i].size()); memcpy(tmp, &compresseds[i][0], compresseds[i].size()); encCache->add(isWebp[i] ? encoderTightWEBP : encoderTightJPEG, @@ -1314,7 +1326,7 @@ uint8_t EncodeManager::getEncoderType(const Rect& rect, const PixelBuffer *pb, type = encoderIndexed; } - if (scaledpb) + if (scaledpb || conn->cp.supportsQOI) type = encoderFullColour; *isWebp = 0; @@ -1349,6 +1361,21 @@ uint8_t EncodeManager::getEncoderType(const Rect& rect, const PixelBuffer *pb, compressed, videoDetected); *isWebp = 1; + } else if (activeEncoders[encoderFullColour] == encoderTightQOI) { + if (scaledpb) { + delete ppb; + ppb = preparePixelBuffer(scaledrect, scaledpb, + encoders[encoderTightQOI]->flags & EncoderUseNativePF ? + false : true); + } else if (encoders[encoderTightQOI]->flags & EncoderUseNativePF) { + delete ppb; + ppb = preparePixelBuffer(rect, pb, false); + } + + ((TightQOIEncoder *) encoders[encoderTightQOI])->compressOnly(ppb, + scaledQuality(rect), + compressed, + videoDetected); } else if (activeEncoders[encoderFullColour] == encoderTightJPEG || webpTookTooLong) { if (scaledpb) { delete ppb; @@ -1389,6 +1416,10 @@ void EncodeManager::writeSubRect(const Rect& rect, const PixelBuffer *pb, ((TightWEBPEncoder *) encoder)->writeOnly(compressed); webpstats.area += rect.area(); webpstats.rects++; + } else if (encoders[encoderTightQOI]->isSupported()) { + ((TightQOIEncoder *) encoder)->writeOnly(compressed); + jpegstats.area += rect.area(); // Also QOI for now + jpegstats.rects++; } else { ((TightJPEGEncoder *) encoder)->writeOnly(compressed); jpegstats.area += rect.area(); diff --git a/common/rfb/ServerCore.cxx b/common/rfb/ServerCore.cxx index eaffbe2..c95bca4 100644 --- a/common/rfb/ServerCore.cxx +++ b/common/rfb/ServerCore.cxx @@ -230,6 +230,7 @@ rfb::IntParameter rfb::Server::udpFullFrameFrequency ("udpFullFrameFrequency", "Send a full frame every N frames for clients using UDP. 0 to disable", 0, 0, 1000); + rfb::IntParameter rfb::Server::udpPort ("udpPort", "Which port to use for UDP. Default same as websocket", diff --git a/common/rfb/TightConstants.h b/common/rfb/TightConstants.h index 5ea1939..70f0ea2 100644 --- a/common/rfb/TightConstants.h +++ b/common/rfb/TightConstants.h @@ -24,7 +24,8 @@ namespace rfb { const unsigned int tightJpeg = 0x09; const unsigned int tightPng = 0x0a; const unsigned int tightWebp = 0x0b; - const unsigned int tightMaxSubencoding = 0x0b; + const unsigned int tightQoi = 0x0c; + const unsigned int tightMaxSubencoding = 0x0c; // Filters to improve compression efficiency const unsigned int tightFilterCopy = 0x00; diff --git a/common/rfb/TightQOIEncoder.cxx b/common/rfb/TightQOIEncoder.cxx new file mode 100644 index 0000000..c9c977d --- /dev/null +++ b/common/rfb/TightQOIEncoder.cxx @@ -0,0 +1,274 @@ +/* Copyright (C) 2019 Kasm Web + * + * This is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This software is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this software; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, + * USA. + */ +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#define QOI_IMPLEMENTATION +#define QOI_NO_STDIO +#include "qoi.h" + +using namespace rfb; +static LogWriter vlog("QOI"); + +static const PixelFormat pfRGBX(32, 24, false, true, 255, 255, 255, 0, 8, 16); +static const PixelFormat pfBGRX(32, 24, false, true, 255, 255, 255, 16, 8, 0); + +// An optimized version that assumes 4-alignment and RGBX/BGRX +static void *qoi_encode_kasm(const void *data, const qoi_desc *desc, int *out_len, + const unsigned isrgb, const unsigned stride) { + int i, max_size, p, run; + unsigned px_len, px_end, px_pos, y, x; + unsigned char *bytes; + const uint32_t *pixels; + qoi_rgba_t index[64]; + qoi_rgba_t px, px_prev; + + if ( + data == NULL || out_len == NULL || desc == NULL || + desc->width == 0 || desc->height == 0 || + desc->channels < 3 || desc->channels > 4 || + desc->colorspace > 1 || + desc->height >= QOI_PIXELS_MAX / desc->width + ) { + return NULL; + } + + max_size = + desc->width * desc->height * (3 + 1) + + QOI_HEADER_SIZE + sizeof(qoi_padding); + + p = 0; + bytes = (unsigned char *) QOI_MALLOC(max_size); + if (!bytes) { + return NULL; + } + + qoi_write_32(bytes, &p, QOI_MAGIC); + qoi_write_32(bytes, &p, desc->width); + qoi_write_32(bytes, &p, desc->height); + bytes[p++] = 3; + bytes[p++] = desc->colorspace; + + + pixels = (const uint32_t *)data; + + QOI_ZEROARR(index); + + run = 0; + px_prev.rgba.r = 0; + px_prev.rgba.g = 0; + px_prev.rgba.b = 0; + px_prev.rgba.a = 255; + px = px_prev; + + px_len = desc->width * desc->height; + px_end = px_len - 1; + + px_pos = 0; + for (y = 0; y < desc->height; y++) { + for (x = 0; x < desc->width; x++, px_pos++) { + const unsigned stridedpos = y * stride + x; + + px.v = pixels[stridedpos]; + if (!isrgb) { + uint8_t tmp = px.rgba.r; + px.rgba.r = px.rgba.b; + px.rgba.b = tmp; + } + + if (px.v == px_prev.v) { + run++; + if (run == 62 || px_pos == px_end) { + bytes[p++] = QOI_OP_RUN | (run - 1); + run = 0; + } + } else { + if (run > 0) { + bytes[p++] = QOI_OP_RUN | (run - 1); + run = 0; + } + + signed char vr = px.rgba.r - px_prev.rgba.r; + signed char vg = px.rgba.g - px_prev.rgba.g; + signed char vb = px.rgba.b - px_prev.rgba.b; + + signed char vg_r = vr - vg; + signed char vg_b = vb - vg; + + if ( + vr > -3 && vr < 2 && + vg > -3 && vg < 2 && + vb > -3 && vb < 2 + ) { + bytes[p++] = QOI_OP_DIFF | (vr + 2) << 4 | (vg + 2) << 2 | (vb + 2); + } else if ( + vg_r > -9 && vg_r < 8 && + vg > -33 && vg < 32 && + vg_b > -9 && vg_b < 8 + ) { + bytes[p++] = QOI_OP_LUMA | (vg + 32); + bytes[p++] = (vg_r + 8) << 4 | (vg_b + 8); + } else { + bytes[p++] = QOI_OP_RGB; + bytes[p++] = px.rgba.r; + bytes[p++] = px.rgba.g; + bytes[p++] = px.rgba.b; + } + } + px_prev = px; + } + } + + for (i = 0; i < (int)sizeof(qoi_padding); i++) { + bytes[p++] = qoi_padding[i]; + } + + *out_len = p; + return bytes; +} + +TightQOIEncoder::TightQOIEncoder(SConnection* conn) : + Encoder(conn, encodingTight, (EncoderFlags)(EncoderUseNativePF), -1) +{ +} + +TightQOIEncoder::~TightQOIEncoder() +{ +} + +bool TightQOIEncoder::isSupported() +{ + if (!conn->cp.supportsEncoding(encodingTight)) + return false; + + if (conn->cp.supportsQOI) + return true; + + // Tight support, but not QOI + return false; +} + +void TightQOIEncoder::compressOnly(const PixelBuffer* pb, const uint8_t qualityIn, + std::vector &out, const bool lowVideoQuality) const +{ + const rdr::U8* buffer; + int stride, len; + qoi_desc desc; + void *encoded; + + buffer = pb->getBuffer(pb->getRect(), &stride); + + desc.width = pb->getRect().width(); + desc.height = pb->getRect().height(); + desc.colorspace = QOI_LINEAR; + desc.channels = 4; + + encoded = qoi_encode_kasm(buffer, &desc, &len, pfRGBX.equal(pb->getPF()), stride); + + if (!encoded) { + // Error + vlog.error("QOI error"); + } + + out.resize(len); + memcpy(&out[0], encoded, len); + + free(encoded); +} + +void TightQOIEncoder::writeOnly(const std::vector &out) const +{ + rdr::OutStream* os; + + os = conn->getOutStream(); + + os->writeU8(tightQoi << 4); + + writeCompact(out.size(), os); + os->writeBytes(&out[0], out.size()); +} + +void TightQOIEncoder::writeRect(const PixelBuffer* pb, const Palette& palette) +{ + rdr::OutStream* os; + const rdr::U8* buffer; + int stride, len; + qoi_desc desc; + void *encoded; + + buffer = pb->getBuffer(pb->getRect(), &stride); + + desc.width = pb->getRect().width(); + desc.height = pb->getRect().height(); + desc.colorspace = QOI_LINEAR; + desc.channels = 4; + + encoded = qoi_encode_kasm(buffer, &desc, &len, pfRGBX.equal(pb->getPF()), stride); + + if (!encoded) { + // Error + vlog.error("QOI error"); + } + + os = conn->getOutStream(); + + os->writeU8(tightQoi << 4); + + writeCompact(len, os); + os->writeBytes(encoded, len); + + free(encoded); +} + +void TightQOIEncoder::writeSolidRect(int width, int height, + const PixelFormat& pf, + const rdr::U8* colour) +{ + // FIXME: Add a shortcut in the JPEG compressor to handle this case + // without having to use the default fallback which is very slow. + Encoder::writeSolidRect(width, height, pf, colour); +} + +void TightQOIEncoder::writeCompact(rdr::U32 value, rdr::OutStream* os) const +{ + // Copied from TightEncoder as it's overkill to inherit just for this + rdr::U8 b; + + b = value & 0x7F; + if (value <= 0x7F) { + os->writeU8(b); + } else { + os->writeU8(b | 0x80); + b = value >> 7 & 0x7F; + if (value <= 0x3FFF) { + os->writeU8(b); + } else { + os->writeU8(b | 0x80); + os->writeU8(value >> 14 & 0xFF); + } + } +} diff --git a/common/rfb/TightQOIEncoder.h b/common/rfb/TightQOIEncoder.h new file mode 100644 index 0000000..050d508 --- /dev/null +++ b/common/rfb/TightQOIEncoder.h @@ -0,0 +1,46 @@ +/* Copyright (C) 2022 Kasm Web + * + * This is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This software is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this software; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, + * USA. + */ +#ifndef __RFB_TIGHTQOIENCODER_H__ +#define __RFB_TIGHTQOIENCODER_H__ + +#include +#include +#include + +namespace rfb { + + class TightQOIEncoder : public Encoder { + public: + TightQOIEncoder(SConnection* conn); + virtual ~TightQOIEncoder(); + + virtual bool isSupported(); + + virtual void writeRect(const PixelBuffer* pb, const Palette& palette); + virtual void compressOnly(const PixelBuffer* pb, const uint8_t quality, + std::vector &out, const bool lowVideoQuality) const; + virtual void writeOnly(const std::vector &out) const; + virtual void writeSolidRect(int width, int height, + const PixelFormat& pf, + const rdr::U8* colour); + + protected: + void writeCompact(rdr::U32 value, rdr::OutStream* os) const; + }; +} +#endif diff --git a/common/rfb/encodings.h b/common/rfb/encodings.h index 6bb319f..dbc4dc7 100644 --- a/common/rfb/encodings.h +++ b/common/rfb/encodings.h @@ -85,6 +85,7 @@ namespace rfb { const int pseudoEncodingVideoScalingLevel9 = -1987; const int pseudoEncodingVideoOutTimeLevel1 = -1986; const int pseudoEncodingVideoOutTimeLevel100 = -1887; + const int pseudoEncodingQOI = -1886; // VMware-specific const int pseudoEncodingVMwareCursor = 0x574d5664; diff --git a/common/rfb/qoi.h b/common/rfb/qoi.h new file mode 100644 index 0000000..3998790 --- /dev/null +++ b/common/rfb/qoi.h @@ -0,0 +1,681 @@ +/* + +QOI - The "Quite OK Image" format for fast, lossless image compression + +Dominic Szablewski - https://phoboslab.org + + +-- LICENSE: The MIT License(MIT) + +Copyright(c) 2021 Dominic Szablewski + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files(the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and / or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions : +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + + +-- About + +QOI encodes and decodes images in a lossless format. Compared to stb_image and +stb_image_write QOI offers 20x-50x faster encoding, 3x-4x faster decoding and +20% better compression. + + +-- Synopsis + +// Define `QOI_IMPLEMENTATION` in *one* C/C++ file before including this +// library to create the implementation. + +#define QOI_IMPLEMENTATION +#include "qoi.h" + +// 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); + + + +-- Documentation + +This library provides the following functions; +- qoi_read -- read and decode a QOI file +- qoi_decode -- decode the raw bytes of a QOI image from memory +- qoi_write -- encode and write a QOI file +- qoi_encode -- encode an rgba buffer into a QOI image in memory + +See the function declaration below for the signature and more information. + +If you don't want/need the qoi_read and qoi_write functions, you can define +QOI_NO_STDIO before including this library. + +This library uses malloc() and free(). To supply your own malloc implementation +you can define QOI_MALLOC and QOI_FREE before including this library. + +This library uses memset() to zero-initialize the index. To supply your own +implementation you can define QOI_ZEROARR before including this library. + + +-- Data Format + +A QOI file has a 14 byte header, followed by any number of data "chunks" and an +8-byte end marker. + +struct qoi_header_t { + 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; // 3 = RGB, 4 = RGBA + uint8_t colorspace; // 0 = sRGB with linear alpha, 1 = all channels linear +}; + +Images are encoded row by row, left to right, top to bottom. The decoder and +encoder start with {r: 0, g: 0, b: 0, a: 255} as the previous pixel value. An +image is complete when all pixels specified by width * height have been covered. + +Pixels are encoded as + - a run of the previous pixel + - an index into an array of previously seen pixels + - a difference to the previous pixel value in r,g,b + - full r,g,b or r,g,b,a values + +The color channels are assumed to not be premultiplied with the alpha channel +("un-premultiplied alpha"). + +A running array[64] (zero-initialized) of previously seen pixel values is +maintained by the encoder and decoder. Each pixel that is seen by the encoder +and decoder is put into this array at the position formed by a hash function of +the color value. In the encoder, if the pixel value at the index matches the +current pixel, this index position is written to the stream as QOI_OP_INDEX. +The hash function for the index is: + + index_position = (r * 3 + g * 5 + b * 7 + a * 11) % 64 + +Each chunk starts with a 2- or 8-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 on the left. + +The 8-bit tags have precedence over the 2-bit tags. A decoder must check for the +presence of an 8-bit tag first. + +The byte stream's end is marked with 7 0x00 bytes followed a single 0x01 byte. + + +The possible chunks are: + + +.- QOI_OP_INDEX ----------. +| Byte[0] | +| 7 6 5 4 3 2 1 0 | +|-------+-----------------| +| 0 0 | index | +`-------------------------` +2-bit tag b00 +6-bit index into the color index array: 0..63 + +A valid encoder must not issue 2 or more consecutive QOI_OP_INDEX chunks to the +same index. QOI_OP_RUN should be used instead. + + +.- QOI_OP_DIFF -----------. +| Byte[0] | +| 7 6 5 4 3 2 1 0 | +|-------+-----+-----+-----| +| 0 1 | dr | dg | db | +`-------------------------` +2-bit tag b01 +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. + +Values are stored as unsigned integers with a bias of 2. E.g. -2 is stored as +0 (b00). 1 is stored as 3 (b11). + +The alpha value remains unchanged from the previous pixel. + + +.- QOI_OP_LUMA -------------------------------------. +| Byte[0] | Byte[1] | +| 7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0 | +|-------+-----------------+-------------+-----------| +| 1 0 | green diff | dr - dg | db - dg | +`---------------------------------------------------` +2-bit tag b10 +6-bit green channel difference from the previous pixel -32..31 +4-bit red channel difference minus green channel difference -8..7 +4-bit blue channel difference minus green channel difference -8..7 + +The green channel is used to indicate the general direction of change and is +encoded in 6 bits. The red and blue channels (dr and db) base their diffs off +of the green channel difference and are encoded in 4 bits. I.e.: + dr_dg = (cur_px.r - prev_px.r) - (cur_px.g - prev_px.g) + db_dg = (cur_px.b - prev_px.b) - (cur_px.g - prev_px.g) + +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. + +Values are stored as unsigned integers with a bias of 32 for the green channel +and a bias of 8 for the red and blue channel. + +The alpha value remains unchanged from the previous pixel. + + +.- QOI_OP_RUN ------------. +| Byte[0] | +| 7 6 5 4 3 2 1 0 | +|-------+-----------------| +| 1 1 | run | +`-------------------------` +2-bit tag b11 +6-bit run-length repeating the previous pixel: 1..62 + +The run-length is stored with a bias of -1. Note that the run-lengths 63 and 64 +(b111110 and b111111) are illegal as they are occupied by the QOI_OP_RGB and +QOI_OP_RGBA tags. + + +.- QOI_OP_RGB ------------------------------------------. +| Byte[0] | Byte[1] | Byte[2] | Byte[3] | +| 7 6 5 4 3 2 1 0 | 7 .. 0 | 7 .. 0 | 7 .. 0 | +|-------------------------+---------+---------+---------| +| 1 1 1 1 1 1 1 0 | red | green | blue | +`-------------------------------------------------------` +8-bit tag b11111110 +8-bit red channel value +8-bit green channel value +8-bit blue channel value + +The alpha value remains unchanged from the previous pixel. + + +.- QOI_OP_RGBA ---------------------------------------------------. +| Byte[0] | Byte[1] | Byte[2] | Byte[3] | Byte[4] | +| 7 6 5 4 3 2 1 0 | 7 .. 0 | 7 .. 0 | 7 .. 0 | 7 .. 0 | +|-------------------------+---------+---------+---------+---------| +| 1 1 1 1 1 1 1 1 | red | green | blue | alpha | +`-----------------------------------------------------------------` +8-bit tag b11111111 +8-bit red channel value +8-bit green channel value +8-bit blue channel value +8-bit alpha channel value + +*/ + + +/* ----------------------------------------------------------------------------- +Header - Public functions */ + +#ifndef QOI_H +#define QOI_H + +#ifdef __cplusplus +extern "C" { +#endif + +/* A pointer to a qoi_desc struct has to be supplied to all of qoi's functions. +It describes either the input format (for qoi_write and qoi_encode), or is +filled with the description read from the file header (for qoi_read and +qoi_decode). + +The colorspace in this qoi_desc is an enum where + 0 = sRGB, i.e. gamma scaled RGB channels and a linear alpha channel + 1 = all channels are linear +You may use the constants QOI_SRGB or QOI_LINEAR. The colorspace is purely +informative. It will be saved to the file header, but does not affect +how chunks are en-/decoded. */ + +#define QOI_SRGB 0 +#define QOI_LINEAR 1 + +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 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, 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. + +The function either returns NULL on failure (invalid data, or malloc or fopen +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, qoi_desc *desc, int channels); + +#endif /* QOI_NO_STDIO */ + + +/* 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 +is set to the size in bytes of the encoded data. + +The returned qoi data should be free()d after use. */ + +void *qoi_encode(const void *data, const qoi_desc *desc, int *out_len, + const unsigned isrgb, const unsigned stride); + + +/* 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, 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, qoi_desc *desc, int channels); + + +#ifdef __cplusplus +} +#endif +#endif /* QOI_H */ + + +/* ----------------------------------------------------------------------------- +Implementation */ + +#ifdef QOI_IMPLEMENTATION +#include +#include + +#ifndef QOI_MALLOC + #define QOI_MALLOC(sz) malloc(sz) + #define QOI_FREE(p) free(p) +#endif +#ifndef QOI_ZEROARR + #define QOI_ZEROARR(a) memset((a),0,sizeof(a)) +#endif + +#define QOI_OP_INDEX 0x00 /* 00xxxxxx */ +#define QOI_OP_DIFF 0x40 /* 01xxxxxx */ +#define QOI_OP_LUMA 0x80 /* 10xxxxxx */ +#define QOI_OP_RUN 0xc0 /* 11xxxxxx */ +#define QOI_OP_RGB 0xfe /* 11111110 */ +#define QOI_OP_RGBA 0xff /* 11111111 */ + +#define QOI_MASK_2 0xc0 /* 11000000 */ + +#define QOI_COLOR_HASH(C) (C.rgba.r*3 + C.rgba.g*5 + C.rgba.b*7 + C.rgba.a*11) +#define QOI_MAGIC \ + (((unsigned int)'q') << 24 | ((unsigned int)'o') << 16 | \ + ((unsigned int)'i') << 8 | ((unsigned int)'f')) +#define QOI_HEADER_SIZE 14 + +/* 2GB is the max file size that this implementation can safely handle. We guard +against anything larger than that, assuming the worst case with 5 bytes per +pixel, rounded down to a nice clean value. 400 million pixels ought to be +enough for anybody. */ +#define QOI_PIXELS_MAX ((unsigned int)400000000) + +typedef union { + struct { unsigned char r, g, b, a; } rgba; + unsigned int v; +} qoi_rgba_t; + +static const unsigned char qoi_padding[8] = {0,0,0,0,0,0,0,1}; + +static void qoi_write_32(unsigned char *bytes, int *p, unsigned int v) { + bytes[(*p)++] = (0xff000000 & v) >> 24; + bytes[(*p)++] = (0x00ff0000 & v) >> 16; + bytes[(*p)++] = (0x0000ff00 & v) >> 8; + bytes[(*p)++] = (0x000000ff & v); +} + +static unsigned int qoi_read_32(const unsigned char *bytes, int *p) { + unsigned int a = bytes[(*p)++]; + unsigned int b = bytes[(*p)++]; + unsigned int c = bytes[(*p)++]; + unsigned int d = bytes[(*p)++]; + return a << 24 | b << 16 | c << 8 | d; +} + +void *qoi_encode(const void *data, const qoi_desc *desc, int *out_len, const unsigned isrgb, + const unsigned stride) { + int i, max_size, p, run; + int px_len, px_end, px_pos, channels; + unsigned char *bytes; + const unsigned char *pixels; + qoi_rgba_t index[64]; + qoi_rgba_t px, px_prev; + + if ( + data == NULL || out_len == NULL || desc == NULL || + desc->width == 0 || desc->height == 0 || + desc->channels < 3 || desc->channels > 4 || + desc->colorspace > 1 || + desc->height >= QOI_PIXELS_MAX / desc->width + ) { + return NULL; + } + + max_size = + desc->width * desc->height * (desc->channels + 1) + + QOI_HEADER_SIZE + sizeof(qoi_padding); + + p = 0; + bytes = (unsigned char *) QOI_MALLOC(max_size); + if (!bytes) { + return NULL; + } + + qoi_write_32(bytes, &p, QOI_MAGIC); + qoi_write_32(bytes, &p, desc->width); + qoi_write_32(bytes, &p, desc->height); + bytes[p++] = desc->channels; + bytes[p++] = desc->colorspace; + + + pixels = (const unsigned char *)data; + + QOI_ZEROARR(index); + + run = 0; + px_prev.rgba.r = 0; + px_prev.rgba.g = 0; + px_prev.rgba.b = 0; + px_prev.rgba.a = 255; + px = px_prev; + + px_len = desc->width * desc->height * desc->channels; + px_end = px_len - desc->channels; + channels = desc->channels; + + for (px_pos = 0; px_pos < px_len; px_pos += channels) { + const unsigned y = (px_pos / channels) / desc->width; + const unsigned x = (px_pos / channels) % desc->width; + const unsigned stridedpos = y * stride + x * channels; + + if (isrgb) { + px.rgba.r = pixels[stridedpos + 0]; + px.rgba.g = pixels[stridedpos + 1]; + px.rgba.b = pixels[stridedpos + 2]; + } else { + px.rgba.b = pixels[stridedpos + 0]; + px.rgba.g = pixels[stridedpos + 1]; + px.rgba.r = pixels[stridedpos + 2]; + } + + if (channels == 4) { + px.rgba.a = pixels[stridedpos + 3]; + } + + if (px.v == px_prev.v) { + run++; + if (run == 62 || px_pos == px_end) { + bytes[p++] = QOI_OP_RUN | (run - 1); + run = 0; + } + } + else { + int index_pos; + + if (run > 0) { + bytes[p++] = QOI_OP_RUN | (run - 1); + run = 0; + } + + index_pos = QOI_COLOR_HASH(px) % 64; + + if (index[index_pos].v == px.v) { + bytes[p++] = QOI_OP_INDEX | index_pos; + } + else { + index[index_pos] = px; + + if (px.rgba.a == px_prev.rgba.a) { + signed char vr = px.rgba.r - px_prev.rgba.r; + signed char vg = px.rgba.g - px_prev.rgba.g; + signed char vb = px.rgba.b - px_prev.rgba.b; + + signed char vg_r = vr - vg; + signed char vg_b = vb - vg; + + if ( + vr > -3 && vr < 2 && + vg > -3 && vg < 2 && + vb > -3 && vb < 2 + ) { + bytes[p++] = QOI_OP_DIFF | (vr + 2) << 4 | (vg + 2) << 2 | (vb + 2); + } + else if ( + vg_r > -9 && vg_r < 8 && + vg > -33 && vg < 32 && + vg_b > -9 && vg_b < 8 + ) { + bytes[p++] = QOI_OP_LUMA | (vg + 32); + bytes[p++] = (vg_r + 8) << 4 | (vg_b + 8); + } + else { + bytes[p++] = QOI_OP_RGB; + bytes[p++] = px.rgba.r; + bytes[p++] = px.rgba.g; + bytes[p++] = px.rgba.b; + } + } + else { + bytes[p++] = QOI_OP_RGBA; + bytes[p++] = px.rgba.r; + bytes[p++] = px.rgba.g; + bytes[p++] = px.rgba.b; + bytes[p++] = px.rgba.a; + } + } + } + px_prev = px; + } + + for (i = 0; i < (int)sizeof(qoi_padding); i++) { + bytes[p++] = qoi_padding[i]; + } + + *out_len = p; + return bytes; +} + +void *qoi_decode(const void *data, int size, qoi_desc *desc, int channels) { + const unsigned char *bytes; + unsigned int header_magic; + unsigned char *pixels; + qoi_rgba_t index[64]; + qoi_rgba_t px; + int px_len, chunks_len, px_pos; + int p = 0, run = 0; + + if ( + data == NULL || desc == NULL || + (channels != 0 && channels != 3 && channels != 4) || + size < QOI_HEADER_SIZE + (int)sizeof(qoi_padding) + ) { + return NULL; + } + + bytes = (const unsigned char *)data; + + 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 ( + desc->width == 0 || desc->height == 0 || + desc->channels < 3 || desc->channels > 4 || + desc->colorspace > 1 || + header_magic != QOI_MAGIC || + desc->height >= QOI_PIXELS_MAX / desc->width + ) { + return NULL; + } + + if (channels == 0) { + channels = desc->channels; + } + + px_len = desc->width * desc->height * channels; + pixels = (unsigned char *) QOI_MALLOC(px_len); + if (!pixels) { + return NULL; + } + + QOI_ZEROARR(index); + px.rgba.r = 0; + px.rgba.g = 0; + px.rgba.b = 0; + px.rgba.a = 255; + + chunks_len = size - (int)sizeof(qoi_padding); + for (px_pos = 0; px_pos < px_len; px_pos += channels) { + if (run > 0) { + run--; + } + else if (p < chunks_len) { + int b1 = bytes[p++]; + + if (b1 == QOI_OP_RGB) { + px.rgba.r = bytes[p++]; + px.rgba.g = bytes[p++]; + px.rgba.b = bytes[p++]; + } + else if (b1 == QOI_OP_RGBA) { + px.rgba.r = bytes[p++]; + px.rgba.g = bytes[p++]; + px.rgba.b = bytes[p++]; + px.rgba.a = bytes[p++]; + } + else if ((b1 & QOI_MASK_2) == QOI_OP_INDEX) { + px = index[b1]; + } + else if ((b1 & QOI_MASK_2) == QOI_OP_DIFF) { + 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_2) == QOI_OP_LUMA) { + int b2 = bytes[p++]; + int vg = (b1 & 0x3f) - 32; + px.rgba.r += vg - 8 + ((b2 >> 4) & 0x0f); + px.rgba.g += vg; + px.rgba.b += vg - 8 + (b2 & 0x0f); + } + else if ((b1 & QOI_MASK_2) == QOI_OP_RUN) { + run = (b1 & 0x3f); + } + + index[QOI_COLOR_HASH(px) % 64] = px; + } + + pixels[px_pos + 0] = px.rgba.r; + pixels[px_pos + 1] = px.rgba.g; + pixels[px_pos + 2] = px.rgba.b; + + if (channels == 4) { + pixels[px_pos + 3] = px.rgba.a; + } + } + + return pixels; +} + +#ifndef QOI_NO_STDIO +#include + +int qoi_write(const char *filename, const void *data, const qoi_desc *desc) { + FILE *f = fopen(filename, "wb"); + int size; + void *encoded; + + if (!f) { + return 0; + } + + 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, qoi_desc *desc, int channels) { + FILE *f = fopen(filename, "rb"); + int size, bytes_read; + void *pixels, *data; + + if (!f) { + return NULL; + } + + fseek(f, 0, SEEK_END); + size = ftell(f); + if (size <= 0) { + fclose(f); + return NULL; + } + fseek(f, 0, SEEK_SET); + + data = QOI_MALLOC(size); + if (!data) { + fclose(f); + return NULL; + } + + bytes_read = fread(data, 1, size, f); + fclose(f); + + pixels = qoi_decode(data, bytes_read, desc, channels); + QOI_FREE(data); + return pixels; +} + +#endif /* QOI_NO_STDIO */ +#endif /* QOI_IMPLEMENTATION */