FastCursor 0.1.2 — Ultra-Lightweight Win32 Native Cursor & Pointer Engine for Java

---

🎯 Ultra-fast native Win32 cursor pointer shape management, capture, and alpha blending for Java.

FastCursor delivers dual capabilities for high-performance Java applications:

1. Pointer Mutation: Sub-microsecond Win32 user32.dll cursor changes (set, setForWindow, get, show, hide) with zero preview flags.
2. Cursor Capture & Blending: Real-time extraction of the active OS mouse cursor (captureCursor) and hardware-accelerated alpha blending (blendCursor) directly into screen-recording and streaming frame buffers.

---

Quick Start

import fastcursor.FastCursor;
import fastcursor.CursorType;

public class QuickStart {
    public static void main(String[] args) {
        // 1. Immediately change active thread cursor to WAIT spinner
        FastCursor.set(CursorType.WAIT);

        // 2. Query native Win32 HCURSOR address
        long hCursor = FastCursor.get();
        System.out.println("Active HCURSOR: 0x" + Long.toHexString(hCursor));

        // 3. Restore default arrow
        FastCursor.set(CursorType.ARROW);

        // 4. Alpha-blend cursor into a frame buffer (for streaming/capture)
        int[] framePixels = new int[1920 * 1080];
        FastCursor.blendCursor(framePixels, 1920, 1080, 0, 0, false);
    }
}

---

Table of Contents

• Quick Start
• Why FastCursor?
• Key Features
• Real-World Use Cases
• Architecture & Design
• Supported Cursor Types
• Code Examples
  • 1. Thread-Scoped Cursor
  • 2. Window-Bound Cursor (HWND)
  • 3. Querying Active Cursor Handle
  • 4. Cursor Visibility (Show / Hide)
• Performance Benchmarks
• Technical Demos & Benchmarks
• Installation
  • Option 1: Maven (Recommended)
  • Option 2: Gradle (via JitPack)
  • Option 3: Direct Download (No Build Tool)
• Documentation
• Platform Support
• Related Projects
• License

---

Why FastCursor?

Standard Java cursor handling via java.awt.Cursor or JavaFX is plagued by severe architectural limitations for high-performance apps, games, and system tools:

• Missing System Cursor Shapes: Standard Java only maps a tiny subset of legacy cursors. Essential Windows cursors like IDC_APPSTARTING, IDC_HELP, or IDC_SIZEALL are either inconsistent or completely missing.
• No Window-Level Class Binding: AWT requires continuous hover listening. If the JVM Event Dispatch Thread (EDT) suffers a latency spike, the cursor freezes or exhibits jitter.
• Missing Direct Handle Access: Standard APIs do not expose the underlying Win32 HCURSOR handle needed for integration with low-level graphic APIs or native window frames.
• The DLL / JNI Overhead Dilemma: Traditional native workarounds rely on heavyweight JNA wrappers or custom C++ DLLs that require cumbersome compilation, extraction, and platform-specific deployments.

FastCursor circumvents all these limitations through an ultra-fast native Win32 C++ & JNI engine backed by FastCore:

Feature	Standard Java (java.awt.Cursor)	Legacy JNA Wrappers	FastCursor (Native JNI)
Underlying Mechanism	AWT Peer abstraction	Dynamic libffi wrappers	Direct Win32 C++ Kernel Subsystem
Java Preview Flags Required	No	No	No (Zero Preview Flags, Java 21+ LTS)
Direct HCURSOR Query	❌ Not exposed	⚠️ Heavy JNA overhead	✅ Native FastCursor.get()
Window Class Binding	❌ Event-polling only	⚠️ Complex bridge	✅ Native SetClassLongPtrW (HWND)
Live Cursor Screen Capture	❌ None	❌ None	✅ Native captureCursor() (ARGB)
Frame Alpha Blending	❌ Manual CPU loops	❌ None	✅ Native blendCursor() (In-Place)
Invocation Latency	~2–5 ms (EDT dispatch)	~50–100 µs (JNA boundary)	< 1 µs (Direct JNI Dispatch)
Preloaded Handle Cache	No	Manual implementation	✅ Built-in Concurrent Cache

---

Key Features

• ⚡ Ultra-Fast Native Win32 C++ & JNI Engine: Zero Java Preview Flags, Zero JNA Overhead. Built for seamless integration across all Java 21+ standard runtimes.
• 🎯 Thread & Window Scoped Cursors: Instantly switch the active thread cursor or register class-level cursor shapes (SetClassLongPtrW) per HWND so Windows applies them natively on hover.
• 🎥 Live Cursor Capture & Blending: High-speed cursor capture with hot-spot geometry and direct alpha compositing into video or framebuffer arrays via blendCursor(...).
• 🔍 Native Handle Inspection: Retrieve the calling thread's active HCURSOR address directly via FastCursor.get().
• 🗲 Sub-Microsecond Latency: Built-in concurrent handle caching avoids redundant LoadCursorW Win32 calls.
• 🛡️ Fail-Safe Fallbacks: Safe native lifecycle with zero JVM crashes, memory leaks, or GC allocations.

---

Real-World Use Cases

• 🎮 Desktop Streaming & Capture (FastVideoStream): Real-time cursor alpha blending into video pipelines via FastCursor.blendCursor(...) without frame jitter.
• 🎨 Canvas, Diagramming & CAD (FastGUI): Native resize pointers (IDC_SIZEWE, IDC_SIZENS, IDC_SIZENWSE, IDC_SIZEALL) that feel 100% native and responsive even during heavy background rendering.
• 🪟 Window Hover Feedback (FastWindow): Bind custom cursors per window handle (setForWindow) for effortless interaction cues.
• ⏳ Background Task Indication: Immediate system spinner (IDC_WAIT / IDC_APPSTARTING) triggered on the calling thread without EDT queue contention.

---

Architecture & Design

┌─────────────────────────────────────────────────────────────┐
│                       Your Application                      │
│            (Editors, Snipping Tools, Canvas, UI)            │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                    fastcursor.FastCursor                    │
│           (Facade: set, setForWindow, get, show, hide)       │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                fastcursor.NativeUser32Cursor                │
│             (Direct JNI Native Dispatch + Cache)            │
└──────────────┬───────────────────────────────┬──────────────┘
               │                               │
        Direct Native JNI               Concurrent Cache
               │                         (HCURSOR handles)
               ▼                               ▼
┌─────────────────────────────────────────────────────────────┐
│            fastcursor.dll (Native C++ Subsystem)            │
│   • SetCursor              • LoadCursorW                    │
│   • SetClassLongPtrW       • GetCursor                      │
│   • ShowCursor             • Capture & Alpha Blending       │
└─────────────────────────────────────────────────────────────┘

---

Supported Cursor Types

CursorType provides full coverage of standard Win32 IDC resource cursor shapes:

Shape	CursorType	Win32 Identifier	Description
	ARROW	IDC_ARROW (32512)	Standard arrow pointer
	IBEAM	IDC_IBEAM (32513)	Text selection I-beam
	WAIT	IDC_WAIT (32514)	Wait / hourglass / spinner
	CROSS	IDC_CROSS (32515)	Crosshair for snipping and precision selection
	APP_STARTING	IDC_APPSTARTING (32516)	Arrow with small spinning wait circle
	HAND	IDC_HAND (32649)	Link / button pointer hand
	SIZE_ALL	IDC_SIZEALL (32646)	Four-pointed movement cursor
	SIZE_WE	IDC_SIZEWE (32644)	Double-pointed horizontal arrow
	SIZE_NS	IDC_SIZENS (32645)	Double-pointed vertical arrow
	SIZE_NWSE	IDC_SIZENWSE (32642)	Diagonal NW-SE resize arrow
	SIZE_NESW	IDC_SIZENESW (32643)	Diagonal NE-SW resize arrow
	NO	IDC_NO (32648)	Prohibited / slashed circle
	HELP	IDC_HELP (32651)	Arrow with question mark
	UP_ARROW	IDC_UPARROW (32516)	Upward arrow

---

Code Examples

1. Thread-Scoped Cursor

import fastcursor.FastCursor;
import fastcursor.CursorType;

// Set wait cursor during background computation
FastCursor.set(CursorType.WAIT);

// Restore default arrow
FastCursor.set(CursorType.ARROW);

2. Window-Bound Cursor (HWND)

import fastcursor.FastCursor;
import fastcursor.CursorType;

long hwnd = 0x12345678L; // Native Win32 window handle

// Set hand cursor whenever mouse hovers over this window
FastCursor.setForWindow(hwnd, CursorType.HAND);

3. Querying Active Cursor Handle

import fastcursor.FastCursor;

// Get the native HCURSOR handle of the active thread (long address)
long hCursor = FastCursor.get();
System.out.println("Native HCURSOR address: 0x" + Long.toHexString(hCursor));

4. Cursor Visibility (Show / Hide)

import fastcursor.FastCursor;

// Hide mouse pointer
FastCursor.hide();

// Restore visibility
FastCursor.show();

---

Performance Benchmarks

FastCursor is rigorously benchmarked via OpenJDK JMH to guarantee zero JVM allocation and sub-microsecond Win32 dispatch latencies:

Benchmark / Operation	Throughput (ops/ms)	Ops per Second	Latency
benchmarkGetCursorHandle (Direct Win32 GetCursor)	~2,704 ops/ms	> 2.70 Million	< 370 ns
benchmarkSetCursorCached (IDC handle resolution + SetCursor)	~1,642 ops/ms	> 1.64 Million	< 610 ns
benchmarkSetCursorSwitch (Active shape alternation)	~1,473 ops/ms	> 1.47 Million	< 680 ns

Measured on Windows 11 (x64), JDK 21.0.12.1. Native C++ JNI dispatch with 0 bytes GC heap allocation and sub-microsecond latency.

---

Technical Demos & Benchmarks

Case	Java Example	Launcher	Description
Interactive Terminal Demo	Demo.java	run-demo.bat	Cycles through all Win32 system cursor shapes every 3 seconds directly over the console window.
JMH Microbenchmark Suite	Benchmark.java	run-benchmark.bat	JMH microbenchmark suite measuring Win32 downcall throughput and handle cache performance.

---

Installation

Option 1: Maven (Recommended)

Add the JitPack repository and the dependency to your pom.xml:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <!-- FastCursor Engine -->
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastCursor</artifactId>
        <version>0.1.2</version>
    </dependency>
    <!-- Required Native Platform Infrastructure -->
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastCore</artifactId>
        <version>0.1.0</version>
    </dependency>
</dependencies>

Option 2: Gradle (via JitPack)

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.andrestubbe:FastCursor:0.1.2'
    implementation 'com.github.andrestubbe:FastCore:0.1.0'
}

Option 3: Direct Download (No Build Tool)

Download the latest compiled JARs directly to add them to your classpath:

1. 🎯 FastCursor-0.1.2.jar (The Core Cursor Engine)
2. ⚙️ FastCore-0.1.0.jar (The Native Platform Loader)

Note

FastCursor 0.1.2+ uses standard JNI (fastcursor.dll loaded automatically via FastCore). No preview flags or JVM arguments are required.

---

Documentation

• CHANGELOG.md: Detailed version notes and update history.
• REFERENCE.md: Complete API manual and method signatures.
• PHILOSOPHY.md: The engineering rationale for zero-DLL FFM performance.
• ROADMAP.md: Future milestones and planned features (.ani/.cur custom cursors).
• COMPILE.md: Build and preview flags guide.

---

Platform Support

Platform	Architecture	Status	Notes
Windows 10 / 11	x64	✅ Fully Supported	Win32 user32.dll via Java 21+ Project Panama FFM
Linux (X11 / Wayland)	x64 / AArch64	🚧 Planned	X11 XFixes / Wayland Pointer Shape Protocol
macOS (Sonoma+)	Apple Silicon / x64	🚧 Planned	Cocoa NSCursor / CoreGraphics Direct Pointer API

---

Related Projects

• FastCore — Unified native loader and Project Panama FFM platform runtime.
• FastMouse — Ultra-low latency native RawInput mouse interception (1,000–8,000 Hz).
• FastPointer — Zero-overhead native address arithmetic and memory pointer abstraction.
• FastRobot — Low-latency native input automation and simulation.

---

License

This project is licensed under the MIT License. Part of the FastJava Ecosystem.