Fixes World Lighting to Text Rendering so its not Fullbright (#1976)

* Fixes World Lighting to Text Rendering so its not Fullbright

* Carry lightmap state per text segment

* Text lighting: per-segment lightmap uniform, fix GL_RESCALE_NORMAL
* per segment uniform instead of stride increase
* Shade text based on GL light state
* fix u_NormalScale
* GL_LIGHT > 1 usage warnings (not currently handled)

---------

Co-authored-by: Jason Mitchell <[email protected]>

.github/workflows/build-tracy-natives.yml

@@ -89,4 +89,4 @@ jobs:
         env:
           MAVEN_USER: ${{ secrets.MAVEN_USER }}
           MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
-        run: ./gradlew :tracy-client:publish
+        run: ./gradlew -PpublishTracy=true :tracy-client:publish

.github/workflows/release-tags.yml

@@ -3,7 +3,7 @@ name: Release tagged build
 
 on:
   push:
-    tags: [ '*' ]
+    tags: [ '*', '!tracy-v*' ]
 
 permissions:
   contents: write

.gitignore

@@ -40,5 +40,6 @@ addon.late.local.gradle
 addon.late.local.gradle.kts
 local/
 tracy-client/src/main/resources/natives/
+tracy-client/angelica/
 dist/tracy-natives/
 *.tracy

build.gradle.kts

@@ -1,3 +1,5 @@
+import com.modrinth.minotaur.TaskModrinthUpload
+import net.darkhax.curseforgegradle.TaskPublishCurseForge
 import xyz.wagyourtail.jvmdg.gradle.flags.DowngradeFlags
 import xyz.wagyourtail.jvmdg.gradle.task.DowngradeJar
 import xyz.wagyourtail.jvmdg.gradle.task.files.DowngradeFiles
@@ -31,11 +33,11 @@ minecraft   {
 
 }
 
-// Ensure flyby args are passed to the client
+// Forward -Dangelica.* from the gradle invocation to the client
 tasks.withType<JavaExec>().matching { it.name.startsWith("runClient") }.configureEach {
     for ((key, value) in System.getProperties()) {
         val name = key.toString()
-        if (name.startsWith("angelica.flyby.")) {
+        if (name.startsWith("angelica.")) {
             jvmArgs("-D$name=$value")
         }
     }
@@ -75,7 +77,7 @@ val isMacOs = org.gradle.internal.os.OperatingSystem.current().isMacOsX
 val isMacOsArm64 = isMacOs && System.getProperty("os.arch") == "aarch64"
 
 tasks.withType<JavaExec>().configureEach {
-    if (name.startsWith("runClient")) {
+    if (name.startsWith("runClient") && name != "runClient") {
         if (isMacOs) {
             // SDL3 / Cocoa / Metal must initialize on the JVM main thread.
             jvmArgs("-XstartOnFirstThread")
@@ -227,7 +229,6 @@ val glCoreTest by tasks.registering(Test::class) {
 }
 
 tasks.test { finalizedBy(glCoreTest) }
-tasks.check { dependsOn(glCoreTest) }
 
 tasks.shadowJar {
     dependsOn(embedOnly)
@@ -252,3 +253,11 @@ tasks.shadowJar {
     relocate("com.gtnewhorizons.angelica.lwjgl3", "com.gtnewhorizons.angelica.lwjgl3")
     relocate("com.gtnewhorizons.angelica.sdlgpu", "com.gtnewhorizons.angelica.sdlgpu")
 }
+
+tasks.withType<TaskPublishCurseForge>().configureEach {
+    uploadArtifacts.forEach { it.addGameVersion("Client") }
+}
+
+tasks.withType<TaskModrinthUpload>().configureEach {
+    setDependsOn(dependsOn.filterNot { it == "build" } + "assemble")
+}

dependencies.gradle.kts

@@ -202,6 +202,7 @@ afterEvaluate {
 
         glsmTestFixtures(testFixtures(project(":glsm")) as ModuleDependency) { isTransitive = false }
         testCompileOnly(testFixtures(project(":glsm")))
+        testImplementation("mega:fluidlogged-mc1.7.10:0.1.2")
 
         testRuntimeOnly(libs.fastutil)
         testRuntimeOnly(libs.joml)

glsm/src/main/java/com/gtnewhorizons/angelica/config/SystemProperties.java

@@ -16,9 +16,11 @@ public final class SystemProperties {
     private static final Logger LOGGER = LogManager.getLogger("SystemProperties");
 
     // Backend selection
-    public static final boolean USE_SDL_GPU = Boolean.getBoolean("angelica.sdlgpu.enable");
+    public static final String KEY_USE_SDL_GPU = "angelica.sdlgpu.enable";
+    public static final boolean USE_SDL_GPU = Boolean.getBoolean(KEY_USE_SDL_GPU);
     public static final String GL_PROFILE = System.getProperty("angelica.glProfile", "");
     public static final boolean DISABLE_NVIDIA_WORKAROUND = Boolean.getBoolean("angelica.disableNvidiaWorkaround");
+    public static final boolean DISABLE_LTW_WORKAROUND = Boolean.getBoolean("angelica.disableLtwWorkaround");
 
     // Redirector
     public static final UnmappedGLMode UNMAPPED_GL = parseEnum("angelica.unmappedGL", UnmappedGLMode.WARN, UnmappedGLMode.WARN, UnmappedGLMode.class);
@@ -33,6 +35,8 @@ public final class SystemProperties {
     public static final boolean SDL_ENCODER_ASSERTIONS_FATAL = ENCODER_ASSERTIONS == SdlAssertionMode.FATAL;
     public static final boolean SDL_VERIFY_STATE_SYNC = Boolean.getBoolean("angelica.sdlgpu.verifyStateSync");
     public static final boolean SDL_VERIFY_PER_FRAME_UNIFORM_BLOCK = Boolean.getBoolean("angelica.sdlgpu.verifyPerFrameUniformBlock");
+    public static final int SDL_FRAMES_IN_FLIGHT = Integer.getInteger("angelica.sdlgpu.framesInFlight", 2);
+    public static final boolean DISABLE_SDL_PRESENTER_THREAD = Boolean.getBoolean("angelica.sdlgpu.disablePresenterThread");
 
     // Tracy
     public static final boolean TRACY = Boolean.getBoolean("angelica.tracy");

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/DisplayListManager.java

@@ -613,6 +613,7 @@ public class DisplayListManager {
             // Get relative transform (changes since glNewList, not absolute matrix state)
             addAccumulatedDraw(tessellator, tessellator.getVertexFormat() != DefaultVertexFormat.POSITION);
         }
+        transformCallback.clearBaked(tessellator);
         tessellator.reset();
     }
 
@@ -1322,6 +1323,16 @@ public class DisplayListManager {
 
         private final Matrix4f transformMatrix = new Matrix4f();
 
+        private DirectTessellator bakedOwner;
+        private int bakedVertices;
+
+        void clearBaked(DirectTessellator tessellator) {
+            if (bakedOwner == tessellator) {
+                bakedOwner = null;
+                bakedVertices = 0;
+            }
+        }
+
         public void scale(float x, float y, float z) {
             transformMatrix.scale(x, y, z);
             markDirty();
@@ -1384,10 +1395,26 @@ public class DisplayListManager {
             return MatrixHelper.isIdentity(transformMatrix);
         }
 
+        @Override
+        public boolean onStartDrawing(CallbackTessellator tessellator, int drawMode) {
+            bakedOwner = tessellator;
+            bakedVertices = 0;
+            return super.onStartDrawing(tessellator, drawMode);
+        }
+
         @Override
         public boolean onDraw(CallbackTessellator tessellator) {
             if (!tessellator.isEmpty()) {
+                if (!isIdentity()) {
+                    final int baked = bakedOwner == tessellator ? bakedVertices : 0;
+                    if (bakedVertices == 0) {
+                        flushMatrix();
+                    } else if (baked != tessellator.vertexCount) {
+                        GLStateManager.warnOnce("dl-mixed-baked-raw", "Display list {}: draw of {} vertices carries {} transformed ones - the rest lose the pending transform", glListId, tessellator.vertexCount, baked);
+                    }
+                }
                 addAccumulatedDraw(tessellator, false);
+                clearBaked(tessellator);
             }
             return true;
         }
@@ -1396,6 +1423,11 @@ public class DisplayListManager {
         public void onVertex(CallbackTessellator tessellator, double x, double y, double z) {
             tessellator.syncVanillaTessellator();
             super.onVertex(tessellator, x, y, z);
+            if (bakedOwner != tessellator) {
+                bakedOwner = tessellator;
+                bakedVertices = 0;
+            }
+            bakedVertices++;
         }
 
         @Override

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/GLContextState.java

@@ -26,10 +26,13 @@ import com.gtnewhorizons.angelica.glsm.states.TextureUnitArray;
 import it.unimi.dsi.fastutil.ints.IntArrayList;
 import it.unimi.dsi.fastutil.ints.IntStack;
 import org.joml.Matrix4fStack;
+import org.lwjgl.BufferUtils;
 import org.lwjgl.opengl.GL11;
 import org.lwjgl.opengl.GL12;
 import org.lwjgl.opengl.GL13;
 
+import java.nio.DoubleBuffer;
+import java.nio.FloatBuffer;
 import java.util.ArrayList;
 import java.util.List;
 
@@ -152,6 +155,8 @@ class GLContextState {
     public final BooleanStateStack map2Vertex4State = track(new BooleanStateStack(GL11.GL_MAP2_VERTEX_4, false, true));
     public final BooleanStateStack[] clipPlaneStates = new BooleanStateStack[GLStateManager.MAX_CLIP_PLANES];
     public final ClipPlaneState clipPlaneState = new ClipPlaneState();
+    public final FloatBuffer queryScratch = BufferUtils.createFloatBuffer(16);
+    public final DoubleBuffer queryScratchDouble = BufferUtils.createDoubleBuffer(16);
     public final MatrixModeStack matrixMode = new MatrixModeStack();
     public final Matrix4fStack modelViewMatrix = new Matrix4fStack(GLStateManager.MAX_MODELVIEW_STACK_DEPTH);
     public final Matrix4fStack projectionMatrix = new Matrix4fStack(GLStateManager.MAX_PROJECTION_STACK_DEPTH);

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/GLStateManager.java

@@ -10,9 +10,11 @@ import com.gtnewhorizons.angelica.config.SystemProperties;
 import com.gtnewhorizons.angelica.glsm.DisplayListManager.RecordMode;
 import com.gtnewhorizons.angelica.glsm.backend.BackendManager;
 import com.gtnewhorizons.angelica.glsm.backend.GLDebugMessageListener;
+import com.gtnewhorizons.angelica.glsm.backend.VSyncMode;
 import com.gtnewhorizons.angelica.glsm.profiling.Tracy;
 import com.gtnewhorizons.angelica.glsm.ffp.ShaderManager;
 import com.gtnewhorizons.angelica.glsm.ffp.VAOManager;
+import com.gtnewhorizons.angelica.glsm.ffp.VertexKey;
 import com.gtnewhorizons.angelica.glsm.hooks.DeferredAlphaHandler;
 import com.gtnewhorizons.angelica.glsm.hooks.DeferredBlendHandler;
 import com.gtnewhorizons.angelica.glsm.hooks.DeferredDepthColorHandler;
@@ -528,7 +530,10 @@ public class GLStateManager {
         }
 
         final String glVendor = RENDER_BACKEND.getString(GL11.GL_VENDOR);
-        VENDOR = Vendor.getVendor(glVendor.toLowerCase());
+        if (glVendor == null) {
+            LOGGER.error("Backend {} reported no GL_VENDOR (context: {}); treating the vendor as unknown", RENDER_BACKEND.getName(), RENDER_BACKEND.hasContext());
+        }
+        VENDOR = Vendor.getVendor(glVendor == null ? "" : glVendor.toLowerCase());
 
         final String os = System.getProperty("os.name").toLowerCase();
         windows = os.contains("win");
@@ -549,6 +554,9 @@ public class GLStateManager {
         // GL_STENCIL_BITS was removed in core profile; query via default FBO attachment
         final int stencilBits = RENDER_BACKEND.getFramebufferAttachmentParameteri(GL30.GL_DRAW_FRAMEBUFFER, GL11.GL_STENCIL, GL30.GL_FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE);
         glCtx.stencilBitMask = stencilBits >= 32 ? 0xFFFFFFFF : (1 << stencilBits) - 1;
+        if (glCtx.stencilBitMask == 0) {
+            LOGGER.warn("Default framebuffer reports 0 stencil bits on backend {}; all stencil masks clamp to 0", RENDER_BACKEND.getClass().getSimpleName());
+        }
 
         // Initialize stencil masks from computed bit mask
         glCtx.stencilState.setValueMaskFront(glCtx.stencilBitMask);
@@ -1183,12 +1191,11 @@ public class GLStateManager {
         };
     }
 
-    private static final FloatBuffer glGetFloatScratch = BufferUtils.createFloatBuffer(16);
-
     public static void glGetFloat(int pname, float[] params) {
+        final FloatBuffer scratch = ctx().queryScratch;
         final FloatBuffer buf;
-        if (params.length <= glGetFloatScratch.capacity()) {
-            buf = glGetFloatScratch;
+        if (params.length <= scratch.capacity()) {
+            buf = scratch;
             buf.clear();
             buf.limit(params.length);
         } else {
@@ -1199,6 +1206,72 @@ public class GLStateManager {
         buf.get(params);
     }
 
+    public static double glGetDouble(int pname) {
+        return switch (pname) {
+            case GL11.GL_DEPTH_CLEAR_VALUE -> ctx().depthState.getClearValue();
+            default -> glGetFloat(pname);
+        };
+    }
+
+    public static void glGetDouble(int pname, DoubleBuffer params) {
+        final GLContextState glCtx = ctx();
+        if (!isCachingEnabled()) {
+            RENDER_BACKEND.getDouble(pname, params);
+            return;
+        }
+
+        final int pos = params.position();
+        switch (pname) {
+            case GL11.GL_DEPTH_CLEAR_VALUE -> params.put(pos, glCtx.depthState.getClearValue());
+            case GL11.GL_DEPTH_RANGE -> {
+                params.put(pos, glCtx.viewportState.depthRangeNear);
+                params.put(pos + 1, glCtx.viewportState.depthRangeFar);
+            }
+            case GL11.GL_MODELVIEW_MATRIX, GL11.GL_PROJECTION_MATRIX, GL11.GL_TEXTURE_MATRIX -> widenFromFloat(pname, params, 16);
+            case GL11.GL_COLOR_CLEAR_VALUE, GL11.GL_CURRENT_COLOR, GL11.GL_CURRENT_TEXTURE_COORDS, GL11.GL_FOG_COLOR,
+                GL11.GL_LIGHT_MODEL_AMBIENT, GL14.GL_BLEND_COLOR -> widenFromFloat(pname, params, 4);
+            case GL11.GL_CURRENT_NORMAL -> widenFromFloat(pname, params, 3);
+            default -> {
+                if (!HAS_MULTIPLE_SET.contains(pname)) {
+                    params.put(pos, glGetDouble(pname));
+                } else {
+                    RENDER_BACKEND.getDouble(pname, params);
+                }
+            }
+        }
+    }
+
+    public static void glGetDouble(int pname, double[] params) {
+        final DoubleBuffer scratch = ctx().queryScratchDouble;
+        final DoubleBuffer buf;
+        if (params.length <= scratch.capacity()) {
+            buf = scratch;
+            buf.clear();
+            buf.limit(params.length);
+        } else {
+            buf = BufferUtils.createDoubleBuffer(params.length);
+        }
+        glGetDouble(pname, buf);
+        buf.position(0);
+        buf.get(params);
+    }
+
+    private static void widenFromFloat(int pname, DoubleBuffer params, int count) {
+        final FloatBuffer scratch = ctx().queryScratch;
+        scratch.clear();
+        glGetFloat(pname, scratch);
+        final int pos = params.position();
+        for (int i = 0; i < count; i++) {
+            params.put(pos + i, scratch.get(i));
+        }
+    }
+
+    public static void glGetClipPlane(int plane, DoubleBuffer equation) {
+        final int index = plane - GL11.GL_CLIP_PLANE0;
+        if (index < 0 || index >= MAX_CLIP_PLANES) return;
+        ctx().clipPlaneState.getEyePlane(index, equation);
+    }
+
     // GLStateManager Functions
 
     public static void glBlendColor(float red, float green, float blue, float alpha) {
@@ -1897,6 +1970,7 @@ public class GLStateManager {
         suspendPixelUnpackBuffer();
         RENDER_BACKEND.texImage2D(target, level, internalformat, width, height, border, format, type, pixels);
         restorePixelUnpackBuffer();
+        if (mode == RecordMode.NONE && RenderSystem.isLTW()) LTWWorkaround.onTexImage2D(target, level, format, pixels != null);
         maybeGenerateMipmap(target, level);
     }
 
@@ -1915,6 +1989,7 @@ public class GLStateManager {
         suspendPixelUnpackBuffer();
         RENDER_BACKEND.texImage2D(target, level, internalformat, width, height, border, format, type, pixels);
         restorePixelUnpackBuffer();
+        if (mode == RecordMode.NONE && RenderSystem.isLTW()) LTWWorkaround.onTexImage2D(target, level, format, pixels != null);
         maybeGenerateMipmap(target, level);
     }
 
@@ -1933,6 +2008,7 @@ public class GLStateManager {
         suspendPixelUnpackBuffer();
         RENDER_BACKEND.texImage2D(target, level, internalformat, width, height, border, format, type, pixels);
         restorePixelUnpackBuffer();
+        if (mode == RecordMode.NONE && RenderSystem.isLTW()) LTWWorkaround.onTexImage2D(target, level, format, pixels != null);
         maybeGenerateMipmap(target, level);
     }
 
@@ -1951,6 +2027,7 @@ public class GLStateManager {
         suspendPixelUnpackBuffer();
         RENDER_BACKEND.texImage2D(target, level, internalformat, width, height, border, format, type, pixels);
         restorePixelUnpackBuffer();
+        if (mode == RecordMode.NONE && RenderSystem.isLTW()) LTWWorkaround.onTexImage2D(target, level, format, pixels != null);
         maybeGenerateMipmap(target, level);
     }
 
@@ -2258,7 +2335,7 @@ public class GLStateManager {
     }
 
     public static void glDrawElements(int mode, ByteBuffer indices) {
-        if (Tracy.ENABLED) drawCalls++;
+        drawCalls++;
         CommandRecorder savedRecorder = null;
         final RecordMode recordMode = DisplayListManager.getRecordMode();
         if (recordMode != RecordMode.NONE) {
@@ -2283,7 +2360,7 @@ public class GLStateManager {
     }
 
     public static void glDrawElements(int mode, IntBuffer indices) {
-        if (Tracy.ENABLED) drawCalls++;
+        drawCalls++;
         CommandRecorder savedRecorder = null;
         final RecordMode recordMode = DisplayListManager.getRecordMode();
         if (recordMode != RecordMode.NONE) {
@@ -2308,7 +2385,7 @@ public class GLStateManager {
     }
 
     public static void glDrawElements(int mode, ShortBuffer indices) {
-        if (Tracy.ENABLED) drawCalls++;
+        drawCalls++;
         CommandRecorder savedRecorder = null;
         final RecordMode recordMode = DisplayListManager.getRecordMode();
         if (recordMode != RecordMode.NONE) {
@@ -2333,7 +2410,7 @@ public class GLStateManager {
     }
 
     public static void glDrawElements(int mode, int count, int type, ByteBuffer indices) {
-        if (Tracy.ENABLED) drawCalls++;
+        drawCalls++;
         CommandRecorder savedRecorder = null;
         final RecordMode recordMode = DisplayListManager.getRecordMode();
         if (recordMode != RecordMode.NONE) {
@@ -2358,7 +2435,7 @@ public class GLStateManager {
     }
 
     public static void glDrawElements(int mode, int indices_count, int type, long indices_buffer_offset) {
-        if (Tracy.ENABLED) drawCalls++;
+        drawCalls++;
         CommandRecorder savedRecorder = null;
         final RecordMode recordMode = DisplayListManager.getRecordMode();
         if (recordMode != RecordMode.NONE) {
@@ -2401,22 +2478,22 @@ public class GLStateManager {
     }
 
     public static void glMultiDrawElementsIndirect(int mode, int type, long indirect, int drawcount, int stride) {
-        if (Tracy.ENABLED) drawCalls += drawcount;
+        drawCalls += drawcount;
         RENDER_BACKEND.multiDrawElementsIndirect(mode, type, indirect, drawcount, stride);
     }
 
     public static void glMultiDrawElementsBaseVertex(int mode, long pCount, int type, long pIndices, int drawcount, long pBaseVertex) {
-        if (Tracy.ENABLED) drawCalls += drawcount;
+        drawCalls += drawcount;
         RENDER_BACKEND.multiDrawElementsBaseVertex(mode, pCount, type, pIndices, drawcount, pBaseVertex);
     }
 
     public static void glDrawElementsBaseVertex(int mode, int count, int type, long indices, int basevertex) {
-        if (Tracy.ENABLED) drawCalls++;
+        drawCalls++;
         RENDER_BACKEND.drawElementsBaseVertex(mode, count, type, indices, basevertex);
     }
 
     public static void glDrawElementsInstanced(int mode, int count, int type, long indices, int primcount) {
-        if (Tracy.ENABLED) drawCalls++;
+        drawCalls++;
         if (mode == GL11.GL_QUADS) {
             QuadConverter.drawQuadElementsAsTrianglesInstanced(count, type, indices, primcount);
             return;
@@ -2426,7 +2503,7 @@ public class GLStateManager {
     }
 
     public static void glDrawArraysInstanced(int mode, int first, int count, int primcount) {
-        if (Tracy.ENABLED) drawCalls++;
+        drawCalls++;
         if (mode == GL11.GL_QUADS) {
             QuadConverter.drawQuadsAsTrianglesInstanced(first, count, primcount);
         } else if (mode == GL11.GL_QUAD_STRIP) {
@@ -2476,7 +2553,7 @@ public class GLStateManager {
     }
 
     public static void glDrawArrays(int mode, int first, int count) {
-        if (Tracy.ENABLED) drawCalls++;
+        drawCalls++;
         CommandRecorder savedRecorder = null;
         final RecordMode recordMode = DisplayListManager.getRecordMode();
         if (recordMode != RecordMode.NONE) {
@@ -2981,9 +3058,15 @@ public class GLStateManager {
                 return;
             }
         }
+        if (light >= VertexKey.FFP_LIGHT_COUNT && (warnedFfpLightMask & (1 << light)) == 0 && ShaderManager.getInstance().isEnabled()) {
+            warnedFfpLightMask |= (1 << light);
+            LOGGER.warn("GL_LIGHT{} enabled, but FFP shader emulation implements only GL_LIGHT0..{}", light, VertexKey.FFP_LIGHT_COUNT - 1, new Throwable("call site"));
+        }
         ctx().lightStates[light].enable();
     }
 
+    private static int warnedFfpLightMask = 0;
+
     public static void enableColorMaterial() {
         final RecordMode mode = DisplayListManager.getRecordMode();
         if (mode != RecordMode.NONE) {
@@ -3306,14 +3389,11 @@ public class GLStateManager {
     }
 
     public static boolean isCurrent() {
-        if (BackendManager.RENDER_BACKEND == null) {
-            return Thread.currentThread() == MainThread;
-        }
-        return BackendManager.RENDER_BACKEND.isCurrent();
+        return RENDER_BACKEND.isCurrent();
     }
 
     public static void swapBuffers() throws LWJGLException {
-        if (BackendManager.RENDER_BACKEND != null && BackendManager.RENDER_BACKEND.handleSwapBuffers()) {
+        if (RENDER_BACKEND.handleSwapBuffers()) {
             return;
         }
         Display.swapBuffers();
@@ -3329,7 +3409,14 @@ public class GLStateManager {
             if (processMessages) Display.processMessages();
             return;
         }
+        if (!RENDER_BACKEND.wantsDisplayUpdateGateTiming()) {
+            Display.update(processMessages);
+            return;
+        }
+        final long start = System.nanoTime();
         Display.update(processMessages);
+        final long end = System.nanoTime();
+        RENDER_BACKEND.recordFrameGate(end - start, end);
     }
 
     /**
@@ -4442,7 +4529,10 @@ public class GLStateManager {
         RENDER_BACKEND.readPixels(x, y, width, height, format, type, pixels);
         restorePixelPackBuffer();
     }
-    public static void glTexStorage2D(int target, int levels, int internalFormat, int width, int height) { RENDER_BACKEND.texStorage2D(target, levels, internalFormat, width, height); }
+    public static void glTexStorage2D(int target, int levels, int internalFormat, int width, int height) {
+        RENDER_BACKEND.texStorage2D(target, levels, internalFormat, width, height);
+        TextureInfoCache.INSTANCE.onTexStorage2D(target, internalFormat, width, height);
+    }
     public static void glClearTexImage(int texture, int level, int format, int type, ByteBuffer data) { RENDER_BACKEND.clearTexImage(texture, level, format, type); }
 
     public static int glGenSamplers() { return RENDER_BACKEND.genSamplers(); }
@@ -4971,6 +5061,54 @@ public class GLStateManager {
         RENDER_BACKEND.setVSyncEnabled(enabled);
     }
 
+    public static void setVSyncMode(VSyncMode mode) {
+        RENDER_BACKEND.setVSyncMode(mode);
+    }
+
+    public static void setVSyncPreference(VSyncMode mode) {
+        RENDER_BACKEND.setVSyncPreference(mode);
+    }
+
+    public static boolean supportsVSyncMode(VSyncMode mode) {
+        return RENDER_BACKEND.supportsVSyncMode(mode);
+    }
+
+    public static VSyncMode preferredTearFreeMode() {
+        return RENDER_BACKEND.preferredTearFreeMode();
+    }
+
+    public static String getRenderBackendName() {
+        return RENDER_BACKEND.getName();
+    }
+
+    public static VSyncMode getEffectiveVSyncMode() {
+        return RENDER_BACKEND.getEffectiveVSyncMode();
+    }
+
+    public static int getDisplayRefreshRateHz() {
+        return RENDER_BACKEND.getDisplayRefreshRateHz();
+    }
+
+    public static boolean gateAnchorsNextFrameStart() {
+        return RENDER_BACKEND.gateAnchorsNextFrameStart();
+    }
+
+    public static long lastFrameGateNanos() {
+        return RENDER_BACKEND.lastFrameGateNanos();
+    }
+
+    public static long lastFrameGateEndNanos() {
+        return RENDER_BACKEND.lastFrameGateEndNanos();
+    }
+
+    public static boolean hasSwapchainBackpressure() {
+        return RENDER_BACKEND.hasSwapchainBackpressure();
+    }
+
+    public static void pumpDisplayMessages() {
+        Display.processMessages();
+    }
+
     public static int glGetError() {
         if (!RENDER_BACKEND.hasContext()) return 0;
         if (initConfig.isNoErrorChecks()) return 0;
@@ -5051,6 +5189,7 @@ public class GLStateManager {
         suspendPixelUnpackBuffer();
         RENDER_BACKEND.texSubImage2D(target, level, xoffset, yoffset, width, height, format, type, pixels);
         restorePixelUnpackBuffer();
+        TextureInfoCache.INSTANCE.onTexSubImage2D(target, level);
         maybeGenerateMipmap(target, level);
     }
 
@@ -5066,6 +5205,7 @@ public class GLStateManager {
         suspendPixelUnpackBuffer();
         RENDER_BACKEND.texSubImage2D(target, level, xoffset, yoffset, width, height, format, type, pixels);
         restorePixelUnpackBuffer();
+        TextureInfoCache.INSTANCE.onTexSubImage2D(target, level);
         maybeGenerateMipmap(target, level);
     }
 
@@ -5075,6 +5215,7 @@ public class GLStateManager {
             throw DisplayListManager.unsupportedInList("glTexSubImage2D with buffer offset");
         }
         RENDER_BACKEND.texSubImage2D(target, level, xoffset, yoffset, width, height, format, type, pixels_buffer_offset);
+        TextureInfoCache.INSTANCE.onTexSubImage2D(target, level);
         maybeGenerateMipmap(target, level);
     }
 
@@ -5115,6 +5256,7 @@ public class GLStateManager {
             throw DisplayListManager.unsupportedInList("glCopyTexSubImage2D");
         }
         RENDER_BACKEND.copyTexSubImage2D(target, level, xoffset, yoffset, x, y, width, height);
+        TextureInfoCache.INSTANCE.onTexSubImage2D(target, level);
         maybeGenerateMipmap(target, level);
     }
 

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/GlslTransformUtils.java

@@ -2,8 +2,10 @@ package com.gtnewhorizons.angelica.glsm;
 
 import org.antlr.v4.runtime.BufferedTokenStream;
 import org.antlr.v4.runtime.CharStreams;
+import org.antlr.v4.runtime.CommonToken;
 import org.antlr.v4.runtime.CommonTokenStream;
 import org.antlr.v4.runtime.Token;
+import org.antlr.v4.runtime.WritableToken;
 import org.antlr.v4.runtime.tree.ParseTree;
 import org.antlr.v4.runtime.tree.TerminalNode;
 import org.taumc.glsl.grammar.GLSLLexer;
@@ -88,6 +90,23 @@ public class GlslTransformUtils {
         return source;
     }
 
+    public static void restoreReservedWordsInTree(ParseTree tree) {
+        if (tree instanceof TerminalNode terminal) {
+            final Token token = terminal.getSymbol();
+            final String text = token.getText();
+            if (text != null && text.startsWith(RENAMED_PREFIX) && token instanceof WritableToken writable) {
+                final String rest = text.substring(RENAMED_PREFIX.length());
+                if (rest.startsWith("texture") || rest.startsWith("sample")) {
+                    writable.setText(rest);
+                }
+            }
+            return;
+        }
+        for (int i = 0; i < tree.getChildCount(); i++) {
+            restoreReservedWordsInTree(tree.getChild(i));
+        }
+    }
+
     public record QuietParse(GLSLParser.Translation_unitContext full, GLSLPreParser.Translation_unitContext pre) {}
 
     public static GLSLParser.Translation_unitContext parseFullQuiet(String source) {
@@ -162,21 +181,32 @@ public class GlslTransformUtils {
     public static String getFormattedShader(ParseTree tree, String header) {
         final StringBuilder sb = new StringBuilder(header + "\n");
         final String[] tabHolder = {""};
-        getFormattedShader(tree, sb, tabHolder);
+        getFormattedShader(tree, sb, tabHolder, false);
         return sb.toString();
     }
 
-    private static void getFormattedShader(ParseTree tree, StringBuilder stringBuilder, String[] tabHolder) {
-        if (tree instanceof TerminalNode) {
+    public static String getFormattedShaderRebased(ParseTree tree, String header) {
+        final StringBuilder sb = new StringBuilder(header + "\n");
+        final String[] tabHolder = {""};
+        getFormattedShader(tree, sb, tabHolder, true);
+        return sb.toString();
+    }
+
+    private static void getFormattedShader(ParseTree tree, StringBuilder stringBuilder, String[] tabHolder, boolean rebaseOffsets) {
+        if (tree instanceof TerminalNode terminal) {
             final String text = tree.getText();
             if (text.equals("<EOF>")) {
                 return;
             }
             if (text.equals("#")) {
                 stringBuilder.append("\n#");
+                rebaseAt(terminal, stringBuilder.length() - 1, text, rebaseOffsets);
                 return;
             }
             stringBuilder.append(text);
+            if (!text.equals("}")) {
+                rebaseAt(terminal, stringBuilder.length() - text.length(), text, rebaseOffsets);
+            }
             if (text.equals("{")) {
                 stringBuilder.append(" \n\t");
                 tabHolder[0] = "\t";
@@ -186,6 +216,7 @@ public class GlslTransformUtils {
                 if (stringBuilder.length() >= 2) {
                     stringBuilder.deleteCharAt(stringBuilder.length() - 2);
                 }
+                rebaseAt(terminal, stringBuilder.length() - 1, text, rebaseOffsets);
                 tabHolder[0] = "";
                 stringBuilder.append(" \n");
             } else {
@@ -193,8 +224,17 @@ public class GlslTransformUtils {
             }
         } else {
             for (int i = 0; i < tree.getChildCount(); ++i) {
-                getFormattedShader(tree.getChild(i), stringBuilder, tabHolder);
+                getFormattedShader(tree.getChild(i), stringBuilder, tabHolder, rebaseOffsets);
             }
         }
     }
+
+    private static void rebaseAt(TerminalNode terminal, int startIndex, String text, boolean rebaseOffsets) {
+        if (!rebaseOffsets) return;
+        if (terminal.getSymbol() instanceof CommonToken common) {
+            common.setText(text);
+            common.setStartIndex(startIndex);
+            common.setStopIndex(startIndex + text.length() - 1);
+        }
+    }
 }

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/LTWWorkaround.java

@@ -0,0 +1,34 @@
+package com.gtnewhorizons.angelica.glsm;
+
+import com.gtnewhorizons.angelica.glsm.states.PixelUnpackState;
+import org.lwjgl.BufferUtils;
+import org.lwjgl.opengl.GL11;
+import org.lwjgl.opengl.GL12;
+
+import java.nio.ByteBuffer;
+
+import static com.gtnewhorizons.angelica.glsm.backend.BackendManager.RENDER_BACKEND;
+
+public final class LTWWorkaround {
+
+    private LTWWorkaround() {}
+
+    private static ByteBuffer oneTexel;
+
+    public static boolean isLtwVersionString(String glVersion) {
+        return glVersion != null && glVersion.contains("LTW");
+    }
+
+    public static void onTexImage2D(int target, int level, int format, boolean hasPixels) {
+        if (target != GL11.GL_TEXTURE_2D || level != 0 || format != GL12.GL_BGRA || hasPixels) return;
+        if (oneTexel == null) {
+            oneTexel = BufferUtils.createByteBuffer(4);
+        }
+        oneTexel.clear();
+        GLStateManager.forcePixelUnpackState(PixelUnpackState.DEFAULT);
+        GLStateManager.suspendPixelUnpackBuffer();
+        RENDER_BACKEND.texSubImage2D(target, level, 0, 0, 1, 1, GL11.GL_RGBA, GL11.GL_UNSIGNED_BYTE, oneTexel);
+        GLStateManager.restorePixelUnpackBuffer();
+        GLStateManager.restorePixelUnpackState(PixelUnpackState.DEFAULT);
+    }
+}

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/RenderSystem.java

@@ -1,5 +1,6 @@
 package com.gtnewhorizons.angelica.glsm;
 
+import com.gtnewhorizons.angelica.config.SystemProperties;
 import com.gtnewhorizons.angelica.glsm.backend.BackendManager;
 import com.gtnewhorizons.angelica.glsm.dsa.DSAARB;
 import com.gtnewhorizons.angelica.glsm.dsa.DSAAccess;
@@ -8,6 +9,7 @@ import com.gtnewhorizons.angelica.glsm.dsa.DSAEXT;
 import com.gtnewhorizons.angelica.glsm.dsa.DSAUnsupported;
 import com.gtnewhorizons.angelica.glsm.ffp.ShaderManager;
 import com.gtnewhorizons.angelica.glsm.texture.TextureInfoCache;
+import com.mitchej123.lwjgl.LWJGLServiceProvider;
 import lombok.Getter;
 import org.jetbrains.annotations.Nullable;
 import org.joml.Matrix4f;
@@ -59,6 +61,9 @@ public class RenderSystem {
     private static volatile boolean glesDetected;
     private static volatile boolean hasClipCullDistance;
 
+    private static volatile boolean isLTW;
+    private static volatile boolean ltwDetected;
+
     // Sampler object state tracking (null if unsupported)
     private static int[] samplers;
 
@@ -107,6 +112,13 @@ public class RenderSystem {
 
         BackendManager.init();
 
+        try {
+            // Force init on client thread
+            GLStateManager.LOGGER.info("Celeritas LWJGL service: {}", LWJGLServiceProvider.LWJGL.getClass().getName());
+        } catch (Throwable t) {
+            GLStateManager.LOGGER.debug("Could not resolve the celeritas LWJGL service: {}", t.toString());
+        }
+
         supportsCompute = supportsCompute();
         supportsTesselation = GLStateManager.capabilities.GL_ARB_tessellation_shader || GLStateManager.capabilities.OpenGL40;
 
@@ -403,6 +415,26 @@ public class RenderSystem {
         }
     }
 
+    public static boolean isLTW() {
+        if (!ltwDetected) detectLTW();
+        return isLTW;
+    }
+
+    private static synchronized void detectLTW() {
+        if (ltwDetected) return;
+        if (SystemProperties.DISABLE_LTW_WORKAROUND) {
+            ltwDetected = true;
+            return;
+        }
+        try {
+            final String v = RENDER_BACKEND.getString(GL11.GL_VERSION);
+            if (v == null) return;
+            isLTW = LTWWorkaround.isLtwVersionString(v);
+            ltwDetected = true;
+        } catch (Throwable ignored) {
+        }
+    }
+
     public static boolean supportsSSBO() {
         return supportsSSBO;
     }

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/backend/BackendManager.java

@@ -4,7 +4,6 @@ import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 
 import java.util.Iterator;
-import java.util.ServiceConfigurationError;
 import java.util.ServiceLoader;
 
 public final class BackendManager {
@@ -39,8 +38,8 @@ public final class BackendManager {
                 if (backend.isAvailable() && (best == null || backend.getPriority() > best.getPriority())) {
                     best = backend;
                 }
-            } catch (ServiceConfigurationError | LinkageError e) {
-                LOGGER.debug("Skipping unavailable backend: {}", e.getMessage());
+            } catch (Throwable t) {
+                LOGGER.debug("Skipping unavailable backend: {}", t.getMessage());
             }
         }
 

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/backend/Lwjgl2GLRenderBackend.java

@@ -10,6 +10,7 @@ import org.lwjgl.opengl.ARBDebugOutputCallback;
 import org.lwjgl.opengl.ARBDirectStateAccess;
 import org.lwjgl.opengl.ARBTimerQuery;
 import org.lwjgl.opengl.ContextCapabilities;
+import org.lwjgl.opengl.DisplayMode;
 import org.lwjgl.opengl.EXTDirectStateAccess;
 import org.lwjgl.opengl.EXTShaderImageLoadStore;
 import org.lwjgl.opengl.GLContext;
@@ -114,7 +115,19 @@ public final class Lwjgl2GLRenderBackend extends RenderBackend {
     public int getMinGLSLVersion() {return 330;}
 
     @Override
-    public void setVSyncEnabled(boolean enabled) {Display.setVSyncEnabled(enabled);}
+    protected VSyncMode applyVSyncMode(VSyncMode preferred) {
+        final boolean enabled = preferred.tearFree();
+        Display.setVSyncEnabled(enabled);
+        return enabled ? VSyncMode.ON : VSyncMode.OFF;
+    }
+
+    @Override
+    protected int queryDisplayRefreshRateHz() {
+        final DisplayMode mode = Display.getDisplayMode();
+        if (mode != null && mode.getFrequency() > 0) return mode.getFrequency();
+        final DisplayMode desktop = Display.getDesktopDisplayMode();
+        return desktop == null ? 0 : desktop.getFrequency();
+    }
 
     @Override
     public boolean isAnisotropicSupported() {
@@ -1371,6 +1384,16 @@ public final class Lwjgl2GLRenderBackend extends RenderBackend {
         GL11.glGetFloat(pname, params);
     }
 
+    @Override
+    public double getDouble(int pname) {
+        return GL11.glGetDouble(pname);
+    }
+
+    @Override
+    public void getDouble(int pname, DoubleBuffer params) {
+        GL11.glGetDouble(pname, params);
+    }
+
     @Override
     public boolean getBoolean(int pname) {
         return GL11.glGetBoolean(pname);

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/backend/RenderBackend.java

@@ -5,8 +5,6 @@ import com.gtnewhorizons.angelica.glsm.GLStateManager;
 import com.gtnewhorizons.angelica.glsm.RenderSystem;
 import org.lwjgl.opengl.GL20;
 
-import me.eigenraven.lwjgl3ify.api.SwapchainInvalidatingChange;
-
 import java.nio.ByteBuffer;
 import java.nio.DoubleBuffer;
 import java.nio.FloatBuffer;
@@ -14,13 +12,14 @@ import java.nio.IntBuffer;
 import java.nio.ShortBuffer;
 import java.util.Collections;
 import java.util.List;
+import java.util.function.Predicate;
 
 /**
  * Abstract rendering backend.
  */
 public abstract class RenderBackend {
 
-    public void onPostWindowCreate(long window, boolean debug) {}
+    public void onPostWindowCreate(long window) {}
 
     public abstract void init();
     public abstract void shutdown();
@@ -64,7 +63,77 @@ public abstract class RenderBackend {
     public abstract void flush();
     public abstract void finish();
 
-    public abstract void setVSyncEnabled(boolean enabled);
+    private VSyncMode effectiveVSyncMode = VSyncMode.ON;
+    private VSyncMode preferredTearFreeMode;
+
+    public final void setVSyncEnabled(boolean enabled) {
+        setVSyncMode(enabled ? preferredTearFreeMode() : VSyncMode.OFF);
+    }
+
+    public final void setVSyncMode(VSyncMode preferred) {
+        setVSyncPreference(preferred);
+        publishVSyncMode(applyVSyncMode(preferred));
+    }
+
+    public final void setVSyncPreference(VSyncMode preferred) {
+        if (preferred.tearFree()) preferredTearFreeMode = preferred;
+    }
+
+    public final VSyncMode preferredTearFreeMode() {
+        return resolveTearFreeMode(preferredTearFreeMode, this::supportsVSyncMode);
+    }
+
+    static VSyncMode resolveTearFreeMode(VSyncMode preferred, Predicate<VSyncMode> supported) {
+        if (preferred != null && preferred.tearFree() && supported.test(preferred)) return preferred;
+        return supported.test(VSyncMode.MAILBOX) ? VSyncMode.MAILBOX : VSyncMode.ON;
+    }
+
+    protected abstract VSyncMode applyVSyncMode(VSyncMode preferred);
+
+    public boolean supportsVSyncMode(VSyncMode mode) { return mode != VSyncMode.MAILBOX; }
+
+    protected final void publishVSyncMode(VSyncMode mode) { effectiveVSyncMode = mode; }
+
+    public final VSyncMode getEffectiveVSyncMode() { return effectiveVSyncMode; }
+
+    private static final long REFRESH_POLL_NANOS = 1_000_000_000L;
+
+    private long refreshPollNanos;
+    private int cachedRefreshHz;
+
+    public final int getDisplayRefreshRateHz() {
+        final long now = System.nanoTime();
+        if (refreshPollNanos == 0L || now - refreshPollNanos >= REFRESH_POLL_NANOS) {
+            refreshPollNanos = now;
+            cachedRefreshHz = queryDisplayRefreshRateHz();
+        }
+        return cachedRefreshHz;
+    }
+
+    protected int queryDisplayRefreshRateHz() { return 0; }
+
+    public static int refreshHzFrom(int numerator, int denominator, float fallbackHz) {
+        if (numerator > 0 && denominator > 0) return (numerator + denominator - 1) / denominator;
+        return fallbackHz > 0.0f ? (int) Math.ceil(fallbackHz) : 0;
+    }
+
+    public boolean hasSwapchainBackpressure() { return false; }
+
+    private long frameGateNanos;
+    private long frameGateEndNanos;
+
+    public boolean gateAnchorsNextFrameStart() { return false; }
+
+    public boolean wantsDisplayUpdateGateTiming() { return true; }
+
+    public void recordFrameGate(long durationNanos, long endNanos) {
+        frameGateNanos = durationNanos;
+        frameGateEndNanos = endNanos;
+    }
+
+    public long lastFrameGateNanos() { return frameGateNanos; }
+
+    public long lastFrameGateEndNanos() { return frameGateEndNanos; }
 
     public void onFrameBegin() {
         if (GLStateManager.takeStateSeedPending()) {
@@ -75,7 +144,7 @@ public abstract class RenderBackend {
     public void onFrameEnd() {}
 
     /** Fired by lwjgl3ify Display before a mutation that recreates the swapchain. */
-    public void onPreSwapchainInvalidatingChange(SwapchainInvalidatingChange change) {}
+    public void onPreSwapchainInvalidatingChange(Object change) {}
 
     public boolean handleMakeCurrent(Object drawable) { return false; }
     public boolean handleReleaseContext(Object drawable) { return false; }
@@ -84,6 +153,11 @@ public abstract class RenderBackend {
 
     public String getTransferDebugInfo() { return null; }
 
+    public boolean bindVoxelizationRegion(int ssboBinding, int vertexBufferGlId, long openPass, float x, float y, float z) { return false; }
+    public long beginVoxelizationBatch(int ssboBinding) { return 0L; }
+    public void voxelizeRange(long pass, int vertexOffset, int vertexCount) {}
+    public void endVoxelizationBatch(long pass) {}
+
     public abstract void enable(int cap);
     public abstract void enablei(int cap, int index);
     public abstract void disable(int cap);
@@ -389,6 +463,8 @@ public abstract class RenderBackend {
     public void getInteger(int pname, int[] params) { if (params.length > 0) params[0] = getInteger(pname); }
     public abstract float getFloat(int pname);
     public abstract void getFloat(int pname, FloatBuffer params);
+    public double getDouble(int pname) { return getFloat(pname); }
+    public void getDouble(int pname, DoubleBuffer params) { if (params.remaining() > 0) params.put(params.position(), getDouble(pname)); }
     public abstract boolean getBoolean(int pname);
     public abstract void getBoolean(int pname, ByteBuffer params);
     public abstract String getString(int pname);

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/backend/VSyncMode.java

@@ -0,0 +1,11 @@
+package com.gtnewhorizons.angelica.glsm.backend;
+
+public enum VSyncMode {
+    OFF,
+    ON,
+    MAILBOX;
+
+    public boolean tearFree() {
+        return this != OFF;
+    }
+}

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/ffp/FFPVertexLighting.java

@@ -0,0 +1,83 @@
+package com.gtnewhorizons.angelica.glsm.ffp;
+
+import com.gtnewhorizons.angelica.glsm.GLStateManager;
+import com.gtnewhorizons.angelica.glsm.states.LightState;
+import com.gtnewhorizons.angelica.glsm.states.MaterialState;
+import org.joml.Matrix3f;
+import org.joml.Vector3f;
+import org.joml.Vector4f;
+
+public final class FFPVertexLighting {
+
+    private static final Vector3f scratchNormal = new Vector3f();
+    private static final Vector3f scratchLightVec = new Vector3f();
+    private static final Vector4f scratchEyePos = new Vector4f();
+    private static final Matrix3f scratchNormalMat = new Matrix3f();
+    private static final Vector3f scratchVec = new Vector3f();
+
+    private FFPVertexLighting() {}
+
+    public static boolean modulatesVertexColor(Vector3f destFactor) {
+        destFactor.set(1.0f);
+
+        if (!GLStateManager.getLightingState().isEnabled()) return false;
+        if (!GLStateManager.getColorMaterial().isEnabled()) return false;
+        if (VertexKey.encodeColorMaterialMode(GLStateManager.getColorMaterialParameter().getValue()) != VertexKey.CM_AMBIENT_AND_DIFFUSE) return false;
+
+        final MaterialState material = GLStateManager.getFrontMaterial();
+        if (material.emission.x != 0.0f || material.emission.y != 0.0f || material.emission.z != 0.0f)
+            return false;
+
+        final boolean materialHasSpecular = material.shininess > 0.0f && (material.specular.x != 0.0f || material.specular.y != 0.0f || material.specular.z != 0.0f);
+
+        final Vector4f lightModelAmbient = GLStateManager.getLightModel().ambient;
+        float r = lightModelAmbient.x;
+        float g = lightModelAmbient.y;
+        float b = lightModelAmbient.z;
+
+        final var lightEnables = GLStateManager.getLightStates();
+        final var lightData = GLStateManager.getLightDataStates();
+        boolean normalReady = false;
+
+        for (int i = 0; i < VertexKey.FFP_LIGHT_COUNT; i++) {
+            if (!lightEnables[i].isEnabled()) continue;
+            final LightState light = lightData[i];
+            if (materialHasSpecular && (light.specular.x != 0.0f || light.specular.y != 0.0f || light.specular.z != 0.0f))
+                return false;
+            if (!normalReady) {
+                transformCurrentNormal();
+                normalReady = true;
+            }
+            final float nDotVP = Math.max(scratchNormal.dot(lightDirection(light)), 0.0f);
+            r += light.ambient.x + nDotVP * light.diffuse.x;
+            g += light.ambient.y + nDotVP * light.diffuse.y;
+            b += light.ambient.z + nDotVP * light.diffuse.z;
+        }
+
+        if (r == 1.0f && g == 1.0f && b == 1.0f) return false;
+        if (!Float.isFinite(r + g + b)) return false;
+        destFactor.set(r, g, b);
+        return true;
+    }
+
+    private static void transformCurrentNormal() {
+        GLStateManager.getModelViewMatrix().normal(scratchNormalMat);
+        scratchNormal.set(ShaderManager.getCurrentNormal());
+        scratchNormalMat.transform(scratchNormal);
+        if (GLStateManager.getNormalizeState().isEnabled()) {
+            scratchNormal.normalize();
+        } else if (GLStateManager.getRescaleNormalState().isEnabled()) {
+            scratchNormal.mul(Uniforms.rescaleFactor(scratchNormalMat, scratchVec));
+        }
+    }
+
+    private static Vector3f lightDirection(LightState light) {
+        if (light.position.w == 0.0f) {
+            scratchLightVec.set(light.position.x, light.position.y, light.position.z);
+        } else {
+            scratchEyePos.set(0.0f, 0.0f, 0.0f, 1.0f).mul(GLStateManager.getModelViewMatrix());
+            scratchLightVec.set(light.position.x - scratchEyePos.x, light.position.y - scratchEyePos.y, light.position.z - scratchEyePos.z);
+        }
+        return scratchLightVec.normalize();
+    }
+}

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/ffp/Uniforms.java

@@ -232,8 +232,12 @@ public class Uniforms {
     private void stageNormalMatrix() {
         GLStateManager.getModelViewMatrix().normal(normalMatrix);
         putMat3(FFPUniformBlock.NORMAL_MATRIX, normalMatrix);
-        final float scale = 1.0f / normalMatrix.getColumn(0, tempVec3).length();
-        putFloat(FFPUniformBlock.NORMAL_SCALE, scale);
+        putFloat(FFPUniformBlock.NORMAL_SCALE, rescaleFactor(normalMatrix, tempVec3));
+    }
+
+    static float rescaleFactor(Matrix3f normalMatrix, Vector3f scratch) {
+        final float f = normalMatrix.getColumn(2, scratch).lengthSquared();
+        return f > 1.0e-12f ? 1.0f / (float) Math.sqrt(f) : 1.0f;
     }
 
     private void stageTextureMatrices() {

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/ffp/VertexKey.java

@@ -20,38 +20,36 @@ public final class VertexKey {
 
     public static final int MAX_UNITS = 4;
 
+    public static final int FFP_LIGHT_COUNT = 2;
+
     private final long packed;
 
     private static final int BIT_LIGHTING            = 0;
-    private static final int BIT_LIGHT0              = 1;
-    private static final int BIT_LIGHT1              = 2;
-    private static final int BIT_LIGHT0_DIR          = 3;
-    private static final int BIT_LIGHT1_DIR          = 4;
-    private static final int BIT_COLOR_MATERIAL      = 5;
-    private static final int BIT_SEPARATE_SPECULAR   = 6;
-    private static final int BIT_FOG                 = 7;
-    private static final int BIT_FOG_DIST_MODE       = 8;  // 2 bits: 8-9
-    private static final int BIT_NORMALIZE           = 10;
-    private static final int BIT_RESCALE_NORMAL      = 11;
-    // Per-unit texcoord enable: bits 12-15 (unit 0..3). Unit 1 doubles as the lightmap flag.
-    private static final int BIT_UNIT_TEX_BASE       = 12;
-    private static final int BIT_HAS_VERTEX_COLOR    = 16;
-    private static final int BIT_HAS_VERTEX_NORMAL   = 17;
-    private static final int BIT_HAS_VERTEX_TEX      = 18;
-    private static final int BIT_HAS_VERTEX_LIGHTMAP = 19;
-    private static final int BIT_COLOR_MAT_MODE      = 20;  // 3 bits: 20-22
-    // TexGen modes (unit 0 only, for now): 3 bits each (0=NONE, 1=OBJ_LINEAR, 2=EYE_LINEAR).
-    private static final int BIT_TEXGEN_S            = 23;  // 3 bits: 23-25
-    private static final int BIT_TEXGEN_T            = 26;  // 3 bits: 26-28
-    private static final int BIT_TEXGEN_R            = 29;  // 3 bits: 29-31
-    private static final int BIT_TEXGEN_Q            = 32;  // 3 bits: 32-34
-    private static final int BIT_CLIP_PLANES         = 35;
-    private static final int BIT_WIDE_LINE           = 36;
-    // Per-unit texmat enable: bits 37-40 (unit 0..3). Unit 1 is the lightmap matrix.
-    private static final int BIT_UNIT_TEXMAT_BASE    = 37;
-    private static final int BIT_UNIT23_UV_FROM_UNIT0 = 41;
-    private static final int BIT_LINE_STIPPLE        = 42;
-    private static final int BIT_INSTANCED           = 44;
+    private static final int BIT_LIGHT_BASE          = BIT_LIGHTING + 1;
+    private static final int BIT_LIGHT_DIR_BASE      = BIT_LIGHT_BASE + FFP_LIGHT_COUNT;
+    private static final int BIT_COLOR_MATERIAL      = BIT_LIGHT_DIR_BASE + FFP_LIGHT_COUNT;
+    private static final int BIT_SEPARATE_SPECULAR   = BIT_COLOR_MATERIAL + 1;
+    private static final int BIT_FOG                 = BIT_SEPARATE_SPECULAR + 1;
+    private static final int BIT_FOG_DIST_MODE       = BIT_FOG + 1;
+    private static final int BIT_NORMALIZE           = BIT_FOG_DIST_MODE + 2;
+    private static final int BIT_RESCALE_NORMAL      = BIT_NORMALIZE + 1;
+    private static final int BIT_UNIT_TEX_BASE       = BIT_RESCALE_NORMAL + 1;
+    private static final int BIT_HAS_VERTEX_COLOR    = BIT_UNIT_TEX_BASE + MAX_UNITS;
+    private static final int BIT_HAS_VERTEX_NORMAL   = BIT_HAS_VERTEX_COLOR + 1;
+    private static final int BIT_HAS_VERTEX_TEX      = BIT_HAS_VERTEX_NORMAL + 1;
+    private static final int BIT_HAS_VERTEX_LIGHTMAP = BIT_HAS_VERTEX_TEX + 1;
+    private static final int BIT_COLOR_MAT_MODE      = BIT_HAS_VERTEX_LIGHTMAP + 1;
+    // TexGen modes are unit 0 only, for now.
+    private static final int BIT_TEXGEN_S            = BIT_COLOR_MAT_MODE + 3;
+    private static final int BIT_TEXGEN_T            = BIT_TEXGEN_S + 3;
+    private static final int BIT_TEXGEN_R            = BIT_TEXGEN_T + 3;
+    private static final int BIT_TEXGEN_Q            = BIT_TEXGEN_R + 3;
+    private static final int BIT_CLIP_PLANES         = BIT_TEXGEN_Q + 3;
+    private static final int BIT_WIDE_LINE           = BIT_CLIP_PLANES + 1;
+    private static final int BIT_UNIT_TEXMAT_BASE    = BIT_WIDE_LINE + 1;
+    private static final int BIT_UNIT23_UV_FROM_UNIT0 = BIT_UNIT_TEXMAT_BASE + MAX_UNITS;
+    private static final int BIT_LINE_STIPPLE        = BIT_UNIT23_UV_FROM_UNIT0 + 1;
+    private static final int BIT_INSTANCED           = BIT_LINE_STIPPLE + 1;
 
     public static final int TG_NONE                  = 0;
     public static final int TG_OBJ_LINEAR            = 1;
@@ -70,10 +68,8 @@ public final class VertexKey {
     public long pack() { return packed; }
 
     public boolean lightingEnabled()       { return bit(BIT_LIGHTING); }
-    public boolean light0Enabled()         { return bit(BIT_LIGHT0); }
-    public boolean light1Enabled()         { return bit(BIT_LIGHT1); }
-    public boolean light0Directional()     { return bit(BIT_LIGHT0_DIR); }
-    public boolean light1Directional()     { return bit(BIT_LIGHT1_DIR); }
+    public boolean lightEnabled(int light)     { return bit(BIT_LIGHT_BASE + light); }
+    public boolean lightDirectional(int light) { return bit(BIT_LIGHT_DIR_BASE + light); }
     public boolean colorMaterialEnabled()  { return bit(BIT_COLOR_MATERIAL); }
     public boolean separateSpecular()      { return bit(BIT_SEPARATE_SPECULAR); }
     public boolean fogEnabled()            { return bit(BIT_FOG); }
@@ -136,17 +132,12 @@ public final class VertexKey {
         if (lighting) {
             bits |= (1L << BIT_LIGHTING);
 
-            if (GLStateManager.getLightStates()[0].isEnabled()) {
-                bits |= (1L << BIT_LIGHT0);
+            for (int i = 0; i < FFP_LIGHT_COUNT; i++) {
+                if (!GLStateManager.getLightStates()[i].isEnabled()) continue;
+                bits |= (1L << (BIT_LIGHT_BASE + i));
                 // position.w == 0 means directional
-                if (GLStateManager.getLightDataStates()[0].position.w == 0.0f) {
-                    bits |= (1L << BIT_LIGHT0_DIR);
-                }
-            }
-            if (GLStateManager.getLightStates()[1].isEnabled()) {
-                bits |= (1L << BIT_LIGHT1);
-                if (GLStateManager.getLightDataStates()[1].position.w == 0.0f) {
-                    bits |= (1L << BIT_LIGHT1_DIR);
+                if (GLStateManager.getLightDataStates()[i].position.w == 0.0f) {
+                    bits |= (1L << (BIT_LIGHT_DIR_BASE + i));
                 }
             }
 
@@ -265,7 +256,7 @@ public final class VertexKey {
     @Override
     public String toString() {
         return String.format("FFPVertexKey[0x%011X: lit=%b l0=%b l1=%b cm=%b fog=%b tex=%d%d%d%d texmat=%d%d%d%d col=%b nrm=%b vtex=%b vlm=%b tg=%d/%d/%d/%d clip=%b wline=%b inst=%b]",
-            packed, lightingEnabled(), light0Enabled(), light1Enabled(),
+            packed, lightingEnabled(), lightEnabled(0), lightEnabled(1),
             colorMaterialEnabled(), fogEnabled(),
             unitTexCoordEnabled(0)?1:0, unitTexCoordEnabled(1)?1:0, unitTexCoordEnabled(2)?1:0, unitTexCoordEnabled(3)?1:0,
             unitTexMatEnabled(0)?1:0, unitTexMatEnabled(1)?1:0, unitTexMatEnabled(2)?1:0, unitTexMatEnabled(3)?1:0,

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/ffp/VertexShaderGenerator.java

@@ -182,11 +182,10 @@ public final class VertexShaderGenerator {
         }
 
         // Per-light accumulation
-        if (key.light0Enabled()) {
-            emitLightContribution(sb, key, 0);
-        }
-        if (key.light1Enabled()) {
-            emitLightContribution(sb, key, 1);
+        for (int i = 0; i < VertexKey.FFP_LIGHT_COUNT; i++) {
+            if (key.lightEnabled(i)) {
+                emitLightContribution(sb, key, i);
+            }
         }
 
         sb.append("  v_Color = vec4(clamp(color0, 0.0, 1.0), outAlpha);\n");
@@ -198,7 +197,7 @@ public final class VertexShaderGenerator {
 
     private static void emitLightContribution(StringBuilder sb, VertexKey key, int lightIndex) {
         final String li = String.valueOf(lightIndex);
-        final boolean directional = (lightIndex == 0) ? key.light0Directional() : key.light1Directional();
+        final boolean directional = key.lightDirectional(lightIndex);
         final String posUniform = "u_Light" + li + "Position";
 
         sb.append("  { // Light ").append(li).append('\n');

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/hooks/ShaderTransformPostProcessor.java

@@ -1,8 +1,13 @@
 package com.gtnewhorizons.angelica.glsm.hooks;
 
 import com.gtnewhorizons.angelica.glsm.shader.ShaderType;
+import org.taumc.glsl.grammar.GLSLParser;
 
 @FunctionalInterface
 public interface ShaderTransformPostProcessor {
     void onTransformed(String transformedSource, ShaderType shaderType);
+
+    default void onTransformed(String transformedSource, GLSLParser.Translation_unitContext bodyTree, int headerLen, ShaderType shaderType) {
+        onTransformed(transformedSource, shaderType);
+    }
 }

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/loading/EcosystemNarrowRules.java

@@ -21,11 +21,11 @@ public final class EcosystemNarrowRules {
             "Reika.DragonAPI.ASM.StructureLootHooks"
         )),
 
-        new NarrowRule("Xaeros_common", "xaero.common.core", List.of(
+        new NarrowRule("Xaeros", "xaero.common.core", List.of(
             "xaero.common.core.transformer"
         )),
 
-        new NarrowRule("Xaeros_map", "xaero.map.core", List.of(
+        new NarrowRule("Xaeros", "xaero.map.core", List.of(
             "xaero.map.core.transformer"
         )),
 
@@ -78,6 +78,13 @@ public final class EcosystemNarrowRules {
             "alfheim.common.core.asm.hook.fixes.CorporeaInputFix",
             "alfheim.common.core.asm.hook.fixes.GodAttributesHooks",
             "alfheim.common.core.asm.hook.fixes.RecipeAncientWillsFix"
+        )),
+
+        new NarrowRule("LegendsMod", "com.tihyo.legends.management.asm", List.of(
+            "com.tihyo.legends.management.asm.LegendsLoadingPlugin",
+            "com.tihyo.legends.management.asm.AbstractTransformer",
+            "com.tihyo.legends.management.asm.ASMHelper",
+            "com.tihyo.legends.management.asm.Transformer"
         ))
     );
 

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/loading/TransformerNarrower.java

@@ -25,7 +25,7 @@ public final class TransformerNarrower {
 
     /**
      * A rule that replaces a broad transformer exclusion with narrower ones.
-     * @param name       Human-readable name for logging (e.g. "DragonAPI")
+     * @param name       Blackboard/config key suffix. (e.g. "DragonAPI").
      * @param broad      The broad exclusion to remove (e.g. "Reika.DragonAPI.ASM")
      * @param narrow     Narrower exclusions to add in its place
      */

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/redirect/GLSMRedirector.java

@@ -162,6 +162,7 @@ public class GLSMRedirector {
     private static final String EXTGpuShader4 = "org/lwjgl/opengl/EXTGpuShader4";
     private static final String EXTGPUShader4 = "org/lwjgl/opengl/EXTGPUShader4";
     private static final String ARBTimerQuery = "org/lwjgl/opengl/ARBTimerQuery";
+    private static final String EXTTimerQuery = "org/lwjgl/opengl/EXTTimerQuery";
 
     // Redirect VAO related calls from NHLib
     private static final String UniversalVAO = "com/gtnewhorizon/gtnhlib/client/opengl/UniversalVAO";
@@ -236,6 +237,9 @@ public class GLSMRedirector {
             .add("glFogi")
             .add("glFrustum")
             .add("glGetBoolean")
+            .add("glGetClipPlane")
+            .add("glGetDouble")
+            .add("glGetDoublev", "glGetDouble")
             .add("glGetFloat")
             .add("glGetFloatv", "glGetFloat")
             .add("glGetInteger")
@@ -629,6 +633,10 @@ public class GLSMRedirector {
             .add("glQueryCounter")
             .add("glGetQueryObjectui64")
         );
+        methodRedirects.put(EXTTimerQuery, RedirectMap.newMap()
+            .add("glGetQueryObjectuEXT", "glGetQueryObjectui64")
+            .add("glGetQueryObjectui64EXT", "glGetQueryObjectui64")
+        );
 
         glDescRedirects.put("org/lwjgl/opengl/GL32C glFenceSync(II)J", "glFenceSync");
         glDescRedirects.put("org/lwjgl/opengl/GL32C glClientWaitSync(JIJ)I", "glClientWaitSync");

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/shader/GlslVulkanPreprocess.java

@@ -100,7 +100,7 @@ public final class GlslVulkanPreprocess {
         return out;
     }
 
-    public record Metadata(Set<String> boolUniforms, Set<String> explicitVsInputs) {}
+    public record Metadata(Set<String> boolUniforms, Set<String> explicitVsInputs, boolean needsSamplerless) {}
 
     public static Metadata collectEdits(String source, GLSLParser.Translation_unitContext root, int glShaderType, String debugName, boolean separateReadOnlyImages, List<Edit> edits) {
         final boolean isVertex = glShaderType == GL20.GL_VERTEX_SHADER;
@@ -216,7 +216,7 @@ public final class GlslVulkanPreprocess {
             }
         }, root);
 
-        if (needsSamplerless[0]) {
+        if (needsSamplerless[0] && source != null) {
             final int at = versionDirectiveEnd(source);
             if (at >= 0) edits.add(new Edit(at, at - 1, "\n" + SAMPLERLESS_EXTENSION));
         }
@@ -234,7 +234,7 @@ public final class GlslVulkanPreprocess {
             }
         }
 
-        return new Metadata(bools, explicitInputs);
+        return new Metadata(bools, explicitInputs, needsSamplerless[0]);
     }
 
     public static void clearCache() {

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/states/ClipPlaneState.java

@@ -4,6 +4,7 @@ import com.gtnewhorizons.angelica.glsm.GLStateManager;
 import org.joml.Matrix4f;
 import org.joml.Vector4f;
 
+import java.nio.DoubleBuffer;
 import java.nio.FloatBuffer;
 
 /**
@@ -31,4 +32,10 @@ public class ClipPlaneState {
         final float[] p = eyePlanes[index];
         buf.put(p[0]).put(p[1]).put(p[2]).put(p[3]);
     }
+
+    public void getEyePlane(int index, DoubleBuffer buf) {
+        final float[] p = eyePlanes[index];
+        final int pos = buf.position();
+        buf.put(pos, p[0]).put(pos + 1, p[1]).put(pos + 2, p[2]).put(pos + 3, p[3]);
+    }
 }

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/texture/TextureInfo.java

@@ -36,6 +36,12 @@ public class TextureInfo {
 
     @Getter @Setter protected boolean generateMipmap = false;
 
+    @Getter protected int uploadGeneration;
+
+    void bumpUploadGeneration() {
+        uploadGeneration++;
+    }
+
     protected TextureInfo(int id) {
         this.id = id;
     }

glsm/src/main/java/com/gtnewhorizons/angelica/glsm/texture/TextureInfoCache.java

@@ -53,6 +53,7 @@ public class TextureInfoCache {
             info.resolvedInternalFormat = isGenericCompressedInternalFormat(internalformat) ? -1 : internalformat;
             info.width = width;
             info.height = height;
+            info.bumpUploadGeneration();
         }
     }
 
@@ -65,9 +66,29 @@ public class TextureInfoCache {
             info.resolvedInternalFormat = isGenericCompressedInternalFormat(internalformat) ? -1 : internalformat;
             info.width = width;
             info.height = height;
+            info.bumpUploadGeneration();
         }
     }
 
+    public void onTexStorage2D(int target, int internalformat, int width, int height) {
+        if (!isTrackedTarget(target)) return;
+        final TextureInfo info = getInfo(GLStateManager.getBoundTextureForServerState());
+        if (info == null) return;
+        info.setTarget(target);
+        info.internalFormat = internalformat;
+        info.resolvedInternalFormat = isGenericCompressedInternalFormat(internalformat) ? -1 : internalformat;
+        info.width = width;
+        info.height = height;
+        info.bumpUploadGeneration();
+    }
+
+    public void onTexSubImage2D(int target, int level) {
+        if (!isTrackedTarget(target) || level != 0) return;
+        final TextureInfo info = getInfo(GLStateManager.getBoundTextureForServerState());
+        if (info == null) return;
+        info.bumpUploadGeneration();
+    }
+
     public static boolean isGenericCompressedInternalFormat(int internalFormat) {
         return switch (internalFormat) {
             case GL30.GL_COMPRESSED_RED,

glsm/src/test/java/com/gtnewhorizons/angelica/glsm/GLSM_DisplayList_RawTessellatorTransform_Test.java

@@ -0,0 +1,153 @@
+package com.gtnewhorizons.angelica.glsm;
+
+import com.gtnewhorizon.gtnhlib.client.renderer.TessellatorManager;
+import com.gtnewhorizons.angelica.glsm.recording.CompiledDisplayList;
+import com.gtnewhorizons.angelica.glsm.recording.GLCommand;
+import it.unimi.dsi.fastutil.ints.IntList;
+import net.minecraft.client.renderer.Tessellator;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.lwjgl.opengl.GL11;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+@GLCoreTest
+class GLSM_DisplayList_RawTessellatorTransform_Test {
+
+    private int testList = -1;
+
+    @AfterEach
+    void cleanup() {
+        if (testList > 0) {
+            GLStateManager.glDeleteLists(testList, 1);
+            testList = -1;
+        }
+        GLStateManager.glLoadIdentity();
+    }
+
+    private static void rawQuad(float size) {
+        final Tessellator tess = Tessellator.instance;
+        final float[][] corners = { { 0.0f, 0.0f }, { size, 0.0f }, { size, size }, { 0.0f, size } };
+        tess.rawBuffer = new int[4 * 8];
+        for (int i = 0; i < 4; i++) {
+            final int base = i * 8;
+            tess.rawBuffer[base] = Float.floatToRawIntBits(corners[i][0]);
+            tess.rawBuffer[base + 1] = Float.floatToRawIntBits(corners[i][1]);
+            tess.rawBuffer[base + 3] = Float.floatToRawIntBits(i == 1 || i == 2 ? 1.0f : 0.0f);
+            tess.rawBuffer[base + 4] = Float.floatToRawIntBits(i >= 2 ? 1.0f : 0.0f);
+        }
+        tess.isDrawing = true;
+        tess.drawMode = GL11.GL_QUADS;
+        tess.hasTexture = true;
+        tess.rawBufferIndex = 4 * 8;
+        tess.vertexCount = 4;
+        TessellatorManager.interceptDraw(tess);
+    }
+
+    private static void immediateQuad(float size) {
+        GLStateManager.glBegin(GL11.GL_QUADS);
+        GLStateManager.glVertex3f(0.0f, 0.0f, 0.0f);
+        GLStateManager.glVertex3f(size, 0.0f, 0.0f);
+        GLStateManager.glVertex3f(size, size, 0.0f);
+        GLStateManager.glVertex3f(0.0f, size, 0.0f);
+        GLStateManager.glEnd();
+    }
+
+    @Test
+    void pendingTransformIsEmittedBeforeARawDraw() {
+        testList = GLStateManager.glGenLists(1);
+        GLStateManager.glNewList(testList, GL11.GL_COMPILE);
+
+        GLStateManager.glScalef(0.5f, 0.5f, 0.5f);
+        rawQuad(1.0f);
+
+        GLStateManager.glEndList();
+
+        final CompiledDisplayList compiled = DisplayListManager.getDisplayList(testList);
+        assertNotNull(compiled);
+
+        final IntList opcodes = compiled.getCommandOpcodes();
+        final int scaleIndex = opcodes.indexOf(GLCommand.SCALE);
+        final int drawIndex = opcodes.indexOf(GLCommand.DRAW_RANGE);
+
+        assertTrue(scaleIndex >= 0, "The pending scale must be recorded");
+        assertTrue(drawIndex >= 0, "The raw draw must be recorded");
+        assertTrue(scaleIndex < drawIndex, "Scale must be emitted before the draw it applies to");
+        assertEquals(1, compiled.getCommandCounts().getOrDefault(GLCommand.SCALE, 0), "Scale emitted once, not again by the end-of-list flush");
+    }
+
+    @Test
+    void pendingTransformIsNotEmittedBeforeABakedDraw() {
+        testList = GLStateManager.glGenLists(1);
+        GLStateManager.glNewList(testList, GL11.GL_COMPILE);
+
+        GLStateManager.glScalef(0.5f, 0.5f, 0.5f);
+        immediateQuad(1.0f);
+
+        GLStateManager.glEndList();
+
+        final CompiledDisplayList compiled = DisplayListManager.getDisplayList(testList);
+        assertNotNull(compiled);
+
+        final IntList opcodes = compiled.getCommandOpcodes();
+        final int scaleIndex = opcodes.indexOf(GLCommand.SCALE);
+        final int drawIndex = opcodes.indexOf(GLCommand.DRAW_RANGE);
+
+        assertTrue(drawIndex >= 0, "The immediate mode draw must be recorded");
+        assertTrue(scaleIndex < 0 || drawIndex < scaleIndex, "Baked geometry must draw before the delta reaches the stream");
+    }
+
+    @Test
+    void aRawDrawAfterABakedDrawStillGetsTheTransform() {
+        testList = GLStateManager.glGenLists(1);
+        GLStateManager.glNewList(testList, GL11.GL_COMPILE);
+
+        GLStateManager.glScalef(0.5f, 0.5f, 0.5f);
+        immediateQuad(1.0f);
+        rawQuad(1.0f);
+
+        GLStateManager.glEndList();
+
+        final CompiledDisplayList compiled = DisplayListManager.getDisplayList(testList);
+        assertNotNull(compiled);
+
+        final IntList opcodes = compiled.getCommandOpcodes();
+        final int scaleIndex = opcodes.indexOf(GLCommand.SCALE);
+        final int lastDrawIndex = opcodes.lastIndexOf(GLCommand.DRAW_RANGE);
+        final int firstDrawIndex = opcodes.indexOf(GLCommand.DRAW_RANGE);
+
+        assertTrue(scaleIndex >= 0, "The pending scale must be recorded");
+        assertTrue(firstDrawIndex < scaleIndex, "The baked draw stays ahead of the transform");
+        assertTrue(scaleIndex < lastDrawIndex, "The raw draw still gets the transform");
+    }
+
+    @Test
+    void aRawDrawDoesNotFlushWhileBakedGeometryIsPending() {
+        testList = GLStateManager.glGenLists(1);
+        GLStateManager.glNewList(testList, GL11.GL_COMPILE);
+
+        GLStateManager.glScalef(0.5f, 0.5f, 0.5f);
+        GLStateManager.glBegin(GL11.GL_QUADS);
+        GLStateManager.glVertex3f(0.0f, 0.0f, 0.0f);
+        GLStateManager.glVertex3f(1.0f, 0.0f, 0.0f);
+        GLStateManager.glVertex3f(1.0f, 1.0f, 0.0f);
+        GLStateManager.glVertex3f(0.0f, 1.0f, 0.0f);
+
+        rawQuad(1.0f);
+
+        GLStateManager.glEnd();
+        GLStateManager.glEndList();
+
+        final CompiledDisplayList compiled = DisplayListManager.getDisplayList(testList);
+        assertNotNull(compiled);
+
+        final IntList opcodes = compiled.getCommandOpcodes();
+        final int scaleIndex = opcodes.indexOf(GLCommand.SCALE);
+        final int drawIndex = opcodes.indexOf(GLCommand.DRAW_RANGE);
+
+        assertTrue(drawIndex >= 0, "Draws must be recorded");
+        assertTrue(scaleIndex < 0 || drawIndex < scaleIndex, "No flush while baked geometry is pending");
+    }
+}

glsm/src/test/java/com/gtnewhorizons/angelica/glsm/GLSM_DisplayList_TransformCollapsing_Test.java

@@ -1,7 +1,9 @@
 package com.gtnewhorizons.angelica.glsm;
 
+import com.gtnewhorizon.gtnhlib.client.renderer.TessellatorManager;
 import com.gtnewhorizons.angelica.glsm.recording.CompiledDisplayList;
 import com.gtnewhorizons.angelica.glsm.recording.GLCommand;
+import net.minecraft.client.renderer.Tessellator;
 import it.unimi.dsi.fastutil.ints.Int2IntMap;
 import it.unimi.dsi.fastutil.ints.IntList;
 import org.joml.Matrix4f;
@@ -837,6 +839,47 @@ class GLSM_DisplayList_TransformCollapsing_Test {
         }
     }
 
+    @Test
+    void testRawTessellatorDrawPlaysBackWithTheTransform() {
+        testList = GL11.glGenLists(1);
+        GLStateManager.glNewList(testList, GL11.GL_COMPILE);
+
+        GLStateManager.glScalef(0.5f, 0.5f, 0.5f);
+
+        final Tessellator tess = Tessellator.instance;
+        final float[][] corners = { { 0.0f, 0.0f }, { 1.0f, 0.0f }, { 1.0f, 1.0f }, { 0.0f, 1.0f } };
+        tess.rawBuffer = new int[4 * 8];
+        for (int i = 0; i < 4; i++) {
+            final int base = i * 8;
+            tess.rawBuffer[base] = Float.floatToRawIntBits(corners[i][0]);
+            tess.rawBuffer[base + 1] = Float.floatToRawIntBits(corners[i][1]);
+            tess.rawBuffer[base + 3] = Float.floatToRawIntBits(i == 1 || i == 2 ? 1.0f : 0.0f);
+            tess.rawBuffer[base + 4] = Float.floatToRawIntBits(i >= 2 ? 1.0f : 0.0f);
+        }
+        tess.isDrawing = true;
+        tess.drawMode = GL11.GL_QUADS;
+        tess.hasTexture = true;
+        tess.rawBufferIndex = 4 * 8;
+        tess.vertexCount = 4;
+        TessellatorManager.interceptDraw(tess);
+
+        GLStateManager.glEndList();
+
+        CompiledDisplayList compiled = DisplayListManager.getDisplayList(testList);
+        assertNotNull(compiled);
+
+        GLStateManager.glPushMatrix();
+        GLStateManager.glLoadIdentity();
+        GLStateManager.glCallList(testList);
+
+        FloatBuffer matrixBuf = BufferUtils.createFloatBuffer(16);
+        GLStateManager.glGetFloat(GL11.GL_MODELVIEW_MATRIX, matrixBuf);
+        assertEquals(0.5f, matrixBuf.get(0), 0.0001f, "Scale X after playback");
+        assertEquals(0.5f, matrixBuf.get(5), 0.0001f, "Scale Y after playback");
+
+        GLStateManager.glPopMatrix();
+    }
+
     // ==================== Optimizer Push/Pop Reset Tests ====================
 
     @Test

glsm/src/test/java/com/gtnewhorizons/angelica/glsm/GLSM_TextureUploadGeneration_GLTest.java

@@ -0,0 +1,71 @@
+package com.gtnewhorizons.angelica.glsm;
+
+import com.gtnewhorizons.angelica.glsm.texture.TextureInfo;
+import com.gtnewhorizons.angelica.glsm.texture.TextureInfoCache;
+import org.junit.jupiter.api.Test;
+import org.lwjgl.BufferUtils;
+import org.lwjgl.opengl.GL11;
+
+import java.nio.ByteBuffer;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertNotSame;
+
+@GLCoreTest
+public class GLSM_TextureUploadGeneration_GLTest {
+
+    private static int allocate(int size) {
+        final int texId = GLStateManager.glGenTextures();
+        GLStateManager.glBindTexture(GL11.GL_TEXTURE_2D, texId);
+        GLStateManager.glTexImage2D(GL11.GL_TEXTURE_2D, 0, GL11.GL_RGBA8, size, size, 0, GL11.GL_RGBA, GL11.GL_UNSIGNED_BYTE, BufferUtils.createByteBuffer(size * size * 4));
+        return texId;
+    }
+
+    @Test
+    void anUploadLeavesANonZeroGeneration() {
+        final int texId = allocate(4);
+        try {
+            assertNotEquals(0, TextureInfoCache.INSTANCE.getInfo(texId).getUploadGeneration());
+        } finally {
+            GLStateManager.glDeleteTextures(texId);
+        }
+    }
+
+    @Test
+    void recreatingATextureAtAReusedIdYieldsAFreshInfo() {
+        final int texId = allocate(4);
+        try {
+            final TextureInfo first = TextureInfoCache.INSTANCE.getInfo(texId);
+            final int firstGeneration = first.getUploadGeneration();
+
+            TextureInfoCache.INSTANCE.onDeleteTexture(texId);
+            final ByteBuffer pixels = BufferUtils.createByteBuffer(4 * 4 * 4);
+            GLStateManager.glTexImage2D(GL11.GL_TEXTURE_2D, 0, GL11.GL_RGBA8, 4, 4, 0, GL11.GL_RGBA, GL11.GL_UNSIGNED_BYTE, pixels);
+
+            final TextureInfo second = TextureInfoCache.INSTANCE.getInfo(texId);
+            assertNotSame(first, second, "a deleted id drops its entry, so the replacement must be a distinct instance");
+            assertEquals(firstGeneration, second.getUploadGeneration(), "generations alias across a delete/recreate cycle, which is exactly why identity has to carry the distinction");
+        } finally {
+            GLStateManager.glDeleteTextures(texId);
+        }
+    }
+
+    @Test
+    void anInPlaceRewriteBumpsTheGeneration() {
+        final int texId = allocate(4);
+        try {
+            final TextureInfo info = TextureInfoCache.INSTANCE.getInfo(texId);
+            final int afterAlloc = info.getUploadGeneration();
+
+            GLStateManager.glTexSubImage2D(GL11.GL_TEXTURE_2D, 0, 0, 0, 2, 2, GL11.GL_RGBA, GL11.GL_UNSIGNED_BYTE, BufferUtils.createByteBuffer(2 * 2 * 4));
+            assertNotEquals(afterAlloc, info.getUploadGeneration(), "content changed, so anything caching the pixels is stale");
+
+            final int afterSub = info.getUploadGeneration();
+            GLStateManager.glTexSubImage2D(GL11.GL_TEXTURE_2D, 1, 0, 0, 1, 1, GL11.GL_RGBA, GL11.GL_UNSIGNED_BYTE, BufferUtils.createByteBuffer(4));
+            assertEquals(afterSub, info.getUploadGeneration(), "only level 0 is tracked");
+        } finally {
+            GLStateManager.glDeleteTextures(texId);
+        }
+    }
+}

glsm/src/test/java/com/gtnewhorizons/angelica/glsm/GLVersionParseTest.java

@@ -21,6 +21,18 @@ class GLVersionParseTest {
         assertEquals(-1, RenderSystem.parseMajorMinor("OpenGL ES 3.2"));
     }
 
+    @Test
+    void detectsLtwWrapper() {
+        assertTrue(LTWWorkaround.isLtwVersionString("3.3 OpenLTW (Built on: May 21 2026/12:38:14)"));
+        assertFalse(LTWWorkaround.isLtwVersionString(null));
+        assertFalse(LTWWorkaround.isLtwVersionString(""));
+        assertFalse(LTWWorkaround.isLtwVersionString("4.6.0 NVIDIA 551.61"));
+        assertFalse(LTWWorkaround.isLtwVersionString("4.6 (Core Profile) Mesa 24.0.3"));
+        assertFalse(LTWWorkaround.isLtwVersionString("4.1 Metal - 88"));
+        assertFalse(LTWWorkaround.isLtwVersionString("OpenGL ES 3.2 ANGLE (Vulkan)"));
+        assertFalse(LTWWorkaround.isLtwVersionString("2.1 gl4es wrapper"));
+    }
+
     @Test
     void isContextValid() {
         assertTrue(RenderSystem.isContextValid(4, 4, 46, true));

glsm/src/test/java/com/gtnewhorizons/angelica/glsm/ReservedWordRestoreTest.java

@@ -0,0 +1,67 @@
+package com.gtnewhorizons.angelica.glsm;
+
+import org.junit.jupiter.api.Test;
+import org.taumc.glsl.grammar.GLSLParser;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class ReservedWordRestoreTest {
+
+    private static void assertTreeRestoreMatchesStringRestore(String label, String renamedSource) {
+        final GLSLParser.Translation_unitContext treeA = GlslTransformUtils.parseFullQuiet(renamedSource);
+        final String legacy = GlslTransformUtils.restoreReservedWords(GlslTransformUtils.getFormattedShader(treeA, ""));
+
+        final GLSLParser.Translation_unitContext treeB = GlslTransformUtils.parseFullQuiet(renamedSource);
+        GlslTransformUtils.restoreReservedWordsInTree(treeB);
+        final String inTree = GlslTransformUtils.getFormattedShader(treeB, "");
+
+        assertEquals(legacy, inTree, "in-tree restore diverged from string restore for " + label);
+    }
+
+    @Test
+    void allThreeRenamesRestoreIdentically() {
+        final String src = "float angelica_renamed_sample = 1.0;\n"
+            + "uniform sampler2D angelica_renamed_sampler;\n"
+            + "vec4 angelica_renamed_texture = vec4(0.0);\n"
+            + "void main() {\n"
+            + "    vec4 c = angelica_renamed_texture + vec4(angelica_renamed_sample);\n"
+            + "}\n";
+        assertTreeRestoreMatchesStringRestore("all-three", src);
+    }
+
+    @Test
+    void renamedNewStaysRenamed() {
+        final String src = "float angelica_renamed_new = 2.0;\n"
+            + "void main() { float x = angelica_renamed_new; }\n";
+        assertTreeRestoreMatchesStringRestore("new-identifier", src);
+
+        final GLSLParser.Translation_unitContext tree = GlslTransformUtils.parseFullQuiet(src);
+        GlslTransformUtils.restoreReservedWordsInTree(tree);
+        final String out = GlslTransformUtils.getFormattedShader(tree, "");
+        assertTrue(out.contains("angelica_renamed_new"), "new is reserved in every GLSL version and must stay renamed");
+    }
+
+    @Test
+    void renamedTextureFunctionCallRestores() {
+        final String src = "uniform sampler2D tex;\n"
+            + "void main() {\n"
+            + "    vec4 c = angelica_renamed_texture2D(tex, vec2(0.5));\n"
+            + "}\n";
+        assertTreeRestoreMatchesStringRestore("texture2D-call", src);
+
+        final GLSLParser.Translation_unitContext tree = GlslTransformUtils.parseFullQuiet(src);
+        GlslTransformUtils.restoreReservedWordsInTree(tree);
+        final String out = GlslTransformUtils.getFormattedShader(tree, "");
+        assertTrue(out.contains("texture2D"), "suffixed rename must strip only the prefix");
+        assertFalse(out.contains("angelica_renamed_"), "no renamed remnants expected");
+    }
+
+    @Test
+    void untouchedSourcePrintsIdentically() {
+        final String src = "layout(location = 0) out vec4 fragColor;\n"
+            + "void main() { fragColor = vec4(1.0); }\n";
+        assertTreeRestoreMatchesStringRestore("no-renames", src);
+    }
+}

glsm/src/test/java/com/gtnewhorizons/angelica/glsm/backend/BackendPolicyTest.java

@@ -0,0 +1,65 @@
+package com.gtnewhorizons.angelica.glsm.backend;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.function.Predicate;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class BackendPolicyTest {
+
+    @Test
+    void onlyImmediateCanTear() {
+        assertTrue(VSyncMode.ON.tearFree());
+        assertTrue(VSyncMode.MAILBOX.tearFree());
+        assertFalse(VSyncMode.OFF.tearFree());
+    }
+
+    private static final Predicate<VSyncMode> NO_MAILBOX = mode -> mode != VSyncMode.MAILBOX;
+    private static final Predicate<VSyncMode> EVERYTHING = mode -> true;
+
+    @Test
+    void mailboxIsTakenWhenTheBackendOffersIt() {
+        assertEquals(VSyncMode.MAILBOX, RenderBackend.resolveTearFreeMode(null, EVERYTHING));
+    }
+
+    @Test
+    void vsyncIsTheFallbackWhenMailboxIsUnsupported() {
+        assertEquals(VSyncMode.ON, RenderBackend.resolveTearFreeMode(null, NO_MAILBOX));
+        assertEquals(VSyncMode.ON, RenderBackend.resolveTearFreeMode(VSyncMode.MAILBOX, NO_MAILBOX));
+    }
+
+    @Test
+    void anExplicitSupportedPreferenceWins() {
+        assertEquals(VSyncMode.ON, RenderBackend.resolveTearFreeMode(VSyncMode.ON, EVERYTHING));
+        assertEquals(VSyncMode.MAILBOX, RenderBackend.resolveTearFreeMode(VSyncMode.MAILBOX, EVERYTHING));
+    }
+
+    @Test
+    void offIsNeverATearFreePreference() {
+        assertEquals(VSyncMode.MAILBOX, RenderBackend.resolveTearFreeMode(VSyncMode.OFF, EVERYTHING));
+        assertEquals(VSyncMode.ON, RenderBackend.resolveTearFreeMode(VSyncMode.OFF, NO_MAILBOX));
+    }
+
+    @Test
+    void refreshPrefersTheExactRational() {
+        assertEquals(144, RenderBackend.refreshHzFrom(144, 1, 0.0f));
+        assertEquals(60, RenderBackend.refreshHzFrom(60000, 1001, 0.0f));
+    }
+
+    @Test
+    void refreshRoundsUp() {
+        assertEquals(144, RenderBackend.refreshHzFrom(0, 0, 143.98f));
+        assertEquals(60, RenderBackend.refreshHzFrom(0, 0, 59.94f));
+        assertEquals(60, RenderBackend.refreshHzFrom(0, 0, 60.0f));
+    }
+
+    @Test
+    void refreshIsZeroWhenUnknown() {
+        assertEquals(0, RenderBackend.refreshHzFrom(0, 0, 0.0f));
+        assertEquals(0, RenderBackend.refreshHzFrom(-1, -1, -1.0f));
+        assertEquals(0, RenderBackend.refreshHzFrom(144, 0, 0.0f));
+    }
+}

glsm/src/test/java/com/gtnewhorizons/angelica/glsm/ffp/FFPVertexLightingGLTest.java

@@ -0,0 +1,241 @@
+package com.gtnewhorizons.angelica.glsm.ffp;
+
+import com.gtnewhorizon.gtnhlib.client.renderer.vertex.VertexFormatElement;
+import com.gtnewhorizons.angelica.glsm.GLCoreTest;
+import com.gtnewhorizons.angelica.glsm.GLStateManager;
+import org.joml.Vector3f;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.lwjgl.BufferUtils;
+import org.lwjgl.opengl.GL11;
+import org.lwjgl.opengl.GL12;
+import org.lwjgl.opengl.GL15;
+
+import java.nio.ByteBuffer;
+import java.nio.FloatBuffer;
+
+import static com.gtnewhorizon.gtnhlib.client.renderer.vertex.VertexFlags.COLOR_BIT;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+@GLCoreTest
+class FFPVertexLightingGLTest {
+
+    private static final int POSITION_LOC = VertexFormatElement.Usage.POSITION.getAttributeLocation();
+    private static final int COLOR_LOC = VertexFormatElement.Usage.COLOR.getAttributeLocation();
+    private static final int STRIDE = 16;
+
+    private static final int VERTEX_COLOR = 0xFF808080;
+    private static final float VERTEX_CHANNEL = 0x80 / 255.0f;
+
+    private static final Vector3f IDENTITY_FACTOR = new Vector3f(1.0f, 1.0f, 1.0f);
+
+    private final Vector3f factor = new Vector3f();
+
+    private int vao;
+    private int vbo;
+
+    @BeforeEach
+    void setUpState() {
+        GLStateManager.glMatrixMode(GL11.GL_PROJECTION);
+        GLStateManager.glLoadIdentity();
+        GLStateManager.glMatrixMode(GL11.GL_MODELVIEW);
+        GLStateManager.glLoadIdentity();
+        GLStateManager.glViewport(0, 0, 800, 600);
+        GLStateManager.disableDepthTest();
+        GLStateManager.disableCull();
+        GLStateManager.disableBlend();
+        GLStateManager.disableTexture();
+        GLStateManager.glNormal3f(0.0f, 0.0f, 1.0f);
+        standardItemLighting();
+
+        GLStateManager.glMaterial(GL11.GL_FRONT_AND_BACK, GL11.GL_EMISSION, floats(0.0f, 0.0f, 0.0f, 1.0f));
+        GLStateManager.glMaterial(GL11.GL_FRONT_AND_BACK, GL11.GL_SPECULAR, floats(0.0f, 0.0f, 0.0f, 1.0f));
+        GLStateManager.glMaterialf(GL11.GL_FRONT_AND_BACK, GL11.GL_SHININESS, 0.0f);
+    }
+
+    @AfterEach
+    void cleanup() {
+        GLStateManager.glDisable(GL11.GL_NORMALIZE);
+        GLStateManager.glDisable(GL12.GL_RESCALE_NORMAL);
+        GLStateManager.glMatrixMode(GL11.GL_MODELVIEW);
+        GLStateManager.glLoadIdentity();
+        GLStateManager.glDisable(GL11.GL_LIGHTING);
+        GLStateManager.glDisable(GL11.GL_LIGHT0);
+        GLStateManager.glDisable(GL11.GL_LIGHT1);
+        GLStateManager.glDisable(GL11.GL_LIGHT2);
+        GLStateManager.glDisable(GL11.GL_COLOR_MATERIAL);
+        final ShaderManager sm = ShaderManager.getInstance();
+        if (sm.isActive()) sm.deactivate();
+        sm.disable();
+        GLStateManager.glBindVertexArray(0);
+        if (vbo != 0) {
+            GLStateManager.glDeleteBuffers(vbo);
+            vbo = 0;
+        }
+        if (vao != 0) {
+            GLStateManager.glDeleteVertexArrays(vao);
+            vao = 0;
+        }
+    }
+
+    private static void standardItemLighting() {
+        GLStateManager.glEnable(GL11.GL_LIGHTING);
+        GLStateManager.glEnable(GL11.GL_LIGHT0);
+        GLStateManager.glEnable(GL11.GL_LIGHT1);
+        GLStateManager.glEnable(GL11.GL_COLOR_MATERIAL);
+        GLStateManager.glColorMaterial(GL11.GL_FRONT_AND_BACK, GL11.GL_AMBIENT_AND_DIFFUSE);
+        GLStateManager.glLightModel(GL11.GL_LIGHT_MODEL_AMBIENT, floats(0.4f, 0.4f, 0.4f, 1.0f));
+        light(GL11.GL_LIGHT0, 0.2f, 1.0f, -0.7f);
+        light(GL11.GL_LIGHT1, -0.2f, 1.0f, 0.7f);
+    }
+
+    private static void light(int light, float x, float y, float z) {
+        GLStateManager.glLight(light, GL11.GL_POSITION, floats(x, y, z, 0.0f));
+        GLStateManager.glLight(light, GL11.GL_DIFFUSE, floats(0.6f, 0.6f, 0.6f, 1.0f));
+        GLStateManager.glLight(light, GL11.GL_AMBIENT, floats(0.0f, 0.0f, 0.0f, 1.0f));
+        GLStateManager.glLight(light, GL11.GL_SPECULAR, floats(0.0f, 0.0f, 0.0f, 1.0f));
+    }
+
+    private static String gateState() {
+        final var material = GLStateManager.getFrontMaterial();
+        return "lighting=" + GLStateManager.getLightingState().isEnabled()
+            + " colorMaterial=" + GLStateManager.getColorMaterial().isEnabled()
+            + " cmParam=0x" + Integer.toHexString(GLStateManager.getColorMaterialParameter().getValue())
+            + " emission=" + material.emission
+            + " specular=" + material.specular
+            + " shininess=" + material.shininess
+            + " lmAmbient=" + GLStateManager.getLightModel().ambient
+            + " light0=" + GLStateManager.getLightStates()[0].isEnabled()
+            + " light1=" + GLStateManager.getLightStates()[1].isEnabled();
+    }
+
+    private static FloatBuffer floats(float... values) {
+        final FloatBuffer buf = BufferUtils.createFloatBuffer(values.length);
+        buf.put(values).flip();
+        return buf;
+    }
+
+    private void buildTriangle() {
+        vao = GLStateManager.glGenVertexArrays();
+        GLStateManager.glBindVertexArray(vao);
+
+        final ByteBuffer data = BufferUtils.createByteBuffer(3 * STRIDE);
+        putVertex(data, -0.9f, -0.9f);
+        putVertex(data, 0.9f, -0.9f);
+        putVertex(data, 0.0f, 0.9f);
+        data.flip();
+
+        vbo = GLStateManager.glGenBuffers();
+        GLStateManager.glBindBuffer(GL15.GL_ARRAY_BUFFER, vbo);
+        GLStateManager.glBufferData(GL15.GL_ARRAY_BUFFER, data, GL15.GL_STATIC_DRAW);
+        GLStateManager.glEnableVertexAttribArray(POSITION_LOC);
+        GLStateManager.glVertexAttribPointer(POSITION_LOC, 3, GL11.GL_FLOAT, false, STRIDE, 0L);
+        GLStateManager.glEnableVertexAttribArray(COLOR_LOC);
+        GLStateManager.glVertexAttribPointer(COLOR_LOC, 4, GL11.GL_UNSIGNED_BYTE, true, STRIDE, 12L);
+        VAOManager.setCurrentVertexFlags(COLOR_BIT);
+    }
+
+    private static void putVertex(ByteBuffer buf, float x, float y) {
+        final int base = buf.position();
+        buf.putFloat(base, x).putFloat(base + 4, y).putFloat(base + 8, 0.0f);
+        buf.putInt(base + 12, VERTEX_COLOR);
+        buf.position(base + STRIDE);
+    }
+
+    private float[] drawAndReadCenter() {
+        buildTriangle();
+        final ShaderManager sm = ShaderManager.getInstance();
+        sm.enable();
+        sm.activate();
+
+        GLStateManager.glClearColor(0.0f, 0.0f, 0.0f, 1.0f);
+        GLStateManager.glClear(GL11.GL_COLOR_BUFFER_BIT);
+        GLStateManager.glDrawArrays(GL11.GL_TRIANGLES, 0, 3);
+        assertEquals(GL11.GL_NO_ERROR, GL11.glGetError(), "FFP draw must not raise a GL error");
+
+        final ByteBuffer pixel = BufferUtils.createByteBuffer(4);
+        GL11.glReadPixels(400, 200, 1, 1, GL11.GL_RGBA, GL11.GL_UNSIGNED_BYTE, pixel);
+        return new float[] { (pixel.get(0) & 0xFF) / 255.0f, (pixel.get(1) & 0xFF) / 255.0f, (pixel.get(2) & 0xFF) / 255.0f };
+    }
+
+    private void assertSolverMatchesShader(String context) {
+        assertTrue(FFPVertexLighting.modulatesVertexColor(factor), context + ": expected a representable factor");
+        final float[] actual = drawAndReadCenter();
+        final float[] expected = { Math.min(1.0f, VERTEX_CHANNEL * factor.x), Math.min(1.0f, VERTEX_CHANNEL * factor.y), Math.min(1.0f, VERTEX_CHANNEL * factor.z) };
+        for (int c = 0; c < 3; c++) {
+            assertEquals(expected[c], actual[c], 2.0f / 255.0f, context + ": channel " + c + " solver=" + expected[c] + " shader=" + actual[c] + " factor=" + factor);
+        }
+    }
+
+    @Test
+    void faceOnNormalMatchesGeneratedShader() {
+        GLStateManager.glNormal3f(0.0f, 0.0f, 1.0f);
+        assertSolverMatchesShader("face-on normal");
+    }
+
+    @Test
+    void signNormalMatchesGeneratedShader() {
+        GLStateManager.glNormal3f(0.0f, 0.0f, -0.010416667f);
+        assertSolverMatchesShader("sign normal");
+        assertTrue(factor.x < 0.45f, "a 0.0104-long normal must stay at the 0.4 light model ambient floor rather than pick up 0.6 per light, got " + factor.x);
+    }
+
+    @Test
+    void tiltedNormalMatchesGeneratedShader() {
+        GLStateManager.glNormal3f(0.3f, 0.8f, 0.5f);
+        assertSolverMatchesShader("tilted normal");
+    }
+
+    @Test
+    void rescaleNormalMatchesGeneratedShader() {
+        GLStateManager.glEnable(GL12.GL_RESCALE_NORMAL);
+        GLStateManager.glScalef(1.0f, 2.0f, 1.0f);
+        GLStateManager.glNormal3f(0.0f, 1.0f, 0.0f);
+        assertSolverMatchesShader("rescale normal");
+    }
+
+    @Test
+    void normalizeMatchesGeneratedShader() {
+        GLStateManager.glEnable(GL11.GL_NORMALIZE);
+        GLStateManager.glScalef(1.0f, 2.0f, 1.0f);
+        GLStateManager.glNormal3f(0.0f, 1.0f, 0.0f);
+        assertSolverMatchesShader("normalize");
+        assertTrue(factor.x > 1.2f, "normalize restores the unit normal, which must pick up more diffuse than rescale's 0.5-long one, got " + factor.x);
+    }
+
+    @Test
+    void materialEmissionIsNotRepresentable() {
+        GLStateManager.glMaterial(GL11.GL_FRONT_AND_BACK, GL11.GL_EMISSION, floats(0.1f, 0.1f, 0.1f, 1.0f));
+        assertFalse(FFPVertexLighting.modulatesVertexColor(factor), "emission is additive, so the lit colour is not vertexColor * factor");
+        assertEquals(IDENTITY_FACTOR, factor, "a rejected solve must leave an identity factor");
+    }
+
+    @Test
+    void specularContributionIsNotRepresentable() {
+        GLStateManager.glMaterial(GL11.GL_FRONT_AND_BACK, GL11.GL_SPECULAR, floats(1.0f, 1.0f, 1.0f, 1.0f));
+        GLStateManager.glMaterialf(GL11.GL_FRONT_AND_BACK, GL11.GL_SHININESS, 16.0f);
+        GLStateManager.glLight(GL11.GL_LIGHT0, GL11.GL_SPECULAR, floats(1.0f, 1.0f, 1.0f, 1.0f));
+        assertFalse(FFPVertexLighting.modulatesVertexColor(factor), "specular is additive, so the lit colour is not vertexColor * factor");
+    }
+
+    @Test
+    void nonAmbientAndDiffuseColorMaterialIsNotRepresentable() {
+        GLStateManager.glColorMaterial(GL11.GL_FRONT_AND_BACK, GL11.GL_EMISSION);
+        assertFalse(FFPVertexLighting.modulatesVertexColor(factor), "only AMBIENT_AND_DIFFUSE makes the lit colour scale with the vertex colour");
+    }
+
+    @Test
+    void lightsBeyondTheFfpCountAreIgnored() {
+        assertTrue(FFPVertexLighting.modulatesVertexColor(factor), FFPVertexLightingGLTest::gateState);
+        final Vector3f twoLights = new Vector3f(factor);
+
+        light(GL11.GL_LIGHT2, 0.0f, 0.0f, 1.0f);
+        GLStateManager.glEnable(GL11.GL_LIGHT2);
+        assertTrue(FFPVertexLighting.modulatesVertexColor(factor), FFPVertexLightingGLTest::gateState);
+
+        assertEquals(twoLights, factor, "VertexShaderGenerator emits only GL_LIGHT0/GL_LIGHT1, so text must not see GL_LIGHT2 either");
+    }
+}

glsm/src/test/java/com/gtnewhorizons/angelica/glsm/ffp/UniformsRescaleTest.java

@@ -0,0 +1,32 @@
+package com.gtnewhorizons.angelica.glsm.ffp;
+
+import org.joml.Matrix3f;
+import org.joml.Matrix4f;
+import org.joml.Vector3f;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class UniformsRescaleTest {
+
+    private static float rescaleFactorFor(float sx, float sy, float sz) {
+        final Matrix3f normalMatrix = new Matrix3f();
+        new Matrix4f().rotateY(0.7f).scale(sx, sy, sz).normal(normalMatrix);
+        return Uniforms.rescaleFactor(normalMatrix, new Vector3f());
+    }
+
+    @Test
+    void rescaleFactorUsesTheInverseModelviewBottomRow() {
+        assertEquals(8.0f, rescaleFactorFor(4.0f, 2.0f, 8.0f), 1.0e-5f, "wrong normal matrix column");
+    }
+
+    @Test
+    void uniformScaleIsRowIndependent() {
+        assertEquals(2.0f, rescaleFactorFor(2.0f, 2.0f, 2.0f), 1.0e-5f);
+    }
+
+    @Test
+    void singularMatrixFallsBackToUnitScale() {
+        assertEquals(1.0f, rescaleFactorFor(1.0f, 1.0f, 0.0f), 1.0e-5f, "a degenerate normal matrix must not divide by zero");
+    }
+}

glsm/src/test/java/com/gtnewhorizons/angelica/glsm/loading/TransformerNarrowerTest.java

@@ -0,0 +1,92 @@
+package com.gtnewhorizons.angelica.glsm.loading;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Set;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class TransformerNarrowerTest {
+
+    private static final String LEGENDS_BROAD = "com.tihyo.legends.management.asm";
+    private static final String LEGENDS_HOOK = LEGENDS_BROAD + ".ASMClientMethods";
+
+    private static Set<String> exceptionsWith(String... entries) {
+        return new HashSet<>(Set.of(entries));
+    }
+
+    private static boolean isExcluded(Set<String> exceptions, String className) {
+        return exceptions.stream().anyMatch(className::startsWith);
+    }
+
+    private static int narrow(Set<String> exceptions, Map<String, Object> blackboard) {
+        return TransformerNarrower.narrow(exceptions, blackboard, "angelica", "Angelica", EcosystemNarrowRules.ALL);
+    }
+
+    @Test
+    void legendsHooksBecomeTransformableButTransformersDoNot() {
+        final Set<String> exceptions = exceptionsWith(LEGENDS_BROAD);
+        assertEquals(1, narrow(exceptions, new HashMap<>()));
+
+        assertFalse(isExcluded(exceptions, LEGENDS_HOOK));
+        assertFalse(isExcluded(exceptions, LEGENDS_BROAD + ".ASMMethods"));
+
+        assertTrue(isExcluded(exceptions, LEGENDS_BROAD + ".LegendsLoadingPlugin"));
+        assertTrue(isExcluded(exceptions, LEGENDS_BROAD + ".AbstractTransformer"));
+        assertTrue(isExcluded(exceptions, LEGENDS_BROAD + ".ASMHelper"));
+        assertTrue(isExcluded(exceptions, LEGENDS_BROAD + ".TransformerRenderPlayer"));
+        assertTrue(isExcluded(exceptions, LEGENDS_BROAD + ".TransformerEntityRenderer"));
+        assertTrue(isExcluded(exceptions, LEGENDS_BROAD + ".TransformerMethodProcess"));
+        assertTrue(isExcluded(exceptions, LEGENDS_BROAD + ".TransformerGuiInventory"));
+    }
+
+    @Test
+    void disabledRuleLeavesBroadExclusionIntact() {
+        final Set<String> exceptions = exceptionsWith(LEGENDS_BROAD);
+        final Map<String, Object> blackboard = new HashMap<>();
+        blackboard.put("angelica.narrow.LegendsMod", Boolean.FALSE);
+
+        assertEquals(0, narrow(exceptions, blackboard));
+        assertTrue(exceptions.contains(LEGENDS_BROAD));
+        assertTrue(isExcluded(exceptions, LEGENDS_HOOK));
+    }
+
+    @Test
+    void sharedXaerosKeyGovernsBothExclusions() {
+        final Set<String> enabled = exceptionsWith("xaero.common.core", "xaero.map.core");
+        assertEquals(2, narrow(enabled, new HashMap<>()));
+        assertFalse(isExcluded(enabled, "xaero.common.gui.GuiMap"));
+        assertFalse(isExcluded(enabled, "xaero.map.gui.GuiMap"));
+        assertTrue(isExcluded(enabled, "xaero.common.core.transformer.Foo"));
+        assertTrue(isExcluded(enabled, "xaero.map.core.transformer.Foo"));
+
+        final Set<String> disabled = exceptionsWith("xaero.common.core", "xaero.map.core");
+        final Map<String, Object> blackboard = new HashMap<>();
+        blackboard.put("angelica.narrow.Xaeros", Boolean.FALSE);
+        assertEquals(0, narrow(disabled, blackboard));
+        assertTrue(disabled.contains("xaero.common.core"));
+        assertTrue(disabled.contains("xaero.map.core"));
+    }
+
+    @Test
+    void narrowingIsIdempotent() {
+        final Set<String> exceptions = exceptionsWith(LEGENDS_BROAD);
+        assertEquals(1, narrow(exceptions, new HashMap<>()));
+
+        final Set<String> afterFirst = new HashSet<>(exceptions);
+        assertEquals(0, narrow(exceptions, new HashMap<>()));
+        assertEquals(afterFirst, exceptions);
+    }
+
+    @Test
+    void absentBroadExclusionIsNoOp() {
+        final Set<String> exceptions = exceptionsWith("some.unrelated.package");
+        assertEquals(0, narrow(exceptions, new HashMap<>()));
+        assertEquals(Set.of("some.unrelated.package"), exceptions);
+    }
+}

glsm/src/test/java/com/gtnewhorizons/angelica/glsm/redirect/GLSMRedirectorTest.java

@@ -331,6 +331,9 @@ class GLSMRedirectorTest {
     void phase2NameKeyedGapsRedirect() {
         assertRedirected("org/lwjgl/opengl/GL33C", "glQueryCounter", "(II)V", "glQueryCounter");
         assertRedirected("org/lwjgl/opengl/GL33C", "glGetQueryObjectui64", "(II)J", "glGetQueryObjectui64");
+        assertRedirected("org/lwjgl/opengl/ARBTimerQuery", "glGetQueryObjectui64", "(II)J", "glGetQueryObjectui64");
+        assertRedirected("org/lwjgl/opengl/EXTTimerQuery", "glGetQueryObjectuEXT", "(II)J", "glGetQueryObjectui64");
+        assertRedirected("org/lwjgl/opengl/EXTTimerQuery", "glGetQueryObjectui64EXT", "(II)J", "glGetQueryObjectui64");
         assertRedirected("org/lwjgl/opengl/GL30C", "glBindFragDataLocation", "(IILjava/lang/CharSequence;)V", "glBindFragDataLocation");
         assertRedirected("org/lwjgl/opengl/GL11C", "glGetIntegerv", "(I[I)V", "glGetInteger");
         assertRedirected("org/lwjgl/opengl/GL20C", "glUniform4fv", "(I[F)V", "glUniform4");

gradle/libs.versions.toml

@@ -9,7 +9,7 @@ asmCompile = "5.0.3"
 lwjgl3 = "3.4.2-20260602.093430-9"
 lwjgl3ify = "3.0.31"
 
-celeritas = "2.5.9-GTNH"
+celeritas = "2.5.10-GTNH"
 gtnhlib = "0.11.36"
 eventbus = "7.0-beta.15"
 glslTransformLib = "0.2.0-33.g3ec381e"

lwjgl3-backend/src/main/java/com/gtnewhorizons/angelica/lwjgl3/Lwjgl3GLRenderBackend.java

@@ -5,6 +5,7 @@ import com.gtnewhorizons.angelica.glsm.GLESCaps;
 import com.gtnewhorizons.angelica.glsm.RenderSystem;
 import com.gtnewhorizons.angelica.glsm.backend.DebugMessageHandler;
 import com.gtnewhorizons.angelica.glsm.backend.RenderBackend;
+import com.gtnewhorizons.angelica.glsm.backend.VSyncMode;
 import me.eigenraven.lwjgl3ify.api.Lwjgl3Aware;
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
@@ -32,6 +33,7 @@ import org.lwjgl.opengl.EXTPolygonOffsetClamp;
 import org.lwjgl.opengl.EXTShaderImageLoadStore;
 import org.lwjgl.opengl.GLCapabilities;
 import org.lwjgl.opengl.GLDebugMessageCallback;
+import org.lwjgl.sdl.SDL_DisplayMode;
 import org.lwjgl.sdl.SDL_DropEvent;
 import org.lwjgl.sdl.SDL_EventFilter;
 import org.lwjgl.sdl.SDLEvents;
@@ -39,6 +41,7 @@ import org.lwjgl.sdl.SDLVideo;
 import org.lwjgl.system.JNI;
 import org.lwjgl.system.MemoryStack;
 import org.lwjgl.system.MemoryUtil;
+import org.lwjglx.opengl.Display;
 
 import java.nio.Buffer;
 import java.nio.ByteBuffer;
@@ -169,7 +172,21 @@ public final class Lwjgl3GLRenderBackend extends RenderBackend {
     public int getMinGLSLVersion() {return 330;}
 
     @Override
-    public void setVSyncEnabled(boolean enabled) {SDLVideo.SDL_GL_SetSwapInterval(enabled ? 1 : 0);}
+    protected VSyncMode applyVSyncMode(VSyncMode preferred) {
+        final boolean enabled = preferred.tearFree();
+        SDLVideo.SDL_GL_SetSwapInterval(enabled ? 1 : 0);
+        return enabled ? VSyncMode.ON : VSyncMode.OFF;
+    }
+
+    @Override
+    protected int queryDisplayRefreshRateHz() {
+        final long window = Display.getWindow();
+        final int displayId = window == 0 ? SDLVideo.SDL_GetPrimaryDisplay() : SDLVideo.SDL_GetDisplayForWindow(window);
+        if (displayId == 0) return 0;
+        final SDL_DisplayMode mode = SDLVideo.SDL_GetCurrentDisplayMode(displayId);
+        if (mode == null) return 0;
+        return refreshHzFrom(mode.refresh_rate_numerator(), mode.refresh_rate_denominator(), mode.refresh_rate());
+    }
 
     @Override
     public boolean isAnisotropicSupported() {
@@ -1504,6 +1521,16 @@ public final class Lwjgl3GLRenderBackend extends RenderBackend {
         GL11C.glGetFloatv(pname, params);
     }
 
+    @Override
+    public double getDouble(int pname) {
+        return GL11C.glGetDouble(pname);
+    }
+
+    @Override
+    public void getDouble(int pname, DoubleBuffer params) {
+        GL11C.glGetDoublev(pname, params);
+    }
+
     @Override
     public boolean getBoolean(int pname) {
         return GL11C.glGetBoolean(pname);

sdl-gpu/build.gradle.kts

@@ -59,6 +59,7 @@ dependencies {
     api(project(":glsm"))
 
     compileOnly(libs.lwjgl3ify) { artifact { classifier = "dev" }; isTransitive = false }
+    compileOnly(libs.retrofuturabootstrap) { isTransitive = false }
     compileOnly(libs.celeritas.common) { isTransitive = false }
 
     // GL enum constants (compileOnly -- no runtime GL dependency)
@@ -76,6 +77,7 @@ dependencies {
     testImplementation(platform(libs.junit.bom))
     testImplementation(libs.junit.jupiter)
     testImplementation(testFixtures(project(":glsm")))
+    testImplementation(libs.celeritas.common) { isTransitive = false }
     testImplementation(libs.lwjgl3.opengl)
     // GL.<clinit> loads liblwjgl_opengl.so. Test scope only: a root-level runtimeOnly collides with lwjgl3Bindings.
     testRuntimeOnly(libs.lwjgl3.opengl) { artifact { classifier = lwjglNatives } }

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/SDLGPUGate.java

@@ -2,11 +2,19 @@ package com.gtnewhorizons.angelica.sdlgpu;
 
 import static org.lwjgl.sdl.SDLVideo.SDL_PROP_WINDOW_CREATE_METAL_BOOLEAN;
 
+import com.gtnewhorizons.angelica.config.SystemProperties;
 import com.gtnewhorizons.angelica.glsm.backend.BackendManager;
 import com.gtnewhorizons.angelica.glsm.backend.RenderBackend;
+import com.gtnewhorizons.angelica.sdlgpu.device.Device;
+import com.gtnewhorizons.angelica.sdlgpu.shader.ShaderManager;
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+import org.lwjgl.sdl.SDLLog;
+import org.taumc.glsl.grammar.GLSLParser;
 import org.lwjgl.sdl.SDLProperties;
 import org.lwjgl.system.Platform;
 import org.lwjglx.Sys;
+import org.lwjglx.input.Mouse;
 import org.lwjglx.opengl.ContextAttribs;
 import org.lwjglx.opengl.Display;
 import org.lwjglx.opengl.PixelFormat;
@@ -14,21 +22,67 @@ import org.lwjglx.opengl.PixelFormat;
 import me.eigenraven.lwjgl3ify.api.DisplayEvents;
 import me.eigenraven.lwjgl3ify.api.DisplayWindowContext;
 import me.eigenraven.lwjgl3ify.api.SwapchainInvalidatingChange;
+import me.eigenraven.lwjgl3ify.client.MainThreadExec;
 
+import java.nio.ByteBuffer;
 import java.util.function.Consumer;
 
 public final class SDLGPUGate {
 
+    private static final Logger LOG = LogManager.getLogger("Angelica/SDLGPU");
+
     private SDLGPUGate() {}
 
-    private static volatile boolean fatalInit;
+    private static Device device;
 
-    public static void markFatalInit() { fatalInit = true; }
+    private static volatile Boolean deviceReady;
+    private static volatile boolean engaged;
+    private static volatile boolean disarmed;
+    private static volatile Throwable initFailure;
+    private static boolean listenersRegistered;
+    private static ByteBuffer[] windowIcons;
 
-    public static boolean isFatalInit() { return fatalInit; }
+    public static void rememberIcons(ByteBuffer[] icons) {
+        windowIcons = icons;
+    }
+
+    public static synchronized Device device() {
+        if (device == null) device = new Device();
+        return device;
+    }
+
+    private static final boolean SDL_GPU_AVAILABLE = SDLGPUGate.class.getClassLoader().getResource("org/lwjgl/sdl/SDLGPU.class") != null;
 
     public static boolean isSDLGPUAvailable() {
-        return SDLGPUGate.class.getClassLoader().getResource("org/lwjgl/sdl/SDLGPU.class") != null;
+        return SDL_GPU_AVAILABLE;
+    }
+
+    public static boolean isDeviceReady() {
+        final Boolean ready = deviceReady;
+        return ready != null ? ready : probe();
+    }
+
+    private static synchronized boolean probe() {
+        if (deviceReady != null) return deviceReady;
+        if (!SystemProperties.USE_SDL_GPU || !isSDLGPUAvailable()) {
+            deviceReady = false;
+            return false;
+        }
+        boolean ok;
+        try {
+            Sys.initialize();
+            ok = MainThreadExec.runOnMainThread(device()::createDevice);
+        } catch (Throwable t) {
+            LOG.error("SDL GPU device probe failed", t);
+            ok = false;
+        }
+        if (!ok) resetSdlLogging();
+        deviceReady = ok;
+        return ok;
+    }
+
+    public static boolean isEngaged() {
+        return engaged;
     }
 
     public static boolean isActive() {
@@ -37,24 +91,96 @@ public final class SDLGPUGate {
         return rb instanceof SDLGPURenderBackend;
     }
 
-    public static Consumer<DisplayWindowContext> sdlGpuPreWindowCreateCallback() {
-        if (Platform.get() != Platform.MACOSX) return null;
-        return ctx -> Sys.checkSdl(SDLProperties.SDL_SetBooleanProperty(ctx.props(), SDL_PROP_WINDOW_CREATE_METAL_BOOLEAN, true));
+    public static void ensureDrawableInstalled() {
+        if (!isActive()) return;
+        SDLGPUDisplayBridge.ensureDrawableInstalled();
     }
 
-    public static Consumer<DisplayWindowContext> sdlGpuPostWindowCreateCallback(boolean debug) {
-        return ctx -> BackendManager.RENDER_BACKEND.onPostWindowCreate(ctx.window(), debug);
+    public static void prewarmSpirv(String transformedSource, int glShaderType) {
+        if (!isActive()) return;
+        ShaderManager.prewarmSpirv(transformedSource, glShaderType);
+    }
+
+    public static void prewarmSpirv(String transformedSource, GLSLParser.Translation_unitContext bodyTree, int headerLen, int glShaderType) {
+        if (!isActive()) return;
+        ShaderManager.prewarmSpirv(transformedSource, bodyTree, headerLen, glShaderType);
+    }
+
+    public static void clearShaderPrewarmCache() {
+        if (!isActive()) return;
+        ShaderManager.clearPrewarmCache();
     }
 
     public static Consumer<SwapchainInvalidatingChange> sdlGpuPreSwapchainInvalidatingCallback() {
         return change -> BackendManager.RENDER_BACKEND.onPreSwapchainInvalidatingChange(change);
     }
 
-    public static void createSDLGPUDisplay(Object format, Object attribs, boolean debug) {
+    public static boolean createSDLGPUDisplay(Object format, Object attribs) {
+        if (!isDeviceReady()) return false;
+
+        initFailure = null;
+        disarmed = false;
+        registerListeners();
+
         DisplayEvents.setCreateGLContext(false);
-        final Consumer<DisplayWindowContext> pre = sdlGpuPreWindowCreateCallback(); // null on non-Mac
-        if (pre != null) DisplayEvents.addPreWindowCreateListener(pre);
-        DisplayEvents.addPostWindowCreateListener(sdlGpuPostWindowCreateCallback(debug));
         Display.create((PixelFormat) format, (ContextAttribs) attribs, /*sharedWindow*/ 0L);
+
+        final Throwable failure = initFailure;
+        if (failure != null) {
+            initFailure = null;
+            LOG.error("SDL GPU could not take the window", failure);
+            return false;
+        }
+        return engaged;
+    }
+
+    private static void registerListeners() {
+        if (listenersRegistered) return;
+        listenersRegistered = true;
+
+        if (Platform.get() == Platform.MACOSX) {
+            DisplayEvents.addPreWindowCreateListener((DisplayWindowContext ctx) -> {
+                if (disarmed) return;
+                Sys.checkSdl(SDLProperties.SDL_SetBooleanProperty(ctx.props(), SDL_PROP_WINDOW_CREATE_METAL_BOOLEAN, true));
+            });
+        }
+
+        DisplayEvents.addPostWindowCreateListener((DisplayWindowContext ctx) -> {
+            if (disarmed) return;
+            try {
+                device().claimWindow(ctx.window());
+                engaged = true;
+                BackendManager.RENDER_BACKEND.onPostWindowCreate(ctx.window());
+            } catch (Throwable t) {
+                initFailure = t;
+            }
+        });
+    }
+
+    public static void fallBackToGL() {
+        if (SDLGPULWJGLService.isOfferedAsAvailable()) {
+            throw new IllegalStateException("Celeritas already selected the SDL GPU LWJGL service; falling back to OpenGL would leave it bound to a dead backend");
+        }
+        disarmed = true;
+        engaged = false;
+        deviceReady = false;
+
+        device().destroyDevice();
+        resetSdlLogging();
+
+        Mouse.setGrabbed(false);
+
+        DisplayEvents.setCreateGLContext(true);
+        if (Display.isCreated()) {
+            Display.destroy();
+        }
+        Display.isCloseRequested();
+        if (windowIcons != null) {
+            Display.setIcon(windowIcons);
+        }
+    }
+
+    private static void resetSdlLogging() {
+        SDLLog.SDL_ResetLogPriorities();
     }
 }

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/SDLGPULWJGLService.java

@@ -19,11 +19,17 @@ import java.util.Arrays;
 
 /** SDL GPU implementation of {@link LWJGLService} for Celeritas */
 public final class SDLGPULWJGLService extends LWJGLService {
+
+    private static volatile boolean offeredAsAvailable;
+
+    public static boolean isOfferedAsAvailable() { return offeredAsAvailable; }
+
     @Override public int getPriority() {
-        if (SystemProperties.USE_SDL_GPU && SDLGPUGate.isSDLGPUAvailable()) {
-            return 200;
+        if (!SystemProperties.USE_SDL_GPU || !SDLGPUGate.isSDLGPUAvailable() || !SDLGPUGate.isEngaged()) {
+            return PRIORITY_UNAVAILABLE;
         }
-        return Integer.MIN_VALUE;
+        offeredAsAvailable = true;
+        return 200;
     }
 
     @Override public boolean isOpenGLVersionSupported(int major, int minor) {
@@ -148,22 +154,30 @@ public final class SDLGPULWJGLService extends LWJGLService {
     }
     @Override public void glDeleteSync(long sync) { BackendManager.RENDER_BACKEND.deleteSync(sync); }
 
-    private long[] queryTimestamps = new long[64];
+    private long[] queryElapsed = new long[64];
+    private int activeQueryId = -1;
+    private long activeQueryStart;
 
     private void ensureQueryCapacity(int id) {
-        if (id >= queryTimestamps.length) {
-            queryTimestamps = Arrays.copyOf(queryTimestamps, Math.max(id + 1, queryTimestamps.length * 2));
+        if (id >= queryElapsed.length) {
+            queryElapsed = Arrays.copyOf(queryElapsed, Math.max(id + 1, queryElapsed.length * 2));
         }
     }
 
     @Override public int glGenQueries() { return BackendManager.RENDER_BACKEND.genQueries(); }
     @Override public void glDeleteQueries(int query) { }
-    @Override public void glQueryCounter(int id, int target) {
+    @Override public void glBeginQuery(int target, int id) {
         ensureQueryCapacity(id);
-        queryTimestamps[id] = System.nanoTime();
+        activeQueryId = id;
+        activeQueryStart = System.nanoTime();
+    }
+    @Override public void glEndQuery(int target) {
+        if (activeQueryId < 0) return;
+        queryElapsed[activeQueryId] = System.nanoTime() - activeQueryStart;
+        activeQueryId = -1;
     }
     @Override public long glGetQueryObjectui64(int id, int pname) {
-        if (id >= 0 && id < queryTimestamps.length) return queryTimestamps[id];
+        if (id >= 0 && id < queryElapsed.length) return queryElapsed[id];
         return 0;
     }
 

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/SDLGPURenderBackend.java

@@ -7,6 +7,7 @@ import com.gtnewhorizons.angelica.glsm.CaptureGate;
 import com.gtnewhorizons.angelica.glsm.GLStateManager;
 import com.gtnewhorizons.angelica.glsm.profiling.Tracy;
 import com.gtnewhorizons.angelica.glsm.backend.GLDebugMessageListener;
+import com.gtnewhorizons.angelica.glsm.backend.VSyncMode;
 import com.gtnewhorizons.angelica.glsm.backend.RenderBackend;
 import com.gtnewhorizons.angelica.glsm.hooks.GLSMConfig;
 import com.gtnewhorizons.angelica.glsm.texture.TextureInfoCache;
@@ -17,6 +18,8 @@ import com.gtnewhorizons.angelica.sdlgpu.frame.ContextState;
 import com.gtnewhorizons.angelica.sdlgpu.frame.FenceTracker;
 import com.gtnewhorizons.angelica.sdlgpu.frame.FrameManager;
 import com.gtnewhorizons.angelica.sdlgpu.frame.FrameManager.FrameState;
+import com.gtnewhorizons.angelica.sdlgpu.frame.Presenter;
+import com.gtnewhorizons.retrofuturabootstrap.MainStartOnFirstThread;
 import com.gtnewhorizons.angelica.sdlgpu.pipeline.DrawDispatch;
 import com.gtnewhorizons.angelica.sdlgpu.pipeline.PipelineApplier;
 import com.gtnewhorizons.angelica.sdlgpu.pipeline.PipelineCache;
@@ -40,9 +43,10 @@ import com.gtnewhorizons.angelica.sdlgpu.sampler.StorageBufferBinder;
 import com.gtnewhorizons.angelica.sdlgpu.sampler.StorageTextureBinder;
 import com.gtnewhorizons.angelica.sdlgpu.shader.ShaderManager;
 import com.gtnewhorizons.angelica.sdlgpu.splash.SplashDispatcher;
-import com.gtnewhorizons.angelica.sdlgpu.splash.SplashOffscreenTarget;
+import com.gtnewhorizons.angelica.sdlgpu.frame.OffscreenTarget;
 import com.gtnewhorizons.angelica.sdlgpu.util.DebugLabels;
 import com.gtnewhorizons.angelica.sdlgpu.util.DebugMessageRelay;
+import com.gtnewhorizons.angelica.sdlgpu.util.ThreadRegistry;
 
 import it.unimi.dsi.fastutil.ints.Int2ObjectOpenHashMap;
 import it.unimi.dsi.fastutil.ints.IntOpenHashSet;
@@ -79,8 +83,8 @@ import java.util.List;
 import java.util.Locale;
 import java.util.Map;
 import java.util.Set;
-import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.BiConsumer;
 
 import org.lwjgl.sdl.SDLGPU;
@@ -96,7 +100,6 @@ import org.lwjglx.opengl.Display;
 import me.eigenraven.lwjgl3ify.api.DisplayEvents;
 import com.gtnewhorizons.angelica.sdlgpu.compat.Lwjgl3GLCapabilitiesShim;
 import me.eigenraven.lwjgl3ify.api.GLCapabilitiesOverride;
-import me.eigenraven.lwjgl3ify.api.SwapchainInvalidatingChange;
 
 import static org.lwjgl.sdl.SDLGPU.*;
 
@@ -106,8 +109,9 @@ public class SDLGPURenderBackend extends RenderBackend {
 
     private static final Tracy.ZoneId Z_SDL_INDIRECT_DRAW = Tracy.zoneId("sdlIndirectDraw", Tracy.COLOR_TERRAIN);
 
-    private final Device device = new Device();
+    private final Device device = SDLGPUGate.device();
     private final FrameManager frameManager = new FrameManager(device);
+    private Presenter presenter;
     private final ResourceManager resourceManager = new ResourceManager(device, frameManager);
     private final Image3DClear image3DClear = new Image3DClear();
     private final ShaderManager shaderManager = new ShaderManager(device);
@@ -151,33 +155,30 @@ public class SDLGPURenderBackend extends RenderBackend {
 
     private volatile boolean shutdown;
 
-    private SplashOffscreenTarget splashTarget;
+    private OffscreenTarget splashTarget;
 
-    private static final CopyOnWriteArrayList<ContextState> registeredStates = new CopyOnWriteArrayList<>();
-    private static final ThreadLocal<ContextState> tlState = ThreadLocal.withInitial(() -> {
+    private static final ThreadRegistry<ContextState> registeredStates = new ThreadRegistry<>(new ContextState[0]);
+    private static final ThreadLocal<ContextState> tlState = new ThreadLocal<>();
+
+    private static ContextState s() {
+        final ContextState sole = registeredStates.sole();
+        if (sole != null && sole.owner == Thread.currentThread()) return sole;
+        final ContextState st = tlState.get();
+        return st != null ? st : registerState();
+    }
+
+    private static ContextState registerState() {
         final ContextState st = new ContextState();
         for (int i = 0; i < ContextState.MAX_VERTEX_ATTRIBS; i++) st.attribDefaults[i * 4 + 3] = 1.0f;
         st.attribDefaults[4] = 1.0f; st.attribDefaults[5] = 1.0f;
         st.attribDefaults[6] = 1.0f;
+        tlState.set(st);
         registeredStates.add(st);
-        refreshSoleState();
         return st;
-    });
-
-    private static volatile ContextState soleState;
-
-    private static void refreshSoleState() {
-        soleState = registeredStates.size() == 1 ? registeredStates.get(0) : null;
-    }
-
-    private static ContextState s() {
-        final ContextState st = soleState;
-        if (st != null && st.owner == Thread.currentThread()) return st;
-        return tlState.get();
     }
 
     private void markAllPipelineInputDirty() {
-        for (ContextState st : registeredStates) st.pipeline.markInputDirty();
+        for (ContextState st : registeredStates.snapshot()) st.pipeline.markInputDirty();
     }
 
     public static final int CTR_SLOT_WRITES = 0;
@@ -189,7 +190,7 @@ public class SDLGPURenderBackend extends RenderBackend {
 
     public static void takeContextCounters(int[] out) {
         Arrays.fill(out, 0);
-        for (ContextState st : registeredStates) {
+        for (ContextState st : registeredStates.snapshot()) {
             out[CTR_SLOT_WRITES] += st.slotWrites;
             out[CTR_SLOT_WRITES_ELIDED] += st.slotWritesElided;
             out[CTR_SSBO_BINDS] += st.ssboBinds;
@@ -204,7 +205,7 @@ public class SDLGPURenderBackend extends RenderBackend {
     }
 
     private void releaseUniformStagingAllThreads(ShaderManager.ProgramObject prog) {
-        for (ContextState st : registeredStates) st.releaseUniformStaging(prog);
+        for (ContextState st : registeredStates.snapshot()) st.releaseUniformStaging(prog);
     }
 
 
@@ -213,8 +214,7 @@ public class SDLGPURenderBackend extends RenderBackend {
         persistentSync.onPersistentBufferWrite(glId, offset, size);
     }
 
-    @Override public void onPostWindowCreate(long window, boolean debug) {
-        device.claimWindow(window, debug);
+    @Override public void onPostWindowCreate(long window) {
         buildCachedStrings();
         populateGLCapabilities();
     }
@@ -227,6 +227,7 @@ public class SDLGPURenderBackend extends RenderBackend {
             LOG.info("SDL-GPU debug markers ENABLED (lwjglDebug={}, angelica.debug.markers={}, captureTool={})", lwjglDebugFlag, SystemProperties.DEBUG_MARKERS, CaptureGate.TOOL_ATTACHED);
         }
         frameManager.setResourceManager(resourceManager);
+        device.setLossDiagnostics(resourceManager::describeGpuState);
         frameManager.setBeforeEndCopyPassCallback(() -> resourceManager.flushBatchedUploads(frameManager.getCopyPass()));
         frameManager.setBeforeSubmitCallback(() -> {
             endComputeDispatchBatch();
@@ -234,7 +235,6 @@ public class SDLGPURenderBackend extends RenderBackend {
             drainDeferredPersistentRegions(s());
             debugLabels.popAutoDebugGroup(s());
         });
-        frameManager.setBeforePendingUploadSubmitCallback(textureOps::drainPendingMipGen);
         frameManager.setAfterPresentCallback(() -> {
             frameManager.requestFlushOnAllRegisteredFrames();
             resourceManager.drainPendingFreeShadows();
@@ -291,13 +291,19 @@ public class SDLGPURenderBackend extends RenderBackend {
         resourceManager.setBufferLivenessListener(this::markAllPipelineInputDirty);
         shaderManager.setUniformReleaseListener(this::releaseUniformStagingAllThreads);
         fenceTracker.setUnresolvedFenceFlush(this::midFrameFenceFlush);
+        frameManager.setMainThread(GLStateManager.getMainThread());
+        if (!SystemProperties.DISABLE_SDL_PRESENTER_THREAD) {
+            presenter = new Presenter(frameManager, MainStartOnFirstThread.instance());
+            frameManager.setPresenter(presenter);
+            LOG.info("SDL presenter thread enabled: presents run on '{}'", device.getWindowThread() != null ? device.getWindowThread().getName() : "window thread");
+        }
 
         final int splashW = Math.max(1, Display.getWidth());
         final int splashH = Math.max(1, Display.getHeight());
         final int[] maxDesktop = device.getMaxDesktopSizePixels();
         final int splashTexW = Math.max(splashW, maxDesktop[0]);
         final int splashTexH = Math.max(splashH, maxDesktop[1]);
-        splashTarget = new SplashOffscreenTarget();
+        splashTarget = new OffscreenTarget();
         splashTarget.create(device, resourceManager, splashTexW, splashTexH, device.getSwapchainTextureFormat());
         SplashDispatcher.seedDrawnSize(splashW, splashH);
         LOG.info("Splash offscreen target {}x{} (window {}x{}, max desktop {}x{})", splashTexW, splashTexH, splashW, splashH, maxDesktop[0], maxDesktop[1]);
@@ -377,13 +383,50 @@ public class SDLGPURenderBackend extends RenderBackend {
         LOG.info("Populated GL capabilities for SDL GPU backend");
     }
 
-    @Override public void setVSyncEnabled(boolean enabled) {
-        device.setVSyncEnabled(enabled);
+    private final AtomicReference<VSyncMode> pendingVSync = new AtomicReference<>();
+
+    @Override protected VSyncMode applyVSyncMode(VSyncMode preferred) {
+        pendingVSync.set(preferred);
+        return device.chooseVSyncMode(preferred);
     }
 
+    @Override public boolean supportsVSyncMode(VSyncMode mode) {
+        return device.supportsVSyncMode(mode);
+    }
+
+    private void applyPendingVSync() {
+        final VSyncMode preferred = pendingVSync.getAndSet(null);
+        if (preferred != null) {
+            if (presenter != null) presenter.drain();
+            publishVSyncMode(device.applyVSync(preferred));
+        }
+    }
+
+    @Override protected int queryDisplayRefreshRateHz() {
+        return device.getDisplayRefreshRateHz();
+    }
+
+    @Override public boolean gateAnchorsNextFrameStart() { return true; }
+
+    @Override public boolean wantsDisplayUpdateGateTiming() { return false; }
+
+    @Override public long lastFrameGateNanos() {
+        if (presenter != null && presenter.isEngaged()) return frameManager.windowFrame().lastFrameGateNanos;
+        return frameManager.lastFrameGateNanos();
+    }
+
+    @Override public long lastFrameGateEndNanos() {
+        if (presenter != null && presenter.isEngaged()) return frameManager.windowFrame().lastFrameGateEndNanos;
+        return frameManager.lastFrameGateEndNanos();
+    }
+
+    @Override public boolean hasSwapchainBackpressure() { return true; }
+
     @Override public void shutdown() {
         if (shutdown) return;
         shutdown = true;
+        if (presenter != null) presenter.drain();
+        frameManager.destroyFinalTarget();
         if (splashTarget != null) {
             splashTarget.destroy(resourceManager);
             splashTarget = null;
@@ -406,7 +449,7 @@ public class SDLGPURenderBackend extends RenderBackend {
         fenceTracker.dispose();
         frameManager.releaseAllRegisteredFrames();
         resourceManager.shutdownTexSamplerStates();
-        for (ContextState st : registeredStates) {
+        for (ContextState st : registeredStates.snapshot()) {
             if (st.fanIndexBuffer != 0) {
                 resourceManager.releaseBufferHandle(st.fanIndexBuffer);
                 st.fanIndexBuffer = 0;
@@ -424,7 +467,6 @@ public class SDLGPURenderBackend extends RenderBackend {
             clearMappedState(st);
         }
         registeredStates.clear();
-        soleState = null;
 
         drawDispatch.clearWarnedState();
         pipelineStore.shutdown();
@@ -434,7 +476,7 @@ public class SDLGPURenderBackend extends RenderBackend {
     }
 
     @Override public boolean isAvailable() {
-        return SystemProperties.USE_SDL_GPU && SDLGPUGate.isSDLGPUAvailable();
+        return SystemProperties.USE_SDL_GPU && SDLGPUGate.isSDLGPUAvailable() && SDLGPUGate.isEngaged();
     }
 
     @Override public String getName() {
@@ -463,13 +505,16 @@ public class SDLGPURenderBackend extends RenderBackend {
     }
 
     @Override public void onRenderThreadReleased(Thread t) {
+        if (shutdown || t == GLStateManager.getMainThread()) return;
         if (frameManager.isFrameActive()) {
             frameManager.endFrame();
         }
         frameManager.releaseThreadState();
-        registeredStates.remove(tlState.get());
-        tlState.remove();
-        refreshSoleState();
+        final ContextState st = tlState.get();
+        if (st != null) {
+            tlState.remove();
+            registeredStates.remove(st);
+        }
     }
 
     @Override public boolean handleMakeCurrent(Object drawable) {
@@ -483,12 +528,11 @@ public class SDLGPURenderBackend extends RenderBackend {
     }
 
     @Override public boolean handleReleaseContext(Object drawable) {
-        if (isSDLManagedDrawable(drawable)) {
-            Lwjgl3GLCapabilitiesShim.clearOnCurrentThread();
-            onRenderThreadReleased(Thread.currentThread());
-            return true;
-        }
-        return false;
+        if (!isSDLManagedDrawable(drawable)) return false;
+        if (Thread.currentThread() == GLStateManager.getMainThread()) return true;
+        Lwjgl3GLCapabilitiesShim.clearOnCurrentThread();
+        onRenderThreadReleased(Thread.currentThread());
+        return true;
     }
 
     private static boolean isSDLManagedDrawable(Object drawable) {
@@ -511,33 +555,19 @@ public class SDLGPURenderBackend extends RenderBackend {
         return true;
     }
 
-    public void dispatchSplashBlit(SplashOffscreenTarget target) {
+    public void dispatchSplashBlit(OffscreenTarget target) {
         if (shutdown || target == null) return;
-        onFrameBegin();
-        final FrameManager.FrameState f = frameManager.frame();
-        if (!frameManager.ensureSwapchainAcquired(f)) {
-            onFrameEnd();
-            return;
-        }
-        frameManager.endCopyPassIfActive();
-        frameManager.endRenderPassIfActive();
         final long drawnSize = SplashDispatcher.getDrawnSize();
         final int srcW = Math.max(1, Math.min((int) (drawnSize >> 32), target.width()));
         final int srcH = Math.max(1, Math.min((int) drawnSize, target.height()));
-        try (var stack = MemoryStack.stackPush()) {
-            final var info = SDL_GPUBlitInfo.calloc(stack);
-            info.source(s -> s.texture(target.colorTexture()).x(0).y(0).w(srcW).h(srcH));
-            info.destination(d -> d.texture(f.swapchainTexture).x(0).y(0).w(f.swapchainWidth).h(f.swapchainHeight));
-            info.filter(SDL_GPU_FILTER_LINEAR);
-            info.flip_mode(SDLSurface.SDL_FLIP_VERTICAL);
-            SDL_BlitGPUTexture(f.commandBuffer, info);
-        }
-        f.swapchainUsedThisFrame = true;
-        onFrameEnd();
+        final FrameState f = frameManager.frame();
+        frameManager.presentBlit(f, target.colorTexture(), srcW, srcH, SDLSurface.SDL_FLIP_VERTICAL);
+        f.presentedThisFrame = false;
     }
 
     @Override public void onFrameBegin() {
         if (shutdown) return;
+        if (GLStateManager.isSplashComplete()) applyPendingVSync();
         frameManager.beginFrame();
         beginFrameInit();
     }
@@ -551,9 +581,13 @@ public class SDLGPURenderBackend extends RenderBackend {
         }
         ResourceManager.setSingleThreadedReads(GLStateManager.isSplashComplete());
         st.clearedTexturesThisFrame.clear();
+        st.clearedStencilTexturesThisFrame.clear();
         st.pendingColorTextures.clear();
         st.pendingDepthTextures.clear();
+        st.pendingStencilTextures.clear();
         st.pendingSwapchainClear = false;
+        st.pendingSwapchainDepthClear = false;
+        st.pendingSwapchainStencilClear = false;
         st.uniformBlocks[0].flushedThisFrame = false;
         st.uniformBlocks[1].flushedThisFrame = false;
         st.fanIndexBufferOffset = 0;
@@ -615,22 +649,24 @@ public class SDLGPURenderBackend extends RenderBackend {
         endFrameUploadFlushNoWait();
 
         final FrameState f = frameManager.frame();
-        if (f.frameActive && !f.swapchainUsedThisFrame) {
+        if (f.frameActive && !f.fbo0UsedThisFrame) {
             if (!emptyFrameWarned) {
                 emptyFrameWarned = true;
-                LOG.info("Frame {} ended without drawing to the swapchain; skipping present (further occurrences counted in sdl.emptyFrames)", f.frameNumber);
+                LOG.info("Frame {} ended without drawing to FBO 0; presenting the previous contents (further occurrences counted in sdl.emptyFrames)", f.frameNumber);
             }
             frameManager.markFrameEmpty(f);
         }
 
         awaitUploadFlush();
         frameManager.endFrame();
+        frameManager.presentFinalTarget();
         fenceTracker.resolvePendingFences();
         resourceManager.flushDeferredReleases();
         resourceManager.recycleGpuBufferPool(frameManager.getFrameNumber());
     }
 
-    @Override public void onPreSwapchainInvalidatingChange(SwapchainInvalidatingChange change) {
+    @Override public void onPreSwapchainInvalidatingChange(Object change) {
+        if (presenter != null) presenter.drain();
         endFrameUploadFlush();
         if (frameManager.isFrameActive()) {
             frameManager.endFrame();
@@ -871,18 +907,19 @@ public class SDLGPURenderBackend extends RenderBackend {
     }
 
     @Override public void clearDepth(double depth) { s().depthClearValue = (float) depth; }
-    @Override public void clearStencil(int s) {}
+    @Override public void clearStencil(int s) { s().stencilClearValue = s & 0xFF; }
 
     @Override public void clear(int mask) {
         final ContextState cs = s();
         if (!frameManager.isFrameActive()) return;
         final boolean wantColor = (mask & GL11.GL_COLOR_BUFFER_BIT) != 0;
         final boolean wantDepth = (mask & GL11.GL_DEPTH_BUFFER_BIT) != 0;
-        if (!wantColor && !wantDepth) return;
+        final boolean wantStencil = (mask & GL11.GL_STENCIL_BUFFER_BIT) != 0;
+        if (!wantColor && !wantDepth && !wantStencil) return;
 
         final ContextState st = cs;
 
-        // Swapchain path: just record pending state; ensureSwapchainRenderPass consumes it lazily.
+        // FBO0 path: just record pending state; ensureFbo0RenderPass consumes it lazily.
         if (st.boundFboId == 0) {
             if (wantColor) {
                 st.pendingSwapchainClear = true;
@@ -891,7 +928,15 @@ public class SDLGPURenderBackend extends RenderBackend {
                 st.pendingSwapchainB = st.clearB;
                 st.pendingSwapchainA = st.clearA;
             }
-            // swapchain has no depth attachment in this backend; ignore wantDepth
+            final int swapDepthFormat = resourceManager.getSwapchainDepthStencilFormat();
+            if (wantDepth && swapDepthFormat != 0) {
+                st.pendingSwapchainDepthClear = true;
+                st.pendingSwapchainDepth = st.depthClearValue;
+            }
+            if (wantStencil && PixelOps.isDepthStencilFormat(swapDepthFormat)) {
+                st.pendingSwapchainStencilClear = true;
+                st.pendingSwapchainStencil = st.stencilClearValue;
+            }
             return;
         }
 
@@ -916,6 +961,10 @@ public class SDLGPURenderBackend extends RenderBackend {
             FBOClearTracker.recordPendingDepthClear(st, fbo.depthTexture, cs.depthClearValue);
             if (passActive && fbo.depthTexture == activeDepth) affectsActivePass = true;
         }
+        if (wantStencil && fbo.depthTexture != 0 && PixelOps.isDepthStencilFormat(fbo.depthFormat)) {
+            FBOClearTracker.recordPendingStencilClear(st, fbo.depthTexture, cs.stencilClearValue);
+            if (passActive && fbo.depthTexture == activeDepth) affectsActivePass = true;
+        }
 
         if (affectsActivePass) {
             frameManager.endRenderPassIfActive();
@@ -1461,14 +1510,12 @@ public class SDLGPURenderBackend extends RenderBackend {
         if (framebuffer == 0) {
             cs.pipeline.setColorTargetFormats(cachedSwapchainFormatArray);
             cs.pipeline.setDrawBuffers(null);
-            cs.pipeline.hasDepthTarget = false;
-            cs.pipeline.depthTargetFormat = 0;
+            cs.pipeline.setDepthTargetFormat(resourceManager.getSwapchainDepthStencilFormat());
         } else {
             final FboState fbo = resourceManager.getFbo(framebuffer);
             if (fbo != null && fbo.getColorTexture() != 0) {
                 fboClearTracker.updatePipelineCacheColorFormats(cs, fbo);
-                cs.pipeline.hasDepthTarget = fbo.depthTexture != 0;
-                cs.pipeline.depthTargetFormat = fbo.depthFormat;
+                cs.pipeline.setDepthTargetFormat(fbo.depthTexture != 0 ? fbo.depthFormat : 0);
             }
         }
         cs.pipeline.markOutputDirty();
@@ -1505,14 +1552,23 @@ public class SDLGPURenderBackend extends RenderBackend {
             fbo.cachedFormatsDirty = true;
             fboClearTracker.updatePipelineCacheColorFormats(cs, fbo);
             cs.pipeline.markOutputDirty();
-        } else if (attachment == GL30.GL_DEPTH_ATTACHMENT || attachment == GL30.GL_DEPTH_STENCIL_ATTACHMENT) {
+        } else if (attachment == GL30.GL_DEPTH_ATTACHMENT || attachment == GL30.GL_DEPTH_STENCIL_ATTACHMENT || attachment == GL30.GL_STENCIL_ATTACHMENT) {
+            final boolean stencilOnly = attachment == GL30.GL_STENCIL_ATTACHMENT;
             if (texture == 0) {
+                if (stencilOnly && fbo.depthGlId != 0) return;
                 fbo.detachDepth();
                 cs.pipeline.hasDepthTarget = false;
                 cs.pipeline.depthTargetFormat = 0;
                 cs.pipeline.markOutputDirty();
                 return;
             }
+            if (stencilOnly && fbo.depthGlId != 0 && fbo.depthGlId != texture) {
+                if (!warnedSplitStencilAttachment) {
+                    warnedSplitStencilAttachment = true;
+                    LOG.warn("Separate stencil attachment (tex {}) on an FBO whose depth attachment is tex {}; SDL has no separate stencil aspect, keeping depth", texture, fbo.depthGlId);
+                }
+                return;
+            }
             final long handle = resourceManager.ensureTextureUsage(texture, SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET);
             final ResourceManager.TextureMeta meta = resourceManager.getTextureMeta(texture);
             fbo.depthTexture = handle;
@@ -1621,7 +1677,7 @@ public class SDLGPURenderBackend extends RenderBackend {
         final long texHandle;
         final int srcSdlFormat;
         if (cs.boundReadFboId == 0) {
-            texHandle = frameManager.getSwapchainTexture();
+            texHandle = frameManager.getFbo0Texture();
             srcSdlFormat = frameManager.getSwapchainFormat();
         } else {
             final FboState fbo = resourceManager.getFbo(cs.boundReadFboId);
@@ -1676,22 +1732,67 @@ public class SDLGPURenderBackend extends RenderBackend {
     }
 
     @Override public int getFramebufferAttachmentParameteri(int target, int attachment, int pname) {
-        final FboState fbo = resourceManager.getFbo(s().boundFboId);
+        final ContextState cs = s();
+        final int fboId = target == GL30.GL_READ_FRAMEBUFFER ? cs.boundReadFboId : cs.boundFboId;
+        if (fboId == 0) {
+            final int colorFormat = cachedSwapchainFormatArray != null ? cachedSwapchainFormatArray[0] : 0;
+            return defaultFramebufferAttachmentParameteri(attachment, pname, colorFormat, resourceManager.getSwapchainDepthStencilFormat());
+        }
+        return fboAttachmentParameteri(resourceManager.getFbo(fboId), attachment, pname);
+    }
+
+    static int fboAttachmentParameteri(FboState fbo, int attachment, int pname) {
         if (fbo == null) return 0;
         final int colorIdx = attachment - GL30.GL_COLOR_ATTACHMENT0;
         final boolean isColor = (colorIdx >= 0 && colorIdx < ContextState.MAX_COLOR_ATTACHMENTS);
-        final boolean isDepth = (attachment == GL30.GL_DEPTH_ATTACHMENT || attachment == GL30.GL_DEPTH_STENCIL_ATTACHMENT);
+        final boolean isDepth = (attachment == GL30.GL_DEPTH_ATTACHMENT || attachment == GL30.GL_DEPTH_STENCIL_ATTACHMENT || attachment == GL30.GL_STENCIL_ATTACHMENT || attachment == GL11.GL_DEPTH || attachment == GL11.GL_STENCIL);
+        final boolean colorPresent = isColor && fbo.colorGlIds[colorIdx] != 0;
+        final boolean depthPresent = isDepth && fbo.depthGlId != 0;
+
         if (pname == GL30.GL_FRAMEBUFFER_ATTACHMENT_OBJECT_NAME) {
-            return isColor ? fbo.colorGlIds[colorIdx] : isDepth ? fbo.depthGlId : 0;
+            return colorPresent ? fbo.colorGlIds[colorIdx] : depthPresent ? fbo.depthGlId : 0;
         }
         if (pname == GL30.GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE) {
-            if (isColor && fbo.colorGlIds[colorIdx] != 0) return GL11.GL_TEXTURE;
-            if (isDepth && fbo.depthGlId != 0) return GL11.GL_TEXTURE;
-            return GL11.GL_NONE;
+            return (colorPresent || depthPresent) ? GL11.GL_TEXTURE : GL11.GL_NONE;
         }
+        if (colorPresent) return colorAttachmentSize(fbo.colorFormats[colorIdx], pname);
+        if (depthPresent) return depthAttachmentSize(fbo.depthFormat, pname);
         return 0;
     }
 
+    static int defaultFramebufferAttachmentParameteri(int attachment, int pname, int colorFormat, int depthFormat) {
+        final boolean isDepth = attachment == GL11.GL_DEPTH || attachment == GL11.GL_STENCIL || attachment == GL30.GL_DEPTH_ATTACHMENT || attachment == GL30.GL_STENCIL_ATTACHMENT || attachment == GL30.GL_DEPTH_STENCIL_ATTACHMENT;
+        if (isDepth) {
+            if (depthFormat == 0) {
+                return pname == GL30.GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE ? GL11.GL_NONE : 0;
+            }
+            if (pname == GL30.GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE) return GL30.GL_FRAMEBUFFER_DEFAULT;
+            if (pname == GL30.GL_FRAMEBUFFER_ATTACHMENT_OBJECT_NAME) return 0;
+            return depthAttachmentSize(depthFormat, pname);
+        }
+        if (pname == GL30.GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE) return GL30.GL_FRAMEBUFFER_DEFAULT;
+        if (pname == GL30.GL_FRAMEBUFFER_ATTACHMENT_OBJECT_NAME) return 0;
+        return colorAttachmentSize(colorFormat, pname);
+    }
+
+    private static int colorAttachmentSize(int sdlFormat, int pname) {
+        return switch (pname) {
+            case GL30.GL_FRAMEBUFFER_ATTACHMENT_RED_SIZE -> PixelOps.colorChannelBits(sdlFormat, 0);
+            case GL30.GL_FRAMEBUFFER_ATTACHMENT_GREEN_SIZE -> PixelOps.colorChannelBits(sdlFormat, 1);
+            case GL30.GL_FRAMEBUFFER_ATTACHMENT_BLUE_SIZE -> PixelOps.colorChannelBits(sdlFormat, 2);
+            case GL30.GL_FRAMEBUFFER_ATTACHMENT_ALPHA_SIZE -> PixelOps.colorChannelBits(sdlFormat, 3);
+            default -> 0;
+        };
+    }
+
+    private static int depthAttachmentSize(int sdlFormat, int pname) {
+        return switch (pname) {
+            case GL30.GL_FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE -> PixelOps.depthBits(sdlFormat);
+            case GL30.GL_FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE -> PixelOps.stencilBits(sdlFormat);
+            default -> 0;
+        };
+    }
+
     @Override public int createShader(int type) { return shaderManager.createShader(type); }
     @Override public void deleteShader(int shader) { shaderManager.deleteShader(shader); }
     @Override public void shaderSource(int shader, CharSequence source) { shaderManager.shaderSource(shader, source); }
@@ -3201,6 +3302,8 @@ public class SDLGPURenderBackend extends RenderBackend {
             case GL11.GL_DRAW_BUFFER -> drawBufferEnum(cs.boundFboId);
             case GL11.GL_READ_BUFFER -> readBufferEnum(cs.boundReadFboId);
             case GL11.GL_TEXTURE_BINDING_2D -> boundTextureOf(cs.activeTextureUnit, cs.boundTextures);
+            case GL11.GL_DEPTH_BITS -> getFramebufferAttachmentParameteri(GL30.GL_DRAW_FRAMEBUFFER, GL11.GL_DEPTH, GL30.GL_FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE);
+            case GL11.GL_STENCIL_BITS -> getFramebufferAttachmentParameteri(GL30.GL_DRAW_FRAMEBUFFER, GL11.GL_STENCIL, GL30.GL_FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE);
             default -> {
                 final int limit = deviceLimit(pname);
                 yield limit >= 0 ? limit : unknownGetInteger(pname);
@@ -3521,7 +3624,7 @@ public class SDLGPURenderBackend extends RenderBackend {
     private int voxLocStart = -1;
     private int voxLocCount = -1;
 
-    public boolean bindVoxelizationRegion(int ssboBinding, int vertexBufferGlId, long openPass, float x, float y, float z) {
+    @Override public boolean bindVoxelizationRegion(int ssboBinding, int vertexBufferGlId, long openPass, float x, float y, float z) {
         if (ssboBinding < 0 || ssboBinding >= ContextState.MAX_INDEXED_BUFFERS || vertexBufferGlId == 0) return false;
         final ContextState st = s();
         if (st.boundProgram == 0) return false;
@@ -3540,7 +3643,7 @@ public class SDLGPURenderBackend extends RenderBackend {
         return names == null ? new String[0] : names.clone();
     }
 
-    public long beginVoxelizationBatch(int ssboBinding) {
+    @Override public long beginVoxelizationBatch(int ssboBinding) {
         if (ssboBinding < 0 || ssboBinding >= ContextState.MAX_INDEXED_BUFFERS) return 0;
         final ContextState st = s();
         final int program = st.boundProgram;
@@ -3550,11 +3653,11 @@ public class SDLGPURenderBackend extends RenderBackend {
         return voxelizationDispatcher.beginBatch(st);
     }
 
-    public void voxelizeRange(long pass, int vertexOffset, int vertexCount) {
+    @Override public void voxelizeRange(long pass, int vertexOffset, int vertexCount) {
         voxelizationDispatcher.dispatchRange(pass, voxLocStart, voxLocCount, vertexOffset, vertexCount, s());
     }
 
-    public void endVoxelizationBatch(long pass) {
+    @Override public void endVoxelizationBatch(long pass) {
         voxelizationDispatcher.endBatch(pass);
     }
 
@@ -3648,6 +3751,7 @@ public class SDLGPURenderBackend extends RenderBackend {
     }
 
     private boolean warnedMSAARenderbuffer = false;
+    private boolean warnedSplitStencilAttachment = false;
 
     @Override
     public void renderbufferStorageMultisample(int target, int samples, int internalformat, int width, int height) {

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/device/Device.java

@@ -1,7 +1,8 @@
 package com.gtnewhorizons.angelica.sdlgpu.device;
 
 import com.gtnewhorizons.angelica.config.SystemProperties;
-import com.gtnewhorizons.angelica.sdlgpu.SDLGPUGate;
+import com.gtnewhorizons.angelica.glsm.backend.VSyncMode;
+import com.gtnewhorizons.angelica.glsm.backend.RenderBackend;
 import com.gtnewhorizons.angelica.sdlgpu.util.DebugMessageRelay;
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
@@ -12,12 +13,15 @@ import org.lwjgl.sdl.SDLStdinc;
 import org.lwjgl.sdl.SDL_DisplayMode;
 import org.lwjgl.sdl.SDL_LogOutputFunction;
 import org.lwjgl.sdl.SDLVersion;
+import org.lwjgl.sdl.SDLVulkan;
 import org.lwjgl.system.MemoryStack;
 import org.lwjgl.system.MemoryUtil;
 import org.lwjgl.system.Platform;
 import org.lwjglx.opengl.Display;
 
 import java.nio.IntBuffer;
+import java.util.List;
+import java.util.function.Supplier;
 
 import static org.lwjgl.sdl.SDLGPU.*;
 import static org.lwjgl.sdl.SDLHints.SDL_HINT_GPU_DRIVER;
@@ -28,23 +32,65 @@ import static org.lwjgl.system.MemoryUtil.memUTF8;
 public final class Device {
     private static final Logger LOG = LogManager.getLogger("Angelica-SDLGPU");
 
-    public static final int FRAMES_IN_FLIGHT = 3;
+    public static final int MAX_FRAMES_IN_FLIGHT = 3;
+
+    private static final int FRAMES_IN_FLIGHT = Math.min(Math.max(SystemProperties.SDL_FRAMES_IN_FLIGHT, 1), MAX_FRAMES_IN_FLIGHT);
+
+    public static int framesInFlight() { return FRAMES_IN_FLIGHT; }
+
+    private static final int REQUESTED_SHADER_FORMATS = SDL_GPU_SHADERFORMAT_SPIRV | SDL_GPU_SHADERFORMAT_MSL | SDL_GPU_SHADERFORMAT_DXBC | SDL_GPU_SHADERFORMAT_DXIL;
 
     private long device;
+    private boolean claimed;
     private int supportedShaderFormats;
     private String driverName;
     private String deviceName;
     private String driverVersion;
     private String driverInfo;
-    private int presentMode = SDL_GPU_PRESENTMODE_VSYNC;
+    private VSyncMode vsyncMode = VSyncMode.ON;
+    private volatile Thread windowThread;
     private SDL_LogOutputFunction logCallback; // prevent GC
 
+    private volatile boolean lost;
+    private volatile Supplier<String> lossDiagnostics = () -> "";
+
+    public boolean isLost() { return lost; }
+
+    public void setLossDiagnostics(Supplier<String> diagnostics) { this.lossDiagnostics = diagnostics; }
+
+    public static boolean isDeviceLossError(String sdlError) {
+        if (sdlError == null) return false;
+        return sdlError.contains("DEVICE_LOST") || sdlError.contains("DEVICE_REMOVED") || sdlError.contains("DEVICE_RESET");
+    }
+
+    public void reportGpuFailure(String operation) {
+        if (lost) return;
+        final String err = SDLError.SDL_GetError();
+        if (!isDeviceLossError(err)) {
+            LOG.error("{}: {}", operation, err);
+            return;
+        }
+        lost = true;
+        LOG.error("GPU DEVICE LOST during {}: {}", operation, err);
+        LOG.error("  gpu={} driver={} {} sdl={}", deviceName, driverName, driverVersion, SDLVersion.SDL_GetVersion());
+        for (final String line : lossDiagnostics.get().split("\n")) {
+            LOG.error("  {}", line);
+        }
+        throw new GpuDeviceLostException(operation, err);
+    }
+
     // Default to vulkan for now until D3D is more tested
     static String resolveDriverName(String userHint, boolean windows) {
         return userHint.isEmpty() && windows ? "vulkan" : null;
     }
 
-    public void claimWindow(long window, boolean lwjglDebug) {
+    static boolean metalNeedsNewerSdl(String driverName, int sdlVersion) {
+        return "metal".equalsIgnoreCase(driverName) && sdlVersion < SDLVersion.SDL_VERSIONNUM(3, 4, 6);
+    }
+
+    public boolean createDevice() {
+        if (device != 0) return true;
+
         installLogCallback();
 
         final int ver = SDLVersion.SDL_GetVersion();
@@ -56,17 +102,15 @@ public final class Device {
             LOG.info("SDL GPU driver hint set to '{}'", driverHint);
         }
 
-        final int requestedFormats = SDL_GPU_SHADERFORMAT_SPIRV | SDL_GPU_SHADERFORMAT_MSL | SDL_GPU_SHADERFORMAT_DXBC | SDL_GPU_SHADERFORMAT_DXIL;
-
-        final boolean gpuDebug = lwjglDebug || SystemProperties.SDL_GPU_DEBUG;
+        final boolean gpuDebug = SystemProperties.LWJGL_DEBUG || SystemProperties.SDL_GPU_DEBUG;
         final String forcedDriver = resolveDriverName(driverHint, Platform.get() == Platform.WINDOWS);
-        device = SDL_CreateGPUDevice(requestedFormats, gpuDebug, forcedDriver);
-        if (device == 0 && forcedDriver != null) {
-            LOG.warn("Failed to create a '{}' SDL GPU device ({}); falling back to SDL's default backend. Set -D{} to pin one.", forcedDriver, SDLError.SDL_GetError(), SystemProperties.KEY_SDL_GPU_DRIVER);
-            device = SDL_CreateGPUDevice(requestedFormats, gpuDebug, (CharSequence) null);
+        device = createGPUDevice(gpuDebug, forcedDriver);
+        if (device == 0 && VideoDriverRecovery.shouldRetryOnX11(SDL_GetCurrentVideoDriver(), vulkanLoaderAvailable(), System.getenv("DISPLAY"))) {
+            device = VideoDriverRecovery.retryUnderX11(() -> createGPUDevice(gpuDebug, forcedDriver));
         }
         if (device == 0) {
-            throw new RuntimeException("Failed to create SDL GPU device: " + SDLError.SDL_GetError());
+            logDeviceCreationFailure(REQUESTED_SHADER_FORMATS);
+            return false;
         }
 
         driverName = SDL_GetGPUDeviceDriver(device);
@@ -77,12 +121,29 @@ public final class Device {
         driverVersion = SDLProperties.SDL_GetStringProperty(props, SDL_PROP_GPU_DEVICE_DRIVER_VERSION_STRING, "");
         driverInfo = SDLProperties.SDL_GetStringProperty(props, SDL_PROP_GPU_DEVICE_DRIVER_INFO_STRING, "");
 
-        LOG.info("SDL GPU device created: gpu={}, driver={} {}, formats=0x{}, debug={}, forcedDriver={}", deviceName, driverName, driverVersion, Integer.toHexString(supportedShaderFormats), gpuDebug, forcedDriver);
+        LOG.info("SDL GPU device created: gpu={}, driver={} {}, video={}, formats=0x{}, debug={}, forcedDriver={}", deviceName, driverName, driverVersion, SDL_GetCurrentVideoDriver(), Integer.toHexString(supportedShaderFormats), gpuDebug, forcedDriver);
 
-        if ("metal".equalsIgnoreCase(driverName) && ver < SDLVersion.SDL_VERSIONNUM(3, 4, 6)) {
-            LOG.fatal("SDL GPU on Metal requires SDL 3.4.6 or newer; exiting");
-            SDLGPUGate.markFatalInit();
-            return;
+        if (metalNeedsNewerSdl(driverName, ver)) {
+            LOG.error("SDL GPU on Metal requires SDL 3.4.6 or newer (have {}.{}.{}); falling back to OpenGL", SDLVersion.SDL_VERSIONNUM_MAJOR(ver), SDLVersion.SDL_VERSIONNUM_MINOR(ver), SDLVersion.SDL_VERSIONNUM_MICRO(ver));
+            destroyDevice();
+            return false;
+        }
+
+        return true;
+    }
+
+    private long createGPUDevice(boolean gpuDebug, String forcedDriver) {
+        long dev = SDL_CreateGPUDevice(REQUESTED_SHADER_FORMATS, gpuDebug, forcedDriver);
+        if (dev == 0 && forcedDriver != null) {
+            LOG.warn("Failed to create a '{}' SDL GPU device ({}); falling back to SDL's default backend. Set -D{} to pin one.", forcedDriver, SDLError.SDL_GetError(), SystemProperties.KEY_SDL_GPU_DRIVER);
+            dev = SDL_CreateGPUDevice(REQUESTED_SHADER_FORMATS, gpuDebug, (CharSequence) null);
+        }
+        return dev;
+    }
+
+    public void claimWindow(long window) {
+        if (device == 0) {
+            throw new IllegalStateException("SDL GPU device not created");
         }
 
         if (window == 0) {
@@ -92,18 +153,66 @@ public final class Device {
         if (!SDL_ClaimWindowForGPUDevice(device, window)) {
             throw new RuntimeException("Failed to claim window for SDL GPU device: " + SDLError.SDL_GetError());
         }
+        claimed = true;
+        windowThread = Thread.currentThread();
 
-        final int n = FRAMES_IN_FLIGHT;
-        if (!SDL_SetGPUAllowedFramesInFlight(device, n)) {
-            LOG.warn("SDL_SetGPUAllowedFramesInFlight({}) failed: {}", n, SDLError.SDL_GetError());
+        if (!SDL_SetGPUAllowedFramesInFlight(device, FRAMES_IN_FLIGHT)) {
+            LOG.warn("SDL_SetGPUAllowedFramesInFlight({}) failed: {}", FRAMES_IN_FLIGHT, SDLError.SDL_GetError());
         } else {
-            LOG.info("SDL frames-in-flight set to {}", n);
+            LOG.info("SDL frames-in-flight set to {}", FRAMES_IN_FLIGHT);
         }
 
         logWindowDiagnostics(window);
         LOG.info("SDL GPU device claimed window successfully");
     }
 
+    private static boolean vulkanLoaderAvailable() {
+        if (Platform.get() == Platform.MACOSX) return false;
+        if (!SDLVulkan.SDL_Vulkan_LoadLibrary((CharSequence) null)) return false;
+        SDLVulkan.SDL_Vulkan_UnloadLibrary();
+        return true;
+    }
+
+    private static void logDeviceCreationFailure(int requestedFormats) {
+        final StringBuilder drivers = new StringBuilder();
+        final int n = SDL_GetNumGPUDrivers();
+        for (int i = 0; i < n; i++) {
+            if (i > 0) drivers.append(", ");
+            drivers.append(SDL_GetGPUDriver(i));
+        }
+        final String videoDriver = SDL_GetCurrentVideoDriver();
+        LOG.error("SDL GPU device creation failed. platform={}, videoDriver={}, requestedShaderFormats=0x{}, compiledGpuDrivers=[{}]", Platform.get(), videoDriver, Integer.toHexString(requestedFormats), drivers);
+
+        if (Platform.get() != Platform.MACOSX) {
+            if (SDLVulkan.SDL_Vulkan_LoadLibrary((CharSequence) null)) {
+                SDLVulkan.SDL_Vulkan_UnloadLibrary();
+                LOG.error("A Vulkan loader is present, so no GPU met SDL's requirements");
+            } else {
+                LOG.error("No usable Vulkan loader: {}", SDLError.SDL_GetError());
+                if (!"x11".equalsIgnoreCase(videoDriver)) {
+                    LOG.error("Retrying under SDL_VIDEODRIVER=x11 did not help either.");
+                }
+            }
+        }
+        LOG.error("Continuing on OpenGL. Set -D{}=false to skip this probe entirely.", SystemProperties.KEY_USE_SDL_GPU);
+    }
+
+    public void destroyDevice() {
+        if (device == 0) return;
+        if (claimed) {
+            final long window = Display.getWindow();
+            if (window != 0) SDL_ReleaseWindowFromGPUDevice(device, window);
+            claimed = false;
+        }
+        SDL_DestroyGPUDevice(device);
+        device = 0;
+        driverName = null;
+        deviceName = null;
+        driverVersion = null;
+        driverInfo = null;
+        supportedShaderFormats = 0;
+    }
+
     private void logWindowDiagnostics(long window) {
         final long flags = SDL_GetWindowFlags(window);
         final boolean hasMetal = (flags & SDL_WINDOW_METAL) != 0;
@@ -146,12 +255,7 @@ public final class Device {
 
     public void shutdown() {
         if (device != 0) {
-            final long window = Display.getWindow();
-            if (window != 0) {
-                SDL_ReleaseWindowFromGPUDevice(device, window);
-            }
-            SDL_DestroyGPUDevice(device);
-            device = 0;
+            destroyDevice();
             LOG.info("SDL GPU device destroyed");
         }
     }
@@ -164,6 +268,10 @@ public final class Device {
         return driverName;
     }
 
+    public Thread getWindowThread() {
+        return windowThread;
+    }
+
     public String getDeviceName() {
         return deviceName;
     }
@@ -192,22 +300,89 @@ public final class Device {
         return (supportedShaderFormats & SDL_GPU_SHADERFORMAT_DXBC) != 0;
     }
 
-    public void setVSyncEnabled(boolean enabled) {
+    private static final List<VSyncMode> ON_ORDER = List.of(VSyncMode.ON);
+    private static final List<VSyncMode> OFF_ORDER = List.of(VSyncMode.OFF, VSyncMode.ON);
+    private static final List<VSyncMode> MAILBOX_ORDER = List.of(VSyncMode.MAILBOX, VSyncMode.ON);
+
+    private static List<VSyncMode> presentModeOrder(VSyncMode preferred) {
+        return switch (preferred) {
+            case MAILBOX -> MAILBOX_ORDER;
+            case OFF -> OFF_ORDER;
+            default -> ON_ORDER;
+        };
+    }
+
+    public VSyncMode chooseVSyncMode(VSyncMode preferred) {
+        for (VSyncMode candidate : presentModeOrder(preferred)) {
+            if (supportsVSyncMode(candidate)) return candidate;
+        }
+        return vsyncMode;
+    }
+
+    public VSyncMode applyVSync(VSyncMode preferred) {
+        if (device == 0 || !claimed) return vsyncMode;
         final long window = Display.getWindow();
-        final int mode;
-        if (enabled) {
-            mode = SDL_GPU_PRESENTMODE_VSYNC;
-        } else if (SDL_WindowSupportsGPUPresentMode(device, window, SDL_GPU_PRESENTMODE_MAILBOX)) {
-            mode = SDL_GPU_PRESENTMODE_MAILBOX;
-        } else {
-            mode = SDL_GPU_PRESENTMODE_IMMEDIATE;
+        final List<VSyncMode> order = presentModeOrder(preferred);
+        for (VSyncMode candidate : order) {
+            final int sdlMode = toSdl(candidate);
+            if (!SDL_WindowSupportsGPUPresentMode(device, window, sdlMode)) continue;
+            if (!SDL_SetGPUSwapchainParameters(device, window, SDL_GPU_SWAPCHAINCOMPOSITION_SDR, sdlMode)) {
+                LOG.warn("Failed to set present mode {}: {}", candidate, SDLError.SDL_GetError());
+                continue;
+            }
+            if (candidate != order.get(0)) {
+                LOG.warn("Present mode {} is not supported by this window; using {} instead", order.get(0), candidate);
+            }
+            vsyncMode = candidate;
+            LOG.info("SDL present mode {} (preferred={}), refresh {}Hz, {}, video={}, framesInFlight={}, supported: vsync={} immediate={} mailbox={}",
+                candidate, preferred, getDisplayRefreshRateHz(),
+                (SDL_GetWindowFlags(window) & SDL_WINDOW_FULLSCREEN) != 0 ? "fullscreen" : "windowed",
+                SDL_GetCurrentVideoDriver(), FRAMES_IN_FLIGHT,
+                supportsVSyncMode(VSyncMode.ON), supportsVSyncMode(VSyncMode.OFF), supportsVSyncMode(VSyncMode.MAILBOX));
+            return candidate;
         }
-        if (!SDL_SetGPUSwapchainParameters(device, window, SDL_GPU_SWAPCHAINCOMPOSITION_SDR, mode)) {
-            LOG.warn("Failed to set present mode {}: {} (keeping prior mode {})", mode, SDLError.SDL_GetError(), presentMode);
-            return;
+        LOG.warn("No usable present mode for preference {}; keeping {}", preferred, vsyncMode);
+        return vsyncMode;
+    }
+
+    public boolean supportsVSyncMode(VSyncMode mode) {
+        return device != 0 && claimed && SDL_WindowSupportsGPUPresentMode(device, Display.getWindow(), toSdl(mode));
+    }
+
+    public long getClaimedWindow() {
+        return device != 0 && claimed ? Display.getWindow() : 0L;
+    }
+
+    public boolean wasWindowResized() {
+        return getClaimedWindow() != 0L && Display.wasResized();
+    }
+
+    public long getWindowSizeInPixels() {
+        final long window = getClaimedWindow();
+        if (window == 0) return 0L;
+        try (MemoryStack stack = MemoryStack.stackPush()) {
+            final IntBuffer w = stack.mallocInt(1);
+            final IntBuffer h = stack.mallocInt(1);
+            SDL_GetWindowSizeInPixels(window, w, h);
+            return ((long) w.get(0) << 32) | (h.get(0) & 0xFFFFFFFFL);
         }
-        presentMode = mode;
-        LOG.info("SDL present mode set to {}", mode);
+    }
+
+    private static int toSdl(VSyncMode mode) {
+        return switch (mode) {
+            case OFF -> SDL_GPU_PRESENTMODE_IMMEDIATE;
+            case MAILBOX -> SDL_GPU_PRESENTMODE_MAILBOX;
+            default -> SDL_GPU_PRESENTMODE_VSYNC;
+        };
+    }
+
+    public int getDisplayRefreshRateHz() {
+        final long window = Display.getWindow();
+        final int displayId = window == 0 ? SDL_GetPrimaryDisplay() : SDL_GetDisplayForWindow(window);
+        if (displayId == 0) return 0;
+        final SDL_DisplayMode mode = SDL_GetCurrentDisplayMode(displayId);
+        if (mode == null) return 0;
+        return RenderBackend.refreshHzFrom(mode.refresh_rate_numerator(), mode.refresh_rate_denominator(), mode.refresh_rate());
     }
 
     public int getSwapchainTextureFormat() {
@@ -218,6 +393,7 @@ public final class Device {
     private void installLogCallback() {
         if (logCallback != null) return;
         logCallback = SDL_LogOutputFunction.create((userdata, category, priority, message) -> {
+            if (lost) return;
             final String msg = memUTF8(message);
             switch (priority) {
                 case SDLLog.SDL_LOG_PRIORITY_ERROR, SDLLog.SDL_LOG_PRIORITY_CRITICAL -> LOG.error("[SDL] {}", msg);

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/device/GpuDeviceLostException.java

@@ -0,0 +1,10 @@
+package com.gtnewhorizons.angelica.sdlgpu.device;
+
+public final class GpuDeviceLostException extends Error {
+
+    public GpuDeviceLostException(String operation, String sdlError) {
+        super("GPU device lost during " + operation + ": " + sdlError
+            + ". A lost device cannot be recovered, so the game cannot continue. Please report this at "
+            + "https://github.com/GTNewHorizons/Angelica/issues and attach your full log file (logs/fml-client-latest.log)");
+    }
+}

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/device/VideoDriverRecovery.java

@@ -0,0 +1,58 @@
+package com.gtnewhorizons.angelica.sdlgpu.device;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+import org.lwjgl.sdl.SDLError;
+import org.lwjgl.sdl.SDLHints;
+import org.lwjgl.sdl.SDLInit;
+
+import java.util.function.LongSupplier;
+
+import static org.lwjgl.sdl.SDLInit.SDL_INIT_VIDEO;
+import static org.lwjgl.sdl.SDLVideo.SDL_GetCurrentVideoDriver;
+
+public final class VideoDriverRecovery {
+
+    private static final Logger LOG = LogManager.getLogger("Angelica-SDLGPU");
+
+    private static final String X11 = "x11";
+
+    private VideoDriverRecovery() {}
+
+    static boolean shouldRetryOnX11(String videoDriver, boolean vulkanLoaderAvailable, String displayEnv) {
+        if (vulkanLoaderAvailable) return false;
+        if (!"wayland".equalsIgnoreCase(videoDriver)) return false;
+        return displayEnv != null && !displayEnv.isEmpty();
+    }
+
+    static long retryUnderX11(LongSupplier createDevice) {
+        final String original = SDL_GetCurrentVideoDriver();
+        LOG.warn("SDL GPU is unavailable under the '{}' video driver; retrying under {}", original, X11);
+
+        if (!restartVideo(X11)) {
+            LOG.warn("Could not restart the SDL video subsystem under {}: {}", X11, SDLError.SDL_GetError());
+            restartVideo(original);
+            return 0L;
+        }
+
+        final long device = createDevice.getAsLong();
+        if (device == 0) {
+            LOG.warn("SDL GPU is unavailable under {} as well; restoring the '{}' video driver", X11, original);
+            restartVideo(original);
+            return 0L;
+        }
+
+        LOG.warn("SDL video driver switched to {} so the SDL GPU backend can run. Set SDL_VIDEODRIVER=wayland to keep the native session and run on OpenGL instead.", X11);
+        return device;
+    }
+
+    private static boolean restartVideo(String driver) {
+        SDLInit.SDL_QuitSubSystem(SDL_INIT_VIDEO);
+        if (driver == null || driver.isEmpty()) {
+            SDLHints.SDL_ResetHint(SDLHints.SDL_HINT_VIDEO_DRIVER);
+        } else {
+            SDLHints.SDL_SetHint(SDLHints.SDL_HINT_VIDEO_DRIVER, driver);
+        }
+        return SDLInit.SDL_InitSubSystem(SDL_INIT_VIDEO);
+    }
+}

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/frame/ContextState.java

@@ -7,6 +7,7 @@ import com.gtnewhorizons.angelica.sdlgpu.shader.UniformStaging;
 import it.unimi.dsi.fastutil.objects.Reference2ObjectOpenHashMap;
 import it.unimi.dsi.fastutil.ints.IntArrayList;
 import it.unimi.dsi.fastutil.longs.Long2FloatOpenHashMap;
+import it.unimi.dsi.fastutil.longs.Long2IntOpenHashMap;
 import it.unimi.dsi.fastutil.longs.Long2ObjectOpenHashMap;
 import it.unimi.dsi.fastutil.longs.LongArrayList;
 import it.unimi.dsi.fastutil.longs.LongOpenHashSet;
@@ -92,6 +93,7 @@ public final class ContextState {
     public float blendColorR, blendColorG, blendColorB, blendColorA;
     public int stencilRef;
     public float depthClearValue = 1.0f;
+    public int stencilClearValue;
     public boolean primitiveRestartEnabled;
     public int primitiveRestartSentinel;
 
@@ -292,13 +294,20 @@ public final class ContextState {
     public int boundReadFboId;
 
     public final LongOpenHashSet clearedTexturesThisFrame = new LongOpenHashSet();
+    public final LongOpenHashSet clearedStencilTexturesThisFrame = new LongOpenHashSet();
 
     public final LongOpenHashSet pendingColorTextures = new LongOpenHashSet();
     public final Long2ObjectOpenHashMap<float[]> pendingColorValues = new Long2ObjectOpenHashMap<>();
     public final LongOpenHashSet pendingDepthTextures = new LongOpenHashSet();
     public final Long2FloatOpenHashMap pendingDepthValues = new Long2FloatOpenHashMap();
+    public final LongOpenHashSet pendingStencilTextures = new LongOpenHashSet();
+    public final Long2IntOpenHashMap pendingStencilValues = new Long2IntOpenHashMap();
     public boolean pendingSwapchainClear;
     public float pendingSwapchainR, pendingSwapchainG, pendingSwapchainB, pendingSwapchainA;
+    public boolean pendingSwapchainDepthClear;
+    public boolean pendingSwapchainStencilClear;
+    public float pendingSwapchainDepth;
+    public int pendingSwapchainStencil;
 
     public final LongArrayList samplerFlushColorHandles = new LongArrayList();
     public final IntArrayList samplerFlushColorGlIds = new IntArrayList();

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/frame/FrameManager.java

@@ -5,6 +5,7 @@ import com.gtnewhorizons.angelica.glsm.profiling.Tracy;
 import com.gtnewhorizons.angelica.sdlgpu.device.Device;
 import com.gtnewhorizons.angelica.sdlgpu.resource.ResourceManager;
 import com.gtnewhorizons.angelica.sdlgpu.util.MemoryAccess;
+import com.gtnewhorizons.angelica.sdlgpu.util.ThreadRegistry;
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 import com.gtnewhorizons.angelica.sdlgpu.resource.UploadArena;
@@ -16,16 +17,19 @@ import org.lwjgl.PointerBuffer;
 import org.lwjgl.system.MemoryStack;
 import org.lwjgl.sdl.SDLError;
 import org.lwjgl.sdl.SDL_FColor;
+import org.lwjgl.sdl.SDL_GPUBlitInfo;
+import org.lwjgl.sdl.SDL_GPUBlitRegion;
 import org.lwjgl.sdl.SDL_GPUColorTargetInfo;
 import org.lwjgl.sdl.SDL_GPUDepthStencilTargetInfo;
-import org.lwjglx.opengl.Display;
 
 import java.nio.ByteBuffer;
 import java.nio.IntBuffer;
 import java.util.Arrays;
-import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicLong;
 
 import static org.lwjgl.sdl.SDLGPU.*;
+import static org.lwjgl.sdl.SDLSurface.SDL_FLIP_NONE;
 import static org.lwjgl.system.MemoryStack.*;
 
 /**
@@ -37,7 +41,6 @@ public final class FrameManager {
     private static final Tracy.ZoneId Z_SDL_FENCE_WAIT = Tracy.zoneId("sdlFenceWait", Tracy.COLOR_SWAP);
     private static final Tracy.ZoneId Z_SDL_SUBMIT = Tracy.zoneId("sdlSubmit", Tracy.COLOR_SWAP);
     private static final Tracy.ZoneId Z_SDL_ACQUIRE_WAIT = Tracy.zoneId("sdlAcquireWait", Tracy.COLOR_SWAP);
-    private static final Tracy.ZoneId Z_SDL_SWAPCHAIN_WAIT = Tracy.zoneId("sdlSwapchainWait", Tracy.COLOR_SWAP);
 
     private final Device device;
     private ResourceManager resourceManager;
@@ -48,19 +51,17 @@ public final class FrameManager {
         public long renderPass;
         public long copyPass;
         public boolean computePassOpen;
-        public long swapchainTexture;
-        public int swapchainWidth;
-        public int swapchainHeight;
         public boolean frameActive;
         public long currentColorTarget;
         public long currentDepthTarget;
         public long activeLayoutHash;
         public long frameNumber;
         public boolean clearedThisFrame;
-        public boolean swapchainUsedThisFrame;
-        public boolean swapchainAcquiredThisFrame;
+        public boolean depthClearedThisFrame;
+        public boolean fbo0UsedThisFrame;
+        public boolean presentedThisFrame;
         public boolean swapchainUnavailable;
-        public boolean skipPresent;
+        public boolean windowThreadChecked;
         public long renderPassGeneration;
 
         public boolean wantFenceOnNextSubmit;
@@ -82,13 +83,17 @@ public final class FrameManager {
         public int batchBreakSamplerThisFrame;
         public int stateAppliesThisFrame;
         public long acquireWaitNanosThisFrame;
+        public volatile long lastFrameGateNanos;
+        public volatile long lastFrameGateEndNanos;
+        public int midFrameSubmitsThisFrame;
         public int mipGensThisFrame;
+        public int mipGenSubmitsThisFrame;
+        public int uploadFlushSubmitsThisFrame;
         public int blitsThisFrame;
         public int presentSkipsThisFrame;
         public int emptyFramesThisFrame;
         public int droppedDrawsThisFrame;
         public int computeBatchJoinsThisFrame;
-        public boolean drawableStarved;
         public int clearPassesThisFrame;
         public int swapchainPassesThisFrame;
         public int fboPassesThisFrame;
@@ -144,34 +149,52 @@ public final class FrameManager {
 
     private volatile boolean globalSyncAtNextBeginFrame;
 
-    private final CopyOnWriteArrayList<FrameState> registeredFrames = new CopyOnWriteArrayList<>();
+    private final ThreadRegistry<FrameState> registeredFrames = new ThreadRegistry<>(new FrameState[0]);
 
-     private volatile FrameState soleFrame;
-
-    private final ThreadLocal<FrameState> tlFrame = ThreadLocal.withInitial(() -> {
-        final FrameState f = new FrameState();
-        registeredFrames.add(f);
-        refreshSoleFrame();
-        return f;
-    });
-
-    private void refreshSoleFrame() {
-        soleFrame = registeredFrames.size() == 1 ? registeredFrames.get(0) : null;
-    }
+    private final ThreadLocal<FrameState> tlFrame = new ThreadLocal<>();
 
     public FrameState frame() {
-        final FrameState f = soleFrame;
-        if (f != null && f.owner == Thread.currentThread()) return f;
-        return tlFrame.get();
+        final FrameState sole = registeredFrames.sole();
+        if (sole != null && sole.owner == Thread.currentThread()) return sole;
+        final FrameState f = tlFrame.get();
+        return f != null ? f : registerFrame();
     }
 
-    public static final long SWAPCHAIN_LAYOUT_HASH = 0x5CA1AB1E5CA1AB1EL;
+    private FrameState registerFrame() {
+        final FrameState f = new FrameState();
+        tlFrame.set(f);
+        registeredFrames.add(f);
+        return f;
+    }
+
+    public int registeredFrameCount() {
+        return registeredFrames.size();
+    }
+
+    public FrameState busiestFrame() {
+        final FrameState[] frames = registeredFrames.snapshot();
+        FrameState best = null;
+        for (final FrameState f : frames) {
+            if (best == null || f.frameNumber > best.frameNumber) best = f;
+        }
+        return best != null ? best : frame();
+    }
+
+    public static final long FBO0_LAYOUT_HASH = 0x5CA1AB1E5CA1AB1EL;
+
+    private final OffscreenTarget finalTarget = new OffscreenTarget();
+
+    public OffscreenTarget finalTarget() { return finalTarget; }
+
+    public void destroyFinalTarget() {
+        if (resourceManager != null) finalTarget.destroy(resourceManager);
+    }
 
     public static final long MAX_PENDING_UPLOAD_BYTES = 16L * 1024L * 1024L;
     public static final int MAX_PENDING_UPLOAD_COMMANDS = 256;
 
     private Runnable beforeEndCopyPass;
-    private Runnable beforePendingUploadSubmit;
+
 
     public FrameManager(Device device) {
         this.device = device;
@@ -181,18 +204,12 @@ public final class FrameManager {
         this.resourceManager = resourceManager;
     }
 
-    private static volatile boolean threadLogged;
-
     public void beginFrame() {
         final FrameState f = frame();
         if (f.frameActive) {
             LOG.warn("beginFrame() called while frame already active on thread {}", Thread.currentThread().getName());
             return;
         }
-        if (!threadLogged) {
-            threadLogged = true;
-            LOG.info("First beginFrame() on thread={}; must match the SDL window-creating thread", Thread.currentThread().getName());
-        }
 
         flushPendingUploadCommandBuffer(f);
         if (globalSyncAtNextBeginFrame) {
@@ -202,23 +219,15 @@ public final class FrameManager {
             finally { Tracy.endZone(); }
         }
 
-        if (f.drawableStarved) {
-            f.drawableStarved = false;
-            Tracy.beginZone(Z_SDL_SWAPCHAIN_WAIT);
-            try { SDL_WaitForGPUSwapchain(device.getDevice(), Display.getWindow()); }
-            finally { Tracy.endZone(); }
-        }
-
         f.commandBuffer = SDL_AcquireGPUCommandBuffer(device.getDevice());
         if (f.commandBuffer == 0) {
             throw new RuntimeException("Failed to acquire GPU command buffer: " + SDLError.SDL_GetError());
         }
 
-        f.swapchainTexture = 0;
-        f.swapchainWidth = 0;
-        f.swapchainHeight = 0;
-        f.swapchainAcquiredThisFrame = false;
         f.swapchainUnavailable = false;
+        f.presentedThisFrame = false;
+
+        maintainFinalTarget();
 
         f.frameActive = true;
         f.renderPass = 0;
@@ -226,23 +235,72 @@ public final class FrameManager {
         f.currentDepthTarget = 0;
         f.frameNumber++;
         f.clearedThisFrame = false;
-        f.swapchainUsedThisFrame = false;
-        f.skipPresent = false;
+        f.depthClearedThisFrame = false;
+        f.fbo0UsedThisFrame = false;
+    }
+
+    private static final long FINAL_TARGET_SIZE_POLL_NANOS = 1_000_000_000L;
+
+    private long finalTargetPollNanos;
+    private volatile Thread mainThread;
+
+    public void setMainThread(Thread thread) {
+        this.mainThread = thread;
+    }
+
+    // Resizing releases a texture an in-flight present may still reference, so drain before ensureSize.
+    private void maintainFinalTarget() {
+        if (resourceManager == null) return;
+        final Thread owner = mainThread;
+        if (owner != null && Thread.currentThread() != owner) return;
+
+        final long now = System.nanoTime();
+        final boolean poll = finalTargetPollNanos == 0L || now - finalTargetPollNanos >= FINAL_TARGET_SIZE_POLL_NANOS;
+        if (!poll && !device.wasWindowResized() && finalTarget.isReady()) return;
+        if (poll) finalTargetPollNanos = now;
+
+        final long size = device.getWindowSizeInPixels();
+        if (size == 0L) return;
+        final int width = (int) (size >> 32);
+        final int height = (int) size;
+        if (finalTarget.isReady() && width == finalTarget.width() && height == finalTarget.height()) return;
+
+        if (presenter != null) presenter.drain();
+        finalTarget.ensureSize(device, resourceManager, width, height);
     }
 
     public void markFrameEmpty(FrameState f) {
-        f.skipPresent = true;
         f.emptyFramesThisFrame++;
     }
 
-    public void ensureSwapchainRenderPass(float clearR, float clearG, float clearB, float clearA, boolean clear) {
-        ensureSwapchainRenderPass(frame(), clearR, clearG, clearB, clearA, clear);
+    static boolean swapchainClearNeedsPassBreak(ContextState st, FrameState f) {
+        return (st.pendingSwapchainClear || st.pendingSwapchainDepthClear || st.pendingSwapchainStencilClear) && f.renderPass != 0 && f.activeLayoutHash == FBO0_LAYOUT_HASH;
     }
 
-    public void ensureSwapchainRenderPass(FrameState f, float clearR, float clearG, float clearB, float clearA, boolean clear) {
-        if (!ensureSwapchainAcquired(f)) return; // present-skip; don't bind tex=0
-        if (f.renderPass != 0 && f.currentColorTarget == f.swapchainTexture) {
-            return;
+    public boolean ensureFbo0RenderPass(FrameState f, ContextState st) {
+        final boolean clearColor = st.pendingSwapchainClear;
+        if (swapchainClearNeedsPassBreak(st, f)) {
+            endRenderPassIfActive(f);
+        }
+        final boolean applied = ensureFbo0RenderPass(f,
+            clearColor ? st.pendingSwapchainR : st.clearR,
+            clearColor ? st.pendingSwapchainG : st.clearG,
+            clearColor ? st.pendingSwapchainB : st.clearB,
+            clearColor ? st.pendingSwapchainA : st.clearA,
+            clearColor,
+            st.pendingSwapchainDepthClear, st.pendingSwapchainDepthClear ? st.pendingSwapchainDepth : st.depthClearValue,
+            st.pendingSwapchainStencilClear, st.pendingSwapchainStencilClear ? st.pendingSwapchainStencil : st.stencilClearValue);
+        if (!applied) return false;
+        st.pendingSwapchainClear = false;
+        st.pendingSwapchainDepthClear = false;
+        st.pendingSwapchainStencilClear = false;
+        return true;
+    }
+
+    private boolean ensureFbo0RenderPass(FrameState f, float clearR, float clearG, float clearB, float clearA, boolean clear, boolean clearDepth, float depthValue, boolean clearStencil, int stencilValue) {
+        if (!finalTarget.isReady() || f.commandBuffer == 0) return false;
+        if (f.renderPass != 0 && f.activeLayoutHash == FBO0_LAYOUT_HASH) {
+            return false;
         }
 
         endActiveEncoders(f);
@@ -251,10 +309,16 @@ public final class FrameManager {
             clear = true;
         }
 
+        final long depthTexture = resourceManager != null ? resourceManager.getOrCreateSwapchainDepthStencil(finalTarget.width(), finalTarget.height()) : 0L;
+        if (depthTexture != 0 && !f.depthClearedThisFrame) {
+            clearDepth = true;
+            clearStencil = true;
+        }
+
         try (var stack = stackPush()) {
             final SDL_GPUColorTargetInfo.Buffer colorTargets = SDL_GPUColorTargetInfo.calloc(1, stack);
             final long ctAddr = colorTargets.get(0).address();
-            MemoryAccess.putAddress(ctAddr + SDL_GPUColorTargetInfo.TEXTURE, f.swapchainTexture);
+            MemoryAccess.putAddress(ctAddr + SDL_GPUColorTargetInfo.TEXTURE, finalTarget.colorTexture());
             MemoryAccess.putInt(ctAddr + SDL_GPUColorTargetInfo.LOAD_OP, clear ? SDL_GPU_LOADOP_CLEAR : SDL_GPU_LOADOP_LOAD);
             MemoryAccess.putInt(ctAddr + SDL_GPUColorTargetInfo.STORE_OP, SDL_GPU_STOREOP_STORE);
 
@@ -267,19 +331,35 @@ public final class FrameManager {
                 f.clearedThisFrame = true;
             }
 
+            SDL_GPUDepthStencilTargetInfo depthTarget = null;
+            if (depthTexture != 0) {
+                depthTarget = SDL_GPUDepthStencilTargetInfo.calloc(stack);
+                final long dtAddr = depthTarget.address();
+                MemoryAccess.putAddress(dtAddr + SDL_GPUDepthStencilTargetInfo.TEXTURE, depthTexture);
+                MemoryAccess.putInt(dtAddr + SDL_GPUDepthStencilTargetInfo.LOAD_OP, clearDepth ? SDL_GPU_LOADOP_CLEAR : SDL_GPU_LOADOP_LOAD);
+                MemoryAccess.putInt(dtAddr + SDL_GPUDepthStencilTargetInfo.STORE_OP, SDL_GPU_STOREOP_STORE);
+                MemoryAccess.putFloat(dtAddr + SDL_GPUDepthStencilTargetInfo.CLEAR_DEPTH, depthValue);
+                MemoryAccess.putInt(dtAddr + SDL_GPUDepthStencilTargetInfo.STENCIL_LOAD_OP, clearStencil ? SDL_GPU_LOADOP_CLEAR : SDL_GPU_LOADOP_LOAD);
+                MemoryAccess.putInt(dtAddr + SDL_GPUDepthStencilTargetInfo.STENCIL_STORE_OP, SDL_GPU_STOREOP_STORE);
+                MemoryAccess.putByte(dtAddr + SDL_GPUDepthStencilTargetInfo.CLEAR_STENCIL, (byte) stencilValue);
+                if (clearDepth && clearStencil) f.depthClearedThisFrame = true;
+            }
+
             if (preRenderPassHook != null) preRenderPassHook.run();
             assertNoEncoderActive(f, "SDL_BeginGPURenderPass(swapchain)");
-            f.renderPass = SDL_BeginGPURenderPass(f.commandBuffer, colorTargets, null);
+            f.renderPass = SDL_BeginGPURenderPass(f.commandBuffer, colorTargets, depthTarget);
             if (f.renderPass == 0) {
                 throw new RuntimeException("Failed to begin render pass: " + SDLError.SDL_GetError());
             }
             f.renderPassGeneration++;
             f.swapchainPassesThisFrame++;
-            f.currentColorTarget = f.swapchainTexture;
-            f.currentDepthTarget = 0;
-            f.activeLayoutHash = SWAPCHAIN_LAYOUT_HASH;
-            f.swapchainUsedThisFrame = true;
+            f.currentColorTarget = finalTarget.colorTexture();
+            f.currentDepthTarget = depthTexture;
+            f.activeLayoutHash = FBO0_LAYOUT_HASH;
+            f.fbo0UsedThisFrame = true;
+            finalTarget.markContent();
         }
+        return true;
     }
 
 
@@ -329,6 +409,8 @@ public final class FrameManager {
 
     public void noteMipGen() { frame().mipGensThisFrame++; }
 
+    public void noteMipGenSubmit() { frame().mipGenSubmitsThisFrame++; }
+
     public void noteBlit() { frame().blitsThisFrame++; }
 
     public void noteClearPass() { frame().clearPassesThisFrame++; }
@@ -409,10 +491,6 @@ public final class FrameManager {
         this.beforeEndCopyPass = callback;
     }
 
-    public void setBeforePendingUploadSubmitCallback(Runnable callback) {
-        this.beforePendingUploadSubmit = callback;
-    }
-
     public void setBeforeSubmitCallback(Runnable callback) {
         this.beforeSubmit = callback;
     }
@@ -422,17 +500,14 @@ public final class FrameManager {
     }
 
     public void requestFlushOnAllRegisteredFrames() {
-        final int n = registeredFrames.size();
-        for (int i = 0; i < n; i++) {
-            registeredFrames.get(i).flushRequested = true;
+        for (final FrameState f : registeredFrames.snapshot()) {
+            f.flushRequested = true;
         }
     }
 
     public void requestSyncFlushOnAllRegisteredFrames() {
         globalSyncAtNextBeginFrame = true;
-        final int n = registeredFrames.size();
-        for (int i = 0; i < n; i++) {
-            final FrameState f = registeredFrames.get(i);
+        for (final FrameState f : registeredFrames.snapshot()) {
             f.flushRequested = true;
             f.syncOnNextFlush = true;
         }
@@ -459,21 +534,18 @@ public final class FrameManager {
         endCopyPassIfActive(f);
         endRenderPassIfActive(f);
 
-        if (!f.swapchainAcquiredThisFrame && !f.swapchainUnavailable && !f.skipPresent && f.commandBuffer != 0) {
-            ensureSwapchainAcquired(f);
-        }
-
         if (f.commandBuffer != 0) {
             Tracy.beginZone(Z_SDL_SUBMIT);
             try {
                 if (f.wantFenceOnNextSubmit) {
                     f.wantFenceOnNextSubmit = false;
+                    if (f.lastAcquiredFence != 0) SDL_ReleaseGPUFence(device.getDevice(), f.lastAcquiredFence);
                     f.lastAcquiredFence = SDL_SubmitGPUCommandBufferAndAcquireFence(f.commandBuffer);
                     if (f.lastAcquiredFence == 0) {
-                        LOG.error("Failed to submit+acquireFence GPU command buffer: {}", SDLError.SDL_GetError());
+                        device.reportGpuFailure("submit+acquireFence GPU command buffer");
                     }
                 } else if (!SDL_SubmitGPUCommandBuffer(f.commandBuffer)) {
-                    LOG.error("Failed to submit GPU command buffer: {}", SDLError.SDL_GetError());
+                    device.reportGpuFailure("submit GPU command buffer");
                 }
             } finally {
                 Tracy.endZone();
@@ -482,9 +554,14 @@ public final class FrameManager {
             f.commandBuffer = 0;
         }
 
-        f.drawableStarved = f.presentSkipsThisFrame > 0;
+        drainWindowPresentCounters(f);
+
+        if (Tracy.ENABLED && resourceManager != null) {
+            SdlFramePlots.emit(f, resourceManager);
+        }
+
+        f.midFrameSubmitsThisFrame = 0;
 
-        if (Tracy.ENABLED && resourceManager != null) SdlFramePlots.emit(f, resourceManager);
         f.lastPlottedRenderPassGen = f.renderPassGeneration;
         f.computePassesThisFrame = 0;
         f.submitsThisFrame = 0;
@@ -502,6 +579,8 @@ public final class FrameManager {
         f.stateAppliesThisFrame = 0;
         f.acquireWaitNanosThisFrame = 0;
         f.mipGensThisFrame = 0;
+        f.mipGenSubmitsThisFrame = 0;
+        f.uploadFlushSubmitsThisFrame = 0;
         f.blitsThisFrame = 0;
         f.clearPassesThisFrame = 0;
         f.swapchainPassesThisFrame = 0;
@@ -516,9 +595,6 @@ public final class FrameManager {
         f.computeBatchJoinsThisFrame = 0;
 
         f.frameActive = false;
-        f.swapchainTexture = 0;
-
-        if (afterPresent != null) afterPresent.run();
     }
 
     public void submitMidFrame() {
@@ -530,17 +606,19 @@ public final class FrameManager {
         try {
             if (f.wantFenceOnNextSubmit) {
                 f.wantFenceOnNextSubmit = false;
+                if (f.lastAcquiredFence != 0) SDL_ReleaseGPUFence(device.getDevice(), f.lastAcquiredFence);
                 f.lastAcquiredFence = SDL_SubmitGPUCommandBufferAndAcquireFence(f.commandBuffer);
                 if (f.lastAcquiredFence == 0) {
-                    LOG.error("Mid-frame submit+acquireFence failed: {}", SDLError.SDL_GetError());
+                    device.reportGpuFailure("mid-frame submit+acquireFence");
                 }
             } else if (!SDL_SubmitGPUCommandBuffer(f.commandBuffer)) {
-                LOG.error("Mid-frame submit failed: {}", SDLError.SDL_GetError());
+                device.reportGpuFailure("mid-frame submit");
             }
         } finally {
             Tracy.endZone();
         }
         f.submitsThisFrame++;
+        f.midFrameSubmitsThisFrame++;
         f.commandBuffer = 0;
         if (f.frameActive) {
             reacquireCommandBuffer();
@@ -552,6 +630,7 @@ public final class FrameManager {
         if (f.frameActive) {
             endFrame();
         }
+        presentFinalTarget();
         beginFrame();
     }
 
@@ -616,7 +695,6 @@ public final class FrameManager {
             return;
         }
         endCopyPassIfActive(f);
-        if (beforePendingUploadSubmit != null) beforePendingUploadSubmit.run();
         if (f.pendingUploadCommandBuffer != 0) {
             Tracy.beginZone(Z_SDL_SUBMIT);
             final boolean submitted;
@@ -626,9 +704,10 @@ public final class FrameManager {
                 Tracy.endZone();
             }
             if (!submitted) {
-                LOG.error("Failed to submit pending upload command buffer: {}", SDLError.SDL_GetError());
+                device.reportGpuFailure("submit pending upload command buffer");
             }
             f.submitsThisFrame++;
+            f.uploadFlushSubmitsThisFrame++;
             f.pendingUploadCommandBuffer = 0;
             f.pendingUploadBytes = 0;
             f.pendingUploadCommands = 0;
@@ -663,22 +742,16 @@ public final class FrameManager {
 
     public long getActiveLayoutHash(FrameState f) { return f.activeLayoutHash; }
 
-    public long getSwapchainTexture() {
-        final FrameState f = frame();
-        ensureSwapchainAcquired(f);
-        return f.swapchainTexture;
+    public long getFbo0Texture() {
+        return finalTarget.colorTexture();
     }
 
-    public int getSwapchainWidth() {
-        final FrameState f = frame();
-        ensureSwapchainAcquired(f);
-        return f.swapchainWidth;
+    public int getFbo0Width() {
+        return finalTarget.width();
     }
 
-    public int getSwapchainHeight() {
-        final FrameState f = frame();
-        ensureSwapchainAcquired(f);
-        return f.swapchainHeight;
+    public int getFbo0Height() {
+        return finalTarget.height();
     }
 
     public int getSwapchainFormat() {
@@ -713,8 +786,8 @@ public final class FrameManager {
         return frame().frameNumber;
     }
 
-    public boolean isSwapchainUsedThisFrame() {
-        return frame().swapchainUsedThisFrame;
+    public boolean isFbo0UsedThisFrame() {
+        return frame().fbo0UsedThisFrame;
     }
 
     public void reacquireCommandBuffer() {
@@ -727,24 +800,18 @@ public final class FrameManager {
         f.currentDepthTarget = 0;
 
         if (f.frameActive) {
-            final boolean wasAcquired = f.swapchainAcquiredThisFrame;
-            f.swapchainAcquiredThisFrame = false;
-            f.swapchainTexture = 0;
-            if (wasAcquired && !ensureSwapchainAcquired(f)) {
-                LOG.warn("Failed to re-acquire swapchain after readback: {}", SDLError.SDL_GetError());
-            }
             f.clearedThisFrame = false;
         }
     }
 
     public void releaseThreadState() {
-        final FrameState f = frame();
+        final FrameState f = tlFrame.get();
+        if (f == null) return;
         if (resourceManager != null) resourceManager.flushUploadArena(f);
         flushPendingUploadCommandBuffer(f);
         releaseFrameStateResources(f);
-        registeredFrames.remove(f);
         tlFrame.remove();
-        refreshSoleFrame();
+        registeredFrames.remove(f);
     }
 
     private void releaseFrameStateResources(FrameState f) {
@@ -782,25 +849,100 @@ public final class FrameManager {
     }
 
     public void releaseAllRegisteredFrames() {
-        for (FrameState f : registeredFrames) {
+        for (final FrameState f : registeredFrames.snapshot()) {
             releaseFrameStateResources(f);
         }
         registeredFrames.clear();
-        soleFrame = null;
     }
 
-    public boolean ensureSwapchainAcquired() {
-        return ensureSwapchainAcquired(frame());
+    public long lastFrameGateNanos() {
+        return frame().lastFrameGateNanos;
     }
 
-    public boolean ensureSwapchainAcquired(FrameState f) {
-        if (f.swapchainAcquiredThisFrame) return true;
-        if (f.swapchainUnavailable) return false;
-        if (!f.frameActive || f.commandBuffer == 0) return false;
+    public long lastFrameGateEndNanos() {
+        return frame().lastFrameGateEndNanos;
+    }
 
-        endActiveEncoders(f);
+    private Presenter presenter;
 
-        final long t0 = Tracy.ENABLED ? System.nanoTime() : 0L;
+    public void setPresenter(Presenter presenter) {
+        this.presenter = presenter;
+    }
+
+    private final FrameState windowFrame = new FrameState();
+
+    public FrameState windowFrame() {
+        return windowFrame;
+    }
+
+    public void presentFinalTarget() {
+        if (!finalTarget.hasContent()) return;
+        final long texture = finalTarget.colorTexture();
+        final int width = finalTarget.width();
+        final int height = finalTarget.height();
+        final Presenter p = presenter;
+        if (p != null && p.isEngaged()) {
+            final FrameState f = frame();
+            if (f.presentedThisFrame) return;
+            f.presentedThisFrame = true;
+            p.requestPresent(texture, width, height);
+        } else {
+            presentBlit(frame(), texture, width, height, SDL_FLIP_NONE);
+        }
+    }
+
+    private final AtomicLong windowAcquireWaitNanos = new AtomicLong();
+    private final AtomicInteger windowPresentSkips = new AtomicInteger();
+
+    private void drainWindowPresentCounters(FrameState f) {
+        if (f == windowFrame) return;
+        final long acquire = windowAcquireWaitNanos.getAndSet(0L);
+        if (acquire != 0L) {
+            f.acquireWaitNanosThisFrame += acquire;
+            f.lastFrameGateNanos = windowFrame.lastFrameGateNanos;
+            f.lastFrameGateEndNanos = windowFrame.lastFrameGateEndNanos;
+        }
+        f.presentSkipsThisFrame += windowPresentSkips.getAndSet(0);
+    }
+
+    private void noteAcquireWait(FrameState f, long waitNanos) {
+        if (f == windowFrame) windowAcquireWaitNanos.addAndGet(waitNanos);
+        else f.acquireWaitNanosThisFrame += waitNanos;
+    }
+
+    private void notePresentSkip(FrameState f) {
+        if (f == windowFrame) windowPresentSkips.incrementAndGet();
+        else f.presentSkipsThisFrame++;
+    }
+
+    public void presentOnWindowThread(long srcTexture, int srcW, int srcH) {
+        presentBlit(windowFrame, srcTexture, srcW, srcH, SDL_FLIP_NONE);
+        windowFrame.presentedThisFrame = false;
+        windowFrame.swapchainUnavailable = false;
+    }
+
+    public boolean presentBlit(FrameState f, long srcTexture, int srcW, int srcH, int flipMode) {
+        if (srcTexture == 0 || srcW <= 0 || srcH <= 0) return false;
+        if (f.presentedThisFrame || f.swapchainUnavailable) return false;
+
+        if (!f.windowThreadChecked) {
+            f.windowThreadChecked = true;
+            final Thread self = Thread.currentThread();
+            final Thread windowThread = device.getWindowThread();
+            if (windowThread != null && windowThread != self) {
+                LOG.warn("Swapchain acquired on '{}' but the SDL window was created on '{}'; SDL requires acquire on the window-creating thread", self.getName(), windowThread.getName());
+            } else {
+                LOG.info("First swapchain acquire on thread={}", self.getName());
+            }
+        }
+
+        final long window = device.getClaimedWindow();
+        if (window == 0) return false;
+
+        final long cb = SDL_AcquireGPUCommandBuffer(device.getDevice());
+        if (cb == 0) return false;
+
+        final long t0 = System.nanoTime();
         final long tex;
         final int w;
         final int h;
@@ -811,7 +953,7 @@ public final class FrameManager {
             final IntBuffer pHeight = stack.ints(0);
             Tracy.beginZone(Z_SDL_ACQUIRE_WAIT);
             try {
-                callOk = SDL_AcquireGPUSwapchainTexture(f.commandBuffer, Display.getWindow(), pTexture, pWidth, pHeight);
+                callOk = SDL_WaitAndAcquireGPUSwapchainTexture(cb, window, pTexture, pWidth, pHeight);
             } finally {
                 Tracy.endZone();
             }
@@ -819,25 +961,43 @@ public final class FrameManager {
             w = pWidth.get(0);
             h = pHeight.get(0);
         } catch (RuntimeException re) {
-            if (Tracy.ENABLED) f.acquireWaitNanosThisFrame += System.nanoTime() - t0;
+            SDL_CancelGPUCommandBuffer(cb);
             f.swapchainUnavailable = true;
             throw re;
         }
-        if (Tracy.ENABLED) f.acquireWaitNanosThisFrame += System.nanoTime() - t0;
+        final long tEnd = System.nanoTime();
+        f.lastFrameGateNanos = tEnd - t0;
+        f.lastFrameGateEndNanos = tEnd;
+        noteAcquireWait(f, tEnd - t0);
 
-        if (!callOk) {
+        if (!callOk || tex == 0) {
+            SDL_CancelGPUCommandBuffer(cb);
             f.swapchainUnavailable = true;
+            notePresentSkip(f);
             return false;
         }
-        if (tex == 0) {
-            f.swapchainUnavailable = true;
-            f.presentSkipsThisFrame++;
+
+        try (MemoryStack stack = stackPush()) {
+            final long info = stack.ncalloc(SDL_GPUBlitInfo.ALIGNOF, 1, SDL_GPUBlitInfo.SIZEOF);
+            writeBlitRegion(info + SDL_GPUBlitInfo.SOURCE, srcTexture, srcW, srcH);
+            writeBlitRegion(info + SDL_GPUBlitInfo.DESTINATION, tex, w, h);
+            MemoryAccess.putInt(info + SDL_GPUBlitInfo.FILTER, SDL_GPU_FILTER_LINEAR);
+            MemoryAccess.putInt(info + SDL_GPUBlitInfo.FLIP_MODE, flipMode);
+            nSDL_BlitGPUTexture(cb, info);
+        }
+
+        if (!SDL_SubmitGPUCommandBuffer(cb)) {
+            device.reportGpuFailure("submit present blit");
             return false;
         }
-        f.swapchainTexture = tex;
-        f.swapchainWidth = w;
-        f.swapchainHeight = h;
-        f.swapchainAcquiredThisFrame = true;
+        f.presentedThisFrame = true;
+        if (afterPresent != null) afterPresent.run();
         return true;
     }
+
+    private static void writeBlitRegion(long region, long texture, int w, int h) {
+        MemoryAccess.putAddress(region + SDL_GPUBlitRegion.TEXTURE, texture);
+        MemoryAccess.putInt(region + SDL_GPUBlitRegion.W, w);
+        MemoryAccess.putInt(region + SDL_GPUBlitRegion.H, h);
+    }
 }

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/frame/OffscreenTarget.java

@@ -1,7 +1,6 @@
-package com.gtnewhorizons.angelica.sdlgpu.splash;
+package com.gtnewhorizons.angelica.sdlgpu.frame;
 
 import com.gtnewhorizons.angelica.sdlgpu.device.Device;
-import com.gtnewhorizons.angelica.sdlgpu.frame.ContextState;
 import com.gtnewhorizons.angelica.sdlgpu.resource.FboState;
 import com.gtnewhorizons.angelica.sdlgpu.resource.ResourceManager;
 import org.lwjgl.opengl.GL11;
@@ -9,13 +8,14 @@ import org.lwjgl.opengl.GL11;
 import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREUSAGE_COLOR_TARGET;
 import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREUSAGE_SAMPLER;
 
-public final class SplashOffscreenTarget {
+public final class OffscreenTarget {
 
     private int fboGlId;
     private int colorTexGlId;
     private long colorTexHandle;
     private int width;
     private int height;
+    private boolean hasContent;
 
     public void create(Device device, ResourceManager rm, int width, int height, int swapchainSdlFormat) {
         this.width = width;
@@ -37,10 +37,20 @@ public final class SplashOffscreenTarget {
         fbo.cachedFormatsDirty = true;
     }
 
+    public void ensureSize(Device device, ResourceManager rm, int width, int height) {
+        if (width <= 0 || height <= 0) return;
+        if (colorTexHandle != 0 && width == this.width && height == this.height) return;
+        destroy(rm);
+        create(device, rm, width, height, device.getSwapchainTextureFormat());
+    }
+
     public int fboId() { return fboGlId; }
     public long colorTexture() { return colorTexHandle; }
     public int width() { return width; }
     public int height() { return height; }
+    public boolean isReady() { return colorTexHandle != 0; }
+    public boolean hasContent() { return hasContent; }
+    public void markContent() { hasContent = true; }
 
     public boolean isFor(ContextState st) {
         return fboGlId != 0 && st.boundFboId == fboGlId;
@@ -56,5 +66,6 @@ public final class SplashOffscreenTarget {
             colorTexGlId = 0;
             colorTexHandle = 0;
         }
+        hasContent = false;
     }
 }

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/frame/Presenter.java

@@ -0,0 +1,44 @@
+package com.gtnewhorizons.angelica.sdlgpu.frame;
+
+import com.gtnewhorizons.angelica.glsm.GLStateManager;
+
+import java.util.concurrent.Executor;
+import java.util.concurrent.Semaphore;
+
+public final class Presenter {
+
+    private final FrameManager frameManager;
+    private final Executor windowThreadExecutor;
+    private final Semaphore pending = new Semaphore(1);
+
+    public Presenter(FrameManager frameManager, Executor windowThreadExecutor) {
+        this.frameManager = frameManager;
+        this.windowThreadExecutor = windowThreadExecutor;
+    }
+
+    public boolean isEngaged() {
+        return windowThreadExecutor != null && GLStateManager.isSplashComplete();
+    }
+
+    public void requestPresent(long srcTexture, int srcW, int srcH) {
+        pending.acquireUninterruptibly();
+        boolean submitted = false;
+        try {
+            windowThreadExecutor.execute(() -> {
+                try {
+                    frameManager.presentOnWindowThread(srcTexture, srcW, srcH);
+                } finally {
+                    pending.release();
+                }
+            });
+            submitted = true;
+        } finally {
+            if (!submitted) pending.release();
+        }
+    }
+
+    public void drain() {
+        pending.acquireUninterruptibly();
+        pending.release();
+    }
+}

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/frame/SdlFramePlots.java

@@ -40,6 +40,8 @@ final class SdlFramePlots {
     private static final long PLOT_PRESENT_TO_PRESENT_US = Tracy.plotHandle("sdl.presentToPresentUs");
     private static final long PLOT_FRAMES_IN_FLIGHT = Tracy.plotHandle("sdl.framesInFlight");
     private static final long PLOT_MIP_GENS = Tracy.plotHandle("sdl.mipGens");
+    private static final long PLOT_MIP_GEN_SUBMITS = Tracy.plotHandle("sdl.mipGenSubmits");
+    private static final long PLOT_UPLOAD_FLUSH_SUBMITS = Tracy.plotHandle("sdl.uploadFlushSubmits");
     private static final long PLOT_BLIT_FALLBACKS = Tracy.plotHandle("sdl.blitFallbacks");
     private static final long PLOT_PRESENT_SKIPS = Tracy.plotHandle("sdl.presentSkips");
     private static final long PLOT_EMPTY_FRAMES = Tracy.plotHandle("sdl.emptyFrames");
@@ -54,6 +56,8 @@ final class SdlFramePlots {
     private static final long PLOT_BUFFER_POOL_HITS = Tracy.plotHandle("sdl.bufferPoolHits");
     private static final long PLOT_PIPELINE_KEY_RECOMPUTES = Tracy.plotHandle("sdl.pipelineKeyRecomputes");
     private static final long PLOT_PIPELINE_FAST_PATH_HITS = Tracy.plotHandle("sdl.pipelineFastPathHits");
+    private static final long PLOT_MID_FRAME_SUBMITS = Tracy.plotHandle("sdl.midFrameSubmits");
+    private static final long PLOT_GATE_US = Tracy.plotHandle("sdl.gateUs");
 
     private static final int[] contextCounters = new int[SDLGPURenderBackend.CTR_COUNT];
 
@@ -97,11 +101,15 @@ final class SdlFramePlots {
         final long nowNanos = System.nanoTime();
         if (f.lastEndFrameNanos != 0) Tracy.plotInt(PLOT_PRESENT_TO_PRESENT_US, (nowNanos - f.lastEndFrameNanos) / 1000);
         f.lastEndFrameNanos = nowNanos;
-        Tracy.plotInt(PLOT_FRAMES_IN_FLIGHT, Device.FRAMES_IN_FLIGHT);
+        Tracy.plotInt(PLOT_FRAMES_IN_FLIGHT, Device.framesInFlight());
         Tracy.plotInt(PLOT_MIP_GENS, f.mipGensThisFrame);
+        Tracy.plotInt(PLOT_MIP_GEN_SUBMITS, f.mipGenSubmitsThisFrame);
+        Tracy.plotInt(PLOT_UPLOAD_FLUSH_SUBMITS, f.uploadFlushSubmitsThisFrame);
         Tracy.plotInt(PLOT_BLIT_FALLBACKS, f.blitsThisFrame);
         Tracy.plotInt(PLOT_PRESENT_SKIPS, f.presentSkipsThisFrame);
         Tracy.plotInt(PLOT_EMPTY_FRAMES, f.emptyFramesThisFrame);
         Tracy.plotInt(PLOT_DROPPED_DRAWS, f.droppedDrawsThisFrame);
+        Tracy.plotInt(PLOT_MID_FRAME_SUBMITS, f.midFrameSubmitsThisFrame);
+        Tracy.plotInt(PLOT_GATE_US, f.lastFrameGateNanos / 1000);
     }
 }

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/pipeline/PipelineApplier.java

@@ -20,6 +20,7 @@ import com.gtnewhorizons.angelica.sdlgpu.resource.FBOClearTracker;
 import com.gtnewhorizons.angelica.sdlgpu.resource.FboState;
 import com.gtnewhorizons.angelica.sdlgpu.resource.PersistentBufferSync;
 import com.gtnewhorizons.angelica.sdlgpu.resource.PersistentMapping;
+import com.gtnewhorizons.angelica.sdlgpu.resource.PixelOps;
 import com.gtnewhorizons.angelica.sdlgpu.resource.ResourceManager;
 import com.gtnewhorizons.angelica.sdlgpu.sampler.SamplerBinder;
 import com.gtnewhorizons.angelica.sdlgpu.sampler.StorageBufferBinder;
@@ -108,11 +109,8 @@ public final class PipelineApplier {
         }
 
         if (st.boundFboId == 0) {
-            if (st.pendingSwapchainClear) {
-                frameManager.ensureSwapchainRenderPass(f, st.pendingSwapchainR, st.pendingSwapchainG, st.pendingSwapchainB, st.pendingSwapchainA, true);
-                st.pendingSwapchainClear = false;
-            } else {
-                frameManager.ensureSwapchainRenderPass(f, st.clearR, st.clearG, st.clearB, st.clearA, false);
+            if (frameManager.ensureFbo0RenderPass(f, st)) {
+                st.pipeline.setDepthTargetFormat(resourceManager.getSwapchainDepthStencilFormat());
             }
             return;
         }
@@ -145,47 +143,50 @@ public final class PipelineApplier {
                 tex = dummyTex;
             }
             final boolean pendingClear = tex != dummyTex && st.pendingColorTextures.contains(tex);
-            final boolean firstUse = !pendingClear && tex != dummyTex && !st.clearedTexturesThisFrame.contains(tex);
+            final boolean defined = tex != dummyTex && resourceManager.isTextureContentDefined(tex);
+            final boolean firstUse = !pendingClear && tex != dummyTex && !defined;
             if (pendingClear || firstUse) proposedClearOps |= 1 << i;
             layoutHash = Hashing.fmix64(layoutHash, tex);
             layoutHash = Hashing.fmix64(layoutHash, db);
+            if (pendingClear || firstUse) {
+                final float[] c = pendingClear ? st.pendingColorValues.get(tex) : null;
+                layoutHash = foldClearColor(layoutHash, c != null ? c[0] : st.clearR, c != null ? c[1] : st.clearG, c != null ? c[2] : st.clearB, c != null ? c[3] : st.clearA);
+            }
         }
         final boolean proposedDepthClear;
+        final boolean proposedStencilClear;
+        final boolean depthHasStencil = fbo.depthTexture != 0 && PixelOps.isDepthStencilFormat(fbo.depthFormat);
         if (fbo.depthTexture != 0) {
             final boolean pendingClear = st.pendingDepthTextures.contains(fbo.depthTexture);
             final boolean firstUse = !pendingClear && !st.clearedTexturesThisFrame.contains(fbo.depthTexture);
             proposedDepthClear = pendingClear || firstUse;
+            final boolean pendingStencil = depthHasStencil && st.pendingStencilTextures.contains(fbo.depthTexture);
+            if (depthHasStencil) {
+                final boolean firstStencilUse = !pendingStencil && !st.clearedStencilTexturesThisFrame.contains(fbo.depthTexture);
+                proposedStencilClear = pendingStencil || firstStencilUse;
+            } else {
+                proposedStencilClear = false;
+            }
             layoutHash = Hashing.fmix64(layoutHash, fbo.depthTexture);
+            if (proposedDepthClear) {
+                layoutHash = foldClearDepth(layoutHash, pendingClear ? st.pendingDepthValues.get(fbo.depthTexture) : st.depthClearValue);
+            }
+            if (proposedStencilClear) {
+                layoutHash = foldClearStencil(layoutHash, pendingStencil ? st.pendingStencilValues.get(fbo.depthTexture) : st.stencilClearValue);
+            }
         } else {
             proposedDepthClear = false;
+            proposedStencilClear = false;
         }
-        layoutHash = Hashing.fmix64(layoutHash, Float.floatToRawIntBits(st.clearR));
-        layoutHash = Hashing.fmix64(layoutHash, Float.floatToRawIntBits(st.clearG));
-        layoutHash = Hashing.fmix64(layoutHash, Float.floatToRawIntBits(st.clearB));
-        layoutHash = Hashing.fmix64(layoutHash, Float.floatToRawIntBits(st.clearA));
-        layoutHash = Hashing.fmix64(layoutHash, Float.floatToRawIntBits(st.depthClearValue));
 
         frameManager.endRenderPassIfActive(f);
 
-        final boolean reuse = fbo.cachedTargetsValid && fbo.cachedTargetsLayoutHash == layoutHash && fbo.cachedTargetsCount == totalTargets && fbo.cachedClearOpFlags == proposedClearOps && fbo.cachedDepthClearLast == proposedDepthClear;
+        final boolean reuse = fbo.cachedTargetsValid && fbo.cachedTargetsLayoutHash == layoutHash && fbo.cachedTargetsCount == totalTargets && fbo.cachedClearOpFlags == proposedClearOps && fbo.cachedDepthClearLast == proposedDepthClear && fbo.cachedStencilClearLast == proposedStencilClear;
 
         SDL_GPUColorTargetInfo.Buffer colorTargets = null;
         SDL_GPUDepthStencilTargetInfo depthTarget = null;
 
         if (reuse) {
-            for (int i = 0; i < totalTargets; i++) {
-                final int db = fbo.drawBuffers[i];
-                final long tex = (db >= 0 && db < ContextState.MAX_COLOR_ATTACHMENTS)
-                    ? fbo.colorTextures[db] : 0L;
-                if (tex != 0) {
-                    st.pendingColorTextures.remove(tex);
-                    if ((proposedClearOps & (1 << i)) != 0) st.clearedTexturesThisFrame.add(tex);
-                }
-            }
-            if (fbo.depthTexture != 0) {
-                st.pendingDepthTextures.remove(fbo.depthTexture);
-                if (proposedDepthClear) st.clearedTexturesThisFrame.add(fbo.depthTexture);
-            }
             if (totalTargets > 0) colorTargets = fbo.cachedColorTargets.position(0).limit(totalTargets);
             if (fbo.depthTexture != 0) depthTarget = fbo.cachedDepthTarget;
         } else {
@@ -199,9 +200,8 @@ public final class PipelineApplier {
                     } else {
                         tex = dummyTex;
                     }
-                    final boolean pendingClear = tex != dummyTex && st.pendingColorTextures.remove(tex);
-                    final boolean firstUse = !pendingClear && tex != dummyTex && !st.clearedTexturesThisFrame.contains(tex);
-                    final boolean clearThis = pendingClear || firstUse;
+                    final boolean pendingClear = tex != dummyTex && st.pendingColorTextures.contains(tex);
+                    final boolean clearThis = (proposedClearOps & (1 << i)) != 0;
                     final long ctAddr = colorTargets.address() + (long) i * SDL_GPUColorTargetInfo.SIZEOF;
                     MemoryAccess.putAddress(ctAddr + SDL_GPUColorTargetInfo.TEXTURE, tex);
                     MemoryAccess.putInt(ctAddr + SDL_GPUColorTargetInfo.LOAD_OP, clearThis ? SDL_GPU_LOADOP_CLEAR : SDL_GPU_LOADOP_LOAD);
@@ -220,36 +220,79 @@ public final class PipelineApplier {
                             MemoryAccess.putFloat(ccAddr + SDL_FColor.B, st.clearB);
                             MemoryAccess.putFloat(ccAddr + SDL_FColor.A, st.clearA);
                         }
-                        if (tex != dummyTex) st.clearedTexturesThisFrame.add(tex);
                     }
                 }
             }
             if (fbo.depthTexture != 0) {
-                final boolean pendingClear = st.pendingDepthTextures.remove(fbo.depthTexture);
-                final boolean firstUse = !pendingClear && !st.clearedTexturesThisFrame.contains(fbo.depthTexture);
-                final boolean clearDepth = pendingClear || firstUse;
+                final boolean pendingClear = st.pendingDepthTextures.contains(fbo.depthTexture);
                 depthTarget = fbo.cachedDepthTarget;
                 final long dtAddr = depthTarget.address();
                 MemoryAccess.putAddress(dtAddr + SDL_GPUDepthStencilTargetInfo.TEXTURE, fbo.depthTexture);
-                MemoryAccess.putInt(dtAddr + SDL_GPUDepthStencilTargetInfo.LOAD_OP, clearDepth ? SDL_GPU_LOADOP_CLEAR : SDL_GPU_LOADOP_LOAD);
+                MemoryAccess.putInt(dtAddr + SDL_GPUDepthStencilTargetInfo.LOAD_OP, proposedDepthClear ? SDL_GPU_LOADOP_CLEAR : SDL_GPU_LOADOP_LOAD);
                 MemoryAccess.putInt(dtAddr + SDL_GPUDepthStencilTargetInfo.STORE_OP, SDL_GPU_STOREOP_STORE);
-                if (clearDepth) {
+                if (proposedDepthClear) {
                     final float dv = pendingClear ? st.pendingDepthValues.get(fbo.depthTexture) : st.depthClearValue;
                     MemoryAccess.putFloat(dtAddr + SDL_GPUDepthStencilTargetInfo.CLEAR_DEPTH, dv);
-                    st.clearedTexturesThisFrame.add(fbo.depthTexture);
+                }
+                if (depthHasStencil) {
+                    final boolean pendingStencil = st.pendingStencilTextures.contains(fbo.depthTexture);
+                    MemoryAccess.putInt(dtAddr + SDL_GPUDepthStencilTargetInfo.STENCIL_LOAD_OP, proposedStencilClear ? SDL_GPU_LOADOP_CLEAR : SDL_GPU_LOADOP_LOAD);
+                    MemoryAccess.putInt(dtAddr + SDL_GPUDepthStencilTargetInfo.STENCIL_STORE_OP, SDL_GPU_STOREOP_STORE);
+                    if (proposedStencilClear) {
+                        final int sv = pendingStencil ? st.pendingStencilValues.get(fbo.depthTexture) : st.stencilClearValue;
+                        MemoryAccess.putByte(dtAddr + SDL_GPUDepthStencilTargetInfo.CLEAR_STENCIL, (byte) sv);
+                    }
+                } else {
+                    MemoryAccess.putInt(dtAddr + SDL_GPUDepthStencilTargetInfo.STENCIL_LOAD_OP, SDL_GPU_LOADOP_LOAD);
+                    MemoryAccess.putInt(dtAddr + SDL_GPUDepthStencilTargetInfo.STENCIL_STORE_OP, SDL_GPU_STOREOP_STORE);
                 }
             }
             fbo.cachedTargetsLayoutHash = layoutHash;
             fbo.cachedTargetsCount = totalTargets;
             fbo.cachedClearOpFlags = proposedClearOps;
             fbo.cachedDepthClearLast = proposedDepthClear;
+            fbo.cachedStencilClearLast = proposedStencilClear;
             fbo.cachedTargetsValid = true;
         }
 
+        consumeClears(resourceManager, st, fbo, dummyTex, proposedClearOps, proposedDepthClear, proposedStencilClear, depthHasStencil);
+
         frameManager.beginRenderPass(colorTargets, depthTarget);
         frameManager.setActiveLayoutHash(fbo.structuralLayoutHash);
     }
 
+    static void consumeClears(ResourceManager rm, ContextState st, FboState fbo, long dummyTex, int clearOps, boolean depthClear, boolean stencilClear, boolean depthHasStencil) {
+        for (int i = 0, n = fbo.drawBuffers.length; i < n; i++) {
+            final int db = fbo.drawBuffers[i];
+            final long tex = (db >= 0 && db < ContextState.MAX_COLOR_ATTACHMENTS) ? fbo.colorTextures[db] : 0L;
+            if (tex == 0 || tex == dummyTex) continue;
+            st.pendingColorTextures.remove(tex);
+            if ((clearOps & (1 << i)) != 0) rm.markTextureContentDefined(tex);
+        }
+        if (fbo.depthTexture == 0) return;
+        st.pendingDepthTextures.remove(fbo.depthTexture);
+        if (depthClear) st.clearedTexturesThisFrame.add(fbo.depthTexture);
+        if (depthHasStencil) {
+            st.pendingStencilTextures.remove(fbo.depthTexture);
+            if (stencilClear) st.clearedStencilTexturesThisFrame.add(fbo.depthTexture);
+        }
+    }
+
+    static long foldClearColor(long h, float r, float g, float b, float a) {
+        h = Hashing.fmix64(h, Float.floatToRawIntBits(r));
+        h = Hashing.fmix64(h, Float.floatToRawIntBits(g));
+        h = Hashing.fmix64(h, Float.floatToRawIntBits(b));
+        return Hashing.fmix64(h, Float.floatToRawIntBits(a));
+    }
+
+    static long foldClearDepth(long h, float depth) {
+        return Hashing.fmix64(h, Float.floatToRawIntBits(depth));
+    }
+
+    static long foldClearStencil(long h, int stencil) {
+        return Hashing.fmix64(h, stencil);
+    }
+
     private static final int RING_BLOCK_BYTES = ContextState.MAX_VERTEX_ATTRIBS * 16;
     private static final int RING_CHUNK_BYTES = ResourceManager.ATTRIB_RING_CHUNK_BLOCKS * RING_BLOCK_BYTES;
 

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/pipeline/PipelineCache.java

@@ -86,6 +86,17 @@ public final class PipelineCache {
     public int stencilCompareMask = 0xFF;
     public int stencilWriteMask = 0xFF;
 
+    private static final LongOpenHashSet loggedStencilMaskLost = new LongOpenHashSet();
+
+    private void warnOnceOnStencilMaskLost() {
+        if (!stencilTestEnabled || effectiveStencilTestEnabled()) return;
+        if (stencilFrontCompareOp == SDL_GPU_COMPAREOP_ALWAYS && stencilBackCompareOp == SDL_GPU_COMPAREOP_ALWAYS && stencilFrontPassOp == SDL_GPU_STENCILOP_KEEP && stencilBackPassOp == SDL_GPU_STENCILOP_KEEP)
+            return;
+        if (!loggedStencilMaskLost.add(Hashing.packHiLo(programId, debugFboId))) return;
+        LOG.warn("Stencil mask dropped: bound target has no stencil aspect. fbo={} depthFormat={} program={} frontCmp={} frontPass={} writeMask=0x{}",
+            debugFboId, textureFormatName(depthTargetFormat), programId, stencilFrontCompareOp, stencilFrontPassOp, Integer.toHexString(stencilWriteMask));
+    }
+
     public boolean cullEnabled = false;
     public int cullFaceMode = SDL_GPU_CULLMODE_BACK;
     public int frontFace = SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE;
@@ -141,6 +152,14 @@ public final class PipelineCache {
         this.drawBuffers = drawBuffers;
     }
 
+    public boolean setDepthTargetFormat(int sdlFormat) {
+        if (depthTargetFormat == sdlFormat && hasDepthTarget == (sdlFormat != 0)) return false;
+        hasDepthTarget = sdlFormat != 0;
+        depthTargetFormat = sdlFormat;
+        markOutputDirty();
+        return true;
+    }
+
     private int attachmentForSlot(int slot) {
         final int[] db = drawBuffers;
         if (db == null || slot < 0 || slot >= db.length) return 0;
@@ -340,7 +359,7 @@ public final class PipelineCache {
     private void warnOnceOnUnconsumedFragOutput(int numColorTargets) {
         if (maxFragOutputLocation < numColorTargets) return;
         if (!loggedUnconsumedFragOutput.add(Hashing.packHiLo(programId, numColorTargets))) return;
-        LOG.warn("[PipelineCache] program {} declares fragment output location {} but framebuffer {} ({} colour attachment(s)) has {} draw buffer(s) {}; writes past location {} are discarded", programId, maxFragOutputLocation, debugFboId, debugFboAttachments, numColorTargets, Arrays.toString(drawBuffers), numColorTargets - 1);
+        LOG.warn("[PipelineCache] program {} declares fragment output location {} but framebuffer {} ({} color attachment(s)) has {} draw buffer(s) {}; writes past location {} are discarded", programId, maxFragOutputLocation, debugFboId, debugFboAttachments, numColorTargets, Arrays.toString(drawBuffers), numColorTargets - 1);
     }
 
     private long createPipeline(PipelineStore store, ContextState cs) {
@@ -360,6 +379,7 @@ public final class PipelineCache {
         try (var stack = stackPush()) {
             final int numColorTargets = colorTargetFormats().length;
             warnOnceOnUnconsumedFragOutput(numColorTargets);
+            warnOnceOnStencilMaskLost();
             final SDL_GPUColorTargetDescription.Buffer colorDesc = SDL_GPUColorTargetDescription.calloc(numColorTargets, stack);
             for (int i = 0; i < numColorTargets; i++) {
                 final var desc = colorDesc.get(i);

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/resource/FBOClearTracker.java

@@ -49,8 +49,19 @@ public final class FBOClearTracker {
         st.clearedTexturesThisFrame.remove(tex);
     }
 
+    public static void recordPendingStencilClear(ContextState st, long tex, int value) {
+        st.pendingStencilValues.put(tex, value);
+        if (st.pendingStencilTextures.add(tex)) {
+            st.pendingMutationGen++;
+        }
+        st.clearedStencilTexturesThisFrame.remove(tex);
+    }
+
     public static boolean fboHasPendingClear(ContextState st, FboState fbo) {
-        if (fbo.depthTexture != 0 && st.pendingDepthTextures.contains(fbo.depthTexture)) return true;
+        if (fbo.depthTexture != 0
+            && (st.pendingDepthTextures.contains(fbo.depthTexture) || st.pendingStencilTextures.contains(fbo.depthTexture))) {
+            return true;
+        }
         if (st.pendingColorTextures.isEmpty()) return false;
         for (int db : fbo.drawBuffers) {
             if (db < 0 || db >= ContextState.MAX_COLOR_ATTACHMENTS) continue;
@@ -67,7 +78,7 @@ public final class FBOClearTracker {
     }
 
     public void flushPendingClearsForBoundSamplers(ContextState st) {
-        if (st.pendingColorTextures.isEmpty() && st.pendingDepthTextures.isEmpty()) return;
+        if (st.pendingColorTextures.isEmpty() && st.pendingDepthTextures.isEmpty() && st.pendingStencilTextures.isEmpty()) return;
 
         if (st.lastFlushedSamplerBindGen == st.samplerBindGen && st.lastFlushedProgram == st.boundProgram && st.lastFlushedPendingMutationGen == st.pendingMutationGen) {
             return;
@@ -115,7 +126,7 @@ public final class FBOClearTracker {
             if (st.pendingColorTextures.remove(handle)) {
                 colorHandles.add(handle);
                 colorGlIds.add(glTexId);
-            } else if (st.pendingDepthTextures.remove(handle)) {
+            } else if (st.pendingDepthTextures.contains(handle) || st.pendingStencilTextures.contains(handle)) {
                 depthHandles.add(handle);
                 depthGlIds.add(glTexId);
             }
@@ -169,6 +180,7 @@ public final class FBOClearTracker {
                     MemoryAccess.putFloat(ccAddr + SDL_FColor.B, color[2]);
                     MemoryAccess.putFloat(ccAddr + SDL_FColor.A, color[3]);
                     st.clearedTexturesThisFrame.add(handle);
+                    resourceManager.markTextureContentDefined(handle);
                     consumed[idx] = true;
                 }
                 frameManager.noteClearPass();
@@ -180,19 +192,38 @@ public final class FBOClearTracker {
         final int dn = depthHandles.size();
         for (int i = 0; i < dn; i++) {
             final long handle = depthHandles.getLong(i);
-            final float val = st.pendingDepthValues.get(handle);
-            try (var stack = MemoryStack.stackPush()) {
-                final SDL_GPUDepthStencilTargetInfo dt = SDL_GPUDepthStencilTargetInfo.calloc(stack);
-                final long addr = dt.address();
-                MemoryAccess.putAddress(addr + SDL_GPUDepthStencilTargetInfo.TEXTURE, handle);
-                MemoryAccess.putInt(addr + SDL_GPUDepthStencilTargetInfo.LOAD_OP, SDL_GPU_LOADOP_CLEAR);
-                MemoryAccess.putInt(addr + SDL_GPUDepthStencilTargetInfo.STORE_OP, SDL_GPU_STOREOP_STORE);
-                MemoryAccess.putFloat(addr + SDL_GPUDepthStencilTargetInfo.CLEAR_DEPTH, val);
-                frameManager.noteClearPass();
-                frameManager.beginRenderPass(null, dt);
-                frameManager.endRenderPassIfActive();
-                st.clearedTexturesThisFrame.add(handle);
+            emitDepthStencilClearPass(st, handle, st.pendingDepthTextures.remove(handle), st.pendingStencilTextures.remove(handle), false);
+        }
+    }
+
+    private void emitDepthStencilClearPass(ContextState st, long handle, boolean clearDepth, boolean clearStencil, boolean materialized) {
+        if (!clearDepth && !clearStencil) return;
+        try (var stack = MemoryStack.stackPush()) {
+            final SDL_GPUDepthStencilTargetInfo dt = SDL_GPUDepthStencilTargetInfo.calloc(stack);
+            final long addr = dt.address();
+            MemoryAccess.putAddress(addr + SDL_GPUDepthStencilTargetInfo.TEXTURE, handle);
+            MemoryAccess.putInt(addr + SDL_GPUDepthStencilTargetInfo.LOAD_OP, clearDepth ? SDL_GPU_LOADOP_CLEAR : SDL_GPU_LOADOP_LOAD);
+            MemoryAccess.putInt(addr + SDL_GPUDepthStencilTargetInfo.STORE_OP, SDL_GPU_STOREOP_STORE);
+            if (clearDepth) {
+                MemoryAccess.putFloat(addr + SDL_GPUDepthStencilTargetInfo.CLEAR_DEPTH, st.pendingDepthValues.get(handle));
             }
+            if (clearStencil) {
+                MemoryAccess.putInt(addr + SDL_GPUDepthStencilTargetInfo.STENCIL_LOAD_OP, SDL_GPU_LOADOP_CLEAR);
+                MemoryAccess.putInt(addr + SDL_GPUDepthStencilTargetInfo.STENCIL_STORE_OP, SDL_GPU_STOREOP_STORE);
+                MemoryAccess.putByte(addr + SDL_GPUDepthStencilTargetInfo.CLEAR_STENCIL, (byte) st.pendingStencilValues.get(handle));
+            }
+            frameManager.noteClearPass();
+            if (materialized) frameManager.noteMaterializedClearPass();
+            frameManager.beginRenderPass(null, dt);
+            frameManager.endRenderPassIfActive();
+        }
+        if (clearDepth) {
+            st.pendingDepthValues.remove(handle);
+            st.clearedTexturesThisFrame.add(handle);
+        }
+        if (clearStencil) {
+            st.pendingStencilValues.remove(handle);
+            st.clearedStencilTexturesThisFrame.add(handle);
         }
     }
 
@@ -206,28 +237,18 @@ public final class FBOClearTracker {
         if (depth) st.pendingDepthValues.remove(handle);
         else st.pendingColorValues.remove(handle);
         st.clearedTexturesThisFrame.add(handle);
+        resourceManager.markTextureContentDefined(handle);
         st.pendingMutationGen++;
         return true;
     }
 
     public void materializePendingClearForTexture(ContextState st, long handle) {
         if (handle == 0) return;
-        if (st.pendingDepthTextures.remove(handle)) {
-            final float val = st.pendingDepthValues.remove(handle);
+        final boolean depthPending = st.pendingDepthTextures.remove(handle);
+        final boolean stencilPending = st.pendingStencilTextures.remove(handle);
+        if (depthPending || stencilPending) {
             frameManager.endRenderPassIfActive();
-            try (var stack = MemoryStack.stackPush()) {
-                final SDL_GPUDepthStencilTargetInfo dt = SDL_GPUDepthStencilTargetInfo.calloc(stack);
-                final long addr = dt.address();
-                MemoryAccess.putAddress(addr + SDL_GPUDepthStencilTargetInfo.TEXTURE, handle);
-                MemoryAccess.putInt(addr + SDL_GPUDepthStencilTargetInfo.LOAD_OP, SDL_GPU_LOADOP_CLEAR);
-                MemoryAccess.putInt(addr + SDL_GPUDepthStencilTargetInfo.STORE_OP, SDL_GPU_STOREOP_STORE);
-                MemoryAccess.putFloat(addr + SDL_GPUDepthStencilTargetInfo.CLEAR_DEPTH, val);
-                frameManager.noteClearPass();
-                frameManager.noteMaterializedClearPass();
-                frameManager.beginRenderPass(null, dt);
-                frameManager.endRenderPassIfActive();
-                st.clearedTexturesThisFrame.add(handle);
-            }
+            emitDepthStencilClearPass(st, handle, depthPending, stencilPending, true);
             st.pendingMutationGen++;
             return;
         }
@@ -250,6 +271,7 @@ public final class FBOClearTracker {
                 frameManager.beginRenderPass(targets, null);
                 frameManager.endRenderPassIfActive();
                 st.clearedTexturesThisFrame.add(handle);
+                resourceManager.markTextureContentDefined(handle);
             }
             st.pendingMutationGen++;
         }
@@ -262,7 +284,10 @@ public final class FBOClearTracker {
         st.pendingColorValues.remove(handle);
         st.pendingDepthTextures.remove(handle);
         st.pendingDepthValues.remove(handle);
+        st.pendingStencilTextures.remove(handle);
+        st.pendingStencilValues.remove(handle);
         st.clearedTexturesThisFrame.remove(handle);
+        st.clearedStencilTexturesThisFrame.remove(handle);
     }
 
     public boolean fbosHaveSameAttachments(ContextState st, int a, int b) {

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/resource/FboState.java

@@ -35,6 +35,7 @@ public final class FboState {
     public int cachedTargetsCount = -1;
     public int cachedClearOpFlags;
     public boolean cachedDepthClearLast;
+    public boolean cachedStencilClearLast;
     public boolean cachedTargetsValid;
 
     public long getColorTexture() { return colorTextures[0]; }
@@ -63,7 +64,7 @@ public final class FboState {
             h = Hashing.fmix64(h, db);
         }
         h = Hashing.fmix64(h, depthTexture);
-        if (h == 0L || h == FrameManager.SWAPCHAIN_LAYOUT_HASH) h = 0xD1CE5EEDL;
+        if (h == 0L || h == FrameManager.FBO0_LAYOUT_HASH) h = 0xD1CE5EEDL;
         structuralLayoutHash = h;
     }
 

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/resource/PixelOps.java

@@ -34,6 +34,85 @@ public final class PixelOps {
         return sdlFormat == SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT || sdlFormat == SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT;
     }
 
+    public static int depthBits(int sdlFormat) {
+        return switch (sdlFormat) {
+            case SDL_GPU_TEXTUREFORMAT_D16_UNORM -> 16;
+            case SDL_GPU_TEXTUREFORMAT_D24_UNORM, SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT -> 24;
+            case SDL_GPU_TEXTUREFORMAT_D32_FLOAT, SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT -> 32;
+            default -> 0;
+        };
+    }
+
+    public static int stencilBits(int sdlFormat) {
+        return isDepthStencilFormat(sdlFormat) ? 8 : 0;
+    }
+
+    public static int colorChannelBits(int sdlFormat, int channel) {
+        if (channel < 0 || channel > 3) return 0;
+        return switch (sdlFormat) {
+            case SDL_GPU_TEXTUREFORMAT_A8_UNORM -> channel == 3 ? 8 : 0;
+            case SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM -> channel == 3 ? 2 : 10;
+            case SDL_GPU_TEXTUREFORMAT_R11G11B10_UFLOAT -> switch (channel) {
+                case 0, 1 -> 11;
+                case 2 -> 10;
+                default -> 0;
+            };
+            case SDL_GPU_TEXTUREFORMAT_B5G6R5_UNORM -> switch (channel) {
+                case 0, 2 -> 5;
+                case 1 -> 6;
+                default -> 0;
+            };
+            case SDL_GPU_TEXTUREFORMAT_B5G5R5A1_UNORM -> channel == 3 ? 1 : 5;
+            case SDL_GPU_TEXTUREFORMAT_B4G4R4A4_UNORM -> 4;
+            default -> channel < sdlFormatColorComponents(sdlFormat) ? uniformChannelBits(sdlFormat) : 0;
+        };
+    }
+
+    private static int uniformChannelBits(int sdlFormat) {
+        return switch (sdlFormat) {
+            case SDL_GPU_TEXTUREFORMAT_R8_UNORM, SDL_GPU_TEXTUREFORMAT_R8_SNORM,
+                 SDL_GPU_TEXTUREFORMAT_R8_UINT, SDL_GPU_TEXTUREFORMAT_R8_INT,
+                 SDL_GPU_TEXTUREFORMAT_R8G8_UNORM, SDL_GPU_TEXTUREFORMAT_R8G8_SNORM,
+                 SDL_GPU_TEXTUREFORMAT_R8G8_UINT, SDL_GPU_TEXTUREFORMAT_R8G8_INT,
+                 SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM, SDL_GPU_TEXTUREFORMAT_R8G8B8A8_SNORM,
+                 SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM_SRGB, SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UINT,
+                 SDL_GPU_TEXTUREFORMAT_R8G8B8A8_INT, SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM,
+                 SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM_SRGB -> 8;
+            case SDL_GPU_TEXTUREFORMAT_R16_UNORM, SDL_GPU_TEXTUREFORMAT_R16_SNORM,
+                 SDL_GPU_TEXTUREFORMAT_R16_FLOAT, SDL_GPU_TEXTUREFORMAT_R16_UINT,
+                 SDL_GPU_TEXTUREFORMAT_R16_INT, SDL_GPU_TEXTUREFORMAT_R16G16_UNORM,
+                 SDL_GPU_TEXTUREFORMAT_R16G16_SNORM, SDL_GPU_TEXTUREFORMAT_R16G16_FLOAT,
+                 SDL_GPU_TEXTUREFORMAT_R16G16_UINT, SDL_GPU_TEXTUREFORMAT_R16G16_INT,
+                 SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UNORM, SDL_GPU_TEXTUREFORMAT_R16G16B16A16_SNORM,
+                 SDL_GPU_TEXTUREFORMAT_R16G16B16A16_FLOAT, SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UINT,
+                 SDL_GPU_TEXTUREFORMAT_R16G16B16A16_INT -> 16;
+            case SDL_GPU_TEXTUREFORMAT_R32_FLOAT, SDL_GPU_TEXTUREFORMAT_R32_UINT,
+                 SDL_GPU_TEXTUREFORMAT_R32_INT, SDL_GPU_TEXTUREFORMAT_R32G32_FLOAT,
+                 SDL_GPU_TEXTUREFORMAT_R32G32_UINT, SDL_GPU_TEXTUREFORMAT_R32G32_INT,
+                 SDL_GPU_TEXTUREFORMAT_R32G32B32A32_FLOAT, SDL_GPU_TEXTUREFORMAT_R32G32B32A32_UINT,
+                 SDL_GPU_TEXTUREFORMAT_R32G32B32A32_INT -> 32;
+            default -> 0;
+        };
+    }
+
+    private static int sdlFormatColorComponents(int sdlFormat) {
+        return switch (sdlFormat) {
+            case SDL_GPU_TEXTUREFORMAT_R8_UNORM, SDL_GPU_TEXTUREFORMAT_R8_SNORM,
+                 SDL_GPU_TEXTUREFORMAT_R8_UINT, SDL_GPU_TEXTUREFORMAT_R8_INT,
+                 SDL_GPU_TEXTUREFORMAT_R16_UNORM, SDL_GPU_TEXTUREFORMAT_R16_SNORM,
+                 SDL_GPU_TEXTUREFORMAT_R16_FLOAT, SDL_GPU_TEXTUREFORMAT_R16_UINT,
+                 SDL_GPU_TEXTUREFORMAT_R16_INT, SDL_GPU_TEXTUREFORMAT_R32_FLOAT,
+                 SDL_GPU_TEXTUREFORMAT_R32_UINT, SDL_GPU_TEXTUREFORMAT_R32_INT -> 1;
+            case SDL_GPU_TEXTUREFORMAT_R8G8_UNORM, SDL_GPU_TEXTUREFORMAT_R8G8_SNORM,
+                 SDL_GPU_TEXTUREFORMAT_R8G8_UINT, SDL_GPU_TEXTUREFORMAT_R8G8_INT,
+                 SDL_GPU_TEXTUREFORMAT_R16G16_UNORM, SDL_GPU_TEXTUREFORMAT_R16G16_SNORM,
+                 SDL_GPU_TEXTUREFORMAT_R16G16_FLOAT, SDL_GPU_TEXTUREFORMAT_R16G16_UINT,
+                 SDL_GPU_TEXTUREFORMAT_R16G16_INT, SDL_GPU_TEXTUREFORMAT_R32G32_FLOAT,
+                 SDL_GPU_TEXTUREFORMAT_R32G32_UINT, SDL_GPU_TEXTUREFORMAT_R32G32_INT -> 2;
+            default -> 4;
+        };
+    }
+
     public static int glPixelSize(int format, int type) {
         final int packed = GLTypes.packedTexelBytes(type);
         if (packed != 0) return packed;

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/resource/ResourceManager.java

@@ -127,6 +127,10 @@ public final class ResourceManager {
 
     private int preferredD24 = SDL_GPU_TEXTUREFORMAT_D24_UNORM;
     private int preferredD24S8 = SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT;
+    private volatile int swapchainDepthStencilFormat = SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT;
+    private long swapchainDepthStencil;
+    private int swapchainDepthStencilWidth;
+    private int swapchainDepthStencilHeight;
 
     private static final Supplier<ContextState.VAOState> VAO_FACTORY = ContextState.VAOState::new;
     private static final Supplier<TextureSamplerState> TEX_SAMPLER_FACTORY = TextureSamplerState::new;
@@ -154,6 +158,21 @@ public final class ResourceManager {
             preferredD24S8 = SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT;
             LOG.info("D24_UNORM_S8_UINT not supported for depth+sampler, using D32_FLOAT_S8_UINT");
         }
+
+        swapchainDepthStencilFormat = preferredD24S8;
+        if (!SDL_GPUTextureSupportsFormat(dev, swapchainDepthStencilFormat, texType, SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET)) {
+            final int alt = swapchainDepthStencilFormat == SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT ? SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT : SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT;
+            if (SDL_GPUTextureSupportsFormat(dev, alt, texType, SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET)) {
+                swapchainDepthStencilFormat = alt;
+            } else {
+                swapchainDepthStencilFormat = 0;
+                LOG.warn("No depth+stencil format usable as a render target; default framebuffer will have no depth or stencil");
+            }
+        }
+    }
+
+    public int getSwapchainDepthStencilFormat() {
+        return swapchainDepthStencilFormat;
     }
 
     public int genTexture() {
@@ -189,6 +208,20 @@ public final class ResourceManager {
         return SDL_GPU_TEXTUREUSAGE_SAMPLER | SDL_GPU_TEXTUREUSAGE_COLOR_TARGET;
     }
 
+    public String describeGpuState() {
+        final FrameManager.FrameState f = frameManager.busiestFrame();
+        final StringBuilder sb = new StringBuilder(256);
+        sb.append("frame=").append(f.frameNumber)
+          .append(" submitsThisFrame=").append(f.submitsThisFrame)
+          .append(" mipGensThisFrame=").append(f.mipGensThisFrame)
+          .append(" pendingUpload=").append(f.pendingUploadBytes >> 10).append("KiB/").append(f.pendingUploadCommands).append("cmds")
+          .append('\n');
+        sb.append("arena capacity=").append(f.arena.capacity() >> 20).append("MiB used=").append(f.arena.usedBytes() >> 10)
+          .append("KiB copies=").append(f.arena.copyCount())
+          .append(" overflowFlushes=").append(f.arenaOverflowFlushesThisFrame);
+        return sb.toString();
+    }
+
     private long createTextureCore(int glId, int glTarget, int sdlFormat, int glFormat, int width, int height, int depth, int levels, int usage) {
         usage = reconcileUsageAndWarn(glId, usage);
         final int sdlType = mapTextureType(glTarget);
@@ -221,7 +254,7 @@ public final class ResourceManager {
             final long handle = SDL_CreateGPUTexture(device.getDevice(), ci);
             if (props != 0) SDLProperties.SDL_DestroyProperties(props);
             if (handle == 0) {
-                LOG.error("Failed to create texture {}x{} fmt=0x{} sdlFmt=0x{} usage=0x{}: {}", width, height, Integer.toHexString(glFormat), Integer.toHexString(sdlFormat), Integer.toHexString(usage), SDLError.SDL_GetError());
+                device.reportGpuFailure("createTexture " + width + "x" + height + " fmt=0x" + Integer.toHexString(glFormat) + " sdlFmt=0x" + Integer.toHexString(sdlFormat) + " usage=0x" + Integer.toHexString(usage));
                 return 0;
             }
             wLock.lock();
@@ -278,7 +311,7 @@ public final class ResourceManager {
         } finally {
             wLock.unlock();
         }
-        releaseTextureHandle(handle);
+        releaseTextureHandleAfterPendingUploads(handle);
     }
 
     public void releaseTextureHandleForRealloc(int glId) {
@@ -290,9 +323,24 @@ public final class ResourceManager {
         } finally {
             wLock.unlock();
         }
+        releaseTextureHandleAfterPendingUploads(handle);
+    }
+
+    private void releaseTextureHandleAfterPendingUploads(long handle) {
+        if (handle == 0) return;
+        if (shouldDeferTextureRelease()) {
+            releaseTextureDeferred(handle);
+            return;
+        }
         releaseTextureHandle(handle);
     }
 
+    boolean shouldDeferTextureRelease() {
+        final TransferThread tt = transferThread;
+        if (tt != null && tt.getSubmittedSeq() < lastTextureUploadSeq) return true;
+        return hasBatchedUploads();
+    }
+
     public void trackBufferHandle(long handle) {
         if (handle == 0) return;
         wLock.lock();
@@ -305,6 +353,40 @@ public final class ResourceManager {
         try { liveTextureHandles.add(handle); } finally { wLock.unlock(); }
     }
 
+    private final LongOpenHashSet definedContentTextures = new LongOpenHashSet();
+
+    public boolean isTextureContentDefined(long handle) {
+        if (handle == 0) return false;
+        if (fastRead()) return definedContentTextures.contains(handle);
+        rLock.lock();
+        try { return definedContentTextures.contains(handle); } finally { rLock.unlock(); }
+    }
+
+    public void markTextureContentDefined(long handle) {
+        if (handle == 0) return;
+        wLock.lock();
+        try { definedContentTextures.add(handle); } finally { wLock.unlock(); }
+    }
+
+    void markTextureContentsDefined(LongArrayList handles) {
+        if (handles.isEmpty()) return;
+        wLock.lock();
+        try {
+            for (int i = 0, n = handles.size(); i < n; i++) {
+                final long handle = handles.getLong(i);
+                if (handle != 0) definedContentTextures.add(handle);
+            }
+        } finally {
+            wLock.unlock();
+        }
+    }
+
+    public void markTextureContentUndefined(long handle) {
+        if (handle == 0) return;
+        wLock.lock();
+        try { definedContentTextures.remove(handle); } finally { wLock.unlock(); }
+    }
+
     public void releaseBufferHandle(long handle) {
         if (handle == 0) return;
         final boolean live;
@@ -324,6 +406,8 @@ public final class ResourceManager {
 
     public void releaseTextureHandle(long handle) {
         if (handle == 0) return;
+        dropBatchedUploadsTargeting(handle);
+        markTextureContentUndefined(handle);
         final boolean live;
         wLock.lock();
         try {
@@ -503,7 +587,7 @@ public final class ResourceManager {
         final GpuBucket b = gpuBufferPool.get(Hashing.packHiLo(usage, bucket));
         if (b == null || b.handles.isEmpty()) return 0;
         for (int i = 0, n = b.handles.size(); i < n; i++) {
-            if (gpuPoolCurrentFrame - b.frames.getLong(i) >= Device.FRAMES_IN_FLIGHT) {
+            if (gpuPoolCurrentFrame - b.frames.getLong(i) >= Device.MAX_FRAMES_IN_FLIGHT) {
                 final long handle = b.handles.getLong(i);
                 final int last = n - 1;
                 if (i != last) {
@@ -606,6 +690,7 @@ public final class ResourceManager {
 
     private final LongArrayList deferredBufferReleases = new LongArrayList();
     private final LongArrayList deferredTextureReleases = new LongArrayList();
+    private volatile long lastTextureUploadSeq;
 
     public void deleteBuffer(int glId) {
         final ByteBuffer droppedPboStaging;
@@ -1291,7 +1376,7 @@ public final class ResourceManager {
             for (int i = 0; i < n; i += 2) {
                 final long handle = batchSegmentPending.getLong(i);
                 final long stamp = batchSegmentPending.getLong(i + 1);
-                if (currentFrame - stamp >= Device.FRAMES_IN_FLIGHT) {
+                if (currentFrame - stamp >= Device.MAX_FRAMES_IN_FLIGHT) {
                     batchSegmentFree.enqueue(handle);
                 } else {
                     batchSegmentPending.set(w, handle);
@@ -1311,7 +1396,7 @@ public final class ResourceManager {
 
             final long handle = SDL_CreateGPUTransferBuffer(device.getDevice(), ci);
             if (handle == 0) {
-                LOG.error("Failed to create transfer buffer size={}: {}", size, SDLError.SDL_GetError());
+                device.reportGpuFailure("createTransferBuffer size=" + size);
             } else {
                 synchronized (xferPoolLock) { liveTransferBufferHandles.add(handle); }
             }
@@ -1413,7 +1498,7 @@ public final class ResourceManager {
         f.arenaCommandBuffer = SDL_AcquireGPUCommandBuffer(device.getDevice());
         if (f.arenaCommandBuffer == 0) {
             LOG.error("Failed to acquire arena upload command buffer: {}", SDLError.SDL_GetError());
-            f.arenaMapped = null;
+            unmapArena(f);
             return false;
         }
         f.arenaCopyPass = SDL_BeginGPUCopyPass(f.arenaCommandBuffer);
@@ -1421,12 +1506,18 @@ public final class ResourceManager {
             LOG.error("Failed to begin arena copy pass: {}", SDLError.SDL_GetError());
             SDL_SubmitGPUCommandBuffer(f.arenaCommandBuffer);
             f.arenaCommandBuffer = 0;
-            f.arenaMapped = null;
+            unmapArena(f);
             return false;
         }
         return true;
     }
 
+    private void unmapArena(FrameManager.FrameState f) {
+        if (f.arenaMapped == null) return;
+        SDL_UnmapGPUTransferBuffer(device.getDevice(), f.arenaXfer);
+        f.arenaMapped = null;
+    }
+
     public void flushUploadArena() {
         flushUploadArena(frameManager.frame());
     }
@@ -1442,7 +1533,7 @@ public final class ResourceManager {
         }
         if (f.arenaCommandBuffer != 0) {
             if (!SDL_SubmitGPUCommandBuffer(f.arenaCommandBuffer)) {
-                LOG.error("Failed to submit arena upload command buffer: {}", SDLError.SDL_GetError());
+                device.reportGpuFailure("submit arena upload command buffer");
             }
             f.arenaCommandBuffer = 0;
             if (Tracy.ENABLED) f.arenaSubmitsThisFrame++;
@@ -1540,12 +1631,16 @@ public final class ResourceManager {
             f.batchMapped = null;
         }
 
+        markTextureContentsDefined(f.pendingTexHandles);
+
         try (var stack = stackPush()) {
             final SDL_GPUTextureTransferInfo src = SDL_GPUTextureTransferInfo.calloc(stack);
             final SDL_GPUTextureRegion dst = SDL_GPUTextureRegion.calloc(stack);
             for (int i = 0; i < n; i++) {
+                final long texture = f.pendingTexHandles.getLong(i);
+                if (texture == 0) continue;
                 src.transfer_buffer(f.batchXfer).offset(f.pendingTexOffsets.getInt(i));
-                dst.texture(f.pendingTexHandles.getLong(i)).mip_level(f.pendingTexLevels.getInt(i))
+                dst.texture(texture).mip_level(f.pendingTexLevels.getInt(i))
                     .x(f.pendingTexX.getInt(i)).y(f.pendingTexY.getInt(i)).z(0)
                     .w(f.pendingTexW.getInt(i)).h(f.pendingTexH.getInt(i)).d(1);
                 SDL_UploadToGPUTexture(copyPass, src, dst, false);
@@ -1566,6 +1661,14 @@ public final class ResourceManager {
         frameManager.recordUploadCommands(totalBytes, n);
     }
 
+    void dropBatchedUploadsTargeting(long handle) {
+        final LongArrayList handles = frameManager.frame().pendingTexHandles;
+        if (handles.isEmpty()) return;
+        for (int i = 0, n = handles.size(); i < n; i++) {
+            if (handles.getLong(i) == handle) handles.set(i, 0L);
+        }
+    }
+
     public boolean hasBatchedUploads() {
         return !frameManager.frame().pendingTexHandles.isEmpty();
     }
@@ -1596,6 +1699,7 @@ public final class ResourceManager {
                 .w(w).h(h).d(d);
             SDL_UploadToGPUTexture(copyPass, src, dst, false);
         }
+        markTextureContentDefined(gpuTexture);
 
         frameManager.recordUploadCommands(size, 1);
         returnTransferBuffer(xfer, size);
@@ -1629,6 +1733,7 @@ public final class ResourceManager {
 
             SDL_UploadToGPUTexture(copyPass, src, dst, false);
         }
+        markTextureContentDefined(gpuTexture);
 
         frameManager.recordUploadCommands(size, 1);
         returnTransferBuffer(xfer, size);
@@ -1650,6 +1755,8 @@ public final class ResourceManager {
         SDL_UnmapGPUTransferBuffer(device.getDevice(), xfer);
         final long seq = TransferThread.nextSeq();
         st.frameHighestEnqueuedSeq = seq;
+        lastTextureUploadSeq = seq;
+        markTextureContentDefined(texHandle);
         tt.enqueue(TransferThread.TextureRegionUpload.acquire(xfer, texHandle, x, y, w, h, level, size, seq));
         tt.wake();
         return true;
@@ -1979,8 +2086,36 @@ public final class ResourceManager {
         return dummyColorTarget;
     }
 
+    public long getOrCreateSwapchainDepthStencil(int width, int height) {
+        if (swapchainDepthStencilFormat == 0 || width <= 0 || height <= 0) return 0;
+        if (swapchainDepthStencil != 0 && swapchainDepthStencilWidth == width && swapchainDepthStencilHeight == height) {
+            return swapchainDepthStencil;
+        }
+        if (swapchainDepthStencil != 0) {
+            releaseTextureDeferred(swapchainDepthStencil);
+            swapchainDepthStencil = 0;
+        }
+        try (var stack = stackPush()) {
+            final SDL_GPUTextureCreateInfo ci = SDL_GPUTextureCreateInfo.calloc(stack)
+                .type(SDL_GPU_TEXTURETYPE_2D)
+                .format(swapchainDepthStencilFormat)
+                .usage(SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET)
+                .width(width).height(height).layer_count_or_depth(1).num_levels(1);
+            swapchainDepthStencil = SDL_CreateGPUTexture(device.getDevice(), ci);
+        }
+        if (swapchainDepthStencil == 0) {
+            swapchainDepthStencilFormat = 0;
+            LOG.warn("Failed to create the default framebuffer depth+stencil target ({}x{}); it will have neither", width, height);
+            return 0;
+        }
+        trackTextureHandle(swapchainDepthStencil);
+        swapchainDepthStencilWidth = width;
+        swapchainDepthStencilHeight = height;
+        return swapchainDepthStencil;
+    }
+
     private static final int DUMMY_VBO_SIZE = 16 * 16;
-    public static final int ATTRIB_RING_BLOCKS = 2048 * Device.FRAMES_IN_FLIGHT;
+    public static final int ATTRIB_RING_BLOCKS = 2048 * Device.MAX_FRAMES_IN_FLIGHT;
     public static final int ATTRIB_RING_CHUNK_BLOCKS = 64;
     private static final int ATTRIB_RING_CHUNKS = ATTRIB_RING_BLOCKS / ATTRIB_RING_CHUNK_BLOCKS;
     private final AtomicLong attribRingCounter = new AtomicLong();
@@ -2094,6 +2229,8 @@ public final class ResourceManager {
             case GL14.GL_DEPTH_COMPONENT32, GL30.GL_DEPTH_COMPONENT32F -> SDL_GPU_TEXTUREFORMAT_D32_FLOAT;
             case GL30.GL_DEPTH24_STENCIL8 -> preferredD24S8;
             case GL30.GL_DEPTH32F_STENCIL8 -> SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT;
+            case GL11.GL_STENCIL_INDEX, GL30.GL_STENCIL_INDEX1, GL30.GL_STENCIL_INDEX4,
+                 GL30.GL_STENCIL_INDEX8, GL30.GL_STENCIL_INDEX16 -> preferredD24S8;
             case GL30.GL_R8UI -> SDL_GPU_TEXTUREFORMAT_R8_UINT;
             case GL30.GL_R16UI -> SDL_GPU_TEXTUREFORMAT_R16_UINT;
             case GL30.GL_R32UI -> SDL_GPU_TEXTUREFORMAT_R32_UINT;
@@ -2213,6 +2350,12 @@ public final class ResourceManager {
             releaseTextureHandle(dummyColorTarget);
             dummyColorTarget = 0;
         }
+        if (swapchainDepthStencil != 0) {
+            releaseTextureHandle(swapchainDepthStencil);
+            swapchainDepthStencil = 0;
+            swapchainDepthStencilWidth = 0;
+            swapchainDepthStencilHeight = 0;
+        }
         if (fallbackStorageTexture3D != 0) {
             releaseTextureHandle(fallbackStorageTexture3D);
             fallbackStorageTexture3D = 0;

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/resource/TextureOps.java

@@ -101,19 +101,11 @@ public final class TextureOps {
 
     public void readbackTexture(long texHandle, int x, int y, int w, int h, int level, ByteBuffer output) {
         if (texHandle == 0 || output == null) return;
-        frameManager.endCopyPassIfActive();
-        frameManager.endRenderPassIfActive();
+        frameManager.submitMidFrame();
 
-        if (texHandle == frameManager.getSwapchainTexture()) {
-            final long cb = frameManager.getCommandBuffer();
-            if (cb == 0) return;
-            resourceManager.downloadFromTexture(cb, texHandle, x, y, w, h, level, output);
-            frameManager.reacquireCommandBuffer();
-        } else {
-            final long cb = SDL_AcquireGPUCommandBuffer(device.getDevice());
-            if (cb == 0) return;
-            resourceManager.downloadFromTexture(cb, texHandle, x, y, w, h, level, output);
-        }
+        final long cb = SDL_AcquireGPUCommandBuffer(device.getDevice());
+        if (cb == 0) return;
+        resourceManager.downloadFromTexture(cb, texHandle, x, y, w, h, level, output);
     }
 
     public void copyTexSubImageImpl(ContextState st, int destGlId, int level, int xoffset, int yoffset, int x, int y, int width, int height) {
@@ -207,15 +199,14 @@ public final class TextureOps {
             SDL_GenerateMipmapsForGPUTexture(uploadCb, handle);
         }
 
+        if (!SDL_SubmitGPUCommandBuffer(uploadCb)) {
+            device.reportGpuFailure("submit mipmap generation CB");
+        }
+        frameManager.noteMipGenSubmit();
+
         if (f.commandBuffer == uploadCb) {
-            if (!SDL_SubmitGPUCommandBuffer(uploadCb)) {
-                LOG.error("drainPendingMipGen: failed to submit frame CB: {}", SDLError.SDL_GetError());
-            }
             f.commandBuffer = 0;
         } else {
-            if (!SDL_SubmitGPUCommandBuffer(uploadCb)) {
-                LOG.error("drainPendingMipGen: failed to submit pending-upload CB: {}", SDLError.SDL_GetError());
-            }
             f.pendingUploadCommandBuffer = 0;
             f.pendingUploadBytes = 0;
             f.pendingUploadCommands = 0;

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/resource/TransferThread.java

@@ -17,6 +17,7 @@ import java.util.concurrent.locks.LockSupport;
 import com.gtnewhorizons.angelica.glsm.profiling.Tracy;
 import com.gtnewhorizons.angelica.glsm.profiling.TracyBackend;
 import com.gtnewhorizons.angelica.sdlgpu.device.Device;
+import com.gtnewhorizons.angelica.sdlgpu.device.GpuDeviceLostException;
 import com.gtnewhorizons.angelica.sdlgpu.resource.ResourceManager;
 import it.unimi.dsi.fastutil.longs.LongArrayList;
 import org.lwjgl.system.MemoryUtil;
@@ -33,6 +34,7 @@ public final class TransferThread {
     private static final Tracy.ZoneId Z_SDL_UPLOAD = Tracy.zoneId("sdlUpload", Tracy.COLOR_WORKER);
 
     private static final Logger LOG = LogManager.getLogger("Angelica-SDLGPU-Transfer");
+    private boolean warnedNullTextureUpload;
 
     private static final AtomicLong SEQ = new AtomicLong();
 
@@ -213,34 +215,59 @@ public final class TransferThread {
         return flushRequestedSeq > submittedSeq || openBytes >= FLUSH_COALESCE_BYTES || openCount >= FLUSH_COALESCE_COMMANDS;
     }
 
+    static boolean shouldPublishRetired(boolean hasOpenCB, long openHighestSeq, long submittedSeq) {
+        return !hasOpenCB && openHighestSeq > submittedSeq;
+    }
+
+    private void publishSubmittedSeq() {
+        if (openHighestSeq <= submittedSeq) return;
+        synchronized (submittedLock) {
+            submittedSeq = openHighestSeq;
+            submittedLock.notifyAll();
+        }
+        drainDuePendingFrees();
+    }
+
     private void run() {
         LOG.info("Transfer thread started");
-        while (!shutdown) {
-            final long workStart = Tracy.ENABLED ? System.nanoTime() : 0L;
-            // Drain all pending uploads
-            DeferredUpload upload = queue.poll();
-            if (upload != null) {
-                do {
-                    processOne(upload);
-                    upload = queue.poll();
-                } while (upload != null);
-            }
-
-            if (shouldFlush(openCB != 0, flushRequestedSeq, submittedSeq, openBytes, openCount)) {
-                flushOpenCB();
-            }
-
-            if (Tracy.ENABLED) pendingActiveNanos += System.nanoTime() - workStart;
-
-            if (queue.isEmpty() && !shutdown) {
-                parked = true;
-                if (queue.isEmpty() && !shutdown && flushRequestedSeq <= submittedSeq) {
-                    LockSupport.parkNanos(1_000_000L); // 1ms
+        try {
+            while (!shutdown) {
+                final long workStart = Tracy.ENABLED ? System.nanoTime() : 0L;
+                // Drain all pending uploads
+                DeferredUpload upload = queue.poll();
+                if (upload != null) {
+                    do {
+                        processOne(upload);
+                        upload = queue.poll();
+                    } while (upload != null);
                 }
-                parked = false;
+
+                if (shouldFlush(openCB != 0, flushRequestedSeq, submittedSeq, openBytes, openCount)) {
+                    flushOpenCB();
+                } else if (shouldPublishRetired(openCB != 0, openHighestSeq, submittedSeq)) {
+                    publishSubmittedSeq();
+                    openHighestSeq = 0;
+                }
+
+                if (Tracy.ENABLED) pendingActiveNanos += System.nanoTime() - workStart;
+
+                if (queue.isEmpty() && !shutdown) {
+                    parked = true;
+                    if (queue.isEmpty() && !shutdown && flushRequestedSeq <= submittedSeq) {
+                        LockSupport.parkNanos(1_000_000L); // 1ms
+                    }
+                    parked = false;
+                }
+            }
+            if (openCB != 0) flushOpenCB();
+        } catch (GpuDeviceLostException e) {
+            LOG.error("Transfer thread stopping: {}", e.getMessage());
+        } finally {
+            synchronized (submittedLock) {
+                submittedSeq = Long.MAX_VALUE;
+                submittedLock.notifyAll();
             }
         }
-        if (openCB != 0) flushOpenCB();
         drainAllPendingFreesOnShutdown();
         srcLoc.free();
         dstRegion.free();
@@ -305,10 +332,18 @@ public final class TransferThread {
         return true;
     }
 
+    private void retireSeq(long seq) {
+        openHighestSeq = Math.max(openHighestSeq, seq);
+    }
+
     private void recordBufferUpload(long transferBuffer, long size, long dstGpuBuffer, long dstOffset, long seq, boolean cycle) {
-        if (transferBuffer == 0) return;
+        if (transferBuffer == 0) {
+            retireSeq(seq);
+            return;
+        }
         if (!ensureOpenCB()) {
             resourceManager.returnTransferBufferThreadSafe(transferBuffer, size);
+            retireSeq(seq);
             return;
         }
         srcLoc.transfer_buffer(transferBuffer).offset(0);
@@ -323,7 +358,10 @@ public final class TransferThread {
     }
 
     private void recordGpuCopy(long srcHandle, long dstHandle, long readOffset, long writeOffset, long size, long seq) {
-        if (!ensureOpenCB()) return;
+        if (!ensureOpenCB()) {
+            retireSeq(seq);
+            return;
+        }
         srcBufLoc.buffer(srcHandle).offset((int) readOffset);
         dstBufLoc.buffer(dstHandle).offset((int) writeOffset);
         SDL_CopyGPUBufferToBuffer(openCopyPass, srcBufLoc, dstBufLoc, (int) size, false);
@@ -334,9 +372,22 @@ public final class TransferThread {
     }
 
     private void recordTextureUpload(long transferBuffer, long texHandle, int x, int y, int w, int h, int level, long size, long seq) {
-        if (transferBuffer == 0) return;
+        if (transferBuffer == 0) {
+            retireSeq(seq);
+            return;
+        }
+        if (texHandle == 0) {
+            if (!warnedNullTextureUpload) {
+                warnedNullTextureUpload = true;
+                LOG.warn("Deferred texture upload with no destination texture; dropped (level={} {}x{} at {},{})", level, w, h, x, y);
+            }
+            resourceManager.returnTransferBufferThreadSafe(transferBuffer, size);
+            retireSeq(seq);
+            return;
+        }
         if (!ensureOpenCB()) {
             resourceManager.returnTransferBufferThreadSafe(transferBuffer, size);
+            retireSeq(seq);
             return;
         }
         texXferInfo.transfer_buffer(transferBuffer).offset(0);
@@ -355,15 +406,10 @@ public final class TransferThread {
 
         SDL_EndGPUCopyPass(openCopyPass);
         if (!SDL_SubmitGPUCommandBuffer(openCB)) {
-            LOG.error("Failed to submit transfer command buffer: {}", SDLError.SDL_GetError());
+            device.reportGpuFailure("submit transfer command buffer");
         }
 
-        synchronized (submittedLock) {
-            submittedSeq = openHighestSeq;
-            submittedLock.notifyAll();
-        }
-
-        drainDuePendingFrees();
+        publishSubmittedSeq();
 
         for (int i = 0, n = pendingReturnHandles.size(); i < n; i++) {
             resourceManager.returnTransferBufferThreadSafe(pendingReturnHandles.getLong(i), pendingReturnSizes.getLong(i));

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/resource/UploadArena.java

@@ -3,6 +3,8 @@ package com.gtnewhorizons.angelica.sdlgpu.resource;
 public final class UploadArena {
     public static final int INITIAL_CAPACITY = 16 * 1024 * 1024;
 
+    public static final int MAX_CAPACITY = 64 * 1024 * 1024;
+
     private static final int ALIGNMENT = 16;
 
     private int capacity = INITIAL_CAPACITY;
@@ -23,8 +25,11 @@ public final class UploadArena {
         return size >= 0 && size <= capacity;
     }
 
-     public void requestGrow(int minSize) {
-        while (growTo < minSize) growTo <<= 1;
+    public void requestGrow(int minSize) {
+        if (minSize <= growTo) return;
+        long next = growTo;
+        while (next < minSize && next < MAX_CAPACITY) next <<= 1;
+        growTo = (int) Math.min(next, MAX_CAPACITY);
     }
 
    public boolean applyGrow() {

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/shader/PerFrameBlockInjector.java

@@ -31,11 +31,6 @@ public final class PerFrameBlockInjector {
     private PerFrameBlockInjector() {}
 
     public static String inject(String source, PerFrameUniformBlock perFrame, PerFrameUniformBlock perPass) {
-        final PerFrameUniformBlock[] blocks = new PerFrameUniformBlock[ShaderManager.BLOCK_COUNT];
-        blocks[ShaderManager.BLOCK_PER_FRAME] = normalize(perFrame);
-        blocks[ShaderManager.BLOCK_PER_PASS] = normalize(perPass);
-        if (blocks[0] == null && blocks[1] == null) return source;
-
         final GLSLParser.Translation_unitContext root;
         try {
             root = GlslTransformUtils.parseFullQuiet(source);
@@ -43,8 +38,19 @@ public final class PerFrameBlockInjector {
             return source;
         }
 
+        final List<Edit> edits = new ArrayList<>();
+        collectEdits(root, perFrame, perPass, edits);
+        return edits.isEmpty() ? source : applyEdits(source, edits);
+    }
+
+    public static void collectEdits(GLSLParser.Translation_unitContext root, PerFrameUniformBlock perFrame, PerFrameUniformBlock perPass, List<Edit> out) {
+        final PerFrameUniformBlock[] blocks = new PerFrameUniformBlock[ShaderManager.BLOCK_COUNT];
+        blocks[ShaderManager.BLOCK_PER_FRAME] = normalize(perFrame);
+        blocks[ShaderManager.BLOCK_PER_PASS] = normalize(perPass);
+        if (blocks[0] == null && blocks[1] == null) return;
+
         final int insertAt = firstDeclarationStart(root);
-        if (insertAt < 0) return source;
+        if (insertAt < 0) return;
 
         final Map<String, String> memberTypes = new LinkedHashMap<>();
         final Object2IntOpenHashMap<String> memberBlock = new Object2IntOpenHashMap<>();
@@ -71,18 +77,16 @@ public final class PerFrameBlockInjector {
                 if (referenced.contains(m.name())) { injected[b] = true; anyInjected = true; break; }
             }
         }
-        if (!anyInjected) return source;
+        if (!anyInjected) return;
 
-        final List<Edit> edits = new ArrayList<>(stripEdits.size() + 2);
         final StringBuilder blockDecls = new StringBuilder(128);
         for (int b = 0; b < blocks.length; b++) {
             if (injected[b]) appendBlockText(blockDecls, b, blocks[b].members(), shadowed);
         }
-        edits.add(new Edit(insertAt, insertAt - 1, blockDecls.toString()));
+        out.add(new Edit(insertAt, insertAt - 1, blockDecls.toString()));
         for (int i = 0; i < stripEdits.size(); i++) {
-            if (injected[stripBlocks.getInt(i)]) edits.add(stripEdits.get(i));
+            if (injected[stripBlocks.getInt(i)]) out.add(stripEdits.get(i));
         }
-        return applyEdits(source, edits);
     }
 
     private static PerFrameUniformBlock normalize(PerFrameUniformBlock block) {

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/shader/ShaderManager.java

@@ -188,19 +188,46 @@ public final class ShaderManager {
             return new PrewarmTransformResult(transformedSource, Set.of());
         }
         final List<Edit> edits = new ArrayList<>();
+        if (glShaderType == GL20.GL_VERTEX_SHADER || glShaderType == GL20.GL_FRAGMENT_SHADER) {
+            PerFrameBlockInjector.collectEdits(root, GLSMHooks.perFrameUniformBlock, GLSMHooks.perPassUniformBlock, edits);
+        }
         final GlslVulkanPreprocess.Metadata meta = GlslVulkanPreprocess.collectEdits(transformedSource, root, glShaderType, "prewarm", true, edits);
         if (glShaderType == GL20.GL_VERTEX_SHADER) {
             ClipZRemap.collectEdits(root, edits);
         }
         SamplerStripper.collectEdits(root, transformedSource, edits);
-        String s = edits.isEmpty() ? transformedSource : GlslVulkanPreprocess.applyEdits(transformedSource, edits);
-        if (glShaderType == GL20.GL_VERTEX_SHADER || glShaderType == GL20.GL_FRAGMENT_SHADER) {
-            s = PerFrameBlockInjector.inject(s, GLSMHooks.perFrameUniformBlock, GLSMHooks.perPassUniformBlock);
-        }
+        final String s = edits.isEmpty() ? transformedSource : GlslVulkanPreprocess.applyEdits(transformedSource, edits);
         return new PrewarmTransformResult(s, meta.boolUniforms());
     }
 
+    public static PrewarmTransformResult applyPrewarmTransformsFull(String finalSource, GLSLParser.Translation_unitContext bodyTree, int headerLen, int glShaderType) {
+        final String header = finalSource.substring(0, headerLen);
+        final String body = finalSource.substring(headerLen);
+        final List<Edit> edits = new ArrayList<>();
+        if (glShaderType == GL20.GL_VERTEX_SHADER || glShaderType == GL20.GL_FRAGMENT_SHADER) {
+            PerFrameBlockInjector.collectEdits(bodyTree, GLSMHooks.perFrameUniformBlock, GLSMHooks.perPassUniformBlock, edits);
+        }
+        final GlslVulkanPreprocess.Metadata meta = GlslVulkanPreprocess.collectEdits(null, bodyTree, glShaderType, "prewarm", true, edits);
+        if (glShaderType == GL20.GL_VERTEX_SHADER) {
+            ClipZRemap.collectEdits(bodyTree, edits);
+        }
+        SamplerStripper.collectEdits(bodyTree, body, edits);
+        String outHeader = header;
+        if (meta.needsSamplerless()) {
+            final int nl = header.indexOf('\n');
+            outHeader = header.substring(0, nl) + "\n" + GlslVulkanPreprocess.SAMPLERLESS_EXTENSION + header.substring(nl);
+        }
+        if (edits.isEmpty() && outHeader == header) {
+            return new PrewarmTransformResult(finalSource, meta.boolUniforms());
+        }
+        return new PrewarmTransformResult(outHeader + GlslVulkanPreprocess.applyEdits(body, edits), meta.boolUniforms());
+    }
+
     public static void prewarmSpirv(String transformedSource, int glShaderType) {
+        prewarmSpirv(transformedSource, null, 0, glShaderType);
+    }
+
+    public static void prewarmSpirv(String transformedSource, GLSLParser.Translation_unitContext bodyTree, int headerLen, int glShaderType) {
         if (glShaderType != GL20.GL_VERTEX_SHADER && glShaderType != GL20.GL_FRAGMENT_SHADER
             && glShaderType != GL43.GL_COMPUTE_SHADER && glShaderType != GL32.GL_GEOMETRY_SHADER) {
             return;
@@ -211,7 +238,9 @@ public final class ShaderManager {
             if (PREWARM_CACHE.containsKey(key)) return;
         }
 
-        final PrewarmTransformResult pre = applyPrewarmTransformsFull(transformedSource, glShaderType);
+        final PrewarmTransformResult pre = bodyTree != null
+            ? applyPrewarmTransformsFull(transformedSource, bodyTree, headerLen, glShaderType)
+            : applyPrewarmTransformsFull(transformedSource, glShaderType);
 
         final SpirvCompiler.Result r = SpirvCompiler.compile(pre.source(), shaderKindFor(glShaderType), "prewarm", SpirvCompiler.Options.vulkanForced460Core());
         if (r.spirv() == null) return;

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/shader/UscaledRetype.java

@@ -2,6 +2,7 @@ package com.gtnewhorizons.angelica.sdlgpu.shader;
 
 import com.gtnewhorizons.angelica.glsm.GlslTransformUtils;
 import com.gtnewhorizons.angelica.glsm.shader.GlslVulkanPreprocess.Edit;
+import it.unimi.dsi.fastutil.objects.Object2ObjectLinkedOpenHashMap;
 import org.antlr.v4.runtime.Token;
 import org.antlr.v4.runtime.tree.ParseTreeWalker;
 import org.taumc.glsl.grammar.GLSLParser;
@@ -18,11 +19,29 @@ public final class UscaledRetype {
 
     public record Attrib(String name, int location, int declVecSize, int boundVecSize, boolean signed) {}
 
+    private record RetypeKey(String source, List<Attrib> attribs) {}
+
+    private static final int CACHE_MAX = 64;
+    private static final Object2ObjectLinkedOpenHashMap<RetypeKey, String> CACHE = new Object2ObjectLinkedOpenHashMap<>();
+
     private UscaledRetype() {}
 
     public static String retype(String source, List<Attrib> attribs) {
         if (attribs.isEmpty()) return source;
 
+        final RetypeKey key = new RetypeKey(source, List.copyOf(attribs));
+        synchronized (CACHE) {
+            if (CACHE.containsKey(key)) return CACHE.getAndMoveToFirst(key);
+        }
+        final String result = retypeUncached(source, attribs);
+        synchronized (CACHE) {
+            CACHE.putAndMoveToFirst(key, result);
+            while (CACHE.size() > CACHE_MAX) CACHE.removeLast();
+        }
+        return result;
+    }
+
+    private static String retypeUncached(String source, List<Attrib> attribs) {
         final GLSLParser.Translation_unitContext root;
         try {
             root = GlslTransformUtils.parseFullQuiet(source);

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/splash/SplashDispatcher.java

@@ -1,6 +1,7 @@
 package com.gtnewhorizons.angelica.sdlgpu.splash;
 
 import com.gtnewhorizons.angelica.sdlgpu.SDLGPURenderBackend;
+import com.gtnewhorizons.angelica.sdlgpu.frame.OffscreenTarget;
 
 public final class SplashDispatcher {
 
@@ -32,7 +33,7 @@ public final class SplashDispatcher {
         return (long) w << 32 | (h & 0xffffffffL);
     }
 
-    public static void tryDispatch(SDLGPURenderBackend backend, SplashOffscreenTarget target) {
+    public static void tryDispatch(SDLGPURenderBackend backend, OffscreenTarget target) {
         if (!frameReady || target == null) return;
         final long now = System.nanoTime();
         if (now - lastBlitNanos < MIN_INTERVAL_NS) return;

sdl-gpu/src/main/java/com/gtnewhorizons/angelica/sdlgpu/util/ThreadRegistry.java

@@ -0,0 +1,67 @@
+package com.gtnewhorizons.angelica.sdlgpu.util;
+
+import java.util.Arrays;
+
+public final class ThreadRegistry<T> {
+
+    private final T[] empty;
+    private final Object lock = new Object();
+
+    private volatile T[] entries;
+    private volatile T sole;
+
+    public ThreadRegistry(T[] empty) {
+        this.empty = empty;
+        this.entries = empty;
+    }
+
+    public T sole() {
+        return sole;
+    }
+
+    public T[] snapshot() {
+        return entries;
+    }
+
+    public int size() {
+        return entries.length;
+    }
+
+    public void add(T entry) {
+        synchronized (lock) {
+            final T[] prev = entries;
+            final T[] next = Arrays.copyOf(prev, prev.length + 1);
+            next[prev.length] = entry;
+            publish(next);
+        }
+    }
+
+    public boolean remove(T entry) {
+        synchronized (lock) {
+            final T[] prev = entries;
+            int idx = -1;
+            for (int i = 0; i < prev.length; i++) {
+                if (prev[i] == entry) {
+                    idx = i;
+                    break;
+                }
+            }
+            if (idx < 0) return false;
+            final T[] next = Arrays.copyOf(prev, prev.length - 1);
+            System.arraycopy(prev, idx + 1, next, idx, prev.length - idx - 1);
+            publish(next);
+        }
+        return true;
+    }
+
+    public void clear() {
+        synchronized (lock) {
+            publish(empty);
+        }
+    }
+
+    private void publish(T[] next) {
+        entries = next;
+        sole = next.length == 1 ? next[0] : null;
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/FramebufferAttachmentQueryTest.java

@@ -0,0 +1,92 @@
+package com.gtnewhorizons.angelica.sdlgpu;
+
+import com.gtnewhorizons.angelica.sdlgpu.resource.FboState;
+import org.junit.jupiter.api.Test;
+import org.lwjgl.opengl.GL11;
+import org.lwjgl.opengl.GL30;
+
+import static com.gtnewhorizons.angelica.sdlgpu.SDLGPURenderBackend.defaultFramebufferAttachmentParameteri;
+import static com.gtnewhorizons.angelica.sdlgpu.SDLGPURenderBackend.fboAttachmentParameteri;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_D24_UNORM;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM;
+
+class FramebufferAttachmentQueryTest {
+
+    private static final int COLOR = SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM;
+
+    private static int defaultFb(int attachment, int pname, int depthFormat) {
+        return defaultFramebufferAttachmentParameteri(attachment, pname, COLOR, depthFormat);
+    }
+
+    @Test
+    void defaultFramebufferReportsEightStencilBits() {
+        assertEquals(8, defaultFb(GL11.GL_STENCIL, GL30.GL_FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE, SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT));
+        assertEquals(8, defaultFb(GL11.GL_STENCIL, GL30.GL_FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE, SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT));
+    }
+
+    @Test
+    void defaultFramebufferReportsDepthAndColorSizes() {
+        assertEquals(24, defaultFb(GL11.GL_DEPTH, GL30.GL_FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE, SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT));
+        assertEquals(32, defaultFb(GL11.GL_DEPTH, GL30.GL_FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE, SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT));
+        assertEquals(8, defaultFb(GL11.GL_BACK_LEFT, GL30.GL_FRAMEBUFFER_ATTACHMENT_RED_SIZE, SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT));
+        assertEquals(8, defaultFb(GL11.GL_BACK_LEFT, GL30.GL_FRAMEBUFFER_ATTACHMENT_ALPHA_SIZE, SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT));
+    }
+
+    @Test
+    void defaultFramebufferWithoutDepthReportsNone() {
+        assertEquals(0, defaultFb(GL11.GL_STENCIL, GL30.GL_FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE, 0));
+        assertEquals(0, defaultFb(GL11.GL_DEPTH, GL30.GL_FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE, 0));
+        assertEquals(GL11.GL_NONE, defaultFb(GL11.GL_DEPTH, GL30.GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE, 0));
+        assertEquals(GL30.GL_FRAMEBUFFER_DEFAULT, defaultFb(GL11.GL_BACK_LEFT, GL30.GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE, 0));
+    }
+
+    @Test
+    void packedDepthStencilAttachmentReportsBothAspects() {
+        final FboState fbo = new FboState();
+        fbo.depthGlId = 42;
+        fbo.depthTexture = 0xDDDDL;
+        fbo.depthFormat = SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT;
+
+        for (int attachment : new int[]{ GL30.GL_DEPTH_ATTACHMENT, GL30.GL_STENCIL_ATTACHMENT, GL30.GL_DEPTH_STENCIL_ATTACHMENT, GL11.GL_STENCIL }) {
+            assertEquals(8, fboAttachmentParameteri(fbo, attachment, GL30.GL_FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE), "attachment " + attachment);
+        }
+        assertEquals(24, fboAttachmentParameteri(fbo, GL30.GL_DEPTH_ATTACHMENT, GL30.GL_FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE));
+        assertEquals(42, fboAttachmentParameteri(fbo, GL30.GL_DEPTH_ATTACHMENT, GL30.GL_FRAMEBUFFER_ATTACHMENT_OBJECT_NAME));
+        assertEquals(GL11.GL_TEXTURE, fboAttachmentParameteri(fbo, GL30.GL_DEPTH_ATTACHMENT, GL30.GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE));
+    }
+
+    @Test
+    void depthOnlyAttachmentReportsNoStencil() {
+        final FboState fbo = new FboState();
+        fbo.depthGlId = 7;
+        fbo.depthTexture = 0xDDDDL;
+        fbo.depthFormat = SDL_GPU_TEXTUREFORMAT_D24_UNORM;
+
+        assertEquals(0, fboAttachmentParameteri(fbo, GL11.GL_STENCIL, GL30.GL_FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE));
+        assertEquals(24, fboAttachmentParameteri(fbo, GL11.GL_DEPTH, GL30.GL_FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE));
+    }
+
+    @Test
+    void missingAttachmentReportsNone() {
+        final FboState fbo = new FboState();
+        assertEquals(GL11.GL_NONE, fboAttachmentParameteri(fbo, GL30.GL_DEPTH_ATTACHMENT, GL30.GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE));
+        assertEquals(0, fboAttachmentParameteri(fbo, GL30.GL_DEPTH_ATTACHMENT, GL30.GL_FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE));
+        assertEquals(0, fboAttachmentParameteri(null, GL30.GL_DEPTH_ATTACHMENT, GL30.GL_FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE));
+    }
+
+    @Test
+    void colorAttachmentReportsChannelSizes() {
+        final FboState fbo = new FboState();
+        fbo.colorGlIds[1] = 11;
+        fbo.colorTextures[1] = 0xCCCCL;
+        fbo.colorFormats[1] = SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM;
+
+        assertEquals(8, fboAttachmentParameteri(fbo, GL30.GL_COLOR_ATTACHMENT0 + 1, GL30.GL_FRAMEBUFFER_ATTACHMENT_GREEN_SIZE));
+        assertEquals(11, fboAttachmentParameteri(fbo, GL30.GL_COLOR_ATTACHMENT0 + 1, GL30.GL_FRAMEBUFFER_ATTACHMENT_OBJECT_NAME));
+        assertEquals(GL11.GL_NONE, fboAttachmentParameteri(fbo, GL30.GL_COLOR_ATTACHMENT0, GL30.GL_FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE));
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/ImageUnitBindingStateTest.java

@@ -7,7 +7,6 @@ import org.lwjgl.opengl.GL15;
 import org.lwjgl.opengl.GL30;
 import org.lwjgl.opengl.GL42;
 
-import java.lang.reflect.Field;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
@@ -15,17 +14,11 @@ import static org.junit.jupiter.api.Assertions.assertTrue;
 
 class ImageUnitBindingStateTest {
 
-    @SuppressWarnings("unchecked")
-    private static ContextState state() throws Exception {
-        final Field f = SDLGPURenderBackend.class.getDeclaredField("tlState");
-        f.setAccessible(true);
-        return ((ThreadLocal<ContextState>) f.get(null)).get();
-    }
 
     @Test
-    void bindImageTextureRecordsTheFullTuple() throws Exception {
+    void bindImageTextureRecordsTheFullTuple() {
         final SDLGPURenderBackend backend = new SDLGPURenderBackend();
-        final ContextState st = state();
+        final ContextState st = SdlTestRig.contextState();
 
         backend.bindImageTexture(2, 77, 3, true, 5, GL15.GL_READ_WRITE, GL30.GL_R32UI);
 
@@ -38,7 +31,7 @@ class ImageUnitBindingStateTest {
     }
 
     @Test
-    void getIntegerIndexedAnswersImageBindingsFromState() throws Exception {
+    void getIntegerIndexedAnswersImageBindingsFromState() {
         final SDLGPURenderBackend backend = new SDLGPURenderBackend();
 
         backend.bindImageTexture(1, 42, 2, false, 4, GL15.GL_READ_ONLY, GL30.GL_RGBA32UI);
@@ -52,9 +45,9 @@ class ImageUnitBindingStateTest {
     }
 
     @Test
-    void outOfRangeUnitIsIgnored() throws Exception {
+    void outOfRangeUnitIsIgnored() {
         final SDLGPURenderBackend backend = new SDLGPURenderBackend();
-        final ContextState st = state();
+        final ContextState st = SdlTestRig.contextState();
 
         backend.bindImageTexture(0, 11, 0, true, 0, GL15.GL_READ_ONLY, GL30.GL_R32UI);
         backend.bindImageTexture(ContextState.MAX_IMAGE_UNITS, 99, 0, true, 0, GL15.GL_READ_ONLY, GL30.GL_R32UI);

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/SDLGPULWJGLServiceGatingTest.java

@@ -0,0 +1,17 @@
+package com.gtnewhorizons.angelica.sdlgpu;
+
+import com.mitchej123.lwjgl.LWJGLService;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+
+class SDLGPULWJGLServiceGatingTest {
+
+    @Test
+    void anUnengagedSdlDeclinesAndNeverArmsTheFallbackTripwire() {
+        assertFalse(SDLGPUGate.isEngaged(), "test JVM must not have an engaged SDL GPU device");
+        assertEquals(LWJGLService.PRIORITY_UNAVAILABLE, new SDLGPULWJGLService().getPriority());
+        assertFalse(SDLGPULWJGLService.isOfferedAsAvailable(), "declining must leave fallBackToGL() usable");
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/SdlTestRig.java

@@ -1,6 +1,8 @@
 package com.gtnewhorizons.angelica.sdlgpu;
 
+import com.gtnewhorizons.angelica.glsm.testutil.Reflect;
 import com.gtnewhorizons.angelica.sdlgpu.device.Device;
+import com.gtnewhorizons.angelica.sdlgpu.frame.ContextState;
 import com.gtnewhorizons.angelica.sdlgpu.frame.FrameManager;
 import com.gtnewhorizons.angelica.sdlgpu.resource.ResourceManager;
 import org.lwjgl.sdl.SDLError;
@@ -57,6 +59,10 @@ public final class SdlTestRig {
         return create().frameManager;
     }
 
+    public static ContextState contextState() {
+        return Reflect.invokeStatic(SDLGPURenderBackend.class, "s", new Class<?>[0]);
+    }
+
     private static long realSdlDevice;
 
     private static final int SHADER_FORMATS = SDL_GPU_SHADERFORMAT_SPIRV | SDL_GPU_SHADERFORMAT_MSL | SDL_GPU_SHADERFORMAT_DXBC | SDL_GPU_SHADERFORMAT_DXIL;

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/UniformNegativeLocationTest.java

@@ -48,13 +48,6 @@ class UniformNegativeLocationTest {
         st.releaseUniformStaging(prog);
     }
 
-    @SuppressWarnings("unchecked")
-    private static ContextState threadState() throws Exception {
-        final Field f = SDLGPURenderBackend.class.getDeclaredField("tlState");
-        f.setAccessible(true);
-        return ((ThreadLocal<ContextState>) f.get(null)).get();
-    }
-
     private static void clearApplier(SDLGPURenderBackend backend) throws Exception {
         final Field f = SDLGPURenderBackend.class.getDeclaredField("pipelineApplier");
         f.setAccessible(true);
@@ -66,7 +59,7 @@ class UniformNegativeLocationTest {
     void scalarAndVectorEntryPointsNeverReachTheApplier() throws Exception {
         final SDLGPURenderBackend backend = new SDLGPURenderBackend();
         clearApplier(backend);
-        threadState().boundProgramObj = null;
+        SdlTestRig.contextState().boundProgramObj = null;
 
         final IntBuffer iv = MemoryUtil.memAllocInt(4);
         try {

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/device/DeviceLifecycleGpuTest.java

@@ -0,0 +1,50 @@
+package com.gtnewhorizons.angelica.sdlgpu.device;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.lwjgl.sdl.SDLError;
+import org.lwjgl.sdl.SDLInit;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assumptions.assumeTrue;
+import static org.lwjgl.sdl.SDLInit.SDL_INIT_VIDEO;
+
+class DeviceLifecycleGpuTest {
+
+    private Device device;
+
+    @BeforeAll
+    static void initSdl() {
+        assumeTrue(SDLInit.SDL_Init(SDL_INIT_VIDEO), () -> "SDL_Init failed: " + SDLError.SDL_GetError());
+    }
+
+    @AfterEach
+    void tearDown() {
+        if (device != null) device.destroyDevice();
+    }
+
+    @Test
+    void createsWithoutAWindowAndIsMemoized() {
+        device = new Device();
+        assumeTrue(device.createDevice(), "no SDL GPU device on this machine");
+
+        final long handle = device.getDevice();
+        assertNotEquals(0L, handle);
+        assertTrue(device.createDevice(), "second createDevice should be a no-op");
+        assertEquals(handle, device.getDevice(), "createDevice must not replace a live device");
+    }
+
+    @Test
+    void destroyIsIdempotentOnAnUnclaimedDevice() {
+        device = new Device();
+        assumeTrue(device.createDevice(), "no SDL GPU device on this machine");
+
+        device.destroyDevice();
+        assertEquals(0L, device.getDevice());
+        device.destroyDevice();
+        assertEquals(0L, device.getDevice());
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/device/DriverSelectionTest.java

@@ -2,9 +2,13 @@ package com.gtnewhorizons.angelica.sdlgpu.device;
 
 import org.junit.jupiter.api.Test;
 
+import static com.gtnewhorizons.angelica.sdlgpu.device.Device.metalNeedsNewerSdl;
 import static com.gtnewhorizons.angelica.sdlgpu.device.Device.resolveDriverName;
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.lwjgl.sdl.SDLVersion.SDL_VERSIONNUM;
 
 class DriverSelectionTest {
 
@@ -24,4 +28,17 @@ class DriverSelectionTest {
         assertNull(resolveDriverName("", false));
         assertNull(resolveDriverName("direct3d12", false));
     }
+
+    @Test
+    void metalBelow346FallsBack() {
+        assertTrue(metalNeedsNewerSdl("metal", SDL_VERSIONNUM(3, 4, 5)));
+        assertFalse(metalNeedsNewerSdl("metal", SDL_VERSIONNUM(3, 4, 6)));
+        assertFalse(metalNeedsNewerSdl("metal", SDL_VERSIONNUM(3, 5, 0)));
+    }
+
+    @Test
+    void otherDriversIgnoreTheMetalFloor() {
+        assertFalse(metalNeedsNewerSdl("vulkan", SDL_VERSIONNUM(3, 4, 5)));
+        assertFalse(metalNeedsNewerSdl("direct3d12", SDL_VERSIONNUM(3, 0, 0)));
+    }
 }

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/device/VideoDriverRecoveryTest.java

@@ -0,0 +1,34 @@
+package com.gtnewhorizons.angelica.sdlgpu.device;
+
+import org.junit.jupiter.api.Test;
+
+import static com.gtnewhorizons.angelica.sdlgpu.device.VideoDriverRecovery.shouldRetryOnX11;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class VideoDriverRecoveryTest {
+
+    @Test
+    void waylandWithoutVulkanSurfaceRetries() {
+        assertTrue(shouldRetryOnX11("wayland", false, ":0"));
+    }
+
+    @Test
+    void waylandWithVulkanStays() {
+        assertFalse(shouldRetryOnX11("wayland", true, ":0"));
+    }
+
+    @Test
+    void noXWaylandMeansNoRetry() {
+        assertFalse(shouldRetryOnX11("wayland", false, null));
+        assertFalse(shouldRetryOnX11("wayland", false, ""));
+    }
+
+    @Test
+    void otherVideoDriversAreLeftAlone() {
+        assertFalse(shouldRetryOnX11("x11", false, ":0"));
+        assertFalse(shouldRetryOnX11("cocoa", false, ":0"));
+        assertFalse(shouldRetryOnX11("windows", false, ":0"));
+        assertFalse(shouldRetryOnX11(null, false, ":0"));
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/frame/ContextCounterAggregationTest.java

@@ -6,13 +6,13 @@ import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
-import java.util.List;
+import com.gtnewhorizons.angelica.sdlgpu.util.ThreadRegistry;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
 class ContextCounterAggregationTest {
 
-    private List<ContextState> registered;
+    private ThreadRegistry<ContextState> registered;
     private ContextState a;
     private ContextState b;
 

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/frame/PresenterTest.java

@@ -0,0 +1,98 @@
+package com.gtnewhorizons.angelica.sdlgpu.frame;
+
+import com.gtnewhorizons.angelica.sdlgpu.device.Device;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.Timeout;
+
+import java.util.ArrayDeque;
+import java.util.Deque;
+import java.util.concurrent.Executor;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+@Timeout(10)
+class PresenterTest {
+
+    private static final class DeferredExecutor implements Executor {
+        final Deque<Runnable> tasks = new ArrayDeque<>();
+
+        @Override
+        public void execute(Runnable command) {
+            tasks.add(command);
+        }
+
+        void runNext() {
+            tasks.removeFirst().run();
+        }
+    }
+
+    private static Presenter presenter(DeferredExecutor executor) {
+        return new Presenter(new FrameManager(new Device()), executor);
+    }
+
+    private static void awaitWaiting(Thread t) throws InterruptedException {
+        while (t.getState() != Thread.State.WAITING && t.getState() != Thread.State.TIMED_WAITING) {
+            assertTrue(t.isAlive(), "thread died instead of blocking");
+            Thread.onSpinWait();
+        }
+    }
+
+    @Test
+    void aSecondRequestBlocksUntilTheFirstPresentRuns() throws Exception {
+        final DeferredExecutor executor = new DeferredExecutor();
+        final Presenter p = presenter(executor);
+
+        p.requestPresent(1L, 10, 10);
+        assertEquals(1, executor.tasks.size());
+
+        final Thread second = new Thread(() -> p.requestPresent(2L, 10, 10));
+        second.start();
+        awaitWaiting(second);
+        assertEquals(1, executor.tasks.size(), "second present must not enqueue while the first is in flight");
+
+        executor.runNext();
+        second.join();
+        assertEquals(1, executor.tasks.size(), "second present enqueues only after the first released the slot");
+    }
+
+    @Test
+    void drainBlocksUntilThePendingPresentCompletes() throws Exception {
+        final DeferredExecutor executor = new DeferredExecutor();
+        final Presenter p = presenter(executor);
+
+        p.requestPresent(1L, 10, 10);
+
+        final Thread drainer = new Thread(p::drain);
+        drainer.start();
+        awaitWaiting(drainer);
+
+        executor.runNext();
+        drainer.join();
+    }
+
+    @Test
+    void anInlineExecutorReleasesTheSlotImmediately() {
+        final Presenter p = new Presenter(new FrameManager(new Device()), Runnable::run);
+        p.requestPresent(1L, 10, 10);
+        p.requestPresent(2L, 10, 10);
+        p.drain();
+    }
+
+    @Test
+    void presentingDoesNotEnterTheFrameRegistry() throws Exception {
+        final DeferredExecutor executor = new DeferredExecutor();
+        final FrameManager fm = new FrameManager(new Device());
+        final Presenter p = new Presenter(fm, executor);
+        fm.frame();
+        final int before = fm.registeredFrameCount();
+
+        p.requestPresent(1L, 10, 10);
+
+        final Thread windowThread = new Thread(executor::runNext, "window-thread");
+        windowThread.start();
+        windowThread.join();
+
+        assertEquals(before, fm.registeredFrameCount(), "the window thread must stay out of the frame registry");
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/frame/SwapchainClearPassBreakTest.java

@@ -0,0 +1,60 @@
+package com.gtnewhorizons.angelica.sdlgpu.frame;
+
+import org.junit.jupiter.api.Test;
+
+import static com.gtnewhorizons.angelica.sdlgpu.frame.FrameManager.swapchainClearNeedsPassBreak;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class SwapchainClearPassBreakTest {
+
+    private static FrameManager.FrameState activeFbo0Pass() {
+        final FrameManager.FrameState f = new FrameManager.FrameState();
+        f.renderPass = 0xBEEFL;
+        f.activeLayoutHash = FrameManager.FBO0_LAYOUT_HASH;
+        return f;
+    }
+
+    @Test
+    void aPendingColorClearBreaksTheActivePass() {
+        final ContextState st = new ContextState();
+        st.pendingSwapchainClear = true;
+        assertTrue(swapchainClearNeedsPassBreak(st, activeFbo0Pass()), "otherwise the clear is deferred to the next pass and wipes what this one drew");
+    }
+
+    @Test
+    void aPendingDepthOrStencilClearBreaksTheActivePass() {
+        final ContextState depth = new ContextState();
+        depth.pendingSwapchainDepthClear = true;
+        assertTrue(swapchainClearNeedsPassBreak(depth, activeFbo0Pass()));
+
+        final ContextState stencil = new ContextState();
+        stencil.pendingSwapchainStencilClear = true;
+        assertTrue(swapchainClearNeedsPassBreak(stencil, activeFbo0Pass()));
+    }
+
+    @Test
+    void nothingPendingLeavesThePassAlone() {
+        assertFalse(swapchainClearNeedsPassBreak(new ContextState(), activeFbo0Pass()));
+    }
+
+    @Test
+    void aClearWithNoActivePassNeedsNoBreak() {
+        final ContextState st = new ContextState();
+        st.pendingSwapchainClear = true;
+
+        final FrameManager.FrameState f = activeFbo0Pass();
+        f.renderPass = 0;
+        assertFalse(swapchainClearNeedsPassBreak(st, f));
+    }
+
+    @Test
+    void aPassBoundToAnFboIsNotTheFbo0Pass() {
+        final ContextState st = new ContextState();
+        st.pendingSwapchainClear = true;
+
+        final FrameManager.FrameState f = activeFbo0Pass();
+        f.activeLayoutHash = 0xF80L;
+        assertFalse(swapchainClearNeedsPassBreak(st, f));
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/pipeline/ClearConsumptionTest.java

@@ -0,0 +1,112 @@
+package com.gtnewhorizons.angelica.sdlgpu.pipeline;
+
+import com.gtnewhorizons.angelica.sdlgpu.SdlTestRig;
+import com.gtnewhorizons.angelica.sdlgpu.frame.ContextState;
+import com.gtnewhorizons.angelica.sdlgpu.resource.FBOClearTracker;
+import com.gtnewhorizons.angelica.sdlgpu.resource.FboState;
+import com.gtnewhorizons.angelica.sdlgpu.resource.ResourceManager;
+import org.junit.jupiter.api.Test;
+
+import static com.gtnewhorizons.angelica.sdlgpu.pipeline.PipelineApplier.consumeClears;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_D24_UNORM;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT;
+
+class ClearConsumptionTest {
+
+    private static final long COLOR = 0xC010L;
+    private static final long DEPTH = 0xD00DL;
+    private static final long DUMMY = 0xD04DL;
+
+    private static FboState fbo(int depthFormat) {
+        final FboState fbo = new FboState();
+        fbo.colorTextures[0] = COLOR;
+        fbo.colorGlIds[0] = 3;
+        if (depthFormat != 0) {
+            fbo.depthTexture = DEPTH;
+            fbo.depthGlId = 5;
+            fbo.depthFormat = depthFormat;
+        }
+        fbo.recomputeTargets();
+        return fbo;
+    }
+
+    private static ResourceManager rm() {
+        return SdlTestRig.resourceManager();
+    }
+
+    @Test
+    void aClearedColorTargetBecomesContentDefined() {
+        final ResourceManager rm = rm();
+        final ContextState st = new ContextState();
+        final FboState fbo = fbo(0);
+        FBOClearTracker.recordPendingColorClear(st, COLOR, 0f, 0f, 0f, 1f);
+
+        consumeClears(rm, st, fbo, DUMMY, 0b1, false, false, false);
+
+        assertFalse(st.pendingColorTextures.contains(COLOR), "the pass applied the clear, so it is no longer pending");
+        assertTrue(rm.isTextureContentDefined(COLOR), "a later frame must not clear it again");
+    }
+
+    @Test
+    void anUnclearedColorTargetIsNotMarkedDefined() {
+        final ResourceManager rm = rm();
+        final ContextState st = new ContextState();
+
+        consumeClears(rm, st, fbo(0), DUMMY, 0, false, false, false);
+
+        assertFalse(rm.isTextureContentDefined(COLOR));
+    }
+
+    @Test
+    void theDummyTargetIsNeverTracked() {
+        final ResourceManager rm = rm();
+        final ContextState st = new ContextState();
+        final FboState fbo = fbo(0);
+        fbo.colorTextures[0] = DUMMY;
+        fbo.recomputeTargets();
+
+        consumeClears(rm, st, fbo, DUMMY, 0b1, false, false, false);
+
+        assertFalse(rm.isTextureContentDefined(DUMMY), "the shared stand-in target has no per-FBO content");
+    }
+
+    @Test
+    void depthAndStencilAreConsumedIndependently() {
+        final ContextState st = new ContextState();
+        FBOClearTracker.recordPendingDepthClear(st, DEPTH, 1f);
+        FBOClearTracker.recordPendingStencilClear(st, DEPTH, 0);
+
+        consumeClears(rm(), st, fbo(SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT), DUMMY, 0, true, true, true);
+
+        assertFalse(st.pendingDepthTextures.contains(DEPTH));
+        assertFalse(st.pendingStencilTextures.contains(DEPTH));
+        assertTrue(st.clearedTexturesThisFrame.contains(DEPTH));
+        assertTrue(st.clearedStencilTexturesThisFrame.contains(DEPTH));
+    }
+
+    @Test
+    void aDepthOnlyTargetLeavesStencilStateAlone() {
+        final ContextState st = new ContextState();
+        FBOClearTracker.recordPendingDepthClear(st, DEPTH, 1f);
+        FBOClearTracker.recordPendingStencilClear(st, DEPTH, 0);
+
+        consumeClears(rm(), st, fbo(SDL_GPU_TEXTUREFORMAT_D24_UNORM), DUMMY, 0, true, false, false);
+
+        assertFalse(st.pendingDepthTextures.contains(DEPTH));
+        assertTrue(st.pendingStencilTextures.contains(DEPTH), "the format has no stencil aspect to clear");
+        assertFalse(st.clearedStencilTexturesThisFrame.contains(DEPTH));
+    }
+
+    @Test
+    void anUnclearedDepthTargetIsStillConsumed() {
+        final ContextState st = new ContextState();
+        FBOClearTracker.recordPendingDepthClear(st, DEPTH, 1f);
+
+        consumeClears(rm(), st, fbo(SDL_GPU_TEXTUREFORMAT_D24_UNORM), DUMMY, 0, false, false, false);
+
+        assertFalse(st.pendingDepthTextures.contains(DEPTH));
+        assertFalse(st.clearedTexturesThisFrame.contains(DEPTH), "no clear was baked, so nothing was cleared");
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/pipeline/ClearValueLayoutHashTest.java

@@ -0,0 +1,44 @@
+package com.gtnewhorizons.angelica.sdlgpu.pipeline;
+
+import org.junit.jupiter.api.Test;
+
+import static com.gtnewhorizons.angelica.sdlgpu.pipeline.PipelineApplier.foldClearColor;
+import static com.gtnewhorizons.angelica.sdlgpu.pipeline.PipelineApplier.foldClearDepth;
+import static com.gtnewhorizons.angelica.sdlgpu.pipeline.PipelineApplier.foldClearStencil;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+
+class ClearValueLayoutHashTest {
+
+    private static final long SEED = 0xA5A5A5A5A5A5A5A5L;
+
+    @Test
+    void depthZeroAndDepthOneDoNotCollide() {
+        assertNotEquals(foldClearDepth(SEED, 0.0f), foldClearDepth(SEED, 1.0f), "the minimap mask clear must not reuse the world's depth-1 clear target");
+    }
+
+    @Test
+    void depthFoldIsStableForTheSameValue() {
+        assertEquals(foldClearDepth(SEED, 0.0f), foldClearDepth(SEED, 0.0f));
+    }
+
+    @Test
+    void negativeZeroIsDistinguishedFromZero() {
+        assertNotEquals(foldClearDepth(SEED, 0.0f), foldClearDepth(SEED, -0.0f), "raw bits, not numeric equality, so the cached value always matches what was baked");
+    }
+
+    @Test
+    void everyColorChannelParticipates() {
+        final long base = foldClearColor(SEED, 0f, 0f, 0f, 1f);
+        assertNotEquals(base, foldClearColor(SEED, 1f, 0f, 0f, 1f), "red");
+        assertNotEquals(base, foldClearColor(SEED, 0f, 1f, 0f, 1f), "green");
+        assertNotEquals(base, foldClearColor(SEED, 0f, 0f, 1f, 1f), "blue");
+        assertNotEquals(base, foldClearColor(SEED, 0f, 0f, 0f, 0f), "alpha");
+    }
+
+    @Test
+    void stencilValuesDoNotCollide() {
+        assertNotEquals(foldClearStencil(SEED, 0), foldClearStencil(SEED, 1));
+        assertEquals(foldClearStencil(SEED, 0xFF), foldClearStencil(SEED, 0xFF));
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/pipeline/StencilMaskGpuTest.java

@@ -0,0 +1,232 @@
+package com.gtnewhorizons.angelica.sdlgpu.pipeline;
+
+import com.gtnewhorizons.angelica.glsm.ffp.VAOManager;
+import com.gtnewhorizons.angelica.sdlgpu.SdlTestRig;
+import com.gtnewhorizons.angelica.sdlgpu.frame.ContextState;
+import com.gtnewhorizons.angelica.sdlgpu.resource.PixelOps;
+import com.gtnewhorizons.angelica.sdlgpu.shader.ShaderManager;
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.lwjgl.opengl.GL11;
+import org.lwjgl.opengl.GL20;
+import org.lwjgl.opengl.GL30;
+import org.lwjgl.sdl.SDLError;
+import org.lwjgl.sdl.SDL_GPUColorTargetInfo;
+import org.lwjgl.sdl.SDL_GPUDepthStencilTargetInfo;
+import org.lwjgl.system.MemoryStack;
+import org.lwjgl.system.MemoryUtil;
+
+import java.nio.ByteBuffer;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.lwjgl.sdl.SDLGPU.*;
+
+class StencilMaskGpuTest {
+
+    private static SdlTestRig rig;
+    private static ShaderManager sm;
+
+    private static final int SIZE = 64;
+    private static final int MASK = 32;
+
+    private static PipelineStore store;
+    private static long colorTexture;
+    private static int colorFormat;
+    private static long depthTexture;
+    private static int depthFormat;
+    private static long maskPipeline;
+    private static long fillPipeline;
+
+    private static final String VERTEX = String.join("\n",
+        "#version 460 core",
+        "void main() {",
+        "    vec2 p = vec2((gl_VertexID << 1) & 2, gl_VertexID & 2);",
+        "    gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);",
+        "}",
+        "");
+
+    private static final String MASK_FRAGMENT = String.join("\n",
+        "#version 460 core",
+        "layout(location = 0) out vec4 fragColor;",
+        "void main() {",
+        "    if (gl_FragCoord.x >= " + MASK + ".0 || gl_FragCoord.y >= " + MASK + ".0) discard;",
+        "    fragColor = vec4(0.0, 0.0, 1.0, 1.0);",
+        "}",
+        "");
+
+    private static final String FILL_FRAGMENT = String.join("\n",
+        "#version 460 core",
+        "layout(location = 0) out vec4 fragColor;",
+        "void main() {",
+        "    fragColor = vec4(1.0, 0.0, 0.0, 1.0);",
+        "}",
+        "");
+
+    @BeforeAll
+    static void setUp() throws Exception {
+        rig = SdlTestRig.acquireRealDevice();
+        rig.resourceManager.cachePreferredDepthFormats();
+        sm = new ShaderManager(rig.device);
+        VAOManager.init(0);
+        store = new PipelineStore(rig.device);
+
+        colorTexture = rig.resourceManager.createTexture(9500, GL11.GL_TEXTURE_2D, GL11.GL_RGBA8, SIZE, SIZE, 1, 1);
+        assertTrue(colorTexture != 0, "color target creation failed");
+        colorFormat = rig.resourceManager.getTextureMeta(9500).sdlFormat();
+        PipelineCache.setSwapchainFormats(new int[]{ colorFormat });
+
+        rig.resourceManager.createTexture(9501, GL11.GL_TEXTURE_2D, GL30.GL_DEPTH24_STENCIL8, SIZE, SIZE, 1, 1);
+        depthTexture = rig.resourceManager.ensureTextureUsage(9501, SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET);
+        assertTrue(depthTexture != 0, "depth+stencil target creation failed");
+        depthFormat = rig.resourceManager.getTextureMeta(9501).sdlFormat();
+        assertEquals(8, PixelOps.stencilBits(depthFormat), "test needs a packed depth+stencil format");
+
+        maskPipeline = createPipeline(MASK_FRAGMENT, true);
+        fillPipeline = createPipeline(FILL_FRAGMENT, false);
+    }
+
+    @AfterAll
+    static void tearDown() {
+        SdlTestRig.releaseRealDevice();
+    }
+
+    private static long createPipeline(String fragmentSource, boolean writesMask) {
+        final int vs = sm.createShader(GL20.GL_VERTEX_SHADER);
+        sm.shaderSource(vs, VERTEX);
+        sm.compileShader(vs);
+        final int fs = sm.createShader(GL20.GL_FRAGMENT_SHADER);
+        sm.shaderSource(fs, fragmentSource);
+        sm.compileShader(fs);
+        final int prog = sm.createProgram();
+        sm.attachShader(prog, vs);
+        sm.attachShader(prog, fs);
+        sm.linkProgram(prog);
+        final ShaderManager.ProgramObject po = sm.getProgram(prog);
+        assertTrue(po != null && po.linked, "link failed: " + (po == null ? "no program" : po.infoLog));
+
+        po.sdlVertexShader = sm.createSDLShader(po.vertexSpirv, SDL_GPU_SHADERSTAGE_VERTEX, po.vertexResources.numSamplers(), po.vertexResources.numUBOs(), po.vertexResources.numStorageBuffers(), po.vertexResources.numStorageTextures());
+        po.sdlFragmentShader = sm.createSDLShader(po.fragmentSpirv, SDL_GPU_SHADERSTAGE_FRAGMENT, po.fragmentResources.numSamplers(), po.fragmentResources.numUBOs(), po.fragmentResources.numStorageBuffers(), po.fragmentResources.numStorageTextures());
+        assertTrue(po.sdlVertexShader != 0 && po.sdlFragmentShader != 0, "SDL shader creation failed");
+
+        final ContextState cs = new ContextState();
+        final PipelineCache cache = cs.pipeline;
+        cache.vertexShader = po.sdlVertexShader;
+        cache.fragmentShader = po.sdlFragmentShader;
+        cache.programId = prog;
+        cache.maxFragOutputLocation = po.maxFragOutputLocation;
+        cache.shaderInputMask = po.vertexInputMask;
+        cache.shaderInputVecSize = po.vertexInputVecSize;
+        cache.shaderInputBaseType = po.vertexInputBaseType;
+        cache.shaderInputName = po.vertexInputName;
+        cache.setColorTargetFormats(new int[]{ colorFormat });
+        cache.setDrawBuffers(new int[]{ 0 });
+        cache.hasDepthTarget = true;
+        cache.depthTargetFormat = depthFormat;
+        cache.depthTestEnabled = false;
+        cache.depthWriteEnabled = false;
+        cache.stencilTestEnabled = true;
+        cache.stencilCompareMask = 0xFF;
+        cache.stencilWriteMask = writesMask ? 0xFF : 0x00;
+        final int compareOp = writesMask ? SDL_GPU_COMPAREOP_ALWAYS : SDL_GPU_COMPAREOP_EQUAL;
+        final int passOp = writesMask ? SDL_GPU_STENCILOP_REPLACE : SDL_GPU_STENCILOP_KEEP;
+        cache.stencilFrontCompareOp = compareOp;
+        cache.stencilBackCompareOp = compareOp;
+        cache.stencilFrontPassOp = passOp;
+        cache.stencilBackPassOp = passOp;
+        cache.markShaderDirty();
+        cache.markOutputDirty();
+
+        assertTrue(cache.effectiveStencilTestEnabled(), "stencil must survive the depth-format gate");
+        final long pipeline = cache.getOrCreatePipeline(store, cs);
+        assertTrue(pipeline != 0, "pipeline creation failed: " + SDLError.SDL_GetError());
+        return pipeline;
+    }
+
+    private static void render(int secondPassStencilLoad) {
+        try (MemoryStack stack = MemoryStack.stackPush()) {
+            final long cb = SDL_AcquireGPUCommandBuffer(rig.device.getDevice());
+            assertTrue(cb != 0, "no command buffer");
+
+            final SDL_GPUColorTargetInfo.Buffer color = SDL_GPUColorTargetInfo.calloc(1, stack);
+            color.get(0).texture(colorTexture).load_op(SDL_GPU_LOADOP_CLEAR).store_op(SDL_GPU_STOREOP_STORE);
+            final SDL_GPUDepthStencilTargetInfo ds = SDL_GPUDepthStencilTargetInfo.calloc(stack)
+                .texture(depthTexture)
+                .load_op(SDL_GPU_LOADOP_CLEAR).store_op(SDL_GPU_STOREOP_STORE).clear_depth(1.0f)
+                .stencil_load_op(SDL_GPU_LOADOP_CLEAR).stencil_store_op(SDL_GPU_STOREOP_STORE).clear_stencil((byte) 0);
+
+            long pass = SDL_BeginGPURenderPass(cb, color, ds);
+            assertTrue(pass != 0, "no render pass");
+            SDL_SetGPUStencilReference(pass, (byte) 1);
+            SDL_BindGPUGraphicsPipeline(pass, maskPipeline);
+            SDL_DrawGPUPrimitives(pass, 3, 1, 0, 0);
+            if (secondPassStencilLoad < 0) {
+                SDL_BindGPUGraphicsPipeline(pass, fillPipeline);
+                SDL_DrawGPUPrimitives(pass, 3, 1, 0, 0);
+            }
+            SDL_EndGPURenderPass(pass);
+
+            if (secondPassStencilLoad >= 0) {
+                color.get(0).load_op(SDL_GPU_LOADOP_LOAD);
+                ds.load_op(SDL_GPU_LOADOP_LOAD).stencil_load_op(secondPassStencilLoad).clear_stencil((byte) 0);
+                pass = SDL_BeginGPURenderPass(cb, color, ds);
+                assertTrue(pass != 0, "no second render pass");
+                SDL_SetGPUStencilReference(pass, (byte) 1);
+                SDL_BindGPUGraphicsPipeline(pass, fillPipeline);
+                SDL_DrawGPUPrimitives(pass, 3, 1, 0, 0);
+                SDL_EndGPURenderPass(pass);
+            }
+
+            assertTrue(SDL_SubmitGPUCommandBuffer(cb), "draw submit failed");
+            SDL_WaitForGPUIdle(rig.device.getDevice());
+        }
+    }
+
+    private static int[] readRedPixels() {
+        final ByteBuffer pixels = MemoryUtil.memAlloc(SIZE * SIZE * 4);
+        try {
+            final long cb = SDL_AcquireGPUCommandBuffer(rig.device.getDevice());
+            assertTrue(cb != 0, "no readback command buffer");
+            rig.resourceManager.downloadFromTexture(cb, colorTexture, 0, 0, SIZE, SIZE, 0, pixels);
+            int count = 0, maxX = -1, minX = SIZE;
+            for (int y = 0; y < SIZE; y++) {
+                for (int x = 0; x < SIZE; x++) {
+                    final int i = (y * SIZE + x) * 4;
+                    final boolean red = (pixels.get(i) & 0xFF) > 200 && (pixels.get(i + 1) & 0xFF) < 64;
+                    if (red) {
+                        count++;
+                        if (x > maxX) maxX = x;
+                        if (x < minX) minX = x;
+                    }
+                }
+            }
+            return new int[]{ count, minX, maxX };
+        } finally {
+            MemoryUtil.memFree(pixels);
+        }
+    }
+
+    @Test
+    void fillIsClippedToTheStencilMask() {
+        render(-1);
+        final int[] r = readRedPixels();
+        assertEquals(MASK * MASK, r[0], "fill must cover exactly the masked region, not the whole target");
+        assertEquals(0, r[1], "masked region starts at x=0");
+        assertEquals(MASK - 1, r[2], "masked region must not bleed past the mask");
+    }
+
+    @Test
+    void maskSurvivesAPassBoundaryWhenStencilIsLoaded() {
+        render(SDL_GPU_LOADOP_LOAD);
+        final int[] r = readRedPixels();
+        assertEquals(MASK * MASK, r[0], "a stored stencil buffer must still clip the next pass");
+        assertEquals(MASK - 1, r[2]);
+    }
+
+    @Test
+    void clearingStencilWipesTheMask() {
+        render(SDL_GPU_LOADOP_CLEAR);
+        assertEquals(0, readRedPixels()[0], "a cleared stencil buffer must clip everything");
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/resource/ColorContentLifetimeTest.java

@@ -0,0 +1,42 @@
+package com.gtnewhorizons.angelica.sdlgpu.resource;
+
+import com.gtnewhorizons.angelica.sdlgpu.SdlTestRig;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class ColorContentLifetimeTest {
+
+    private static final long TEX = 0xC010125L;
+
+    @Test
+    void freshTextureHasUndefinedContents() {
+        final ResourceManager rm = SdlTestRig.resourceManager();
+        assertFalse(rm.isTextureContentDefined(TEX), "never written, so the first pass must clear");
+    }
+
+    @Test
+    void definedContentsSurviveAcrossFrames() {
+        final ResourceManager rm = SdlTestRig.resourceManager();
+        rm.markTextureContentDefined(TEX);
+        assertTrue(rm.isTextureContentDefined(TEX));
+
+        assertTrue(rm.isTextureContentDefined(TEX), "contents outlive the frame that produced them");
+    }
+
+    @Test
+    void releaseResetsContentsBecauseSdlCanRecycleThePointer() {
+        final ResourceManager rm = SdlTestRig.resourceManager();
+        rm.markTextureContentDefined(TEX);
+        rm.markTextureContentUndefined(TEX);
+        assertFalse(rm.isTextureContentDefined(TEX), "a recycled handle must not inherit the previous texture's defined flag");
+    }
+
+    @Test
+    void theZeroHandleIsNeverDefined() {
+        final ResourceManager rm = SdlTestRig.resourceManager();
+        rm.markTextureContentDefined(0L);
+        assertFalse(rm.isTextureContentDefined(0L));
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/resource/DepthStencilBitsTest.java

@@ -0,0 +1,64 @@
+package com.gtnewhorizons.angelica.sdlgpu.resource;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.lwjgl.sdl.SDLGPU.*;
+
+class DepthStencilBitsTest {
+
+    @Test
+    void depthBitsPerFormat() {
+        assertEquals(16, PixelOps.depthBits(SDL_GPU_TEXTUREFORMAT_D16_UNORM));
+        assertEquals(24, PixelOps.depthBits(SDL_GPU_TEXTUREFORMAT_D24_UNORM));
+        assertEquals(24, PixelOps.depthBits(SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT));
+        assertEquals(32, PixelOps.depthBits(SDL_GPU_TEXTUREFORMAT_D32_FLOAT));
+        assertEquals(32, PixelOps.depthBits(SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT));
+        assertEquals(0, PixelOps.depthBits(SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM));
+    }
+
+    @Test
+    void onlyPackedFormatsCarryStencil() {
+        assertEquals(8, PixelOps.stencilBits(SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT));
+        assertEquals(8, PixelOps.stencilBits(SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT));
+        assertEquals(0, PixelOps.stencilBits(SDL_GPU_TEXTUREFORMAT_D24_UNORM));
+        assertEquals(0, PixelOps.stencilBits(SDL_GPU_TEXTUREFORMAT_D32_FLOAT));
+        assertEquals(0, PixelOps.stencilBits(SDL_GPU_TEXTUREFORMAT_D16_UNORM));
+        assertEquals(0, PixelOps.stencilBits(SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM));
+    }
+
+    @Test
+    void stencilBitsAgreesWithIsDepthStencilFormat() {
+        final int[] formats = {
+            SDL_GPU_TEXTUREFORMAT_D16_UNORM, SDL_GPU_TEXTUREFORMAT_D24_UNORM, SDL_GPU_TEXTUREFORMAT_D32_FLOAT,
+            SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT, SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT,
+            SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM,
+        };
+        for (int f : formats) {
+            assertEquals(PixelOps.isDepthStencilFormat(f), PixelOps.stencilBits(f) != 0, "format " + f);
+        }
+    }
+
+    @Test
+    void colorChannelBitsForCommonFormats() {
+        for (int fmt : new int[]{ SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM, SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM }) {
+            for (int c = 0; c < 4; c++) assertEquals(8, PixelOps.colorChannelBits(fmt, c), "channel " + c);
+        }
+        assertEquals(16, PixelOps.colorChannelBits(SDL_GPU_TEXTUREFORMAT_R16G16B16A16_FLOAT, 3));
+        assertEquals(8, PixelOps.colorChannelBits(SDL_GPU_TEXTUREFORMAT_R8_UNORM, 0));
+        assertEquals(0, PixelOps.colorChannelBits(SDL_GPU_TEXTUREFORMAT_R8_UNORM, 1));
+        assertEquals(8, PixelOps.colorChannelBits(SDL_GPU_TEXTUREFORMAT_R8G8_UNORM, 1));
+        assertEquals(0, PixelOps.colorChannelBits(SDL_GPU_TEXTUREFORMAT_R8G8_UNORM, 2));
+        assertEquals(10, PixelOps.colorChannelBits(SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM, 0));
+        assertEquals(2, PixelOps.colorChannelBits(SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM, 3));
+        assertEquals(0, PixelOps.colorChannelBits(SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT, 0));
+    }
+
+    @Test
+    void depthFormatsAreNotColorFormats() {
+        assertTrue(PixelOps.isDepthFormat(SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT));
+        assertFalse(PixelOps.isDepthFormat(SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM));
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/resource/FullCoverageClearDiscardTest.java

@@ -35,6 +35,18 @@ class FullCoverageClearDiscardTest {
         assertTrue(st.clearedTexturesThisFrame.contains(HANDLE), "the overwrite counts as the clear");
     }
 
+    @Test
+    void fullTargetColorBlitDefinesTheContents() {
+        final ContextState st = new ContextState();
+        FBOClearTracker.recordPendingColorClear(st, HANDLE, 1f, 0f, 0f, 1f);
+
+        final SdlTestRig rig = SdlTestRig.create();
+        final FBOClearTracker tracker = new FBOClearTracker(rig.frameManager, rig.resourceManager, null);
+        assertTrue(tracker.discardPendingClearIfFullyCovered(st, HANDLE, 0, 0, 0, W, H, meta()));
+
+        assertTrue(rig.resourceManager.isTextureContentDefined(HANDLE), "the overwrite defines the contents, so a later frame must not clear it back");
+    }
+
     @Test
     void fullTargetDepthBlitDropsThePendingClear() {
         final ContextState st = new ContextState();

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/resource/PixelFormatBitsTest.java

@@ -0,0 +1,68 @@
+package com.gtnewhorizons.angelica.sdlgpu.resource;
+
+import org.junit.jupiter.api.Test;
+
+import static com.gtnewhorizons.angelica.sdlgpu.resource.PixelOps.colorChannelBits;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_A8_UNORM;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_B4G4R4A4_UNORM;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_B5G5R5A1_UNORM;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_B5G6R5_UNORM;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_R11G11B10_UFLOAT;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_R16G16_FLOAT;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_R32G32B32A32_FLOAT;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_R8_UNORM;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM;
+
+class PixelFormatBitsTest {
+
+    private static int[] rgba(int sdlFormat) {
+        return new int[]{
+            colorChannelBits(sdlFormat, 0),
+            colorChannelBits(sdlFormat, 1),
+            colorChannelBits(sdlFormat, 2),
+            colorChannelBits(sdlFormat, 3),
+        };
+    }
+
+    private static void assertRgba(int sdlFormat, int r, int g, int b, int a) {
+        assertEquals(r, colorChannelBits(sdlFormat, 0), "red");
+        assertEquals(g, colorChannelBits(sdlFormat, 1), "green");
+        assertEquals(b, colorChannelBits(sdlFormat, 2), "blue");
+        assertEquals(a, colorChannelBits(sdlFormat, 3), "alpha");
+    }
+
+    @Test
+    void uniformWidthFormats() {
+        assertRgba(SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM, 8, 8, 8, 8);
+        assertRgba(SDL_GPU_TEXTUREFORMAT_R8_UNORM, 8, 0, 0, 0);
+        assertRgba(SDL_GPU_TEXTUREFORMAT_R16G16_FLOAT, 16, 16, 0, 0);
+        assertRgba(SDL_GPU_TEXTUREFORMAT_R32G32B32A32_FLOAT, 32, 32, 32, 32);
+    }
+
+    @Test
+    void packedFormatsReportTheirRealChannelWidths() {
+        assertRgba(SDL_GPU_TEXTUREFORMAT_A8_UNORM, 0, 0, 0, 8);
+        assertRgba(SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM, 10, 10, 10, 2);
+        assertRgba(SDL_GPU_TEXTUREFORMAT_R11G11B10_UFLOAT, 11, 11, 10, 0);
+        assertRgba(SDL_GPU_TEXTUREFORMAT_B5G6R5_UNORM, 5, 6, 5, 0);
+        assertRgba(SDL_GPU_TEXTUREFORMAT_B5G5R5A1_UNORM, 5, 5, 5, 1);
+        assertRgba(SDL_GPU_TEXTUREFORMAT_B4G4R4A4_UNORM, 4, 4, 4, 4);
+    }
+
+    @Test
+    void depthAndCompressedFormatsHaveNoColorChannels() {
+        assertRgba(SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT, 0, 0, 0, 0);
+        assertRgba(SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM, 0, 0, 0, 0);
+    }
+
+    @Test
+    void outOfRangeChannelsAreZero() {
+        assertEquals(0, colorChannelBits(SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM, -1));
+        assertEquals(0, colorChannelBits(SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM, 4));
+        assertEquals(4, rgba(SDL_GPU_TEXTUREFORMAT_B4G4R4A4_UNORM).length);
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/resource/ReadbackSubmitOrderGpuTest.java

@@ -0,0 +1,58 @@
+package com.gtnewhorizons.angelica.sdlgpu.resource;
+
+import com.gtnewhorizons.angelica.sdlgpu.SdlTestRig;
+import com.gtnewhorizons.angelica.sdlgpu.frame.FrameManager;
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.Timeout;
+import org.lwjgl.opengl.GL11;
+
+import java.nio.ByteBuffer;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREUSAGE_COLOR_TARGET;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREUSAGE_SAMPLER;
+import static org.lwjgl.system.MemoryUtil.memAlloc;
+import static org.lwjgl.system.MemoryUtil.memFree;
+
+@Timeout(60)
+class ReadbackSubmitOrderGpuTest {
+
+    private static final int SIZE = 4;
+
+    @AfterAll
+    static void releaseDevice() {
+        SdlTestRig.releaseRealDevice();
+    }
+
+    @Test
+    void aReadbackSubmitsTheFramesWritesFirst() throws Exception {
+        final SdlTestRig rig = SdlTestRig.acquireRealDevice();
+        final ResourceManager rm = rig.resourceManager;
+        final FrameManager fm = rig.frameManager;
+        final TextureOps textureOps = new TextureOps(rig.device, fm, rm, null);
+
+        final int glId = rm.genTexture();
+        final long texture = rm.createTexture(glId, GL11.GL_TEXTURE_2D, GL11.GL_RGBA8, SIZE, SIZE, 1, 1, SDL_GPU_TEXTUREUSAGE_SAMPLER | SDL_GPU_TEXTUREUSAGE_COLOR_TARGET);
+        assertNotEquals(0L, texture, "texture creation failed");
+
+        fm.beginFrame();
+        final FrameManager.FrameState f = fm.frame();
+        final long frameCb = f.commandBuffer;
+        assertNotEquals(0L, frameCb, "no frame command buffer to order against");
+        assertEquals(0, f.midFrameSubmitsThisFrame);
+
+        final ByteBuffer out = memAlloc(SIZE * SIZE * 4);
+        try {
+            textureOps.readbackTexture(texture, 0, 0, SIZE, SIZE, 0, out);
+        } finally {
+            memFree(out);
+        }
+
+        assertEquals(1, f.midFrameSubmitsThisFrame, "the frame command buffer must be submitted before the download buffer, or the readback sees stale contents");
+        assertNotEquals(frameCb, f.commandBuffer, "the frame must continue on a freshly acquired command buffer");
+
+        fm.endFrame();
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/resource/StencilClearTrackingTest.java

@@ -0,0 +1,122 @@
+package com.gtnewhorizons.angelica.sdlgpu.resource;
+
+import com.gtnewhorizons.angelica.sdlgpu.SdlTestRig;
+import com.gtnewhorizons.angelica.sdlgpu.frame.ContextState;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.lwjgl.sdl.SDLGPU.SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT;
+
+class StencilClearTrackingTest {
+
+    private static final long DEPTH = 0xD00DL;
+
+    private static FBOClearTracker tracker() {
+        final SdlTestRig rig = SdlTestRig.create();
+        return new FBOClearTracker(rig.frameManager, rig.resourceManager, null);
+    }
+
+    private static FboState packedDepthStencilFbo() {
+        final FboState fbo = new FboState();
+        fbo.depthTexture = DEPTH;
+        fbo.depthGlId = 5;
+        fbo.depthFormat = SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT;
+        fbo.recomputeTargets();
+        return fbo;
+    }
+
+    @Test
+    void pendingStencilClearIsTrackedSeparatelyFromDepth() {
+        final ContextState st = new ContextState();
+        FBOClearTracker.recordPendingStencilClear(st, DEPTH, 0);
+
+        assertTrue(st.pendingStencilTextures.contains(DEPTH));
+        assertFalse(st.pendingDepthTextures.contains(DEPTH), "a stencil clear must not imply a depth clear");
+    }
+
+    @Test
+    void stencilClearSurvivesADepthClearOnTheSameHandle() {
+        final ContextState st = new ContextState();
+        FBOClearTracker.recordPendingStencilClear(st, DEPTH, 3);
+        FBOClearTracker.recordPendingDepthClear(st, DEPTH, 1f);
+
+        assertTrue(st.pendingStencilTextures.contains(DEPTH), "depth and stencil share a texture but not a clear");
+        assertEquals(3, st.pendingStencilValues.get(DEPTH));
+    }
+
+    @Test
+    void aPendingStencilClearAloneBlocksTargetReuse() {
+        final ContextState st = new ContextState();
+        final FboState fbo = packedDepthStencilFbo();
+        assertFalse(FBOClearTracker.fboHasPendingClear(st, fbo));
+
+        FBOClearTracker.recordPendingStencilClear(st, DEPTH, 0);
+        assertTrue(FBOClearTracker.fboHasPendingClear(st, fbo), "the pass must be rebuilt to apply the stencil clear");
+    }
+
+    @Test
+    void recordingAStencilClearRetractsTheClearedThisFrameMark() {
+        final ContextState st = new ContextState();
+        st.clearedStencilTexturesThisFrame.add(DEPTH);
+
+        FBOClearTracker.recordPendingStencilClear(st, DEPTH, 0);
+        assertFalse(st.clearedStencilTexturesThisFrame.contains(DEPTH), "a second clear in one frame must not be swallowed");
+    }
+
+    @Test
+    void recordingBumpsMutationGen() {
+        final ContextState st = new ContextState();
+        FBOClearTracker.snapshotFlushGenerations(st);
+        final int before = st.pendingMutationGen;
+
+        FBOClearTracker.recordPendingStencilClear(st, DEPTH, 0);
+        assertEquals(before + 1, st.pendingMutationGen);
+    }
+
+    @Test
+    void scrubDropsStencilStateWithTheTexture() {
+        final ContextState st = new ContextState();
+        FBOClearTracker.recordPendingStencilClear(st, DEPTH, 7);
+        st.clearedStencilTexturesThisFrame.add(DEPTH);
+
+        final SdlTestRig rig = SdlTestRig.create();
+        final int glId = rig.resourceManager.genTexture();
+        SdlReflect.putTextureHandle(rig.resourceManager, glId, DEPTH);
+        new FBOClearTracker(rig.frameManager, rig.resourceManager, null).scrubPendingClearsForTexture(st, glId);
+
+        assertFalse(st.pendingStencilTextures.contains(DEPTH));
+        assertFalse(st.pendingStencilValues.containsKey(DEPTH));
+        assertFalse(st.clearedStencilTexturesThisFrame.contains(DEPTH));
+    }
+
+    @Test
+    void stencilClearValueIsMaskedToEightBits() {
+        final ContextState st = new ContextState();
+        FBOClearTracker.recordPendingStencilClear(st, DEPTH, 0xFF);
+        assertEquals(0xFF, st.pendingStencilValues.get(DEPTH));
+        assertEquals((byte) 0xFF, (byte) st.pendingStencilValues.get(DEPTH));
+    }
+
+    @Test
+    void aStencilOnlyClearStillReachesTheSamplerFlush() {
+        final ContextState st = new ContextState();
+        FBOClearTracker.recordPendingStencilClear(st, DEPTH, 0);
+        final int gen = st.pendingMutationGen;
+
+        tracker().flushPendingClearsForBoundSamplers(st);
+
+        assertEquals(gen, st.lastFlushedPendingMutationGen, "the early-out must not skip a texture whose only pending clear is stencil");
+    }
+
+    @Test
+    void trackerIsUnusedForFbosWithoutADepthAttachment() {
+        final ContextState st = new ContextState();
+        FBOClearTracker.recordPendingStencilClear(st, DEPTH, 0);
+        final FboState colorOnly = new FboState();
+        colorOnly.colorTextures[0] = 0xAAAAL;
+        colorOnly.recomputeTargets();
+        assertFalse(FBOClearTracker.fboHasPendingClear(st, colorOnly));
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/resource/TextureReleaseUploadOrderTest.java

@@ -0,0 +1,112 @@
+package com.gtnewhorizons.angelica.sdlgpu.resource;
+
+import com.gtnewhorizons.angelica.glsm.testutil.Reflect;
+import com.gtnewhorizons.angelica.sdlgpu.SdlTestRig;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class TextureReleaseUploadOrderTest {
+
+    private static final long HANDLE = 0xBEEFL;
+
+    private static List<Long> deferredReleases(ResourceManager rm) {
+        return Reflect.get(rm, "deferredTextureReleases");
+    }
+
+    private static void setUploadSeqs(ResourceManager rm, long lastUpload) {
+        Reflect.setDeclared(ResourceManager.class, rm, "lastTextureUploadSeq", lastUpload);
+    }
+
+    @Test
+    void releaseIsImmediateWhenNoTransferThreadIsAttached() {
+        final ResourceManager rm = SdlTestRig.resourceManager();
+        setUploadSeqs(rm, 50L);
+        assertFalse(rm.shouldDeferTextureRelease(), "with no transfer thread there is nothing to outlive");
+    }
+
+    @Test
+    void releaseIsDeferredWhileTextureUploadsAreStillQueued() {
+        final SdlTestRig rig = SdlTestRig.create();
+        final ResourceManager rm = rig.resourceManager;
+        final TransferThread tt = new TransferThread(rig.device, rm);
+        rm.setTransferThread(tt);
+        setUploadSeqs(rm, 50L);
+        Reflect.setDeclared(TransferThread.class, tt, "submittedSeq", 10L);
+
+        rm.trackTextureHandle(HANDLE);
+        final int glId = rm.genTexture();
+        SdlReflect.putTextureHandle(rm, glId, HANDLE);
+
+        rm.deleteTexture(glId);
+        assertEquals(List.of(HANDLE), deferredReleases(rm), "the free must wait for the queued upload");
+    }
+
+    @Test
+    void releaseIsImmediateOnceTheTransferThreadHasCaughtUp() {
+        final SdlTestRig rig = SdlTestRig.create();
+        final ResourceManager rm = rig.resourceManager;
+        final TransferThread tt = new TransferThread(rig.device, rm);
+        rm.setTransferThread(tt);
+        setUploadSeqs(rm, 50L);
+
+        Reflect.setDeclared(TransferThread.class, tt, "submittedSeq", 49L);
+        assertTrue(rm.shouldDeferTextureRelease(), "one upload still unsubmitted is enough to defer");
+
+        Reflect.setDeclared(TransferThread.class, tt, "submittedSeq", 50L);
+        assertFalse(rm.shouldDeferTextureRelease(), "nothing is in flight, so no need to defer");
+    }
+
+    @Test
+    void aQueuedInlineBatchAlsoDefersTheRelease() {
+        final SdlTestRig rig = SdlTestRig.create();
+        final ResourceManager rm = rig.resourceManager;
+        rig.frameManager.setResourceManager(rm);
+        assertFalse(rm.shouldDeferTextureRelease(), "nothing queued yet");
+
+        rig.frameManager.frame().pendingTexHandles.add(HANDLE);
+        assertTrue(rm.hasBatchedUploads());
+        assertTrue(rm.shouldDeferTextureRelease(), "a queued batch entry must outlive the release");
+
+        rig.frameManager.frame().pendingTexHandles.clear();
+        assertFalse(rm.shouldDeferTextureRelease());
+    }
+
+    @Test
+    void releasingATextureBlanksItsQueuedBatchEntries() {
+        final SdlTestRig rig = SdlTestRig.create();
+        final ResourceManager rm = rig.resourceManager;
+        rig.frameManager.setResourceManager(rm);
+        final var handles = rig.frameManager.frame().pendingTexHandles;
+        handles.add(HANDLE);
+        handles.add(0xFEEDL);
+        handles.add(HANDLE);
+
+        rm.dropBatchedUploadsTargeting(HANDLE);
+
+        assertEquals(0L, handles.getLong(0), "every entry for the dying texture is blanked");
+        assertEquals(0xFEEDL, handles.getLong(1), "other destinations are untouched");
+        assertEquals(0L, handles.getLong(2));
+    }
+
+    @Test
+    void reallocReleaseObeysTheSameRule() {
+        final SdlTestRig rig = SdlTestRig.create();
+        final ResourceManager rm = rig.resourceManager;
+        final TransferThread tt = new TransferThread(rig.device, rm);
+        rm.setTransferThread(tt);
+        setUploadSeqs(rm, 7L);
+        Reflect.setDeclared(TransferThread.class, tt, "submittedSeq", 0L);
+
+        rm.trackTextureHandle(HANDLE);
+        final int glId = rm.genTexture();
+        SdlReflect.putTextureHandle(rm, glId, HANDLE);
+
+        rm.releaseTextureHandleForRealloc(glId);
+        assertEquals(List.of(HANDLE), deferredReleases(rm), "glTexImage2D re-specification frees the old handle on the same path as a delete");
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/resource/TransferRetireSeqTest.java

@@ -0,0 +1,61 @@
+package com.gtnewhorizons.angelica.sdlgpu.resource;
+
+import com.gtnewhorizons.angelica.glsm.testutil.Reflect;
+import com.gtnewhorizons.angelica.sdlgpu.SdlTestRig;
+import org.junit.jupiter.api.Test;
+
+import static com.gtnewhorizons.angelica.sdlgpu.resource.TransferThread.shouldPublishRetired;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class TransferRetireSeqTest {
+
+    private static TransferThread idleThread() {
+        final SdlTestRig rig = SdlTestRig.create();
+        final TransferThread tt = new TransferThread(rig.device, rig.resourceManager);
+        tt.shutdown();
+        try {
+            tt.getThread().join(5_000L);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new AssertionError("interrupted while stopping the transfer thread", e);
+        }
+        assertFalse(tt.getThread().isAlive(), "the worker must be stopped first: its loop zeroes openHighestSeq after publishing, so a live worker races this test");
+        return tt;
+    }
+
+    @Test
+    void anOpenCommandBufferIsNeverPublishedEarly() {assertFalse(shouldPublishRetired(true, 50L, 10L),
+            "those copies are recorded but not submitted; a waiter must not be released");
+    }
+
+    @Test
+    void retiredSeqsArePublishedWhenNothingIsOpen() {
+        assertTrue(shouldPublishRetired(false, 50L, 10L));
+    }
+
+    @Test
+    void anAlreadyPublishedSeqIsNotRepublished() {
+        assertFalse(shouldPublishRetired(false, 10L, 10L));
+        assertFalse(shouldPublishRetired(false, 0L, 10L));
+    }
+
+    @Test
+    void aDroppedTextureUploadStillRetiresItsSeq() {
+        final TransferThread tt = idleThread();
+        Reflect.invoke(tt, "recordTextureUpload",
+            new Class<?>[]{ long.class, long.class, int.class, int.class, int.class, int.class, int.class, long.class, long.class },
+            0L, 0xBEEFL, 0, 0, 16, 16, 0, 1024L, 42L);
+
+        assertEquals(42L, (long) Reflect.get(tt, "openHighestSeq"), "a dropped upload must still advance the watermark or awaitSubmittedUpTo blocks forever");
+    }
+
+    @Test
+    void aDroppedBufferUploadStillRetiresItsSeq() {
+        final TransferThread tt = idleThread();
+        Reflect.invoke(tt, "recordBufferUpload", new Class<?>[]{ long.class, long.class, long.class, long.class, long.class, boolean.class }, 0L, 256L, 0xF00L, 0L, 7L, false);
+
+        assertEquals(7L, (long) Reflect.get(tt, "openHighestSeq"));
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/resource/UploadArenaTest.java

@@ -64,6 +64,26 @@ class UploadArenaTest {
         assertEquals(UploadArena.INITIAL_CAPACITY * 4, a.capacity());
     }
 
+    @Test
+    void requestGrowClampsAtMaxCapacityInsteadOfSpinning() {
+        final UploadArena a = new UploadArena();
+        a.requestGrow(Integer.MAX_VALUE);
+        assertTrue(a.applyGrow());
+        assertEquals(UploadArena.MAX_CAPACITY, a.capacity());
+        a.requestGrow(Integer.MAX_VALUE);
+        assertFalse(a.applyGrow());
+        assertEquals(UploadArena.MAX_CAPACITY, a.capacity());
+    }
+
+    @Test
+    void requestGrowIsIdempotentBelowCurrentTarget() {
+        final UploadArena a = new UploadArena();
+        a.requestGrow(UploadArena.INITIAL_CAPACITY * 4);
+        a.requestGrow(1);
+        assertTrue(a.applyGrow());
+        assertEquals(UploadArena.INITIAL_CAPACITY * 4, a.capacity());
+    }
+
     @Test
     void overflowThenGrowRoundTrip() {
         final UploadArena a = new UploadArena();

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/sampler/SamplerBindGenerationTest.java

@@ -1,29 +1,23 @@
 package com.gtnewhorizons.angelica.sdlgpu.sampler;
 
 import com.gtnewhorizons.angelica.sdlgpu.SDLGPURenderBackend;
+import com.gtnewhorizons.angelica.sdlgpu.SdlTestRig;
 import com.gtnewhorizons.angelica.sdlgpu.frame.ContextState;
 import org.junit.jupiter.api.Test;
 import org.lwjgl.opengl.GL11;
 import org.lwjgl.opengl.GL13;
 
-import java.lang.reflect.Field;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotEquals;
 
 class SamplerBindGenerationTest {
 
-    @SuppressWarnings("unchecked")
-    private static ContextState state() throws Exception {
-        final Field f = SDLGPURenderBackend.class.getDeclaredField("tlState");
-        f.setAccessible(true);
-        return ((ThreadLocal<ContextState>) f.get(null)).get();
-    }
 
     @Test
-    void switchingActiveUnitDoesNotBumpTheGeneration() throws Exception {
+    void switchingActiveUnitDoesNotBumpTheGeneration() {
         final SDLGPURenderBackend backend = new SDLGPURenderBackend();
-        final ContextState st = state();
+        final ContextState st = SdlTestRig.contextState();
 
         backend.activeTexture(GL13.GL_TEXTURE0);
         final int before = st.samplerBindGen;
@@ -37,9 +31,9 @@ class SamplerBindGenerationTest {
     }
 
     @Test
-    void aRealBindChangeBumpsTheGeneration() throws Exception {
+    void aRealBindChangeBumpsTheGeneration() {
         final SDLGPURenderBackend backend = new SDLGPURenderBackend();
-        final ContextState st = state();
+        final ContextState st = SdlTestRig.contextState();
 
         backend.activeTexture(GL13.GL_TEXTURE0);
         backend.bindTexture(GL11.GL_TEXTURE_2D, 0);
@@ -50,9 +44,9 @@ class SamplerBindGenerationTest {
     }
 
     @Test
-    void rebindingTheSameTextureDoesNotBumpTheGeneration() throws Exception {
+    void rebindingTheSameTextureDoesNotBumpTheGeneration() {
         final SDLGPURenderBackend backend = new SDLGPURenderBackend();
-        final ContextState st = state();
+        final ContextState st = SdlTestRig.contextState();
 
         backend.activeTexture(GL13.GL_TEXTURE0);
         backend.bindTexture(GL11.GL_TEXTURE_2D, 99);
@@ -63,9 +57,9 @@ class SamplerBindGenerationTest {
     }
 
     @Test
-    void bindingsAreHeldPerUnitSoTheActiveUnitIsNotSamplerState() throws Exception {
+    void bindingsAreHeldPerUnitSoTheActiveUnitIsNotSamplerState() {
         final SDLGPURenderBackend backend = new SDLGPURenderBackend();
-        final ContextState st = state();
+        final ContextState st = SdlTestRig.contextState();
 
         backend.activeTexture(GL13.GL_TEXTURE2);
         backend.bindTexture(GL11.GL_TEXTURE_2D, 55);

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/shader/FontFilterVertexSamplerTest.java

@@ -0,0 +1,76 @@
+package com.gtnewhorizons.angelica.sdlgpu.shader;
+
+import com.gtnewhorizons.angelica.glsm.shader.GlslVulkanPreprocess;
+import com.gtnewhorizons.angelica.glsm.shader.SpirvCompiler;
+import com.gtnewhorizons.angelica.glsm.testutil.TestPaths;
+import com.gtnewhorizons.angelica.sdlgpu.sampler.SamplerLookup;
+import it.unimi.dsi.fastutil.objects.Object2IntOpenHashMap;
+import org.junit.jupiter.api.Test;
+import org.lwjgl.opengl.GL20;
+import org.lwjgl.util.shaderc.Shaderc;
+
+import java.nio.ByteBuffer;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.lwjgl.system.MemoryUtil.memFree;
+
+class FontFilterVertexSamplerTest {
+
+    private static final String FONT_FILTER_VSH = TestPaths.readString("src/main/resources/assets/angelica/shaders/fontFilter.vsh");
+
+    private static String runSdlPipeline(String raw) {
+        final GlslVulkanPreprocess.Result pre = GlslVulkanPreprocess.run(raw, GL20.GL_VERTEX_SHADER, "fontFilter.vsh", true);
+        String src = pre != null ? pre.rewrittenSource() : raw;
+        src = ClipZRemap.injectGLToVulkanClipZ(src);
+        src = SamplerStripper.stripUnused(src);
+        return src;
+    }
+
+    private static ShaderManager.StageReflection reflect(String source) {
+        final SpirvCompiler.Result r = SpirvCompiler.compile(source, Shaderc.shaderc_vertex_shader,
+            "fontFilter.vsh", SpirvCompiler.Options.vulkanForced460Core());
+        assertNotNull(r.spirv(), () -> "fontFilter.vsh failed to compile for Vulkan: " + r.error());
+        final ByteBuffer spirv = r.spirv();
+        try {
+            return ShaderManager.reflectStage(spirv, true);
+        } finally {
+            memFree(spirv);
+        }
+    }
+
+    @Test
+    void samplerSurvivesStrippingAndReflectsOnTheVertexStage() {
+        final String transformed = runSdlPipeline(FONT_FILTER_VSH);
+        assertTrue(transformed.contains("uniform sampler2D lightmap"), "a reference inside a runtime if must keep the declaration; only preprocessor #if hides it");
+
+        final List<String> samplers = reflect(transformed).samplerNames();
+        assertEquals(List.of("lightmap"), samplers, "the vertex stage must expose exactly the lightmap sampler");
+    }
+
+    @Test
+    void looseVec3UniformReflectsWithAStd140Offset() {
+        final List<ShaderManager.UboMember> members = reflect(runSdlPipeline(FONT_FILTER_VSH)).uboMembers();
+
+        final ShaderManager.UboMember lightmap = members.stream()
+            .filter(m -> m.name().endsWith("u_Lightmap"))
+            .findFirst()
+            .orElseThrow(() -> new AssertionError("u_Lightmap missing from the default uniform block: " + members));
+
+        assertEquals(3, lightmap.vectorSize(), "u_Lightmap must reflect as a 3-wide vector");
+        assertEquals(1, lightmap.columns(), "u_Lightmap is a vector, not a matrix");
+        assertEquals(0, lightmap.arrayStride(), "a scalar member takes Std140Writer's contiguous path");
+        assertEquals(0, lightmap.offset() % 16, "std140 aligns a vec3 to 16 bytes");
+    }
+
+    @Test
+    void samplerNamedLightmapResolvesToTextureUnitOne() {
+        final List<String> samplers = reflect(runSdlPipeline(FONT_FILTER_VSH)).samplerNames();
+        final Object2IntOpenHashMap<String> noExplicitUnits = new Object2IntOpenHashMap<>();
+        noExplicitUnits.defaultReturnValue(-1);
+
+        assertEquals(1, SamplerLookup.getSamplerTextureUnit(samplers, noExplicitUnits, 0), "even without a glUniform1i the SDL fallback must put a sampler named 'lightmap' on unit 1");
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/shader/PrewarmSingleParseEquivalenceTest.java

@@ -1,15 +1,28 @@
 package com.gtnewhorizons.angelica.sdlgpu.shader;
 
+import com.gtnewhorizons.angelica.glsm.hooks.GLSMHooks;
+import com.gtnewhorizons.angelica.glsm.hooks.PerFrameUniformBlock;
+import com.gtnewhorizons.angelica.glsm.hooks.PerFrameUniformBlock.Member;
 import com.gtnewhorizons.angelica.glsm.shader.GlslVulkanPreprocess;
+import com.gtnewhorizons.angelica.glsm.shader.UniformType;
+import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.Test;
 import org.lwjgl.opengl.GL20;
 import org.lwjgl.opengl.GL32;
 import org.lwjgl.opengl.GL43;
 
+import java.util.List;
+
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
 class PrewarmSingleParseEquivalenceTest {
 
+    @AfterEach
+    void clearBlocks() {
+        GLSMHooks.perFrameUniformBlock = null;
+        GLSMHooks.perPassUniformBlock = null;
+    }
+
     private static String legacy(String source, int glShaderType) {
         final GlslVulkanPreprocess.Result pre = GlslVulkanPreprocess.run(source, glShaderType, "test", true);
         String src = pre != null ? pre.rewrittenSource() : source;
@@ -17,6 +30,9 @@ class PrewarmSingleParseEquivalenceTest {
             src = ClipZRemap.injectGLToVulkanClipZ(src);
         }
         src = SamplerStripper.stripUnused(src);
+        if (glShaderType == GL20.GL_VERTEX_SHADER || glShaderType == GL20.GL_FRAGMENT_SHADER) {
+            src = PerFrameBlockInjector.inject(src, GLSMHooks.perFrameUniformBlock, GLSMHooks.perPassUniformBlock);
+        }
         return src;
     }
 
@@ -28,6 +44,14 @@ class PrewarmSingleParseEquivalenceTest {
         assertEquals(legacyOut, parseOnceOut, "single-parse vs chained pipeline diverged for " + label);
     }
 
+    private static void assertEquivalentIgnoringWhitespace(String label, String source, int glShaderType) {
+        GlslVulkanPreprocess.clearCache();
+        final String legacyOut = legacy(source, glShaderType);
+        GlslVulkanPreprocess.clearCache();
+        final String parseOnceOut = ShaderManager.applyPrewarmTransforms(source, glShaderType);
+        assertEquals(legacyOut.replaceAll("\\s+", " "), parseOnceOut.replaceAll("\\s+", " "), "single-parse vs chained pipeline diverged beyond whitespace for " + label);
+    }
+
     @Test
     void minimalFragment_noTransformsNeeded() {
         final String src = "#version 460 core\n"
@@ -135,4 +159,87 @@ class PrewarmSingleParseEquivalenceTest {
         final String src = "this is not valid GLSL @@@@\n";
         assertEquivalent("unparseable", src, GL20.GL_FRAGMENT_SHADER);
     }
+
+    private static final PerFrameUniformBlock PER_FRAME = new PerFrameUniformBlock(List.of(
+        new Member("cameraPosition", UniformType.VEC3),
+        new Member("frameTimeCounter", UniformType.FLOAT)));
+
+    private static final PerFrameUniformBlock PER_PASS = new PerFrameUniformBlock(List.of(
+        new Member("alphaTestRef", UniformType.FLOAT)));
+
+    @Test
+    void perFrameBlock_replaceableUniformStrippedAndInjected() {
+        GLSMHooks.perFrameUniformBlock = PER_FRAME;
+        GLSMHooks.perPassUniformBlock = PER_PASS;
+        final String src = "#version 460 core\n"
+            + "uniform float frameTimeCounter;\n"
+            + "uniform float alphaTestRef;\n"
+            + "layout(location = 0) out vec4 fragColor;\n"
+            + "void main() {\n"
+            + "    if (fragColor.a < alphaTestRef) discard;\n"
+            + "    fragColor = vec4(frameTimeCounter);\n"
+            + "}\n";
+        assertEquivalent("pfb-replaceable", src, GL20.GL_FRAGMENT_SHADER);
+    }
+
+    @Test
+    void perFrameBlock_firstDeclIsUnlocatedVsInput() {
+        GLSMHooks.perFrameUniformBlock = PER_FRAME;
+        final String src = "#version 460 core\n"
+            + "in vec3 a_Position;\n"
+            + "layout(location = 5) in vec2 a_TexCoord;\n"
+            + "uniform vec3 cameraPosition;\n"
+            + "void main() {\n"
+            + "    gl_Position = vec4(a_Position - cameraPosition, 1.0);\n"
+            + "}\n";
+        assertEquivalent("pfb-unlocated-first-in", src, GL20.GL_VERTEX_SHADER);
+    }
+
+    @Test
+    void perFrameBlock_memberUniformWithInitializer() {
+        GLSMHooks.perPassUniformBlock = PER_PASS;
+        final String src = "#version 460 core\n"
+            + "uniform float alphaTestRef = 0.1;\n"
+            + "layout(location = 0) out vec4 fragColor;\n"
+            + "void main() {\n"
+            + "    if (fragColor.a < alphaTestRef) discard;\n"
+            + "}\n";
+        assertEquivalent("pfb-initializer", src, GL20.GL_FRAGMENT_SHADER);
+    }
+
+    @Test
+    void perFrameBlock_firstDeclIsStrippedSampler() {
+        GLSMHooks.perFrameUniformBlock = PER_FRAME;
+        final String src = "#version 460 core\n"
+            + "uniform sampler2D u_Unused;\n"
+            + "uniform float frameTimeCounter;\n"
+            + "layout(location = 0) out vec4 fragColor;\n"
+            + "void main() {\n"
+            + "    fragColor = vec4(frameTimeCounter);\n"
+            + "}\n";
+        assertEquivalentIgnoringWhitespace("pfb-stripped-first-sampler", src, GL20.GL_FRAGMENT_SHADER);
+    }
+
+    @Test
+    void perFrameBlock_shadowedMemberKeepsLocalDeclaration() {
+        GLSMHooks.perFrameUniformBlock = PER_FRAME;
+        final String src = "#version 460 core\n"
+            + "uniform vec4 frameTimeCounter;\n"
+            + "uniform vec3 cameraPosition;\n"
+            + "layout(location = 0) out vec4 fragColor;\n"
+            + "void main() {\n"
+            + "    fragColor = frameTimeCounter + vec4(cameraPosition, 0.0);\n"
+            + "}\n";
+        assertEquivalent("pfb-shadowed", src, GL20.GL_FRAGMENT_SHADER);
+    }
+
+    @Test
+    void perFrameBlock_noReferencesLeavesSourceUntouched() {
+        GLSMHooks.perFrameUniformBlock = PER_FRAME;
+        GLSMHooks.perPassUniformBlock = PER_PASS;
+        final String src = "#version 460 core\n"
+            + "layout(location = 0) out vec4 fragColor;\n"
+            + "void main() { fragColor = vec4(1.0); }\n";
+        assertEquivalent("pfb-unreferenced", src, GL20.GL_FRAGMENT_SHADER);
+    }
 }

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/shader/PrewarmTreeHandoffEquivalenceTest.java

@@ -0,0 +1,123 @@
+package com.gtnewhorizons.angelica.sdlgpu.shader;
+
+import com.gtnewhorizons.angelica.glsm.GlslTransformUtils;
+import com.gtnewhorizons.angelica.glsm.hooks.GLSMHooks;
+import com.gtnewhorizons.angelica.glsm.hooks.PerFrameUniformBlock;
+import com.gtnewhorizons.angelica.glsm.hooks.PerFrameUniformBlock.Member;
+import com.gtnewhorizons.angelica.glsm.shader.GlslVulkanPreprocess;
+import com.gtnewhorizons.angelica.glsm.shader.UniformType;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.lwjgl.opengl.GL20;
+import org.lwjgl.opengl.GL32;
+import org.taumc.glsl.ShaderParser;
+import org.taumc.glsl.grammar.GLSLParser;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class PrewarmTreeHandoffEquivalenceTest {
+
+    private static final String HEADER = "#version 460 core\n";
+
+    @AfterEach
+    void clearBlocks() {
+        GLSMHooks.perFrameUniformBlock = null;
+        GLSMHooks.perPassUniformBlock = null;
+    }
+
+    private static void assertHandoffEquivalent(String label, String body, int glShaderType) {
+        final GLSLParser.Translation_unitContext tree = ShaderParser.parseShader(body).full();
+        GlslTransformUtils.restoreReservedWordsInTree(tree);
+        final String printedBody = GlslTransformUtils.getFormattedShaderRebased(tree, "");
+        final String finalSource = HEADER + printedBody;
+
+        GlslVulkanPreprocess.clearCache();
+        final ShaderManager.PrewarmTransformResult reparse = ShaderManager.applyPrewarmTransformsFull(finalSource, glShaderType);
+        GlslVulkanPreprocess.clearCache();
+        final ShaderManager.PrewarmTransformResult treeFed = ShaderManager.applyPrewarmTransformsFull(finalSource, tree, HEADER.length(), glShaderType);
+
+        assertEquals(reparse.source(), treeFed.source(), "tree handoff diverged from re-parse for " + label);
+        assertEquals(reparse.boolUniforms(), treeFed.boolUniforms(), "bool uniforms diverged for " + label);
+    }
+
+    @Test
+    void minimalFragment() {
+        assertHandoffEquivalent("minimal-fragment",
+            "layout(location = 0) out vec4 fragColor;\n"
+                + "void main() { fragColor = vec4(1.0); }\n",
+            GL20.GL_FRAGMENT_SHADER);
+    }
+
+    @Test
+    void unusedSamplerStripped() {
+        assertHandoffEquivalent("unused-sampler",
+            "uniform sampler2D u_Unused;\n"
+                + "uniform sampler2D u_Used;\n"
+                + "layout(location = 0) out vec4 fragColor;\n"
+                + "void main() { fragColor = texture(u_Used, vec2(0.5)); }\n",
+            GL20.GL_FRAGMENT_SHADER);
+    }
+
+    @Test
+    void perFrameBlockInjection() {
+        GLSMHooks.perFrameUniformBlock = new PerFrameUniformBlock(List.of(
+            new Member("cameraPosition", UniformType.VEC3),
+            new Member("frameTimeCounter", UniformType.FLOAT)));
+        assertHandoffEquivalent("per-frame-block",
+            "uniform float frameTimeCounter;\n"
+                + "layout(location = 0) out vec4 fragColor;\n"
+                + "void main() { fragColor = vec4(frameTimeCounter); }\n",
+            GL20.GL_FRAGMENT_SHADER);
+    }
+
+    @Test
+    void vertexClipZAndUnlocatedInputs() {
+        GLSMHooks.perFrameUniformBlock = new PerFrameUniformBlock(List.of(
+            new Member("cameraPosition", UniformType.VEC3)));
+        assertHandoffEquivalent("vertex-clipz-unlocated",
+            "layout(location = 0) in vec3 a_Position;\n"
+                + "in vec2 a_TexCoord;\n"
+                + "uniform vec3 cameraPosition;\n"
+                + "out vec2 v_TexCoord;\n"
+                + "void main() {\n"
+                + "    v_TexCoord = a_TexCoord;\n"
+                + "    gl_Position = vec4(a_Position - cameraPosition, 1.0);\n"
+                + "}\n",
+            GL20.GL_VERTEX_SHADER);
+    }
+
+    @Test
+    void boolUniformMetadata() {
+        assertHandoffEquivalent("bool-uniform",
+            "uniform bool u_Enabled;\n"
+                + "layout(location = 0) out vec4 fragColor;\n"
+                + "void main() { fragColor = vec4(u_Enabled ? 1.0 : 0.0); }\n",
+            GL20.GL_FRAGMENT_SHADER);
+    }
+
+    @Test
+    void texelFetchPath() {
+        assertHandoffEquivalent("texelfetch",
+            "uniform sampler2D u_Data;\n"
+                + "layout(location = 0) out vec4 fragColor;\n"
+                + "void main() { fragColor = texelFetch(u_Data, ivec2(0), 0); }\n",
+            GL20.GL_FRAGMENT_SHADER);
+    }
+
+    @Test
+    void geometryStage() {
+        assertHandoffEquivalent("geometry",
+            "layout(triangles) in;\n"
+                + "layout(triangle_strip, max_vertices = 3) out;\n"
+                + "void main() {\n"
+                + "    for (int i = 0; i < 3; i++) {\n"
+                + "        gl_Position = gl_in[i].gl_Position;\n"
+                + "        EmitVertex();\n"
+                + "    }\n"
+                + "    EndPrimitive();\n"
+                + "}\n",
+            GL32.GL_GEOMETRY_SHADER);
+    }
+}

sdl-gpu/src/test/java/com/gtnewhorizons/angelica/sdlgpu/util/ThreadRegistryTest.java

@@ -0,0 +1,46 @@
+package com.gtnewhorizons.angelica.sdlgpu.util;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+
+class ThreadRegistryTest {
+
+    private static ThreadRegistry<Object> registry() {
+        return new ThreadRegistry<>(new Object[0]);
+    }
+
+    @Test
+    void soleTracksTheSingleEntry() {
+        final ThreadRegistry<Object> r = registry();
+        final Object a = new Object();
+        final Object b = new Object();
+
+        assertNull(r.sole(), "empty registry has no sole entry");
+        r.add(a);
+        assertSame(a, r.sole());
+        r.add(b);
+        assertNull(r.sole(), "two entries means no sole entry");
+        r.remove(b);
+        assertSame(a, r.sole());
+        r.remove(a);
+        assertNull(r.sole());
+        assertEquals(0, r.size());
+    }
+
+    @Test
+    void removeOfAnAbsentEntryLeavesTheRegistryAlone() {
+        final ThreadRegistry<Object> r = registry();
+        final Object a = new Object();
+        r.add(a);
+        final Object[] before = r.snapshot();
+
+        assertFalse(r.remove(new Object()));
+        assertSame(before, r.snapshot(), "a no-op remove must not republish");
+        assertSame(a, r.sole());
+    }
+
+}

src/main/java/com/gtnewhorizons/angelica/client/font/BatchingFontRenderer.java

@@ -4,19 +4,14 @@ import com.google.common.collect.ImmutableSet;
 import com.gtnewhorizon.gtnhlib.bytebuf.MemoryStack;
 import com.gtnewhorizon.gtnhlib.client.renderer.vao.IndexBuffer;
 import com.gtnewhorizon.gtnhlib.util.font.GlyphReplacements;
-import static com.gtnewhorizons.angelica.client.font.ColorCodeUtils.FORMATTING_CHAR;
-import static com.gtnewhorizons.angelica.client.font.ColorCodeUtils.GRADIENT_PAYLOAD;
-import static com.gtnewhorizons.angelica.client.font.ColorCodeUtils.SECTION_X_LENGTH;
-import static com.gtnewhorizons.angelica.client.font.ColorCodeUtils.SECTION_X_PAYLOAD;
-
 import com.gtnewhorizons.angelica.config.AngelicaConfig;
 import com.gtnewhorizons.angelica.config.FontConfig;
-import com.gtnewhorizons.angelica.hudcaching.HUDCaching;
-import com.gtnewhorizons.angelica.AngelicaMod;
 import com.gtnewhorizons.angelica.glsm.GLStateManager;
-import com.gtnewhorizons.angelica.glsm.RenderSystem;
+import com.gtnewhorizons.angelica.glsm.ffp.FFPVertexLighting;
+import com.gtnewhorizons.angelica.glsm.hooks.GLSMConfig;
 import com.gtnewhorizons.angelica.glsm.streaming.PersistentStreamingBuffer;
 import com.gtnewhorizons.angelica.glsm.streaming.StreamingUploader;
+import com.gtnewhorizons.angelica.hudcaching.HUDCaching;
 import com.gtnewhorizons.angelica.mixins.interfaces.FontRendererAccessor;
 import com.gtnewhorizons.angelica.rendering.tesr.ModelPartBatcher;
 import com.gtnewhorizons.angelica.rendering.tesr.TesrBatchRenderer;
@@ -29,20 +24,31 @@ import net.minecraft.util.MathHelper;
 import net.minecraft.util.ResourceLocation;
 import org.embeddedt.embeddium.impl.render.shader.ShaderLoader;
 import org.joml.Matrix4f;
+import org.joml.Vector3f;
+import org.joml.Vector4f;
 import org.lwjgl.opengl.GL11;
+import org.lwjgl.opengl.GL13;
 import org.lwjgl.opengl.GL15;
 import org.lwjgl.opengl.GL20;
 
-
 import java.nio.ByteBuffer;
 import java.nio.FloatBuffer;
-
 import java.util.Arrays;
 import java.util.Comparator;
 import java.util.Objects;
 
 import static com.gtnewhorizon.gtnhlib.bytebuf.MemoryStack.stackPush;
-import static com.gtnewhorizon.gtnhlib.bytebuf.MemoryUtilities.*;
+import static com.gtnewhorizon.gtnhlib.bytebuf.MemoryUtilities.memAddress0;
+import static com.gtnewhorizon.gtnhlib.bytebuf.MemoryUtilities.memAlloc;
+import static com.gtnewhorizon.gtnhlib.bytebuf.MemoryUtilities.memFree;
+import static com.gtnewhorizon.gtnhlib.bytebuf.MemoryUtilities.memPutByte;
+import static com.gtnewhorizon.gtnhlib.bytebuf.MemoryUtilities.memPutFloat;
+import static com.gtnewhorizon.gtnhlib.bytebuf.MemoryUtilities.memPutShort;
+import static com.gtnewhorizon.gtnhlib.bytebuf.MemoryUtilities.memRealloc;
+import static com.gtnewhorizons.angelica.client.font.ColorCodeUtils.FORMATTING_CHAR;
+import static com.gtnewhorizons.angelica.client.font.ColorCodeUtils.GRADIENT_PAYLOAD;
+import static com.gtnewhorizons.angelica.client.font.ColorCodeUtils.SECTION_X_LENGTH;
+import static com.gtnewhorizons.angelica.client.font.ColorCodeUtils.SECTION_X_PAYLOAD;
 
 /**
  * A batching replacement for {@code FontRenderer}
@@ -67,6 +73,8 @@ public class BatchingFontRenderer {
     private final int AAStrength;
     private final int alphaTestRefLocation;
     private final int mvpMatrixLocation;
+    private final int lightmapLocation;
+    private final int lightmapSamplerLocation;
     private final int fontShaderId;
 
     final boolean isSGA;
@@ -111,6 +119,8 @@ public class BatchingFontRenderer {
         AAStrength = GLStateManager.glGetUniformLocation(fontShaderId, "strength");
         alphaTestRefLocation = GLStateManager.glGetUniformLocation(fontShaderId, "alphaTestRef");
         mvpMatrixLocation = GLStateManager.glGetUniformLocation(fontShaderId, "u_MVPMatrix");
+        lightmapLocation = GLStateManager.glGetUniformLocation(fontShaderId, "u_Lightmap");
+        lightmapSamplerLocation = GLStateManager.glGetUniformLocation(fontShaderId, "lightmap");
         if (ebo == null) {
             ebo = new IndexBuffer();
             vbo = GLStateManager.glGenBuffers();
@@ -128,6 +138,9 @@ public class BatchingFontRenderer {
     // [v, v, t, t, c, c, c, c, tb, tb, tb, tb]
     // v, t and tb are floats, c is bytes; 36 bytes total
     private static final int VERTEX_SIZE = 36;
+
+    /** {@code OpenGlHelper.lightmapTexUnit} */
+    private static final int LIGHTMAP_TEX_UNIT = 1;
     private static int rawCapacity = INITIAL_BATCH_SIZE * VERTEX_SIZE;
     private static ByteBuffer vertexData = memAlloc(rawCapacity);
     private static long vertexDataAddress = memAddress0(vertexData);
@@ -138,6 +151,7 @@ public class BatchingFontRenderer {
     private static int fontVAO = 0;
     private static int vbo;
     private static IndexBuffer ebo;
+    private static int lightmapSamplerProgram;
 
     private static final int RING_CAPACITY = 2 * 1024 * 1024;
     private static PersistentStreamingBuffer streamRing;
@@ -158,11 +172,58 @@ public class BatchingFontRenderer {
     private int blendSrcRGB = GL11.GL_SRC_ALPHA;
     private int blendDstRGB = GL11.GL_ONE_MINUS_SRC_ALPHA;
 
-    private static final class DeferredTextSegment {
+    private float lightmapU = 0.0f;
+    private float lightmapV = 0.0f;
+    private boolean lightmapActive = false;
+    private int lightmapTextureId = 0;
+
+    private final Vector3f lightingFactor = new Vector3f(1.0f, 1.0f, 1.0f);
+    private boolean lightingFactorActive = false;
+
+    private static final Vector4f scratchLightmapUv = new Vector4f();
+
+    private int applyLighting(int argb) {
+        if (!lightingFactorActive) return argb;
+        final int red = Math.max(0, Math.min(255, (int) (((argb >> 16) & 0xFF) * lightingFactor.x + 0.5f)));
+        final int green = Math.max(0, Math.min(255, (int) (((argb >> 8) & 0xFF) * lightingFactor.y + 0.5f)));
+        final int blue = Math.max(0, Math.min(255, (int) ((argb & 0xFF) * lightingFactor.z + 0.5f)));
+        return (argb & 0xFF000000) | (red << 16) | (green << 8) | blue;
+    }
+
+    private void captureLightmapState() {
+        final int unitBinding = GLStateManager.getTextures().getTextureUnitBindings(LIGHTMAP_TEX_UNIT).getBinding();
+
+        final boolean active = GLStateManager.getProjectionMatrix().m33() == 0.0f && unitBinding != 0;
+
+        float u = 0.0f;
+        float v = 0.0f;
+        int texture = 0;
+        if (active) {
+            scratchLightmapUv.set(GLSMConfig.lastBrightnessX, GLSMConfig.lastBrightnessY, 0.0f, 1.0f).mul(GLStateManager.getTextures().getTextureUnitMatrix(LIGHTMAP_TEX_UNIT));
+            u = scratchLightmapUv.x;
+            v = scratchLightmapUv.y;
+            texture = unitBinding;
+        }
+
+        if (active == lightmapActive && u == lightmapU && v == lightmapV && texture == lightmapTextureId) {
+            return;
+        }
+        sealBatchSegment();
+        lightmapActive = active;
+        lightmapU = u;
+        lightmapV = v;
+        lightmapTextureId = texture;
+    }
+
+    private static final class TextSegment {
         final Matrix4f mvp = new Matrix4f();
         BatchingFontRenderer owner;
         int cmdStart;
         int cmdEnd;
+        float lightmapU;
+        float lightmapV;
+        boolean lightmapActive;
+        int lightmapTexture;
     }
 
     // 16-bit EBO index range
@@ -172,10 +233,16 @@ public class BatchingFontRenderer {
     private static int deferredIdxPos;
 
     private int deferredCmdWatermark;
-    private static final ObjectArrayList<DeferredTextSegment> deferredSegments = ObjectArrayList.wrap(new DeferredTextSegment[16], 0);
-    private static final ObjectArrayList<DeferredTextSegment> deferredSegmentPool = ObjectArrayList.wrap(new DeferredTextSegment[16], 0);
+    private static final ObjectArrayList<TextSegment> deferredSegments = ObjectArrayList.wrap(new TextSegment[16], 0);
+    private static final ObjectArrayList<TextSegment> deferredSegmentPool = ObjectArrayList.wrap(new TextSegment[16], 0);
     private boolean deferCurrentBatch;
 
+    private final Matrix4f batchProj = new Matrix4f();
+    private final Matrix4f batchModelView = new Matrix4f();
+    private boolean batchMatrixValid;
+    private final ObjectArrayList<TextSegment> batchSegments = ObjectArrayList.wrap(new TextSegment[16], 0);
+    private int batchSealedEnd;
+    private static BatchingFontRenderer arenaOwner;
 
     private void allocateBuffers() {
         populateEBO(rawCapacity / VERTEX_SIZE);
@@ -248,6 +315,7 @@ public class BatchingFontRenderer {
 
     private void pushVtx(float x, float y, int rgba, float u, float v, float uMin, float uMax, float vMin, float vMax) {
         final long ptr = vertexDataAddress + vertexDataPos;
+        rgba = applyLighting(rgba);
 
         // v, v
         memPutFloat(ptr, x);
@@ -298,8 +366,9 @@ public class BatchingFontRenderer {
     }
 
     private void pushDrawCmd(int startIdx, int idxCount, ResourceLocation texture, boolean isUnicode) {
-        // Never coalesce into a command below the watermark - it belongs to a sealed deferred segment.
-        if (batchCommands.size() > deferredCmdWatermark) {
+        arenaOwner = this;
+        // Never coalesce into a command below the watermark - it belongs to a sealed segment.
+        if (batchCommands.size() > batchSealedEnd) {
             final FontDrawCmd lastCmd = batchCommands.get(batchCommands.size() - 1);
             final int prevEndVtx = lastCmd.startVtx + lastCmd.idxCount;
             if (prevEndVtx == startIdx && lastCmd.texture == texture) {
@@ -370,9 +439,59 @@ public class BatchingFontRenderer {
      * allow for easier optimizing of blocks of font rendering code.
      */
     public void beginBatch() {
+        if (arenaOwner != null && arenaOwner != this) {
+            arenaOwner.flushBatch();
+        }
+        if (batchDepth > 0) {
+            if (batchCommands.size() == batchSealedEnd) {
+                captureBatchMatrix();
+            } else if (!batchProj.equals(GLStateManager.getProjectionMatrix(), 0.0f) || !batchModelView.equals(GLStateManager.getModelViewMatrix(), 0.0f)) {
+                sealBatchSegment();
+                captureBatchMatrix();
+            }
+        }
         batchDepth++;
     }
 
+    private void captureBatchMatrix() {
+        batchProj.set(GLStateManager.getProjectionMatrix());
+        batchModelView.set(GLStateManager.getModelViewMatrix());
+        batchMatrixValid = true;
+    }
+
+    private void resolveMvp(Matrix4f dest) {
+        if (batchMatrixValid) {
+            batchProj.mul(batchModelView, dest);
+        } else {
+            GLStateManager.getProjectionMatrix().mul(GLStateManager.getModelViewMatrix(), dest);
+        }
+    }
+
+    private void sealBatchSegment() {
+        final int end = batchCommands.size();
+        if (end == batchSealedEnd) return;
+        final TextSegment segment = deferredSegmentPool.isEmpty() ? new TextSegment() : deferredSegmentPool.pop();
+        segment.owner = this;
+        segment.cmdStart = batchSealedEnd;
+        segment.cmdEnd = end;
+        resolveMvp(segment.mvp);
+        segment.lightmapActive = lightmapActive;
+        segment.lightmapU = lightmapU;
+        segment.lightmapV = lightmapV;
+        segment.lightmapTexture = lightmapTextureId;
+        batchSegments.add(segment);
+        batchSealedEnd = end;
+    }
+
+    private void recycleBatchSegments() {
+        if (batchSegments.isEmpty()) return;
+        for (int i = 0, n = batchSegments.size(); i < n; i++) {
+            batchSegments.get(i).owner = null;
+        }
+        deferredSegmentPool.addAll(batchSegments);
+        batchSegments.clear();
+    }
+
     public void endBatch() {
         if (batchDepth <= 0) {
             batchDepth = 0;
@@ -404,7 +523,8 @@ public class BatchingFontRenderer {
     }
 
     private void deferBatch() {
-        if (batchCommands.size() == deferredCmdWatermark || vertexDataPos == deferredVertexPos) {
+        sealBatchSegment();
+        if (batchSegments.isEmpty()) {
             truncateBatchToWatermark();
             return;
         }
@@ -412,15 +532,13 @@ public class BatchingFontRenderer {
             flushBatch();
             return;
         }
-        final DeferredTextSegment segment = deferredSegmentPool.isEmpty() ? new DeferredTextSegment() : deferredSegmentPool.pop();
-        segment.owner = this;
-        segment.cmdStart = deferredCmdWatermark;
-        segment.cmdEnd = batchCommands.size();
-        GLStateManager.getProjectionMatrix().mul(GLStateManager.getModelViewMatrix(), segment.mvp);
-        deferredSegments.add(segment);
+        deferredSegments.addAll(batchSegments);
+        batchSegments.clear();
         deferredCmdWatermark = batchCommands.size();
+        batchSealedEnd = deferredCmdWatermark;
         deferredVertexPos = vertexDataPos;
         deferredIdxPos = idxWriterIndex;
+        batchMatrixValid = false;
     }
 
     public static void flushDeferredText() {
@@ -432,6 +550,7 @@ public class BatchingFontRenderer {
         final boolean isTextureEnabledBefore = GLStateManager.glIsEnabled(GL11.GL_TEXTURE_2D);
         final boolean isBlendEnabledBefore = GLStateManager.glIsEnabled(GL11.GL_BLEND);
         final int boundTextureBefore = GLStateManager.glGetInteger(GL11.GL_TEXTURE_BINDING_2D);
+        final int lightmapBindingBefore = boundLightmapTexture();
 
         final boolean depthTestBefore = GLStateManager.getDepthTest().isEnabled();
         final boolean depthMaskBefore = GLStateManager.getDepthState().isEnabled();
@@ -440,17 +559,20 @@ public class BatchingFontRenderer {
         GLStateManager.glDepthMask(false);
         flushLastTexture = DUMMY_RESOURCE_LOCATION;
         flushTextureChanged = false;
+        resetFlushLightmap();
         try (MemoryStack stack = stackPush()) {
             final FloatBuffer mvpBuf = stack.mallocFloat(16);
             for (int i = 0, n = deferredSegments.size(); i < n; i++) {
-                final DeferredTextSegment segment = deferredSegments.get(i);
+                final TextSegment segment = deferredSegments.get(i);
                 mvpBuf.clear();
                 segment.mvp.get(mvpBuf);
                 GLStateManager.glUniformMatrix4(segment.owner.mvpMatrixLocation, false, mvpBuf);
+                uploadLightmap(segment.owner.lightmapLocation, segment.lightmapActive, segment.lightmapU,
+                    segment.lightmapV, segment.lightmapTexture);
                 drawCommands(segment.owner.batchCommands.elements(), segment.cmdStart, segment.cmdEnd, segment.owner);
             }
         }
-        restoreFontDrawState(prevProgram, isTextureEnabledBefore, isBlendEnabledBefore, boundTextureBefore);
+        restoreFontDrawState(prevProgram, isTextureEnabledBefore, isBlendEnabledBefore, boundTextureBefore, lightmapBindingBefore);
         restoreDepth(depthTestBefore, depthMaskBefore);
 
         discardDeferredText();
@@ -459,8 +581,12 @@ public class BatchingFontRenderer {
     public static void discardDeferredText() {
         if (deferredSegments.isEmpty()) return;
         for (int i = 0, n = deferredSegments.size(); i < n; i++) {
-            final DeferredTextSegment segment = deferredSegments.get(i);
+            final TextSegment segment = deferredSegments.get(i);
             segment.owner.clearDeferredCommands();
+            segment.owner.recycleBatchSegments();
+            segment.owner.batchSealedEnd = 0;
+            segment.owner.batchMatrixValid = false;
+            segment.owner.resetLightmapState();
             segment.owner = null;
         }
         deferredSegmentPool.addAll(deferredSegments);
@@ -469,6 +595,7 @@ public class BatchingFontRenderer {
         deferredIdxPos = 0;
         vertexDataPos = 0;
         idxWriterIndex = 0;
+        arenaOwner = null;
     }
 
     private void clearDeferredCommands() {
@@ -477,6 +604,12 @@ public class BatchingFontRenderer {
             batchCommandPool.add(batchCommands.get(i));
         }
         batchCommands.removeElements(0, deferredCmdWatermark);
+        for (int i = 0, n = batchSegments.size(); i < n; i++) {
+            final TextSegment segment = batchSegments.get(i);
+            segment.cmdStart -= deferredCmdWatermark;
+            segment.cmdEnd -= deferredCmdWatermark;
+        }
+        batchSealedEnd = Math.max(0, batchSealedEnd - deferredCmdWatermark);
         deferredCmdWatermark = 0;
     }
 
@@ -495,7 +628,8 @@ public class BatchingFontRenderer {
 
     private void flushBatchInner() {
         final int cmdCount = batchCommands.size();
-        if (vertexDataPos == deferredVertexPos || cmdCount == deferredCmdWatermark) {
+        final int segmentCount = batchSegments.size();
+        if (segmentCount == 0 && (vertexDataPos == deferredVertexPos || cmdCount == deferredCmdWatermark)) {
             truncateBatchToWatermark();
             return;
         }
@@ -504,26 +638,44 @@ public class BatchingFontRenderer {
 
         final int prevProgram = GLStateManager.glGetInteger(GL20.GL_CURRENT_PROGRAM);
 
-        Arrays.sort(batchCommands.elements(), deferredCmdWatermark, cmdCount, FontDrawCmd.DRAW_ORDER_COMPARATOR);
+        final FontDrawCmd[] cmds = batchCommands.elements();
+        for (int i = 0; i < segmentCount; i++) {
+            final TextSegment segment = batchSegments.get(i);
+            Arrays.sort(cmds, segment.cmdStart, segment.cmdEnd, FontDrawCmd.DRAW_ORDER_COMPARATOR);
+        }
+        Arrays.sort(cmds, batchSealedEnd, cmdCount, FontDrawCmd.DRAW_ORDER_COMPARATOR);
 
         final boolean isTextureEnabledBefore = GLStateManager.glIsEnabled(GL11.GL_TEXTURE_2D);
         final boolean isBlendEnabledBefore = GLStateManager.glIsEnabled(GL11.GL_BLEND);
         final int boundTextureBefore = GLStateManager.glGetInteger(GL11.GL_TEXTURE_BINDING_2D);
+        final int lightmapBindingBefore = boundLightmapTexture();
         final boolean depthTestBefore = GLStateManager.getDepthTest().isEnabled();
         final boolean depthMaskBefore = GLStateManager.getDepthState().isEnabled();
 
         setupFontDrawState();
-        try (MemoryStack stack = stackPush()) {
-            final FloatBuffer mvpBuf = stack.mallocFloat(16);
-            GLStateManager.getProjectionMatrix().mul(GLStateManager.getModelViewMatrix(), scratchMvp);
-            scratchMvp.get(mvpBuf);
-            GLStateManager.glUniformMatrix4(mvpMatrixLocation, false, mvpBuf);
-        }
-
         flushLastTexture = DUMMY_RESOURCE_LOCATION;
         flushTextureChanged = false;
-        drawCommands(batchCommands.elements(), deferredCmdWatermark, cmdCount, this);
-        restoreFontDrawState(prevProgram, isTextureEnabledBefore, isBlendEnabledBefore, boundTextureBefore);
+        resetFlushLightmap();
+        try (MemoryStack stack = stackPush()) {
+            final FloatBuffer mvpBuf = stack.mallocFloat(16);
+            for (int i = 0; i < segmentCount; i++) {
+                final TextSegment segment = batchSegments.get(i);
+                mvpBuf.clear();
+                segment.mvp.get(mvpBuf);
+                GLStateManager.glUniformMatrix4(mvpMatrixLocation, false, mvpBuf);
+                uploadLightmap(lightmapLocation, segment.lightmapActive, segment.lightmapU, segment.lightmapV, segment.lightmapTexture);
+                drawCommands(cmds, segment.cmdStart, segment.cmdEnd, this);
+            }
+            if (batchSealedEnd < cmdCount) {
+                mvpBuf.clear();
+                resolveMvp(scratchMvp);
+                scratchMvp.get(mvpBuf);
+                GLStateManager.glUniformMatrix4(mvpMatrixLocation, false, mvpBuf);
+                uploadLightmap(lightmapLocation, lightmapActive, lightmapU, lightmapV, lightmapTextureId);
+                drawCommands(cmds, batchSealedEnd, cmdCount, this);
+            }
+        }
+        restoreFontDrawState(prevProgram, isTextureEnabledBefore, isBlendEnabledBefore, boundTextureBefore, lightmapBindingBefore);
         restoreDepth(depthTestBefore, depthMaskBefore);
 
         truncateBatchToWatermark();
@@ -546,6 +698,10 @@ public class BatchingFontRenderer {
             GLStateManager.glUniform1f(AAStrength, FontConfig.fontAAStrength / 120.f);
         }
         GLStateManager.glUniform1f(alphaTestRefLocation, GLStateManager.getAlphaState().getReference());
+        if (lightmapSamplerProgram != fontShaderId) {
+            GLStateManager.glUniform1i(lightmapSamplerLocation, LIGHTMAP_TEX_UNIT);
+            lightmapSamplerProgram = fontShaderId;
+        }
 
         if (fontVAO == 0) {
             fontVAO = GLStateManager.glGenVertexArrays();
@@ -576,6 +732,38 @@ public class BatchingFontRenderer {
     private static ResourceLocation flushLastTexture;
     private static boolean flushTextureChanged;
 
+    private static float flushLastLightmapU;
+    private static float flushLastLightmapV;
+    private static boolean flushLastLightmapActive;
+
+    private static void resetFlushLightmap() {
+        flushLastLightmapU = Float.NaN;
+        flushLastLightmapV = Float.NaN;
+        flushLastLightmapActive = false;
+    }
+
+    private static int boundLightmapTexture() {
+        return GLStateManager.getTextures().getTextureUnitBindings(LIGHTMAP_TEX_UNIT).getBinding();
+    }
+
+    private static void bindLightmapTexture(int texture) {
+        GLStateManager.glActiveTexture(GL13.GL_TEXTURE0 + LIGHTMAP_TEX_UNIT);
+        GLStateManager.glBindTexture(GL11.GL_TEXTURE_2D, texture);
+        GLStateManager.glActiveTexture(GL13.GL_TEXTURE0);
+    }
+
+    private static void uploadLightmap(int uniformLocation, boolean active, float u, float v, int texture) {
+        if (u != flushLastLightmapU || v != flushLastLightmapV || active != flushLastLightmapActive) {
+            GLStateManager.glUniform3f(uniformLocation, u, v, active ? 1.0f : 0.0f);
+            flushLastLightmapU = u;
+            flushLastLightmapV = v;
+            flushLastLightmapActive = active;
+        }
+        if (active && texture != 0 && boundLightmapTexture() != texture) {
+            bindLightmapTexture(texture);
+        }
+    }
+
     private static void drawCommands(FontDrawCmd[] cmdsData, int from, int to, BatchingFontRenderer owner) {
         for (int i = from; i < to; i++) {
             final FontDrawCmd cmd = cmdsData[i];
@@ -595,7 +783,7 @@ public class BatchingFontRenderer {
         }
     }
 
-    private static void restoreFontDrawState(int prevProgram, boolean textureEnabledBefore, boolean blendEnabledBefore, int boundTextureBefore) {
+    private static void restoreFontDrawState(int prevProgram, boolean textureEnabledBefore, boolean blendEnabledBefore, int boundTextureBefore, int lightmapBindingBefore) {
         GLStateManager.glUseProgram(prevProgram);
 
         GLStateManager.glBindBuffer(GL15.GL_ARRAY_BUFFER, 0);
@@ -610,6 +798,9 @@ public class BatchingFontRenderer {
         if (flushTextureChanged) {
             GLStateManager.glBindTexture(GL11.GL_TEXTURE_2D, boundTextureBefore);
         }
+        if (boundLightmapTexture() != lightmapBindingBefore) {
+            bindLightmapTexture(lightmapBindingBefore);
+        }
     }
 
     private static void restoreDepth(boolean testBefore, boolean maskBefore) {
@@ -622,12 +813,26 @@ public class BatchingFontRenderer {
     }
 
     private void truncateBatchToWatermark() {
+        recycleBatchSegments();
         for (int i = batchCommands.size() - 1; i >= deferredCmdWatermark; i--) {
             batchCommandPool.add(batchCommands.get(i));
         }
         batchCommands.size(deferredCmdWatermark);
+        batchSealedEnd = deferredCmdWatermark;
+        batchMatrixValid = false;
         vertexDataPos = deferredVertexPos;
         idxWriterIndex = deferredIdxPos;
+        resetLightmapState();
+        if (arenaOwner == this) {
+            arenaOwner = null;
+        }
+    }
+
+    private void resetLightmapState() {
+        lightmapActive = false;
+        lightmapU = 0.0f;
+        lightmapV = 0.0f;
+        lightmapTextureId = 0;
     }
 
     // === Actual text mesh generation
@@ -724,6 +929,8 @@ public class BatchingFontRenderer {
         FontProviderMC.get(this.isSGA).locationFontTexture = this.locationFontTexture;
 
         this.beginBatch();
+        this.captureLightmapState();
+        this.lightingFactorActive = FFPVertexLighting.modulatesVertexColor(this.lightingFactor);
         float curX = anchorX;
         try {
             final int totalStringLength = string.length();

src/main/java/com/gtnewhorizons/angelica/compat/DriverCompatabilityCheck.java

@@ -7,6 +7,7 @@ import org.lwjgl.opengl.GL11;
 
 import com.gtnewhorizons.angelica.config.SystemProperties;
 import com.gtnewhorizons.angelica.glsm.GLStateManager;
+import com.gtnewhorizons.angelica.glsm.LTWWorkaround;
 
 /**
  * Checks for known problematic driver configurations and applies workarounds. Adapted from Embeddium/Sodium's LateDriverScanner.
@@ -28,6 +29,14 @@ public class DriverCompatabilityCheck {
         LOGGER.info("OpenGL Renderer: {}", renderer);
         LOGGER.info("OpenGL Version: {}", version);
 
+        if (LTWWorkaround.isLtwVersionString(version)) {
+            if (SystemProperties.DISABLE_LTW_WORKAROUND) {
+                LOGGER.info("OpenLTW workaround disabled via -Dangelica.disableLtwWorkaround=true");
+            } else {
+                LOGGER.info("OpenLTW wrapper detected; enabling BGRA texture swizzle workaround");
+            }
+        }
+
         if (vendor != null && vendor.contains("NVIDIA")) {
             if (SystemProperties.DISABLE_NVIDIA_WORKAROUND) {
                 LOGGER.info("NVIDIA workaround disabled via -Dangelica.disableNvidiaWorkaround=true");

src/main/java/com/gtnewhorizons/angelica/config/AngelicaConfig.java

@@ -385,6 +385,11 @@ public class AngelicaConfig {
         @Config.DefaultBoolean(true)
         @Config.RequiresMcRestart
         public boolean narrowFoamFix;
+
+        @Config.Comment("Narrow Legends Mod transformer exclusions to allow GL redirection")
+        @Config.DefaultBoolean(true)
+        @Config.RequiresMcRestart
+        public boolean narrowLegendsMod;
     }
 
     @Config.Comment("Renders chunks before neighbors are ready. Improves loading at render distance edges, useful for low render distance servers.")

src/main/java/com/gtnewhorizons/angelica/helpers/RendererLivingEntityHelper.java

@@ -0,0 +1,35 @@
+package com.gtnewhorizons.angelica.helpers;
+
+import static com.gtnewhorizons.angelica.client.font.ColorCodeUtils.FORMATTING_CHAR;
+
+import net.minecraft.entity.EntityLiving;
+import net.minecraft.entity.EntityLivingBase;
+import net.minecraft.entity.player.EntityPlayer;
+import net.minecraft.util.EnumChatFormatting;
+
+public final class RendererLivingEntityHelper {
+
+    private RendererLivingEntityHelper() {}
+
+    public static String getUpsideDownName(EntityLivingBase entity) {
+        if (entity instanceof EntityLiving living) {
+            return living.hasCustomNameTag() ? entity.getCommandSenderName() : "";
+        }
+
+        if (entity instanceof EntityPlayer player) {
+            return player.getHideCape() ? "" : entity.getCommandSenderName();
+        }
+
+        return entity.getCommandSenderName();
+    }
+
+    public static String stripFormattingCodes(String entityName) {
+        if (entityName == null || entityName.isEmpty()) {
+            return "";
+        }
+
+        return entityName.indexOf(FORMATTING_CHAR) < 0
+            ? entityName
+            : EnumChatFormatting.getTextWithoutFormattingCodes(entityName);
+    }
+}

src/main/java/com/gtnewhorizons/angelica/iris/IrisGLSMBridge.java

@@ -6,8 +6,11 @@ import com.gtnewhorizons.angelica.glsm.hooks.DeferredBlendHandler;
 import com.gtnewhorizons.angelica.glsm.hooks.DeferredDepthColorHandler;
 import com.gtnewhorizons.angelica.glsm.hooks.GLSMConfig;
 import com.gtnewhorizons.angelica.glsm.hooks.GLSMHooks;
+import com.gtnewhorizons.angelica.glsm.hooks.ShaderTransformPostProcessor;
+import com.gtnewhorizons.angelica.glsm.shader.ShaderType;
+import org.taumc.glsl.grammar.GLSLParser;
 import com.gtnewhorizons.angelica.glsm.hooks.ShaderWorkSubmitter;
-import com.gtnewhorizons.angelica.sdlgpu.shader.ShaderManager;
+import com.gtnewhorizons.angelica.sdlgpu.SDLGPUGate;
 import net.coderbot.iris.Iris;
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Supplier;
@@ -48,6 +51,27 @@ public class IrisGLSMBridge {
         StateUpdateNotifiers.colorModulatorNotifier = listener -> colorModulatorListener = listener;
     }
 
+    public static void installPostTransformHook() {
+        if (GLSMHooks.postTransformProcessor != null) return;
+        GLSMHooks.postTransformProcessor = new ShaderTransformPostProcessor() {
+            @Override
+            public void onTransformed(String src, ShaderType shaderType) {
+                onTransformed(src, null, 0, shaderType);
+            }
+
+            @Override
+            public void onTransformed(String src, GLSLParser.Translation_unitContext bodyTree, int headerLen, ShaderType shaderType) {
+                if (Iris.ShaderTransformExecutor.isOnWorker()) {
+                    SDLGPUGate.prewarmSpirv(src, bodyTree, headerLen, shaderType.id);
+                } else {
+                    Iris.ShaderTransformExecutor.submitTracked(() -> {
+                        SDLGPUGate.prewarmSpirv(src, bodyTree, headerLen, shaderType.id);
+                    });
+                }
+            }
+        };
+    }
+
     public static void register() {
         GLSMConfig.expandVertexFormats = Iris.enabled;
         IrisSamplers.initRenderer();
@@ -57,15 +81,7 @@ public class IrisGLSMBridge {
                 return Iris.ShaderTransformExecutor.submitTracked(work);
             }
         };
-        GLSMHooks.postTransformProcessor = (src, shaderType) -> {
-            if (Iris.ShaderTransformExecutor.isOnWorker()) {
-                ShaderManager.prewarmSpirv(src, shaderType.id);
-            } else {
-                Iris.ShaderTransformExecutor.submitTracked(() -> {
-                    ShaderManager.prewarmSpirv(src, shaderType.id);
-                });
-            }
-        };
+        installPostTransformHook();
         GLSMHooks.blendHandler = new DeferredBlendHandler() {
             @Override
             public boolean isBlendLocked() {

src/main/java/com/gtnewhorizons/angelica/loading/AngelicaClientTweaker.java

@@ -201,6 +201,7 @@ public final class AngelicaClientTweaker implements IFMLLoadingPlugin, IEarlyMix
             narrowTransformerConfig("Ears", AngelicaConfig.transformerCompat.narrowEars);
             narrowTransformerConfig("FiskHeroes", AngelicaConfig.transformerCompat.narrowFiskHeroes);
             narrowTransformerConfig("FoamFix", AngelicaConfig.transformerCompat.narrowFoamFix);
+            narrowTransformerConfig("LegendsMod", AngelicaConfig.transformerCompat.narrowLegendsMod);
 
             tweaks.add("com.gtnewhorizons.angelica.loading.fml.tweakers.IncompatibleModsDisablerTweaker");
             if (AngelicaConfig.enableHudCaching) {