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

feat(render): Campaign V slice V6k commit 1 - the sky draws on Vulkan

Browse source 
V4f's content, landed as a SECOND arm per section 5.5.6: GL keeps its raw world
path through to V10 and the RHI world path ships on Vulkan. Every GL statement in
SkyRenderer is the one it always issued; the encoder arm lives in SkyRenderer.Rhi.cs
and runs only when there is no GL context.

What it produces. ACDREAM_RENDER_BACKEND=vulkan renders the sky: the dome
quadrants, the horizon band, the cloud sheet and the fog gradient, in the same
place and the same colours as the GL capture of the same scene (within a few
units on the channels sampled, which is the day-fraction drift between two
launches). Section 5.5.15's first V7 defect - "the sky is flat fog" - is closed.

Three things differ from the GL arm, each because Vulkan bakes what GL sets. The
per-submesh blend function becomes two PIPELINES, additive for sun/moon/stars and
straight alpha for everything else, because core Vulkan 1.3 does not make blend
dynamic. The SkyParams block becomes a ring slice taken per draw rather than one
buffer rewritten per draw, because a descriptor's contents are read at execution
time, not record time. And the pass is borrowed from IWorldPassScope, because the
frame's one backbuffer pass resolves and a second pass could not load what it
left.

The sky is the first Vulkan consumer of set 1 binding 4. Section 5.5.8 recorded
that UniformSkyParams was missing from the uniform set layout and V6i-2 added it;
until now nothing had ever bound it.

The stride bug, which is the fourth of its class this campaign. The first Vulkan
sky frame drew the dome as a field of blue-white noise. The RHI vertex layout
declared a 32-byte stride - position, normal, texcoord, exactly what sky.vert
reads - while AcDream.Core.Terrain.Vertex is 36 bytes: it carries a fourth
member, TerrainLayer, that no sky attribute names and that the GL arm never
described to a glVertexAttribPointer but did count, because it says
sizeof(Vertex). Nothing else in the frame looked wrong, no validation rule was
violated, and the offline pixel gate masks the sky band, so only a side-by-side
capture found it. SkyVertexLayoutTests now asserts the REQUIREMENT - the stride
is the uploaded record's footprint - rather than today's number.

The last interim handle table is gone. V4t retired the private
GlBindlessHandleTable in WbDrawDispatcher, EnvCellRenderer, TerrainModernRenderer
and ParticleRenderer and deliberately left the sky's, because the sky is the one
world path that mints its own resident handles from TextureCache's raw GL texture
names rather than interning someone else's. It now registers those handles
through V4t's RegisterWorldTextureHandle seam instead, which is the same
mechanical change the other four took, and the class and its tests are deleted
because nothing else ever used them.

TextureCache gains RegisterWorldSurface(surfaceId, repeat), the sky's RHI texture
source: the same DecodeFromDats the GL path uses, created through
IGpuDevice.CreateTexture and paired with a real sampler object rather than baked
into a bindless handle. Keyed by (surface, wrap) for the same reason the GL arm
keys its handles that way - a table entry is a combined image sampler, so the
dome sampled CLAMP_TO_EDGE and a scrolling cloud sheet sampled REPEAT are two
entries over one decoded texture.

Gates. Release build green. App tests 4,109 passed / 3 skipped - the 4,112
baseline less the six GlBindlessHandleTable tests that went with the class, plus
three vertex-layout tests. Strict GL offline pixel gate against 7ae796a1:
4.43e-05, 25 differing pixels of 563,200, inside the documented 9-31 band, with
maximumChannelDelta 48 in the same 46-52 range every control pair reports. GL
connected repeat gate at 3 runs: 3/3 RENDERED on the desktop witness and 3/3 on
the client capture. Seven-day-group before-and-after comparison on GL - the
method V6e used, because the pixel gate masks the sky band - matching in
gradient, cloud sheet, horizon band and fog on every group, including day group
2's salmon cloud band and day group 6's green band. One offline Vulkan run with
VK_LAYER_KHRONOS_validation proven inserted by the loader: zero validation
errors, zero warnings, a captured sky frame, graceful close.

Coverage gap, stated rather than assumed. The offline scene is a fixed outdoor
view at one time of day, so the sun, the moon and the rain cylinder are drawn by
neither arm's gate. They join the accumulated user-gate debt in plan section 5.1,
where V6e already filed them.

No divergence-register row: no retail-facing behaviour changes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Erik 2026-07-28 16:31:37 +02:00
parent 7ae796a110
commit 22aa2edc65
7 changed files with 618 additions and 293 deletions
Download patch file Download diff file Expand all files Collapse all files

256
src/AcDream.App/Rendering/Sky/SkyRenderer.cs
View file

@ -43,35 +43,45 @@ namespace AcDream.App.Rendering.Sky;
/// measured clockwise from north.
/// </para>
/// </summary>
public sealed unsafe class SkyRenderer : IDisposable
public sealed unsafe partial class SkyRenderer : IDisposable
{
private readonly GL _gl;
private readonly GL? _gl;
private readonly IDatReaderWriter _dats;
private readonly Shader _shader;
private readonly Shader? _shader;
private readonly TextureCache _textures;
private readonly SamplerCache _samplers;
private readonly SamplerCache? _samplers;
// Campaign V slice V6e. Three GL objects replace what used to be a run of
// Campaign V slice V6e. Two GL objects replace what used to be a run of
// glUniform* calls and a texture/sampler binding on unit 0:
//
// _paramsUbo — the std140 SkyParams block both stages declare.
// _textureTableSsbo — the binding=9 handle table (the GL-only emulation
// of Vulkan's set 2), holding one entry per
// (texture, wrap-mode) pair the sky samples.
// _uTextureIndexALoc — the push-constant-named uniform carrying the slot.
//
// The wrap mode is what makes the pairing necessary. A bindless handle
// BAKES its sampler state, so the per-submesh Repeat-vs-ClampToEdge choice
// that used to be a glBindSampler call has to be a different handle — which
// is also exactly how the Vulkan table works, where an entry is a combined
// image sampler. ManagedGLTextureArray has interned wrap/clamp handle pairs
// the same way since the world path went bindless.
private readonly Wb.BindlessSupport _bindless;
private readonly GlBindlessHandleTable _textureTable = new();
// The wrap mode is what makes the (texture, wrap) pairing necessary. A
// bindless handle BAKES its sampler state, so the per-submesh
// Repeat-vs-ClampToEdge choice that used to be a glBindSampler call has to be
// a different handle — which is also exactly how the Vulkan table works,
// where an entry is a combined image sampler. ManagedGLTextureArray has
// interned wrap/clamp handle pairs the same way since the world path went
// bindless.
//
// Campaign V slice V6k retired the interim per-renderer GlBindlessHandleTable
// — the last one in the tree — for the device's own retirement-gated table,
// exactly as V4t did for the other four world renderers. The handles are
// still minted here, because the sky is the one world path whose textures it
// produces itself; only the slot allocator moved.
private readonly Wb.BindlessSupport? _bindless;
/// <summary>
/// Campaign V slice V6k: the GL arm's slot allocator. The sky mints its own
/// resident handles — it is the one world path that does — so it registers
/// them into the device's table through V4t's world-handle seam instead of
/// keeping the last private <c>GlBindlessHandleTable</c> in the tree.
/// </summary>
private readonly AcDream.App.Rendering.Gpu.Gl.GlGpuDevice? _glDevice;
private readonly Dictionary<(uint Texture, bool Repeat), ulong> _handleByTextureAndWrap = new();
private uint _paramsUbo;
private uint _textureTableSsbo;
private int _textureTableSsboCapacityBytes;
private int _uTextureIndexALoc = -1;
private SkyParams _params;
@ -87,13 +97,14 @@ public sealed unsafe class SkyRenderer : IDisposable
public float Near { get; set; } = 0.1f;
public float Far { get; set; } = 1_000_000f;
public SkyRenderer(
internal SkyRenderer(
GL gl,
IDatReaderWriter dats,
Shader shader,
TextureCache textures,
SamplerCache samplers,
Wb.BindlessSupport bindless)
Wb.BindlessSupport bindless,
AcDream.App.Rendering.Gpu.Gl.GlGpuDevice device)
{
_gl = gl ?? throw new ArgumentNullException(nameof(gl));
_dats = dats ?? throw new ArgumentNullException(nameof(dats));
@ -101,6 +112,7 @@ public sealed unsafe class SkyRenderer : IDisposable
_textures = textures ?? throw new ArgumentNullException(nameof(textures));
_samplers = samplers ?? throw new ArgumentNullException(nameof(samplers));
_bindless = bindless ?? throw new ArgumentNullException(nameof(bindless));
_glDevice = device ?? throw new ArgumentNullException(nameof(device));
_uTextureIndexALoc = _gl.GetUniformLocation(_shader.Program, "uTextureIndexA");
@ -117,9 +129,6 @@ public sealed unsafe class SkyRenderer : IDisposable
BufferUsageARB.DynamicDraw,
"allocating sky params UBO");
_gl.BindBuffer(BufferTargetARB.UniformBuffer, 0);
_textureTableSsbo = Wb.TrackedGlResource.CreateBuffer(
_gl, "sky texture-table SSBO creation");
}
/// <summary>
@ -228,7 +237,7 @@ public sealed unsafe class SkyRenderer : IDisposable
skyView.M42 = 0f;
skyView.M43 = 0f;
_shader.Use();
_shader?.Use();
// Campaign V slice V6e: the values below used to be individual
// glUniform* calls. They now populate the std140 SkyParams block, which
// is uploaded once per submesh right before its draw — the same cadence
@ -246,29 +255,33 @@ public sealed unsafe class SkyRenderer : IDisposable
_params.SunDir =
AcDream.Core.World.SkyStateProvider.SunDirectionFromKeyframe(keyframe);
_gl.BindBufferBase(
BufferTargetARB.UniformBuffer,
AcDream.App.Rendering.Gpu.GpuBindingModel.UniformSkyParams,
_paramsUbo);
bool wasCullFace = false;
if (_gl is { } gl)
{
gl.BindBufferBase(
BufferTargetARB.UniformBuffer,
AcDream.App.Rendering.Gpu.GpuBindingModel.UniformSkyParams,
_paramsUbo);
// Save + override GL state.
_gl.DepthMask(false);
_gl.Disable(EnableCap.DepthTest);
// Save + disable CullFace for the sky pass; restore at the end.
// Mirrors TextRenderer.cs's save/restore pattern. Without this the
// sky pass left CullFace disabled regardless of its prior state,
// which is benign today (the global convention in this codebase is
// off and subsequent renderers manage their own CullFace) but
// would break the moment any future caller assumes back-face
// culling stays on across the sky pass.
bool wasCullFace = _gl.IsEnabled(EnableCap.CullFace);
_gl.Disable(EnableCap.CullFace);
_gl.Enable(EnableCap.Blend);
// Default blend — overridden per-submesh inside the inner loop.
// Additive surfaces (sun/moon/stars via SurfaceType.Additive =
// 0x10000) get GL_SRC_ALPHA / GL_ONE; alpha-blended (clouds, dome
// with Alpha flag) get GL_SRC_ALPHA / GL_ONE_MINUS_SRC_ALPHA.
_gl.BlendFunc(BlendingFactor.SrcAlpha, BlendingFactor.OneMinusSrcAlpha);
// Save + override GL state.
gl.DepthMask(false);
gl.Disable(EnableCap.DepthTest);
// Save + disable CullFace for the sky pass; restore at the end.
// Mirrors TextRenderer.cs's save/restore pattern. Without this the
// sky pass left CullFace disabled regardless of its prior state,
// which is benign today (the global convention in this codebase is
// off and subsequent renderers manage their own CullFace) but
// would break the moment any future caller assumes back-face
// culling stays on across the sky pass.
wasCullFace = gl.IsEnabled(EnableCap.CullFace);
gl.Disable(EnableCap.CullFace);
gl.Enable(EnableCap.Blend);
// Default blend — overridden per-submesh inside the inner loop.
// Additive surfaces (sun/moon/stars via SurfaceType.Additive =
// 0x10000) get GL_SRC_ALPHA / GL_ONE; alpha-blended (clouds, dome
// with Alpha flag) get GL_SRC_ALPHA / GL_ONE_MINUS_SRC_ALPHA.
gl.BlendFunc(BlendingFactor.SrcAlpha, BlendingFactor.OneMinusSrcAlpha);
}
// Look up the keyframe's override list so we can apply
// SkyObjReplace (r12 §2.3): per-keyframe GfxObj swaps + rotation
@ -389,11 +402,16 @@ public sealed unsafe class SkyRenderer : IDisposable
// SrcAlpha/InvSrcAlpha for a no-op blend at alpha=1).
// See FUN_00508010 (chunk_00500000.c:7535) for the retail
// pattern — retail routes sky meshes through the normal
// mesh pipeline where Surface flags dictate state.
if (sub.IsAdditive)
_gl.BlendFunc(BlendingFactor.SrcAlpha, BlendingFactor.One);
else
_gl.BlendFunc(BlendingFactor.SrcAlpha, BlendingFactor.OneMinusSrcAlpha);
// mesh pipeline where Surface flags dictate state. On the RHI
// arm the same two blend functions are two pipelines, because
// Vulkan bakes blend rather than making it dynamic.
if (_gl is { } blendGl)
{
if (sub.IsAdditive)
blendGl.BlendFunc(BlendingFactor.SrcAlpha, BlendingFactor.One);
else
blendGl.BlendFunc(BlendingFactor.SrcAlpha, BlendingFactor.OneMinusSrcAlpha);
}
// Emissive source picks the surface's authored Luminosity by
// default; the per-keyframe replace data can OVERRIDE
@ -445,8 +463,6 @@ public sealed unsafe class SkyRenderer : IDisposable
// 0x08000023 remains unfogged and keeps the pink detail.
_params.ApplyFog = sub.DisableFog ? 0f : 1f;
uint tex = _textures.GetOrUpload(sub.SurfaceId);
// Sky meshes need per-object wrap mode driven by the
// mesh's authored UV range, not by TexVelocity:
// * The outer dome (0x010015EE/F0/F1/F2) authors UVs
@ -486,19 +502,28 @@ public sealed unsafe class SkyRenderer : IDisposable
bool needsRepeat = sub.NeedsUvRepeat
|| obj.TexVelocityX != 0f
|| obj.TexVelocityY != 0f;
_gl.ProgramUniform1(
_shader.Program,
_uTextureIndexALoc,
TextureTableSlot(tex, needsRepeat));
uint slot = TextureTableSlot(sub.SurfaceId, needsRepeat);
UploadParams();
FlushAndBindTextureTable();
if (_gl is { } drawGl)
{
drawGl.ProgramUniform1(
_shader!.Program,
_uTextureIndexALoc,
slot);
_gl.BindVertexArray(sub.Vao);
_gl.DrawElements(PrimitiveType.Triangles,
(uint)sub.IndexCount,
DrawElementsType.UnsignedInt,
(void*)0);
UploadParams();
FlushAndBindTextureTable();
drawGl.BindVertexArray(sub.Vao);
drawGl.DrawElements(PrimitiveType.Triangles,
(uint)sub.IndexCount,
DrawElementsType.UnsignedInt,
(void*)0);
}
else
{
DrawSubMeshRhi(sub, slot);
}
}
}
@ -510,11 +535,14 @@ public sealed unsafe class SkyRenderer : IDisposable
// nothing left to leak onto the next renderer's unit 0. That unbind was
// load-bearing precisely because the binding was global state; a table
// slot is not.
_gl.Disable(EnableCap.Blend);
_gl.DepthMask(true);
_gl.Enable(EnableCap.DepthTest);
if (wasCullFace) _gl.Enable(EnableCap.CullFace);
_gl.BindVertexArray(0);
if (_gl is { } restoreGl)
{
restoreGl.Disable(EnableCap.Blend);
restoreGl.DepthMask(true);
restoreGl.Enable(EnableCap.DepthTest);
if (wasCullFace) restoreGl.Enable(EnableCap.CullFace);
restoreGl.BindVertexArray(0);
}
}
/// <summary>
@ -531,18 +559,22 @@ public sealed unsafe class SkyRenderer : IDisposable
/// handle table in the codebase — the sky's texture set is a fixed handful
/// per day group and does not churn.</para>
/// </summary>
private uint TextureTableSlot(uint textureName, bool repeat)
private uint TextureTableSlot(uint surfaceId, bool repeat)
{
if (_gl is null)
return RhiTextureTableSlot(surfaceId, repeat);
uint textureName = _textures.GetOrUpload(surfaceId);
var key = (textureName, repeat);
if (!_handleByTextureAndWrap.TryGetValue(key, out ulong handle))
{
handle = _bindless.GetResidentHandle(
handle = _bindless!.GetResidentHandle(
textureName,
repeat ? _samplers.Wrap : _samplers.Clamp);
repeat ? _samplers!.Wrap : _samplers!.Clamp);
_handleByTextureAndWrap.Add(key, handle);
}
return _textureTable.GetOrAdd(handle);
return _glDevice!.RegisterWorldTextureHandle(handle).Index;
}
/// <summary>
@ -552,51 +584,31 @@ public sealed unsafe class SkyRenderer : IDisposable
/// </summary>
private void UploadParams()
{
GL gl = _gl!;
fixed (void* p = &_params)
{
_gl.BindBuffer(BufferTargetARB.UniformBuffer, _paramsUbo);
_gl.BufferSubData(
gl.BindBuffer(BufferTargetARB.UniformBuffer, _paramsUbo);
gl.BufferSubData(
BufferTargetARB.UniformBuffer, 0, (nuint)SkyParams.SizeInBytes, p);
}
}
/// <summary>
/// Uploads newly interned handles to the binding=9 table and (re)binds it.
/// Campaign V slice V6k: drains the device texture table's dirty runs and
/// (re)binds it at
/// <see cref="AcDream.App.Rendering.Gpu.GpuBindingModel.StorageTextureTable"/>.
/// Mirrors <c>ParticleRenderer.FlushAndBindTextureTable</c>, including its
/// reason for running per draw rather than per pass: a submesh partway
/// through the sky stack can be the first to ask for a wrap mode.
/// </summary>
private void FlushAndBindTextureTable()
{
if (_textureTable.Dirty)
{
ReadOnlySpan<ulong> handles = _textureTable.Handles;
int byteCount = handles.Length * sizeof(ulong);
fixed (ulong* p = handles)
{
_gl.BindBuffer(BufferTargetARB.ShaderStorageBuffer, _textureTableSsbo);
if (_textureTableSsboCapacityBytes < byteCount)
{
int grown = DynamicBufferCapacity.Grow(_textureTableSsboCapacityBytes, byteCount);
Wb.TrackedGlResource.AllocateBufferStorage(
_gl,
BufferTargetARB.ShaderStorageBuffer,
_textureTableSsbo,
_textureTableSsboCapacityBytes,
grown,
BufferUsageARB.DynamicDraw,
"growing sky texture-table SSBO");
_textureTableSsboCapacityBytes = grown;
}
_gl.BufferSubData(BufferTargetARB.ShaderStorageBuffer, 0, (nuint)byteCount, p);
}
_textureTable.MarkFlushed();
}
_gl.BindBufferBase(
AcDream.App.Rendering.Gpu.Gl.GlGpuDevice device = _glDevice!;
device.FlushTextureTable();
_gl!.BindBufferBase(
BufferTargetARB.ShaderStorageBuffer,
AcDream.App.Rendering.Gpu.GpuBindingModel.StorageTextureTable,
_textureTableSsbo);
device.TextureTableGlName);
}
/// <summary>
@ -826,6 +838,9 @@ public sealed unsafe class SkyRenderer : IDisposable
private SubMeshGpu UploadSubMesh(GfxObjSubMesh sm)
{
if (_gl is null)
return UploadSubMeshRhi(sm);
uint vao = _gl.GenVertexArray();
_gl.BindVertexArray(vao);
@ -882,6 +897,12 @@ public sealed unsafe class SkyRenderer : IDisposable
public void Dispose()
{
if (_gl is null)
{
DisposeRhi();
return;
}
foreach (var subs in _gpuByGfxObj.Values)
{
foreach (var sub in subs)
@ -896,8 +917,16 @@ public sealed unsafe class SkyRenderer : IDisposable
// Campaign V slice V6e. Residency first: a handle made resident pins
// its texture's GPU address, and the textures themselves belong to
// TextureCache, which outlives this renderer and disposes them itself.
//
// Slice V6k: the device's table entry is retired alongside it, in the
// order V4t established — the table entry goes first, because the slot
// is only recycled once the frames that could still read it retire,
// whereas the handle stops being valid the instant it is non-resident.
foreach (ulong handle in _handleByTextureAndWrap.Values)
_bindless.MakeNonResident(handle);
{
_glDevice!.ReleaseWorldTextureHandle(handle);
_bindless!.MakeNonResident(handle);
}
_handleByTextureAndWrap.Clear();
if (_paramsUbo != 0)
@ -906,17 +935,6 @@ public sealed unsafe class SkyRenderer : IDisposable
_gl, _paramsUbo, SkyParams.SizeInBytes, "sky params UBO disposal");
_paramsUbo = 0;
}
if (_textureTableSsbo != 0)
{
Wb.TrackedGlResource.DeleteBuffer(
_gl,
_textureTableSsbo,
_textureTableSsboCapacityBytes,
"sky texture-table SSBO disposal");
_textureTableSsbo = 0;
_textureTableSsboCapacityBytes = 0;
}
}
/// <summary>
@ -955,6 +973,14 @@ public sealed unsafe class SkyRenderer : IDisposable
public uint Vao;
public uint Vbo;
public uint Ebo;
/// <summary>
/// Campaign V slice V6k: the RHI arm's vertex source. The sky's meshes are
/// built once per GfxObj and never change, so each submesh owns a
/// device-local buffer pair rather than taking a ring slice per frame.
/// Null on the GL arm, which uses <see cref="Vao"/>.
/// </summary>
public AcDream.App.Rendering.Gpu.IGpuBuffer? VertexBuffer;
public AcDream.App.Rendering.Gpu.IGpuBuffer? IndexBuffer;
public int IndexCount;
public uint SurfaceId;
/// <summary>