From e35f178011ac7a539a0d77a2cbf32770677cc531 Mon Sep 17 00:00:00 2001
From: SeanOMik <seanomik@gmail.com>
Date: Fri, 9 Aug 2024 12:36:35 -0400
Subject: [PATCH] Add README.md

---
 README.md                                | 83 ++++++++++++++++++++++++
 {shaders => examples}/base.wgsl          |  0
 {shaders => examples}/inner_include.wgsl |  0
 {shaders => examples}/simple.wgsl        |  0
 4 files changed, 83 insertions(+)
 create mode 100644 README.md
 rename {shaders => examples}/base.wgsl (100%)
 rename {shaders => examples}/inner_include.wgsl (100%)
 rename {shaders => examples}/simple.wgsl (100%)

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7b645c9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,83 @@
+# WGSL Preprocessor
+
+This crate was created for my 3d game engine, Lyra Engine, which uses this as a preprocessor.
+
+## Features
+
+* Modules import other modules via defined module paths
+More to come, check out issues in this repo.
+
+## How-To
+
+### Preprocessing modules
+
+To process modules, they first must be parsed to find the module paths of each file:
+
+```rust
+let mut p = Processor::new();
+
+let inner_include_src = fs::read_to_string("shaders/inner_include.wgsl").unwrap();
+let inner_module_path = p.parse_module(&inner_include_src)
+    .unwrap().expect("failed to find module");
+
+let simple_include_src = fs::read_to_string("shaders/simple.wgsl").unwrap();
+let simple_module_path = p.parse_module(&simple_include_src)
+    .unwrap().expect("failed to find module");
+
+let base_include_src = fs::read_to_string("shaders/base.wgsl").unwrap();
+let base_module_path = p.parse_module(&base_include_src)
+    .unwrap().expect("failed to find module");
+```
+
+Then, after all the modules are parsed, you can preprocess the module. This is where all the imported modules and items are compiled into a single output shader:
+
+```rust
+let out = p.process_file(&base_module_path, &base_include_src).unwrap();
+fs::write("out.wgsl", out).unwrap();
+```
+
+### Importing modules
+
+To import modules, that module must have its path defined. Do to so, at the top of the file, use the preprocessor command `#define_module <module_path>` with `module_path` being the identifier of the module and how its imported:
+
+```wgsl
+/// ==== shadows.wgsl
+#define_module engine::shadows
+
+const PCF_SAMPLES_NUM: u32 = 32;
+
+/// ==== pbr.wgsl
+#define_module engine::pbr
+#import engine::shadows::{PCF_SAMPLES_NUM}
+
+fn fs_main(in: VertexOutput) -> vec4<f32> {
+    // ...
+
+    let samples_num = PCF_SAMPLES_NUM;
+
+    // ...
+}
+```
+
+The above example imports an item from the `engine::shadows` module. Keep in mind that you cannot have conflicted names of variables, functions, types, and other imported things. Instead of importing an item from the module, you can import the module and use items from it (still no conflicting names):
+
+```wgsl
+/// ==== shadows.wgsl
+#define_module engine::shadows
+
+const PCF_SAMPLES_NUM: u32 = 32;
+
+/// ==== pbr.wgsl
+#define_module engine::pbr
+// not importing an item, but only a module
+#import engine::shadows
+
+fn fs_main(in: VertexOutput) -> vec4<f32> {
+    // ...
+
+    // use an item from the module here
+    let samples_num = shadows::PCF_SAMPLES_NUM;
+
+    // ...
+}
+```
diff --git a/shaders/base.wgsl b/examples/base.wgsl
similarity index 100%
rename from shaders/base.wgsl
rename to examples/base.wgsl
diff --git a/shaders/inner_include.wgsl b/examples/inner_include.wgsl
similarity index 100%
rename from shaders/inner_include.wgsl
rename to examples/inner_include.wgsl
diff --git a/shaders/simple.wgsl b/examples/simple.wgsl
similarity index 100%
rename from shaders/simple.wgsl
rename to examples/simple.wgsl