tracel_rspirv/lib.rs
1//! Library APIs for SPIR-V module processing functionalities.
2//!
3//! This library provides:
4//!
5//! * The whole SPIR-V [grammar](grammar/index.html) (instruction layouts
6//! and their operands)
7//! * A [data representation](dr/index.html) of SPIR-V modules and its
8//! loader and builder
9//! * A [structured representation](sr/index.html) of SPIR-V modules
10//! (under developing)
11//! * SPIR-V [binary](binary/index.html) module decoding and parsing
12//! functionalities
13//!
14//! The data representation (DR) focuses on presenting the data within a
15//! SPIR-V module; it uses plain vectors to hold data of SPIR-V instructions,
16//! following the instructions' layouts defined in the grammar. DR has little
17//! structure; only bare structures need for representing modules, functions,
18//! and blocks are adopted.
19//!
20//! The structured representation (SR) focuses on presenting the structure
21//! within a SPIR-V module; it tries to links as much information as possible.
22//! Types, values, instructions, decorations and so on have their dedicated
23//! structs. The purpose of SR is to facilitate SPIR-V analysis and
24//! transformations.
25//!
26//! # Examples
27//!
28//! Building a SPIR-V module, assembling it, parsing it, and then
29//! disassembling it:
30//!
31//! ```
32//! use tracel_rspirv::binary::Assemble;
33//! use tracel_rspirv::binary::Disassemble;
34//! use tracel_rspirv::spirv;
35//!
36//! // Building
37//! let mut b = tracel_rspirv::dr::Builder::new();
38//! b.memory_model(spirv::AddressingModel::Logical, spirv::MemoryModel::GLSL450);
39//! let void = b.type_void();
40//! let voidf = b.type_function(void, vec![void]);
41//! b.begin_function(void,
42//! None,
43//! (spirv::FunctionControl::DONT_INLINE |
44//! spirv::FunctionControl::CONST),
45//! voidf)
46//! .unwrap();
47//! b.begin_block(None).unwrap();
48//! b.ret().unwrap();
49//! b.end_function().unwrap();
50//! let module = b.module();
51//!
52//! // Assembling
53//! let code = module.assemble();
54//! assert!(code.len() > 20); // Module header contains 5 words
55//! assert_eq!(spirv::MAGIC_NUMBER, code[0]);
56//!
57//! // Parsing
58//! let mut loader = tracel_rspirv::dr::Loader::new();
59//! tracel_rspirv::binary::parse_words(&code, &mut loader).unwrap();
60//! let module = loader.module();
61//!
62//! // Disassembling
63//! assert_eq!(module.disassemble(),
64//! "; SPIR-V\n\
65//! ; Version: 1.6\n\
66//! ; Generator: rspirv\n\
67//! ; Bound: 5\n\
68//! OpMemoryModel Logical GLSL450\n\
69//! %1 = OpTypeVoid\n\
70//! %2 = OpTypeFunction %1 %1\n\
71//! %3 = OpFunction %1 DontInline|Const %2\n\
72//! %4 = OpLabel\n\
73//! OpReturn\n\
74//! OpFunctionEnd");
75//! ```
76
77#[macro_use]
78extern crate bitflags;
79
80pub mod binary;
81pub mod dr;
82pub mod grammar;
83pub mod lift;
84pub mod spirv;
85pub mod sr;
86
87mod utils;