Update the scripting API for FrameSettings, FrameSettingsOverrideMask and IBitArray (#110)

Author: RSlysz

com.unity.render-pipelines.core/Runtime/Utilities/BitArray.cs

@@ -9,35 +9,35 @@ namespace UnityEngine.Rendering
     /// </summary>
     public interface IBitArray
     {
-        /// <summary>Number of elements in the bit array.</summary>
+        /// <summary>Gets the capacity of this BitArray. This is the number of bits that are usable.</summary>
         uint capacity { get; }
-        /// <summary>True if all bits are 0.</summary>
+        /// <summary>Return `true` if all the bits of this BitArray are set to 0. Returns `false` otherwise.</summary>
         bool allFalse { get; }
-        /// <summary>True if all bits are 1.</summary>
+        /// <summary>Return `true` if all the bits of this BitArray are set to 1. Returns `false` otherwise.</summary>
         bool allTrue { get; }
         /// <summary>
-        /// Returns the state of the bit at a specific index.
+        /// An indexer that allows access to the bit at a given index. This provides both read and write access.
         /// </summary>
         /// <param name="index">Index of the bit.</param>
         /// <returns>State of the bit at the provided index.</returns>
         bool this[uint index] { get; set; }
-        /// <summary>Returns the bit array in a human readable form.</summary>
+        /// <summary>Writes the bits in the array in a human-readable form. This is as a string of 0s and 1s packed by 8 bits. This is useful for debugging.</summary>
         string humanizedData { get; }
 
         /// <summary>
-        /// Bit-wise And operation.
+        /// Perform an AND bitwise operation between this BitArray and the one you pass into the function and return the result. Both BitArrays must have the same capacity. This will not change current BitArray values.
         /// </summary>
-        /// <param name="other">Bit array with which to the And operation.</param>
+        /// <param name="other">BitArray with which to the And operation.</param>
         /// <returns>The resulting bit array.</returns>
         IBitArray BitAnd(IBitArray other);
         /// <summary>
-        /// Bit-wise Or operation.
+        /// Perform an OR bitwise operation between this BitArray and the one you pass into the function and return the result. Both BitArrays must have the same capacity. This will not change current BitArray values.
         /// </summary>
-        /// <param name="other">Bit array with which to the Or operation.</param>
+        /// <param name="other">BitArray with which to the Or operation.</param>
         /// <returns>The resulting bit array.</returns>
         IBitArray BitOr(IBitArray other);
         /// <summary>
-        /// Invert the bit array.
+        /// Return the BitArray with every bit inverted.
         /// </summary>
         /// <returns></returns>
         IBitArray BitNot();

com.unity.render-pipelines.high-definition/Runtime/RenderPipeline/Settings/FrameSettings.cs

@@ -318,7 +318,9 @@ public enum FrameSettingsField
     [DebuggerDisplay("{mask.humanizedData}")]
     public struct FrameSettingsOverrideMask
     {
-        /// <summary>Mask of overridden values.</summary>
+        /// <summary>Gets the underlying BitArray HDRP uses to store the override mask and thus specific which field is overridden or not.
+        /// Note: BitArray128 is implements IBitArray and therefore has the scripting API described below. It is recomended to use the interface as the exact BitArray con evolve from one version of the package to another as the we need more capacity here.
+        /// </summary>
         [SerializeField]
         public BitArray128 mask;
     }
@@ -501,59 +503,54 @@ partial struct FrameSettings
         BitArray128 bitDatas;
 
         /// <summary>
-        /// if <c>lodBiasMode == LODBiasMode.Fixed</c>, then this value will overwrite <c>QualitySettings.lodBias</c>
-        /// if <c>lodBiasMode == LODBiasMode.ScaleQualitySettings</c>, then this value will scale <c>QualitySettings.lodBias</c>
+        /// If <c>lodBiasMode</c> is <c>LODBiasMode.Fixed</c>, then this value overwrites <c>QualitySettings.lodBias</c>.
+        /// If <c>lodBiasMode</c> is <c>LODBiasMode.ScaleQualitySettings</c>, then this value scales <c>QualitySettings.lodBias</c>.
         /// </summary>
         [SerializeField]
         public float lodBias;
-        /// <summary>Define how the <c>QualitySettings.lodBias</c> value is set.</summary>
+        /// <summary>Specifies how HDRP calculates <c>QualitySettings.lodBias</c>.</summary>
         [SerializeField]
         public LODBiasMode lodBiasMode;
-        /// <summary>The quality level to use when fetching the quality setting value.</summary>
+        /// <summary>The quality level the rendering component uses when it fetches the quality setting value.</summary>
         [SerializeField]
         public int lodBiasQualityLevel;
         /// <summary>
-        /// if <c>maximumLODLevelMode == MaximumLODLevelMode.FromQualitySettings</c>, then this value will overwrite <c>QualitySettings.maximumLODLevel</c>
-        /// if <c>maximumLODLevelMode == MaximumLODLevelMode.OffsetQualitySettings</c>, then this value will offset <c>QualitySettings.maximumLODLevel</c>
+        /// If <c>maximumLODLevelMode</c> is <c>MaximumLODLevelMode.FromQualitySettings</c>, then this value overwrites <c>QualitySettings.maximumLODLevel</c>
+        /// If <c>maximumLODLevelMode</c> is <c>MaximumLODLevelMode.OffsetQualitySettings</c>, then this value offsets <c>QualitySettings.maximumLODLevel</c>
         /// </summary>
         [SerializeField]
         public int maximumLODLevel;
-        /// <summary>Define how the <c>QualitySettings.maximumLODLevel</c> value is set.</summary>
+        /// <summary>Specifies how HDRP calculates <c>QualitySettings.maximumLODLevel</c>.</summary>
         [SerializeField]
         public MaximumLODLevelMode maximumLODLevelMode;
-        /// <summary>The quality level to use when fetching the quality setting value.</summary>
+        /// <summary>The maximum quality level the rendering component uses when it fetches the quality setting value.</summary>
         [SerializeField]
         public int maximumLODLevelQualityLevel;
 
         /// <summary>
-        /// The material quality level to use for this rendering.
-        /// if <c>materialQuality == 0</c>, then the material quality from the current quality settings
-        /// (in HDRP Asset) will be used.
+        /// The material quality level this rendering component uses.
+        /// If <c>materialQuality == 0</c>, the rendering component uses the material quality from the current quality settings in the HDRP Asset.
         /// </summary>
         public MaterialQuality materialQuality;
 
-        /// <summary>Helper to see binary saved data on LitShaderMode as a LitShaderMode enum.</summary>
+        /// <summary>Specifies the rendering path this rendering component uses. Here you can use the <c>LitShaderMode</c> enum to specify whether the rendering component uses forward or deferred rendering.</summary>
         public LitShaderMode litShaderMode
         {
             get => bitDatas[(uint)FrameSettingsField.LitShaderMode] ? LitShaderMode.Deferred : LitShaderMode.Forward;
             set => bitDatas[(uint)FrameSettingsField.LitShaderMode] = value == LitShaderMode.Deferred;
         }
 
-        /// <summary>
-        /// <summary>Get stored data for this field.</summary>
-        /// </summary>
+        /// <summary>Gets the stored override value for the passed in Frame Setting. Use this to access boolean values.</summary>
         /// <param name="field">Requested field.</param>
         /// <returns>True if the field is enabled.</returns>
         public bool IsEnabled(FrameSettingsField field) => bitDatas[(uint)field];
-        /// <summary>
-        /// <summary>Set stored data for this field.</summary>
-        /// </summary>
+        /// <summary>Sets the stored override value for the passed in Frame Setting. Use this to access boolean values.</summary>
         /// <param name="field">Requested field.</param>
         /// <param name="value">State to set to the field.</param>
         public void SetEnabled(FrameSettingsField field, bool value) => bitDatas[(uint)field] = value;
 
         /// <summary>
-        /// Compute the LOD bias value to use
+        /// Calculates the LOD bias value to use.
         /// </summary>
         /// <param name="hdrp">The HDRP Assets to use</param>
         /// <returns>The LOD Bias to use</returns>
@@ -570,7 +567,7 @@ public float GetResolvedLODBias(HDRenderPipelineAsset hdrp)
         }
 
         /// <summary>
-        /// Compute the Maximum LOD level to use
+        /// Calculates the Maximum LOD level to use.
         /// </summary>
         /// <param name="hdrp">The HDRP Asset to use</param>
         /// <returns>The Maximum LOD level to use.</returns>
@@ -732,7 +729,7 @@ internal static void AggregateFrameSettings(ref FrameSettings aggregatedFrameSet
         }
 
         /// <summary>
-        /// Equality operator.
+        /// Equality operator between two FrameSettings. Return `true` if equivalent. (comparison of content).
         /// </summary>
         /// <param name="a">First frame settings.</param>
         /// <param name="b">Second frame settings.</param>
@@ -748,7 +745,7 @@ internal static void AggregateFrameSettings(ref FrameSettings aggregatedFrameSet
             && a.materialQuality == b.materialQuality;
 
         /// <summary>
-        /// Inequality operator.
+        /// Inequality operator between two FrameSettings. Return `true` if different. (comparison of content).
         /// </summary>
         /// <param name="a">First frame settings.</param>
         /// <param name="b">Second frame settings.</param>
@@ -764,7 +761,7 @@ internal static void AggregateFrameSettings(ref FrameSettings aggregatedFrameSet
             || a.materialQuality != b.materialQuality;
 
         /// <summary>
-        /// Equality operator.
+        /// Equality operator between two FrameSettings. Return `true` if equivalent. (comparison of content).
         /// </summary>
         /// <param name="obj">Frame Settings to compare to.</param>
         /// <returns>True if both settings are equal.</returns>
@@ -780,7 +777,7 @@ public override bool Equals(object obj)
             && materialQuality.Equals(((FrameSettings)obj).materialQuality);
 
         /// <summary>
-        /// Returns the hash code of the frame settings.
+        /// Returns the hash code of this object.
         /// </summary>
         /// <returns>Hash code of the frame settings.</returns>
         public override int GetHashCode()