Documentation
¶
Overview ¶
Package backend provides a pluggable rendering backend abstraction.
The backend package allows the gg library to support multiple rendering implementations. Currently, only the software backend is available, but this architecture enables future GPU-accelerated backends via gogpu/wgpu.
Backend Registration ¶
Backends are registered via init() functions and selected at runtime. The software backend is automatically registered on import:
import _ "github.com/gogpu/gg/backend"
Backend Selection ¶
Use Default() to get the best available backend, or Get() to request a specific backend by name:
// Get the default (best available) backend
b := backend.Default()
// Or request a specific backend
b := backend.Get("software")
Usage with Context ¶
The backend provides renderers that implement gg.Renderer:
b := backend.Default()
if err := b.Init(); err != nil {
log.Fatal(err)
}
defer b.Close()
renderer := b.NewRenderer(800, 600)
Retained Mode Rendering ¶
For complex scenes, use RenderScene for optimized rendering:
scene := scene.NewScene()
scene.Fill(scene.FillNonZero, scene.IdentityAffine(),
scene.SolidBrush(gg.Red), circle)
pixmap := gg.NewPixmap(800, 600)
if err := b.RenderScene(pixmap, scene); err != nil {
log.Fatal(err)
}
Available Backends ¶
- "software": CPU-based scanline rasterizer (always available) - "wgpu": GPU-accelerated via gogpu/wgpu (future)
Index ¶
- Constants
- Variables
- func Available() []string
- func IsRegistered(name string) bool
- func Register(name string, factory BackendFactory)
- func Unregister(name string)
- type BackendFactory
- type RenderBackend
- type SoftwareBackend
- func (b *SoftwareBackend) Close()
- func (b *SoftwareBackend) Init() error
- func (b *SoftwareBackend) Name() string
- func (b *SoftwareBackend) NewRenderer(width, height int) gg.Renderer
- func (b *SoftwareBackend) RenderScene(target *gg.Pixmap, s *scene.Scene) error
- func (b *SoftwareBackend) SceneRenderer() *scene.Renderer
Constants ¶
const ( // BackendSoftware is the name of the CPU-based software backend. BackendSoftware = "software" // BackendNative is the name of the Pure Go GPU backend (gogpu/wgpu). BackendNative = "native" // BackendRust is the name of the Rust GPU backend (go-webgpu/webgpu FFI). BackendRust = "rust" // BackendGo is an alias for BackendNative (user convenience). BackendGo = BackendNative )
Backend name constants.
Variables ¶
var ( // ErrBackendNotAvailable is returned when a requested backend is not available. ErrBackendNotAvailable = errors.New("backend: not available") // ErrNotInitialized is returned when operations are called before Init. ErrNotInitialized = errors.New("backend: not initialized") )
Common backend errors.
Functions ¶
func IsRegistered ¶
IsRegistered checks if a backend with the given name is registered.
func Register ¶
func Register(name string, factory BackendFactory)
Register registers a backend factory with the given name. This is typically called from init() functions in backend packages. If a backend with the same name is already registered, it will be replaced.
func Unregister ¶
func Unregister(name string)
Unregister removes a backend from the registry. This is useful for testing.
Types ¶
type BackendFactory ¶
type BackendFactory func() RenderBackend
BackendFactory creates a new backend instance.
type RenderBackend ¶
type RenderBackend interface {
// Name returns the backend identifier (e.g., "software", "wgpu").
Name() string
// Init initializes the backend.
// This should be called before any rendering operations.
Init() error
// Close releases all backend resources.
// The backend should not be used after Close is called.
Close()
// NewRenderer creates a renderer for immediate mode rendering.
// The renderer is sized for the given dimensions and can be
// used with gg.Context for drawing operations.
NewRenderer(width, height int) gg.Renderer
// RenderScene renders a scene to the target pixmap using retained mode.
// This is more efficient for complex scenes as it can optimize
// the rendering pipeline.
RenderScene(target *gg.Pixmap, s *scene.Scene) error
}
RenderBackend is the interface for rendering backends. It abstracts the rendering implementation, allowing the library to support multiple backends (software, GPU via wgpu, etc.).
Backends must be registered via Register() and are selected via Get() or Default().
func Default ¶
func Default() RenderBackend
Default returns the best available backend based on priority. Priority order: wgpu > software Returns nil if no backends are registered.
func Get ¶
func Get(name string) RenderBackend
Get returns a backend instance by name. Returns nil if the backend is not registered.
func InitDefault ¶
func InitDefault() (RenderBackend, error)
InitDefault initializes the default backend based on availability. This is called automatically when using gg.NewContext() without explicit backend selection.
func MustDefault ¶
func MustDefault() RenderBackend
MustDefault returns the default backend or panics.
type SoftwareBackend ¶
type SoftwareBackend struct {
// contains filtered or unexported fields
}
SoftwareBackend is a CPU-based rendering backend. It wraps the existing SoftwareRenderer for immediate mode and scene.Renderer for retained mode rendering.
func NewSoftwareBackend ¶
func NewSoftwareBackend() *SoftwareBackend
NewSoftwareBackend creates a new software rendering backend.
func (*SoftwareBackend) Close ¶
func (b *SoftwareBackend) Close()
Close releases all backend resources.
func (*SoftwareBackend) Name ¶
func (b *SoftwareBackend) Name() string
Name returns the backend identifier.
func (*SoftwareBackend) NewRenderer ¶
func (b *SoftwareBackend) NewRenderer(width, height int) gg.Renderer
NewRenderer creates a renderer for immediate mode rendering. This wraps gg.NewSoftwareRenderer to provide a gg.Renderer interface.
func (*SoftwareBackend) RenderScene ¶
RenderScene renders a scene to the target pixmap using retained mode. This uses parallel tile-based rendering for efficiency.
func (*SoftwareBackend) SceneRenderer ¶
func (b *SoftwareBackend) SceneRenderer() *scene.Renderer
SceneRenderer returns the underlying scene renderer for advanced usage. Returns nil if no scene has been rendered yet.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package native provides a Pure Go GPU-accelerated rendering backend using gogpu/wgpu.
|
Package native provides a Pure Go GPU-accelerated rendering backend using gogpu/wgpu. |
|
Package rust provides a GPU-accelerated rendering backend using go-webgpu/webgpu.
|
Package rust provides a GPU-accelerated rendering backend using go-webgpu/webgpu. |