From f8209946e332a3cbeea246d82c5a58b234f32909 Mon Sep 17 00:00:00 2001
From: Michael Tang <tangmi@uw.edu>
Date: Sat, 12 Sep 2020 13:49:28 -0700
Subject: [PATCH] Update documentation for building shaders

---
 resources/shaders/README.md |  7 ++-----
 shaders/Makefile            |  8 +++++---
 shaders/README.md           | 26 ++++++++++++++++++++++++++
 3 files changed, 33 insertions(+), 8 deletions(-)
 create mode 100644 shaders/README.md

diff --git a/resources/shaders/README.md b/resources/shaders/README.md
index 24bff80f..163ba3f1 100644
--- a/resources/shaders/README.md
+++ b/resources/shaders/README.md
@@ -1,7 +1,4 @@
 This directory contains postprocessed versions of the shaders in the top-level
 `shaders/` directory, for convenience. Don't modify the shaders here; instead
-modify the corresponding shaders in `shaders/` and rerun `make` in that
-directory.
-
-You will need `glslangValidator` and `spirv-cross` installed to execute the
-Makefile. On macOS, you can get these with `brew install glslang spirv-cross`.
+modify the corresponding shaders in `shaders/` and rebuild them according to
+`shaders/README.md`.
\ No newline at end of file
diff --git a/shaders/Makefile b/shaders/Makefile
index 15d8a329..2154c2c4 100644
--- a/shaders/Makefile
+++ b/shaders/Makefile
@@ -58,6 +58,8 @@ OUT=\
 
 GLSL_3_VERSION=330
 GLSL_4_VERSION=430
+
+GLSLANG?=glslangValidator
 GLSLANGFLAGS=--auto-map-locations -I.
 GLSLANGFLAGS_METAL=$(GLSLANGFLAGS) -DPF_ORIGIN_UPPER_LEFT=1
 
@@ -81,13 +83,13 @@ clean:
 	rm -f $(OUT)
 
 build/metal/%.spv:	%.glsl $(INCLUDES)
-	mkdir -p $(dir $@) && glslangValidator $(GLSLANGFLAGS_METAL) -G$(GLSL_VERSION) -S $(GLSL_SHADER_TYPE$(suffix $(basename $(notdir $<)))) -o $@ $<
+	mkdir -p $(dir $@) && $(GLSLANG) $(GLSLANGFLAGS_METAL) -G$(GLSL_VERSION) -S $(GLSL_SHADER_TYPE$(suffix $(basename $(notdir $<)))) -o $@ $<
 
 $(TARGET_DIR)/gl3/%.glsl:	%.glsl $(INCLUDES)
-	mkdir -p $(dir $@) && echo $(GLSL_VERSION_HEADER) > $@ && echo $(HEADER) >> $@ && ( glslangValidator $(GLSLANGFLAGS) -S $(GLSL_SHADER_TYPE$(suffix $(basename $(notdir $<)))) -E $< | sed $(GLSL_SED_ARGS) >> $@ ) || ( rm $@ && exit 1 )
+	mkdir -p $(dir $@) && echo $(GLSL_VERSION_HEADER) > $@ && echo $(HEADER) >> $@ && ( $(GLSLANG) $(GLSLANGFLAGS) -S $(GLSL_SHADER_TYPE$(suffix $(basename $(notdir $<)))) -E $< | sed $(GLSL_SED_ARGS) >> $@ ) || ( rm $@ && exit 1 )
 
 $(TARGET_DIR)/gl4/%.glsl:	%.glsl $(INCLUDES)
-	mkdir -p $(dir $@) && echo $(GLSL_VERSION_HEADER) > $@ && echo $(HEADER) >> $@ && ( glslangValidator $(GLSLANGFLAGS) -S $(GLSL_SHADER_TYPE$(suffix $(basename $(notdir $<)))) -E $< | sed $(GLSL_SED_ARGS) >> $@ ) || ( rm $@ && exit 1 )
+	mkdir -p $(dir $@) && echo $(GLSL_VERSION_HEADER) > $@ && echo $(HEADER) >> $@ && ( $(GLSLANG) $(GLSLANGFLAGS) -S $(GLSL_SHADER_TYPE$(suffix $(basename $(notdir $<)))) -E $< | sed $(GLSL_SED_ARGS) >> $@ ) || ( rm $@ && exit 1 )
 
 $(TARGET_DIR)/metal/%.metal:   build/metal/%.spv
 	mkdir -p $(dir $@) && echo $(HEADER) > $@ && ( $(SPIRVCROSS) $(SPIRVCROSSFLAGS) $< >> $@ ) || ( rm $@ && exit 1 )
diff --git a/shaders/README.md b/shaders/README.md
new file mode 100644
index 00000000..31f847ae
--- /dev/null
+++ b/shaders/README.md
@@ -0,0 +1,26 @@
+# Building the shaders
+
+You will need `glslangValidator` and `spirv-cross` installed to execute the
+Makefile from this directory. You can speed up the build by parallelizing the
+build: `make -j`.
+
+## macOS
+
+You can use [Homebrew](https://brew.sh/) to install the dependencies:
+
+```sh
+brew install glslang spirv-cross
+```
+
+## Windows
+
+`glslangValidator` and `spirv-cross` are available by installing the
+[Vulkan SDK](https://vulkan.lunarg.com/sdk/home). You'll also need some commands
+like `make`, `rm`, etc. These are available on the
+[Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
+shell. You'll need to set these environment variables for `make` to succeed:
+
+```sh
+export GLSLANG=glslangValidator.exe
+export SPIRVCROSS=spirv-cross.exe
+```