FastImage v0.1.0-STABLE: Final Polish (32-byte Alignment, API Design, Full Handle Safety)

Author: andrestubbe

README.md

@@ -1,13 +1,21 @@
-# FastImage — SIMD-Accelerated Native Imaging for Java
+# FastImage — SIMD‑Accelerated, Off‑Heap Image Processing for Java
 
-**Ultra-fast image processing using native AVX2/SSE4.1 kernels and off-heap memory.**
+[![FastJava](https://img.shields.io/badge/Ecosystem-FastJava-0078D4.svg?style=for-the-badge&logo=java)](https://github.com/andrestubbe)
+[![Release](https://img.shields.io/badge/Release-v0.1.0--STABLE-green.svg?style=for-the-badge)](https://github.com/andrestubbe/FastImage/releases)
+[![Performance](https://img.shields.io/badge/Performance-10--50x_Faster-blue.svg?style=for-the-badge)](https://github.com/andrestubbe/FastImage#benchmarks)
 
-[![Java](https://img.shields.io/badge/Java-17+-blue.svg)](https://www.java.com)
-[![Platform](https://img.shields.io/badge/Platform-Windows%20x64-lightgrey.svg)]()
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Standard: BluePrint](https://img.shields.io/badge/Standard-BluePrint-blueviolet.svg)](#)
+**FastImage** ist eine ultra‑schnelle, native‑beschleunigte Image‑Processing‑Engine für Java, gebaut für das FastJava‑Ecosystem. Es kombiniert AVX/SSE SIMD, off‑heap Storage, zero‑copy Pipelines und eine fluent API, um typische BufferedImage‑Operationen **10–50× schneller** auszuführen — ohne GC‑Pressure, ohne Pixel‑Loops, ohne JVM‑Overhead.
 
-FastImage is the high-performance imaging core of the **FastJava** ecosystem. By moving pixel data out of the JVM heap and into **native memory**, it eliminates GC overhead and enables real-time filters (Blur, Contrast, Brightness) at 60+ FPS on 4K images.
+### Highlights
+- ⚡ **SIMD Accelerated**: AVX2 & SSE4.1 optimierte Kernel für maximale CPU-Ausnutzung.
+- 📦 **Off-Heap Memory**: Pixel werden außerhalb des Java-Heaps gespeichert (kein GC-Overhead).
+- 🧬 **Fluent API**: Intuitive Verkettung von Operationen (`resize().blur().grayscale()`).
+- 🛡️ **Fail-Safe JNI**: Robuste Fehlerbehandlung und Bounds-Checks.
+
+---
+
+### Tags
+`java` `image-processing` `simd` `avx` `sse` `native` `jni` `off-heap` `high-performance` `fastjava` `graphics` `zero-copy`
 
 ---
 

docs/API_DESIGN.md

@@ -0,0 +1,27 @@
+# FastImage API Design & Architecture
+
+FastImage is designed for ultra-high-performance image processing in Java, bypassing the limitations of the JVM heap and garbage collector.
+
+## Core Philosophy
+
+1.  **Off-Heap Storage**: Pixel data is stored in native memory via `_aligned_malloc`. This avoids GC pressure and allows direct access by native SIMD kernels.
+2.  **SIMD Acceleration**: Every core operation is vectorized using Intel SSE4.1 and AVX2 instructions.
+3.  **Runtime Dispatching**: The library detects CPU features at startup and automatically chooses the fastest available code path (AVX2 -> SSE4.1 -> Plain C++).
+4.  **Zero-Stutter JNI**: JNI transitions are minimized, and long-running operations are designed to be thread-safe for background execution.
+
+## Memory Model
+
+-   **Manual Management**: Since memory is off-heap, `dispose()` must be called to free native resources. A fallback `finalize()` is provided but should not be relied upon.
+-   **Alignment**: All buffers are 32-byte aligned to satisfy the requirements of 256-bit AVX instructions.
+
+## Error Handling
+
+-   **Bounds Validation**: All parameters (radii, dimensions, factors) are validated in Java before reaching native code.
+-   **Native Safety**: JNI entry points verify native handles. Invalid access throws `FastImageException` instead of crashing the JVM.
+
+## Integration with FastJava
+
+FastImage follows the **BluePrint** standard:
+-   Modular architecture.
+-   Fluent API for filter chaining.
+-   Native performance with Java simplicity.