Added documentation for material GUI

com.unity.render-pipelines.high-definition/Editor/Material/MaterialHeaderScope.cs

@@ -26,6 +26,15 @@ internal struct MaterialHeaderScope : IDisposable
         int oldIndentLevel;
 #endif
 
+        /// <summary>
+        /// Creates a material header scope to display the foldout in the material UI.
+        /// </summary>
+        /// <param name="title">Title of the header.</param>
+        /// <param name="bitExpanded">Bit index which specifies the state of the header (whether it is open or collapsed) inside Editor Prefs.</param>
+        /// <param name="materialEditor">The current material editor.</param>
+        /// <param name="spaceAtEnd">Set this to true to make the block include space at the bottom of its UI. Set to false to not include any space.</param>
+        /// <param name="colorDot">Specify a color to display a dot, like in the layered UI.</param>
+        /// <param name="subHeader">Set to true to make this into a sub-header. This affects the style of the header. Set to false to make this use the standard style.</param>
         public MaterialHeaderScope(string title, uint bitExpanded, MaterialEditor materialEditor, bool spaceAtEnd = true, Color colorDot = default(Color), bool subHeader = false)
         {
             bool beforeExpended = materialEditor.GetExpandedAreas(bitExpanded);
@@ -66,6 +75,7 @@ internal struct MaterialHeaderScope : IDisposable
                 ++EditorGUI.indentLevel;
         }
 
+        /// <summary>Disposes of the material scope header and cleans up any resources it used.</summary>
         void IDisposable.Dispose()
         {
             if (expanded)

com.unity.render-pipelines.high-definition/Editor/Material/UIBlocks/HDShaderGUI.cs

@@ -17,21 +17,37 @@ namespace UnityEditor.Rendering.HighDefinition
     // of the material you must use Material UI Blocks, examples of doing so can be found in the classes UnlitGUI,
     // LitGUI or LayeredLitGUI.
 
-    abstract class HDShaderGUI : ShaderGUI
+    /// <summary>
+    /// Use this class to build your custom Shader GUI for HDRP.
+    /// You can use a class that inherits from HDShaderGUI in the Shader Graph Custom EditorGUI field.
+    /// </summary>
+    internal abstract class HDShaderGUI : ShaderGUI
     {
-        protected bool m_FirstFrame = true;
+        internal protected bool m_FirstFrame = true;
 
         // The following set of functions are call by the ShaderGraph
         // It will allow to display our common parameters + setup keyword correctly for them
+
         protected abstract void SetupMaterialKeywordsAndPassInternal(Material material);
 
+        /// <summary>
+        /// Unity calls this function when you assign a new shader to the material.
+        /// </summary>
+        /// <param name="material">The current material.</param>
+        /// <param name="oldShader">The shader the material currently uses.</param>
+        /// <param name="newShader">The new shader to assign to the material.</param>
         public override void AssignNewShaderToMaterial(Material material, Shader oldShader, Shader newShader)
         {
             base.AssignNewShaderToMaterial(material, oldShader, newShader);
 
             SetupMaterialKeywordsAndPassInternal(material);
         }
 
+        /// <summary>
+        /// Sets up the keywords and passes for the material. You must call this function after you change a property on a material to ensure it's validity.
+        /// </summary>
+        /// <param name="changed">GUI.changed is the usual value for this parameter. If this value is false, the function just exits.</param>
+        /// <param name="materials">The materials to perform the setup on.</param>
         protected void ApplyKeywordsAndPassesIfNeeded(bool changed, Material[] materials)
         {
             // !!! HACK !!!
@@ -49,6 +65,9 @@ protected void ApplyKeywordsAndPassesIfNeeded(bool changed, Material[] materials
             }
         }
 
+        /// <summary>
+        /// Unity calls this function when it displays the GUI. This method is sealed so you cannot override it. To implement your custom GUI, use OnMaterialGUI instead.
+        /// </summary>
         public sealed override void OnGUI(MaterialEditor materialEditor, MaterialProperty[] props)
         {
             if (!(RenderPipelineManager.currentPipeline is HDRenderPipeline))
@@ -61,12 +80,21 @@ public sealed override void OnGUI(MaterialEditor materialEditor, MaterialPropert
             }
         }
 
+        /// <summary>
+        /// Implement your custom GUI in this function. To display a UI similar to HDRP shaders, use a MaterialUIBlock.
+        /// </summary>
+        /// <param name="materialEditor">The current material editor.</param>
+        /// <param name="props">The list of properties the material has.</param>
         protected abstract void OnMaterialGUI(MaterialEditor materialEditor, MaterialProperty[] props);
 
         readonly static string[] floatPropertiesToSynchronize = {
             kUseSplitLighting
         };
 
+        /// <summary>
+        /// Synchronize a set of properties that Unity requires for Shader Graph materials to work correctly. This function is for Shader Graph only.
+        /// </summary>
+        /// <param name="material">The target material.</param>
         protected static void SynchronizeShaderGraphProperties(Material material)
         {
             var defaultProperties = new Material(material.shader);

com.unity.render-pipelines.high-definition/Editor/Material/UIBlocks/LightingShaderGraphGUI.cs

@@ -9,7 +9,7 @@ namespace UnityEditor.Rendering.HighDefinition
     /// <summary>
     /// Common GUI for Lit ShaderGraphs
     /// </summary>
-    class LightingShaderGraphGUI : HDShaderGUI
+    internal class LightingShaderGraphGUI : HDShaderGUI
     {
         // For surface option shader graph we only want all unlit features but alpha clip and back then front rendering
         const SurfaceOptionUIBlock.Features   surfaceOptionFeatures = SurfaceOptionUIBlock.Features.Lit
@@ -22,6 +22,11 @@ class LightingShaderGraphGUI : HDShaderGUI
             new AdvancedOptionsUIBlock(MaterialUIBlock.Expandable.Advance, ~AdvancedOptionsUIBlock.Features.SpecularOcclusion)
         };
 
+        /// <summary>
+        /// Implement your custom GUI in this function. To display a UI similar to HDRP shaders, use a MaterialUIBlock.
+        /// </summary>
+        /// <param name="materialEditor">The current material editor.</param>
+        /// <param name="props">The list of properties the material has.</param>
         protected override void OnMaterialGUI(MaterialEditor materialEditor, MaterialProperty[] props)
         {
             using (var changed = new EditorGUI.ChangeCheckScope())
@@ -31,6 +36,10 @@ protected override void OnMaterialGUI(MaterialEditor materialEditor, MaterialPro
             }
         }
 
+        /// <summary>
+        /// Sets up the keywords and passes for a Lit Shader Graph material.
+        /// </summary>
+        /// <param name="material">The target material.</param>
         public static void SetupMaterialKeywordsAndPass(Material material)
         {
             SynchronizeShaderGraphProperties(material);

com.unity.render-pipelines.high-definition/Editor/Material/UIBlocks/MaterialUIBlock.cs

@@ -6,16 +6,23 @@
 
 namespace UnityEditor.Rendering.HighDefinition
 {
+    /// <summary>
+    /// Base implementation of a material GUI block to be disabled in the material inspector.
+    /// </summary>
     abstract class MaterialUIBlock
     {
+        /// <summary>The current material editor.</summary>
         protected MaterialEditor        materialEditor;
+        /// <summary>The list of selected materials to edit.</summary>
         protected Material[]            materials;
+        /// <summary>The list of available properties in the selected materials.</summary>
         protected MaterialProperty[]    properties;
 
+        /// <summary>Parent of the UI block.</summary>
         protected MaterialUIBlockList   parent;
 
         [Flags]
-        public enum Expandable : uint
+        internal enum Expandable : uint
         {
             // Standard
             Base = 1<<0,
@@ -52,7 +59,7 @@ public enum Expandable : uint
             LayeringOption3 = 1 << 30
         }
 
-        public void         Initialize(MaterialEditor materialEditor, MaterialProperty[] properties, MaterialUIBlockList parent)
+        internal void         Initialize(MaterialEditor materialEditor, MaterialProperty[] properties, MaterialUIBlockList parent)
         {
             this.materialEditor = materialEditor;
             this.parent = parent;
@@ -62,12 +69,18 @@ public void         Initialize(MaterialEditor materialEditor, MaterialProperty[]
             materialEditor.InitExpandableState();
         }
 
-        public void         UpdateMaterialProperties(MaterialProperty[] properties)
+        internal void         UpdateMaterialProperties(MaterialProperty[] properties)
         {
             this.properties = properties;
             LoadMaterialProperties();
         }
 
+        /// <summary>
+        /// Find a material property in the list of available properties.
+        /// </summary>
+        /// <param name="propertyName">Name of the property.</param>
+        /// <param name="isMandatory">Specifies whether the property is mandatory for your Inspector.</param>
+        /// <returns>Returns the material property if it exists. Returns null otherwise.</returns>
         protected MaterialProperty FindProperty(string propertyName, bool isMandatory = false)
         {
             // ShaderGUI.FindProperty is a protected member of ShaderGUI so we can't call it here:
@@ -83,6 +96,13 @@ protected MaterialProperty FindProperty(string propertyName, bool isMandatory =
             return null;
         }
 
+        /// <summary>
+        /// Find a material property with layering option
+        /// </summary>
+        /// <param name="propertyName">Name of the property.</param>
+        /// <param name="layerCount">Number of layers of the shader.</param>
+        /// <param name="isMandatory">Specifies whether the property is mandatory for your Inspector.</param>
+        /// <returns>Returns the material property if it exists. Returns null otherwise.</returns>
         protected MaterialProperty[] FindPropertyLayered(string propertyName, int layerCount, bool isMandatory = false)
         {
             MaterialProperty[] properties = new MaterialProperty[layerCount];
@@ -99,7 +119,14 @@ protected MaterialProperty[] FindPropertyLayered(string propertyName, int layerC
             return properties;
         }
 
+        /// <summary>
+        /// Use this function to load the material properties you need in your block.
+        /// </summary>
         public abstract void LoadMaterialProperties();
+
+        /// <summary>
+        /// Renders the properties in your block.
+        /// </summary>
         public abstract void OnGUI();
     }
 }

com.unity.render-pipelines.high-definition/Editor/Material/Unlit/ShaderGraph/HDUnlitGUI.cs

@@ -10,7 +10,7 @@ namespace UnityEditor.Rendering.HighDefinition
     /// <summary>
     /// GUI for HDRP Unlit shader graphs
     /// </summary>
-    class HDUnlitGUI : HDShaderGUI
+    internal class HDUnlitGUI : HDShaderGUI
     {
         const SurfaceOptionUIBlock.Features surfaceOptionFeatures = SurfaceOptionUIBlock.Features.Unlit;
 
@@ -21,6 +21,11 @@ class HDUnlitGUI : HDShaderGUI
             new AdvancedOptionsUIBlock(MaterialUIBlock.Expandable.Advance, ~AdvancedOptionsUIBlock.Features.SpecularOcclusion)
         };
 
+        /// <summary>
+        /// Implement your custom GUI in this function. To display a UI similar to HDRP shaders, use a MaterialUIBlock.
+        /// </summary>
+        /// <param name="materialEditor">The current material editor.</param>
+        /// <param name="props">The list of properties the material has.</param>
         protected override void OnMaterialGUI(MaterialEditor materialEditor, MaterialProperty[] props)
         {
             using (var changed = new EditorGUI.ChangeCheckScope())
@@ -30,6 +35,10 @@ protected override void OnMaterialGUI(MaterialEditor materialEditor, MaterialPro
             }
         }
 
+        /// <summary>
+        /// Sets up the keywords and passes for an Unlit Shader Graph material.
+        /// </summary>
+        /// <param name="material">The target material.</param>
         public static void SetupMaterialKeywordsAndPass(Material material)
         {
             SynchronizeShaderGraphProperties(material);