zig-qoi
A implementation of the Quite OK Image Format for Zig. This implementation conforms to the Qoi specification.
API
Add src/qoi.zig to your Zig project as a package.
pub const DecodeError = error{ OutOfMemory, InvalidData, EndOfStream };
pub const EncodeError = error{ OutOfMemory };
// Simple API:
pub fn isQOI(bytes: []const u8) bool;
pub fn decodeBuffer(allocator: std.mem.Allocator, buffer: []const u8) DecodeError!Image;
pub fn decodeStream(allocator: std.mem.Allocator, reader: anytype) !Image;
pub fn encodeBuffer(allocator: std.mem.Allocator, image: ConstImage) EncodeError![]u8;
pub fn encodeStream(image: ConstImage, writer: anytype) !void;
// Streaming API:
pub fn encoder(writer: anytype) Encoder(@TypeOf(writer));
pub fn Encoder(comptime Writer: type) type {
return struct {
writer: Writer,
pub fn reset(self: *Self) void;
pub fn flush(self: *Self) (EncodeError || Writer.Error)!void;
pub fn push(self: *Self, pixel: Color) (EncodeError || Writer.Error)!void;
};
}
pub const ColorRun = struct {
color: Color,
length: usize,
};
pub fn decoder(reader: anytype) Decoder(@TypeOf(reader));
pub fn Decoder(comptime Reader: type) type {
return struct {
reader: Reader,
pub fn fetch(self: *Self) Reader.Error!ColorRun;
};
}Implementation Status
Everything specified in phoboslab/qoi#37 is implemented and accessible via the API.
Performance
On my machine (AMD Ryzen 7 3700U), i did a small benchmark with decoding bench.zig, which will decode zero.qoi:
| Build Mode | QOI Bytes | Raw Bytes | Encoding Time | Decoding Time |
|---|---|---|---|---|
| Debug | 75.024 byte | 1.048.576 byte | 14.439ms | 7.061ms |
| ReleaseSmall | 75.024 byte | 1.048.576 byte | 1.888ms | 1.499ms |
| ReleaseSafe | 75.024 byte | 1.048.576 byte | 1.392ms | 512.706us |
| ReleaseFast | 75.024 byte | 1.048.576 byte | 1.186ms | 456.762us |
This means that this implementation is roughly able to decode ~2.1 GB/s raw texture data and is considered "fast enough" for now. If you find some performance improvements, feel free to PR it!
Running perf on the benchmark compiled with ReleaseFast showed that the implementation is quite optimal for the CPU, utilizing it to 100% and executing up to 3 instructions per cycle on my machine.
[felix@denkplatte-v2 zig-qoi]$ perf stat ./zig-out/bin/qoi-bench
Benchmark [4067/4096] Encoding time for 1048576 => 75024 bytes: 1.019ms
Benchmark [4067/4096] Decoding time for 75024 => 1048576 bytes: 419.223us
Performance counter stats for './zig-out/bin/qoi-bench':
9.665,11 msec task-clock:u # 0,997 CPUs utilized
0 context-switches:u # 0,000 K/sec
0 cpu-migrations:u # 0,000 K/sec
21.066 page-faults:u # 0,002 M/sec
29.757.225.002 cycles:u # 3,079 GHz (83,33%)
317.453.390 stalled-cycles-frontend:u # 1,07% frontend cycles idle (83,33%)
515.819.113 stalled-cycles-backend:u # 1,73% backend cycles idle (83,32%)
83.377.885.642 instructions:u # 2,80 insn per cycle
# 0,01 stalled cycles per insn (83,36%)
18.947.655.057 branches:u # 1960,417 M/sec (83,31%)
193.594.708 branch-misses:u # 1,02% of all branches (83,35%)
9,693303129 seconds time elapsed
9,553127000 seconds user
0,112001000 seconds sys
Also, running the benchmark dataset of the original author, it yielded the following data:
Number of total images: 1351
Average PNG Compression: 18.57%
Average QOI Compression: 22.70%
Average Compression Rate (MB/s): 438.31 MB/s
Minimal Compression Rate (MB/s): 27.06 MB/s
Maximum Compression Rate (MB/s): 1390.15 MB/s
Average Decompression Rate (MB/s): 1128.46 MB/s
Maximum Decompression Rate (MB/s): 39.77 MB/s
Maximum Deompression Rate (MB/s): 13307.20 MB/s
See also the original analysis on Google Docs
Contribution
Run the test suite like this:
[user@host zig-qoi]$ zig build test
All 5 tests passed.
Run the benchmark like this:
[user@host zig-qoi]$ zig build benchmark
Benchmark [4096/4096] Encoding time for 1048576 => 67076 bytes: 16.649ms
Benchmark [4095/4096] Decoding time for 67076 => 1048576 bytes: 5.681ms
To run the benchmark for batch files, run this:
[user@host zig-qoi]$ zig build install && ./zig-out/bin/qoi-bench-files $(folder_a) $(folder_b) ...
File Name Width Height Total Raw Bytes Total PNG Bytes PNG Compression Total QOI Bytes QOI Compression QOI to PNG Decode Time (ns) Encode Time (ns)
data/zero.png 512 512 1048576 80591 0.08 67076 0.06 0.8323013782501221 5628360 14499346
total sum 0 0 1048576 80591 0.08 67076 0.06 0.8323013782501221 5628360 14499346
Pass as many folders you like to the benchmarking tool. It will render a CSV file on the stderr.