| # Tint Architecture | |
| ``` | |
| ┏━━━━━━━━┓ ┏━━━━━━┓ | |
| ┃ SPIR━V ┃ ┃ WGSL ┃ | |
| ┗━━━━┃━━━┛ ┗━━━┃━━┛ | |
| ▼ ▼ | |
| ┏━━━━━━━━━┃━━━━━━━━━━━━━━━━━━━━━━━━━━━┃━━━━━━━━┓ | |
| ┃ ┃ Reader ┃ ┃ | |
| ┃ ┃ ┃ ┃ | |
| ┃ ┏━━━━━━━┻━━━━━━┓ ┏━━━━━━┻━━━━━━┓ ┃ | |
| ┃ ┃ SPIRV-Reader ┃ ┃ WGSL-Reader ┃ ┃ | |
| ┃ ┗━━━━━━━━━━━━━━┛ ┗━━━━━━━━━━━━━┛ ┃ | |
| ┗━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┛ | |
| ▼ | |
| ┏━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━┓ | |
| ┃ ProgramBuilder ┃ | |
| ┃ (mutable) ┃ | |
| ┏━━━━━━━━━━━━►┫ ┏━━━━━┓ ┏━━━━━━━┓ ┏━━━━━━━━━┓ ┃ | |
| ┃ ┃ ┃ AST ┃ ┃ Types ┃ ┃ Symbols ┃ ┃ | |
| ┃ ┃ ┗━━━━━┛ ┗━━━━━━━┛ ┗━━━━━━━━━┛ ┃ | |
| ┃ ┗━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┛ | |
| ┃ ▼ | |
| ┃ ┌┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┃┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐ | |
| ▲ ┆ Build ▼ ┆ | |
| ┏━━━┻━━━┓ ┆ ┏━━━━━━━━┻━━━━━━━━┓ ┆ | |
| ┃ Clone ┃ ┆ ┃ Resolver ┃ ┆ | |
| ┗━━━┳━━━┛ ┆ ┗━━━━━━━━━━━━━━━━━┛ ┆ | |
| ▲ └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┃┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘ | |
| ┃ ▼ | |
| ┃ ┏━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━┓ | |
| ┃ ┃ Program ┃ | |
| ┃ ┃ (immutable) ┃ | |
| ┣━━━━━━◄┫ ┏━━━━━┓ ┏━━━━━━━┓ ┏━━━━━━━━━━┓ ┏━━━━━━━━━┓ ┃ | |
| ┃ ┃ ┃ AST ┃ ┃ Types ┃ ┃ Semantic ┃ ┃ Symbols ┃ ┃ | |
| ┃ ┃ ┗━━━━━┛ ┗━━━━━━━┛ ┗━━━━━━━━━━┛ ┗━━━━━━━━━┛ ┃ | |
| ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┛ | |
| ▲ ▼ | |
| ┏━━━━━┻━━━━━┓ ┃ ┏━━━━━━━━━━━┓ | |
| ┃ Transform ┃◄━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━►┃ Inspector ┃ | |
| ┗━━━━━━━━━━━┛ ┃ ┗━━━━━━━━━━━┛ | |
| ▼ | |
| ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ | |
| ┃ Writers ┃ | |
| ┃ ┃ | |
| ┃ ┏━━━━━━━━━━━━━━┓┏━━━━━━━━━━━━━┓┏━━━━━━━━━━━━━┓┏━━━━━━━━━━━━━┓┏━━━━━━━━━━━━┓ ┃ | |
| ┃ ┃ SPIRV-Writer ┃┃ WGSL-Writer ┃┃ HLSL-Writer ┃┃ GLSL-Writer ┃┃ MSL-Writer ┃ ┃ | |
| ┃ ┗━━━━━━━┳━━━━━━┛┗━━━━━━┳━━━━━━┛┗━━━━━━┳━━━━━━┛┗━━━━━━┳━━━━━━┛┗━━━━━━┳━━━━━┛ ┃ | |
| ┗━━━━━━━━━┃━━━━━━━━━━━━━━┃━━━━━━━━━━━━━━┃━━━━━━━━━━━━━━┃━━━━━━━━━━━━━━┃━━━━━━━┛ | |
| ▼ ▼ ▼ ▼ ▼ | |
| ┏━━━━┻━━━┓ ┏━━━┻━━┓ ┏━━━┻━━┓ ┏━━━┻━━┓ ┏━━┻━━┓ | |
| ┃ SPIR-V ┃ ┃ WGSL ┃ ┃ HLSL ┃ ┃ GLSL ┃ ┃ MSL ┃ | |
| ┗━━━━━━━━┛ ┗━━━━━━┛ ┗━━━━━━┛ ┗━━━━━━┛ ┗━━━━━┛ | |
| ``` | |
| ## Reader | |
| Readers are responsible for parsing a shader program and populating a | |
| `ProgramBuilder` with the parsed AST, type and symbol information. | |
| The WGSL reader is a recursive descent parser. It closely follows the WGSL | |
| grammar in the naming of the parse methods. | |
| ## ProgramBuilder | |
| A `ProgramBuilder` is the primary interface to construct an immutable `Program`. | |
| There are a number of methods exposed which make creating of the `Program` | |
| simpler. A `ProgramBuilder` can only be used once, and must be discarded after | |
| the `Program` is constructed. | |
| A `Program` is built from the `ProgramBuilder` by `std::move()`ing the | |
| `ProgramBuilder` to a new `Program` object. When built, resolution is performed | |
| so the produced `Program` will contain all the needed semantic information. | |
| At any time before building the `Program`, `ProgramBuilder::IsValid()` may be | |
| called to ensure the AST is **structurally** correct. This checks that things | |
| like `if` statements have a condition and body attached. | |
| If further changes to the `Program` are needed (say via a `Transform`) then a | |
| new `ProgramBuilder` can be produced by cloning the `Program` into a new | |
| `ProgramBuilder`. | |
| Unlike `Program`s, `ProgramBuilder`s are not part of the public Tint API. | |
| ## AST | |
| The Abstract Syntax Tree is a directed acyclic graph of `ast::Node`s which | |
| encode the syntactic structure of the WGSL program. | |
| The root of the AST is the `ast::Module` class which holds each of the declared | |
| functions, variables and user defined types (type aliases and structures). | |
| Each `ast::Node` represents a **single** part of the program's source, and so | |
| `ast::Node`s are not shared. | |
| The AST does not perform any verification of its content. For example, the | |
| `ast::StrideAttribute` node has numeric stride parameter, which is a count of | |
| the number of bytes from the start of one array element to the start of the | |
| next. The AST node itself does not constrain the set of stride values that you | |
| can set, aside from storing it as an unsigned integer. | |
| ## Types | |
| Types are constructed during the Reader and resolution phases, and are | |
| held by the `Program` or `ProgramBuilder`. AST and semantic nodes can both | |
| reference types. | |
| Each `type::Type` node **uniquely** represents a particular spelling of a WGSL | |
| type within the program, so you can compare `type::Type*` pointers to check for | |
| equivalence of type expressions. | |
| For example, there is only one `type::Type` node for the `i32` type, no matter | |
| how many times it is mentioned in the source program. | |
| However, if `MyI32` is a type alias for `i32`, then they will have two different | |
| type nodes. | |
| ## Semantic information | |
| Semantic information is held by `sem::Node`s which describe the program at | |
| a higher / more abstract level than the AST. This includes information such as | |
| the resolved type of each expression, the resolved overload of a builtin | |
| function call, and the module scoped variables used by each function. | |
| Semantic information is generated by the `Resolver` when the `Program` | |
| is built from a `ProgramBuilder`. | |
| The `sem::Info` class holds a map of `ast::Node`s to `sem::Node`s. | |
| This map is **many-to-one** - i.e. while a AST node might have a single | |
| corresponding semantic node, the reverse may not be true. For example: | |
| many `ast::IdentifierExpression` nodes may map to a single `sem::Variable`, | |
| and so the `sem::Variable` does not have a single corresponding | |
| `ast::Node`. | |
| Unlike `ast::Node`s, semantic nodes may not necessarily form a directed acyclic | |
| graph, and the semantic graph may contain diamonds. | |
| ## Symbols | |
| Symbols represent a unique string identifier in the source program. These string | |
| identifiers are transformed into symbols within the `Reader`s. | |
| During the Writer phase, symbols may be emitted as strings using a `Namer`. | |
| A `Namer` may output the symbol in any form that preserves the uniqueness of | |
| that symbol. | |
| ## Resolver | |
| The `Resolver` will automatically run when a `Program` is built. | |
| A `Resolver` creates the `Program`s semantic information by analyzing the | |
| `Program`s AST and type information. | |
| The `Resolver` will validate to make sure the generated `Program` is | |
| semantically valid. | |
| ## Program | |
| A `Program` holds an immutable version of the information from the | |
| `ProgramBuilder` along with semantic information generated by the | |
| `Resolver`. | |
| Like `ProgramBuilder`, `Program::IsValid()` may be called to ensure the AST is | |
| structurally correct and semantically valid, and that the `Resolver` did not | |
| report any errors. | |
| Unlike the `ProgramBuilder`, a `Program` is fully immutable, and is part of the | |
| public Tint API. The immutable nature of `Program`s make these entirely safe | |
| to share between multiple threads without the use of synchronization primitives. | |
| ## Inspector | |
| The inspectors job is to go through the `Program` and pull out various pieces of | |
| information. The information may be used to pass information into the downstream | |
| compilers (things like specialization constants) or may be used to pass into | |
| transforms to update the AST before generating the resulting code. | |
| The input `Program` to the inspector must be valid (pass validation). | |
| ## Transforms | |
| There maybe various transforms we want to run over the `Program`. | |
| This is for things like Vertex Pulling or Robust Buffer Access. | |
| A transform operates by cloning the input `Program` into a new `ProgramBuilder`, | |
| applying the required changes, and then finally building and returning a new | |
| output `Program`. As the resolver is always run when a `Program` is built, | |
| Transforms will always emit a `Program` with semantic information. | |
| The input `Program` to a transform must be valid (pass validation). | |
| If the input `Program` of a transform is valid then the transform must guarantee | |
| that the output program is also valid. | |
| ## Writers | |
| A writer is responsible for writing the `Program` in the target shader language. | |
| The input `Program` to a writer must be valid (pass validation). |