software

package
v0.19.7 Latest Latest
Warning

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

 Go to latest Published: Mar 7, 2026 License: MIT Imports: 7 Imported by: 1

Documentation

Overview

Package software provides a CPU-based software rendering backend.

Status: IMPLEMENTED (Phase 1 - Headless Rendering)

The software backend implements all HAL interfaces using pure Go CPU rendering. Unlike the noop backend, it actually performs rendering operations in memory.

Use cases:

  • Headless rendering (servers, CI/CD)
  • Screenshot/image generation without GPU
  • Testing rendering logic without GPU hardware
  • Embedded systems without GPU
  • Fallback when no GPU backend is available

Implemented features (Phase 1):

  • Real data storage for buffers and textures
  • Clear operations (fill framebuffer/texture with color)
  • Buffer/texture copy operations
  • Framebuffer readback via Surface.GetFramebuffer()
  • Thread-safe resource access

Limitations:

  • Much slower than GPU backends (CPU-bound)
  • No hardware acceleration
  • No compute shaders (returns error)
  • No rasterization yet (draw calls are no-op - Phase 2)
  • No shader execution (basic resources only)

Always compiled (no build tags required).

Example: 

import _ "github.com/gogpu/wgpu/hal/software"

// Software backend is registered automatically
// Adapter name: "Software Renderer"
// Device type: types.DeviceTypeCPU

Backend identifier: types.BackendEmpty

Index

Constants

This section is empty.

Variables

View Source 
var ErrComputeNotSupported = errors.New("software: compute shaders not supported")

ErrComputeNotSupported indicates that compute shaders are not available in the software backend. The software backend only supports rasterization; use a GPU-accelerated backend (Vulkan, Metal, DX12) for compute workloads.

Functions

This section is empty.

Types

type API 

type API struct{}

API implements hal.Backend for the software backend.

func (API) CreateInstance 

func (API) CreateInstance(_ *hal.InstanceDescriptor) (hal.Instance, error)

CreateInstance creates a new software rendering instance. Always succeeds and returns a CPU-based rendering instance.

func (API) Variant 

func (API) Variant() gputypes.Backend

Variant returns the backend type identifier.

type Adapter 

type Adapter struct{}

Adapter implements hal.Adapter for the software backend.

func (*Adapter) Destroy 

func (a *Adapter) Destroy()

Destroy is a no-op for the software adapter.

func (*Adapter) Open 

func (a *Adapter) Open(_ gputypes.Features, _ gputypes.Limits) (hal.OpenDevice, error)

Open creates a software device with the requested features and limits. Always succeeds and returns a device/queue pair.

func (*Adapter) SurfaceCapabilities 

func (a *Adapter) SurfaceCapabilities(_ hal.Surface) *hal.SurfaceCapabilities

SurfaceCapabilities returns default surface capabilities.

func (*Adapter) TextureFormatCapabilities 

func (a *Adapter) TextureFormatCapabilities(_ gputypes.TextureFormat) hal.TextureFormatCapabilities

TextureFormatCapabilities returns default capabilities for all formats.

type Buffer 

type Buffer struct {
	Resource
	// contains filtered or unexported fields
}

Buffer implements hal.Buffer with real data storage. All software buffers store their data in memory.

func (*Buffer) GetData 

func (b *Buffer) GetData() []byte

GetData returns a copy of the buffer data (thread-safe).

func (*Buffer) NativeHandle 

func (b *Buffer) NativeHandle() uintptr

NativeHandle returns 0 for software buffers.

func (*Buffer) WriteData 

func (b *Buffer) WriteData(offset uint64, data []byte)

WriteData writes data to the buffer (thread-safe).

type CommandEncoder 

type CommandEncoder struct{}

CommandEncoder implements hal.CommandEncoder for the software backend.

func (*CommandEncoder) BeginComputePass 

func (c *CommandEncoder) BeginComputePass(desc *hal.ComputePassDescriptor) hal.ComputePassEncoder

BeginComputePass begins a compute pass and returns an encoder.

func (*CommandEncoder) BeginEncoding 

func (c *CommandEncoder) BeginEncoding(_ string) error

BeginEncoding is a no-op.

func (*CommandEncoder) BeginRenderPass 

func (c *CommandEncoder) BeginRenderPass(desc *hal.RenderPassDescriptor) hal.RenderPassEncoder

BeginRenderPass begins a render pass and returns an encoder.

func (*CommandEncoder) ClearBuffer 

func (c *CommandEncoder) ClearBuffer(buffer hal.Buffer, offset, size uint64)

ClearBuffer clears a buffer region to zero.

func (*CommandEncoder) CopyBufferToBuffer 

func (c *CommandEncoder) CopyBufferToBuffer(src, dst hal.Buffer, regions []hal.BufferCopy)

CopyBufferToBuffer copies data between buffers.

func (*CommandEncoder) CopyBufferToTexture 

func (c *CommandEncoder) CopyBufferToTexture(src hal.Buffer, dst hal.Texture, regions []hal.BufferTextureCopy)

CopyBufferToTexture copies data from a buffer to a texture.

func (*CommandEncoder) CopyTextureToBuffer 

func (c *CommandEncoder) CopyTextureToBuffer(src hal.Texture, dst hal.Buffer, regions []hal.BufferTextureCopy)

CopyTextureToBuffer copies data from a texture to a buffer.

func (*CommandEncoder) CopyTextureToTexture 

func (c *CommandEncoder) CopyTextureToTexture(src, dst hal.Texture, regions []hal.TextureCopy)

CopyTextureToTexture copies data between textures.

func (*CommandEncoder) DiscardEncoding 

func (c *CommandEncoder) DiscardEncoding()

DiscardEncoding is a no-op.

func (*CommandEncoder) EndEncoding 

func (c *CommandEncoder) EndEncoding() (hal.CommandBuffer, error)

EndEncoding returns a placeholder command buffer.

func (*CommandEncoder) ResetAll 

func (c *CommandEncoder) ResetAll(_ []hal.CommandBuffer)

ResetAll is a no-op.

func (*CommandEncoder) ResolveQuerySet 

func (c *CommandEncoder) ResolveQuerySet(_ hal.QuerySet, _, _ uint32, _ hal.Buffer, _ uint64)

ResolveQuerySet is a no-op (query sets not supported in software backend).

func (*CommandEncoder) TransitionBuffers 

func (c *CommandEncoder) TransitionBuffers(_ []hal.BufferBarrier)

TransitionBuffers is a no-op (software backend doesn't need explicit transitions).

func (*CommandEncoder) TransitionTextures 

func (c *CommandEncoder) TransitionTextures(_ []hal.TextureBarrier)

TransitionTextures is a no-op (software backend doesn't need explicit transitions).

type ComputePassEncoder 

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

ComputePassEncoder implements hal.ComputePassEncoder for the software backend.

func (*ComputePassEncoder) Dispatch 

func (c *ComputePassEncoder) Dispatch(_, _, _ uint32)

Dispatch is a no-op (compute not supported).

func (*ComputePassEncoder) DispatchIndirect 

func (c *ComputePassEncoder) DispatchIndirect(_ hal.Buffer, _ uint64)

DispatchIndirect is a no-op.

func (*ComputePassEncoder) End 

func (c *ComputePassEncoder) End()

End is a no-op.

func (*ComputePassEncoder) SetBindGroup 

func (c *ComputePassEncoder) SetBindGroup(_ uint32, _ hal.BindGroup, _ []uint32)

SetBindGroup is a no-op.

func (*ComputePassEncoder) SetPipeline 

func (c *ComputePassEncoder) SetPipeline(_ hal.ComputePipeline)

SetPipeline is a no-op (compute not supported).

type Device 

type Device struct{}

Device implements hal.Device for the software backend.

func (*Device) CreateBindGroup 

func (d *Device) CreateBindGroup(_ *hal.BindGroupDescriptor) (hal.BindGroup, error)

CreateBindGroup creates a software bind group.

func (*Device) CreateBindGroupLayout 

func (d *Device) CreateBindGroupLayout(_ *hal.BindGroupLayoutDescriptor) (hal.BindGroupLayout, error)

CreateBindGroupLayout creates a software bind group layout.

func (*Device) CreateBuffer 

func (d *Device) CreateBuffer(desc *hal.BufferDescriptor) (hal.Buffer, error)

CreateBuffer creates a software buffer with real data storage.

func (*Device) CreateCommandEncoder 

func (d *Device) CreateCommandEncoder(_ *hal.CommandEncoderDescriptor) (hal.CommandEncoder, error)

CreateCommandEncoder creates a software command encoder.

func (*Device) CreateComputePipeline 

func (d *Device) CreateComputePipeline(_ *hal.ComputePipelineDescriptor) (hal.ComputePipeline, error)

CreateComputePipeline returns ErrComputeNotSupported. The software backend does not support compute shaders.

func (*Device) CreateFence 

func (d *Device) CreateFence() (hal.Fence, error)

CreateFence creates a software fence with atomic counter.

func (*Device) CreatePipelineLayout 

func (d *Device) CreatePipelineLayout(_ *hal.PipelineLayoutDescriptor) (hal.PipelineLayout, error)

CreatePipelineLayout creates a software pipeline layout.

func (*Device) CreateQuerySet 

func (d *Device) CreateQuerySet(_ *hal.QuerySetDescriptor) (hal.QuerySet, error)

CreateQuerySet is not supported in the software backend.

func (*Device) CreateRenderBundleEncoder 

func (d *Device) CreateRenderBundleEncoder(_ *hal.RenderBundleEncoderDescriptor) (hal.RenderBundleEncoder, error)

CreateRenderBundleEncoder is not supported in the software backend.

func (*Device) CreateRenderPipeline 

func (d *Device) CreateRenderPipeline(_ *hal.RenderPipelineDescriptor) (hal.RenderPipeline, error)

CreateRenderPipeline creates a software render pipeline.

func (*Device) CreateSampler 

func (d *Device) CreateSampler(_ *hal.SamplerDescriptor) (hal.Sampler, error)

CreateSampler creates a software sampler.

func (*Device) CreateShaderModule 

func (d *Device) CreateShaderModule(_ *hal.ShaderModuleDescriptor) (hal.ShaderModule, error)

CreateShaderModule creates a software shader module.

func (*Device) CreateTexture 

func (d *Device) CreateTexture(desc *hal.TextureDescriptor) (hal.Texture, error)

CreateTexture creates a software texture with real pixel storage.

func (*Device) CreateTextureView 

func (d *Device) CreateTextureView(texture hal.Texture, _ *hal.TextureViewDescriptor) (hal.TextureView, error)

CreateTextureView creates a software texture view.

func (*Device) Destroy 

func (d *Device) Destroy()

Destroy is a no-op for the software device.

func (*Device) DestroyBindGroup 

func (d *Device) DestroyBindGroup(_ hal.BindGroup)

DestroyBindGroup is a no-op.

func (*Device) DestroyBindGroupLayout 

func (d *Device) DestroyBindGroupLayout(_ hal.BindGroupLayout)

DestroyBindGroupLayout is a no-op.

func (*Device) DestroyBuffer 

func (d *Device) DestroyBuffer(_ hal.Buffer)

DestroyBuffer is a no-op (Go GC handles cleanup).

func (*Device) DestroyComputePipeline 

func (d *Device) DestroyComputePipeline(_ hal.ComputePipeline)

DestroyComputePipeline is a no-op.

func (*Device) DestroyFence 

func (d *Device) DestroyFence(_ hal.Fence)

DestroyFence is a no-op.

func (*Device) DestroyPipelineLayout 

func (d *Device) DestroyPipelineLayout(_ hal.PipelineLayout)

DestroyPipelineLayout is a no-op.

func (*Device) DestroyQuerySet 

func (d *Device) DestroyQuerySet(_ hal.QuerySet)

DestroyQuerySet is a no-op for the software device.

func (*Device) DestroyRenderBundle 

func (d *Device) DestroyRenderBundle(_ hal.RenderBundle)

DestroyRenderBundle is a no-op for the software device.

func (*Device) DestroyRenderPipeline 

func (d *Device) DestroyRenderPipeline(_ hal.RenderPipeline)

DestroyRenderPipeline is a no-op.

func (*Device) DestroySampler 

func (d *Device) DestroySampler(_ hal.Sampler)

DestroySampler is a no-op.

func (*Device) DestroyShaderModule 

func (d *Device) DestroyShaderModule(_ hal.ShaderModule)

DestroyShaderModule is a no-op.

func (*Device) DestroyTexture 

func (d *Device) DestroyTexture(_ hal.Texture)

DestroyTexture is a no-op (Go GC handles cleanup).

func (*Device) DestroyTextureView 

func (d *Device) DestroyTextureView(_ hal.TextureView)

DestroyTextureView is a no-op.

func (*Device) FreeCommandBuffer 

func (d *Device) FreeCommandBuffer(_ hal.CommandBuffer)

FreeCommandBuffer is a no-op for the software device.

func (*Device) GetFenceStatus 

func (d *Device) GetFenceStatus(fence hal.Fence) (bool, error)

GetFenceStatus returns true if the fence is signaled (non-blocking).

func (*Device) ResetFence 

func (d *Device) ResetFence(fence hal.Fence) error

ResetFence resets a fence to the unsignaled state.

func (*Device) Wait 

func (d *Device) Wait(fence hal.Fence, value uint64, _ time.Duration) (bool, error)

Wait simulates waiting for a fence value. Always returns true immediately (fence reached).

func (*Device) WaitIdle 

func (d *Device) WaitIdle() error

WaitIdle is a no-op for the software device.

type Fence 

type Fence struct {
	Resource
	// contains filtered or unexported fields
}

Fence implements hal.Fence with an atomic counter for synchronization.

type Instance 

type Instance struct{}

Instance implements hal.Instance for the software backend.

func (*Instance) CreateSurface 

func (i *Instance) CreateSurface(_, _ uintptr) (hal.Surface, error)

CreateSurface creates a software rendering surface. Always succeeds regardless of display/window handles.

func (*Instance) Destroy 

func (i *Instance) Destroy()

Destroy is a no-op for the software instance.

func (*Instance) EnumerateAdapters 

func (i *Instance) EnumerateAdapters(_ hal.Surface) []hal.ExposedAdapter

EnumerateAdapters returns a single default software adapter. The surfaceHint is ignored.

type Queue 

type Queue struct{}

Queue implements hal.Queue for the software backend.

func (*Queue) GetTimestampPeriod 

func (q *Queue) GetTimestampPeriod() float32

GetTimestampPeriod returns 1.0 nanosecond timestamp period.

func (*Queue) Present 

func (q *Queue) Present(_ hal.Surface, _ hal.SurfaceTexture) error

Present simulates surface presentation. In software backend, this is essentially a no-op since framebuffer is already updated.

func (*Queue) ReadBuffer 

func (q *Queue) ReadBuffer(buffer hal.Buffer, offset uint64, data []byte) error

ReadBuffer reads data from a buffer.

func (*Queue) Submit 

func (q *Queue) Submit(_ []hal.CommandBuffer, fence hal.Fence, fenceValue uint64) error

Submit simulates command buffer submission. If a fence is provided, it is signaled with the given value.

func (*Queue) WriteBuffer 

func (q *Queue) WriteBuffer(buffer hal.Buffer, offset uint64, data []byte) error

WriteBuffer performs immediate buffer writes with real data storage.

func (*Queue) WriteTexture 

func (q *Queue) WriteTexture(dst *hal.ImageCopyTexture, data []byte, layout *hal.ImageDataLayout, size *hal.Extent3D) error

WriteTexture performs immediate texture writes with real data storage.

type RenderPassEncoder 

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

RenderPassEncoder implements hal.RenderPassEncoder for the software backend.

func (*RenderPassEncoder) Draw 

func (r *RenderPassEncoder) Draw(_, _, _, _ uint32)

Draw is a no-op (rasterization not implemented in Phase 1).

func (*RenderPassEncoder) DrawIndexed 

func (r *RenderPassEncoder) DrawIndexed(_, _, _ uint32, _ int32, _ uint32)

DrawIndexed is a no-op (rasterization not implemented in Phase 1).

func (*RenderPassEncoder) DrawIndexedIndirect 

func (r *RenderPassEncoder) DrawIndexedIndirect(_ hal.Buffer, _ uint64)

DrawIndexedIndirect is a no-op.

func (*RenderPassEncoder) DrawIndirect 

func (r *RenderPassEncoder) DrawIndirect(_ hal.Buffer, _ uint64)

DrawIndirect is a no-op.

func (*RenderPassEncoder) End 

func (r *RenderPassEncoder) End()

End finishes the render pass and performs load/store operations.

func (*RenderPassEncoder) ExecuteBundle 

func (r *RenderPassEncoder) ExecuteBundle(_ hal.RenderBundle)

ExecuteBundle is a no-op.

func (*RenderPassEncoder) SetBindGroup 

func (r *RenderPassEncoder) SetBindGroup(_ uint32, _ hal.BindGroup, _ []uint32)

SetBindGroup is a no-op.

func (*RenderPassEncoder) SetBlendConstant 

func (r *RenderPassEncoder) SetBlendConstant(_ *gputypes.Color)

SetBlendConstant is a no-op.

func (*RenderPassEncoder) SetIndexBuffer 

func (r *RenderPassEncoder) SetIndexBuffer(_ hal.Buffer, _ gputypes.IndexFormat, _ uint64)

SetIndexBuffer is a no-op.

func (*RenderPassEncoder) SetPipeline 

func (r *RenderPassEncoder) SetPipeline(_ hal.RenderPipeline)

SetPipeline is a no-op.

func (*RenderPassEncoder) SetScissorRect 

func (r *RenderPassEncoder) SetScissorRect(_, _, _, _ uint32)

SetScissorRect is a no-op.

func (*RenderPassEncoder) SetStencilReference 

func (r *RenderPassEncoder) SetStencilReference(_ uint32)

SetStencilReference is a no-op.

func (*RenderPassEncoder) SetVertexBuffer 

func (r *RenderPassEncoder) SetVertexBuffer(_ uint32, _ hal.Buffer, _ uint64)

SetVertexBuffer is a no-op.

func (*RenderPassEncoder) SetViewport 

func (r *RenderPassEncoder) SetViewport(_, _, _, _, _, _ float32)

SetViewport is a no-op.

type Resource 

type Resource struct{}

Resource is a placeholder implementation for most HAL resource gputypes. It implements the hal.Resource interface with a no-op Destroy method.

func (*Resource) Destroy 

func (r *Resource) Destroy()

Destroy is a no-op.

func (*Resource) NativeHandle 

func (r *Resource) NativeHandle() uintptr

NativeHandle returns 0 for software resources (no real GPU handle).

type Surface 

type Surface struct {
	Resource
	// contains filtered or unexported fields
}

Surface implements hal.Surface for the software backend.

func (*Surface) AcquireTexture 

func (s *Surface) AcquireTexture(_ hal.Fence) (*hal.AcquiredSurfaceTexture, error)

AcquireTexture returns a surface texture backed by the framebuffer.

func (*Surface) Configure 

func (s *Surface) Configure(_ hal.Device, config *hal.SurfaceConfiguration) error

Configure configures the surface with the given settings.

Returns hal.ErrZeroArea if width or height is zero. This commonly happens when the window is minimized or not yet fully visible. Wait until the window has valid dimensions before calling Configure again.

func (*Surface) DiscardTexture 

func (s *Surface) DiscardTexture(_ hal.SurfaceTexture)

DiscardTexture is a no-op (framebuffer stays allocated).

func (*Surface) GetFramebuffer 

func (s *Surface) GetFramebuffer() []byte

GetFramebuffer returns a copy of the current framebuffer data (thread-safe). This is the key method for reading rendered results in software backend.

func (*Surface) Unconfigure 

func (s *Surface) Unconfigure(_ hal.Device)

Unconfigure removes the surface configuration.

type SurfaceTexture 

type SurfaceTexture struct {
	Texture
	// contains filtered or unexported fields
}

SurfaceTexture implements hal.SurfaceTexture. It shares the framebuffer with the surface.

type Texture 

type Texture struct {
	Resource
	// contains filtered or unexported fields
}

Texture implements hal.Texture with real pixel storage.

func (*Texture) Clear 

func (t *Texture) Clear(color gputypes.Color)

Clear fills the texture with a color value.

func (*Texture) GetData 

func (t *Texture) GetData() []byte

GetData returns a copy of the texture data (thread-safe).

func (*Texture) NativeHandle 

func (t *Texture) NativeHandle() uintptr

NativeHandle returns 0 for software textures.

func (*Texture) WriteData 

func (t *Texture) WriteData(offset uint64, data []byte)

WriteData writes data to the texture (thread-safe).

type TextureView 

type TextureView struct {
	Resource
	// contains filtered or unexported fields
}

TextureView implements hal.TextureView. In software backend, views just reference the original texture.

func (*TextureView) NativeHandle 

func (v *TextureView) NativeHandle() uintptr

NativeHandle returns 0 for software texture views.

Source Files

View all Source files

Directories

Path Synopsis
Package raster provides CPU-based triangle rasterization for the software backend.
 Package raster provides CPU-based triangle rasterization for the software backend.
Package shader provides callback-based shader execution for the software backend.
 Package shader provides callback-based shader execution for the software backend.

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.