41 releases (7 stable)

new 1.2.0 Mar 23, 2024
1.1.1 Dec 26, 2023
0.6.4 Jun 1, 2023
0.6.3 Jan 31, 2023
0.1.0 Dec 28, 2019

#38 in Graphics APIs

Download history 8/week @ 2023-12-11 26/week @ 2023-12-18 127/week @ 2023-12-25 10/week @ 2024-02-05 16/week @ 2024-02-12 62/week @ 2024-02-19 65/week @ 2024-02-26 9/week @ 2024-03-04 171/week @ 2024-03-11 216/week @ 2024-03-18

464 downloads per month
Used in 14 crates (9 directly)

MIT/Apache

94KB
2.5K SLoC

SPIR-Q

Crate Documentation

SPIR-Q is a light weight library for SPIR-V pipeline metadata query, supporting upto SPIR-V 1.5 specification aligned with Vulkan 1.3.

Why SPIR-Q?

Back in days of OpenGL, we have glGetActiveUniformsiv and other APIs to get pipeline metadata, so that we can determine the sizes, names, array strides and other information dynamically at runtime. However, the next-gen API, Vulkan, was deisgned not to support shader reflection so that the driver can be kept as thin as possible. SPIR-Q is an attempt to fill this gap.

SPIR-Q can be very useful for scenarios where we want some dynamic in pipeline construction, so that we don't have to refill those redundantly long VkXxxCreateInfos all the time. It can also be used to automate filler code generation at compile time.

It should be noted that SPIR-V is targeting at Vulkan so OpenCL binaries are not supported.

Usage

use spirq::*;
let entry_points = ReflectConfig::new()
    // Load SPIR-V data into `[u32]` buffer `spv_words`.
    .spv(spv_words)
    // Set this true if you want to reflect all resources no matter it's
    // used by an entry point or not.
    .ref_all_rscs(true)
    // Combine sampled image and separated sampler states if they are bound
    // to the same binding point.
    .combine_img_samplers(true)
    // Generate unique names for types and struct fields to help further
    // processing of the reflection data. Otherwise, the debug names are
    // assigned.
    .gen_unique_names(true)
    // Specialize the constant at `SpecID=3` with unsigned integer 7. The
    // constants specialized here won't be listed in the result entry point's
    // variable list.
    .specialize(3, ConstantValue::U32(7))
    // Do the work.
    .reflect()
    .unwrap();
// All extracted entry point data are available in `entry_points` now.

Please also refer to the attached examples:

  • walk: Enumerate offsets, symbols and types of all descriptor variables.
  • inspect: Customize shader reflection with your own inspector function.
  • gallery: All data types in GLSL.

Sample output are attached in the same directories as the code files.

License

This project is licensed under either of

at your option.

Dependencies

~1.8–2.4MB
~51K SLoC