Performance improvements: Gate unneeded fields in RenderVertex behind feature flags to reduce memory bandwidth pressure, add ability to bake directional lighting into static objects, RenderOrder re-orders a list of indices rather than the actual triangles, faster AABB culling, manually unrolled loop on ESP32 for SIMD copying. Roughly 30% perf improvement in showcase.

Author: CubeCoders

src/Material.hpp

@@ -38,7 +38,7 @@ class Material {
                                 ///<   biasing the reflection axis upward to align with the true
                                 ///<   waterline. Stored in device-native pixels (no resolution scaling).
                                 ///<   Set via WaterSurface::setReflectionMode(alpha, rippleAmp, yBias).
-    ShadingMode shadingMode = ShadingMode::GOURAUD; ///< Shading model.
+    ShadingMode shadingMode = ShadingMode::FLAT; ///< Shading model.
     char* name;                 ///< Optional name; used for `usemtl` matching in OBJ loading.
 
     /// @brief Construct a material.

src/Object.cpp

@@ -1,4 +1,5 @@
 #include "Object.hpp"
+#include "Light.hpp"
 #include "TrigLUT.hpp"
 #include <cmath>
 
@@ -212,4 +213,68 @@ namespace Renderer
     {
         lookAt(targetObject->position);
     }
+    void Object::bakeFlatLighting(const DirectionalLight* directionalLight,
+                                   const AmbientLight*     ambientLight)
+    {
+        // Ambient components (0 if no ambient light).
+        const uint32_t ambR = ambientLight ? ambientLight->color.r : 0;
+        const uint32_t ambG = ambientLight ? ambientLight->color.g : 0;
+        const uint32_t ambB = ambientLight ? ambientLight->color.b : 0;
+
+        for (auto& tri : triangles) {
+            tri.colorBaked = false;
+            if (!tri.material) continue;
+            if (tri.material->diffuseMap) continue; // textured — skip
+            const ShadingMode mode = tri.material->shadingMode;
+            if (mode != ShadingMode::FLAT &&
+                mode != ShadingMode::GOURAUD &&
+                mode != ShadingMode::UNLIT) continue;
+            if (mode == ShadingMode::UNLIT ||
+                (!directionalLight && !ambientLight)) {
+                // Already emissive / no lights — just stamp the raw colour.
+                tri.bakedColor = tri.material->color;
+                tri.colorBaked = true;
+                continue;
+            }
+
+            // Compute brightness from the face normal (v1 for FLAT/GOURAUD).
+            // Use the same squared-falloff Lambert as jetShadeBrightness.
+            uint32_t brightness = 0;
+            if (directionalLight) {
+                const Vector3& N = vertices[tri.v1].normal;
+                const Vector3& L = directionalLight->worldLightDir;
+                int64_t dot = (int64_t)N.x * L.x + (int64_t)N.y * L.y + (int64_t)N.z * L.z;
+                if (dot > 0) {
+                    uint32_t lambert = (uint32_t)(dot >> 12);
+                    if (lambert > 255) lambert = 255;
+                    lambert = (lambert * lambert + 128) >> 8;  // squared falloff
+                    lambert = (lambert * (uint32_t)directionalLight->intensity) >> 8;
+                    brightness = (lambert * (uint32_t)tri.material->diffuse) >> 8;
+                    const uint32_t maxBrightness = 255u + tri.material->specular;
+                    if (brightness > maxBrightness) brightness = maxBrightness;
+                }
+            }
+
+            // Per-channel modulation (mirrors jetModulateRGB565 in Renderer.cpp).
+            const uint16_t base = tri.material->color;
+            const uint32_t maxBrightness = 255u + tri.material->specular;
+            const uint32_t tR = std::min(brightness + ambR, maxBrightness);
+            const uint32_t tG = std::min(brightness + ambG, maxBrightness);
+            const uint32_t tB = std::min(brightness + ambB, maxBrightness);
+            auto ch5 = [](uint32_t base5, uint32_t t) -> uint32_t {
+                if (t > 255) { const uint32_t blow = t-255; return base5 + ((31u-base5)*blow)/256u; }
+                const uint32_t v = base5 * t; return (v + 128u + (v>>8)) >> 8;
+            };
+            auto ch6 = [](uint32_t base6, uint32_t t) -> uint32_t {
+                if (t > 255) { const uint32_t blow = t-255; return base6 + ((63u-base6)*blow)/256u; }
+                const uint32_t v = base6 * t; return (v + 128u + (v>>8)) >> 8;
+            };
+            const uint32_t r = ch5((base >> 11) & 0x1Fu, tR);
+            const uint32_t g = ch6((base >>  5) & 0x3Fu, tG);
+            const uint32_t b = ch5( base        & 0x1Fu, tB);
+            tri.bakedColor = (uint16_t)((r << 11) | (g << 5) | b);
+            tri.colorBaked = true;
+        }
+    }
+
 } // namespace Renderer

src/Object.hpp

@@ -9,6 +9,9 @@
 
 namespace Renderer {
 
+class DirectionalLight;
+class AmbientLight;
+
 /// @brief Triangle culling mode for an Object.
 enum class CullingMode {
     CULL_BACKFACES,     ///< Cull triangles facing away from the camera.
@@ -33,6 +36,11 @@ class Object {
     struct Triangle {
         uint16_t v1, v2, v3;        ///< Vertex indices.
         Material* material;         ///< Material applied to this face.
+        /// @brief Pre-lit RGB565 colour baked by bakeFlatLighting().
+        /// When `colorBaked` is true this overrides material->color and
+        /// bypasses all per-frame lighting computation for this face.
+        uint16_t bakedColor  = 0;
+        bool     colorBaked  = false;
     };
 
     /// @brief Single mesh vertex.
@@ -239,6 +247,23 @@ class Object {
     /// @param numerator Scale numerator.
     /// @param denominator Scale denominator (must be non-zero).
     void bakeScale(int32_t numerator, int32_t denominator);
+
+    /// @brief Pre-compute FLAT shading into each triangle's `bakedColor` field
+    ///        so that subsequent render() calls cost nothing for lighting.
+    ///
+    /// Only triangles whose material uses `ShadingMode::FLAT` (or UNLIT/GOURAUD
+    /// when `forceFlat` is true) are processed; others are skipped.
+    /// The original material pointers are preserved unchanged — baking does
+    /// not allocate any new Material objects.
+    ///
+    /// After calling this, set `LIGHTING=0` in JetConfig and the scene will
+    /// render at full no-lighting speed while still looking correctly lit.
+    /// If the light or ambient colour changes, call this again to rebuild.
+    ///
+    /// @param directionalLight  Directional light to bake from (may be nullptr).
+    /// @param ambientLight      Ambient light to bake from (may be nullptr).
+    void bakeFlatLighting(const DirectionalLight* directionalLight,
+                          const AmbientLight*     ambientLight);
 private:
 
 };

src/ParticleSystem.hpp

@@ -342,11 +342,10 @@ class ParticleSystem {
 
             // v0 = tip (velocity direction), v1/v2 = base ± perp.
             // noWriteZ so sparks don't occlude each other or later geometry.
-            Object::Vertex v0, v1, v2;
+            RenderVertex v0, v1, v2;
             v0.position = { tx,         ty,         tcZ  };
             v1.position = { bx + perpX, by + perpY, camZ };
             v2.position = { bx - perpX, by - perpY, camZ };
-            v0.color = v1.color = v2.color = mat.color;
 
             raster->drawTriangle(v0, v1, v2, &mat,
                                  nullptr, nullptr,

src/Renderer.cpp

@@ -106,7 +106,19 @@ static inline void fillRGB565Span(uint16_t* framebuffer, int32_t bufferIndex, in
                 : : [v] "r"(color32)
             );
             const int stride = 16;
-            for (int32_t i = 0; i < quads; ++i) {
+            // 4x-unrolled: one loop iteration retires 64 bytes. The asm
+            // blocks are volatile with a memory clobber, so GCC can't
+            // unroll them itself — do it by hand to amortise the branch.
+            for (int32_t i = quads >> 2; i > 0; --i) {
+                __asm__ volatile (
+                    "ee.vst.128.xp q0, %[p], %[s]\n\t"
+                    "ee.vst.128.xp q0, %[p], %[s]\n\t"
+                    "ee.vst.128.xp q0, %[p], %[s]\n\t"
+                    "ee.vst.128.xp q0, %[p], %[s]\n\t"
+                    : [p] "+r"(out) : [s] "r"(stride) : "memory"
+                );
+            }
+            for (int32_t i = quads & 3; i > 0; --i) {
                 __asm__ volatile (
                     "ee.vst.128.xp q0, %[p], %[s]\n\t"
                     : [p] "+r"(out) : [s] "r"(stride) : "memory"
@@ -333,9 +345,9 @@ namespace Renderer
     }
 
     bool PERF_CRITICAL Rasterizer::drawTriangle(
-        const Object::Vertex &v1,
-        const Object::Vertex &v2,
-        const Object::Vertex &v3,
+        const RenderVertex &v1,
+        const RenderVertex &v2,
+        const RenderVertex &v3,
         Material *material,
         DirectionalLight *directionalLight,
         AmbientLight *ambientLight,
@@ -344,7 +356,8 @@ namespace Renderer
         bool noWriteZBuffer,
         int zBias,
         uint8_t objAlpha,
-        bool brightnessPrecomputed)
+        bool brightnessPrecomputed,
+        int32_t avgZHint)
     {
         // Fold per-object fade alpha into the material alpha up front so
         // every downstream alpha decision (early-out, depth fog, stipple
@@ -360,6 +373,8 @@ namespace Renderer
             return false;
         }
 
+        (void)avgZHint; // Only consumed on the FAST_Z && !LAZY_Z path.
+
 #if TEXTURE_MAPPING
         Texture *diffuseMap = material->diffuseMap;
 #endif
@@ -413,14 +428,30 @@ namespace Renderer
 
 #if FAST_Z
 #if LAZY_Z
+        // LAZY_Z needs the max Z, not the average — the caller's avgZ hint
+        // doesn't apply here.
         int32_t z = std::max({v1.position.z, v2.position.z, v3.position.z});
-#else
-        int32_t z = (v1.position.z + v2.position.z + v3.position.z) / 3;
-#endif
         if (z < nearPlane || z > farPlane)
         {
             return false;
         }
+#else
+        int32_t z;
+        if (avgZHint != INT32_MIN)
+        {
+            // Scene::emitTri computed this exact average at queue time and
+            // already culled against near/far — trust it and skip both.
+            z = avgZHint;
+        }
+        else
+        {
+            z = (v1.position.z + v2.position.z + v3.position.z) / 3;
+            if (z < nearPlane || z > farPlane)
+            {
+                return false;
+            }
+        }
+#endif
         #if Z_BUFFERING
         // Z buffer stores raw int32_t z, narrowed to uint16_t. The project's
         // farPlane (~4096) fits comfortably; we clamp to UINT16_MAX so any
@@ -494,7 +525,7 @@ namespace Renderer
                 }
                 else
                 {
-                    const Object::Vertex* verts[3] = { &v1, &v2, &v3 };
+                    const RenderVertex* verts[3] = { &v1, &v2, &v3 };
                     for (int i = 0; i < 3; i++)
                     {
                         vertexBrightness[i] = jetShadeBrightness(
@@ -720,13 +751,18 @@ namespace Renderer
         int32_t oneOverZ2 = (FIXED_POINT_SCALE * FIXED_POINT_SCALE) / v2.position.z;
         int32_t oneOverZ3 = (FIXED_POINT_SCALE * FIXED_POINT_SCALE) / v3.position.z;
 
-        // Precompute u_over_z and v_over_z at each vertex
+#if TEXTURE_MAPPING
+        // Precompute u_over_z and v_over_z at each vertex. Only with
+        // TEXTURE_MAPPING: RenderVertex carries uv only in textured builds.
+        // (PERSPECTIVE_CORRECT_TEXTURES without TEXTURE_MAPPING is still a
+        // valid config — it drives perspective-correct PHONG normals.)
         int32_t uOverZ1 = (v1.uv.x * oneOverZ1) / FIXED_POINT_SCALE;
         int32_t vOverZ1 = (v1.uv.y * oneOverZ1) / FIXED_POINT_SCALE;
         int32_t uOverZ2 = (v2.uv.x * oneOverZ2) / FIXED_POINT_SCALE;
         int32_t vOverZ2 = (v2.uv.y * oneOverZ2) / FIXED_POINT_SCALE;
         int32_t uOverZ3 = (v3.uv.x * oneOverZ3) / FIXED_POINT_SCALE;
         int32_t vOverZ3 = (v3.uv.y * oneOverZ3) / FIXED_POINT_SCALE;
+#endif // TEXTURE_MAPPING
 
 #if LIGHTING
         // Precompute normal_component / z at each vertex so Phong shading
@@ -1033,7 +1069,16 @@ namespace Renderer
                 // across resolutions: 28 → 28 px on 800p desktop,
                 // 28 → ~8 px on 240p ESP32.
                 const int amp    = (int)material->specular * screenHeight / 2400; // /3 of original
-                const int angle  = ((y * 5 + (int)(waterTime * 240.0f)) % 360 + 360) % 360;
+                // Perspective-correct wave density: waves should appear compressed
+                // (denser) near the horizon where geometry is far away, and stretched
+                // (sparser) near the camera.  (screenHeight - y) is large at the top of
+                // the screen (horizon side) and approaches 0 at the very bottom (camera
+                // side), so squaring it produces the right quadratic phase accumulation —
+                // many wave cycles near the waterline, fewer toward the viewer.
+                // Cost: one extra multiply and a divide versus the old linear y*5.
+                const int perspY = screenHeight - y;
+                const int angle  = ((perspY * perspY * 20 / screenHeight + (int)(waterTime * 240.0f)) % 360 + 360) % 360;
+                //const int angle = ((y * 5 + (int)(waterTime * 240.0f)) % 360 + 360) % 360; //MB: This version doesn't take perspective into account, so waves look the same near and far, which is less realistic but more performant.
                 const int ripple = (lookupSinI(angle) * amp) >> 10; // Q10 → pixels
                 // Use the camera-pitch-correct waterline as the mirror axis:
                 // mirrorY = 2*waterlineY - y gives geometrically accurate

src/Renderer.hpp

@@ -24,6 +24,32 @@
 
 namespace Renderer
 {
+/// @brief Slim render-time vertex flowing through the transform → queue →
+/// rasterise pipeline.
+///
+/// `Object::Vertex` is the authoring type: game/mesh code always has uv,
+/// normal, etc. available regardless of build configuration. RenderVertex
+/// is what the per-frame pipeline copies around (Scene's transformed-vertex
+/// scratch, the render queue, the painter's sort) — so it only carries the
+/// fields the configured pipeline actually consumes. With TEXTURE_MAPPING
+/// and LIGHTING both off this is just 12 bytes of position instead of 36,
+/// which roughly 3×'s the per-triangle queue/sort copy traffic savings.
+///
+/// `position` is screen-space x/y with camera-space z after projection.
+struct RenderVertex {
+    Vector3 position = {0, 0, 0};
+#if TEXTURE_MAPPING
+    Vector2 uv = {0, 0};            ///< Texture coordinates.
+#endif
+#if LIGHTING
+    Vector3 normal = {0, 0, 0};     ///< View-space (or mesh-local, see lambertBrightness) normal.
+    /// @brief Precomputed Lambert brightness for the object-local-light
+    /// path (see Scene.cpp "objectLocalLight"). Only meaningful when the
+    /// triangle was queued with brightnessPrecomputed == true.
+    uint16_t lambertBrightness = 0;
+#endif
+};
+
 /// @brief Low-level triangle rasteriser owning a colour and depth buffer.
 ///
 /// Scene drives this class on every render(). External users normally
@@ -145,8 +171,15 @@ class Rasterizer
         /// @param noWriteZBuffer Skip the depth write when true.
         /// @param zBias Per-triangle depth bias in z-buffer units.
         /// @param objAlpha Per-object alpha multiplier (255 = no fade).
+        /// @param brightnessPrecomputed v1/v2/v3.lambertBrightness already holds per-vertex brightness (object-local-light path).
+        /// @param avgZHint Caller-supplied triangle average camera-space Z, or
+        ///        INT32_MIN (default) to compute it here. Scene::rasterizeBand
+        ///        passes the avgZ it already computed (and near/far-culled
+        ///        against) at queue time, so the FAST_Z setup can skip the
+        ///        recompute and the redundant near/far test. Ignored when
+        ///        LAZY_Z is enabled (LAZY_Z needs the max, not the average).
         /// @return True if the triangle produced any rasterizer work.
-        bool drawTriangle(const Object::Vertex &v1, const Object::Vertex &v2, const Object::Vertex &v3, Material *material, DirectionalLight *directionalLight, AmbientLight *ambientLight, bool renderEvenLines, bool ignoreZBuffer, bool noWriteZBuffer, int zBias, uint8_t objAlpha = 255, bool brightnessPrecomputed = false);
+        bool drawTriangle(const RenderVertex &v1, const RenderVertex &v2, const RenderVertex &v3, Material *material, DirectionalLight *directionalLight, AmbientLight *ambientLight, bool renderEvenLines, bool ignoreZBuffer, bool noWriteZBuffer, int zBias, uint8_t objAlpha = 255, bool brightnessPrecomputed = false, int32_t avgZHint = INT32_MIN);
 
         /// @brief Map an 8-bit grayscale value to RGB565.
         /// @param grayscale 8-bit luminance.