Crate dxil_reader 

A reader of Shader Model 6 programs (DXIL) as Direct3D stores them in a DXBC container: the program part’s header (program), its LLVM bitcode through a bounded bitstream reader (bitstream) into the module it holds (module), the entry point’s metadata, resource records and signature parts (reflection), the validator’s pipeline state record (psv), a library’s runtime data (rdat) and the texture and sampler each sampling call uses (sampling), each as the records the file stores with DXIL’s and D3D’s own numbers.

It reads and checks bytes and never interprets them for an API: a resource is its record’s class, range and shape numbers, a signature element its stored name, index, register and masks. Mapping those into a graphics API’s vocabulary is the caller’s choice. Everything it can’t read (a truncated record, an abbreviation it does not know, a reference outside its table) is an Error naming the bit where it happened; it never panics on untrusted input.

let container = std::fs::read("shader.dxil").expect("a compiled shader");
let parts = dxil_reader::parts(&container)?;
let module = dxil_reader::module(&parts, b"DXIL")?.expect("a DXIL part");
println!("{} functions", module.functions.len());

Re-exports

pub use module::Module;

Modules

bitstream

A bounded reader of LLVM’s bitstream container: blocks, abbreviations (literal, fixed, VBR, array, char6, blob) and the BLOCKINFO block. It knows nothing of IR; it returns a tree of blocks and records. Every length is checked against the bits that remain before anything is allocated, and nesting, abbreviations and the total number of operands are capped, so a crafted file errors instead of exhausting memory.

disasm

A disassembler of DXIL programs: the listing dxc -dumpbin (dxc 1.9.2609) prints of a container, byte for byte.

module

LLVM 3.7 IR as DXIL stores it, read from the bitstream tree: the type table, module values (globals, functions, constants), metadata, value names and function bodies. Only what DXIL programs use is decoded; any other record in a function body is refused by name. The blocks of a function body that say nothing a reader of the program’s behaviour needs (its metadata and its use-list order) are the only things skipped. The metadata attached to an instruction or a function is kept as the pairs the file stores (Instruction::attachments, Function::attachments, with the kind names in Module::kinds), dx.precise also as Instruction::precise; the attribute groups and lists are kept as stored (Module::attribute_groups, Module::attribute_lists) and each function value names its list.

psv

The pipeline state validation (PSV0) part of a Shader Model 6 program container: the runtime information, resource records and signature elements a pipeline is validated against, which the validator writes from the program’s own metadata. Little-endian.

rdat

The runtime data (RDAT) part of a library container: its subobjects (state object and pipeline configurations, root signatures and their associations, hit groups), which a ray tracing pipeline is built from.

reflection

The entry point’s metadata, resource records, type annotations and signature parts of an SM6 container, as the records the file stores: the entry point and what its properties state (thread group, geometry, mesh, hull and domain state), its signature elements and their packing, the bound resource ranges of dx.resources with their tags, the field annotations of dx.typeAnnotations, and the rows of an ISG1/OSG1/PSG1 part, each with DXIL’s and D3D’s own numbers, and the entry point’s other property tags, the tail tags of its signature elements, the optional fields of the resource records and the string attributes of the entry function. What the numbers mean for a graphics API is the caller’s to decide.

sampling

Which sampler each texture read of a module uses: every dx.op call that samples, gathers, queries the level of detail of or loads a resource, with the register, space and class of the texture’s handle and of the sampler’s handle, and whether the operation compares.

Structs

Error

Something the reader can’t read: the bit where it is (in the bitcode, or eight times a byte of the container or part being read), and what.

Part

The DXIL part of a DXBC container: the program header and its LLVM bitcode.

Functions

module

The module of a container’s program part of this kind (DXIL, or STAT for the reflection module), if it has one.

operations

The shader kind (0 pixel, 1 vertex, 2 geometry, 3 hull, 4 domain, 5 compute) of a container and the dx.op operations called across all the module’s function bodies (a hull shader’s patch-constant function is a second one), by name: for surveying which operations a set of shaders uses.

part

Find and check a container’s DXIL part.

parts

The parts of a DXBC container (its directory), an error of the container at the bit of its byte.

program

A program part’s header (DXIL and the STAT reflection part share it) and its bitcode.

Type Aliases

Result

The reader’s result: an Error naming the bit where reading failed.