acdream/src/AcDream.App/Rendering/Gpu/GpuCapabilityRecord.cs

namespace AcDream.App.Rendering.Gpu;

/// <summary>
/// Backend-neutral view of what the device can do. Both backends fill this from
/// their own probe layer — <c>GraphicalCapabilityRecord</c> for GL, and its
/// Vulkan sibling added at slice V5 — and the renderers consult only this.
///
/// The alignment fields are load-bearing rather than informational: ring
/// allocations must satisfy them, and getting one wrong produces a driver error
/// on Vulkan and silently wrong data on some GL implementations.
/// </summary>
internal sealed record GpuCapabilityRecord
{
    public required GpuBackendKind Backend { get; init; }

    /// <summary>Adapter name, e.g. <c>"AMD Radeon RX 9070 XT"</c>.</summary>
    public required string DeviceName { get; init; }

    /// <summary>Driver identification string for diagnostics and bug reports.</summary>
    public required string DriverInfo { get; init; }

    /// <summary>API version actually in use, e.g. <c>"OpenGL 4.6"</c> or <c>"Vulkan 1.3.280"</c>.</summary>
    public required string ApiVersion { get; init; }

    /// <summary>Simultaneously registerable texture-table slots. Must reach <see cref="GpuBindingModel.TextureTableCapacity"/>.</summary>
    public required uint MaxTextureTableSlots { get; init; }

    /// <summary>Storage-buffer bindings available. Must reach <see cref="GpuBindingModel.StorageBindingCount"/>.</summary>
    public required uint MaxStorageBufferBindings { get; init; }

    /// <summary>Push-constant bytes available. Must reach <see cref="GpuBindingModel.PushConstantBytes"/>.</summary>
    public required uint MaxPushConstantBytes { get; init; }

    /// <summary>Required alignment for a storage-buffer binding offset.</summary>
    public required uint MinStorageBufferOffsetAlignment { get; init; }

    /// <summary>Required alignment for a uniform-buffer binding offset.</summary>
    public required uint MinUniformBufferOffsetAlignment { get; init; }

    /// <summary>Clip distances usable by a shader. Phase U.3's per-cell clip gate needs 8.</summary>
    public required uint MaxClipDistances { get; init; }

    /// <summary>Highest supported multisample count for the backbuffer.</summary>
    public required uint MaxSampleCount { get; init; }

    /// <summary>Multi-draw-indirect. Mandatory — it is the entire draw architecture.</summary>
    public required bool SupportsMultiDrawIndirect { get; init; }

    /// <summary>Shader draw parameters (<c>gl_DrawID</c>). Mandatory — batch lookup depends on it.</summary>
    public required bool SupportsDrawParameters { get; init; }

    /// <summary>BC1/2/3 sampling. Mandatory — DAT surfaces upload as DXT without transcoding.</summary>
    public required bool SupportsTextureCompressionBc { get; init; }

    /// <summary>GPU timestamps. Optional: absence degrades profiling, not rendering.</summary>
    public required bool SupportsTimestampQueries { get; init; }

    /// <summary>
    /// Whether per-frame data can be written straight into mapped memory the GPU
    /// reads. Both backends report this; only Vulkan currently answers true, and
    /// it is the mechanism behind Campaign V's CPU-cost target.
    /// </summary>
    public required bool SupportsPersistentlyMappedRings { get; init; }

    /// <summary>
    /// Every mandatory capability this device fails to provide, phrased as
    /// operator-facing sentences. Empty means the device can run acdream.
    /// Startup turns a non-empty list into the same <c>NotSupportedException</c>
    /// and exit-code-4 contract the GL gate already publishes.
    /// </summary>
    public IReadOnlyList<string> SupportFailures
    {
        get
        {
            List<string> failures = [];

            if (!SupportsMultiDrawIndirect)
                failures.Add("Multi-draw-indirect is required to submit world geometry.");
            if (!SupportsDrawParameters)
                failures.Add("Shader draw parameters (gl_DrawID) are required to select per-draw batch data.");
            if (!SupportsTextureCompressionBc)
                failures.Add("BC (DXT) texture compression is required to upload DAT surfaces.");
            if (MaxTextureTableSlots < GpuBindingModel.TextureTableCapacity)
            {
                failures.Add(
                    $"The texture table needs {GpuBindingModel.TextureTableCapacity} slots; " +
                    $"this device provides {MaxTextureTableSlots}.");
            }

            if (MaxStorageBufferBindings < GpuBindingModel.StorageBindingCount)
            {
                failures.Add(
                    $"{GpuBindingModel.StorageBindingCount} storage-buffer bindings are required; " +
                    $"this device provides {MaxStorageBufferBindings}.");
            }

            if (MaxPushConstantBytes < GpuBindingModel.PushConstantBytes)
            {
                failures.Add(
                    $"{GpuBindingModel.PushConstantBytes} push-constant bytes are required; " +
                    $"this device provides {MaxPushConstantBytes}.");
            }

            if (MaxClipDistances < GpuBindingModel.ClipPlanesPerSlot)
            {
                failures.Add(
                    $"{GpuBindingModel.ClipPlanesPerSlot} clip distances are required by the per-cell clip gate; " +
                    $"this device provides {MaxClipDistances}.");
            }

            return failures;
        }
    }

    public bool IsSupported => SupportFailures.Count == 0;
}