Documentation
¶
Overview ¶
Package readback reads the GPU readback corpus under testdata/readback: small compute shaders with the values a GPU must write when it runs them.
naga cannot run a GPU. The corpus lives here, next to the compiler it checks; gogpu/wgpu runs it on every backend and adapter and compares the buffers it reads back. naga's own tests use this package to keep every case well formed and compilable on every backend, so a case that rots fails naga CI before it reaches a GPU run. testdata/readback/README.md is the format specification wgpu implements; this package is its reference reader.
Index ¶
Constants ¶
const FormatVersion = 2
FormatVersion is the newest case format this package reads; it reads every format from 1 up to it. A case declares its format, and a reader rejects a newer one, so a newer corpus fails loudly instead of being misread. Format 2 adds KnownFailure.Skip.
const ReadmeName = "README.md"
ReadmeName is the corpus README at the root of the tree, the only file outside an area directory.
Variables ¶
var Backends = []Backend{BackendVulkan, BackendDX12FXC, BackendDX12DXIL, BackendGLES, BackendMetal, BackendSoftware}
Backends lists every backend of format 1.
Functions ¶
func CheckModule ¶
CheckModule checks that spec describes the shader m, a module from Module: the entry point is a compute one, every buffer it binds has a JSON binding of the same kind and at least the type's size, and the other way round, and the case requires shader-f16 exactly when the shader uses f16.
func Module ¶
Module returns the IR a backend compiles for case c, as wgpu builds a compute pipeline from it: the WGSL frontend's module, validated with the capabilities the case requires, with its overrides processed for its entry point and pipeline constants. Processing for one entry point removes the globals it does not use, so the bindings left are the pipeline's.
Types ¶
type Backend ¶
type Backend string
Backend names a wgpu backend and, for DX12, the shader compiler path. A naga backend serves each: vulkan and software run SPIR-V, dx12-fxc runs HLSL through FXC, dx12-dxil runs naga's DXIL, gles runs GLSL and metal MSL.
type Binding ¶
type Binding struct {
Binding uint32 `json:"binding"`
Kind Kind `json:"kind"`
// Words are the initial contents.
Words []Word `json:"words,omitempty"`
// Len is the size in words when the buffer starts as Len copies of Fill.
Len int `json:"len,omitempty"`
// Fill is the initial value of every word when Len is set (default 0);
// "fill" in Expect stands for it.
Fill *Word `json:"fill,omitempty"`
// Expect lists the acceptable contents after the dispatch (any of them);
// each has exactly Size words. Only storage-rw bindings have it.
Expect [][]ExpectWord `json:"expect,omitempty"`
// Type says how to print the words in a failure: u32 (default), i32 or
// f32. It does not change the comparison, which is bit for bit.
Type string `json:"type,omitempty"`
}
Binding is one buffer at @group(0) @binding(Binding). Its initial contents are either Words, or Len copies of Fill.
func (*Binding) Expected ¶
Expected returns the acceptable contents after the dispatch, with "fill" replaced by the fill value.
type Case ¶
type Case struct {
// Name is "<area>/<name>", the case path without an extension.
Name string
// WGSL is the shader source.
WGSL string
// Spec is the decoded and checked JSON file.
Spec Spec
}
Case is one corpus case: <area>/<name>.wgsl and its <area>/<name>.json.
type ExpectWord ¶
ExpectWord is an expected word: a Word, or the string "fill" for the binding's fill value (the sentinel must still be there).
func (*ExpectWord) UnmarshalJSON ¶
func (w *ExpectWord) UnmarshalJSON(data []byte) error
UnmarshalJSON implements json.Unmarshaler.
type KnownFailure ¶
type KnownFailure struct {
Backend Backend `json:"backend"`
Adapter string `json:"adapter,omitempty"`
Driver string `json:"driver,omitempty"`
// Card is the kanban card that tracks the bug: a naga card ID, or
// "gogpu/<repo>:<ID>" for a card of another gogpu repository.
Card string `json:"card"`
Reason string `json:"reason"`
// Skip (format 2) tells the runner not to dispatch the case on a matched
// run, as Rust wgpu's FailureCase skip: the GPU hangs or the device is
// lost, which would fail every case after it. A skipped run cannot report
// an unexpected pass, so whoever works the card re-checks the case.
Skip bool `json:"skip,omitempty"`
}
KnownFailure is an expected failure, as Rust wgpu's FailureCase: it matches a run on Backend whose adapter name and driver contain Adapter and Driver (case-insensitive; empty matches any). A matched case that passes is an error, so a fixed bug cannot hide behind a stale entry.
func (*KnownFailure) AllAdapters ¶
func (k *KnownFailure) AllAdapters() bool
AllAdapters reports whether the entry matches every adapter of its backend.
type Spec ¶
type Spec struct {
// Format is the case format version, FormatVersion.
Format int `json:"format"`
// Desc says what the case checks and why it exists.
Desc string `json:"desc"`
// Entry is the name of the compute entry point to run.
Entry string `json:"entry"`
// Workgroups is the dispatch size: exactly three counts, each at least 1.
Workgroups []uint32 `json:"workgroups"`
// Constants are pipeline-constant values by override name or @id.
Constants map[string]float64 `json:"constants,omitempty"`
// Requires lists the WebGPU features the case needs; an adapter without
// one skips the case.
Requires []string `json:"requires,omitempty"`
// Bindings are the buffers of @group(0), one per @binding.
Bindings []Binding `json:"bindings"`
// KnownFailures are the backends and adapters on which the case is
// expected to fail, each tracked by a card.
KnownFailures []KnownFailure `json:"knownFailures,omitempty"`
}
Spec is one case's JSON file.
Source Files