Added initial documentation

Author: Cibbi

.docs/.gitignore

@@ -0,0 +1,11 @@
+###############
+#    folder   #
+###############
+/**/DROP/
+/**/TEMP/
+/**/packages/
+/**/bin/
+/**/obj/
+_site
+.idea/
+*.meta

.docs/api/.gitignore

@@ -0,0 +1,5 @@
+###############
+#  temp file  #
+###############
+*.yml
+.manifest

.docs/api/index.md

@@ -0,0 +1,3 @@
+# Welcome to the API Section
+
+Here you will find the documentation of each publicly available classes within the API.

.docs/docfx.json

@@ -0,0 +1,51 @@
+{
+  "metadata": [],
+  "build": {
+    "content": [],
+    "resource": [
+      {
+        "files": [
+          "images/**",
+          "logo.png",
+          "favicon.ico"
+        ]
+      }
+    ],
+    "overwrite": [
+      {
+        "files": [
+          "apidoc/**.md"
+        ],
+        "exclude": [
+          "obj/**",
+          "_site/**"
+        ]
+      }
+    ],
+    "dest": "_site",
+    "xref": [ "https://normanderwan.github.io/UnityXrefMaps/xrefmap.yml" ],
+    "xrefService": [ "https://xref.docs.microsoft.com/query?uid={uid}" ],
+    "postProcessors": [ "ExtractSearchIndex" ],
+    "globalMetadata": {
+      "_appTitle": "Modular Shader System Documentation",
+      "_appFooter": "<span>Copyright © VRLabs.<br>Generated by <strong>DocFX</strong></span>",
+      "_disableContribution": true,
+      "_enableSearch": "true"
+    },
+    "fileMetadataFiles": [],
+    "template": [
+      "default",
+      "templates/darkfx",
+      "templates/memberpage/content"
+    ],
+    "markdownEngineName": "markdig",
+    "noLangKeyword": false,
+    "keepFileLink": false,
+    "cleanupCacheHistory": false,
+    "sitemap": {
+      "baseUrl": "https://mss.vrlabs.dev",
+      "priority": 0.4,
+      "changefreq": "monthly"
+    }
+  }
+}

.docs/favicon.ico

@@ -0,0 +1,41 @@
+---
+uid: adv-EmbeddingLibrary
+title: Embedding The Library
+---
+
+# Embedding The Library
+
+Embedding the library is the process of making a functional copy of the library for your exclusive use, making you able to export a unity package of your modular shader without worrying about the end user having to download the modular shader system by themselves, and also gives you control over what version of the modular shader system the shader is shipped with.
+
+If you're planning to make a shader to publish it's important to do this as fist step, since there are going to be some differences applied to the embedded library compared to the base one.
+
+Luckily for you there's an editor window dedicated to this, and can be found in `VRLabs > Modular Shader > Embed Library`.
+
+## Embed Library Window
+
+![window](/images/docs/AdvancedTopics/1.png)
+
+The window contains some fields that are filled with the default values. Most of these values need to be changed based on your needs.
+
+- **Namespace:** this will be the namespace of the embedded library, it has to differ from `VRLabs` since this one is already there, and it would cause compilation errors. The end namespace will always be `*YourInput*.ModularShaderSystem` (a preview is visible in the window)
+- **Default variable keyword:** is the keyword used by default when no keywords are provided for variables. You can change it to whatever you want, or keep it like that.
+- **Default code keyword:** is the keyword used by default when no keywords are provided for function code implementation. You can change it to whatever you want, or keep it like that.
+- **Default properties keyword:** is the keyword used as an entry point for templates that target the property block when that option is enabled. You can change it to whatever you want, or keep it like that.
+- **Resource folder:** it will be the name used for the resource folder of the library, it has to be different from the default value to avoid having collisions with the default library resources, since otherwise when those resources are used the default library ones may be loaded instead if both the embedded and original library are in the project, which could cause issues if the 2 libraries are of different versions with breaking changes between the 2 of them.
+- **Template extension:** extension for the template file. It has to be different from the default value, to avoid collisions with the scripted importer of the 2 versions.
+- **Collection extension:** extension for the template collection file. It has to be different from the default value, to avoid collisions with the scripted importer of the 2 versions.
+- **Editor window menu path:** path to the editor windows in the menu, has to be different from the default one to avoid collisions with the base library, which would end up to being able to only have the options for 1 of the 2 libraries.
+- **Create asset menu path:** path to the create asset menu in the menu, has to be different from the default one to avoid collisions with the base library, which would end up to being able to only have the options for 1 of the 2 libraries.
+
+> [!IMPORTANT]
+> You should keep an eye to what public shaders using the system use for these options, since you also have to not collide with them.
+
+After setting all those options for the first time, it's a good idea to save them to a file, so that the next times you have to update the embedded library you can just load the options from the file.
+
+Now it's time to embed the library by clicking `Embed`. It will prompt you to select a folder to where to put the library. The folder must be a folder called `Editor` since everything needs to be an editor script. Once done the editor will copy the library with the modifications declared and save it under a folder called `ModularShaderSystem` inside the selected editor folder.
+
+From here you can use the embedded library directly to make your own shader. This has also the advantage that since you now have your own file extensions for templates and collections, they won't get mixed up with other's people modular shader templates.
+
+
+
+

.docs/guides/AdvancedTopics/EmbeddingLibrary.md

@@ -0,0 +1,97 @@
+---
+uid: adv-GeneratorDive
+title: Modular Shader Generator Deep Dive
+---
+
+# Modular Shader Generator Deep Dive
+
+The modular shader generator is fairly simple to use, you just call the [GenerateShader](xref:VRLabs.ModularShaderSystem.ShaderGenerator.GenerateShader) method, pass in the destination folder path, the modular shader, and you're done.
+
+But it may be useful to know what happens underneath and talk about the generation steps.
+
+First of all, the [GenerateShader](xref:VRLabs.ModularShaderSystem.ShaderGenerator.GenerateShader) is a wrapper that sets up one or more [ShaderContext](xref:VRLabs.ModularShaderSystem.ShaderGenerator.ShaderContext) objects, and these objects are what actually generate the shader.
+This separation is done so that the generator is unified in all use cases, for example in the library it's used for both generating the shader and generating optimised shaders.
+
+## GenerateShader method
+
+In the case of the [GenerateShader](xref:VRLabs.ModularShaderSystem.ShaderGenerator.GenerateShader) method, it first retrieves and reloads all the used template assets,
+then it evaluates all the possible variants combinations the modular shader has (as a reminder, variants are those templates that to be able to have the module toggled on and off, need to have the code actually removed, ending up with multiple shader files), 
+after that it generates the PropertyBlock string, which contains all properties declared in all modules (if you have the shader setup to use templates for properties, only the ones in the dedicated template in the modular shader asset is included here, the rest will be handled later with the other templates).
+
+The PropertyBlock string is generated outside of the shader context here cause they will all share the same properties, so you only need to generate it once.
+
+> [!NOTE]
+> in an ideal world reloading all template assets needed should not be done since you should be able to just take the reference from the modular shader and shader module assets, but in some specific situations (specifically when you first import unitypackages containing a modular shader, up until editor restart) that returns empty assets instead of our templates, so we just reload them for the generation process
+
+
+Now for each variant combination a ShaderContext is generated, by passing all its relevant informations.
+
+Now that we have a list of contexts to run, we will just process them all in parallel, since everything that a context does is manipulating strings, we aren't limited to do it inside the main thread. This speeds up a lot the generation of shaders that have a lot of variant combinations. 
+
+After all the contexts are done, we tell unity that we are starting to edit assets, write down files with the result of each context, and then tell unity we finished editing, so that it can import the newly generated shaders.
+
+To finish it off, we load all the newly generated shaders and add a reference to them in the modular shader asset, this way the modular shader always contains a reference to the last shaders that were generated with it.
+
+## The ShaderContext 
+
+As we previously said, a [ShaderContext](xref:VRLabs.ModularShaderSystem.ShaderGenerator.ShaderContext) takes care of generating a single shader file using the informations it has been given by calling its [GenerateShader](xref:VRLabs.ModularShaderSystem.ShaderGenerator.ShaderContext.GenerateShader) method.
+
+First it generates the name for both the file and the shader path in the material's shader selector, after that it generates the property section of the shader by using the provided property block or by generating its own if it's empty (in this case it makes the assumption that it's doing it for optimised shaders and does not include module's Enable properties).
+
+### Adding templates
+
+Then it's time to generate the SubShader block by applying the templates. They get listed from modules and then reordered by queue (this should keep the templates with the same queue ordered by position of their relative modules).
+
+Then for each template there's a check to see if the template is a toggleable template that doesn't need a variant, in which case the template code gets enclosed by an `if` check (in optimised shaders this would never happen since the module would not be even in the list of used modules for the context generation).
+
+After that it checks for the presence of any `internal keyword`, and each found one gets replaced with a runtime generated one that is dependent on the module id and original internal keyword. This is to assure that internal keywords that are in multiple modules don't actually get used by different modules from the one it was intended for.
+
+> [!NOTE]
+> the instanced internal keywords are stored in a dictionary where the key is a combination of module id and original internal keyword, so that it can be easily retrieved when we search an internal keyword for a specific template in a module.
+
+Now it's time to add the template to the main code by finding the indexes of the selected keywords (or instanced internal keywords), and inserting the template string (with the mentioned modifications) in each of these indexes, from the last one to the first one.
+
+> [!NOTE]
+> We go from last to first index because if we went the other way around after the first index is used the others would not be valid, since the keywords positions have shifted indexes by the amount of characters equivalent to the lenght of the inserted template.
+> 
+> We could have just taken that into account and also shifter our indexes after each iteration, but it's just simpler to start from the last and go backwards.
+
+Once all templates have been dealt with, all the instanced internal keywords get removed, since they're not going to be used anymore.
+
+### Adding functions
+
+Now it's time to add all the functions declared in modules, which is a bit more involved process since there are multiple things to keep track of.
+
+Fist we list all the functions that have to be added, then we start by adding all the variables in their respective keywords.
+This is done by looping each function, looking for which variables it declares, check which keywords they're supposed to go in, and then adding them to the respective list (these lists are contained in a dictionary where the key is the keyword they should go in).
+
+iterating all functions for their variables, for each list a string with the variable declarations is generated (duplicates of variables get removed here), and then each string is added to the shader code with the same logic templates did (minus the internal keywords that are not here anymore).
+
+Now that variables are dealt with, it's time for the functions themselves. Their order depends first on where they declare to go (keyword or other functions), then by their queue.
+Due to that, functions that go to keywords are the first to be looked at, since they are the root of the call chain. Therefore we look at all keywords that are being used by functions, and for each keyword we list all functions that go there, and order them by queue. Just like templates, we check if the function needs to be able to be disabled and in that case we enclose the call with an `if` check, and then append the string to the call sequence. 
+
+Before cycling to the next function in the list, we need to check if the function has other functions that declare to be appended right after it. This is pretty much the same process done with these top level functions, but using the function name instead of a keyword, so the entire process can be repeated recursively. And after that the next function in the list is evaluated and the process repeats.
+
+At the end of the call sequence evaluation of each keyword, the entire call sequence string gets appended to each keywords, with the same logic already used for templates and variables.
+
+During the evaluation process functions also get reordered into a list where the order is dependent on when a function has been used by the sequence, and this is used now to write down the actual function code implementation stored in template assets.
+For each function in the reordered list its code template string is taken and added to the relative keyword (in case of no keywords declared, the default `DEFAULT_CODE` keyword is used).
+
+> [!NOTE]
+> the code strings are stored in a dictionary of StringBuilders first, and then added to the main code by keywords later on, so that the final insertion to the keywords is done only once per keyword.
+
+During this process is also made sure that a code implementation template is not added more than once per keyword, to avoid code duplication that would make the shader fail to compile.
+
+### Final steps
+
+Now that functions have been taken of, there's some last things to take care of.
+First is to add the defined `CustomEditor` so that is used the inspector that has been defined in the modular shader asset, then a custom `PostGeneration` action is called.
+This action can be passed to the shader context to have custom code run at this step, this could be useful in case someone needs to do some edits to the shader code before it is finalized.
+
+> [!TIP]
+> You can still look for keywords at this stage.
+
+After that all the keywords used up to now get removed from the final shader code, since they are not needed anymore.
+
+And everything ends with a final code cleanup where the shader code gets indented correctly (for the most part) and line terminators get normalized.
+

.docs/guides/AdvancedTopics/ModularShaderDive.md

@@ -0,0 +1,62 @@
+ZTest[_ZTest]
+ZWrite[_ZWrite]
+Cull[_CullMode]
+
+Pass
+{
+    Tags 
+    {
+        "LightMode" = "ForwardBase" 
+    }
+
+    CGPROGRAM
+    #pragma target 3.0
+    #pragma vertex Vertex
+    #pragma fragment Fragment
+    
+    #include "UnityStandardUtils.cginc"
+
+    struct VertexData 
+    {
+        float4 vertex     : POSITION;
+        float2 uv         : TEXCOORD0;
+        float3 normal     : NORMAL;
+    };
+    
+    struct FragmentData 
+    {
+        float4 pos        : SV_POSITION;
+        float3 normal     : NORMAL;
+        float2 uv         : TEXCOORD0;
+        float3 worldPos   : TEXCOORD1;
+    };
+    
+    FragmentData FragData;
+    float4 FinalColor;
+    
+    #K#DEFAULT_VARIABLES
+    
+    #K#DEFAULT_CODE
+    
+    FragmentData Vertex (VertexData v)
+    {
+        FragmentData i;
+        UNITY_INITIALIZE_OUTPUT(FragmentData, i);
+        
+        #K#VERTEX_FUNCTION
+        
+        return i;
+    }
+    
+    float4 Fragment (FragmentData i) : SV_TARGET
+    {	
+        FragData = i;
+        FinalColor = float4(0,0,0,0);
+        
+        #K#FRAGMENT_FUNCTION
+        
+        return FinalColor;
+    }
+
+    ENDCG
+}

.docs/guides/Code/BaseTemplate.txt

@@ -0,0 +1,4 @@
+void ApplyColor()
+{
+    FinalColor = _MyColor;
+}

.docs/guides/Code/FragmentFunction.txt

@@ -0,0 +1,82 @@
+Shader "Example/ExampleShader"
+{
+	Properties
+	{
+		[Enum(UnityEngine.Rendering.CompareFunction)] _ZTest("Depth test", Float) = 4
+		_ZWrite("Depth write", Float) = 0
+		[Enum(UnityEngine.Rendering.CullMode)] _Cull("Cull Mode", Float) = 2
+		_MyColor("My Color", Color) = (1, 1, 1, 1)
+	}
+	SubShader
+	{
+		ZTest[_ZTest]
+		ZWrite[_ZWrite]
+		Cull[_CullMode]
+		
+		Pass
+		{
+			Tags
+			{
+				"LightMode" = "ForwardBase"
+			}
+			
+			CGPROGRAM
+			#pragma target 3.0
+			#pragma vertex Vertex
+			#pragma fragment Fragment
+			
+			#include "UnityStandardUtils.cginc"
+			
+			struct VertexData
+			{
+				float4 vertex     : POSITION;
+				float2 uv         : TEXCOORD0;
+				float3 normal     : NORMAL;
+			};
+			
+			struct FragmentData
+			{
+				float4 pos        : SV_POSITION;
+				float3 normal     : NORMAL;
+				float2 uv         : TEXCOORD0;
+				float3 worldPos   : TEXCOORD1;
+			};
+			
+			FragmentData FragData;
+			float4 FinalColor;
+			
+			float4 _MyColor;
+			
+			void ApplyColor()
+			{
+				FinalColor = _MyColor;
+			}
+			
+			FragmentData Vertex (VertexData v)
+			{
+				FragmentData i;
+				UNITY_INITIALIZE_OUTPUT(FragmentData, i);
+				
+				i.pos        = UnityObjectToClipPos(v.vertex);
+				i.normal     = UnityObjectToWorldNormal(v.normal);
+				i.worldPos   = mul(unity_ObjectToWorld, v.vertex);
+				i.uv         = v.uv;
+				
+				return i;
+			}
+			
+			float4 Fragment (FragmentData i) : SV_TARGET
+			{
+				FragData = i;
+				FinalColor = float4(0,0,0,0);
+				
+				ApplyColor();
+				
+				return FinalColor;
+			}
+			
+			ENDCG
+		}
+		
+	}
+}