Crate iridia_interface

Expand description

What a compiled shader program exposes, as plain data: its inputs and outputs, its resources (constant buffers with explicit layouts, textures, samplers, buffers, storage) and the stage’s own facts, the fixed-function state it is drawn with, and what the analyses of iridia observe of its code, independent of any graphics API.

A reader maps its API’s reflection into this once and keeps the API’s own names and addresses in provenance, so a consumer that only needs meaning (a binding step, a validator, a writer) never sees an API’s enum numbers. The rule for differences between APIs: conventions are normalized (D3D register packing is unpacked into one varying per label, D3D, std140 and DX9 constant packings all become explicit byte offsets and strides) and the original is kept in provenance; behaviour that differs is not hidden here at all (that is the program body’s business). A value a reader cannot map is refused by name, never mapped to a guess.

Everything is plain data: owned strings, integers and enums, no handles and no GPU types, and every type implements serde::Serialize, so the vocabulary can be shown, stored and compared. What a program’s inputs, constants and outputs stand for (a view-projection matrix, an albedo) is not here: that is decided by whoever binds the program to a renderer or a baker, in its own terms.

§Contents

Interface: the Stage, the Varyings a program takes and gives (by Label, with a SystemValue where the pipeline supplies it, an Interpolation and the D3D register and lanes in VaryingProvenance), its Resources and the per-stage StageFacts (tessellation, geometry, mesh and ray tracing facts).
Resource and ResourceKind: constant buffers with a BufferLayout of Constants whose ConstantType states every stride, textures, samplers, buffers and storage.
ShaderFormat: how a program’s bytes are encoded; InstructionCount: how large a program is.
RenderState (blend, depth, stencil, cull, fill, alpha test) and SamplerState (filters, addressing, comparison): Direct3D’s fixed-function state, as a source states it.
What a program’s code shows, as iridia’s analyses read it: MatrixLines (whether a constant’s lines are a matrix’s rows or its columns), AlphaComparison (what a discard compares a constant with) and OutputUse (what tests or blends an output’s lanes); and ConstantBufferBinding, the size a source binds a constant buffer with.

§Example

An interface is built by a reader (iridia-dxbc, iridia-dxil), but it is only data; this one is written by hand and serialized:

use iridia_interface::{
    Interface, Label, ScalarType, Stage, StageFacts, SystemValue, Value, Varying, VaryingProvenance,
};

let colour = Varying {
    label: Label { name: "SV_Target".into(), index: 0 },
    system: Some(SystemValue::Target(0)),
    value: Value { scalar: ScalarType::Float, width: 4 },
    interp: None,
    used: true,
    provenance: VaryingProvenance::default(),
};
let interface = Interface {
    stage: Stage::Pixel,
    inputs: Vec::new(),
    outputs: vec![colour],
    resources: Vec::new(),
    facts: StageFacts::None,
};
let json = serde_json::to_string(&interface)?;
assert!(json.contains(r#""stage":"pixel""#));

Structs§

AlphaTest: Alpha test: a pixel is kept where alpha compare reference.
Blend: Blending of the colour and the alpha channel.
BlendEquation: op(src * source, dst * destination).
BufferLayout: A constant buffer’s contents.
Constant: One named constant of a buffer.
ConstantBufferBinding: What the source states of how it binds a constant buffer of the program, beyond what its constants are.
D3dBinding: A D3D bind point: class, register index and register space.
D3dSignature: Where a D3D signature element sits: its register (four 32-bit lanes each) and the lanes of it the element occupies, as a mask (bit k is lane k, x first), and the signature’s read/write mask as stored.
DepthBias: A depth bias, D3D12’s three terms: bias = constant * r + slope_scaled * max_slope, limited to clamp when that is not zero (r the smallest resolvable depth difference).
DepthState: Depth test and write.
DomainFacts: What a domain program states about its patch: the same domain as the hull program that feeds it, how many control points it reads, and the patch-constant varyings it reads (inputs of the interface are its control points’).
Filters: A sampler’s filters as the source states them: each None where it states none (the renderer’s default).
GeometryFacts: What a geometry program states: the primitive it reads, what its emitted vertices make, the most vertices an invocation emits and how many invocations run for a primitive.
HitGroup: A hit group of a ray tracing library: the programs it runs, named by the library’s exports (none where the group has no such program).
HullFacts: What a hull program states about its patch beyond its varyings. The patch-constant varyings are its outputs per patch (SV_TessFactor, SV_InsideTessFactor, whatever the domain program reads); outputs of the interface are its control points’.
InstructionCount: How many instructions a program has, in the unit that says how they were counted.
Interface: What a program exposes: its stage, the varyings it takes and gives, and the resources it binds.
Interpolation: A pixel input’s interpolation: the mode and the sampling location.
Label: A varying’s name in its source: the semantic name and its index (DXBC TEXCOORD and 5, SPIR-V Location and 3, GLSL vUv and 0). Labels are not interpreted: games put anything in TEXCOORDn, and what a label means is the consumer’s business. Stages match by label.
Member: A structure’s member: its offset is from the start of the structure.
MeshFacts: What a mesh program states: what its primitives are and the most vertices and primitives it writes. Its thread group size is the entry point’s, as a compute program’s is.
OutputUse: What a pixel program’s code and its target’s stated blend show of the lanes of one output that is a render target (iridia::output_uses::output_uses): observations, not roles. Each is a lane mask, bit k lane k.
RayTracingFacts: What a ray tracing program’s library states: the program’s own export name (as the subobjects name it) and every subobject of the library, in the order it stores them. A pipeline is built from a library’s programs and these.
RenderState: Fixed-function state as the source stores it; each None where it states none. D3D12-shaped: blend is render target 0’s blend (what a consumer with one render target reads), and targets has every render target’s blend and write mask where the source states them, with targets[0]’s blend equal to blend (a consumer’s verification checks it).
Resource: One bound resource.
ResourceId: Names a resource within one super::Interface; the reader numbers them in its source’s order.
ResourceProvenance: The source’s own name and address for a resource; one field per API that has a notion of it.
SamplerState: A sampler’s state as the source stores it, for a texture slot or a program’s sampler: each part None where the source states none.
Stencil: An enabled stencil test (a disabled one is None in RenderState::stencil).
StencilFace: What the stencil test does for one facing.
TargetState: What one render target does with a fragment: its blend and which channels it writes.
Value: A scalar type and a width of 1 to 4 lanes.
Varying: One interface variable: a value passed between stages (or between a stage and the pipeline), one per label. D3D packs several into one register; they are separate here, with the register and lanes kept in provenance.
VaryingProvenance: The source’s own address of a varying; one field per API that has a notion of it.

Enums§

Access: What a program may do to a storage resource.
AddressMode: What a texture coordinate outside 0 to 1 reads, along one axis.
AlphaComparison: What a discard compares against a constant word (an alpha reference), proved from the program’s data flow (iridia::output_uses::discard_compares).
BlendFactor: A blend factor.
BlendOp: How the two weighted terms of a blend are combined.
BufferKind: How a buffer’s elements are addressed.
Compare: How two values are compared; the left one is the fragment’s own (its depth or alpha, or the stencil reference), the right one what it is tested against.
ConstantType: The type of one constant, with the layout it has in its buffer written out: vectors are tightly packed lanes, every matrix line and array element sits at a stated stride, whatever packing rules (D3D, std140, std430, DX9 registers) put it there.
Cull: Which facing of triangle is not drawn.
D3dClass: The register class of a D3D binding: b, t, s or u.
Fill: How a triangle is filled.
Filter: How texels are filtered when a texture is magnified or minified (glTF’s sampler filters).
GsInput: The primitive a geometry program reads.
GsOutput: What a geometry program’s emitted vertices make.
HitGroupKind: What a hit group runs for the geometry it is bound to.
InstructionUnit: The source’s counting unit. DXBC counts decoded instructions including control flow, excluding declarations; DXIL counts LLVM instructions in the functions the lifter reads. Neither is an executed instruction count or an IR expression count.
InterpMode: How a varying is interpolated across a primitive.
InterpSampling: Where in a pixel a varying is sampled.
Majorness: Whether consecutive lines of a matrix are its rows or its columns.
MatrixLines: How a matrix constant’s 16-byte lines hold the matrix the program applies to column vectors (a view-projection’s clip position is M * p). The layout’s packing (row_major, column_major) does not decide it, since a program may multiply on either side (mul(M, v), mul(v, M)): iridia::matrix::lines_at reads it from what the program does.
MeshTopology: What a mesh program’s primitives are.
MipFilter: How mip levels are used when a texture is minified.
Partitioning: How the tessellator spaces the vertices it adds along an edge.
ResourceKind: What a resource is.
SampleType: What a texture returns when it is read.
ScalarType: The scalar type of a value or constant.
ShaderFormat: How a shader program’s bytes are encoded. Only the encoding lives here; reading one is the job of the crate that knows it (iridia-dxbc, iridia-dxil, iridia-d3d9, iridia-mojo), and the program’s meaning is lifted from it on demand.
Stage: The pipeline stage a program runs in.
StageFacts: Facts about a program a stage’s varyings and resources do not carry.
StateParam: A piece of pipeline state a program reads (Op::LoadState), by the stage or unit it belongs to. A known one is folded into literals by specialisation; an unknown numeric one is carried in a state block the binding plan places; an unknown one that changes types (a texture’s dimension) has no uniform form.
StencilOp: A stencil operation (D3D12 and Vulkan have the same eight).
StorageTarget: What a storage resource is.
Subobject: A state object subobject of a ray tracing library, as the library declares it.
SystemValue: The system values, one vocabulary for every API: what the pipeline itself supplies to or takes from a stage.
TessDomain: The shape a tessellator gives a patch.
TessTopology: What the tessellator emits.
TextureDim: The dimensionality of a texture or image. Whether it is an array or multisampled is separate.
Unshown: Why a program does not show a matrix’s lines (MatrixLines::Unshown): the kind a consumer branches on, its text (core::fmt::Display) the reason.