BufferBackingState comments

src/Ryujinx.Graphics.Gpu/Memory/BufferBackingState.cs

@@ -4,6 +4,10 @@ using System.Collections.Generic;
 
 namespace Ryujinx.Graphics.Gpu.Memory
 {
+    /// <summary>
+    /// Type of backing memory.
+    /// In ascending order of priority when merging multiple buffer backing states.
+    /// </summary>
     internal enum BufferBackingType
     {
         HostMemory,
@@ -45,6 +49,13 @@ namespace Ryujinx.Graphics.Gpu.Memory
 
         private readonly int _size;
 
+        /// <summary>
+        /// Initialize the buffer backing state for a given parent buffer.
+        /// </summary>
+        /// <param name="context">Gpu context</param>
+        /// <param name="parent">Parent buffer</param>
+        /// <param name="stage">Initial buffer stage</param>
+        /// <param name="baseBuffers">Buffers to inherit state from</param>
         public BufferBackingState(GpuContext context, Buffer parent, BufferStage stage, IEnumerable<Buffer> baseBuffers = null)
         {
             _size = (int)parent.Size;
@@ -99,11 +110,22 @@ namespace Ryujinx.Graphics.Gpu.Memory
             }
         }
 
+        /// <summary>
+        /// Combine buffer backing types, selecting the one with highest priority.
+        /// </summary>
+        /// <param name="left">First buffer backing type</param>
+        /// <param name="right">Second buffer backing type</param>
+        /// <returns>Combined buffer backing type</returns>
         private static BufferBackingType CombineTypes(BufferBackingType left, BufferBackingType right)
         {
             return (BufferBackingType)Math.Max((int)left, (int)right);
         }
 
+        /// <summary>
+        /// Combine the state from the given buffer backing state with this one,
+        /// so that the state isn't lost when migrating buffers.
+        /// </summary>
+        /// <param name="oldState">Buffer state to combine into this state</param>
         private void CombineState(BufferBackingState oldState)
         {
             _setCount += oldState._setCount;
@@ -118,6 +140,11 @@ namespace Ryujinx.Graphics.Gpu.Memory
             _desiredType = CombineTypes(_desiredType, oldState._desiredType);
         }
 
+        /// <summary>
+        /// Get the buffer access for the desired backing type, and record that type as now being active.
+        /// </summary>
+        /// <param name="parent">Parent buffer</param>
+        /// <returns>Buffer access</returns>
         public BufferAccess SwitchAccess(Buffer parent)
         {
             BufferAccess access = parent.SparseCompatible ? BufferAccess.SparseCompatible : BufferAccess.Default;
@@ -145,6 +172,9 @@ namespace Ryujinx.Graphics.Gpu.Memory
             return access;
         }
 
+        /// <summary>
+        /// Record when data has been uploaded to the buffer.
+        /// </summary>
         public void RecordSet()
         {
             _setCount++;
@@ -152,6 +182,9 @@ namespace Ryujinx.Graphics.Gpu.Memory
             ConsiderUseCounts();
         }
 
+        /// <summary>
+        /// Record when data has been flushed from the buffer.
+        /// </summary>
         public void RecordFlush()
         {
             if (_lastFlushWrite != _writeCount)
@@ -162,11 +195,20 @@ namespace Ryujinx.Graphics.Gpu.Memory
             }
         }
 
+        /// <summary>
+        /// Determine if the buffer backing should be changed.
+        /// </summary>
+        /// <returns>True if the desired backing type is different from the current type</returns>
         public readonly bool ShouldChangeBacking()
         {
             return _desiredType != _activeType;
         }
 
+        /// <summary>
+        /// Determine if the buffer backing should be changed, considering a new use with the given buffer stage.
+        /// </summary>
+        /// <param name="stage">Buffer stage for the use</param>
+        /// <returns>True if the desired backing type is different from the current type</returns>
         public bool ShouldChangeBacking(BufferStage stage)
         {
             if (!_canSwap)
@@ -202,6 +244,10 @@ namespace Ryujinx.Graphics.Gpu.Memory
             return _desiredType != _activeType;
         }
 
+        /// <summary>
+        /// Evaluate the current counts to determine what the buffer's desired backing type is.
+        /// This method depends on heuristics devised by testing a variety of software.
+        /// </summary>
         private void ConsiderUseCounts()
         {
             if (_canSwap)