Skip to content

Commit 56fbae2

Browse files
andrestubbeandrestubbe
committed
release: FastImage 0.1.1 with FastSIMD AVX2 vector engine integration
1 parent bbb6835 commit 56fbae2

14 files changed

Lines changed: 424 additions & 413 deletions

File tree

‎README.md‎

Lines changed: 146 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,41 @@
1-
# FastImage 0.1.0 [ALPHA-2026-05-17] — SIMD-Accelerated, Off-Heap Image Processing for Java
1+
# FastImage 0.1.1 [ALPHA-2026-08] — High-Performance Off-Heap Image Processing for Java
22

3-
4-
[![Status](https://img.shields.io/badge/status-0.1.0-brightgreen.svg)](https://github.com/andrestubbe/FastImage/releases/tag/0.1.0)
3+
[![Status](https://img.shields.io/badge/status-0.1.1-brightgreen.svg)](https://github.com/andrestubbe/FastImage/releases/tag/0.1.1)
54
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
65
[![Java](https://img.shields.io/badge/Java-17+-blue.svg)](https://www.java.com)
76
[![Platform](https://img.shields.io/badge/Platform-Windows%2010+-lightgrey.svg)]()
8-
[![JitPack](https://img.shields.io/badge/JitPack-ready-green.svg)](https://jitpack.io/#andrestubbe/FastImage)
7+
[![JitPack](https://img.shields.io/badge/JitPack-0.1.1-green.svg)](https://jitpack.io/#andrestubbe/FastImage)
98

109
---
1110

12-
**🖼️ Ultra-fast native image processing using AVX2/SSE4.1 kernels and zero-GC memory management.**
11+
**⚡ 10–50× faster than Java's BufferedImage.** Off-heap zero-copy memory. SIMD AVX2 accelerated image scaling and blur filters.
1312

14-
FastImage ist eine ultra-schnelle, nativ-beschleunigte Image-Processing-Engine für Java, gebaut für das
15-
FastJava-Ecosystem. Es kombiniert AVX/SSE SIMD, off-heap Storage, zero-copy Pipelines und eine fluent API, um typische
16-
BufferedImage-Operationen **10–50× schneller** auszuführen — ohne GC-Pressure, ohne Pixel-Loops, ohne JVM-Overhead.
13+
`FastImage` provides ultra-fast C++ native image processing for Java applications, replacing slow JVM `BufferedImage` rendering loops with SIMD-accelerated Bilinear scaling, Dual-Kawase blur, and color transforms.
1714

18-
```java
19-
// Quick Start SIMD-Accelerated Filtering
15+
[![Showcase](docs/screenshot.png)](https://www.youtube.com/watch?v=BZsqQl7WqWk)
16+
17+
---
18+
19+
## Quick Start — Example
2020

21+
```java
2122
import fastimage.FastImage;
23+
import java.awt.image.BufferedImage;
2224

2325
public class Demo {
2426
public static void main(String[] args) {
25-
FastImage img = FastImage.load("input.jpg");
26-
27-
img.adjustContrast(1.2f)
28-
.blurStack(15.0f)
29-
.grayscale();
30-
31-
img.save("output.png");
32-
img.dispose(); // Free native memory
27+
// 1. Create 1080p off-heap image buffer
28+
FastImage img = FastImage.create(1920, 1080);
29+
30+
// 2. Apply SIMD-accelerated filters (Chaining API)
31+
FastImage processed = img
32+
.resize(1280, 720)
33+
.blurKawase(3.0f, 2)
34+
.grayscale()
35+
.adjustBrightness(1.2f);
36+
37+
// 3. Export to BufferedImage or native handle
38+
BufferedImage result = processed.toBufferedImage();
3339
}
3440
}
3541
```
@@ -38,50 +44,93 @@ public class Demo {
3844

3945
## Table of Contents
4046

47+
- [Why FastImage?](#why-fastimage)
4148
- [Key Features](#key-features)
42-
- [Performance](#performance)
49+
- [Real-World Use Cases](#real-world-use-cases)
50+
- [Performance Benchmarks](#performance-benchmarks)
51+
- [Architecture Overview](#architecture-overview)
52+
- [API Quick Reference](#api-quick-reference)
4353
- [Installation](#installation)
44-
- [Try the Demo](#try-the-demo)
45-
- [API Reference](#api-reference)
54+
- [Documentation](#documentation)
4655
- [Platform Support](#platform-support)
47-
- [Building from Source](#building-from-source)
4856
- [License](#license)
4957
- [Related Projects](#related-projects)
5058

5159
---
5260

61+
## Why FastImage?
62+
63+
Standard Java `BufferedImage` operations suffer from heavy heap allocation overhead, slow software rasterizers, and JVM GC stalls. `FastImage` addresses this by:
64+
65+
- **SIMD Vectorization** — Uses native C++ AVX2 vector instructions for multi-pixel parallel scaling and color manipulation.
66+
- **Off-Heap Direct Memory** — Stores pixel buffers in native unmanaged memory to eliminate JVM GC pauses completely.
67+
- **Kawase & Mipmapped Blur** — Implements modern GPU-grade blur algorithms running in native C++ for UI overlays.
68+
69+
---
70+
5371
## Key Features
5472

55-
- **⚡ SIMD Acceleration**: Hand-optimized C++ kernels using **AVX2** and **SSE4.1** vector instructions.
56-
- **⚙️ Zero-GC Overhead**: Pixels are stored in **off-heap** memory, preventing GC pauses during heavy manipulation.
57-
- **🎨 Advanced Blur Suite**: Real-time Gaussian, Stack (iOS-style), and Kawase blurs.
58-
- **🛡️ Fail-Safe JNI**: Robust error handling with `FastImageException` and native handle validation.
59-
- **📥 Fast Conversion**: Optimized bit-copying between `BufferedImage` and native memory.
73+
* **⚡ Native AVX2 SIMD Acceleration** — Leverages 256-bit AVX2 vector registers for ultra-fast Bilinear scaling and color adjustments.
74+
* **🖼️ Off-Heap Zero-GC Memory** — Allocates raw pixel buffers in direct native memory to prevent JVM Garbage Collection stalls.
75+
* **🌀 Dual Kawase & Stack Blur** — High-speed blur algorithms for modern UI translucent overlays and game HUDs.
76+
* **🔗 Chainable Fluent API** — Functional transformation pipeline returning new immutable `FastImage` instances.
77+
* **🔄 Interoperable Java Bridge** — Zero-copy converter to and from `java.awt.image.BufferedImage`.
78+
79+
---
80+
81+
## Real-World Use Cases
82+
83+
- 🎮 **Game Overlays & Translucent HUDs**: Real-time Gaussian and Kawase blur filtering for high-FPS game HUD overlays.
84+
- 📹 **Live Screen Capture Pipeline**: Downscale and process 1080p/4K video frames from **[FastScreen](https://github.com/andrestubbe/FastScreen)** without GC stutters.
85+
- 🖼️ **Thumbnail & Preview Generators**: Batch-resize thousands of high-resolution images in web servers and media CMS platforms.
86+
- 🤖 **Computer Vision Preprocessing**: Normalize, crop, and convert image frames before feeding AI vision models.
87+
88+
---
89+
90+
## Performance Benchmarks
91+
92+
In the official [JMH Benchmark](examples/Benchmark), `FastImage` measured throughput for full 1080p (1920x1080) frame processing:
93+
94+
```text
95+
Benchmark Mode Cnt Score Error Units
96+
JMH_Image.benchmarkFastImageResize thrpt 2 19.521 ops/s
97+
JMH_Image.benchmarkFastImageKawaseBlur thrpt 2 17.942 ops/s
98+
```
99+
100+
> **1080p Real-Time Processing (19+ Full Frames / sec)**: `FastImage` resizes 1080p full HD uncompressed image buffers to 720p at **19.5 full operations per second** with **zero JVM Garbage Collection allocations**.
60101
61102
---
62103

63-
## Performance
104+
## Architecture Overview
64105

65-
FastImage utilizes the full power of your CPU, outperforming standard Java2D loops by orders of magnitude:
106+
**FastImage (This Library — Native Image Engine)**
107+
Provides SIMD-accelerated image scaling, blur filters, and color transforms.
66108

67-
| Operation | Java2D (BufferedImage) | FastImage (SIMD) | Speedup |
68-
|:------------------------|:-----------------------|:-----------------|:---------|
69-
| **Brightness** | ~48.6 ms/op | **~1.5 ms/op** | **32x** |
70-
| **Gaussian Blur (r10)** | ~1100.0 ms/op | **~170.4 ms/op** | **6.5x** |
71-
| **Grayscale** | ~20.0 ms/op | **~1.3 ms/op** | **15x** |
109+
**[FastSIMD](https://github.com/andrestubbe/FastSIMD) (Hardware Acceleration Engine)**
110+
Provides cross-platform hardware SIMD vectorization primitives.
72111

73-
*Tested on: 1920x1080 (1080p) ARGB Image on Intel i7-12700K.*
112+
**[FastScreen](https://github.com/andrestubbe/FastScreen) (Zero-Copy DirectX Screen Capture)**
113+
Feeds DirectX video frames into `FastImage` for real-time frame processing.
114+
115+
---
116+
117+
## API Quick Reference
118+
119+
| Method | Description | Path |
120+
|--------|-------------|------|
121+
| `create(width, height)` | Creates an off-heap `FastImage` instance. | [Reference 📖](docs/REFERENCE.md#create) |
122+
| `resize(newW, newH)` | AVX2 SIMD bilinear image scaling. | [Reference 📖](docs/REFERENCE.md#resize) |
123+
| `blurKawase(radius, passes)` | High-speed Dual-Kawase blur filter. | [Reference 📖](docs/REFERENCE.md#blurkawase) |
74124

75125
---
76126

77127
## Installation
78128

79129
### Option 1: Maven (Recommended)
80130

81-
Add the JitPack repository and the dependencies to your `pom.xml`:
131+
Add the JitPack repository and the complete dependency stack to your `pom.xml`:
82132

83133
```xml
84-
85134
<repositories>
86135
<repository>
87136
<id>jitpack.io</id>
@@ -90,19 +139,40 @@ Add the JitPack repository and the dependencies to your `pom.xml`:
90139
</repositories>
91140

92141
<dependencies>
93-
<!-- FastImage Library -->
94-
<dependency>
95-
<groupId>com.github.andrestubbe</groupId>
96-
<artifactId>fastimage</artifactId>
97-
<version>0.1.0</version>
98-
</dependency>
99-
100-
<!-- FastCore (Required Native Loader) -->
101-
<dependency>
102-
<groupId>com.github.andrestubbe</groupId>
103-
<artifactId>fastcore</artifactId>
104-
<version>0.1.0</version>
105-
</dependency>
142+
<!-- FastImage Engine -->
143+
<dependency>
144+
<groupId>com.github.andrestubbe</groupId>
145+
<artifactId>FastImage</artifactId>
146+
<version>0.1.1</version>
147+
</dependency>
148+
149+
<!-- FastSIMD Hardware Vector Acceleration Engine -->
150+
<dependency>
151+
<groupId>com.github.andrestubbe</groupId>
152+
<artifactId>FastSIMD</artifactId>
153+
<version>0.1.3</version>
154+
</dependency>
155+
156+
<!-- FastMemory Aligned Allocator -->
157+
<dependency>
158+
<groupId>com.github.andrestubbe</groupId>
159+
<artifactId>FastMemory</artifactId>
160+
<version>0.1.1</version>
161+
</dependency>
162+
163+
<!-- FastPointer Address Wrapper -->
164+
<dependency>
165+
<groupId>com.github.andrestubbe</groupId>
166+
<artifactId>FastPointer</artifactId>
167+
<version>0.1.1</version>
168+
</dependency>
169+
170+
<!-- FastCore Native Loader -->
171+
<dependency>
172+
<groupId>com.github.andrestubbe</groupId>
173+
<artifactId>FastCore</artifactId>
174+
<version>0.1.0</version>
175+
</dependency>
106176
</dependencies>
107177
```
108178

@@ -114,80 +184,60 @@ repositories {
114184
}
115185
116186
dependencies {
117-
implementation 'com.github.andrestubbe:fastimage:0.1.0'
118-
implementation 'com.github.andrestubbe:fastcore:0.1.0'
187+
implementation 'com.github.andrestubbe:FastImage:0.1.1'
188+
implementation 'com.github.andrestubbe:FastSIMD:0.1.3'
189+
implementation 'com.github.andrestubbe:FastMemory:0.1.1'
190+
implementation 'com.github.andrestubbe:FastPointer:0.1.1'
191+
implementation 'com.github.andrestubbe:FastCore:0.1.0'
119192
}
120193
```
121194

122195
### Option 3: Direct Download (No Build Tool)
123196

124-
Download the latest JARs directly to add them to your classpath:
197+
Download the required JARs directly to add them to your classpath:
125198

126-
1. 📦 **[fastimage-0.1.0.jar](https://github.com/andrestubbe/FastImage/releases/download/0.1.0/fastimage-0.1.0.jar)** (The Core Library)
127-
2. ⚙️ **[fastcore-0.1.0.jar](https://github.com/andrestubbe/FastCore/releases/download/0.1.0/fastcore-0.1.0.jar)** (The Mandatory Native Loader)
199+
1. ⚡ **[FastImage-0.1.1.jar](https://github.com/andrestubbe/FastImage/releases/download/0.1.1/FastImage-0.1.1.jar)** (The Core Library)
200+
2. 🚀 **[FastSIMD-0.1.3.jar](https://github.com/andrestubbe/FastSIMD/releases/download/0.1.3/FastSIMD-0.1.3.jar)** (Hardware Vector Acceleration Engine)
201+
3. 💾 **[FastMemory-0.1.1.jar](https://github.com/andrestubbe/FastMemory/releases/download/0.1.1/FastMemory-0.1.1.jar)** (32-Byte Aligned Allocator)
202+
4. 📍 **[FastPointer-0.1.1.jar](https://github.com/andrestubbe/FastPointer/releases/download/0.1.1/FastPointer-0.1.1.jar)** (Primitive Address Pointer)
203+
5. ⚙️ **[fastcore-0.1.0.jar](https://github.com/andrestubbe/FastCore/releases/download/0.1.0/fastcore-0.1.0.jar)** (Mandatory Native Loader)
128204

129205
> [!IMPORTANT]
130-
> All JARs must be in your classpath for the native JNI calls to function correctly.
131-
132-
## Try the Demo
133-
134-
1. Clone this repository: `git clone https://github.com/andrestubbe/FastImage.git`
135-
2. Run the automated showcase: `.\run-demo.bat`
136-
137-
*Includes the interactive Visual Editor and the Blur Gallery.*
138-
139-
---
140-
141-
## API Reference
142-
143-
| Method | Description |
144-
|:---------------------------|:---------------------------------------------------------|
145-
| `void grayscale()` | Converts image to luminance-weighted grayscale via SIMD. |
146-
| `void adjustBrightness(f)` | Scales RGB values with saturation clamping. |
147-
| `void adjustContrast(f)` | Adjusts image contrast around the midpoint. |
148-
| `void blurGaussian(r)` | High-quality Gaussian blur approximation ($O(N)$). |
149-
| `void blurStack(r)` | Extremely fast separable weighted blur. |
150-
| `void resize(w, h)` | Bilinear resizing using native kernels. |
206+
> All JARs must be included in your classpath for the native SIMD JNI bindings to function correctly.
151207
152208
---
153209

154210
## Documentation
155211

156-
* **[COMPILE.md](docs/COMPILE.md)**: Full compilation guide (MSVC C++17 build chain + JNI Setup).
157-
* **[REFERENCE.md](docs/REFERENCE.md)**: Full API descriptions, border configurations, and codepoint index.
158-
* **[PHILOSOPHY.md](docs/PHILOSOPHY.md)**: The engineering rationale for zero-allocation performance.
159-
* **[ROADMAP.md](docs/ROADMAP.md)**: Future milestones and planned features.
212+
- **[COMPILE.md](docs/COMPILE.md)**: Full compilation guide (MSVC C++17 build chain + JNI Setup).
213+
- **[REFERENCE.md](docs/REFERENCE.md)**: Full API contracts and routing logic.
214+
- **[PHILOSOPHY.md](docs/PHILOSOPHY.md)**: Off-heap zero-GC memory philosophy.
215+
- **[ROADMAP.md](docs/ROADMAP.md)**: Future development goals.
160216

161217
---
162218

163219
## Platform Support
164220

165-
| Architecture | Instruction Set | OS |
166-
|:-------------|:----------------------------|:--------------|
167-
| x64 | **AVX2** (Runtime Dispatch) | Windows 10/11 |
168-
| x64 | **SSE4.1** (Fallback) | Windows 10/11 |
169-
170-
| Platform | Status |
171-
|---------------|-------------------|
172-
| Windows 10/11 | ✅ Fully Supported |
173-
| Linux | 🔗 Planned |
174-
| macOS | 🔗 Planned |
221+
| Platform | Status |
222+
|----------|--------|
223+
| Windows 10/11 (x64) | ✅ Fully Supported |
224+
| Linux | 🔄 Planned |
225+
| macOS | 🔄 Planned |
175226

176227
---
177228

178229
## License
179230

180-
MIT License See [LICENSE](LICENSE) file for details.
231+
MIT License — See [LICENSE](LICENSE) file for details.
181232

182233
---
183234

184235
## Related Projects
185236

186-
- [FastCore](https://github.com/andrestubbe/FastCore) Native Library Loader
187-
- [FastTheme](https://github.com/andrestubbe/FastTheme) Native Window Styling
188-
- [FastGraphics](https://github.com/andrestubbe/FastGraphics) Hardware-accelerated 2D Rendering
237+
- [FastScreen](https://github.com/andrestubbe/FastScreen) — DirectX zero-copy screen capture engine
238+
- [FastGraphics](https://github.com/andrestubbe/FastGraphics) — Hardware-accelerated DirectX rendering
239+
- [FastCore](https://github.com/andrestubbe/FastCore) — Native JNI loader for FastJava libraries
189240

190241
---
191242

192-
**Part of the FastJava Ecosystem** — *Making the JVM faster. Small package. Maximum speed. Zero bloat. 🚀📋*
193-
243+
Part of the FastJava Ecosystem — Making the JVM faster. Small package. Maximum speed. Zero bloat. ⚡

‎build/fastimage.dll‎

0 Bytes
Binary file not shown.

0 commit comments

Comments
 (0)