perf(terrain): compute draped altitude natively instead of per-frame QueryAltitude

Draped in-world overlays (skill range rings, loot beacons, danger rings,
quest path, rivers, weather) sampled the surface via GW::Map::QueryAltitude
once per plane per vertex every frame. That call swaps the global map
context and walks the terrain heightfield, so a large ring (~1000 verts x N
planes) collapsed the frame rate (#2408).

Read the terrain heightfield directly instead. NativeTerrainZ resolves the
exact surface z at a point from the mapped terrain object (MapContext+0x84):
a 32x32-float-chunk grid, 96-gwinch tiles, Y-flipped, B-C diagonal split.
It is a pure memory read with no game call and no context swap. QueryAltAt
now routes plane 0 (the common case) through it, so every draped consumer
gets the speedup; non-zero planes still use QueryAltitude for the prop-mesh
raycast.

SurfaceZ/DrapeZ no longer scan all planes. They take the native plane-0
surface as the baseline and query only the non-zero planes whose pathing
trapezoid actually contains (x,y), located via a point-location DAG walk.

Verified in-game (map 474, 42 planes): native z matches the client's own
plane-0 value within the expected radius-disk-vs-point delta; the pruned
SurfaceZ is 12.5x faster than the old all-planes loop (21.4 -> 1.7 us/query);
a hovered Sandstorm (312 + 1050 rings) costs ~1 fps instead of collapsing it.

Struct layouts and query math reverse-engineered from the client; see the
harness verbs nativez / drapebench / fpsprobe (Debug-only) used to verify.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013qkJXMrytQ75KYP4o2yZgX

Author: henderkes

GWToolboxdll/Modules/TestHarness.cpp

@@ -1,5 +1,6 @@
 #include "stdafx.h"
 
+#include <chrono>
 #include <cmath>
 #include <filesystem>
 #include <sstream>
@@ -71,6 +72,11 @@ namespace {
     bool log_play_effects = false;
     GW::HookEntry PlayEffect_Entry;
 
+    bool fps_active = false;
+    int fps_frames = 0;
+    clock_t fps_start = 0;
+    long fps_duration_ms = 0;
+
     std::filesystem::path cmd_path() { return Resources::GetPath(L"harness_command.txt"); }
     std::filesystem::path status_path() { return Resources::GetPath(L"harness_status.txt"); }
     std::filesystem::path config_path() { return Resources::GetPath(L"harness_config.txt"); }
@@ -521,6 +527,110 @@ namespace {
             write_status("dattex: queued");
             return;
         }
+        if (verb == "nativez") { // nativez [radius step]: compare native terrain z vs GW::Map::QueryAltitude(plane 0) on a grid
+            float radius = 1200.f, step = 96.f;
+            is >> radius >> step;
+            radius = std::clamp(radius, 100.f, 5000.f);
+            step = std::clamp(step, 24.f, 500.f);
+            const auto self = GW::Agents::GetControlledCharacter();
+            if (!self) { write_status("nativez: no character"); return; }
+            Log::Log("[nativez] map=%d player=(%.0f,%.0f,z%u) radius=%.0f step=%.0f",
+                     static_cast<int>(GW::Map::GetMapID()), self->pos.x, self->pos.y, self->pos.zplane, radius, step);
+            uint32_t samples = 0, both = 0, logged = 0;
+            float max_delta = 0.f;
+            double sum_delta = 0.0;
+            for (float dx = -radius; dx <= radius; dx += step) {
+                for (float dy = -radius; dy <= radius; dy += step) {
+                    const float x = self->pos.x + dx, y = self->pos.y + dy;
+                    const float native = TerrainDrape::NativeTerrainZ(x, y);
+                    GW::GamePos p(x, y, 0);
+                    const float game = GW::Map::QueryAltitude(&p);
+                    ++samples;
+                    if (native == 0.f || game == 0.f) continue; // OOB on either side
+                    ++both;
+                    const float d = std::fabs(native - game);
+                    max_delta = std::max(max_delta, d);
+                    sum_delta += d;
+                    if (d > 5.f && logged++ < 20)
+                        Log::Log("[nativez]   (%.0f,%.0f) native=%.1f game=%.1f delta=%.1f", x, y, native, game, d);
+                }
+            }
+            char b[160];
+            snprintf(b, sizeof(b), "nativez: samples=%u both=%u max_delta=%.2f avg_delta=%.3f", samples, both, max_delta,
+                     both ? sum_delta / both : 0.0);
+            Log::Log("[harness] %s", b);
+            Log::FlushFile();
+            write_status(b);
+            return;
+        }
+        if (verb == "drapebench") { // drapebench [n radius]: A/B the old all-planes QueryAltitude loop vs the new pruned SurfaceZ
+            uint32_t n = 2000;
+            float radius = 1200.f;
+            is >> n >> radius;
+            n = std::clamp(n, 100u, 200000u);
+            radius = std::clamp(radius, 100.f, 5000.f);
+            const auto self = GW::Agents::GetControlledCharacter();
+            const auto* pm = GW::Map::GetPathingMap();
+            if (!self || !pm || !pm->size()) {
+                write_status("drapebench: no character or pathing map");
+                return;
+            }
+            const auto n_planes = static_cast<uint32_t>(pm->size());
+            // Same pseudo-random disk of sample points for both methods.
+            std::vector<std::pair<float, float>> pts(n);
+            uint32_t seed = 0x9E3779B9u;
+            const auto next01 = [&seed] {
+                seed = seed * 1664525u + 1013904223u;
+                return (seed >> 8) * (1.f / 16777216.f);
+            };
+            for (uint32_t i = 0; i < n; ++i) {
+                const float ang = next01() * 6.2831853f, r = radius * std::sqrt(next01());
+                pts[i] = {self->pos.x + std::cos(ang) * r, self->pos.y + std::sin(ang) * r};
+            }
+
+            // OLD path: QueryAltitude on every plane, keep highest surface (min z). This is what SurfaceZ did before.
+            float sink_old = 0.f;
+            const auto t_old0 = std::chrono::steady_clock::now();
+            for (uint32_t i = 0; i < n; ++i) {
+                float best = 0.f;
+                for (uint32_t zp = 0; zp < n_planes; ++zp) {
+                    GW::GamePos p(pts[i].first, pts[i].second, zp);
+                    const float a = GW::Map::QueryAltitude(&p);
+                    if (a != 0.f && (best == 0.f || a < best)) best = a;
+                }
+                sink_old += best;
+            }
+            const auto us_old = std::chrono::duration_cast<std::chrono::microseconds>(std::chrono::steady_clock::now() - t_old0).count();
+
+            // NEW path: native plane-0 read + trapezoid-pruned non-zero planes.
+            float sink_new = 0.f;
+            const auto t_new0 = std::chrono::steady_clock::now();
+            for (uint32_t i = 0; i < n; ++i)
+                sink_new += TerrainDrape::SurfaceZ(pts[i].first, pts[i].second, self->pos.zplane, n_planes);
+            const auto us_new = std::chrono::duration_cast<std::chrono::microseconds>(std::chrono::steady_clock::now() - t_new0).count();
+
+            char b[220];
+            snprintf(b, sizeof(b),
+                     "drapebench: n=%u planes=%u | OLD %.2fms (%.2fus/q) | NEW %.2fms (%.2fus/q) | speedup %.1fx | sink d=%.0f",
+                     n, n_planes, us_old / 1000.0, static_cast<double>(us_old) / n, us_new / 1000.0,
+                     static_cast<double>(us_new) / n, us_new ? static_cast<double>(us_old) / us_new : 0.0,
+                     std::fabs(sink_old - sink_new));
+            Log::Log("[harness] %s", b);
+            Log::FlushFile();
+            write_status(b);
+            return;
+        }
+        if (verb == "fpsprobe") { // fpsprobe [seconds]: count frames over a window, report avg fps
+            float seconds = 3.f;
+            is >> seconds;
+            seconds = std::clamp(seconds, 0.5f, 30.f);
+            fps_duration_ms = static_cast<long>(seconds * 1000.f);
+            fps_frames = 0;
+            fps_start = TIMER_INIT();
+            fps_active = true;
+            write_status("fpsprobe: running");
+            return;
+        }
         write_status("unknown_command: " + verb);
     }
 } // namespace
@@ -555,6 +665,18 @@ void TestHarness::Update(float)
 {
 #ifdef HARNESS_ENABLED
     if (terminating) return;
+    if (fps_active) {
+        ++fps_frames;
+        const long elapsed = TIMER_DIFF(fps_start);
+        if (elapsed >= fps_duration_ms) {
+            fps_active = false;
+            char b[96];
+            snprintf(b, sizeof(b), "fpsprobe: frames=%d secs=%.2f avg_fps=%.1f", fps_frames, elapsed / 1000.f, fps_frames * 1000.f / elapsed);
+            Log::Log("[harness] %s", b);
+            Log::FlushFile();
+            write_status(b);
+        }
+    }
     if (last_poll && TIMER_DIFF(last_poll) < kPollMs) return;
     last_poll = TIMER_INIT();
 

GWToolboxdll/Utils/TerrainDrape.cpp

@@ -1,38 +1,204 @@
 #include "stdafx.h"
 
+#include <cfloat>
+#include <cmath>
+#include <cstddef>
+
 #include <GWCA/GameContainers/GamePos.h>
 #include <GWCA/GameEntities/Pathing.h>
+#include <GWCA/Context/MapContext.h>
 #include <GWCA/Managers/MapMgr.h>
 
 #include <Utils/TerrainDrape.h>
 
+namespace {
+    // GW's terrain heightfield object (MapContext+0x84). Only the fields the altitude sampler touches
+    // are named; layout reverse-engineered from Terrain_QueryAltitude (Gw.exe FUN_0074eb10). See
+    // memory reference-gw-terrain-altitude-internals for the full derivation.
+    struct GwTerrain {
+        uint32_t type;           // +0x00
+        uint32_t dim_x;          // +0x04 tiles in x (multiple of 32)
+        uint32_t dim_y;          // +0x08 tiles in y
+        uint32_t chunks_x;       // +0x0C dim_x >> 5
+        uint32_t chunks_y;       // +0x10 dim_y >> 5
+        uint32_t flags;          // +0x14 bit0: clamp z>0 result to 0
+        float min_x;             // +0x18
+        float min_y;             // +0x1C
+        float max_x;             // +0x20
+        float max_y;             // +0x24 grid anchored at (min_x, max_y)
+        uint32_t pad0[2];        // +0x28
+        uint32_t grid_dim_x;     // +0x30
+        uint32_t grid_dim_y;     // +0x34
+        uint32_t chunks_per_row; // +0x38 (dim_x >> 5) + 1  (the +1 is a border chunk column)
+        uint32_t chunk_rows;     // +0x3C (dim_y >> 5) + 1
+        float** chunk_ptrs;      // +0x40 chunks_per_row * chunk_rows entries -> 32x32 float32
+        uint32_t chunk_count;    // +0x44
+        uint32_t chunk_capacity; // +0x48
+    };
+    static_assert(offsetof(GwTerrain, dim_x) == 0x04);
+    static_assert(offsetof(GwTerrain, flags) == 0x14);
+    static_assert(offsetof(GwTerrain, min_x) == 0x18);
+    static_assert(offsetof(GwTerrain, max_y) == 0x24);
+    static_assert(offsetof(GwTerrain, chunks_per_row) == 0x38);
+    static_assert(offsetof(GwTerrain, chunk_ptrs) == 0x40);
+    static_assert(offsetof(GwTerrain, chunk_capacity) == 0x48);
+
+    constexpr float kTile = 96.0f;
+    constexpr float kNoData = FLT_MAX; // internal "no surface" sentinel; mapped to GW's 0.f at the API edge
+
+    const GwTerrain* GetTerrain()
+    {
+        const GW::MapContext* mc = GW::GetMapContext();
+        if (!mc || !mc->terrain) return nullptr;
+        const auto* t = static_cast<const GwTerrain*>(mc->terrain);
+        // Cheap sanity gate against a torn-down / mid-load terrain object.
+        if (t->dim_x == 0 || t->dim_x > 0x8000 || t->dim_y == 0 || t->dim_y > 0x8000) return nullptr;
+        if (t->chunks_per_row == 0 || !t->chunk_ptrs) return nullptr;
+        return t;
+    }
+
+    float SampleGrid(const GwTerrain* t, const uint32_t gx, const uint32_t gy)
+    {
+        const uint32_t ci = (gy >> 5) * t->chunks_per_row + (gx >> 5);
+        if (ci >= t->chunk_capacity) return kNoData;
+        const float* chunk = t->chunk_ptrs[ci];
+        if (!chunk) return kNoData;
+        return chunk[(gy & 31) * 32 + (gx & 31)];
+    }
+
+    // cross2d(P,A,B) = (P.y-A.y)(B.x-A.x) - (P.x-A.x)(B.y-A.y); the exact side test GW uses (FUN_007294e0).
+    float Cross2D(const float px, const float py, const float ax, const float ay, const float bx, const float by)
+    {
+        return (py - ay) * (bx - ax) - (px - ax) * (by - ay);
+    }
+
+    // GW's strict point-in-trapezoid test (FUN_0072b680): y-band open, left edge >= 0, right edge <= 0.
+    bool TrapezoidContains(const GW::PathingTrapezoid* pt, const float x, const float y)
+    {
+        if (!(pt->YB < y && y < pt->YT)) return false;
+        if (Cross2D(x, y, pt->XTL, pt->YT, pt->XBL, pt->YB) < 0.f) return false;
+        if (Cross2D(x, y, pt->XTR, pt->YT, pt->XBR, pt->YB) > 0.f) return false;
+        return true;
+    }
+
+    // Walk one plane's point-location DAG (root at PathingMap::root_node) to the containing trapezoid.
+    // Returns true iff a real trapezoid of this plane covers (x,y). Mirrors GW's exact locator
+    // (FUN_0072aa80); the toolbox's older Pathing::FindTrapezoid has an inverted entry guard, so this is
+    // implemented fresh rather than reused.
+    bool PlaneContains(const GW::PathingMap& pm, const float x, const float y)
+    {
+        const GW::Node* n = pm.root_node;
+        int guard = 100000;
+        while (n && guard-- > 0) {
+            switch (n->type) {
+                case 0: { // XNode
+                    const auto* xn = static_cast<const GW::XNode*>(n);
+                    const float d = (y - xn->pos.y) * xn->dir.x - (x - xn->pos.x) * xn->dir.y;
+                    n = d >= 0.f ? xn->right : xn->left;
+                    break;
+                }
+                case 1: { // YNode
+                    const auto* yn = static_cast<const GW::YNode*>(n);
+                    n = (y > yn->pos.y) ? yn->above
+                        : (y < yn->pos.y) ? yn->below
+                        : (x >= yn->pos.x) ? yn->above : yn->below;
+                    break;
+                }
+                case 2: { // SinkNode -- the leaf's trapezoid contains (x,y) only if the point is really on it
+                    const auto* sn = static_cast<const GW::SinkNode*>(n);
+                    return sn->trapezoid && TrapezoidContains(sn->trapezoid, x, y);
+                }
+                default:
+                    return false;
+            }
+        }
+        return false;
+    }
+}
+
+float TerrainDrape::NativeTerrainZ(const float x, const float y)
+{
+    const GwTerrain* t = GetTerrain();
+    if (!t) return 0.f;
+
+    const float gxf = (x - t->min_x) / kTile;
+    const float gyf = (t->max_y - y) / kTile; // grid rows grow toward -y
+    if (gxf < 0.f || gyf < 0.f) return 0.f;
+
+    const auto gxi = static_cast<uint32_t>(gxf);
+    const auto gyi = static_cast<uint32_t>(gyf);
+    if (gxi >= t->dim_x || gyi >= t->dim_y) return 0.f; // gxi+1 <= dim_x reads the border chunk column
+
+    const float fx = gxf - static_cast<float>(gxi);
+    const float fy = gyf - static_cast<float>(gyi);
+
+    const float zA = SampleGrid(t, gxi, gyi);
+    const float zB = SampleGrid(t, gxi + 1, gyi);
+    const float zC = SampleGrid(t, gxi, gyi + 1);
+    const float zD = SampleGrid(t, gxi + 1, gyi + 1);
+    if (zA == kNoData || zB == kNoData || zC == kNoData || zD == kNoData) return 0.f;
+
+    // Cell is split on the B-C diagonal (fx+fy==1), matching the game's triangulation.
+    float z;
+    if (fx + fy <= 1.f)
+        z = zA + fx * (zB - zA) + fy * (zC - zA);
+    else
+        z = zB + (fx + fy - 1.f) * (zD - zB) + (1.f - fx) * (zC - zB);
+
+    if ((t->flags & 1u) && z > 0.f) z = 0.f; // GW clamps below-zero-plane surfaces
+    return z;
+}
+
 float TerrainDrape::QueryAltAt(const float x, const float y, const uint32_t zplane)
 {
+    if (zplane == 0)
+        return NativeTerrainZ(x, y);
     GW::GamePos p{x, y, zplane};
     return GW::Map::QueryAltitude(&p);
 }
 
 float TerrainDrape::DrapeZ(const float x, const float y, const uint32_t zplane, const uint32_t n_planes, const float ref)
 {
     float best = ref, best_d = FLT_MAX;
-    for (uint32_t zp = 0; zp < n_planes; ++zp) {
-        const float a = QueryAltAt(x, y, zp);
-        if (a == 0.f) continue;
-        const float d = std::fabs(a - ref);
-        if (d < best_d || (d == best_d && zp == zplane)) {
-            best_d = d;
-            best = a;
+
+    const float ground = NativeTerrainZ(x, y);
+    if (ground != 0.f) {
+        best_d = std::fabs(ground - ref);
+        best = ground;
+    }
+
+    const GW::PathingMapArray* pm = GW::Map::GetPathingMap();
+    if (pm) {
+        const auto planes = std::min<uint32_t>(n_planes, static_cast<uint32_t>(pm->size()));
+        for (uint32_t zp = 1; zp < planes; ++zp) {
+            if (!PlaneContains((*pm)[zp], x, y)) continue;
+            const float a = QueryAltAt(x, y, zp);
+            if (a == 0.f) continue;
+            const float d = std::fabs(a - ref);
+            if (d < best_d || (d == best_d && zp == zplane)) {
+                best_d = d;
+                best = a;
+            }
         }
     }
     return best;
 }
 
 float TerrainDrape::SurfaceZ(const float x, const float y, const uint32_t, const uint32_t n_planes)
 {
-    float best = 0.f;
-    for (uint32_t zp = 0; zp < n_planes; ++zp) {
-        const float a = QueryAltAt(x, y, zp);
-        if (a != 0.f && (best == 0.f || a < best)) best = a;
+    // Highest surface = min z. Plane-0 ground is a native read; only planes whose trapezoid actually
+    // covers (x,y) can add a higher (bridge/prop) surface, so the old blind all-planes loop is pruned
+    // to those candidates.
+    float best = NativeTerrainZ(x, y); // 0.f when off-terrain
+
+    const GW::PathingMapArray* pm = GW::Map::GetPathingMap();
+    if (pm) {
+        const auto planes = std::min<uint32_t>(n_planes, static_cast<uint32_t>(pm->size()));
+        for (uint32_t zp = 1; zp < planes; ++zp) {
+            if (!PlaneContains((*pm)[zp], x, y)) continue;
+            const float a = QueryAltAt(x, y, zp);
+            if (a != 0.f && (best == 0.f || a < best)) best = a;
+        }
     }
     return best;
 }

GWToolboxdll/Utils/TerrainDrape.h

@@ -3,9 +3,18 @@
 #include <cstdint>
 
 // Surface-draping helpers shared by the in-world overlay modules (danger rings, loot beacons,
-// skill range rings). QueryAltitude swaps the global map context, so call these ONLY on the
-// render thread. GW's "no altitude data" sentinel is 0.f, and up is -z (highest surface = min z).
+// skill range rings). GW's "no altitude data" sentinel is 0.f, and up is -z (highest surface = min z).
+//
+// Plane 0 (the terrain heightfield) is read directly from the mapped terrain object -- no game call,
+// no map-context swap -- so it is safe from any thread and cheap enough to sample per vertex per frame.
+// Non-zero planes (bridges/prop surfaces) still route through GW::Map::QueryAltitude, which swaps the
+// global map context, so the DrapeZ/SurfaceZ helpers must run ONLY on the render thread. They prune the
+// old all-planes loop to just the planes whose pathing trapezoid actually contains (x,y).
 namespace TerrainDrape {
+    // Exact terrain surface z at (x,y) on plane 0, interpolated from the heightfield. Returns 0.f when
+    // (x,y) is outside the terrain or the map is not loaded (matching GW's OOB sentinel). Native read.
+    float NativeTerrainZ(float x, float y);
+
     float QueryAltAt(float x, float y, uint32_t zplane);
 
     // Surface altitude at (x,y), choosing the plane closest to `ref`.