ADD: Docs and shader optim

src/core/types.h

@@ -28,6 +28,7 @@ inline const char *string_VkFormat(VkFormat) { return "VkFormat"; }
 #include <fmt/core.h>
 
 #include <glm/mat4x4.hpp>
+#include <glm/mat3x4.hpp>
 #include <glm/vec4.hpp>
 #include <glm/vec3.hpp>
 #include <glm/gtc/quaternion.hpp>
@@ -194,9 +195,16 @@ struct GPUMeshBuffers {
 // push constants for our mesh object draws
 struct GPUDrawPushConstants {
     glm::mat4 worldMatrix;
+    // std140-compatible representation of mat3 (3 x vec4 columns; w unused).
+    glm::mat3x4 normalMatrix;
     VkDeviceAddress vertexBuffer;
     uint32_t objectID;
 };
+static_assert(offsetof(GPUDrawPushConstants, worldMatrix) == 0);
+static_assert(offsetof(GPUDrawPushConstants, normalMatrix) == 64);
+static_assert(offsetof(GPUDrawPushConstants, vertexBuffer) == 112);
+static_assert(offsetof(GPUDrawPushConstants, objectID) == 120);
+static_assert(sizeof(GPUDrawPushConstants) == 128);
 
 struct DrawContext;
 

src/render/passes/geometry.cpp

@@ -281,6 +281,12 @@ void GeometryPass::draw_geometry(VkCommandBuffer cmd,
         }
         GPUDrawPushConstants push_constants{};
         push_constants.worldMatrix = r.transform;
+        {
+            const glm::mat3 n = glm::transpose(glm::inverse(glm::mat3(r.transform)));
+            push_constants.normalMatrix[0] = glm::vec4(n[0], 0.0f);
+            push_constants.normalMatrix[1] = glm::vec4(n[1], 0.0f);
+            push_constants.normalMatrix[2] = glm::vec4(n[2], 0.0f);
+        }
         push_constants.vertexBuffer = r.vertexBufferAddress;
         push_constants.objectID = r.objectID;
 

src/render/passes/shadow.cpp

@@ -19,6 +19,22 @@
 #include "core/types.h"
 #include "core/config.h"
 
+namespace
+{
+struct ShadowPushConstants
+{
+    glm::mat4 render_matrix;
+    VkDeviceAddress vertexBuffer;
+    uint32_t objectID;
+    uint32_t cascadeIndex;
+};
+static_assert(offsetof(ShadowPushConstants, render_matrix) == 0);
+static_assert(offsetof(ShadowPushConstants, vertexBuffer) == 64);
+static_assert(offsetof(ShadowPushConstants, objectID) == 72);
+static_assert(offsetof(ShadowPushConstants, cascadeIndex) == 76);
+static_assert(sizeof(ShadowPushConstants) == 80);
+} // namespace
+
 void ShadowPass::init(EngineContext *context)
 {
     _context = context;
@@ -29,10 +45,7 @@ void ShadowPass::init(EngineContext *context)
     // Keep push constants matching current shader layout for now
     VkPushConstantRange pc{};
     pc.offset = 0;
-    // Push constants layout in shadow.vert is GPUDrawPushConstants + cascade index, rounded to 16 bytes
-    const uint32_t pcRaw = static_cast<uint32_t>(sizeof(GPUDrawPushConstants) + sizeof(uint32_t));
-    const uint32_t pcAligned = (pcRaw + 15u) & ~15u; // 16-byte alignment to match std430 expectations
-    pc.size = pcAligned;
+    pc.size = static_cast<uint32_t>(sizeof(ShadowPushConstants));
     pc.stageFlags = VK_SHADER_STAGE_VERTEX_BIT;
 
     GraphicsPipelineCreateInfo info{};
@@ -180,12 +193,6 @@ void ShadowPass::draw_shadow(VkCommandBuffer cmd,
     const DrawContext &dc = ctxLocal->getMainDrawContext();
 
     VkBuffer lastIndexBuffer = VK_NULL_HANDLE;
-
-    struct ShadowPC
-    {
-        GPUDrawPushConstants draw;
-        uint32_t cascadeIndex;
-    };
     for (const auto &r : dc.OpaqueSurfaces)
     {
         if (r.indexBuffer != lastIndexBuffer)
@@ -194,12 +201,12 @@ void ShadowPass::draw_shadow(VkCommandBuffer cmd,
             vkCmdBindIndexBuffer(cmd, r.indexBuffer, 0, VK_INDEX_TYPE_UINT32);
         }
 
-        ShadowPC spc{};
-        spc.draw.worldMatrix = r.transform;
-        spc.draw.vertexBuffer = r.vertexBufferAddress;
-        spc.draw.objectID = r.objectID;
+        ShadowPushConstants spc{};
+        spc.render_matrix = r.transform;
+        spc.vertexBuffer = r.vertexBufferAddress;
+        spc.objectID = r.objectID;
         spc.cascadeIndex = cascadeIndex;
-        vkCmdPushConstants(cmd, layout, VK_SHADER_STAGE_VERTEX_BIT, 0, sizeof(ShadowPC), &spc);
+        vkCmdPushConstants(cmd, layout, VK_SHADER_STAGE_VERTEX_BIT, 0, sizeof(ShadowPushConstants), &spc);
         vkCmdDrawIndexed(cmd, r.indexCount, 1, r.firstIndex, 0, 0);
     }
 }

src/render/passes/transparent.cpp

@@ -195,6 +195,12 @@ void TransparentPass::draw_transparent(VkCommandBuffer cmd,
         }
         GPUDrawPushConstants push{};
         push.worldMatrix = r.transform;
+        {
+            const glm::mat3 n = glm::transpose(glm::inverse(glm::mat3(r.transform)));
+            push.normalMatrix[0] = glm::vec4(n[0], 0.0f);
+            push.normalMatrix[1] = glm::vec4(n[1], 0.0f);
+            push.normalMatrix[2] = glm::vec4(n[2], 0.0f);
+        }
         push.vertexBuffer = r.vertexBufferAddress;
         push.objectID = r.objectID;
         vkCmdPushConstants(cmd, r.material->pipeline->layout,