feat(quads): n-gon mesh representation foundation + edit-mode ops

.github/workflows/deploy.yml

@@ -1,10 +1,16 @@
 name: Deploy
 
-on: 
+on:
    push:
-      branches: [ "master" ]
+      branches: [ "master", "feat/quads", "feat/quads-*" ]
    pull_request:
-      branches: [ "master" ]
+      # `master` covers shipping work; `feat/quads` is the long-lived
+      # quad-migration integration branch (#326) that chunked PRs land
+      # on before the final merge to master. The `feat/quads-*` glob
+      # covers chunked PRs that target a previous chunk's branch
+      # (stacked PRs). Without these, chunked PRs would have no CI
+      # safety net.
+      branches: [ "master", "feat/quads", "feat/quads-*" ]
    release:
       types: [published]
 

src/EditModeController.h

@@ -129,6 +129,11 @@ class EditModeController : public QObject
     Q_PROPERTY(bool wireframeEnabled READ wireframeEnabled WRITE setWireframeEnabled NOTIFY wireframeChanged)
     bool wireframeEnabled() const { return m_wireframeEnabled; }
     void setWireframeEnabled(bool enabled);
+
+    /// True if any submesh of the current edit mesh has non-empty
+    /// n-gon `.faces` — i.e. quad-based already. Drives the
+    /// "Convert to Quads" toolbar button enable state.
+    Q_INVOKABLE bool isMeshQuadBased() const;
     /// @}
 
     /// @name Mesh info (only valid when in edit mode)
@@ -462,6 +467,47 @@ class EditModeController : public QObject
      */
     Q_INVOKABLE int subdivideSelection();
 
+    /**
+     * @brief Insert a loop cut starting from the first selected edge.
+     *
+     * Walks the chain of quads adjacent to the start edge via the
+     * "opposite edge" relation. Each quad in the ring is bisected by
+     * splitting two parallel edges at their midpoints and connecting
+     * the new midpoints with a new edge. The walk terminates at
+     * boundaries, non-quad faces, or when it loops back to the start.
+     *
+     * Requires Edge selection mode and at least one selected edge.
+     * Uses the FIRST selected edge as the start; multi-edge loop cuts
+     * are out of scope for the MVP (each cut is independent).
+     *
+     * Pushes one undo command labeled "Loop Cut".
+     *
+     * @return Number of new vertices inserted (0 on no-op / failure).
+     */
+    Q_INVOKABLE int loopCutSelection();
+
+    /**
+     * @brief Subdivide the entire mesh by one Catmull-Clark step.
+     *
+     * Unlike `subdivideSelection` (which does a 1-to-4 triangle split
+     * on the selected faces only), this op operates on the whole mesh
+     * at once and produces an all-quad output regardless of input
+     * topology — a triangle becomes 3 quads, a quad becomes 4. Output
+     * geometry is smoothed via the classic Catmull-Clark rule (face
+     * points, edge points, smoothed vertex positions) so the surface
+     * approaches a C¹-continuous limit on closed manifolds.
+     *
+     * Selection is cleared after the op (the new face/edge points
+     * don't have stable analogues in the pre-op selection set, and
+     * partial-mesh CC needs a more sophisticated boundary blend that
+     * isn't in this MVP).
+     *
+     * Pushes one undo command labeled "Catmull-Clark Subdivide".
+     *
+     * @return Number of vertices added (0 on no-op).
+     */
+    Q_INVOKABLE int subdivideCatmullClarkAll();
+
     /**
      * @brief Fill the current selection with new face(s).
      *
@@ -481,6 +527,28 @@ class EditModeController : public QObject
      * @return Number of triangles created (0 on no-op or rejection).
      */
     Q_INVOKABLE int fillSelection();
+
+    /**
+     * @brief Merge coplanar adjacent triangle pairs into quads.
+     *
+     * Whole-mesh operation: walks every submesh, looks for triangle pairs
+     * that share an edge and are within `angleThresholdDeg` of coplanar
+     * (default 1°), and merges each qualifying pair into a single quad
+     * face. Promotes the legacy triangle-only representation into the
+     * n-gon canonical form. After the operation, downstream features
+     * that branch on n-gon `.faces` (loop cut, n-gon-aware bevel,
+     * quad-aware wireframe) start working.
+     *
+     * No-op when nothing qualifies (all tris are non-coplanar, or the
+     * mesh is already quad-dominant). Pushes one undo command labeled
+     * "Convert to Quads" iff merges happened.
+     *
+     * @param angleThresholdDeg Maximum dihedral angle (deg) to treat as
+     *        coplanar. 0 = strict, ~5 = forgiving for float-quantised
+     *        imports. Defaults to 1°.
+     * @return Number of triangle pairs merged across all submeshes.
+     */
+    Q_INVOKABLE int convertToQuads(float angleThresholdDeg = 1.0f);
     /// @}
 
     /// @name Vertex transform support
@@ -681,6 +749,18 @@ class EditModeController : public QObject
 
     /// Convert (subMeshIndex, localTriangleIndex) to a global triangle index.
     int localTriToGlobal(size_t subMeshIndex, size_t localTriIndex) const;
+
+    /// @brief Convert the current `m_selectedFaces` set (global triangle
+    /// indices) into a deduplicated list of HE face indices that
+    /// HalfEdgeMesh ops accept. Each unique HE face is reported once
+    /// regardless of how many of its fan-triangulated children appear
+    /// in the selection — so a quad selected via either of its
+    /// triangles maps to a single HE face.
+    ///
+    /// HE face indexing matches `HalfEdgeMesh::buildFromEditableMesh`
+    /// order: submesh 0's faces first (or its triangles, in legacy
+    /// triangle-only submeshes), then submesh 1's, etc.
+    std::vector<int> selectedFacesAsHEFaceIndices() const;
     /// @}
 
 signals:
@@ -709,6 +789,12 @@ class EditModeController : public QObject
     void knifeSessionChanged();
     void vertexPaintChanged();
 
+    /// Emitted when an edit-mode op short-circuits and wants to surface
+    /// a one-line explanation to the user (e.g. "Loop cut requires a
+    /// quad mesh — try Mesh → Convert to Quads"). QML overlays /
+    /// status-bar widgets can subscribe.
+    void editHintMessage(const QString& message);
+
 private slots:
     void onSelectionChanged();
 
@@ -751,6 +837,12 @@ private slots:
     Ogre::ManualObject* m_overlayVertices = nullptr;
     Ogre::ManualObject* m_overlayEdges = nullptr;
     Ogre::ManualObject* m_overlayFaces = nullptr;
+    /// Quad-aware wireframe: lines along n-gon face boundaries only,
+    /// hiding the diagonals introduced by `triangulateFaces()`. Active
+    /// when `m_wireframeEnabled` AND any submesh has non-empty `.faces`.
+    /// On legacy triangle-only meshes this stays empty and the
+    /// PM_WIREFRAME material override does the work instead.
+    Ogre::ManualObject* m_overlayBoundaryEdges = nullptr;
     Ogre::SceneNode* m_overlayNode = nullptr;
 
     // Bevel session state — populated on beginBevel, consumed on commit/cancel.
@@ -909,6 +1001,27 @@ private slots:
     // Wireframe helpers
     void applyWireframeMaterials();
     void removeWireframeMaterials();
+    /// True if any submesh has non-empty `.faces` (n-gon canonical).
+    /// Drives the choice between PM_WIREFRAME (all submeshes pure tris)
+    /// and the boundary-edge overlay (any n-gon faces present).
+    bool meshHasNgonFaces() const;
+    /// (Re)build the n-gon boundary-edge overlay from `m_editableMesh`.
+    /// Active when `m_wireframeEnabled` AND `meshHasNgonFaces()` —
+    /// otherwise clears the overlay so it draws nothing.
+    void updateBoundaryEdgeOverlay();
+
+public:
+    /// Refresh an entity after a topology mutation: rebuild tangents
+    /// (when any material is bump-mapped), `_deinitialise/_initialise`
+    /// the entity, restore per-subentity material overrides, re-attach
+    /// RTSS SRS_NORMALMAP, and invalidate cached shader programs. Used
+    /// by every Edit-Mode topology op (subdivide, extrude, bevel, …)
+    /// AND by `EditMeshTopologyCommand::applyMeshState` so undo/redo
+    /// preserves bump map / per-pixel lighting state. Static so
+    /// command code can invoke it without a controller instance.
+    static void rewriteEntityAfterTopologyChange(Ogre::Entity* ent);
+
+private:
 
     // Wireframe mode
     bool m_wireframeEnabled = false;

src/EditModeController_test.cpp

@@ -18,12 +18,35 @@ The MIT License
 #include "HalfEdgeMesh.h"
 #include <Ogre.h>
 #include <QSignalSpy>
+#include <QDir>
+#include <QFile>
+#include <QTextStream>
 #include <set>
 #include <utility>
 #include <cmath>
 #include <array>
 #include <map>
 
+// ===========================================================================
+// rewriteEntityAfterTopologyChange — null + no-bump-map shape (chunk: quads
+// follow-up). Full bump-map / RTSS exercise needs a GL context, which the
+// test infra doesn't provide on macOS; the integration coverage lives in
+// hand smoke tests on the bump-mapped Mixamo asset. Here we lock down the
+// public-API contract: static, callable from outside the class (notably
+// from EditMeshTopologyCommand::applyMeshState in the undo/redo path),
+// null-tolerant, and a no-op when no entity material requests tangents.
+// ===========================================================================
+
+TEST(EditModeControllerStandalone, RewriteEntityAfterTopologyChangeNullIsNoOp) {
+    // Regression for chunk 4b → quads follow-up: the static helper is
+    // reachable from command code in TransformCommands.cpp via a class-
+    // qualified call, and accepts a null entity without crashing. If
+    // someone refactors it back to a free function in an anonymous
+    // namespace, undo/redo will silently lose its lighting hook again.
+    EditModeController::rewriteEntityAfterTopologyChange(nullptr);
+    SUCCEED();
+}
+
 // ===========================================================================
 // Pure geometry tests (no Ogre needed)
 // ===========================================================================
@@ -1937,3 +1960,107 @@ TEST_F(EditModeControllerBevelE2ETest, FillSelectionPushesUndoCommand) {
     EXPECT_EQ(trisAfterUndo.size(), triCountBefore - 1)
         << "undo after fill should drop back to the post-delete tri count";
 }
+
+// ===========================================================================
+// enterEditMode: n-gon import path (chunk 4)
+// ===========================================================================
+
+namespace {
+// Write a minimal quad OBJ to a temp file. Mirrors the helper in
+// EditableMesh_test.cpp (intentionally duplicated rather than shared
+// across translation units, since the test files don't share a TU).
+QString writeQuadObjForCtrl(const QString& baseName)
+{
+    const QString path = QDir::tempPath() + "/" + baseName + ".obj";
+    QFile f(path);
+    if (!f.open(QIODevice::WriteOnly | QIODevice::Truncate)) return {};
+    QTextStream out(&f);
+    out << "v 0 0 0\nv 1 0 0\nv 1 1 0\nv 0 1 0\nf 1 2 3 4\n";
+    f.close();
+    return path;
+}
+} // namespace
+
+TEST_F(EditModeControllerBevelE2ETest, EnterEditModeUsesNgonPathWhenSourceCached) {
+    // When the entity's mesh has qtme.source_path set, enterEditMode
+    // should re-import via Assimp with aiProcess_Triangulate disabled,
+    // populating EditableSubMesh::faces with the polygon structure.
+    const QString objPath = writeQuadObjForCtrl("ctrl_ngon_path");
+    ASSERT_FALSE(objPath.isEmpty());
+
+    // Tag the cube mesh from the fixture's setup with a source path
+    // pointing at the OBJ. enterEditMode should then re-import the OBJ
+    // (overriding the cube's geometry — that's fine, the test only
+    // verifies that the n-gon code path fired, not vertex content).
+    auto* mesh = m_entity->getMesh().get();
+    mesh->getUserObjectBindings().setUserAny(
+        "qtme.source_path", Ogre::Any(objPath.toStdString()));
+
+    auto* ctrl = EditModeController::instance();
+    ASSERT_TRUE(ctrl->enterEditMode());
+
+    auto* editableMesh = ctrl->currentMesh();
+    ASSERT_NE(editableMesh, nullptr);
+    ASSERT_FALSE(editableMesh->subMeshes().empty());
+    EXPECT_FALSE(editableMesh->subMeshes()[0].faces.empty())
+        << "enterEditMode with source_path set should populate faces "
+           "via the n-gon-aware loadFromAssimpFile path";
+    EXPECT_EQ(editableMesh->subMeshes()[0].faces[0].indices.size(), 4u);
+
+    QFile::remove(objPath);
+}
+
+TEST_F(EditModeControllerBevelE2ETest, EnterEditModeFallsBackToLegacyWhenNoSourcePath) {
+    // The fixture's cube has no qtme.source_path tag. enterEditMode
+    // should fall through to loadFromEntity and produce the
+    // triangle-only legacy submesh shape (faces empty).
+    auto* mesh = m_entity->getMesh().get();
+    EXPECT_FALSE(mesh->getUserObjectBindings().getUserAny(
+        "qtme.source_path").has_value())
+        << "fixture cube starts without source path — sanity check";
+
+    auto* ctrl = EditModeController::instance();
+    ASSERT_TRUE(ctrl->enterEditMode());
+
+    auto* editableMesh = ctrl->currentMesh();
+    ASSERT_NE(editableMesh, nullptr);
+    ASSERT_FALSE(editableMesh->subMeshes().empty());
+    EXPECT_TRUE(editableMesh->subMeshes()[0].faces.empty())
+        << "no source path → legacy path → faces empty (chunk-1 invariant)";
+}
+
+TEST_F(EditModeControllerBevelE2ETest, EnterEditModeAfterEditDoesNotReimport) {
+    // Enter Edit Mode with the n-gon path (sets faces), make a
+    // committable edit, exit, re-enter. The second entry must use the
+    // legacy path because the first edit wiped qtme.source_path.
+    const QString objPath = writeQuadObjForCtrl("ctrl_ngon_post_edit");
+    ASSERT_FALSE(objPath.isEmpty());
+
+    auto* mesh = m_entity->getMesh().get();
+    mesh->getUserObjectBindings().setUserAny(
+        "qtme.source_path", Ogre::Any(objPath.toStdString()));
+
+    auto* ctrl = EditModeController::instance();
+    ASSERT_TRUE(ctrl->enterEditMode());
+    ASSERT_FALSE(ctrl->currentMesh()->subMeshes().empty());
+    ASSERT_FALSE(ctrl->currentMesh()->subMeshes()[0].faces.empty())
+        << "first entry must take the n-gon path";
+
+    // Commit any change (translate one vertex by zero — still triggers
+    // the commitToEntity path that wipes the source path).
+    ctrl->setSelectionMode(EditModeController::VertexMode);
+    ctrl->selectVertex(0);
+    ctrl->translateSelectedVertices(Ogre::Vector3::ZERO);
+    ctrl->exitEditMode(/*commitChanges*/ true);
+
+    EXPECT_FALSE(mesh->getUserObjectBindings().getUserAny(
+        "qtme.source_path").has_value())
+        << "exitEditMode commit must have wiped the source path";
+
+    // Re-enter: should fall back to legacy path now.
+    ASSERT_TRUE(ctrl->enterEditMode());
+    EXPECT_TRUE(ctrl->currentMesh()->subMeshes()[0].faces.empty())
+        << "second entry (post-edit) must use legacy loadFromEntity path";
+
+    QFile::remove(objPath);
+}