spirq/
lib.rs

1//! # SPIR-Q: Light Weight SPIR-V Query Utility for Graphics.
2//!
3//! SPIR-Q is a light weight library for SPIR-V pipeline metadata query, which
4//! can be very useful for dynamic graphics/compute pipeline construction,
5//! shader debugging and so on. SPIR-Q is currently compatible with a subset of
6//! SPIR-V 1.5, with most of graphics capabilities but no OpenCL kernel
7//! capabilities covered.
8//!
9//! ## How-to
10//!
11//! ```ignore
12//! use spirq::prelude::*;
13//!
14//! let entry_points = ReflectConfig::new()
15//!     // Load SPIR-V data into `[u32]` buffer `spv_words`.
16//!     .spv(spv_words)
17//!     // Set this true if you want to reflect all resources no matter it's
18//!     // used by an entry point or not.
19//!     .ref_all_rscs(true)
20//!     // Combine sampled image and separated sampler states if they are bound
21//!     // to the same binding point.
22//!     .combine_img_samplers(true)
23//!     // Generate unique names for types and struct fields to help further
24//!     // processing of the reflection data. Otherwise, the debug names are
25//!     // assigned.
26//!     .gen_unique_names(true)
27//!     // Specialize the constant at `SpecID=3` with unsigned integer 7. The
28//!     // constants specialized here won't be listed in the result entry point's
29//!     // variable list.
30//!     .specialize(3, ConstantValue::U32(7))
31//!     // Do the work.
32//!     .reflect()
33//!     .unwrap();
34//! // All extracted entry point data are available in `entry_points` now.
35//! ```
36//!
37//! By calling [`reflect`] of the wrapper type [`SpirvBinary`], every entry
38//! point in the binary are analyzed and reported as one or more
39//! [`EntryPoint`]s with all the types and bindings/locations.
40//!
41//! ## Size calculation
42//!
43//! The struct member offsets and array/matrix strides are specified in SPIR-V
44//! files. With these information SPIR-Q deduce the minimal size required for
45//! to contain an instance of a type. However, SPIR-Q cannot handle dynamically-
46//! sized arrays, and it will treat such arrays as zero-sized. The user has to
47//! handle such SSBO-like themselves via [`Type`] APIs.
48//!
49//! Note: It should be noted that descriptor multibinds are treated like single-
50//! binds because although they use the same syntax as arrays, they are not
51//! actually arrays.
52//!
53//! Note: Although `spv` files generated directly from compilers normally keep
54//! the nameing data, it should be noticed that names are debug information that
55//! might be wiped out during compression.
56//!
57//! [`SpirvBinary`]: struct.SpirvBinary.html
58//! [`EntryPoint`]: struct.EntryPoint.html
59//! [`reflect`]: reflect/struct.ReflectConfig.html#method.reflect
60//! [`Type`]: ty/enum.Type.html
61mod instr;
62
63pub mod entry_point;
64pub mod inspect;
65pub mod reflect;
66pub mod reflect_cfg;
67
68#[cfg(test)]
69mod tests;
70
71pub use spq_core::annotation;
72pub use spq_core::constant;
73pub use spq_core::error;
74pub use spq_core::evaluator;
75pub use spq_core::func;
76pub use spq_core::parse;
77pub use spq_core::spirv;
78pub use spq_core::ty;
79pub use spq_core::var;
80
81pub use reflect_cfg::ReflectConfig;
82
83// Re-exports.
84pub mod prelude {
85    pub use super::ReflectConfig;
86    pub use super::{
87        constant::ConstantValue,
88        entry_point::{EntryPoint, ExecutionModel},
89        error::{Error, Result},
90        parse::SpirvBinary,
91        ty::{AccessType, DescriptorType, SpirvType, Type},
92        var::{DescriptorBinding, InterfaceLocation, SpecId, Variable},
93    };
94}
spirq/lib.rs

spirq/
lib.rs
