Crate spirq

SPIR-Q: Light Weight SPIR-V Query Utility for Graphics.

SPIR-Q is a light weight library for SPIR-V pipeline metadata query, which can be very useful for dynamic graphics/compute pipeline construction, shader debugging and so on. SPIR-Q is currently compatible with a subset of SPIR-V 1.5, with most of graphics capabilities but no OpenCL kernel capabilities covered.

How-to

// Load SPIR-V data into `[u32]` buffer `spv_words`.
let spv: SpirvBinary = spv_words.into();
let entries = spv.reflect().unwrap();
// All extracted entry point data are available in `entries`.

By calling reflect of the wrapper type SpirvBinary, every entry point in the binary are analyzed and reported as one or more EntryPoints. Each entry point has a Manifest that supports queries from allocation requirement to fine-grained typing details.

Size calculation

The struct member offsets and array/matrix strides are specified in SPIR-V files. With these information SPIR-Q deduce the minimal size required for to contain an instance of a type. However, SPIR-Q cannot handle dynamically- sized arrays, and it will treat such arrays as zero-sized. The user has to handle such SSBO-like themselves via Type APIs.

Symbol resolution

SPIR-Q uses a very simple solution to help you locate any metadata including input/output variables, descriptors and variables defined inside those descriptors. We call it a Symbol. A symbol is a dot-separated list of identifiers. Identifiers can be an index or a name literal (or empty for the push constant block.)

Input/output variables are referred to by their locations. The following are examples of input/output variable symbols:

1
aTexCoord
vWorldPosition
1.2 // ERROR: I/O variables cannot be nested.
gl_Position // WARNING: Built-in variables are ignored during reflection.

Descriptors have to be referred to with both the descriptor set number and its binding point number specified. The following are valid symbols for descriptor variables:

0.1 // Refering to the descriptor at set 0 on binding 1.
light.0 // Refering to the first member of block 'light'.
1.0.bones.4 // Refering to the 5th element of array member `bones` in descriptor `1.0`.
.modelview // Push constants are referred to by an empty identifier.

Note: It should be noted that descriptor multibinds are treated like single- binds because although they use the same syntax as arrays, they are not actually arrays.

Note: Although spv files generated directly from compilers normally keep the nameing data, it should be noticed that names are debug information that might be wiped out during compression.

Re-exports

pub use sym::*;

pub use error::*;

Modules

error	Error and result reported by SPIR-Q procedures.
sym	Sym used to identify shader module resources.
ty	Structured representations of SPIR-V types.

Structs

DescriptorBinding	Descriptor set and binding point carrier.
DescriptorResolution	Descriptor variable resolution result.
EntryPoint	Representing an entry point described in a SPIR-V.
InterfaceLocation	Interface variable location and component.
InterfaceVariableResolution	Interface variables resolution result.
Manifest	A set of information used to describe variable typing and routing.
MemberVariableResolution	Member variable resolution result.
SpirvBinary	SPIR-V program binary.

Enums

AccessType	Access type of a variable.
ExecutionModel	SPIR-V operand kind: ExecutionModel