Update README.md

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?
+## 🚀 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.
+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.
+- **Ultra-Fast:** Near-memcpy decoding speeds utilizing cache-friendly algorithms.
-- **Small Footprint:** Single-header C99 library with zero dependencies.
+- **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
+## 📊 Performance Comparison
-- PIK Dimensions: 5120x2880
+Benchmark results for loading a 5K professional image (Sample dimensions: 5120x2880):
-- ------------------------------------
-- PNG Load Time:  0.193990 seconds
-- PNG Dimensions: 5120x2880
 
-## Implementation
+| Format | Load Time | Dimensions |
-The core library consists of only two files: `pikture.h` and `pikture.c`.
+| :--- | :--- | :--- |
+| **PIK** | **0.111735 sec** | 5120x2880 |
+| PNG | 0.193990 sec | 5120x2880 |
 
-### Building
+*PIKTURE decodes nearly 2x faster than standard PNG implementations on the same hardware.*
-The project is designed to be cross-compiled using the **Zig** toolchain for maximum portability across Linux, Windows, and macOS.
+
+---
+
+## 🛠️ 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 <stdio.h>
+
+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.sh   # UNIX (macOS / Linux)
-./build.bat | WINDOWS
+./build.bat  # WINDOWS
+
 ```
 
-## Technical Specification
+### Advanced Compilation Flags
-### 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.
 
-### 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.
+
+```
+
+```