Comments Update

Author: Erfan-Ahmadi

include/nbl/video/utilities/SIntendedSubmitInfo.h

@@ -75,34 +75,45 @@ struct SIntendedSubmitInfo final : core::Uncopyable
         }
 
     public:
-        // This parameter is required but may be unused if there is no need (no overflow) to do submit
+        // This parameter is required but may be unused if there is no need (no overflow) to perform submit operations (no call to `overflowSubmit` or `submit`)
         IQueue* queue = nullptr;
-        // Use this parameter to wait for previous operations to finish before whatever commands the Utility you're using records
+
+        // Use this parameter to wait for previous operations to finish before whatever commands the Utility you're using records.
         std::span<const IQueue::SSubmitInfo::SSemaphoreInfo> waitSemaphores = {};
-        // Fill the commandbuffers you want to run before the first command the Utility records to run in the same submit,
-        // for example baked command buffers with pipeline barrier commands.
+
+        // Fill the commandbuffers you want to run before the first command the Utility records to run in the same submit, 
+        // for example, baked command buffers with pipeline barrier commands.
         std::span<const IQueue::SSubmitInfo::SCommandBufferInfo> prevCommandBuffers = {};
-        // A set of command buffers the Utility can round robin its transient commands. All must be individually resettable.
-        // Command buffers are cycled through for use and submission in a simple modular arithmetic fashion.
-        // EXACTLY ONE commandbuffer must be in recording state! This is the one the utility will use immediately to record commands.
-        // But remember that even though its scratch, you can record some of your own preceeding commands into it as well.
+
+        // A set of command buffers the Utility can use in a round-robin manner for its transient commands. All command buffers must be individually resettable. 
+        // Command buffers are cycled through for use and submission using a simple modular arithmetic fashion. 
+        // EXACTLY ONE commandbuffer must be in recording state! This is the one the utilities will use immediately to record commands. 
+        // However, even though it's scratch, you can record some of your own preceding commands into it as well.
         std::span<IQueue::SSubmitInfo::SCommandBufferInfo> scratchCommandBuffers = {};
-        // This semaphore is needed to ensure correct and valid usage of the command buffer used to record the next submit by ensuring they are not currently pending.
-        // The initial `scratchSemaphore.value` gets incremented and signalled on each submit, can start at 0 because an overflow will signal `value+1`.
-        // `[Multi]TimelineEventHandler` to latch cleanups on `scratchSemaphore` where this value, so make sure you're submitting by yourself manually and use the functions provided here.
-        // is a value that they expect to actually get signalled in the future.
-        // NOTE: To ensure deterministic behavior, do not attempt to signal this semaphore yourself.
-        // You can actually examine the change in `scratchSemaphore.value` to figure out how many submits occurred.
+
+        // This semaphore is needed to "stitch together" additional submits, ensuring they occur before and after the original intended signals and waits. 
+        // It also ensures safe usage of the scratch command buffers by blocking the CPU if the command buffer is in a PENDING state and not safe to begin. 
+        // The initial `scratchSemaphore.value` gets incremented and signaled on each submit. It can start at 0 because an overflow will signal `value+1`.
+        // NOTE: You should signal this semaphore when doing your last/tail submit manually OR when not submitting the recorded scratch at all 
+        //       (in which case, signal from Host or another submit). Why? The utilities that deal with `SIntendedSubmitInfo` might use the 
+        //       `[Multi]TimelineEventHandler` to latch cleanups/deallocations on `scratchSemaphore`, and `getFutureScratchSemaphore()` 
+        //       is the value they expect to get signaled in the future.
+        // NOTE: Each overflow submit bumps the value to wait and signal by +1. A utility may overflow an arbitrary number of times. 
+        //       Therefore, DO NOT choose the values for waits and signals manually, and do not modify the `scratchSemaphore` field after initialization or first use. 
+        //       You can examine the change in `scratchSemaphore.value` to observe how many overflows or submits have occurred.
         IQueue::SSubmitInfo::SSemaphoreInfo scratchSemaphore = {};
-        // Optional: If you had a semaphore whose highest pending signal is 45 but gave the scratch a value of 68 (causing 69 to get signalled in a popped submit),
-        // but only used 4 scratch command buffers, we'd wait for the semaphore to reach 66 before resetting the next scratch command buffer.
-        // That is obviously suboptimal if the next scratch command buffer wasn't pending with a signal of 67 at all (you'd wait until 70 gets signalled).
-        // Therefore you would need to override this behaviour somehow and be able to tell to only wait for the semaphore at values higher than 68.
+
+        // Optional: If you had a semaphore whose highest pending signal is 45 but gave the scratch a value of 68 (causing 69 to get signaled in a popped submit), 
+        // but only used 4 scratch command buffers, we'd wait for the semaphore to reach 66 before resetting the next scratch command buffer. 
+        // This is obviously suboptimal if the next scratch command buffer wasn't pending with a signal of 67 at all (you'd be waiting until 70 gets signaled). 
+        // Therefore, you would need to override this behavior to only wait for semaphore values higher than 68.
         size_t initialScratchValue = 0;
-        // Optional: Callback to perform some other CPU work while blocking for one of the submitted scratch command buffers to complete execution.
-        // Can get called repeatedly! The argument is the scratch semaphore (so it can poll itself to know when to finish work - prevent priority inversion)
+
+        // Optional: Callback to perform some other CPU work while blocking for one of the submitted scratch command buffers to complete execution. 
+        // This callback may be called repeatedly! The argument provided is the scratch semaphore, allowing it to poll itself to determine when it can finish its work, 
+        // preventing priority inversion.
         std::function<void(const ISemaphore::SWaitInfo&)> overflowCallback = {};
-        
+
         //
         inline ISemaphore::SWaitInfo getFutureScratchSemaphore() const {return {scratchSemaphore.semaphore,scratchSemaphore.value+1};}