diff --git a/CHANGELOG.md b/CHANGELOG.md index cf761c6..568cc77 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,8 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.10.0] - 2026-03-15 + +### Removed + +- **HalProvider interface DELETED** — `HalDevice() any` and `HalQueue() any` removed entirely. + Replaced by typed pattern: `provider.Device()` returns `gpucontext.Device`, consumers + type-assert to `*wgpu.Device` for full API access. Zero `any` in the device provider chain. + Go "accept interfaces, return structs" pattern. + ### Changed +- **Device, Queue, Adapter, Surface, Instance** interfaces in webgpu_types.go converted to + minimal type-token interfaces. Enables implicit Go interface satisfaction — `*wgpu.Device` + implements `gpucontext.Device` without gpucontext importing wgpu. + - **WindowProvider.Size()** now documented as returning logical points (DIP) instead of physical pixels - Aligns with gogpu RETINA refactor: `App.Size()` returns logical coordinates - Physical pixel dimensions = `Size() * ScaleFactor()` diff --git a/README.md b/README.md index 50c03aa..05df2bc 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,7 @@ go get github.com/gogpu/gpucontext ## Features -- **DeviceProvider** — Interface for injecting GPU device and queue -- **HalProvider** — Optional direct access to HAL device/queue for GPU accelerators +- **DeviceProvider** — Interface for injecting GPU device and queue (typed, zero `any`) - **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.) @@ -66,26 +65,26 @@ func NewGPUCanvas(provider gpucontext.DeviceProvider) *Canvas { } ``` -### HalProvider (for GPU accelerators) +### Device Sharing (typed, zero `any`) -`HalProvider` is an optional interface on `DeviceProvider` that exposes low-level HAL types. -This enables GPU accelerators (like gg's SDF pipeline) to share the host device without creating their own: +GPU accelerators (like gg's SDF pipeline) share the host device via typed interfaces: ```go -// In gogpu/gg - GPU accelerator checks for HAL access +// Consumer gets typed device from provider func (a *SDFAccelerator) SetDeviceProvider(dp gpucontext.DeviceProvider) { - if hp, ok := dp.(gpucontext.HalProvider); ok { - device := hp.HalDevice().(hal.Device) - queue := hp.HalQueue().(hal.Queue) - a.initWithSharedDevice(device, queue) + dev := dp.Device() // gpucontext.Device (minimal interface) + wgpuDev, ok := dev.(*wgpu.Device) // type assert for full wgpu API + if ok { + a.initWithSharedDevice(wgpuDev) } } - -// In gogpu/gogpu - implements HalProvider -func (app *App) HalDevice() any { return app.halDevice } -func (app *App) HalQueue() any { return app.halQueue } ``` +The pattern follows Go's "accept interfaces, return structs": +- `gpucontext.Device` — minimal interface (type token) +- `*wgpu.Device` — concrete type, satisfies `gpucontext.Device` implicitly +- Consumer type-asserts when it needs the full API + ### WindowProvider (for UI frameworks and rendering libraries) The `WindowProvider` interface enables UI frameworks and rendering libraries to query @@ -290,7 +289,7 @@ names := backends.Available() // ["vulkan", "software"] ▼ gpucontext (imports gputypes) - DeviceProvider, HalProvider, + DeviceProvider, WindowProvider, PlatformProvider, EventSource, Texture, Registry │ diff --git a/hal_provider.go b/hal_provider.go deleted file mode 100644 index 9650925..0000000 --- a/hal_provider.go +++ /dev/null @@ -1,27 +0,0 @@ -// Copyright 2026 The gogpu Authors -// SPDX-License-Identifier: MIT - -package gpucontext - -// HalProvider is an optional interface for DeviceProviders that can expose -// low-level HAL types directly. This enables GPU accelerators to share -// devices without creating their own. -// -// The returned any values are hal.Device and hal.Queue from wgpu/hal. -// Consumers type-assert to the concrete hal types they need. -// -// Example usage: -// -// if hp, ok := provider.(gpucontext.HalProvider); ok { -// device := hp.HalDevice().(hal.Device) -// queue := hp.HalQueue().(hal.Queue) -// } -type HalProvider interface { - // HalDevice returns the underlying HAL device for direct GPU access. - // Returns nil if HAL access is not available. - HalDevice() any - - // HalQueue returns the underlying HAL queue for direct GPU access. - // Returns nil if HAL access is not available. - HalQueue() any -} diff --git a/webgpu_types.go b/webgpu_types.go index cdbcf9c..89b33dc 100644 --- a/webgpu_types.go +++ b/webgpu_types.go @@ -3,85 +3,64 @@ package gpucontext -// WebGPU Interface Definitions for Cross-Package Sharing +// WebGPU Type Token Interfaces for Cross-Package Sharing // -// This file defines interfaces that are implemented by wgpu/hal -// and used by consumers like gg, gogpu, and born-ml. +// This file defines type token interfaces for GPU objects (Device, Queue, etc.) +// that enable type-safe dependency injection between packages without coupling +// them to a specific GPU implementation. // -// Types (TextureFormat, BufferUsage, etc.) are in gputypes package. -// Interfaces (Device, Queue, etc.) are defined here as behavioral contracts. +// Concrete types (e.g., *wgpu.Device) satisfy these empty interfaces implicitly. +// Consumers type-assert to the concrete type when they need the full API. // -// Users should import both packages: +// Types (TextureFormat, BufferUsage, etc.) are in the gputypes package. +// +// Usage: // // import ( // "github.com/gogpu/gpucontext" // "github.com/gogpu/gputypes" // ) -// Device represents a logical GPU device. -// Implemented by wgpu/hal.Device. -type Device interface { - // Poll processes pending operations. - Poll(wait bool) - - // Destroy releases the device resources. - Destroy() -} - -// Queue represents a GPU command queue. -// Implemented by wgpu/hal.Queue. -type Queue interface { - // Submit submits command buffers for execution. - // Submit(commandBuffers []CommandBuffer) - - // WriteBuffer writes data to a buffer. - // WriteBuffer(buffer Buffer, offset uint64, data []byte) - - // WriteTexture writes data to a texture. - // WriteTexture(destination gputypes.ImageCopyTexture, data []byte, layout gputypes.TextureDataLayout, size gputypes.Extent3D) -} - -// Adapter represents a physical GPU. -// Implemented by wgpu/hal.Adapter. -type Adapter interface { - // RequestDevice requests a logical device from this adapter. - // RequestDevice(descriptor gputypes.DeviceDescriptor) (Device, Queue, error) - - // GetInfo returns information about this adapter. - // GetInfo() gputypes.AdapterInfo - - // Features returns the features supported by this adapter. - // Features() gputypes.Features - - // Limits returns the limits of this adapter. - // Limits() gputypes.Limits -} - -// Surface represents a rendering surface (window). -// Implemented by wgpu/hal.Surface. -type Surface interface { - // Configure configures the surface for rendering. - // Configure(device Device, config gputypes.SurfaceConfiguration) - - // GetCurrentTexture gets the current texture for rendering. - // GetCurrentTexture() (SurfaceTexture, error) - - // Present presents the current frame. - // Present() -} - -// Instance is the entry point for GPU operations. -// Implemented by wgpu/hal.Instance. -type Instance interface { - // CreateSurface creates a surface for a window. - // CreateSurface(descriptor SurfaceDescriptor) (Surface, error) - - // RequestAdapter requests a GPU adapter. - // RequestAdapter(options gputypes.RequestAdapterOptions) (Adapter, error) +// Device is a type token for a logical GPU device. +// +// Concrete implementations (e.g., *wgpu.Device) satisfy this interface +// implicitly. Consumers that need the full device API should type-assert +// to the concrete type: +// +// dev := provider.Device() +// wgpuDev, ok := dev.(*wgpu.Device) +// if ok { +// halDevice := wgpuDev.HalDevice() +// } +// +// The interface is intentionally minimal to avoid coupling gpucontext +// to any specific GPU implementation. +type Device interface{} - // EnumerateAdapters returns all available adapters. - // EnumerateAdapters() []Adapter -} +// Queue is a type token for a GPU command queue. +// +// Concrete implementations (e.g., *wgpu.Queue) satisfy this interface +// implicitly. Consumers that need the full queue API should type-assert +// to the concrete type: +// +// q := provider.Queue() +// wgpuQueue, ok := q.(*wgpu.Queue) +type Queue interface{} + +// Adapter is a type token for a physical GPU adapter. +// Consumers that need the full adapter API should type-assert +// to the concrete type (e.g., *wgpu.Adapter). +type Adapter interface{} + +// Surface is a type token for a rendering surface (window). +// Consumers that need the full surface API should type-assert +// to the concrete type (e.g., *wgpu.Surface). +type Surface interface{} + +// Instance is a type token for the GPU instance entry point. +// Consumers that need the full instance API should type-assert +// to the concrete type (e.g., *wgpu.Instance). +type Instance interface{} // OpenDevice bundles a device and queue together. // This is a convenience type for initialization.