gpu

package
v0.1.3 Latest Latest
Warning

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

 Go to latest Published: Jul 30, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package gpu manages wgpu pipeline state for the g3d forward renderer.

This package operates on wgpu types and raw byte slices. It does NOT import the g3d root package — all data arrives as [16]float32 (matrices), []byte (uniform data), or gputypes constants. This prevents circular dependencies.

Index

Constants

View Source 
const (
	ShaderBasic    = "basic"
	ShaderStandard = "standard"
)

Shader ID constants used for pipeline keying.

View Source 
const (
	// FrameUniformsSize is the byte size of the FrameUniforms struct (224 bytes).
	FrameUniformsSize = 224

	// ObjectUniformsSize is the byte size of the ObjectUniforms struct (128 bytes).
	ObjectUniformsSize = 128

	// MaxLights is the maximum number of lights per frame (matches WGSL array size).
	MaxLights = 4
)

Uniform buffer sizes must match WGSL struct layouts byte-for-byte.

Variables

This section is empty.

Functions

func DefaultPrimitive 

func DefaultPrimitive(doubleSided bool) gputypes.PrimitiveState

DefaultPrimitive returns a PrimitiveState for triangle list rendering. When doubleSided is true, culling is disabled; otherwise back-face culling is enabled with counter-clockwise front face (WebGPU default).

func NoMultisample 

func NoMultisample() gputypes.MultisampleState

NoMultisample returns a MultisampleState with count=1 (no MSAA). Phase 1 does not use MSAA; it can be added in Phase 2.

func OpaqueDepthStencil 

func OpaqueDepthStencil(depthFormat gputypes.TextureFormat) *wgpu.DepthStencilState

OpaqueDepthStencil returns a DepthStencilState configured for standard opaque 3D rendering: depth test enabled (Less), depth write enabled, no stencil.

g3d uses Depth24Plus (no stencil) unlike gg which uses Depth24PlusStencil8 for stencil-then-cover path clipping. 3D opaque rendering does not need stencil.

func PackFrameUniforms 

func PackFrameUniforms(data *FrameUniformsData) []byte

PackFrameUniforms encodes FrameUniformsData as 224 bytes in little-endian format for GPU upload.

func PackObjectUniforms 

func PackObjectUniforms(data *ObjectUniformsData) []byte

PackObjectUniforms encodes ObjectUniformsData as 128 bytes in little-endian format for GPU upload.

func StandardVertexLayout 

func StandardVertexLayout() []gputypes.VertexBufferLayout

StandardVertexLayout returns the vertex buffer layout for the standard 3D vertex format: position(vec3, loc 0) + normal(vec3, loc 1) + uv(vec2, loc 2). Stride: 32 bytes.

Types

type FrameUniformsData 

type FrameUniformsData struct {
	ViewProjection [16]float32
	CameraPosition [4]float32
	Lights         [MaxLights]LightData
	LightCount     uint32
	Pad            [3]uint32
}

FrameUniformsData holds per-frame data for GPU upload. Layout matches the WGSL FrameUniforms struct (224 bytes total). 

offset   0: ViewProjection [16]float32 (64 bytes)
offset  64: CameraPosition [4]float32  (16 bytes — vec4, NOT vec3!)
offset  80: Lights         [4]LightData (128 bytes)
offset 208: LightCount     uint32       (4 bytes)
offset 212: Pad            [3]uint32    (12 bytes)

type GPUState 

type GPUState struct {
	// contains filtered or unexported fields
}

GPUState manages the wgpu device and associated GPU caches (shaders, pipelines). It supports two initialization modes:

  1. External device — injected via SetDeviceProvider (used when g3d runs inside gogpu).
  2. Standalone — created lazily via EnsureDevice (used for headless/test scenarios).

The design follows the gg/internal/gpu/gpu_shared.go pattern exactly.

func NewGPUState 

func NewGPUState() *GPUState

NewGPUState creates an uninitialized GPUState. Call SetDeviceProvider or EnsureDevice before using GPU resources.

func (*GPUState) Close 

func (g *GPUState) Close()

Close releases all GPU resources in the correct order:

  1. Pipeline cache (pipelines + layouts + bind group layouts)
  2. Shader cache (shader modules)
  3. Device/Instance (only if standalone, external=false)

Follows gg/internal/gpu/gpu_shared.go:216-257 cleanup order.

func (*GPUState) Device 

func (g *GPUState) Device() *wgpu.Device

Device returns the wgpu device, or nil if not initialized.

func (*GPUState) EnsureDevice 

func (g *GPUState) EnsureDevice() error

EnsureDevice lazily creates a standalone wgpu device if none has been set. This is used for headless testing or standalone rendering without gogpu.

func (*GPUState) IsReady 

func (g *GPUState) IsReady() bool

IsReady reports whether the GPU is initialized and ready for rendering.

func (*GPUState) Pipelines 

func (g *GPUState) Pipelines() *PipelineCache

Pipelines returns the pipeline cache.

func (*GPUState) Queue 

func (g *GPUState) Queue() *wgpu.Queue

Queue returns the wgpu queue, or nil if not initialized.

func (*GPUState) SetDeviceDirect 

func (g *GPUState) SetDeviceDirect(device *wgpu.Device, queue *wgpu.Queue) error

SetDeviceDirect configures the GPUState with an explicit device and queue. Used by NewRendererFromDevice for standalone mode without a full DeviceProvider.

func (*GPUState) SetDeviceProvider 

func (g *GPUState) SetDeviceProvider(provider gpucontext.DeviceProvider) error

SetDeviceProvider configures the GPUState to use a shared GPU device from an external provider (e.g., gogpu.App). The provider's Device() must return a *wgpu.Device.

This follows the gg/internal/gpu/gpu_shared.go:124-189 pattern exactly:

  1. Check for software adapter -> return error
  2. Type-assert provider.Device() to *wgpu.Device
  3. Get queue
  4. Destroy own resources if previously initialized
  5. Store external device, create shader + pipeline caches
  6. Set ready = true

func (*GPUState) Shaders 

func (g *GPUState) Shaders() *ShaderCache

Shaders returns the shader cache.

type LightData 

type LightData struct {
	Direction [3]float32
	LightType uint32
	Color     [3]float32
	Intensity float32
}

LightData is the GPU-side representation of a single light source. Layout matches the WGSL LightData struct (32 bytes, 16-byte aligned). 

offset  0: Direction [3]float32 (12 bytes)
offset 12: LightType uint32     (4 bytes)
offset 16: Color     [3]float32 (12 bytes)
offset 28: Intensity float32    (4 bytes)

type ObjectUniformsData 

type ObjectUniformsData struct {
	Model       [16]float32
	NormalModel [16]float32
}

ObjectUniformsData holds per-object data for GPU upload. Layout matches the WGSL ObjectUniforms struct (128 bytes total). 

offset  0: Model       [16]float32 (64 bytes)
offset 64: NormalModel  [16]float32 (64 bytes)

type PipelineBundle 

type PipelineBundle struct {
	Pipeline       *wgpu.RenderPipeline
	FrameLayout    *wgpu.BindGroupLayout // group 0 — per-frame uniforms
	ObjectLayout   *wgpu.BindGroupLayout // group 1 — per-object + per-material uniforms
	PipelineLayout *wgpu.PipelineLayout
}

PipelineBundle holds a compiled render pipeline and its associated layouts. All resources in the bundle are released together via the PipelineCache.

type PipelineCache 

type PipelineCache struct {
	// contains filtered or unexported fields
}

PipelineCache creates and caches render pipelines keyed by PipelineKey. Pipelines are created on first request and reused for all subsequent frames.

func NewPipelineCache 

func NewPipelineCache(device *wgpu.Device, shaders *ShaderCache) *PipelineCache

NewPipelineCache creates a pipeline cache backed by the given device and shaders.

func (*PipelineCache) Close 

func (c *PipelineCache) Close()

Close releases all cached pipelines and layouts in reverse creation order.

func (*PipelineCache) Get 

func (c *PipelineCache) Get(key PipelineKey) (*PipelineBundle, error)

Get returns the cached pipeline bundle for the given key, creating it on first access. Returns an error if pipeline creation fails.

type PipelineKey 

type PipelineKey struct {
	ShaderID      string
	SurfaceFormat gputypes.TextureFormat
	DepthFormat   gputypes.TextureFormat
	DoubleSided   bool
}

PipelineKey identifies a unique render pipeline configuration. Pipelines with the same key share a single GPU pipeline object.

The key captures all state that affects pipeline compilation:

  • ShaderID: which shader module ("basic" or "standard")
  • SurfaceFormat: the color target format (e.g., BGRA8Unorm)
  • DepthFormat: the depth attachment format (e.g., Depth24Plus)
  • DoubleSided: whether back-face culling is disabled

type ShaderCache 

type ShaderCache struct {
	// contains filtered or unexported fields
}

ShaderCache compiles and caches WGSL shader modules. Modules are compiled once at creation time and reused for all pipeline creation and rendering.

func NewShaderCache 

func NewShaderCache(device *wgpu.Device) (*ShaderCache, error)

NewShaderCache compiles the built-in shaders (basic, standard) and returns a cache. Returns an error if any shader fails to compile.

func (*ShaderCache) Close 

func (c *ShaderCache) Close()

Close releases all cached shader modules.

func (*ShaderCache) Get 

func (c *ShaderCache) Get(name string) *wgpu.ShaderModule

Get returns the cached ShaderModule for the given name, or nil if not found.

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.