Merge pull request #1245 from Unity-Technologies/feature/BufferHistoryUpdate

Cleaning in BufferedRTHandleSystem

ScriptableRenderPipeline/Core/CoreRP/Textures/BufferedRTHandleSystem.cs

 
 namespace UnityEngine.Experimental.Rendering
 {
+    /// <summary>
+    /// Implement a multiple buffering for RenderTextures.
+    /// </summary>
+    /// <exemple>
+    /// <code>
+    /// enum BufferType
+    /// {
+    ///     Color,
+    ///     Depth    
+    /// }
+    /// 
+    /// void Render()
+    /// {
+    ///     var camera = GetCamera();
+    ///     var buffers = GetFrameHistoryBuffersFor(camera);
+    ///     
+    ///     // Set reference size in case the rendering size changed this frame
+    ///     buffers.SetReferenceSize(
+    ///         GetCameraWidth(camera), GetCameraHeight(camera), 
+    ///         GetCameraUseMSAA(camera), GetCameraMSAASamples(camera)
+    ///     );
+    ///     buffers.Swap();
+    /// 
+    ///     var currentColor = buffer.GetFrameRT((int)BufferType.Color, 0);
+    ///     if (currentColor == null) // Buffer was not allocated
+    ///     {
+    ///         buffer.AllocBuffer(
+    ///             (int)BufferType.Color,      // Color buffer id
+    ///             ColorBufferAllocator,       // Custom functor to implement allocation
+    ///             2                           // Use 2 RT for this buffer for double buffering
+    ///         );
+    ///         currentColor = buffer.GetFrameRT((int)BufferType.Color, 0);
+    ///     }
+    /// 
+    ///     var previousColor = buffers.GetFrameRT((int)BufferType.Color, 1);
+    /// 
+    ///     // Use previousColor and write into currentColor
+    /// }
+    /// </code>
+    /// </exemple>
     public class BufferedRTHandleSystem : IDisposable
     {
         Dictionary<int, RTHandleSystem.RTHandle[]> m_RTHandles = new Dictionary<int, RTHandleSystem.RTHandle[]>();
 
-        public RTHandleSystem.RTHandle GetFrameRT(int id, int index)
+        /// <summary>
+        /// Return the frame RT or null.
+        /// </summary>
+        /// <param name="bufferId">Defines the buffer to use.</param>
+        /// <param name="frameIndex"></param>
+        /// <returns>The frame RT or null when the <paramref name="bufferId"/> was not previously allocated (<see cref="BufferedRTHandleSystem.AllocBuffer(int, Func{RTHandleSystem, int, RTHandleSystem.RTHandle}, int)" />).</returns>
+        public RTHandleSystem.RTHandle GetFrameRT(int bufferId, int frameIndex)
-            if (!m_RTHandles.ContainsKey(id))
+            if (!m_RTHandles.ContainsKey(bufferId))
-            Assert.IsTrue(index >= 0 && index < m_RTHandles[id].Length);
+            Assert.IsTrue(frameIndex >= 0 && frameIndex < m_RTHandles[bufferId].Length);
-            return m_RTHandles[id][index];
+            return m_RTHandles[bufferId][frameIndex];
+        /// <summary>
+        /// Allocate RT handles for a buffer.
+        /// </summary>
+        /// <param name="bufferId">The buffer to allocate.</param>
+        /// <param name="allocator">The functor to use for allocation.</param>
+        /// <param name="bufferCount">The number of RT handles for this buffer.</param>
-            int id, 
+            int bufferId, 
-            int bufferSize
+            int bufferCount
-            var buffer = new RTHandleSystem.RTHandle[bufferSize];
-            m_RTHandles.Add(id, buffer);
+            var buffer = new RTHandleSystem.RTHandle[bufferCount];
+            m_RTHandles.Add(bufferId, buffer);
 
             // First is autoresized
             buffer[0] = allocator(m_RTHandleSystem, 0);
             }
         }
 
+        /// <summary>
+        /// Set the reference size for this RT Handle System (<see cref="RTHandleSystem.SetReferenceSize(int, int, bool, MSAASamples)"/>)
+        /// </summary>
+        /// <param name="width">The width of the RTs of this buffer.</param>
+        /// <param name="height">The height of the RTs of this buffer.</param>
+        /// <param name="msaa">Whether this buffer use MSAA.</param>
+        /// <param name="msaaSamples">Number of MSAA samples for this buffer.</param>
+        /// <summary>
+        /// Swap the buffers.
+        /// 
+        /// Take care that if the new current frame needs resizing, it will occurs during the this call.
+        /// </summary>
         public void Swap()
         {
             foreach (var item in m_RTHandles)
             Dispose(true);
         }
 
+        /// <summary>
+        /// Deallocate and clear all buffers.
+        /// </summary>
         public void ReleaseAll()
         {
             foreach (var item in m_RTHandles)