Documentation
¶
Overview ¶
Package valid validates an IR module: Rust naga's valid module. Validate checks a module against the capabilities a WebGPU implementation allows and returns, per function and entry point, the globals it uses (ModuleInfo).
The layering is Rust naga's (lib.rs): package ir is the data, the typifier types its expressions, and valid builds on both. The backends type the module they write but never validate it; validate first, then compile.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Capabilities ¶
type Capabilities uint64
Capabilities represents hardware/API features available to the shader. Mirrors Rust naga valid::Capabilities bitflags.
When compiling WGSL, types like f64, i64, u64, and f16 are only valid if the caller enables the corresponding capability. Without it, the validator rejects the shader with a descriptive error.
Default value (0) means no extended capabilities are enabled, which matches Rust naga's default behavior where only f32/i32/u32/bool are allowed without explicit capability opt-in.
The bits are Rust's, which go above bit 31 (DEBUG_PRINTF is 1 << 45 at the pin), so the type is as wide as Rust's u64. A constant exists for each capability Validate checks; the others arrive with the IR they gate.
Not checked, by design: IMMEDIATES and TEXTURE_EXTERNAL are core WebGPU (var<immediate>, texture_external), so a core caller may use them without a capability; MULTISAMPLED_SHADING, CUBE_ARRAY_TEXTURES, LINEAR_INTERPOLATION and SHADER_FLOAT16_IN_FLOAT32 are core features some devices lack, for a future negative-polarity option; the four *_NON_UNIFORM_INDEXING capabilities need the uniformity analysis the validator does not have yet.
const ( // CapFloat64 enables f64 scalar type (Float width=8). // Maps to Rust naga valid::Capabilities::FLOAT64 (1 << 1). CapFloat64 Capabilities = 1 << 1 // CapPrimitiveIndex enables @builtin(primitive_index) (Rust // PRIMITIVE_INDEX). CapPrimitiveIndex Capabilities = 1 << 2 // CapTextureAndSamplerBindingArray enables binding arrays of sampled // and depth textures and of samplers (Rust // TEXTURE_AND_SAMPLER_BINDING_ARRAY). CapTextureAndSamplerBindingArray Capabilities = 1 << 3 // CapBufferBindingArray enables binding arrays of uniform buffers (Rust // BUFFER_BINDING_ARRAY). CapBufferBindingArray Capabilities = 1 << 4 // CapStorageTextureBindingArray enables binding arrays of storage // textures (Rust STORAGE_TEXTURE_BINDING_ARRAY). CapStorageTextureBindingArray Capabilities = 1 << 5 // CapStorageBufferBindingArray enables binding arrays of storage // buffers (Rust STORAGE_BUFFER_BINDING_ARRAY). CapStorageBufferBindingArray Capabilities = 1 << 6 // CapClipDistances enables @builtin(clip_distances) (Rust // CLIP_DISTANCES). CapClipDistances Capabilities = 1 << 7 // CapStorageTexture16BitNormFormats enables the r16unorm, r16snorm, // rg16unorm, rg16snorm, rgba16unorm and rgba16snorm storage texture // formats (Rust STORAGE_TEXTURE_16BIT_NORM_FORMATS). CapStorageTexture16BitNormFormats Capabilities = 1 << 9 // CapMultiview enables @builtin(view_index) (Rust MULTIVIEW). CapMultiview Capabilities = 1 << 10 // CapEarlyDepthTest enables a fragment entry point's early depth test // (Rust EARLY_DEPTH_TEST). CapEarlyDepthTest Capabilities = 1 << 11 // CapRayQuery enables ray queries and acceleration structures (Rust // RAY_QUERY). CapRayQuery Capabilities = 1 << 13 // CapDualSourceBlending enables @blend_src on fragment outputs (Rust // DUAL_SOURCE_BLENDING). CapDualSourceBlending Capabilities = 1 << 14 // CapShaderInt64 enables i64 and u64 scalar types (Sint/Uint width=8). // Maps to Rust naga valid::Capabilities::SHADER_INT64 (1 << 16). CapShaderInt64 Capabilities = 1 << 16 // CapSubgroup enables subgroup operations (barriers excepted) and the // subgroup built-ins in fragment and compute-like shaders (Rust // SUBGROUP). With it, a zero Options.SubgroupOperations allows every // operation and a zero Options.SubgroupStages the fragment and // compute-like stages. CapSubgroup Capabilities = 1 << 17 // CapSubgroupBarrier enables subgroup barriers, together with // CapSubgroup (Rust SUBGROUP_BARRIER). CapSubgroupBarrier Capabilities = 1 << 18 // CapSubgroupVertexStage adds the vertex stage to the stages a zero // Options.SubgroupStages allows (Rust SUBGROUP_VERTEX_STAGE). CapSubgroupVertexStage Capabilities = 1 << 19 // CapShaderInt64AtomicMinMax enables atomicMin and atomicMax on 64-bit // integers in the storage address space, when the result is not used // (Rust SHADER_INT64_ATOMIC_MIN_MAX). CapShaderInt64AtomicMinMax Capabilities = 1 << 20 // CapShaderInt64AtomicAllOps enables every atomic operation on 64-bit // integers (Rust SHADER_INT64_ATOMIC_ALL_OPS). CapShaderInt64AtomicAllOps Capabilities = 1 << 21 // CapShaderFloat32Atomic enables atomic<f32> with atomicAdd, atomicSub // and atomicExchange in the storage address space (Rust // SHADER_FLOAT32_ATOMIC). CapShaderFloat32Atomic Capabilities = 1 << 22 // CapTextureAtomic enables atomics on r32sint and r32uint storage // textures (Rust TEXTURE_ATOMIC). CapTextureAtomic Capabilities = 1 << 23 // CapTextureInt64Atomic enables atomics on r64uint storage textures // (Rust TEXTURE_INT64_ATOMIC). CapTextureInt64Atomic Capabilities = 1 << 24 // CapShaderFloat16 enables f16 scalar type (Float width=2). // Maps to Rust naga valid::Capabilities::SHADER_FLOAT16 (1 << 26). CapShaderFloat16 Capabilities = 1 << 26 // CapShaderBarycentrics enables @builtin(barycentric) and // @builtin(barycentric_no_perspective) (Rust SHADER_BARYCENTRICS). CapShaderBarycentrics Capabilities = 1 << 29 // CapMeshShader enables task and mesh shaders, the mesh built-ins, the // task_payload address space and @per_primitive (Rust MESH_SHADER). CapMeshShader Capabilities = 1 << 30 // CapMeshShaderPointTopology enables mesh shaders that output points // (Rust MESH_SHADER_POINT_TOPOLOGY). CapMeshShaderPointTopology Capabilities = 1 << 31 // CapPerVertex enables @interpolate(per_vertex) fragment inputs (Rust // PER_VERTEX). CapPerVertex Capabilities = 1 << 37 // CapDrawIndex enables @builtin(draw_index) (Rust DRAW_INDEX). CapDrawIndex Capabilities = 1 << 39 // CapAccelerationStructureBindingArray enables binding arrays of // acceleration structures (Rust ACCELERATION_STRUCTURE_BINDING_ARRAY). CapAccelerationStructureBindingArray Capabilities = 1 << 40 // CapShaderInt16 enables i16 and u16 scalar types (Sint/Uint width=2; // Rust SHADER_INT16). CapShaderInt16 Capabilities = 1 << 43 // CapAll enables all capabilities, those added later included. Used by // test infrastructure and tools that need to accept any valid WGSL // without restriction. CapAll Capabilities = ^Capabilities(0) )
func (Capabilities) Contains ¶
func (c Capabilities) Contains(flag Capabilities) bool
Contains reports whether c includes all the flags in flag.
type Error ¶
type Error struct {
Message string
// Optional context
Function string
Expression *ir.ExpressionHandle
Statement int
}
Error is a validation error (Rust naga's ValidationError).
type Errors ¶
type Errors []Error
Errors is the error Validate returns: every problem it found, where Rust naga stops at the first. errors.As finds an *Error.
type FunctionInfo ¶
type FunctionInfo struct {
// GlobalUses is indexed by GlobalVariableHandle; a zero entry means the
// function does not use the variable.
GlobalUses []GlobalUse
}
FunctionInfo is what validation learns about one function or entry point, its callees included: Rust naga's valid::FunctionInfo, so far its global_uses. Later fields are additive.
type GlobalUse ¶
type GlobalUse uint8
GlobalUse is how a function uses a global variable: Rust naga's valid::GlobalUse.
const ( // GlobalUseRead: data is read from the variable. GlobalUseRead GlobalUse = 1 << iota // GlobalUseWrite: data is written to the variable. GlobalUseWrite // GlobalUseQuery: information about the data is queried (its array // length, an image's size), or the variable is only named. GlobalUseQuery // GlobalUseAtomic: atomic operations are performed on an image. GlobalUseAtomic )
type ModuleInfo ¶
type ModuleInfo struct {
Functions []FunctionInfo
EntryPoints []FunctionInfo
}
ModuleInfo is what validation learns about a module: Rust naga's valid::ModuleInfo. Functions is indexed by FunctionHandle, EntryPoints like Module.EntryPoints. A WebGPU implementation reads from it which globals each entry point uses statically, and how (the workgroup storage limit, binding sizes, bind group layouts).
func Validate ¶
func Validate(module *ir.Module, opts Options) (ModuleInfo, error)
Validate checks the module for correctness (Rust naga's Validator::validate) and returns what a WebGPU implementation needs from it: per function and entry point, the globals it uses and how. A module with problems returns an Errors.
type Options ¶
type Options struct {
// Capabilities are the optional features the module may use; a type or
// operation that needs one outside the set is a validation error. This
// is the single gate for capabilities: neither the frontends nor the
// backends check them.
Capabilities Capabilities
// SubgroupStages are the stages a subgroup operation may run in (Rust
// naga's Validator::subgroup_stages). Zero derives them from
// Capabilities, as Rust's Validator::new: CapSubgroup gives the fragment
// and compute-like stages, CapSubgroupVertexStage adds the vertex stage.
// A non-zero set replaces the derived one. An entry point whose stage
// is outside the set and that reaches a subgroup operation is an error.
SubgroupStages ShaderStages
// SubgroupOperations are the subgroup operations the module may use
// (Rust naga's Validator::subgroup_operations). Zero derives them from
// Capabilities, as Rust's Validator::new: CapSubgroup gives every
// operation, none without it. A non-zero set replaces the derived one.
// Every subgroup operation still needs CapSubgroup.
SubgroupOperations SubgroupOperationSet
}
Options configures Validate. The zero value is WebGPU core: no optional capability.
type ShaderStages ¶
type ShaderStages uint16
ShaderStages is a set of shader stages: Rust naga's valid::ShaderStages, with Rust's bits. The ray tracing stages arrive with their IR.
const ( // ShaderStagesVertex is the vertex stage (Rust VERTEX). ShaderStagesVertex ShaderStages = 0x1 // ShaderStagesFragment is the fragment stage (Rust FRAGMENT). ShaderStagesFragment ShaderStages = 0x2 // ShaderStagesCompute is the compute stage (Rust COMPUTE). ShaderStagesCompute ShaderStages = 0x4 // ShaderStagesMesh is the mesh stage (Rust MESH). ShaderStagesMesh ShaderStages = 0x8 // ShaderStagesTask is the task stage (Rust TASK). ShaderStagesTask ShaderStages = 0x10 // ShaderStagesComputeLike is the compute, task and mesh stages (Rust // COMPUTE_LIKE). ShaderStagesComputeLike = ShaderStagesCompute | ShaderStagesTask | ShaderStagesMesh )
type SubgroupOperationSet ¶
type SubgroupOperationSet uint8
SubgroupOperationSet is a set of subgroup operation classes: Rust naga's valid::SubgroupOperationSet, with Rust's bits (bit 6, clustered, and bit 8, quad in all stages, are not supported by Rust either).
const ( // SubgroupBasic is subgroup barriers (Rust BASIC). SubgroupBasic SubgroupOperationSet = 1 << 0 // SubgroupVote is subgroupAll and subgroupAny (Rust VOTE). SubgroupVote SubgroupOperationSet = 1 << 1 // SubgroupArithmetic is the reductions and scans (Rust ARITHMETIC). SubgroupArithmetic SubgroupOperationSet = 1 << 2 // SubgroupBallot is ballot and broadcast (Rust BALLOT). SubgroupBallot SubgroupOperationSet = 1 << 3 // SubgroupShuffle is shuffle and shuffle xor (Rust SHUFFLE). SubgroupShuffle SubgroupOperationSet = 1 << 4 // SubgroupShuffleRelative is shuffle up and down (Rust // SHUFFLE_RELATIVE). SubgroupShuffleRelative SubgroupOperationSet = 1 << 5 // SubgroupQuadFragmentCompute is the quad operations in fragment and // compute shaders (Rust QUAD_FRAGMENT_COMPUTE). SubgroupQuadFragmentCompute SubgroupOperationSet = 1 << 7 )
Source Files