FastThumb v0.1.0 [ALPHA] — Native Thumbnail Extraction for Java

---

⚡ Native Windows 11 Thumbnail Extraction for Java (Explorer-Parity, High-DPI, Zero-Copy)

FastThumb is an ultra-fast, native thumbnail extractor for Windows 10/11. It leverages IShellItem + IShellItemImageFactory — the exact same APIs used by Windows Explorer. It provides High-DPI thumbnails (up to 512px+), folder previews, video keyframes, and composite thumbnails, perfectly integrated into the FastJava ecosystem.

---

---

Table of Contents

• Quick Start
• Features

---

Quick Start

Path p = Paths.get("C:/Users/Andre/Pictures/IMG_00123.JPG");
FastImage img = FastThumb.get(p, 256);

if (img != null) {
    viewer.draw(img); // FastWindow / FastUI
}

Folder Preview:

FastImage preview = FastThumb.getFolder(Paths.get("C:/Users/Andre/Pictures"), 256);

---

Features

• 🖼️ Explorer‑Parity — Identical thumbnails to Windows Explorer (colors, cropping, DPI, video frames, folder preview logic).
• 🔍 High‑DPI Support — 32px → 512px → unbounded. No 48px limitation like Java ShellFolder.
• ⚡ Zero‑Copy JNI Pipeline — Native DIB → DirectByteBuffer → FastImage.
• 🗂️ Folder Preview Logic (Win11) — Micro‑thumbnails, composite layouts, and content‑sampling.
• 🎞️ Video & Multimedia — Keyframes, album art, PDF/Office previews (via Explorer backend).
• 🧵 STA‑Thread Engine — COM Thumbnail APIs run in a dedicated STA thread for maximum stability.
• 🧩 FastJava Integration — Seamlessly combines with FastIO, FastFileIndex, FastImage, and FastWindow.

---

Returns

• FastImage (ARGB, direct, zero-copy).
• Guaranteed High-DPI and Explorer-consistent.

Error Handling

• Item without thumbnail → null (falls back to icon if available).
• Folder empty → null.
• Not supported → isSupported() == false.

---

Architecture

Java
 └── FastThumb.get(path, size)
       ↓ JNI (Zero-Copy)
Native (C++)
 ├── CoInitializeEx(STA) (Dedicated Thread)
 ├── SHCreateItemFromParsingName
 ├── IShellItemImageFactory::GetImage(size)
 ├── HBITMAP → DIB → DirectByteBuffer
 └── return to Java (FastImage)

Guarantees

• Always STA-Thread: All COM operations are proxied to a dedicated Single-Threaded Apartment thread to prevent deadlocks and undefined behavior.
• Always High-DPI: Leverages IShellItemImageFactory for high-resolution assets (256px, 512px, 1024px) without scaling artifacts.
• Always Explorer-Parity: Matches the exact Windows look and feel, including video frame overlays and folder contents.
• Zero-Copy: Pixels are written directly into a native buffer that FastImage manages. No intermediate int[] copies.

---

Performance

Operation	FastThumb	Java ShellFolder	Speedup
128px Thumbnail	0.3 – 1.2 ms	20 – 40 ms	~30x
256px Thumbnail	0.5 – 2.0 ms	Not supported	∞
512px Thumbnail	3.0 – 5.0 ms	Not supported	∞
Folder Preview	1.0 – 4.0 ms	Not supported	∞

Note: Benchmarks performed on Windows 11, NVMe SSD.

---

Folder Preview Logic (Windows 11)

FastThumb replicates the exact Explorer heuristic:

• Sampling: Samples the first N files for content previews.
• Prioritization: Images > Videos > Documents.
• Grid Layout: Automatic 2x2 or 3x3 composite grid for folders.
• DPI Awareness: Renders micro-thumbnails at the appropriate scale.

---

Documentation

• COMPILE.md: Full compilation guide (MSVC C++17 build chain + JNI Setup).
• REFERENCE.md: Full API descriptions, border configurations, and codepoint index.
• PHILOSOPHIE.md: The engineering rationale for zero-allocation performance.
• ROADMAP.md: Future milestones and planned features.

---

Platform Support

Platform	Status
Windows 10/11	✅ Fully Supported
Linux	🚧 Planned
macOS	🚧 Planned

---

License

MIT License — See LICENSE file for details.

---

Related Projects

• FastCore — Native Library Loader for Java
• FastKeyboard — High-performance RawInput engine
• FastTheme — Advanced UI styling engine

---

Part of the FastJava Ecosystem — Making the JVM faster.