refactor: render ImGui through CNA

Author: robertvokac

CMakeLists.txt

@@ -73,26 +73,20 @@ endfunction()
 # Graphics backend selection
 # -----------------------------------------------------------------------------
 #
-# This variable selects the CNA *engine* backend. IMPORTANT: it is NOT the
-# MeshCraft editor GUI backend. The editor's ImGui layer is hard-wired to
-# OpenGL/GLES3 (ImGui_ImplOpenGL3 + ImGui_ImplSDL3_InitForOpenGL +
-# SDL_GL_GetCurrentContext, see src/MeshCraft/MeshCraftApplication.cpp), so the
-# GUI editor only renders under a GL context — i.e. EASYGL (desktop GL) or its
-# Emscripten WebGL2 variant. SDL_RENDERER / BGFX / VULKAN configure CNA's engine
-# but leave the editor UI unable to render (no matching ImGui backend, no GL
-# context). Use them only for CNA-level experimentation or the CNA-free CLI
-# tools (mc3togltf / mc3tomcb), which don't depend on the backend at all.
+# This variable selects the CNA engine backend. MeshCraft's ImGui renderer
+# consumes ImDrawData through CNA graphics APIs, so it does not require an
+# native graphics context or a renderer backend tied to one API.
 #
 # Override with:
-#   cmake -S . -B build -DMESH_CRAFT_GRAPHICS_BACKEND=EASYGL   # editor GUI works
-#   cmake -S . -B build -DMESH_CRAFT_GRAPHICS_BACKEND=SDL_RENDERER  # CNA engine only
+#   cmake -S . -B build -DMESH_CRAFT_GRAPHICS_BACKEND=EASYGL
+#   cmake -S . -B build-vulkan -DMESH_CRAFT_GRAPHICS_BACKEND=VULKAN
 #
 # Accepted (CNA engine): SDL_RENDERER, EASYGL, BGFX, VULKAN.
-# Functional for the MeshCraft editor GUI: EASYGL only.
+# Editor compatibility is determined by CNA's selected backend capabilities.
 # -----------------------------------------------------------------------------
 
 set(MESH_CRAFT_GRAPHICS_BACKEND "EASYGL" CACHE STRING
-        "CNA engine backend. The editor GUI only renders on EASYGL.")
+        "CNA engine backend used by the MeshCraft editor GUI.")
 set_property(CACHE MESH_CRAFT_GRAPHICS_BACKEND PROPERTY STRINGS
         SDL_RENDERER EASYGL BGFX VULKAN)
 
@@ -117,21 +111,6 @@ endif()
 
 message(STATUS "MeshCraft graphics backend (CNA engine): ${MESH_CRAFT_GRAPHICS_BACKEND_UPPER}")
 
-# Gate C truthfulness: the editor GUI only renders on EASYGL. Warn loudly for any
-# other backend so a non-functional editor build is never produced silently. The
-# CNA-free CLI tools are unaffected. Set MESH_CRAFT_SILENCE_BACKEND_WARNING=ON to
-# suppress this when you are deliberately building CNA-only / a CLI-only target.
-if(NOT MESH_CRAFT_GRAPHICS_BACKEND_UPPER STREQUAL "EASYGL"
-        AND NOT MESH_CRAFT_SILENCE_BACKEND_WARNING)
-    message(WARNING
-        "MESH_CRAFT_GRAPHICS_BACKEND='${MESH_CRAFT_GRAPHICS_BACKEND_UPPER}' selects the "
-        "CNA engine backend, but the MeshCraft *editor GUI* is hard-wired to OpenGL/GLES3 "
-        "(ImGui_ImplOpenGL3). Under this backend the editor will build but its UI will NOT "
-        "render (no GL context / no matching ImGui backend). Use EASYGL for a working editor; "
-        "the CNA-free CLI tools (mc3togltf, mc3tomcb) work under any backend. "
-        "Set -DMESH_CRAFT_SILENCE_BACKEND_WARNING=ON to silence this.")
-endif()
-
 if(MESH_CRAFT_GRAPHICS_BACKEND_UPPER STREQUAL "SDL_RENDERER")
     set(CNA_BACKEND_SDL_RENDERER ON  CACHE BOOL "" FORCE)
     set(CNA_BACKEND_EASY_GL      OFF CACHE BOOL "" FORCE)
@@ -248,7 +227,7 @@ add_subdirectory(mcb)
 # mc3tomcb — CLI converter between MC3 XML and MCB binary
 add_subdirectory(mc3tomcb)
 
-# ImGui — immediate-mode UI (SDL3 + OpenGL ES 3 backends)
+# ImGui — immediate-mode UI (SDL3 input platform backend; rendering is CNA).
 include(FetchContent)
 FetchContent_Declare(imgui
     GIT_REPOSITORY https://github.com/ocornut/imgui.git
@@ -263,13 +242,11 @@ add_library(imgui STATIC
     ${imgui_SOURCE_DIR}/imgui_tables.cpp
     ${imgui_SOURCE_DIR}/imgui_widgets.cpp
     ${imgui_SOURCE_DIR}/backends/imgui_impl_sdl3.cpp
-    ${imgui_SOURCE_DIR}/backends/imgui_impl_opengl3.cpp
 )
 target_include_directories(imgui PUBLIC
     ${imgui_SOURCE_DIR}
     ${imgui_SOURCE_DIR}/backends
 )
-target_compile_definitions(imgui PUBLIC IMGUI_IMPL_OPENGL_ES3)
 
 # SDL3 headers: use prebuilt path from CNA's SDL3_DIR cache variable
 # SDL3_DIR is .../lib/cmake/SDL3, so include dir is 3 levels up + /include
@@ -279,9 +256,6 @@ if(DEFINED SDL3_DIR)
 elseif(TARGET SDL3::SDL3)
     target_link_libraries(imgui PUBLIC SDL3::SDL3)
 endif()
-if(NOT EMSCRIPTEN)
-    target_link_libraries(imgui PUBLIC GLESv2)
-endif()
 
 # Manifold — CSG boolean mesh evaluation. Pinned at v3.0.0 (STAB-0222); no
 # minimum-version requirement beyond this exact pin has been established —
@@ -493,7 +467,7 @@ meshcraft_apply_sanitize(${_target})
 # runtime check is the surgical alternative that still satisfies Gate C
 # ("unsupported and rejected clearly"): embed the selected backend name, and
 # main() (src/MeshCraft/main.cpp) refuses to proceed under a backend the
-# editor cannot render on, before any window/GL initialization -- an
+# editor cannot render on, before any window or graphics-device initialization -- an
 # unsupported configuration is REJECTED at startup with a clear message and a
 # non-zero exit code, not silently launched as a broken window. The CLI tools
 # (mc3togltf/mc3tomcb) do not link this target and are unaffected.
@@ -911,6 +885,22 @@ if(MESH_CRAFT_BUILD_TESTING AND UNIX AND NOT ANDROID AND NOT EMSCRIPTEN)
     add_test(NAME graphics_backend_check COMMAND graphics_backend_check_test)
     set_tests_properties(graphics_backend_check PROPERTIES TIMEOUT 15 LABELS "unit")
 
+    add_executable(imgui_texture_registry_test
+        ${CMAKE_CURRENT_SOURCE_DIR}/test/imgui_texture_registry_test.cpp)
+    target_include_directories(imgui_texture_registry_test PRIVATE
+        ${CMAKE_CURRENT_SOURCE_DIR}/include)
+    target_compile_features(imgui_texture_registry_test PRIVATE cxx_std_23)
+    add_test(NAME imgui_texture_registry COMMAND imgui_texture_registry_test)
+    set_tests_properties(imgui_texture_registry PROPERTIES TIMEOUT 15 LABELS "unit")
+
+    add_executable(imgui_draw_translation_test
+        ${CMAKE_CURRENT_SOURCE_DIR}/test/imgui_draw_translation_test.cpp)
+    target_include_directories(imgui_draw_translation_test PRIVATE
+        ${CMAKE_CURRENT_SOURCE_DIR}/include)
+    target_compile_features(imgui_draw_translation_test PRIVATE cxx_std_23)
+    add_test(NAME imgui_draw_translation COMMAND imgui_draw_translation_test)
+    set_tests_properties(imgui_draw_translation PROPERTIES TIMEOUT 15 LABELS "unit")
+
     # SYS-W7-02: differential geometry tests -- viewport renderer (via the
     # CNA-free tessellateUnit*Alg() mirror in
     # include/MeshCraft/Renderer/PrimitiveTessellationAlg.hpp) vs. the glTF
@@ -1082,6 +1072,15 @@ if(MESH_CRAFT_BUILD_TESTING AND UNIX AND NOT ANDROID AND NOT EMSCRIPTEN)
                          "${CMAKE_CURRENT_SOURCE_DIR}")
         set_tests_properties(undo_snapshot_lint PROPERTIES TIMEOUT 15 LABELS "lint")
 
+        # SYS-W8-02/03/04: production ImGui rendering must stay on CNA's
+        # public graphics API; a native OpenGL backend/texture handle would
+        # make alternate CNA backends impossible again.
+        add_test(NAME imgui_renderer_portability
+                 COMMAND "${PYTHON3_FOR_LINT}"
+                         "${CMAKE_CURRENT_SOURCE_DIR}/test/imgui_renderer_portability_test.py"
+                         "${CMAKE_CURRENT_SOURCE_DIR}")
+        set_tests_properties(imgui_renderer_portability PROPERTIES TIMEOUT 15 LABELS "lint")
+
         # plan.md/NEXT.md mechanical self-consistency: unique task IDs, DONE
         # counts match the summary line, DONE tasks cite a commit, the priority
         # queue never points at a DONE task, no machine-specific absolute paths.

NEXT.md

@@ -78,9 +78,9 @@ before when explicitly requested (`SYS-W14-##` rows).
 ## 2. Current status
 
 - **Build: clean**, `cmake --build b-release -j4` passed after SVG texture
-  support was added (EASYGL backend on Linux — the only backend buildable
-  here).
-- **Tests:** 177 tests are registered. SVG-specific verification passes with
+  support was added (EASYGL backend on Linux). The CNA-backed ImGui adapter
+  also builds there; alternate-backend runtime qualification remains blocked.
+- **Tests:** 180 tests are registered. SVG-specific verification passes with
   `-j4`: external and inline SVG export to glTF PNGs, bounded/malformed input,
   cache invalidation, and real headless viewport screenshots sampling the
   rasterized material pixels. This session's own
@@ -90,10 +90,10 @@ before when explicitly requested (`SYS-W14-##` rows).
   count this file last recorded (2026-07-19) predates unrelated work not
   narrated here (a further audit pass and the `SYS-W14-18..27`
   mc3-format-vs-editor gap closures — see `plan.md`/memory, not fully
-  reflected in this file's own history) — don't treat 142→177 as this
+  reflected in this file's own history) — don't treat 142→180 as this
   session's own delta.
-  All builds/tests this session used `-j4` (not `-j$(nproc)`), per the
-  user's standing request (shared machine).
+  All builds/tests this session used at most `-j4` (never `-j$(nproc)`), per
+  the user's standing request (shared machine).
 - **CLI/tools/apps/libraries currently available:**
   - `MeshCraft` — the interactive editor (`./b-release/MeshCraft
     scene.mc3.xml`, or `--screenshot out.png` / `--export out.glb` /

TESTING.md

@@ -2,7 +2,7 @@
 
 _Last updated: 2026-07-25. Counts below were produced from the live release build with `ctest -L <label> -N`, not carried over from an earlier revision. This document is derived from the actual `CMakeLists.txt` test registrations and test source files — if it drifts from `ctest -N`'s output, trust `ctest -N`, not this file's claimed count._
 
-MeshCraft's tests run through **CTest** — **177 tests registered** (`ctest --print-labels` label breakdown: `ai` 1, `commands` 1, `export` 71, `format` 37, `lint` 3, `perf` 2, `registry` 1, `render` 34, `unit` 29), mixing C++ assertion-based binaries and Python/bash subprocess-driven checks against the `mc3togltf`/`mc3tomcb` CLIs and the `MeshCraft` editor binary itself (headless `--screenshot` real-pixel-sampling tests, plus 3 tests that drive real headless Blender for GLB-import verification). `render_display_preflight` verifies an actual `xvfb-run` + `xdpyinfo` X client before the render subset; if unavailable, it reports a CTest skip and CMake disables only the other render-labelled tests. **Known gap:** the "CLI-driving Python tests" table below documents the most significant/representative tests in each category but is not exhaustively 1:1 with all registrations — `ctest -N` and `ctest --print-labels` are authoritative for the complete list.
+MeshCraft's tests run through **CTest** — **180 tests registered** (`ctest --print-labels` label breakdown: `ai` 1, `commands` 1, `export` 71, `format` 37, `lint` 4, `perf` 2, `registry` 1, `render` 34, `unit` 31), mixing C++ assertion-based binaries and Python/bash subprocess-driven checks against the `mc3togltf`/`mc3tomcb` CLIs and the `MeshCraft` editor binary itself (headless `--screenshot` real-pixel-sampling tests, plus 3 tests that drive real headless Blender for GLB-import verification). `render_display_preflight` verifies an actual `xvfb-run` + `xdpyinfo` X client before the render subset; if unavailable, it reports a CTest skip and CMake disables only the other render-labelled tests. **Known gap:** the "CLI-driving Python tests" table below documents the most significant/representative tests in each category but is not exhaustively 1:1 with all registrations — `ctest -N` and `ctest --print-labels` are authoritative for the complete list.
 
 ---
 
@@ -31,7 +31,7 @@ ctest --print-labels   # list all labels
 ctest --rerun-failed --output-on-failure
 ```
 
-Expected result: every registered test passes. The 177-registration count was checked 2026-07-25; the relevant focused suites are run with `-j4` after each change. A failing test prints its assertion/subprocess output inline with `--output-on-failure`; without that flag, CTest only shows pass/fail per test name.
+Expected result: every registered test passes. The 180-registration count was checked 2026-07-25; the relevant focused suites are run with `-j4` after each change. A failing test prints its assertion/subprocess output inline with `--output-on-failure`; without that flag, CTest only shows pass/fail per test name.
 
 Each C++ test binary can also be run directly (bypassing CTest) for faster iteration:
 

include/MeshCraft/GraphicsBackendCheck.hpp

@@ -6,20 +6,17 @@
 // messages) so it is headlessly unit-testable without a full alternate-
 // backend rebuild -- see test/graphics_backend_check_test.cpp.
 //
-// The editor's ImGui UI is hard-wired to OpenGL/GLES3 (see
-// src/MeshCraft/MeshCraftApplication.cpp's ImGui_ImplOpenGL3_Init /
-// ImGui_ImplSDL3_InitForOpenGL) and only actually renders under EASYGL.
+// The editor's ImGui renderer uses CNA rather than a native graphics API.
 
 #include <string>
 
 namespace MeshCraft {
 
-// Returns true if `backend` should be allowed to proceed (EASYGL always is;
-// any other backend only if `allowOverride` is set, e.g. from
-// MESH_CRAFT_ALLOW_UNSUPPORTED_BACKEND).
-inline bool isBackendSupportedAlg(const std::string& backend, bool allowOverride) {
-    if (backend == "EASYGL") return true;
-    return allowOverride;
+// The renderer has no native-GL dependency, but a backend becomes launchable
+// only after SYS-W8-05's real screenshot qualification. EASYGL is qualified
+// now; the other CNA backends stay truthfully rejected until then.
+inline bool isBackendSupportedAlg(const std::string& backend, bool /*allowOverride*/) {
+    return backend == "EASYGL";
 }
 
 } // namespace MeshCraft

include/MeshCraft/ImGuiRenderAlgorithms.hpp

@@ -0,0 +1,52 @@
+#pragma once
+
+#include <algorithm>
+#include <cmath>
+#include <optional>
+#include <vector>
+
+namespace MeshCraft {
+
+struct ImGuiScissorRect {
+    int x;
+    int y;
+    int width;
+    int height;
+};
+
+// Converts Dear ImGui's display-relative clip rectangle to a bounded CNA
+// scissor rectangle. Kept graphics-context-free for regression tests.
+inline std::optional<ImGuiScissorRect> makeImGuiScissorRect(
+    float left, float top, float right, float bottom,
+    float displayX, float displayY, float scaleX, float scaleY,
+    float framebufferWidth, float framebufferHeight)
+{
+    const int x = std::max(0, static_cast<int>(std::floor((left - displayX) * scaleX)));
+    const int y = std::max(0, static_cast<int>(std::floor((top - displayY) * scaleY)));
+    const int r = std::min(static_cast<int>(framebufferWidth),
+                           static_cast<int>(std::ceil((right - displayX) * scaleX)));
+    const int b = std::min(static_cast<int>(framebufferHeight),
+                           static_cast<int>(std::ceil((bottom - displayY) * scaleY)));
+    if (r <= x || b <= y) return std::nullopt;
+    return ImGuiScissorRect{x, y, r - x, b - y};
+}
+
+// CNA user-indexed draws have no base-vertex parameter. Copy the command's
+// indices into a short-lived local range relative to its vertex offset.
+template <typename Index>
+inline bool localizeImGuiIndices(const Index* source, unsigned int sourceCount,
+                                 unsigned int indexOffset, unsigned int elementCount,
+                                 unsigned int vertexOffset, std::vector<Index>& destination)
+{
+    if (indexOffset > sourceCount || elementCount > sourceCount - indexOffset)
+        return false;
+    destination.resize(elementCount);
+    for (unsigned int i = 0; i < elementCount; ++i) {
+        const Index index = source[indexOffset + i];
+        if (index < vertexOffset) return false;
+        destination[i] = static_cast<Index>(index - vertexOffset);
+    }
+    return true;
+}
+
+} // namespace MeshCraft

include/MeshCraft/ImGuiRenderer.hpp

@@ -0,0 +1,35 @@
+#pragma once
+
+#include <cstdint>
+#include <memory>
+
+struct ImDrawData;
+struct SDL_Window;
+
+namespace Microsoft::Xna::Framework::Graphics {
+class GraphicsDevice;
+class Texture2D;
+}
+
+namespace MeshCraft {
+
+// MeshCraft's rendering half of Dear ImGui. SDL remains the platform/input
+// backend; this class deliberately renders ImDrawData only through CNA.
+class ImGuiRenderer {
+public:
+    virtual ~ImGuiRenderer() = default;
+    virtual bool initialize(Microsoft::Xna::Framework::Graphics::GraphicsDevice& device,
+                            SDL_Window* window) = 0;
+    virtual void newFrame() = 0;
+    virtual void render(ImDrawData* drawData) = 0;
+    virtual void shutdown() = 0;
+
+    // ImTextureID is opaque. MeshCraft stores this integer token rather than
+    // leaking a native API handle into panels that call ImGui::Image().
+    virtual std::uintptr_t registerTexture(Microsoft::Xna::Framework::Graphics::Texture2D& texture) = 0;
+    virtual void unregisterTexture(std::uintptr_t token) = 0;
+
+    static std::unique_ptr<ImGuiRenderer> createCnaRenderer();
+};
+
+} // namespace MeshCraft

include/MeshCraft/ImGuiTextureRegistry.hpp

@@ -0,0 +1,34 @@
+#pragma once
+
+#include <cstdint>
+#include <unordered_map>
+
+namespace Microsoft::Xna::Framework::Graphics { class Texture2D; }
+
+namespace MeshCraft {
+
+// Backend-neutral ownership-free mapping between Dear ImGui's opaque texture
+// token and the CNA texture that the renderer will bind for a draw command.
+class ImGuiTextureRegistry {
+public:
+    std::uintptr_t registerTexture(Microsoft::Xna::Framework::Graphics::Texture2D* texture) {
+        if (!texture) return 0;
+        const std::uintptr_t token = nextToken_++;
+        textures_.emplace(token, texture);
+        return token;
+    }
+
+    Microsoft::Xna::Framework::Graphics::Texture2D* resolve(std::uintptr_t token) const {
+        const auto found = textures_.find(token);
+        return found == textures_.end() ? nullptr : found->second;
+    }
+
+    void unregisterTexture(std::uintptr_t token) { textures_.erase(token); }
+    void clear() { textures_.clear(); }
+
+private:
+    std::unordered_map<std::uintptr_t, Microsoft::Xna::Framework::Graphics::Texture2D*> textures_;
+    std::uintptr_t nextToken_{1};
+};
+
+} // namespace MeshCraft