erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions

feat(render): Campaign V slice V6b - Vulkan textures, mips, samplers and the descriptor table

Browse source 
The second of V6's three commits: everything the fragment stage samples. Plan
sections 4.3 (textures and mip generation) and 4.4 (descriptors).

The descriptor table is the piece that retires GL_ARB_bindless_texture. One
update-after-bind, partially-bound, variable-count combined-image-sampler array
of 16384; registration appends exactly one vkUpdateDescriptorSets and nothing is
written at draw time, so steady state is zero descriptor writes per frame. A
slot is a (view, sampler) pair, exactly like a bindless handle, which is why the
CPU data model needs no change at all - GpuTextureSlot already carries the index
and V2 already moved every batch onto it.

Eviction is retirement-gated and the slot is scrubbed on the way out. Returning
a slot the moment a texture is deleted would let the LRU alias a live draw onto
a new texture, so the release is filed through the ledger; and when it runs the
slot is first overwritten with the default 1x1 white. A stale view descriptor
sitting in a partially-bound array is legal right up until something reads it,
at which point it is a use-after-free with no error attached. Writing the dummy
makes that impossible rather than unlikely.

The CPU block-compression codec is the slice's other substantial piece, and it
exists because Vulkan cannot blit into a compressed image. DAT surfaces arrive
as DXT1/3/5 with no mips, so the chain has to be decoded, box filtered and
re-encoded here. That is not merely a substitute for the missing blit: the GL
path calls glGenerateMipmap on compressed array textures, whose result is
explicitly implementation-defined, so this is the first time that part of the
pipeline has had a defined answer.

Two properties matter more than quality, and both are tested. It is
deterministic - integer arithmetic end to end, endpoints from the block's
bounding box, nearest-palette selection, no dithering and no iterative fit -
because the offline pixel gate compares captures from separate processes and a
chain that varied run to run would make every textured surface look like a
regression. And it preserves BC1's one-bit cut-out: a block containing any texel
below the alpha threshold is encoded in three-colour mode, because retail's
foliage and grates ARE that mode and quantising those texels to an opaque colour
would fill in every leaf. Plan 4.3's escape hatch stands if quality ever trips a
gate: store the affected textures as RGBA8 and blit their mips.

Uncompressed images do take the blit chain, added to the upload queue. Each
source level moves to TRANSFER_SRC for its blit and back to TRANSFER_DST
afterwards; leaving the chain in mixed layouts would be one barrier cheaper and
would then force the batch's final shader-read transition to name a different
old layout per level, so ending every level the same way is what keeps that
transition one barrier per image.

The upload queue now records the layout each image is in on ENTRY to a batch
rather than always naming UNDEFINED. UNDEFINED lets the driver discard existing
contents, which is right for a fresh image and wrong for the incremental
array-layer fills that mirror ManagedGLTextureArray - discarding there would
erase every layer uploaded earlier.

Render targets are single-sampled per the contract and carry SAMPLED usage
alongside COLOR_ATTACHMENT, so a paperdoll or appraisal view can be registered
into the table and drawn by the retained UI the moment its pass ends.
VulkanBackbufferAttachments owns the two attachments the swapchain does not: the
multisampled colour scratch that resolves into the swapchain image, and the
transient depth/stencil. Both are TRANSIENT_ATTACHMENT because nothing reads
either after the frame. Stencil is not optional - issue #117's portal punch
needs the aspect, which is why the V5 gate prefers D32_SFLOAT_S8_UINT over a
depth-only format.

Every format stays UNORM, and that is the V3 audit's finding rather than a
default. The plan previously specified an sRGB swapchain "matching the GL
FramebufferSrgb contract"; that contract does not exist, the renderer is plain
UNORM end to end, and shipping _SRGB would have brightened every frame and
passed silently until V7.

VulkanPipelineLayouts is extracted from V5's capability probe rather than
written beside it, and the probe now calls it. The probe's whole value is
proving the layouts the live backend builds can be built on this device; two
similar-looking definitions would have quietly ended that the first time one of
them changed.

Gates: Release build clean, App suite 4037 passed / 3 skipped (4014 at V6a plus
23 new), offline pixel gate PASS against the parent baseline at a differing
fraction of 4.26e-05 - 24 pixels of 563,200, one above the campaign's recorded
15-23 same-commit noise band and about 23x under the 0.001 threshold, on a
commit that changes no GL code path.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Erik 2026-07-28 07:49:40 +02:00
parent 37f3ed0498
commit 9eae496301
11 changed files with 2614 additions and 220 deletions
Download patch file Download diff file Expand all files Collapse all files

284
src/AcDream.App/Rendering/Gpu/Vk/VulkanUploadQueue.cs
View file

@ -59,9 +59,7 @@ internal sealed unsafe class VulkanUploadQueue : IDisposable
uint MipLevel,
uint Layer,
uint Width,
uint Height,
uint MipLevelCount,
uint LayerCount);
uint Height);
private readonly record struct TemporaryStaging(Buffer Buffer, VulkanAllocation Allocation);
@ -86,8 +84,28 @@ internal sealed unsafe class VulkanUploadQueue : IDisposable
"vk-staging-ring");
}
/// <summary>Images whose layout must be moved to TRANSFER_DST before the drain and to SHADER_READ after it.</summary>
private readonly HashSet<Image> _imagesNeedingBarrier = [];
/// <summary>
/// Images touched by this batch, and the layout each is in on entry.
///
/// <para>The entry layout is not always <c>UNDEFINED</c>, and that
/// distinction is load-bearing. <c>UNDEFINED</c> lets the driver discard the
/// existing contents, which is exactly right for the first upload into a
/// fresh image and exactly wrong for the incremental array-layer fills that
/// mirror <c>ManagedGLTextureArray</c> — discarding there would erase every
/// layer uploaded earlier. The first writer of a batch records the layout it
/// found the image in, and that is what the barrier names.</para>
/// </summary>
private readonly Dictionary<Image, ImageLayout> _imageEntryLayouts = [];
/// <summary>Mip chains to generate with <c>vkCmdBlitImage</c> after this batch's copies land.</summary>
private readonly List<MipBlitRequest> _mipBlits = [];
private readonly record struct MipBlitRequest(
Image Image,
int Width,
int Height,
int MipLevelCount,
int LayerCount);
internal int PendingBufferCopyCount => _bufferCopies.Count;
@ -122,8 +140,7 @@ internal sealed unsafe class VulkanUploadQueue : IDisposable
int layer,
int width,
int height,
int mipLevelCount,
int layerCount,
ImageLayout entryLayout,
ReadOnlySpan<byte> data,
string ownerName)
{
@ -142,10 +159,36 @@ internal sealed unsafe class VulkanUploadQueue : IDisposable
(uint)mipLevel,
(uint)layer,
(uint)width,
(uint)height,
(uint)mipLevelCount,
(uint)layerCount));
_imagesNeedingBarrier.Add(destination);
(uint)height));
RecordEntryLayout(destination, entryLayout);
}
/// <summary>
/// Queues a <c>vkCmdBlitImage</c> mip chain for an uncompressed image. BC
/// images cannot use this — a compressed image is not a legal blit
/// destination — and take a CPU-built chain instead (plan §4.3).
/// </summary>
internal void EnqueueMipBlit(
Image image,
int width,
int height,
int mipLevelCount,
int layerCount,
ImageLayout entryLayout)
{
ObjectDisposedException.ThrowIf(_disposed, this);
if (mipLevelCount <= 1)
return;
_mipBlits.Add(new MipBlitRequest(image, width, height, mipLevelCount, layerCount));
RecordEntryLayout(image, entryLayout);
}
private void RecordEntryLayout(Image image, ImageLayout entryLayout)
{
// First writer of the batch wins: a later writer that found the image
// already in TRANSFER_DST is describing this batch's own effect, not the
// layout the batch started from.
_imageEntryLayouts.TryAdd(image, entryLayout);
}
/// <summary>Queues a device-side buffer copy — the mesh arena's grow-and-copy migration.</summary>
@ -174,11 +217,11 @@ internal sealed unsafe class VulkanUploadQueue : IDisposable
/// </summary>
internal bool Record(CommandBuffer commands)
{
if (_bufferCopies.Count == 0 && _imageCopies.Count == 0)
if (_bufferCopies.Count == 0 && _imageCopies.Count == 0 && _mipBlits.Count == 0)
return false;
if (_imagesNeedingBarrier.Count > 0)
TransitionImages(commands, ImageLayout.Undefined, ImageLayout.TransferDstOptimal, toTransfer: true);
if (_imageEntryLayouts.Count > 0)
TransitionImagesToTransfer(commands);
foreach (BufferCopy2 copy in _bufferCopies)
{
@ -217,8 +260,11 @@ internal sealed unsafe class VulkanUploadQueue : IDisposable
&region);
}
if (_imagesNeedingBarrier.Count > 0)
TransitionImages(commands, ImageLayout.TransferDstOptimal, ImageLayout.ShaderReadOnlyOptimal, toTransfer: false);
foreach (MipBlitRequest blit in _mipBlits)
RecordMipBlit(commands, blit);
if (_imageEntryLayouts.Count > 0)
TransitionImagesToShaderRead(commands);
// One buffer barrier for the whole batch: transfer writes become
// readable by every consumer stage a copied buffer can feed.
@ -250,64 +296,204 @@ internal sealed unsafe class VulkanUploadQueue : IDisposable
_bufferCopies.Clear();
_imageCopies.Clear();
_imagesNeedingBarrier.Clear();
_mipBlits.Clear();
_imageEntryLayouts.Clear();
return true;
}
private void TransitionImages(
CommandBuffer commands,
ImageLayout oldLayout,
ImageLayout newLayout,
bool toTransfer)
private static ImageSubresourceRange WholeColorImage => new()
{
int count = _imagesNeedingBarrier.Count;
var barriers = new ImageMemoryBarrier2[count];
AspectMask = ImageAspectFlags.ColorBit,
BaseMipLevel = 0,
LevelCount = Silk.NET.Vulkan.Vk.RemainingMipLevels,
BaseArrayLayer = 0,
LayerCount = Silk.NET.Vulkan.Vk.RemainingArrayLayers,
};
private void TransitionImagesToTransfer(CommandBuffer commands)
{
var barriers = new ImageMemoryBarrier2[_imageEntryLayouts.Count];
int index = 0;
foreach (Image image in _imagesNeedingBarrier)
foreach ((Image image, ImageLayout entryLayout) in _imageEntryLayouts)
{
barriers[index++] = new ImageMemoryBarrier2
{
SType = StructureType.ImageMemoryBarrier2,
SrcStageMask = toTransfer
? PipelineStageFlags2.AllCommandsBit
: PipelineStageFlags2.AllTransferBit,
SrcAccessMask = toTransfer ? AccessFlags2.None : AccessFlags2.TransferWriteBit,
DstStageMask = toTransfer
? PipelineStageFlags2.AllTransferBit
: PipelineStageFlags2.FragmentShaderBit | PipelineStageFlags2.VertexShaderBit,
DstAccessMask = toTransfer ? AccessFlags2.TransferWriteBit : AccessFlags2.ShaderReadBit,
// Undefined discards existing contents, which is right for the
// first upload into a fresh image and wrong for an incremental
// one; incremental array-layer fills therefore name the layout
// they are already in.
OldLayout = oldLayout,
NewLayout = newLayout,
SrcStageMask = PipelineStageFlags2.AllCommandsBit,
SrcAccessMask = AccessFlags2.None,
DstStageMask = PipelineStageFlags2.AllTransferBit,
DstAccessMask = AccessFlags2.TransferWriteBit | AccessFlags2.TransferReadBit,
OldLayout = entryLayout,
NewLayout = ImageLayout.TransferDstOptimal,
SrcQueueFamilyIndex = Silk.NET.Vulkan.Vk.QueueFamilyIgnored,
DstQueueFamilyIndex = Silk.NET.Vulkan.Vk.QueueFamilyIgnored,
Image = image,
SubresourceRange = new ImageSubresourceRange
{
AspectMask = ImageAspectFlags.ColorBit,
BaseMipLevel = 0,
LevelCount = Silk.NET.Vulkan.Vk.RemainingMipLevels,
BaseArrayLayer = 0,
LayerCount = Silk.NET.Vulkan.Vk.RemainingArrayLayers,
},
SubresourceRange = WholeColorImage,
};
}
SubmitBarriers(commands, barriers);
}
private void TransitionImagesToShaderRead(CommandBuffer commands)
{
var barriers = new ImageMemoryBarrier2[_imageEntryLayouts.Count];
int index = 0;
foreach (Image image in _imageEntryLayouts.Keys)
{
barriers[index++] = new ImageMemoryBarrier2
{
SType = StructureType.ImageMemoryBarrier2,
SrcStageMask = PipelineStageFlags2.AllTransferBit,
SrcAccessMask = AccessFlags2.TransferWriteBit,
DstStageMask = PipelineStageFlags2.FragmentShaderBit | PipelineStageFlags2.VertexShaderBit,
DstAccessMask = AccessFlags2.ShaderReadBit,
OldLayout = ImageLayout.TransferDstOptimal,
NewLayout = ImageLayout.ShaderReadOnlyOptimal,
SrcQueueFamilyIndex = Silk.NET.Vulkan.Vk.QueueFamilyIgnored,
DstQueueFamilyIndex = Silk.NET.Vulkan.Vk.QueueFamilyIgnored,
Image = image,
SubresourceRange = WholeColorImage,
};
}
SubmitBarriers(commands, barriers);
}
private void SubmitBarriers(CommandBuffer commands, ImageMemoryBarrier2[] barriers)
{
if (barriers.Length == 0)
return;
fixed (ImageMemoryBarrier2* first = barriers)
{
var dependency = new DependencyInfo
{
SType = StructureType.DependencyInfo,
ImageMemoryBarrierCount = (uint)count,
ImageMemoryBarrierCount = (uint)barriers.Length,
PImageMemoryBarriers = first,
};
_vk.CmdPipelineBarrier2(commands, &dependency);
}
}
/// <summary>
/// Halves level N into level N+1 with a linear blit, all layers at once.
///
/// <para>Each source level is moved to TRANSFER_SRC for its blit and then
/// moved BACK to TRANSFER_DST. Leaving the chain in mixed layouts would be
/// one barrier cheaper and would then need the batch's final
/// shader-read transition to name a different old layout per level; ending
/// every level in the same layout is what lets that final transition stay
/// one barrier per image.</para>
/// </summary>
private void RecordMipBlit(CommandBuffer commands, in MipBlitRequest request)
{
int width = request.Width;
int height = request.Height;
for (uint level = 1; level < request.MipLevelCount; level++)
{
int nextWidth = Math.Max(1, width / 2);
int nextHeight = Math.Max(1, height / 2);
TransitionMipLevel(
commands,
request.Image,
level - 1,
ImageLayout.TransferDstOptimal,
ImageLayout.TransferSrcOptimal,
AccessFlags2.TransferWriteBit,
AccessFlags2.TransferReadBit);
var blit = new ImageBlit2
{
SType = StructureType.ImageBlit2,
SrcSubresource = new ImageSubresourceLayers
{
AspectMask = ImageAspectFlags.ColorBit,
MipLevel = level - 1,
BaseArrayLayer = 0,
LayerCount = (uint)request.LayerCount,
},
DstSubresource = new ImageSubresourceLayers
{
AspectMask = ImageAspectFlags.ColorBit,
MipLevel = level,
BaseArrayLayer = 0,
LayerCount = (uint)request.LayerCount,
},
};
blit.SrcOffsets.Element0 = new Offset3D(0, 0, 0);
blit.SrcOffsets.Element1 = new Offset3D(width, height, 1);
blit.DstOffsets.Element0 = new Offset3D(0, 0, 0);
blit.DstOffsets.Element1 = new Offset3D(nextWidth, nextHeight, 1);
var info = new BlitImageInfo2
{
SType = StructureType.BlitImageInfo2,
SrcImage = request.Image,
SrcImageLayout = ImageLayout.TransferSrcOptimal,
DstImage = request.Image,
DstImageLayout = ImageLayout.TransferDstOptimal,
RegionCount = 1,
PRegions = &blit,
Filter = Filter.Linear,
};
_vk.CmdBlitImage2(commands, &info);
TransitionMipLevel(
commands,
request.Image,
level - 1,
ImageLayout.TransferSrcOptimal,
ImageLayout.TransferDstOptimal,
AccessFlags2.TransferReadBit,
AccessFlags2.TransferWriteBit);
width = nextWidth;
height = nextHeight;
}
}
private void TransitionMipLevel(
CommandBuffer commands,
Image image,
uint level,
ImageLayout oldLayout,
ImageLayout newLayout,
AccessFlags2 sourceAccess,
AccessFlags2 destinationAccess)
{
var barrier = new ImageMemoryBarrier2
{
SType = StructureType.ImageMemoryBarrier2,
SrcStageMask = PipelineStageFlags2.AllTransferBit,
SrcAccessMask = sourceAccess,
DstStageMask = PipelineStageFlags2.AllTransferBit,
DstAccessMask = destinationAccess,
OldLayout = oldLayout,
NewLayout = newLayout,
SrcQueueFamilyIndex = Silk.NET.Vulkan.Vk.QueueFamilyIgnored,
DstQueueFamilyIndex = Silk.NET.Vulkan.Vk.QueueFamilyIgnored,
Image = image,
SubresourceRange = new ImageSubresourceRange
{
AspectMask = ImageAspectFlags.ColorBit,
BaseMipLevel = level,
LevelCount = 1,
BaseArrayLayer = 0,
LayerCount = Silk.NET.Vulkan.Vk.RemainingArrayLayers,
},
};
var dependency = new DependencyInfo
{
SType = StructureType.DependencyInfo,
ImageMemoryBarrierCount = 1,
PImageMemoryBarriers = &barrier,
};
_vk.CmdPipelineBarrier2(commands, &dependency);
}
/// <summary>Reclaims staging bytes and temporary buffers belonging to completed frames.</summary>
internal void ReleaseCompleted(long completedSerial) => _ringState.Release(completedSerial);
@ -387,6 +573,6 @@ internal sealed unsafe class VulkanUploadQueue : IDisposable
_ringState.Reset();
_bufferCopies.Clear();
_imageCopies.Clear();
_imagesNeedingBarrier.Clear();
}
}