Documentation
¶
Overview ¶
Package shaderir holds the naga IR of a WGSL shader module and specializes it for one pipeline stage.
A HAL backend lowers WGSL to IR once, when the shader module is created. If the module has no pipeline-overridable constants (WGSL `override`), the backend may compile it once and reuse the result for every pipeline. If it has overrides, or a pipeline gives constants, the backend calls Specialize for every pipeline stage and compiles the result: the override values, the expressions that depend on them and workgroup sizes given by overrides are known only then. This is Rust wgpu-hal's call to naga::back::pipeline_constants::process_overrides before every backend (vulkan/device.rs:804, dx12/device.rs:349, gles/device.rs:385, metal/device.rs:174).
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrUnresolvedOverride = errors.New("BUG: HAL compiled a shader with unresolved overrides (naga.ProcessOverrides not run)")
ErrUnresolvedOverride wraps a naga backend error caused by overrides that were not resolved before the backend ran. It is a bug in the HAL backend, never in the shader or the pipeline.
Functions ¶
func BackendError ¶
BackendError returns err from a naga shader backend. If err says that overrides were not resolved (ir.ErrUnresolvedOverride), the result also wraps ErrUnresolvedOverride, which marks it as an internal error.
func Lowerings ¶
func Lowerings() uint64
Lowerings returns how many times WGSL has been parsed and validated in this process. Tests use it to prove that a shader module is lowered once (P1-CORE-013).
func PerStage ¶
PerStage reports whether module must be specialized for each pipeline stage: it has overrides, or the pipeline gives constants (which must then name overrides of the module). Otherwise module can be compiled once.
A module from the WGSL frontend without overrides has no override expressions, override workgroup sizes or override-sized arrays (the guarantee of naga.ProcessOverrides).
func SPIRV ¶
SPIRV compiles module to SPIR-V words with the backend's options. Every backend passes its own options, as each Rust wgpu-hal backend does: naga's zero values (SPIR-V 1.0, Restrict on every bounds check) suit no device.
func StageName ¶
func StageName(stage ir.ShaderStage) string
StageName returns the WGSL attribute name of a shader stage.
Types ¶
type Module ¶
type Module struct {
IR *ir.Module
Info valid.ModuleInfo
}
Module is a validated IR module and the ModuleInfo of that validation, which naga.ProcessOverrides takes.
func Lower ¶
Lower parses WGSL to IR and validates it, allowing every capability (valid.CapAll).
A backend calls it only when the HAL is used without core: core lowers the module once with the device's capabilities (LowerOptions) and hands the result to the HAL in hal.ShaderModuleDescriptor.IR, as Rust wgpu-core hands wgpu-hal hal::ShaderInput::Naga. A capability gate here would refuse features the device has.
func LowerDescriptor ¶
func LowerDescriptor(desc *hal.ShaderModuleDescriptor) (Module, error)
LowerDescriptor returns the module of a WGSL shader module descriptor: the IR and ModuleInfo core validated (desc.IR, desc.Info), or, when desc.IR is nil because the HAL is used without core, Lower(desc.Source.WGSL).
func LowerOptions ¶
LowerOptions parses WGSL to IR and validates it with opts.
A parse error keeps naga's *wgsl.ParseError (errors.As works) and is prefixed with its line and column: ParseError.Error is the message only. A validation error is valid.Errors.
func Specialize ¶
func Specialize(module Module, stage ir.ShaderStage, entryPoint string, constants map[string]float64) (Module, error)
Specialize returns module for one pipeline stage: only the entry point named entryPoint of the given stage is kept (it is EntryPoints[0] of the result), and every override takes its value from constants or its default.
module is not modified, and Specialize may run concurrently on the same module. The result may share memory with module; treat it as read-only.
A constant error keeps naga's error: errors.Is with naga.ErrOverrideNotFound and the other sentinels, and errors.As with *naga.PipelineConstantError, work on the result.
Source Files