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

feat(render): Campaign V slice V6l commit 3 - the offscreen viewports draw on Vulkan

Browse source 
Amendment 3 of three: the paperdoll and creature-appraisal views render on the
Vulkan arm. Plan section 5.5.16 defect 3 named two backend fixes as the
precondition; both are here, and running it found two more the note could not
have known about.

Fix 1: a layered sampled view per render target. An ATTACHMENT view must be
VK_IMAGE_VIEW_TYPE_2D and the global texture table's descriptor array is
sampler2DArray, so the attachment view cannot legally be registered into it -
section 5.5.7 recorded that as invalid usage rather than a mismatch that samples
oddly, and V6k made RegisterTexture refuse it loudly and name this fix.
VulkanGpuTexture now creates a SECOND, layered view over the same image for a
colour render target: one image, one allocation, two ways of looking at it,
legal without any creation flag. SampledView is what the table registers for
every texture, so the question disappears rather than being answered.

Fix 2: sample-count pipeline variants for WbDrawDispatcher. Vulkan requires a
pipeline's rasterizationSamples to equal the pass it draws in, and this
dispatcher draws in two passes with different counts - the multisampled
backbuffer world pass and the single-sampled offscreen target, which the
contract fixes at one sample. Its five pipelines became a MeshPipelineSet with
two instances, selected at bind time from the live pass rather than from the
scope, which is the same shape section 5.5.8 gave the depth-format problem. When
the backbuffer is single-sampled the two sets are one object, so nothing is
built twice and nothing is freed twice. The offscreen target's DEPTH attachment
also had to take the device's own combined depth/stencil format rather than the
contract enum's literal D24_UNORM_S8_UINT: a pipeline bakes one depth/stencil
format under dynamic rendering and the same pipelines draw in both passes, so a
second format would make one of the two undefined.

Fix 3, which running it found: entity APPEARANCE composites were still
bindless-only, so no entity with a palette override could be drawn on the Vulkan
arm at all - the doll being one, and every creature and player besides. The
backend that serves it has existed since V6i-2 and had no production consumer;
it has one now. TextureCache builds the composite cache on both arms, and
EnsureCompositeTexturesAvailable stops asking about bindless. Nothing about the
cache itself changed: the sharing, the bounded unowned LRU, the metered upload
budget and the retirement fence were already backend-neutral.

Fix 4, which the first successful capture found: the doll rendered upside down.
UiViewport has flipped V since V4a because a GL framebuffer's origin is
bottom-left, so its colour texture samples bottom-up. A Vulkan image's origin is
top-left and the backend's negative viewport height stores the rendered image
that way round, so the same flip stands the doll on its head. That is a property
of the backend that made the texture, not of the widget that draws it, so
IUiViewportRenderer answers TextureIsBottomUp and UiViewport asks. The line this
replaces had predicted exactly this failure since it was written.

The seam. WbDrawDispatcher's RHI arm borrows its pass from IWorldPassScope
rather than opening one, so a viewport that opens a pass of its own has to
publish it there for the span of the draw. Publish is on the interface now for
that. It does not nest: the world phase has closed its own pass by the time
private presentation runs, which is where these viewports have always drawn.

Gates. Release build green. App tests 4,129/3 skips; complete Release suite
9,192/5 (one solution-wide run reported a single App failure that did not
reproduce in the App suite alone or in a second solution-wide run - the
documented rerun-singly flake class; the failing test name was not surfaced by
the runner and is not carried forward as a claim). Strict GL offline pixel gate
against 08ffe141: 3.55e-05, 20 differing pixels of 563,200, inside the
documented 9-31 band. GL connected -Runs 3: 3/3 RENDERED on the desktop witness
and 3/3 on the client capture. One offline Vulkan run with
VK_LAYER_KHRONOS_validation proven inserted by the loader: zero validation
errors, zero warnings.

And the two captures the offline gate cannot reach, both connected and both
inspected. The Vulkan paperdoll (artifacts/v6l-vk-paperdoll3) renders the doll
upright, in armour, at the right scale, over a transparent background, and is
indistinguishable from the same capture on GL taken minutes later
(artifacts/v6l-gl-paperdoll) - which is also the no-regression check for the V
change. Particles (artifacts/v6l-vk-poi versus artifacts/v6l-gl-poi, cropped
4x at artifacts/crop-vk-glow.png and crop-gl-glow.png): Holtburg's forge plume
and its field of glint sprites draw in the same places with the same alpha
compositing on both backends, the puffs differing only in phase because two
launches cannot agree on an emitter's age.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Erik 2026-07-28 18:05:24 +02:00
parent eced67d038
commit 2e8b8b91ad
13 changed files with 353 additions and 102 deletions
Download patch file Download diff file Expand all files Collapse all files

34
src/AcDream.App/Rendering/Gpu/Vk/VulkanGpuDevice.Resources.cs
View file

@ -245,7 +245,8 @@ internal sealed unsafe partial class VulkanGpuDevice
_uploads,
_flights,
_debugNames,
description);
description,
DepthStencilFormat);
}
public GpuTextureSlot RegisterTexture(IGpuTexture texture, IGpuSampler sampler)
@ -258,27 +259,16 @@ internal sealed unsafe partial class VulkanGpuDevice
if (sampler is not VulkanGpuSampler vulkanSampler)
throw new ArgumentException("The Vulkan backend can only register a Vulkan sampler.", nameof(sampler));
// Campaign V slice V6k, the §5.5.7 re-check. A render-target image is
// viewed as VK_IMAGE_VIEW_TYPE_2D because that is what an ATTACHMENT
// needs; the texture table's descriptor array is declared
// sampler2DArray, so writing that view into it is invalid usage rather
// than a mismatch that samples oddly. §5.5.7 recorded that this "did not
// fire" and asked that it be re-checked rather than accepted, and the
// reason it still does not fire is that the one renderer with an
// offscreen target — PrivateEntityViewportRenderer — is composed on GL
// only. Making the precondition loud here is what stops that from being
// discovered as a driver-level fault the first time it is composed;
// serving it needs a SECOND, layered view per render target, which
// belongs to the slice that gives the Vulkan arm a viewport.
if (VulkanTextureFormatMapping.IsRenderTarget(vulkanTexture.Format))
{
throw new NotSupportedException(
$"Render target '{vulkanTexture.Name}' cannot be registered into the texture table: "
+ "its attachment view is 2-D and the table's descriptor array is sampler2DArray. "
+ "A layered sampled view per render target is the fix (campaign plan §5.5.7).");
}
return TextureTable.Register(vulkanTexture.View, vulkanSampler.Handle);
// Campaign V slice V6k made this a loud refusal, and V6l is the slice
// that serves it. A render-target image is viewed as
// VK_IMAGE_VIEW_TYPE_2D because that is what an ATTACHMENT needs, while
// the table's descriptor array is declared sampler2DArray — so the
// attachment view is invalid usage here rather than a mismatch that
// samples oddly (plan §5.5.7). VulkanGpuTexture now creates a SECOND,
// layered view over the same image for exactly this, and every texture
// that is not an attachment has always had one; SampledView is that view
// in both cases, so the question disappears rather than being answered.
return TextureTable.Register(vulkanTexture.SampledView, vulkanSampler.Handle);
}
public void ReleaseTextureSlot(GpuTextureSlot slot)

17
src/AcDream.App/Rendering/Gpu/Vk/VulkanGpuRenderTarget.cs
View file

@ -12,6 +12,12 @@ namespace AcDream.App.Rendering.Gpu.Vk;
/// so it can be registered into the texture table and drawn by the retained UI
/// the moment its pass ends — which is the whole reason these exist rather than
/// rendering those views onto the backbuffer.</para>
///
/// <para>Slice V6l made both halves of that sentence true. The colour image now
/// carries a second, LAYERED view for the table to sample (see
/// <see cref="VulkanGpuTexture.SampledView"/>), and the depth image takes the
/// device's own combined depth/stencil format so the world pipelines that draw
/// into this target are not undefined against it.</para>
/// </summary>
internal sealed class VulkanGpuRenderTarget : IGpuRenderTarget
{
@ -26,7 +32,8 @@ internal sealed class VulkanGpuRenderTarget : IGpuRenderTarget
VulkanUploadQueue uploads,
IGpuResourceRetirementQueue retirement,
VulkanDebugNames debugNames,
in GpuRenderTargetDescription description)
in GpuRenderTargetDescription description,
Format deviceDepthStencilFormat)
{
ArgumentException.ThrowIfNullOrWhiteSpace(description.Name);
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(description.Width);
@ -69,7 +76,13 @@ internal sealed class VulkanGpuRenderTarget : IGpuRenderTarget
LayerCount: 1,
MipLevelCount: 1),
Math.Max(1, description.SampleCount),
renderTarget: true);
renderTarget: true,
// Slice V6l: the DEVICE's combined depth/stencil format, not the
// contract enum's literal one. Every pipeline bakes one
// depth/stencil format under dynamic rendering and the same
// pipelines draw in both the backbuffer pass and this one, so a
// second format here would make one of the two undefined.
formatOverride: deviceDepthStencilFormat);
}
}

49
src/AcDream.App/Rendering/Gpu/Vk/VulkanGpuTexture.cs
View file

@ -40,7 +40,10 @@ internal sealed unsafe class VulkanGpuTexture : IGpuTexture
VulkanDebugNames debugNames,
in GpuTextureDescription description,
int sampleCount = 1,
bool renderTarget = false)
bool renderTarget = false,
// Fully qualified: in a parameter-default expression the simple name
// `Format` binds to this type's own GpuTextureFormat property first.
Format formatOverride = Silk.NET.Vulkan.Format.Undefined)
{
_vk = vk ?? throw new ArgumentNullException(nameof(vk));
_device = device;
@ -61,7 +64,14 @@ internal sealed unsafe class VulkanGpuTexture : IGpuTexture
LayerCount = description.LayerCount;
MipLevelCount = description.MipLevelCount;
SampleCount = sampleCount;
VkFormat = VulkanTextureFormatMapping.FormatOf(description.Format);
// Slice V6l: an offscreen target's DEPTH attachment takes the format the
// device already chose for the backbuffer, because a pipeline bakes one
// depth/stencil format and draws in both kinds of pass. The contract's
// Depth24Stencil8 means "a combined depth+stencil attachment"; which
// combined format that is belongs to the device that probed for it.
VkFormat = formatOverride != Silk.NET.Vulkan.Format.Undefined
? formatOverride
: VulkanTextureFormatMapping.FormatOf(description.Format);
Aspect = VulkanTextureFormatMapping.AspectOf(description.Format);
bool depthStencil = VulkanTextureFormatMapping.IsDepthStencil(description.Format);
@ -132,6 +142,28 @@ internal sealed unsafe class VulkanGpuTexture : IGpuTexture
_vk.CreateImageView(_device, &viewCreate, null, out ImageView view),
$"vkCreateImageView ('{description.Name}')");
View = view;
SampledView = view;
// Campaign V slice V6l: a colour render target needs TWO views.
//
// An ATTACHMENT view must be VK_IMAGE_VIEW_TYPE_2D, and the global
// texture table's descriptor array is declared sampler2DArray, so the
// attachment view cannot legally be registered into it — plan §5.5.7
// recorded that as invalid usage rather than a mismatch that samples
// oddly, and V6k made VulkanGpuDevice.RegisterTexture refuse it and
// name this fix. A second, LAYERED view over the same image is that
// fix: one image, one allocation, two ways of looking at it. Legal
// without any creation flag — a 2D_ARRAY view over an imageType-2D
// image with arrayLayers >= 1 is exactly what the spec permits.
if (renderTarget && !depthStencil)
{
viewCreate.ViewType = VulkanTextureFormatMapping.SampledViewTypeOf(description.Kind);
VulkanInterop.Check(
_vk.CreateImageView(_device, &viewCreate, null, out ImageView sampled),
$"vkCreateImageView ('{description.Name}', sampled)");
SampledView = sampled;
debugNames.NameImageView(sampled, $"{description.Name}-sampled-view");
}
}
catch
{
@ -153,7 +185,17 @@ internal sealed unsafe class VulkanGpuTexture : IGpuTexture
internal int SampleCount { get; }
internal Image Image { get; }
/// <summary>The view a pass names as an attachment, and the only view a non-attachment has.</summary>
internal ImageView View { get; }
/// <summary>
/// The view the global texture table samples. Identical to <see cref="View"/>
/// for every ordinary texture; a second, LAYERED view for a colour render
/// target, because an attachment view is 2-D and the table's descriptor array
/// is <c>sampler2DArray</c> (slice V6l, plan §5.5.7).
/// </summary>
internal ImageView SampledView { get; }
internal Format VkFormat { get; }
internal ImageAspectFlags Aspect { get; }
@ -218,9 +260,12 @@ internal sealed unsafe class VulkanGpuTexture : IGpuTexture
Image image = Image;
ImageView view = View;
ImageView sampledView = SampledView;
VulkanAllocation allocation = _allocation;
_retirement.Retire(() =>
{
if (sampledView.Handle != view.Handle)
_vk.DestroyImageView(_device, sampledView, null);
_vk.DestroyImageView(_device, view, null);
_vk.DestroyImage(_device, image, null);
_allocator.Free(allocation);

2
src/AcDream.App/Rendering/Gpu/Vk/VulkanWorldPassScope.cs
View file

@ -52,7 +52,7 @@ internal sealed unsafe class VulkanWorldPassScope : IWorldPassScope
/// per frame, so a nested publication could only mean two phases believe they
/// own the frame.
/// </summary>
internal IDisposable Publish(IGpuPassEncoder encoder)
public IDisposable Publish(IGpuPassEncoder encoder)
{
ArgumentNullException.ThrowIfNull(encoder);
if (_encoder is not null)