gpucontext

package module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 30, 2026 License: MIT Imports: 3 Imported by: 0

README

gpucontext

Shared GPU infrastructure for the gogpu ecosystem.

Overview

gpucontext provides interfaces and utilities for sharing GPU resources across multiple packages without circular dependencies.

Relationship to gputypes

Package Purpose Dependencies
gputypes WebGPU types (enums, structs, constants) ZERO
gpucontext Interfaces (DeviceProvider, EventSource, Texture) imports gputypes

gpucontext imports gputypes to use shared types in interface signatures, ensuring type compatibility across the ecosystem.

Installation

go get github.com/gogpu/gpucontext

Requires: Go 1.25+

Features

  • DeviceProvider — Interface for injecting GPU device and queue
  • EventSource — Interface for input events (keyboard, mouse, window, IME)
  • TouchEventSource — Interface for multi-touch input (mobile, tablets, touchscreens)
  • Texture — Minimal interface for GPU textures with TextureDrawer/TextureCreator
  • IME Support — Input Method Editor for CJK languages (Chinese, Japanese, Korean)
  • Registry[T] — Generic registry with priority-based backend selection
  • WebGPU Interfaces — Device, Queue, Adapter, Surface interfaces
  • WebGPU Types — Re-exports from gputypes (TextureFormat, etc.)

Usage

DeviceProvider Pattern

The DeviceProvider interface enables dependency injection of GPU capabilities:

// In gogpu/gogpu - implements DeviceProvider
type App struct {
    device gpucontext.Device
    queue  gpucontext.Queue
}

func (app *App) Device() gpucontext.Device       { return app.device }
func (app *App) Queue() gpucontext.Queue         { return app.queue }
func (app *App) SurfaceFormat() gpucontext.TextureFormat { return app.format }
func (app *App) Adapter() gpucontext.Adapter     { return app.adapter }

// In gogpu/gg - uses DeviceProvider
func NewGPUCanvas(provider gpucontext.DeviceProvider) *Canvas {
    return &Canvas{
        device: provider.Device(),
        queue:  provider.Queue(),
    }
}
EventSource (for UI frameworks)

EventSource enables UI frameworks to receive input events from host applications:

// In gogpu/ui - uses EventSource
func (ui *UI) AttachEvents(source gpucontext.EventSource) {
    source.OnKeyPress(func(key gpucontext.Key, mods gpucontext.Modifiers) {
        ui.focused.HandleKeyDown(key, mods)
    })

    source.OnMousePress(func(button gpucontext.MouseButton, x, y float64) {
        widget := ui.hitTest(x, y)
        widget.HandleMouseDown(button, x, y)
    })
}

// In gogpu/gogpu - implements EventSource
type App struct {
    keyHandlers []func(gpucontext.Key, gpucontext.Modifiers)
}

func (app *App) OnKeyPress(fn func(gpucontext.Key, gpucontext.Modifiers)) {
    app.keyHandlers = append(app.keyHandlers, fn)
}
IME Support (CJK Input)

IMEState and related interfaces enable Input Method Editor support for Chinese, Japanese, and Korean input:

// In gogpu/ui - handle IME composition
func (input *TextInput) AttachIME(source gpucontext.EventSource) {
    source.OnIMECompositionStart(func() {
        input.showCompositionWindow()
    })

    source.OnIMECompositionUpdate(func(state gpucontext.IMEState) {
        // Show composition text with cursor
        input.setCompositionText(state.CompositionText, state.CursorPos)
    })

    source.OnIMECompositionEnd(func(committed string) {
        // Insert final text
        input.insertText(committed)
        input.hideCompositionWindow()
    })
}

// Control IME position (for composition window placement)
func (input *TextInput) Focus(controller gpucontext.IMEController) {
    controller.SetIMEEnabled(true)
    controller.SetIMEPosition(input.cursorX, input.cursorY)
}
Texture Interface

Texture provides a minimal interface for GPU textures, enabling sharing between packages:

// Texture is a minimal interface for GPU textures
type Texture interface {
    Width() int
    Height() int
}

// TextureDrawer can draw textures (implemented by renderers)
type TextureDrawer interface {
    DrawTexture(tex Texture, x, y float32) error
    DrawTextureEx(tex Texture, opts TextureDrawOptions) error
}

// TextureCreator can create textures from pixel data
type TextureCreator interface {
    CreateTexture(width, height int, pixels []byte) (Texture, error)
}

Usage in integration packages:

// In gg/integration/ggcanvas - creates textures from CPU canvas
func (c *Canvas) Flush() (gpucontext.Texture, error) {
    pixels := c.pixmap.Pix()
    return c.creator.CreateTexture(c.width, c.height, pixels)
}

// In gogpu - implements TextureDrawer
func (ctx *Context) DrawTexture(tex gpucontext.Texture, x, y float32) error {
    return ctx.renderer.DrawTexture(tex, x, y)
}
Touch Input (Multi-touch Support)

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

// Touch phases follow platform conventions (iOS, Android, W3C)
const (
    TouchBegan     // First contact
    TouchMoved     // Touch moved
    TouchEnded     // Touch lifted
    TouchCancelled // 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:

// 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.TouchCancelled:
                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:

import "github.com/gogpu/gpucontext"

// Create registry with priority order
var backends = gpucontext.NewRegistry[Backend](
    gpucontext.WithPriority("vulkan", "dx12", "metal", "gles", "software"),
)

// Register backends (typically in init())
func init() {
    backends.Register("vulkan", NewVulkanBackend)
    backends.Register("software", NewSoftwareBackend)
}

// Get best available backend
backend := backends.Best()

// Or get specific backend
vulkan := backends.Get("vulkan")

// Check availability
if backends.Has("vulkan") {
    // Vulkan is available
}

// List all available
names := backends.Available() // ["vulkan", "software"]

Dependency Graph

                   gputypes (ZERO deps)
                 All WebGPU types (100+)
                          │
                          ▼
                   gpucontext
                  (imports gputypes)
          DeviceProvider, EventSource, Texture
              TouchEventSource, Registry
                          │
          ┌───────────────┼───────────────┐
          │               │               │
          ▼               ▼               ▼
        gogpu            gg          born-ml/born
     (implements)      (uses)      (implements & uses)
          │
          ▼
       wgpu/hal

Ecosystem

Package Description
gogpu/gogpu Graphics framework, implements DeviceProvider
gogpu/gg 2D graphics, uses DeviceProvider
gogpu/wgpu Pure Go WebGPU implementation
born-ml/born ML framework, implements & uses

License

MIT License — see LICENSE for details.

Documentation

Overview

Package gpucontext provides shared GPU infrastructure for the gogpu ecosystem.

This package defines interfaces and utilities used across multiple gogpu projects to enable GPU resource sharing without circular dependencies:

  • DeviceProvider: Interface for providing GPU device and queue
  • EventSource: Interface for window/input events (keyboard, mouse)
  • TouchEventSource: Interface for touch input (multi-touch, gestures)
  • Texture: Minimal interface for GPU textures
  • TextureDrawer: Interface for drawing textures (2D rendering)
  • TextureCreator: Interface for creating textures from pixel data

Consumers

  • gogpu/gogpu: Implements DeviceProvider via App/Renderer
  • gogpu/gg: Uses DeviceProvider for GPU-accelerated 2D rendering
  • born-ml/born: Implements and uses for GPU compute

Design Principles

This package follows the wgpu ecosystem pattern where shared types are separated from implementation (cf. wgpu-types in Rust).

The key insight is that GPU context (device + queue + related state) is a universal concept across Vulkan, CUDA, OpenGL, and WebGPU. By defining a minimal interface here, different packages can share GPU resources without depending on each other.

Example Usage 

// In gogpu/gogpu - implements DeviceProvider
func (app *App) Device() gpucontext.Device { return app.renderer.device }
func (app *App) Queue() gpucontext.Queue { return app.renderer.queue }

// In gogpu/gg - uses DeviceProvider
func NewGPUCanvas(provider gpucontext.DeviceProvider) *Canvas {
    return &Canvas{
        device: provider.Device(),
        queue:  provider.Queue(),
    }
}

Reference: https://github.com/gogpu/gpucontext

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Adapter 

type Adapter interface {
}

Adapter represents a physical GPU. Implemented by wgpu/hal.Adapter.

type Device 

type Device interface {
	// Poll processes pending operations.
	Poll(wait bool)

	// Destroy releases the device resources.
	Destroy()
}

Device represents a logical GPU device. Implemented by wgpu/hal.Device.

type DeviceHandle 

type DeviceHandle = DeviceProvider

DeviceHandle is an alias for DeviceProvider for backward compatibility. Deprecated: Use DeviceProvider instead.

type DeviceProvider 

type DeviceProvider interface {
	// Device returns the WebGPU device handle.
	// The device is used for creating GPU resources (buffers, textures, pipelines).
	Device() Device

	// Queue returns the WebGPU command queue.
	// The queue is used for submitting command buffers to the GPU.
	Queue() Queue

	// SurfaceFormat returns the preferred texture format for the surface.
	// May return gputypes.TextureFormatUndefined if no surface is attached (headless mode).
	// This is useful for creating render targets that match the surface format.
	SurfaceFormat() gputypes.TextureFormat

	// Adapter returns the WebGPU adapter (optional, may be nil).
	// The adapter provides information about the GPU capabilities.
	// Some implementations may not expose the adapter.
	Adapter() Adapter
}

DeviceProvider provides access to GPU device, queue, and related resources. This interface enables dependency injection of GPU capabilities between packages without circular dependencies.

Implementations:

  • gogpu.App implements DeviceProvider via renderer
  • born.Session implements DeviceProvider for ML compute

Example usage in gg: 

import (
    "github.com/gogpu/gpucontext"
    "github.com/gogpu/gputypes"
)

func NewGPUCanvas(provider gpucontext.DeviceProvider) *Canvas {
    format := provider.SurfaceFormat() // returns gputypes.TextureFormat
    return &Canvas{
        device: provider.Device(),
        queue:  provider.Queue(),
        format: format,
    }
}

type EventSource 

type EventSource interface {

	// OnKeyPress registers a callback for key press events.
	OnKeyPress(func(key Key, mods Modifiers))

	// OnKeyRelease registers a callback for key release events.
	OnKeyRelease(func(key Key, mods Modifiers))

	// OnTextInput registers a callback for text input events.
	// Text input is the result of key presses after applying keyboard layouts
	// and input methods. This is the preferred way to handle text entry.
	OnTextInput(func(text string))

	// OnMouseMove registers a callback for mouse movement.
	OnMouseMove(func(x, y float64))

	// OnMousePress registers a callback for mouse button press.
	OnMousePress(func(button MouseButton, x, y float64))

	// OnMouseRelease registers a callback for mouse button release.
	OnMouseRelease(func(button MouseButton, x, y float64))

	// OnScroll registers a callback for scroll wheel events.
	// dx and dy are the scroll deltas (positive = right/down).
	OnScroll(func(dx, dy float64))

	// OnResize registers a callback for window resize.
	OnResize(func(width, height int))

	// OnFocus registers a callback for focus change.
	OnFocus(func(focused bool))

	// OnIMECompositionStart registers a callback for when IME composition begins.
	// This is called when the user starts typing in an IME (e.g., for CJK input).
	OnIMECompositionStart(fn func())

	// OnIMECompositionUpdate registers a callback for IME composition updates.
	// Called during composition with the current state (preview text, cursor).
	OnIMECompositionUpdate(fn func(state IMEState))

	// OnIMECompositionEnd registers a callback for when IME composition ends.
	// The committed parameter contains the final text that should be inserted.
	OnIMECompositionEnd(fn func(committed string))
}

EventSource provides input events from the host application to UI frameworks.

This interface enables UI frameworks (like gogpu/ui) to receive user input events from the host window system. The host application (e.g., gogpu.App) implements EventSource and passes it to the UI layer.

Event callbacks are invoked on the main thread during the event loop. Callback functions should be fast and non-blocking.

Example usage in a UI framework: 

func (ui *UI) AttachEvents(source gpucontext.EventSource) {
    source.OnMousePress(func(button MouseButton, x, y float64) {
        widget := ui.hitTest(x, y)
        if widget != nil {
            widget.HandleMouseDown(button, x, y)
        }
    })

    source.OnKeyPress(func(key Key, mods Modifiers) {
        ui.focused.HandleKeyDown(key, mods)
    })
}

Note: This interface is designed for gogpu ↔ ui integration. The rendering library (gg) does NOT use this interface.

type IMEController added in v0.2.0 

type IMEController interface {
	// SetIMEPosition tells the platform where to show the IME candidate window.
	// The coordinates are in screen pixels relative to the window.
	SetIMEPosition(x, y int)

	// SetIMEEnabled enables or disables IME for the current input context.
	// When disabled, key presses are delivered directly without IME processing.
	// This is useful for password fields or non-text inputs.
	SetIMEEnabled(enabled bool)
}

IMEController allows widgets to control IME behavior. This interface is typically implemented by the host window system.

type IMEState added in v0.2.0 

type IMEState struct {
	// Composing indicates whether IME is currently in composition mode.
	Composing bool

	// CompositionText is the text currently being composed (e.g., pinyin for Chinese).
	// This should be displayed inline at the cursor position with special styling.
	CompositionText string

	// CursorPos is the cursor position within the composition text.
	CursorPos int

	// SelectionStart is the start of the selection within the composition text.
	// This is used for candidate selection in some IME systems.
	SelectionStart int

	// SelectionEnd is the end of the selection within the composition text.
	SelectionEnd int
}

IMEState represents the current state of the Input Method Editor. This is used for CJK (Chinese, Japanese, Korean) and other complex text input.

During IME composition, the user types phonetic characters that are converted to ideographic characters. The IMEState contains the current preview text and cursor information for rendering the composition inline.

type Instance 

type Instance interface {
}

Instance is the entry point for GPU operations. Implemented by wgpu/hal.Instance.

type Key 

type Key uint16

Key represents a keyboard key. Values follow a platform-independent virtual key code scheme. 

const (
	KeyUnknown Key = iota

	// Letters
	KeyA
	KeyB
	KeyC
	KeyD
	KeyE
	KeyF
	KeyG
	KeyH
	KeyI
	KeyJ
	KeyK
	KeyL
	KeyM
	KeyN
	KeyO
	KeyP
	KeyQ
	KeyR
	KeyS
	KeyT
	KeyU
	KeyV
	KeyW
	KeyX
	KeyY
	KeyZ

	// Numbers
	Key0
	Key1
	Key2
	Key3
	Key4
	Key5
	Key6
	Key7
	Key8
	Key9

	// Function keys
	KeyF1
	KeyF2
	KeyF3
	KeyF4
	KeyF5
	KeyF6
	KeyF7
	KeyF8
	KeyF9
	KeyF10
	KeyF11
	KeyF12

	// Navigation
	KeyEscape
	KeyTab
	KeyBackspace
	KeyEnter
	KeySpace
	KeyInsert
	KeyDelete
	KeyHome
	KeyEnd
	KeyPageUp
	KeyPageDown
	KeyLeft
	KeyRight
	KeyUp
	KeyDown

	// Modifiers (as keys, not modifiers)
	KeyLeftShift
	KeyRightShift
	KeyLeftControl
	KeyRightControl
	KeyLeftAlt
	KeyRightAlt
	KeyLeftSuper
	KeyRightSuper

	// Punctuation
	KeyMinus
	KeyEqual
	KeyLeftBracket
	KeyRightBracket
	KeyBackslash
	KeySemicolon
	KeyApostrophe
	KeyGrave
	KeyComma
	KeyPeriod
	KeySlash

	// Numpad
	KeyNumpad0
	KeyNumpad1
	KeyNumpad2
	KeyNumpad3
	KeyNumpad4
	KeyNumpad5
	KeyNumpad6
	KeyNumpad7
	KeyNumpad8
	KeyNumpad9
	KeyNumpadDecimal
	KeyNumpadDivide
	KeyNumpadMultiply
	KeyNumpadSubtract
	KeyNumpadAdd
	KeyNumpadEnter

	// Other
	KeyCapsLock
	KeyScrollLock
	KeyNumLock
	KeyPrintScreen
	KeyPause
)

Common key codes. These match typical USB HID usage codes for cross-platform compatibility.

type Modifiers 

type Modifiers uint8

Modifiers represents keyboard modifier keys. 

const (
	// ModShift indicates the Shift key is pressed.
	ModShift Modifiers = 1 << iota

	// ModControl indicates the Control key is pressed.
	ModControl

	// ModAlt indicates the Alt key is pressed (Option on macOS).
	ModAlt

	// ModSuper indicates the Super key is pressed (Windows/Command).
	ModSuper

	// ModCapsLock indicates Caps Lock is active.
	ModCapsLock

	// ModNumLock indicates Num Lock is active.
	ModNumLock
)

func (Modifiers) HasAlt 

func (m Modifiers) HasAlt() bool

HasAlt returns true if the Alt modifier is set.

func (Modifiers) HasControl 

func (m Modifiers) HasControl() bool

HasControl returns true if the Control modifier is set.

func (Modifiers) HasShift 

func (m Modifiers) HasShift() bool

HasShift returns true if the Shift modifier is set.

func (Modifiers) HasSuper 

func (m Modifiers) HasSuper() bool

HasSuper returns true if the Super modifier is set.

type MouseButton 

type MouseButton uint8

MouseButton represents a mouse button. 

const (
	// MouseButtonLeft is the primary mouse button.
	MouseButtonLeft MouseButton = iota

	// MouseButtonRight is the secondary mouse button.
	MouseButtonRight

	// MouseButtonMiddle is the middle mouse button (scroll wheel click).
	MouseButtonMiddle

	// MouseButton4 is an extra mouse button.
	MouseButton4

	// MouseButton5 is an extra mouse button.
	MouseButton5
)

type NullEventSource 

type NullEventSource struct{}

NullEventSource is an EventSource that ignores all event registrations. Used when events are not needed.

func (NullEventSource) OnFocus 

func (NullEventSource) OnFocus(func(bool))

OnFocus does nothing.

func (NullEventSource) OnIMECompositionEnd added in v0.2.0 

func (NullEventSource) OnIMECompositionEnd(func(string))

OnIMECompositionEnd does nothing.

func (NullEventSource) OnIMECompositionStart added in v0.2.0 

func (NullEventSource) OnIMECompositionStart(func())

OnIMECompositionStart does nothing.

func (NullEventSource) OnIMECompositionUpdate added in v0.2.0 

func (NullEventSource) OnIMECompositionUpdate(func(IMEState))

OnIMECompositionUpdate does nothing.

func (NullEventSource) OnKeyPress 

func (NullEventSource) OnKeyPress(func(Key, Modifiers))

OnKeyPress does nothing.

func (NullEventSource) OnKeyRelease 

func (NullEventSource) OnKeyRelease(func(Key, Modifiers))

OnKeyRelease does nothing.

func (NullEventSource) OnMouseMove 

func (NullEventSource) OnMouseMove(func(float64, float64))

OnMouseMove does nothing.

func (NullEventSource) OnMousePress 

func (NullEventSource) OnMousePress(func(MouseButton, float64, float64))

OnMousePress does nothing.

func (NullEventSource) OnMouseRelease 

func (NullEventSource) OnMouseRelease(func(MouseButton, float64, float64))

OnMouseRelease does nothing.

func (NullEventSource) OnResize 

func (NullEventSource) OnResize(func(int, int))

OnResize does nothing.

func (NullEventSource) OnScroll 

func (NullEventSource) OnScroll(func(float64, float64))

OnScroll does nothing.

func (NullEventSource) OnTextInput 

func (NullEventSource) OnTextInput(func(string))

OnTextInput does nothing.

type NullTouchEventSource added in v0.4.0 

type NullTouchEventSource struct{}

NullTouchEventSource implements TouchEventSource by ignoring all registrations. Useful for platforms or configurations where touch input is not available.

func (NullTouchEventSource) OnTouch added in v0.4.0 

func (NullTouchEventSource) OnTouch(func(TouchEvent))

OnTouch does nothing.

type OpenDevice 

type OpenDevice struct {
	Device Device
	Queue  Queue
}

OpenDevice bundles a device and queue together. This is a convenience type for initialization.

type Queue 

type Queue interface {
}

Queue represents a GPU command queue. Implemented by wgpu/hal.Queue.

type Registry 

type Registry[T any] struct {
	// contains filtered or unexported fields
}

Registry provides thread-safe registration and lookup of named factories. It supports priority-based selection when multiple implementations exist.

Type parameter T is the type returned by factories.

Example: 

var backends = gpucontext.NewRegistry[Backend](
    gpucontext.WithPriority("vulkan", "dx12", "metal", "gles", "software"),
)

backends.Register("vulkan", func() Backend { return NewVulkanBackend() })
backends.Register("software", func() Backend { return NewSoftwareBackend() })

best := backends.Best() // Returns vulkan if available, otherwise software

func NewRegistry 

func NewRegistry[T any](opts ...RegistryOption) *Registry[T]

NewRegistry creates a new Registry with optional configuration.

func (*Registry[T]) Available 

func (r *Registry[T]) Available() []string

Available returns all registered names. Thread-safe.

func (*Registry[T]) Best 

func (r *Registry[T]) Best() T

Best returns the highest-priority registered implementation. Returns the zero value of T if no implementations are registered. Thread-safe.

func (*Registry[T]) BestName 

func (r *Registry[T]) BestName() string

BestName returns the name of the highest-priority registered implementation. Returns empty string if no implementations are registered. Thread-safe.

func (*Registry[T]) Count 

func (r *Registry[T]) Count() int

Count returns the number of registered factories. Thread-safe.

func (*Registry[T]) Get 

func (r *Registry[T]) Get(name string) T

Get returns the factory output for the given name. Returns the zero value of T if not found. Thread-safe.

func (*Registry[T]) Has 

func (r *Registry[T]) Has(name string) bool

Has returns true if a factory with the given name is registered. Thread-safe.

func (*Registry[T]) Register 

func (r *Registry[T]) Register(name string, factory func() T)

Register adds a factory for the given name. If a factory with the same name already exists, it is replaced. Thread-safe.

func (*Registry[T]) Unregister 

func (r *Registry[T]) Unregister(name string)

Unregister removes the factory with the given name. Thread-safe.

type RegistryOption 

type RegistryOption func(*registryConfig)

RegistryOption configures a Registry.

func WithPriority 

func WithPriority(names ...string) RegistryOption

WithPriority sets the priority order for backend selection. Backends listed first are preferred over backends listed later. Backends not in the list have lowest priority (in registration order).

type Surface 

type Surface interface {
}

Surface represents a rendering surface (window). Implemented by wgpu/hal.Surface.

type Texture added in v0.4.0 

type Texture interface {
	// Width returns the texture width in pixels.
	Width() int

	// Height returns the texture height in pixels.
	Height() int
}

Texture is the minimal interface for GPU textures. This interface enables type-safe cross-package texture handling without circular dependencies.

Implementations:

  • gogpu.Texture implements Texture

Design note: This interface intentionally contains only read-only methods that are universally needed for texture operations. Implementation-specific methods (like UpdateData) remain on concrete types.

type TextureCreator added in v0.4.0 

type TextureCreator interface {
	// NewTextureFromRGBA creates a texture from RGBA pixel data.
	// The data must be width * height * 4 bytes (RGBA, 8 bits per channel).
	//
	// The returned Texture can be drawn using TextureDrawer.DrawTexture.
	//
	// Returns error if:
	//   - Data size doesn't match width * height * 4
	//   - GPU texture creation fails
	NewTextureFromRGBA(width, height int, data []byte) (Texture, error)
}

TextureCreator provides texture creation from raw pixel data. This interface enables packages to create GPU textures without depending directly on specific GPU implementations.

Implementations:

  • gogpu.Renderer implements TextureCreator (via adapter)

Example usage: 

creator := drawer.TextureCreator()
tex, err := creator.NewTextureFromRGBA(800, 600, pixelData)
if err != nil {
    return err
}
drawer.DrawTexture(tex, 0, 0)

type TextureDrawer added in v0.4.0 

type TextureDrawer interface {
	// DrawTexture draws a texture at the specified position.
	//
	// Coordinate system:
	//   - (0, 0) is the top-left corner
	//   - Positive X goes right
	//   - Positive Y goes down
	//   - Coordinates are in pixels
	//
	// The texture must have been created by TextureCreator from this drawer.
	DrawTexture(tex Texture, x, y float32) error

	// TextureCreator returns the texture creator associated with this drawer.
	// Use this to create textures that can be drawn by this drawer.
	TextureCreator() TextureCreator
}

TextureDrawer provides texture drawing capabilities for 2D rendering. This interface enables packages like ggcanvas to draw textures without depending directly on gogpu, following the Dependency Inversion Principle.

Implementations:

  • gogpu.Context implements TextureDrawer (via adapter)

Example usage in ggcanvas: 

func (c *Canvas) RenderTo(drawer gpucontext.TextureDrawer) error {
    tex, _ := c.Flush()
    return drawer.DrawTexture(tex, 0, 0)
}

type TouchEvent added in v0.4.0 

type TouchEvent struct {
	// Phase indicates the lifecycle stage of the touches in Changed.
	Phase TouchPhase

	// Changed contains the touch points that triggered this event.
	// For TouchBegan: newly added touches
	// For TouchMoved: touches that moved
	// For TouchEnded: touches that were lifted
	// For TouchCancelled: touches that were interrupted
	Changed []TouchPoint

	// All contains all currently active touch points.
	// Useful for multi-touch gestures that need to track all contacts.
	// For TouchEnded/TouchCancelled, this excludes the Changed touches.
	All []TouchPoint

	// Modifiers contains keyboard modifier state at the time of the event.
	// Useful for modifier+touch combinations (e.g., Ctrl+drag for zoom).
	Modifiers Modifiers

	// Timestamp is the event time as duration since an arbitrary reference.
	// Useful for calculating velocities in fling gestures.
	// Zero if timestamps are not available on the platform.
	Timestamp time.Duration
}

TouchEvent represents a touch input event containing one or more touch points.

Multi-touch handling:

  • TouchBegan: Changed contains new touches, All contains all active touches
  • TouchMoved: Changed contains moved touches, All contains all active touches
  • TouchEnded: Changed contains lifted touches, All contains remaining touches
  • TouchCancelled: Changed contains cancelled touches, All may be empty

Example multi-touch pinch gesture processing: 

func handleTouch(ev gpucontext.TouchEvent) {
    if ev.Phase == gpucontext.TouchMoved && len(ev.All) == 2 {
        // Calculate distance between two fingers for pinch
        dx := ev.All[0].X - ev.All[1].X
        dy := ev.All[0].Y - ev.All[1].Y
        distance := math.Sqrt(dx*dx + dy*dy)
        // Use distance for zoom...
    }
}

type TouchEventSource added in v0.4.0 

type TouchEventSource interface {
	// OnTouch registers a callback for touch events.
	// The callback receives a TouchEvent containing all touch information.
	//
	// Callback threading: Called on the main/UI thread.
	// Callbacks should be fast and non-blocking.
	//
	// Touch events are delivered in order: Began -> Moved* -> Ended/Cancelled
	// Multi-touch events for simultaneous contacts are coalesced into single events.
	OnTouch(fn func(TouchEvent))
}

TouchEventSource extends EventSource with touch input capabilities. This interface is optional - not all EventSource implementations support touch input (e.g., desktop-only applications).

Implementation note: Rather than adding to EventSource directly, we use a separate interface to maintain backward compatibility and allow type assertion: 

if tes, ok := eventSource.(gpucontext.TouchEventSource); ok {
    tes.OnTouch(handleTouchEvent)
}

type TouchID added in v0.4.0 

type TouchID int

TouchID uniquely identifies a touch point within a touch session. The ID remains constant from TouchBegan through TouchEnded/TouchCancelled. IDs may be reused after a touch ends.

Design note: Using int for compatibility with both int32 (Android) and int64 (iOS). Matches Ebitengine pattern for familiarity.

type TouchPhase added in v0.4.0 

type TouchPhase uint8

TouchPhase represents the lifecycle stage of a touch point. These phases align with platform conventions:

  • Android: ACTION_DOWN/MOVE/UP/CANCEL
  • iOS: touchesBegan/Moved/Ended/Cancelled
  • W3C: touchstart/move/end/cancel
const (
	// TouchBegan indicates first contact with the touch surface.
	// Sent once per touch point at the start of interaction.
	TouchBegan TouchPhase = iota

	// TouchMoved indicates the touch point has moved.
	// Sent multiple times during drag/pan gestures.
	TouchMoved

	// TouchEnded indicates the touch point was lifted normally.
	// Sent once per touch point at the end of interaction.
	TouchEnded

	// TouchCancelled indicates the system interrupted the touch.
	// This can happen when:
	//   - The app loses focus
	//   - A system gesture is recognized (e.g., swipe to home)
	//   - The touch hardware reports an error
	// Always handle cancellation to reset UI state properly.
	TouchCancelled
)

func (TouchPhase) String added in v0.4.0 

func (p TouchPhase) String() string

String returns the phase name for debugging.

type TouchPoint added in v0.4.0 

type TouchPoint struct {
	// ID uniquely identifies this touch point within the session.
	// Track touches by ID, not by array index (indices can change).
	ID TouchID

	// X is the horizontal position in logical pixels.
	X float64

	// Y is the vertical position in logical pixels.
	Y float64

	// Pressure is the contact pressure, if supported by hardware.
	// Range: 0.0 (no pressure) to 1.0 (maximum pressure).
	// nil if pressure sensing is not available.
	//
	// Use case: Drawing apps, pressure-sensitive UI elements.
	Pressure *float32

	// Radius is the approximate contact radius in logical pixels.
	// Represents a circular approximation of the contact area.
	// nil if radius detection is not available.
	//
	// Use case: Distinguishing finger vs knuckle touches,
	// accessibility features for users with larger contact areas.
	Radius *float32
}

TouchPoint represents a single point of contact on a touch surface.

Position coordinates are in logical pixels relative to the window's content area. The coordinate system matches the graphics system:

  • Origin (0, 0) is at top-left
  • X increases rightward
  • Y increases downward

Design decisions:

  • Using float64 for sub-pixel precision (matches mouse events in EventSource)
  • Pressure/Radius are pointers to indicate optional support
  • No coordinate transformation - that's the UI layer's responsibility

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.