cvcGL: fast-draw low-memory mapper (~2/3 fewer GL calls per frame on WebGL2) + reship cvc.16

CMakeLists.txt

@@ -390,7 +390,7 @@ if(CVC_BUILD_PYCVC)
 endif()
 
 # ************* Install documentation & resources *************
-install(FILES README.md USAGE.md LICENSE
+install(FILES README.md USAGE.md LICENSE THIRD_PARTY_NOTICES.md
   DESTINATION ${CMAKE_INSTALL_DOCDIR}
   COMPONENT libcvc)
 

README.md

@@ -705,6 +705,15 @@ libcvc is licensed under the **GNU Lesser General Public License, version 2.1**
 The bundled XmlRpc++ sources under `inc/xmlrpc/` and `src/xmlrpc/` are
 Copyright (c) 2002-2003 Chris Morley and are used under LGPL-2.1-or-later.
 
+Portions of `src/cvcGL/LowMemoryPolyDataMapper.cpp` are derived from VTK 9.5.0,
+Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen, and are used under the
+BSD-3-Clause license. That and the other third-party code in, or compiled into,
+libcvc and cvcGL -- stb_image, PocketFFT, the contour library, kazlib, sdf,
+mtxlib, the DTU `.vtk` reader, VTK's marching-cubes table, the ABYSSAL ocean
+port in the cvcGL examples, and the vendored CMake modules -- are listed with
+their notices in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md), which is
+installed with the documentation.
+
 ## Credits
 
 Based on research and software developed at the **Computational Visualization Center, University of Texas at Austin**.

cvcpkg/recipes/cvcgl-cuda/recipe.yaml

@@ -5,13 +5,18 @@ recipe:
   # Reset to 1 for the 3.3.0 upstream version: cvc_revision counts
   # revisions OF an upstream version, so a version bump restarts it.
   # Bumped 1 -> 3 (2 is #522's): ships share/cvcGL/ (the wasm state shim), as cvcgl 3.4.0+cvc.18.
-  cvc_revision: 3
+  # Bumped 3 -> 4 (3 is master's wasm app contract above, and the 2 set aside for this change
+  # sits below it; none published yet): carries cvcGL's fast-draw low-memory mapper and the
+  # BSD-3-Clause license metadata for its VTK 9.5.0-derived code (same as cvcgl 3.4.0+cvc.19).
+  cvc_revision: 4
   maintainer: "cvcpkg group"
   maintainer_email: "info@cvcpkg.org"
   maintainer_url: "https://cvcpkg.org"
   description: "cvcGL (CUDA/GPU build) — the Qt-free VTK scene-graph library built against the CUDA libcvc-cuda SDK, so its GPU-only code paths (GL <-> CUDA interop: mapping a volume's CUDA unified/device buffer into a GL 3D texture for on-device volume rendering) compile in. Same cmake package (cvc::cvcGL) and same API as the CPU `cvcgl` package."
   homepage: https://github.com/transfix/libcvc
-  license: LGPL-2.1-only
+  # BSD-3-Clause: libcvcGL carries code derived from VTK 9.5.0
+  # (LowMemoryPolyDataMapper.cpp); THIRD_PARTY_NOTICES.md ships in share/doc/cvcGL.
+  license: "LGPL-2.1-only AND BSD-3-Clause"
   tags: [scientific, volumetric, scene, vtk, graphics, cuda, gpu]
 
 # The GPU build of cvcGL — identical sources to the CPU `cvcgl` recipe, built

cvcpkg/recipes/cvcgl-examples/build-wasm.sh

@@ -75,3 +75,8 @@ python3 "$CVC_SOURCE_DIR/src/cvcGL/examples/wasm/build-pages.py" \
     --bin "$CVC_BUILD_DIR/bin" \
     --out "$WEB" \
     --assets "$CVC_SOURCE_DIR/src/cvcGL/examples/wasm/gallery-assets"
+# The .wasm files embed third-party code (VTK-derived code in cvcGL, BSD-3-Clause;
+# stb, sdf / mtxlib and the DTU .vtk reader in the cvc core) whose notices a binary
+# redistribution must reproduce: ship them, and the LICENSE they link to, beside
+# the gallery.
+install -m 644 "$CVC_SOURCE_DIR/THIRD_PARTY_NOTICES.md" "$CVC_SOURCE_DIR/LICENSE" "$WEB/"

cvcpkg/recipes/cvcgl-examples/recipe.yaml

@@ -18,13 +18,22 @@ recipe:
   # CVC_STATE_EXEC option is gone; state_exec is always built), so the wasm
   # gallery carries the program lanes that Ariadne apps run on.
   # Bumped 3 -> 17 (15 published, 16 is #522's): every wasm demo is a cvcgl_wasm_app; ships glsync.
-  cvc_revision: 17
+  # Bumped 17 -> 18 (15 went out as a native publish, 17 is master's wasm app contract above, and
+  # the 16 set aside for this change sits below it; revisions stay monotonic across platforms):
+  # ships THIRD_PARTY_NOTICES.md + LICENSE (native share/cvcgl-examples/ and the wasm web/
+  # payload), declares LGPL-2.1-only AND BSD-3-Clause AND MIT, and rebuilds the demos against
+  # cvcgl 3.4.0+cvc.19 (fast-draw low-memory mapper).
+  cvc_revision: 18
   maintainer: "cvcpkg group"
   maintainer_email: "info@cvcpkg.org"
   maintainer_url: "https://cvcpkg.org"
   description: "cvcGL example programs as ready-to-run commands: the GRL-SNAM navigation demos (nav_city_swarm / nav_city_drive / nav_fog_ghost / nav_finale — the torch-free cvc::nav reactive swarm rendered natively) plus terrain_lab, as native binaries in bin/, AND the full navigation gallery as a threaded (wasm-mt) WebAssembly browser build (share/cvcgl-examples/web/) with a cvcgl-examples-web launcher that serves it cross-origin-isolated (COOP/COEP) and opens a browser."
   homepage: https://github.com/transfix/libcvc
-  license: LGPL-2.1-only
+  # BSD-3-Clause: the demos link cvcGL statically, which carries code derived
+  # from VTK 9.5.0. MIT: lsystem_coast's OceanFFT is a port of ABYSSAL. Both
+  # notices are in THIRD_PARTY_NOTICES.md, shipped in share/cvcgl-examples/ (and
+  # share/cvcgl-examples/web/ for the browser build).
+  license: "LGPL-2.1-only AND BSD-3-Clause AND MIT"
   tags: [scientific, graphics, examples, vtk, wasm]
 
 # The examples are demos of cvcGL-as-a-toolkit, packaged separately from the

cvcpkg/recipes/cvcgl/recipe.yaml

@@ -70,13 +70,22 @@ recipe:
   # scene-bounds walk deferred under hidden chrome. ABI-stale: SceneGraph/GraphicsNode/
   # NullGraphicNode layouts changed, so the published +cvc.14 must not be mixed with this build.
   # Bumped 15 -> 18 (16 published, 17 is #522's): cvcgl_wasm_app(), the WebGL state shim, FrameYield.
-  cvc_revision: 18
+  # Bumped 18 -> 19 (16 went out as a native publish of master without this, 18 is master's wasm
+  # app contract above, and the 17 set aside for this change sits below it): the fast-draw
+  # low-memory mapper (LowMemoryPolyDataMapper: skips empty cell-type agents and re-binds the
+  # cached shader program; ~2/3 fewer GL calls per frame on WebGL2 with byte-identical pixels;
+  # CVCGL_LOWMEM_DRAW / setDrawPath for A/B), now the base of StreamingLowMemoryPolyDataMapper;
+  # late shader replacements reach the GPU on the low-memory path. License metadata now
+  # LGPL-2.1-only AND BSD-3-Clause (VTK 9.5.0-derived code).
+  cvc_revision: 19
   maintainer: "cvcpkg group"
   maintainer_email: "info@cvcpkg.org"
   maintainer_url: "https://cvcpkg.org"
   description: "cvcGL — the Qt-free VTK scene-graph library extracted from volrover3: a reactive SceneGraph of GraphicsNode/GeometryNode/VolumeNode over cvc::state that renders cvc::geometry / cvc::volume via VTK. Ships libcvcGL.a + headers + a cmake package config; provides the cvcGL cmake package (cvc::cvcGL target). Consumed by pycvc-gl and other non-Qt scene consumers."
   homepage: https://github.com/transfix/libcvc
-  license: LGPL-2.1-only
+  # BSD-3-Clause: libcvcGL carries code derived from VTK 9.5.0
+  # (LowMemoryPolyDataMapper.cpp); THIRD_PARTY_NOTICES.md ships in share/doc/cvcGL.
+  license: "LGPL-2.1-only AND BSD-3-Clause"
   tags: [scientific, volumetric, scene, vtk, graphics]
 
 # cvcGL is its OWN package, separate from libcvc: a plain libcvc bundle is a

cvcpkg/recipes/libcvc/recipe.yaml

@@ -134,7 +134,12 @@ recipe:
   # caster-aware shadow baking, the cheaper bounds walk). ABI: SceneGraph, GraphicsNode and
   # NullGraphicNode layouts changed (#512 and the frame-cost fixes) with the SOVERSION
   # unchanged, so dependents must rebuild. cvcgl bumps in lockstep (14 -> 15).
-  cvc_revision: 15
+  # Bumped 15 -> 17 (16 went out as a native publish of master without this):
+  # lockstep with cvcgl's fast-draw low-memory mapper
+  # (LowMemoryPolyDataMapper, ~2/3 fewer GL calls per frame on WebGL2) and the expanded
+  # THIRD_PARTY_NOTICES.md. libcvc's own sources are unchanged by it; the bump keeps the pair's
+  # revisions aligned for consumers that pin both.
+  cvc_revision: 17
   maintainer: "cvcpkg group"
   maintainer_email: "info@cvcpkg.org"
   maintainer_url: "https://cvcpkg.org"

inc/cvc/gl/LowMemoryPolyDataMapper.h

@@ -0,0 +1,220 @@
+/*
+  Copyright 2026 The University of Texas at Austin
+
+  This file is part of libcvc.
+
+  libcvc is free software; you can redistribute it and/or
+  modify it under the terms of the GNU Lesser General Public
+  License version 2.1 as published by the Free Software Foundation.
+
+  libcvc is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public
+  License along with this library; if not, write to the Free Software
+  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+*/
+
+// LowMemoryPolyDataMapper -- VTK 9.5.0's low-memory (GLES3/WebGL2) poly-data
+// mapper with two pixel-identical cuts to its per-draw cost.
+//
+// On GLES3/WebGL2 VTK's object factory hands every vtkPolyDataMapper::New() a
+// vtkOpenGLLowMemoryPolyDataMapper. Its draw runs four cell-type "agents" in a
+// row (verts, lines, polys, strips), and each one does the full shader setup
+// whether or not it has anything to draw: every array texture re-bound, every
+// camera, material, shadow and agent uniform re-sent, the VAO bound and
+// unbound. A typical mesh has one cell type, so three quarters of that is
+// thrown away -- about 110 of the ~160 GL calls a lit mesh costs per draw. On
+// top of that, every draw re-resolves its shader program through the shader
+// cache: five source copies, re-substitution and an MD5 of ~16 KB, to find the
+// program it already has.
+//
+// This subclass:
+//   1. skips the cell types that draw nothing (a cell type draws iff its first
+//      cell group can render, exactly the condition VTK's agent tests), and
+//   2. re-binds the program it resolved last time while the shader has not been
+//      rebuilt since (same ShaderBuildTimeStamp, same render window shader cache)
+//      instead of looking it up again.
+// Nothing else changes: the drawn cell type gets the same uniforms, textures and
+// draw call in the same order, so frames are byte-identical (the cvcgl_lowmem_
+// fastdraw test pins that, and pins the replica against VTK call-for-call).
+//
+// The cell-type agents are VTK private classes (headers not installed, symbols
+// hidden), so the drawn agent's PreDraw/Draw/PostDraw is replicated here from
+// VTK 9.5.0 (BSD-3-Clause; the notice is in LowMemoryPolyDataMapper.cpp and
+// THIRD_PARTY_NOTICES.md). Picking, vertex visibility and a coincident-offset
+// layout where skipping a cell type would change the depth offset a drawn one
+// sees all take the stock (all four agents) draw.
+//
+// The replica is active (replicaActive()) only against an UNPATCHED VTK 9.5.0.
+// The version macros alone cannot tell a patched 9.5.0 from a pristine one, so:
+//   * Contract for the libcvc-deps VTK recipe: any patch that touches the
+//     Rendering/OpenGL2 low-memory mapper, its cell-type agents,
+//     vtkDrawTexturedElements or the GLSL mods must also add
+//         #define VTK_CVC_LOWMEM_PATCHLEVEL <n>   // n >= 1
+//     to the installed vtkOpenGLLowMemoryPolyDataMapper.h. The replica turns
+//     itself off whenever that macro is defined (every DrawPath is then the
+//     stock draw) until it is re-validated against the patched code and taught
+//     that patch level.
+//   * At configure time cvcGL also hashes the installed
+//     vtkOpenGLLowMemoryPolyDataMapper.h, vtkDrawTexturedElements.h and
+//     vtkGLSLModCoincidentTopology.h against pristine 9.5.0 and builds the
+//     replica off (CVC_GL_LOWMEM_REPLICA_DISABLED) if any of them differs.
+// cvcgl_lowmem_fastdraw pins the replica against the stock draw call for call,
+// so it is the gate for any VTK recipe change.
+//
+// VTK v9.7.0 (tagged 2026-08-14) is NOT a drop-in replacement. It carries
+// upstream f59c2d0b297 (vtkDrawTexturedElements re-binds its cached program
+// unless GetShader() was called -- this class's cut 2) and 15ed6edc478
+// (per-program uniform-location and last-value caches in vtkShaderProgram, the
+// GLSL mods and the low-memory mapper), but it still runs all four cell-type
+// agents per draw. A VTK upgrade switches the replica off (version check), so
+// the empty-agent skip (cut 1) must be re-ported against 9.7's agents or that
+// saving is lost. 9.7.0 also contains d1cde2af1a8, which makes every
+// vtkOpenGLState::vtkglBlitFramebuffer issue two glCheckFramebufferStatus calls
+// first -- at a cvcGL frame's two blits, 4 synchronous round trips per frame on
+// WebGL; revert or avoid it in the wasm VTK build.
+//
+// The shader-cache skip (cut 2) relies on one invariant: this->Shaders (the
+// vtkShader sources vtkDrawTexturedElements resolves its program from) changes
+// only inside UpdateShaders, and RenderPieceStart always follows UpdateShaders
+// with ShaderBuildTimeStamp.Modified(). vtkDrawTexturedElements::GetShader() is
+// public and hands out a mutable vtkShader, so this class hides it with a
+// version that drops the cached program first (as upstream f59c2d0b297 does);
+// anything that edits shader sources by another route must call
+// invalidateProgramCache(). Nothing in cvcGL edits them outside
+// UpdateShaders today.
+//
+// For every VTK version, RenderPieceStart also rebuilds the shader program when
+// the actor's shader property (replacements, custom uniform declarations)
+// changed after the program was built: VTK's low-memory mapper (9.5 through
+// 9.7) ignores the shader property once its program exists, so a
+// GeometryNode::add*ShaderReplacement made after the first draw would never
+// reach the GPU on WebGL.
+//
+// It also zero-initialises the shift/scale members VTK 9.5.0 leaves
+// uninitialised (with DISABLE_SHIFT_SCALE nothing ever assigns them, so a
+// garbage "in use" byte made the mapper upload a shift/scale copy of the
+// positions).
+#ifndef CVC_GL_LOW_MEMORY_POLY_DATA_MAPPER_H
+#define CVC_GL_LOW_MEMORY_POLY_DATA_MAPPER_H
+
+#include <cstdint>
+#include <vtkOpenGLLowMemoryPolyDataMapper.h>
+#include <vtkOpenGLShaderCache.h>
+#include <vtkShader.h>
+#include <vtkSmartPointer.h>
+#include <vtkWeakPointer.h>
+
+namespace cvc {
+namespace gl {
+
+class LowMemoryPolyDataMapper : public vtkOpenGLLowMemoryPolyDataMapper {
+public:
+  static LowMemoryPolyDataMapper *New();
+  vtkTypeMacro(LowMemoryPolyDataMapper, vtkOpenGLLowMemoryPolyDataMapper);
+
+  // How every LowMemoryPolyDataMapper in the process draws. The initial value
+  // comes from CVCGL_LOWMEM_DRAW (stock | all | fast, default fast); the other
+  // two paths exist for A/B measurement and for the tests:
+  //   Stock         VTK's own RenderPieceDraw (all four agents, full lookup).
+  //   AllCellTypes  the replica with nothing skipped -- issues the same GL calls
+  //                 as Stock, call for call.
+  //   Fast          the replica, empty cell types skipped, program re-bound.
+  enum class DrawPath : int { Stock = 0, AllCellTypes = 1, Fast = 2 };
+  static void setDrawPath(DrawPath path);
+  static DrawPath drawPath();
+
+  // True when this build carries the VTK 9.5.0 replica (an unpatched 9.5.0, see
+  // above). False means every path is the stock draw.
+  static bool replicaActive();
+
+  // Per-mapper counters, read and reset on the render thread.
+  struct Stats {
+    std::uint64_t draws = 0;                 // RenderPieceDraw calls
+    std::uint64_t stockDraws = 0;            //   of which drew through VTK's own path
+    std::uint64_t cellTypesSkipped = 0;      // agents not run because they draw nothing
+    std::uint64_t coincidentFallbacks = 0;   // draws that ran all four for the depth offset
+    std::uint64_t programLookups = 0;        // full shader-cache lookups (copy + MD5)
+    std::uint64_t programLookupsSkipped = 0; // cached program re-bound instead
+  };
+  const Stats &stats() const { return m_stats; }
+  void resetStats() { m_stats = Stats{}; }
+
+  // Test instrumentation: when set, the replica reports where each stage of a
+  // draw begins and ends (the cvcgl_lowmem_fastdraw GL trace interleaves these
+  // with the GL calls to cut a trace into draws and cell-type blocks). Null --
+  // the default -- costs one relaxed load per stage. Stock draws report nothing.
+  enum class DrawStage : int {
+    DrawBegin,   // arg: 1 if this draw skips its empty cell types (Fast only)
+    LookupBegin, // full shader-cache lookup
+    LookupEnd,
+    RebindBegin, // cached program re-bound instead
+    RebindEnd,
+    AgentBegin, // arg: cell type 0-3
+    AgentEnd,   // arg: cell type 0-3
+    AgentSkipped,
+    DrawEnd
+  };
+  using StageObserver = void (*)(DrawStage stage, int arg);
+  static void setStageObserver(StageObserver observer);
+
+  // Drop the program the last lookup resolved, so the next draw looks it up in
+  // the shader cache again. For anything that edits this->Shaders outside
+  // UpdateShaders (see the invariant above).
+  void invalidateProgramCache();
+  // vtkDrawTexturedElements::GetShader (public, non-virtual) hands out a
+  // mutable source; this hides it so a caller holding this class also drops
+  // the cached program.
+  vtkShader *GetShader(vtkShader::Type shaderType);
+
+  void RenderPieceStart(vtkRenderer *ren, vtkActor *act) override;
+  void RenderPieceDraw(vtkRenderer *ren, vtkActor *act) override;
+  void ReleaseGraphicsResources(vtkWindow *win) override;
+
+protected:
+  LowMemoryPolyDataMapper();
+  ~LowMemoryPolyDataMapper() override = default;
+
+  // Bind this draw's shader program: the full lookup, or -- when allowSkip and
+  // nothing it depends on changed -- the program the last lookup returned.
+  void readyProgram(vtkRenderer *ren, bool allowSkip);
+  // Whether cell type t (0 verts, 1 lines, 2 polys, 3 strips) draws anything.
+  bool renderable(int t) const;
+  // Whether skipping the non-drawing cell types leaves every drawn one, and the
+  // program afterwards, with the depth offset the stock draw would.
+  bool coincidentSkipSafe(vtkActor *act) const;
+  // VTK 9.5.0's vtkOpenGLLowMemoryCellTypeAgent::PreDraw / Draw for cell type t.
+  void agentPreDraw(int t, vtkRenderer *ren, vtkActor *act);
+  void agentDraw(int t, vtkRenderer *ren, vtkActor *act);
+
+  vtkWeakPointer<vtkOpenGLShaderCache> m_cache; // cache the program was last resolved from
+  vtkMTimeType m_builtStamp = 0;                // ShaderBuildTimeStamp at that lookup
+  Stats m_stats;
+
+private:
+  LowMemoryPolyDataMapper(const LowMemoryPolyDataMapper &) = delete;
+  void operator=(const LowMemoryPolyDataMapper &) = delete;
+};
+
+// Which mapper newPolyDataMapper() returns. The initial value comes from the
+// CVCGL_LOWMEM_MAPPER environment variable (auto | force | off, default auto):
+//   Auto   LowMemoryPolyDataMapper wherever VTK's factory would hand out a
+//          vtkOpenGLLowMemoryPolyDataMapper (GLES3/WebGL2), the factory's mapper
+//          everywhere else (vtkOpenGLPolyDataMapper on desktop GL).
+//   Force  LowMemoryPolyDataMapper everywhere, desktop GL included -- for native
+//          tests and GL-call measurement of the WebGL path.
+//   Off    the factory's mapper everywhere.
+enum class LowMemoryMapperPolicy : int { Auto = 0, Force = 1, Off = 2 };
+void setLowMemoryMapperPolicy(LowMemoryMapperPolicy policy);
+LowMemoryMapperPolicy lowMemoryMapperPolicy();
+
+// The poly-data mapper for a cvcGL node, chosen by the policy above.
+vtkSmartPointer<vtkPolyDataMapper> newPolyDataMapper();
+
+} // namespace gl
+} // namespace cvc
+
+#endif // CVC_GL_LOW_MEMORY_POLY_DATA_MAPPER_H