research: assess type aliases in wgpu public API — problems and recommendations

[kolkov]

The wgpu package exposes ~81 type aliases (type T = source.T) from gputypes (75) and hal (6) packages.

Go type aliases were designed for gradual code refactoring transitions, not permanent public API (Go Blog, Type Alias Proposal).

Potential problems

1. Leaking implementation — hal.Extent3D visible in godoc/errors instead of wgpu.Extent3D
2. No encapsulation — hal/gputypes changes automatically affect public API
3. Cannot add methods — aliases don't support wgpu-specific methods
4. Tight coupling — public API directly tied to internal package structure

Current state

// descriptor.go — HAL aliases (6 types, leaks implementation layer)
type Extent3D = hal.Extent3D
type Origin3D = hal.Origin3D
type DepthStencilState = hal.DepthStencilState

// types.go — gputypes aliases (75 types)
type TextureFormat = gputypes.TextureFormat
type BufferUsage = gputypes.BufferUsage
// ...

Research needed

Before any action, deep investigation is required:

1. Severity assessment — is this a real problem or cosmetic? Audit godoc, compiler errors, IDE behavior with actual aliases
2. HAL aliases vs gputypes aliases — different concerns. hal is implementation layer, gputypes is shared vocabulary. May need different treatment
3. Industry analysis — how do mature Go libraries handle multi-layer type exposure? (K8s client-go, gRPC-Go, Terraform SDK, etc.)
4. Go 1.24+ generic type aliases — does this change the calculus?
5. Breaking change scope — how many downstream call sites across gogpu, gg, ui?
6. Migration strategy — if fix is needed, gradual deprecation or major bump?

Deliverable

Research document with:

• Findings for each question
• Severity rating (cosmetic / moderate / critical)
• Recommendation: fix / accept / partial fix
• If fix: implementation plan. If accept: documented rationale.

References

• Go Blog: What's in an Alias Name
• Type Alias Proposal
• Dave Cheney: Use internal packages
• Discovered during PR [feat] Add WriteTexture to Queue #95 review

[kolkov]

Resolved in v0.21.0 (WGPU-API-002): all HAL type aliases replaced with proper struct definitions + toHAL() converters.