Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,48 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.8.0] - 2026-02-06

### Added

- **WindowProvider interface** for window geometry and DPI integration
- `Size() (width, height int)` — window client area in physical pixels
- `ScaleFactor() float64` — DPI scale factor (1.0 = standard, 2.0 = Retina/HiDPI)
- `RequestRedraw()` — request a new frame in on-demand rendering mode
- `NullWindowProvider` — configurable defaults for testing and headless operation

- **PlatformProvider interface** for OS integration features (optional)
- `ClipboardRead() (string, error)` — read text from system clipboard
- `ClipboardWrite(text string) error` — write text to system clipboard
- `SetCursor(cursor CursorShape)` — change mouse cursor shape
- `DarkMode() bool` — system dark mode detection
- `ReduceMotion() bool` — accessibility: reduced animation preference
- `HighContrast() bool` — accessibility: high contrast mode
- `FontScale() float32` — user's font size preference multiplier
- `NullPlatformProvider` — no-op defaults for testing

- **CursorShape enum** with 12 standard cursor shapes
- Default, Pointer, Text, Crosshair, Move
- ResizeNS, ResizeEW, ResizeNWSE, ResizeNESW
- NotAllowed, Wait, None (hidden)
- `String()` method for debugging

### Removed

- **TouchEventSource interface** — replaced by PointerEventSource (W3C Pointer Events Level 3)
- `TouchID`, `TouchPhase`, `TouchPoint`, `TouchEvent` types removed
- `TouchEventSource` interface removed
- `NullTouchEventSource` removed
- Touch input is fully covered by `PointerEventSource` with `PointerType: Touch`
- W3C recommends Pointer Events over Touch Events (Touch Events is legacy)

### Notes

- PlatformProvider is **optional** — use type assertion on WindowProvider:
`if pp, ok := provider.(gpucontext.PlatformProvider); ok { ... }`
- These interfaces enable UI frameworks to access host window and platform
capabilities without direct dependency on gogpu

## [0.7.0] - 2026-02-05

### Added
Expand Down Expand Up @@ -51,6 +93,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- **TouchCancelled → TouchCanceled** — US English spelling (misspell linter)
- Removed unused `DeviceHandle` alias

[0.8.0]: https://github.com/gogpu/gpucontext/releases/tag/v0.8.0
[0.7.0]: https://github.com/gogpu/gpucontext/releases/tag/v0.7.0
[0.6.0]: https://github.com/gogpu/gpucontext/releases/tag/v0.6.0
[0.5.0]: https://github.com/gogpu/gpucontext/releases/tag/v0.5.0
Expand Down
127 changes: 56 additions & 71 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,12 @@ go get github.com/gogpu/gpucontext
## Features

- **DeviceProvider** — Interface for injecting GPU device and queue
- **WindowProvider** — Window geometry, DPI scale factor, and redraw requests
- **PlatformProvider** — Clipboard, cursor, dark mode, and accessibility preferences
- **CursorShape** — 12 standard cursor shapes (arrow, pointer, text, resize, etc.)
- **EventSource** — Interface for input events (keyboard, mouse, window, IME)
- **PointerEventSource** — W3C Pointer Events Level 3 (unified mouse/touch/pen)
- **ScrollEventSource** — Scroll/wheel events with pixel/line/page modes
- **TouchEventSource** — Interface for multi-touch input (mobile, tablets, touchscreens)
- **Texture** — Minimal interface for GPU textures with TextureUpdater/TextureDrawer/TextureCreator
- **IME Support** — Input Method Editor for CJK languages (Chinese, Japanese, Korean)
- **Registry[T]** — Generic registry with priority-based backend selection
Expand Down Expand Up @@ -63,6 +65,54 @@ func NewGPUCanvas(provider gpucontext.DeviceProvider) *Canvas {
}
```

### WindowProvider (for UI frameworks)

The `WindowProvider` interface enables UI frameworks to query window dimensions and DPI:

```go
// In gogpu/ui - uses WindowProvider for layout
func (ui *UI) Layout(wp gpucontext.WindowProvider) {
w, h := wp.Size()
scale := wp.ScaleFactor()
dpW := float64(w) / scale
dpH := float64(h) / scale
ui.root.Layout(dpW, dpH)
}
```

### PlatformProvider (optional OS integration)

`PlatformProvider` exposes clipboard, cursor, and system preferences.
Not all hosts support it — use type assertion to check:

```go
// In gogpu/ui - cursor management
func (ui *UI) UpdateCursor(provider gpucontext.WindowProvider) {
if pp, ok := provider.(gpucontext.PlatformProvider); ok {
pp.SetCursor(gpucontext.CursorPointer) // hand cursor
}
}

// In gogpu/ui - clipboard
func (ui *UI) Paste(provider gpucontext.WindowProvider) {
if pp, ok := provider.(gpucontext.PlatformProvider); ok {
text, err := pp.ClipboardRead()
if err == nil {
ui.focused.InsertText(text)
}
}
}

// In gogpu/ui - theme detection
func (ui *UI) DetectTheme(provider gpucontext.WindowProvider) {
if pp, ok := provider.(gpucontext.PlatformProvider); ok {
if pp.DarkMode() {
ui.SetTheme(DarkTheme)
}
}
}
```

### EventSource (for UI frameworks)

`EventSource` enables UI frameworks to receive input events from host applications:
Expand Down Expand Up @@ -169,72 +219,6 @@ func (ctx *Context) DrawTexture(tex gpucontext.Texture, x, y float32) error {
}
```

### Touch Input (Multi-touch Support)

`TouchEventSource` enables multi-touch handling for mobile and tablet applications:

```go
// Touch phases follow platform conventions (iOS, Android, W3C)
const (
TouchBegan // First contact
TouchMoved // Touch moved
TouchEnded // Touch lifted
TouchCanceled // System interrupted
)

// TouchPoint represents a single touch contact
type TouchPoint struct {
ID TouchID // Unique within session
X, Y float64 // Position in logical pixels
Pressure *float32 // Optional: 0.0-1.0
Radius *float32 // Optional: contact radius
}

// TouchEvent contains all touch information
type TouchEvent struct {
Phase TouchPhase // Lifecycle stage
Changed []TouchPoint // Touches that triggered this event
All []TouchPoint // All active touches
Modifiers Modifiers // Keyboard modifiers (Ctrl+drag, etc.)
Timestamp time.Duration // For velocity calculations
}
```

Usage for gesture handling:

```go
// Implement pinch-to-zoom
func (app *App) AttachTouchEvents(source gpucontext.EventSource) {
// Check if touch is supported
if tes, ok := source.(gpucontext.TouchEventSource); ok {
tes.OnTouch(func(ev gpucontext.TouchEvent) {
switch ev.Phase {
case gpucontext.TouchBegan:
app.startGesture(ev.Changed)
case gpucontext.TouchMoved:
if len(ev.All) == 2 {
// Pinch gesture
app.handlePinch(ev.All[0], ev.All[1])
} else if len(ev.All) == 1 {
// Pan gesture
app.handlePan(ev.All[0])
}
case gpucontext.TouchEnded, gpucontext.TouchCanceled:
app.endGesture()
}
})
}
}

// Calculate pinch distance
func (app *App) handlePinch(t1, t2 gpucontext.TouchPoint) {
dx := t1.X - t2.X
dy := t1.Y - t2.Y
distance := math.Sqrt(dx*dx + dy*dy)
app.zoom = distance / app.initialPinchDistance
}
```

### Backend Registry

The `Registry[T]` provides thread-safe registration with priority-based selection:
Expand Down Expand Up @@ -277,14 +261,15 @@ names := backends.Available() // ["vulkan", "software"]
gpucontext
(imports gputypes)
DeviceProvider, EventSource, Texture
TouchEventSource, Registry
DeviceProvider, WindowProvider,
PlatformProvider, EventSource,
Texture, PointerEventSource, Registry
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
gogpu gg born-ml/born
(implements) (uses) (implements & uses)
gogpu gg ui
(implements) (uses) (uses)
wgpu/hal
Expand Down
49 changes: 29 additions & 20 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,35 @@

`gpucontext` is the shared foundation for the [gogpu](https://github.com/gogpu) ecosystem, providing interfaces and utilities for GPU resource sharing without circular dependencies.

## Current: v0.3.1
## Current: v0.8.0

**Status:** Released
**Status:** In Development

- Import gputypes v0.2.0 (webgpu.h spec-compliant enums)
- DeviceProvider interface
- EventSource interface (with IME support)
- Registry[T] generic
- WindowProvider interface (window geometry, DPI, redraw requests)
- PlatformProvider interface (clipboard, cursor, dark mode, accessibility)
- CursorShape enum (12 standard cursor shapes)
- NullWindowProvider / NullPlatformProvider for testing

## Released

### v0.7.0 (2026-02-05)
- TextureUpdater interface for dynamic texture content

### v0.6.0 (2026-01-31)
- Gesture events (GestureEvent, GestureEventSource)

### v0.5.0 (2026-01-31)
- W3C Pointer Events Level 3
- Scroll events with delta modes
- CI/CD infrastructure

### v0.4.0 (2026-01-30)
- Texture interfaces (Texture, TextureDrawer, TextureCreator)
- Touch input support (multi-touch, pressure, radius)

### v0.3.1 (2026-01-29)
- Update gputypes to v0.2.0

### v0.3.0 (2026-01-29)
- Import gputypes for unified WebGPU types

Expand All @@ -24,21 +42,12 @@
### v0.1.1 (2026-01-27)
- Initial release with DeviceProvider, EventSource, Registry

## Planned: v0.4.0

**Focus:** Extended capabilities

- [ ] `Capabilities` interface for feature queries
- [ ] `ResourceLimits` struct for GPU limits
- [ ] `ShaderFormat` enum (WGSL, SPIR-V, GLSL)
- [ ] `BufferUsage`, `TextureUsage` flags

## Future Considerations

### v0.4.0 — Compute Support
- ComputeProvider interface
- WorkgroupLimits
- Storage buffer types
### v0.9.0 — Extended Capabilities
- Capabilities interface for feature queries
- ResourceLimits for GPU limits
- ShaderFormat enum (WGSL, SPIR-V, GLSL)

### v1.0.0 — API Freeze
- Stable API guarantee
Expand All @@ -48,7 +57,7 @@
## Non-Goals

- This package will **never** contain implementations
- This package will **never** have external dependencies
- This package will **never** have external dependencies (beyond gputypes)
- This package focuses on **interfaces**, not concrete types

## Contributing
Expand Down
5 changes: 3 additions & 2 deletions doc.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,9 @@
//
// - DeviceProvider: Interface for providing GPU device and queue
// - EventSource: Interface for window/input events (keyboard, mouse)
// - TouchEventSource: Interface for touch input (multi-touch, gestures)
// - PointerEventSource: Interface for unified pointer events (W3C Level 3)
// - PointerEventSource: Interface for unified pointer events (W3C Level 3, mouse+touch+pen)
// - WindowProvider: Interface for window geometry, DPI, and redraw requests
// - PlatformProvider: Interface for clipboard, cursor, dark mode, accessibility
// - ScrollEventSource: Interface for detailed scroll events
// - Texture: Minimal interface for GPU textures
// - TextureDrawer: Interface for drawing textures (2D rendering)
Expand Down
Loading
Loading