diff --git a/README.md b/README.md index 4ed8513..d633b5c 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,129 @@ # PIKTURE (PIK) **Fast. Small. Easy.** -PIKTURE is a high-performance, lossless image format designed for systems where decoding speed and binary simplicity are critical. It is built on the FSE philosophy: Fast execution, Small file size, and Easy integration. +PIKTURE is a high-performance, lossless image format designed for systems where decoding speed and binary simplicity are critical. It is built on the **FSE** philosophy: **F**ast execution, **S**mall file size, and **E**asy integration. -## Why PIKTURE? -Standard formats like PNG are often bottlenecked by heavy decompression algorithms (DEFLATE/ZIP). PIKTURE replaces complex bit-shuffling with a hardware-friendly **INDEX + Delta** encoding, allowing the CPU to stream pixels directly to memory with minimal overhead. +## 🚀 Why PIKTURE? +Standard formats like PNG are often bottlenecked by heavy decompression algorithms (DEFLATE/ZIP). PIKTURE replaces complex bit-shuffling with a hardware-friendly **INDEX + Delta** encoding. This allows the CPU to stream pixels directly to memory with minimal overhead, acting closer to a memory copy operation than a math-heavy decompression. -### Key Features +### ✨ Key Features - **Lossless:** 100% bit-perfect reproduction of RGBA data. -- **Ultra-Fast:** Near-memcpy decoding speeds. -- **Small Footprint:** Single-header C99 library with zero dependencies. +- **Ultra-Fast:** Near-memcpy decoding speeds utilizing cache-friendly algorithms. +- **Hardware Acceleration:** Optional SIMD (AVX/NEON) and OpenMP multithreading support. +- **Small Footprint:** Two-file C library (`.c` / `.h`) with zero external dependencies. +- **Endian-Aware:** Cross-architecture compatibility (Little-Endian / Big-Endian). - **Smart Alpha:** Automatically optimizes storage when transparency is not used. -## Performance Comparison -Benchmark results for a 5K professional image (sample 5120x2880): +--- -- PIK Load Time: 0.111735 seconds -- PIK Dimensions: 5120x2880 -- ------------------------------------ -- PNG Load Time: 0.193990 seconds -- PNG Dimensions: 5120x2880 +## 📊 Performance Comparison +Benchmark results for loading a 5K professional image (Sample dimensions: 5120x2880): -## Implementation -The core library consists of only two files: `pikture.h` and `pikture.c`. +| Format | Load Time | Dimensions | +| :--- | :--- | :--- | +| **PIK** | **0.111735 sec** | 5120x2880 | +| PNG | 0.193990 sec | 5120x2880 | -### Building -The project is designed to be cross-compiled using the **Zig** toolchain for maximum portability across Linux, Windows, and macOS. +*PIKTURE decodes nearly 2x faster than standard PNG implementations on the same hardware.* + +--- + +## 🛠️ Implementation & Usage + +The core library consists of only two files: +* `pikture.h` - Contains the data structures (`pikture_t`) and public API declarations. +* `pikture.c` - Contains the core encoding/decoding logic, hashing, and byte-stream processing. + +### Basic API Example +Integrating PIKTURE into your C/C++ project is trivial: + +```c +#include "pikture.h" +#include + +int main() { + // Load an image + pikture_t* img = pikture_load("image.pik"); + if (!img) { + printf("Failed to load image!\n"); + return 1; + } + + printf("Loaded %dx%d image.\n", img->width, img->height); + + // Save an image + pikture_save("output.pik", img); + + // Free memory + pikture_free(img); + return 0; +} + +``` + +--- + +## ⚙️ Building & Compilation + +The project is designed to be highly portable. You can compile it using standard GCC/Clang or cross-compile it using the **Zig** toolchain. + +### Build Scripts ```bash # Run the build script to generate static and shared libraries -./build.sh | UNIX (macOS / Linux) -./build.bat | WINDOWS +./build.sh # UNIX (macOS / Linux) +./build.bat # WINDOWS + ``` -## Technical Specification -### PIKTURE uses a custom byte-stream protocol: -- 0x00 - 0x3F: INDEX - Fetch pixel from a 64-color LRU cache. -- 0x40 - 0x7F: DIFF - Apply small RGB deltas. -- 0x80 - 0xBF: LUMA - Apply green-relative color deltas. -- 0xC0 - 0xFD: RUN - Repeat previous pixel. -- 0xFE: RGB - Full 24-bit color change. -- 0xFF: RGBA - Full 32-bit color change. +### Advanced Compilation Flags -### MIT LICENSE +You can enable hardware-specific optimizations by passing the following preprocessor directives during compilation: + +* `-DPIKT_USE_SIMD` : Enables vectorized instructions (AVX/SSE for x86_64, NEON for ARM64) to process multiple pixels per clock cycle. +* `-DPIKT_USE_THREADS` : Enables OpenMP multithreading. Divides the decoding/encoding workload across multiple CPU cores (perfect for large 4K/8K images). + +**Example compilation with optimizations (GCC):** + +```bash +gcc -O3 -DPIKT_USE_SIMD -DPIKT_USE_THREADS -fopenmp main.c pikture.c -o myapp + +``` + +--- + +## 🔬 Technical Specification + +PIKTURE is a binary format. All multi-byte integers in the header are stored in **Big-Endian** format. + +### 1. File Header (11 Bytes) + +| Offset | Size | Type | Description | +| --- | --- | --- | --- | +| `0x00` | 4 bytes | `char[4]` | Magic bytes: `"PIK!"` | +| `0x04` | 1 byte | `uint8_t` | Version number (Currently `5`) | +| `0x05` | 2 bytes | `uint16_t` | Image Width | +| `0x07` | 2 bytes | `uint16_t` | Image Height | +| `0x09` | 1 byte | `uint8_t` | Bit Depth (Currently `32` for RGBA) | +| `0x0A` | 1 byte | `uint8_t` | Endianness flag (`0` = Little, `1` = Big) | + +### 2. Byte-Stream Protocol + +Immediately following the header is the compressed pixel data payload. PIKTURE uses a custom command-byte protocol combined with a 64-color Least Recently Used (LRU) cache: + +* `0x00 - 0x3F` (**INDEX**): Fetch the exact pixel from the 64-color LRU cache. +* `0x40 - 0x7F` (**DIFF**): Apply small RGB deltas (differences from the previous pixel). +* `0x80 - 0xBF` (**LUMA**): Apply green-relative color deltas (highly efficient for gradients). +* `0xC0 - 0xFD` (**RUN**): Repeat the exact same previous pixel `N` times (Run-Length Encoding). +* `0xFE` (**RGB**): Full 24-bit color change (Alpha remains unchanged). Followed by 3 bytes (R, G, B). +* `0xFF` (**RGBA**): Full 32-bit color change. Followed by 4 bytes (R, G, B, A). + +--- + +## 📜 License + +This project is licensed under the **MIT License**. Free to use, modify, and distribute for personal and commercial purposes. + +``` + +```