acdream/src/AcDream.App/Rendering/Gpu/Vk/VulkanFrameGpuMeasurement.cs

using AcDream.App.Diagnostics;

namespace AcDream.App.Rendering.Gpu.Vk;

/// <summary>
/// Campaign V slice V8: the Vulkan arm's render-transaction measurement.
///
/// <para>V6h left the Vulkan arm on <c>NullRenderFrameGpuMeasurement</c>,
/// which meant <see cref="FrameProfiler.FrameBoundary()"/> was never called at
/// all — so a Vulkan run produced no <c>[frame-prof]</c> line, no frame-history
/// CSV and no allocation-per-frame column. That is not a missing nicety: the R6
/// soak waits on <c>[frame-prof]</c> boundaries to time its samples, so the
/// campaign's performance vehicle could not be pointed at the backend it was
/// meant to judge. V8 cannot measure what it cannot instrument, so the
/// instrument lands first.</para>
///
/// <para>The bracket was deliberately the SAME one GL used. On GL,
/// <c>FrameProfilerGpuMeasurement</c> (deleted at Campaign V slice V11) began a
/// <c>TimeElapsed</c> query at <see cref="BeginFrame"/> and ended it at
/// <see cref="EndFrame"/>, spanning resource preparation, the world scene and
/// private presentation but not the swapchain present. This adapter opens and
/// closes a Vulkan timestamp scope at exactly those two points, so
/// <c>gpu_ms</c> means the same thing in both columns of the V8 table.
/// Comparing two differently-bracketed numbers would have been worse than
/// reporting none.</para>
///
/// <para>Timestamps resolve two or three frames late, which is why the sample
/// carries the profiler frame index that ISSUED it
/// (<see cref="VulkanGpuDevice.TryTakeFrameGpuSample"/>) rather than being
/// credited to the frame that happened to read it — the same pairing the
/// deleted <c>GpuFrameTimer</c> used to perform internally on the GL arm.</para>
/// </summary>
internal sealed class VulkanFrameGpuMeasurement : IRenderFrameGpuMeasurement
{
    private readonly FrameProfiler _profiler;
    private readonly VulkanGpuDevice _device;

    internal VulkanFrameGpuMeasurement(FrameProfiler profiler, VulkanGpuDevice device)
    {
        _profiler = profiler ?? throw new ArgumentNullException(nameof(profiler));
        _device = device ?? throw new ArgumentNullException(nameof(device));
    }

    public void BeginFrame()
    {
        _profiler.FrameBoundary();

        // Drain first: these are measurements of frames that have already
        // retired, and the queue is bounded by the flight count.
        while (_device.TryTakeFrameGpuSample(out int frameIndex, out long elapsedUs))
            _profiler.RecordGpuSample(frameIndex, elapsedUs);

        _device.BeginFrameTimerScope(_profiler.CurrentFrameIndex);
    }

    public void EndFrame() => _device.EndFrameTimerScope();
}