Merge pull request #9404 from davidkline-ms/shaderSentinelVer

add versioning to the shader import logic

Author: David Kline

Assets/MRTK/StandardAssets/EditorUtilities/OnLoadUtilities.cs

@@ -11,45 +11,122 @@ namespace Microsoft.MixedReality.Toolkit.Utilities.Editor
     [InitializeOnLoad]
     static class OnLoadUtilities
     {
-        private const string SessionStateKey = "StandardAssetsOnLoadUtilitiesSessionStateKey";
-
         private const string ShaderSentinelGuid = "05852dd420bb9ec4cb7318bfa529d37c";
         private const string ShaderSentinelFile = "MRTK.Shaders.sentinel";
 
         private const string ShaderImportDestination = "MRTK/Shaders";
 
+        private const string IgnoreFileName = "IgnoreUpdateCheck.sentinel";
+
         static OnLoadUtilities()
         {
-            // This InitializeOnLoad handler only runs once at editor launch in order to adjust for Unity version
-            // differences. These don't need to (and should not be) run on an ongoing basis. This uses the
-            // volatile SessionState which is clear when Unity launches to ensure that this only runs the
-            // expensive work (file system i/o) once.
-            if (!SessionState.GetBool(SessionStateKey, false))
-            {
-                SessionState.SetBool(SessionStateKey, true);
-                EnsureShaders();
-            }
+            EnsureShaders(false);
+        }
+
+        /// <summary>
+        /// Checks for updated shaders and bypasses the ignore update check.
+        /// </summary>
+        [MenuItem("Mixed Reality Toolkit/Utilities/Check for Shader Updates")]
+        private static void CheckForShaderUpdates()
+        {
+            EnsureShaders(true);
         }
 
         /// <summary>
         /// Ensures that MRTK shader files are present in a writable location. To support the 
         /// Universal Render Pipeline, shader modifications must be persisted.
         /// </summary>
-        private static void EnsureShaders()
+        /// <param name="bypassIgnore">Causes the shader update code to disregard the ignore file.</param>
+        private static void EnsureShaders(bool bypassIgnore)
         {
-            if (!AssetsContainsShaders())
+            DirectoryInfo packageShaderFolder = FindShaderFolderInPackage();
+
+            if (bypassIgnore)
+            {
+                // The customer is manually checking for updates, delete the ignore file
+                string sentinelPath = AssetDatabase.GUIDToAssetPath(ShaderSentinelGuid);
+                if (!string.IsNullOrWhiteSpace(sentinelPath))
+                {
+                    FileInfo ignoreFile = new FileInfo(Path.Combine(new FileInfo(sentinelPath).Directory.FullName, IgnoreFileName));
+                    if (ignoreFile.Exists)
+                    {
+                        ignoreFile.Delete();
+                    }
+                    ignoreFile.Refresh();
+                }
+            }
+
+            if (!AssetsContainsShaders(packageShaderFolder))
             {
-                ImportShaderFiles();
+                ImportShaderFiles(packageShaderFolder);
             }
         }
 
         /// <summary>
         /// Checks to see if the Assets or Packages (if embedded) folder trees contains the MRTK shaders.
         /// </summary>
         /// <returns>True if the shader sentinel file is found, otherwise false.</returns>
-        private static bool AssetsContainsShaders()
+        private static bool AssetsContainsShaders(DirectoryInfo packageShaderFolder)
         {
-            return !string.IsNullOrWhiteSpace(AssetDatabase.GUIDToAssetPath(ShaderSentinelGuid));
+            string sentinelPath = AssetDatabase.GUIDToAssetPath(ShaderSentinelGuid);
+
+            // If we do not find the sentinel, we need to import the shaders.
+            if (string.IsNullOrWhiteSpace(sentinelPath))
+            {
+                return false;
+            }
+
+            // Getting here indicates that the project's Assets folder contains the shader sentinel.
+
+            // Check for the "ignore this check" file, if present we do NOT import
+            FileInfo ignoreFile = new FileInfo(Path.Combine(new FileInfo(sentinelPath).Directory.FullName, IgnoreFileName));
+            if (ignoreFile.Exists)
+            {
+                return true;
+            }
+
+            // If the package shader folder does not exist, there is nothing for us to do.
+            if ((packageShaderFolder == null) || !packageShaderFolder.Exists)
+            {
+                return true;
+            }
+
+            // Get the versions of the sentinel files,
+            int packageVer = ReadSentinelVersion(Path.Combine(packageShaderFolder.FullName, ShaderSentinelFile));
+            int assetVer = ReadSentinelVersion(sentinelPath);
+
+            // No need to copy if the versions are the same.
+            if (packageVer == assetVer)
+            {
+                return true;
+            }
+
+            string message = (packageVer < assetVer) ?
+                "The MRTK shaders older than those in your project, do you wish to overwrite the existing shaders?" :
+                "Updated MRTK shaders are available, do you wish to overwrite the existing shaders?";
+
+            int dialogResponse = EditorUtility.DisplayDialogComplex(
+                "Mixed Reality Toolkit Standard Assets",
+                message +
+                "\n\nNOTE: Overwriting will lose any customizations and may require reconfiguring the render pipeline.",
+                "Yes",      // returns 0
+                "Ignore",   // returns 1 - placed in the cancel slot to force the button order as Yes, No, Ignore
+                "No");      // returns 2
+
+            if (dialogResponse == 1)
+            {
+                // Write an "ignore this check" file to prevent future prompting
+                if (!ignoreFile.Directory.Exists)
+                {
+                    ignoreFile.Directory.Create();
+                }
+                ignoreFile.Create();
+            }
+            ignoreFile.Refresh();
+
+            // Return the inverse of the dialog result. Result of true means we want to overwrite, this method returns false
+            // to cause an overwrite.
+            return (dialogResponse != 0);
         }
 
         /// <summary>
@@ -85,10 +162,9 @@ private static DirectoryInfo FindShaderFolderInPackage()
         /// <summary>
         /// Copies the shader files from the package cache to the Assets folder tree.
         /// </summary>
-        private static void ImportShaderFiles()
+        private static void ImportShaderFiles(DirectoryInfo packageShaderFolder)
         {
-            DirectoryInfo source = FindShaderFolderInPackage();
-            if (source == null)
+            if (packageShaderFolder == null)
             {
                 Debug.LogError("Unable to locate the shader source folder in the package");
                 return;
@@ -100,11 +176,43 @@ private static void ImportShaderFiles()
                 destination.Create();
             }
 
-            FileInfo[] sourceFiles = source.GetFiles();
+            FileInfo[] sourceFiles = packageShaderFolder.GetFiles();
             foreach (FileInfo fi in sourceFiles)
             {
-                fi.CopyTo(Path.Combine(destination.FullName, fi.Name));
+                fi.CopyTo(Path.Combine(destination.FullName, fi.Name), true);
+            }
+        }
+
+        /// <summary>
+        /// Reads the version number out of the shader 
+        /// </summary>
+        /// <param name="sentinelPath">The path to the sentinel file.</param>
+        /// <returns>The version number found in the file, or -1.</returns>
+        private static int ReadSentinelVersion(string sentinelPath)
+        {
+            using (FileStream fs = new FileStream(sentinelPath, FileMode.Open, FileAccess.Read))
+            {
+                using (StreamReader reader = new StreamReader(fs))
+                {
+                    const string token = "ver:";
+
+                    while (!reader.EndOfStream)
+                    {
+                        string line = reader.ReadLine();
+                        if (line.StartsWith(token))
+                        {
+                            line = line.Substring(token.Length).Trim();
+                            if (!int.TryParse(line, out int ver))
+                            {
+                                break;
+                            }
+                            return ver;
+                        }
+                    }
+                }
             }
+
+            return -1;
         }
     }
 }

Assets/MRTK/StandardAssets/Shaders/ChannelPacker.shader

@@ -1,6 +1,9 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+// NOTE: MRTK Shaders are versioned via the MRTK.Shaders.sentinel file.
+// When making changes to any shader's source file, the value in the sentinel _must_ be incremented.
+
 Shader "Hidden/ChannelPacker"
 {
     Properties

Assets/MRTK/StandardAssets/Shaders/DepthBufferPostProcess.shader

@@ -1,6 +1,9 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+// NOTE: MRTK Shaders are versioned via the MRTK.Shaders.sentinel file.
+// When making changes to any shader's source file, the value in the sentinel _must_ be incremented.
+
 Shader "Mixed Reality Toolkit/Depth Buffer Viewer"
 {
     Properties

Assets/MRTK/StandardAssets/Shaders/InstancedColored.shader

@@ -1,6 +1,9 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+// NOTE: MRTK Shaders are versioned via the MRTK.Shaders.sentinel file.
+// When making changes to any shader's source file, the value in the sentinel _must_ be incremented.
+
 Shader "Hidden/Instanced-Colored"
 {
     Properties

Assets/MRTK/StandardAssets/Shaders/InvisibleShader.shader

@@ -1,6 +1,9 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+// NOTE: MRTK Shaders are versioned via the MRTK.Shaders.sentinel file.
+// When making changes to any shader's source file, the value in the sentinel _must_ be incremented.
+
 Shader "Mixed Reality Toolkit/InvisibleShader" {
 
 	Subshader

Assets/MRTK/StandardAssets/Shaders/MRTK.Shaders.sentinel

@@ -0,0 +1 @@
+ver: 0

Assets/MRTK/StandardAssets/Shaders/MRTK_Wireframe.shader

@@ -1,6 +1,9 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+// NOTE: MRTK Shaders are versioned via the MRTK.Shaders.sentinel file.
+// When making changes to any shader's source file, the value in the sentinel _must_ be incremented.
+
 ///
 /// Basic wireframe shader that can be used for rendering spatial mapping meshes.
 ///

Assets/MRTK/StandardAssets/Shaders/MixedRealityStandard.shader

@@ -1,6 +1,9 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+// NOTE: MRTK Shaders are versioned via the MRTK.Shaders.sentinel file.
+// When making changes to any shader's source file, the value in the sentinel _must_ be incremented.
+
 Shader "Mixed Reality Toolkit/Standard"
 {
     Properties

Assets/MRTK/StandardAssets/Shaders/MixedRealityTextMeshPro.shader

@@ -1,6 +1,9 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+// NOTE: MRTK Shaders are versioned via the MRTK.Shaders.sentinel file.
+// When making changes to any shader's source file, the value in the sentinel _must_ be incremented.
+
 // Simplified SDF shader:
 // - No Shading Option (bevel / bump / env map)
 // - No Glow Option

Assets/MRTK/StandardAssets/Shaders/Text3DShader.shader

@@ -1,6 +1,9 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+// NOTE: MRTK Shaders are versioned via the MRTK.Shaders.sentinel file.
+// When making changes to any shader's source file, the value in the sentinel _must_ be incremented.
+
 ///
 /// Basic 3D TextMesh shader with proper z-sorting and culling options.
 ///

Assets/MRTK/StandardAssets/packagetemplate.json

@@ -28,6 +28,6 @@
         "url": "https://github.com/microsoft/MixedRealityToolkit-Unity/issues"
     },
     "dependencies": {
-        "com.unity.textmeshpro": "2.1.1"
+        "com.unity.textmeshpro": "2.1.4"
     }
 }

Documentation/Images/Tools/ShaderUpdateMenu.png

@@ -0,0 +1,22 @@
+# Updating Shaders
+
+Starting with version 2.6.0, the MRTK shaders are being versioned via the MRTK.Shaders.sentinel file. When upgrading to a new version of MRTK, the following message may appear.
+
+![Update shaders prompt](../Images/Tools/UpdateShaderPrompt.png)
+
+Selecting **Yes** instructs MRTK to overwrite the contents of **Assets** > **MRTK** > **Shaders** with the latest version. Selecting **No** will preserve the current files. **Ignore** will create a file (`IgnoreUpdateCheck.sentinel`) in **Assets** > **MRTK** > **Shaders**, which will suppress future shader update checks.
+
+> [!IMPORTANT]
+> When overwriting the shader files, any custom modifications will be lost. Be sure to backup any modified shader files before upgrading.
+>
+> If the project has been configured to use the Universal Render Pipeline (URP) - formerly Lightweight Render Pipeline (LWRP), please re-run **Mixed Reality Toolkit** > **Utilities** >
+> **Upgrade MRTK Standard Shader for Lightweight Render Pipeline**.
+
+At is also possible to check for shader updates at any time using **Mixed Reality Toolkit** > **Utilities** > **Check for Shader Updates** on the Unity Editor's menu bar.
+
+![Check for shader updates](../Images/Tools/ShaderUpdateMenu.png)
+
+**Check for Shader Updates** disregards the `IgnoreUpdateCheck.sentinel` file and allows on-demand shader updating.
+
+> [!NOTE]
+> Checking for shader updates is not required when importing the MRTK .unitypackage files.