add split viewport support with independent cameras

Adds support for split viewports with independent per-viewport camera
state and arbitrary grid layouts (1x1, 1x2, 2x1, 2x2). Each viewport
owns its own scene framebuffers, swapped with the engine during
rendering so all existing rendering paths work without modification.

Addresses #387.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jdumas

examples/demo-app/demo_app.cpp

@@ -16,6 +16,7 @@
 #include "polyscope/surface_mesh.h"
 #include "polyscope/types.h"
 #include "polyscope/view.h"
+#include "polyscope/viewport.h"
 #include "polyscope/volume_grid.h"
 #include "polyscope/volume_mesh.h"
 
@@ -954,6 +955,23 @@ void callback() {
     addSparseVolumeGrid();
   }
 
+  // Split viewport controls (per-viewport settings are in the built-in View panel)
+  if (ImGui::Button("Single")) {
+    polyscope::setSingleViewport();
+  }
+  ImGui::SameLine();
+  if (ImGui::Button("V-Split")) {
+    polyscope::setVerticalSplitViewport();
+  }
+  ImGui::SameLine();
+  if (ImGui::Button("H-Split")) {
+    polyscope::setHorizontalSplitViewport();
+  }
+  ImGui::SameLine();
+  if (ImGui::Button("Quad")) {
+    polyscope::setQuadViewport();
+  }
+
   // ImPlot
   // dummy data
   if (ImGui::TreeNode("ImPlot")) {

include/polyscope/context.h

@@ -4,6 +4,7 @@
 
 #include <polyscope/pick.h>
 #include <polyscope/types.h>
+#include <polyscope/viewport.h>
 #include <polyscope/weak_handle.h>
 
 #include <glm/glm.hpp>
@@ -119,6 +120,16 @@ struct Context {
   bool pointCloudEfficiencyWarningReported = false;
   FloatingQuantityStructure* globalFloatingQuantityStructure = nullptr;
 
+  // ======================================================
+  // === Viewport grid
+  // ======================================================
+
+  int viewportGridRows = 1;
+  int viewportGridCols = 1;
+  std::vector<std::unique_ptr<Viewport>> viewports;
+  Viewport* activeViewport = nullptr;     // the viewport currently receiving mouse input (null when no button held)
+  Viewport* lastActiveViewport = nullptr; // the most recently interacted viewport (persists after mouse release)
+
   // ======================================================
   // === Other various global lists
   // ======================================================

include/polyscope/polyscope.h

@@ -21,6 +21,7 @@
 #include "polyscope/structure.h"
 #include "polyscope/transformation_gizmo.h"
 #include "polyscope/utilities.h"
+#include "polyscope/viewport.h"
 #include "polyscope/weak_handle.h"
 #include "polyscope/widget.h"
 
@@ -196,6 +197,26 @@ void buildPickGui();
 void buildUserGuiAndInvokeCallback();
 
 
+// === Viewport management
+
+// Set the viewport grid layout (e.g. 1x1, 1x2, 2x1, 2x2)
+void setViewportGridLayout(int rows, int cols);
+int getViewportGridRows();
+int getViewportGridCols();
+
+// Convenience presets
+void setSingleViewport();
+void setVerticalSplitViewport();   // 1 row, 2 columns (left | right)
+void setHorizontalSplitViewport(); // 2 rows, 1 column (top / bottom)
+void setQuadViewport();            // 2 rows, 2 columns
+
+// Get a specific viewport (nullptr if out of range)
+Viewport* getViewport(int row, int col);
+Viewport* getActiveViewport();
+
+// Internal: update viewport layouts after window resize
+void updateViewportLayouts();
+
 // === Utility
 
 // Execute one iteration of the main loop

include/polyscope/viewport.h

@@ -0,0 +1,120 @@
+// Copyright 2017-2023, Nicholas Sharp and the Polyscope contributors. https://polyscope.run
+
+#pragma once
+
+#include <array>
+#include <memory>
+#include <string>
+
+#include "polyscope/types.h"
+#include "polyscope/view.h"
+
+namespace polyscope {
+
+// Forward declarations
+namespace render {
+class FrameBuffer;
+class TextureBuffer;
+class ShaderProgram;
+} // namespace render
+
+// A snapshot of the global view state, used for push/pop when rendering viewports
+struct ViewStateSnapshot {
+  glm::mat4x4 viewMat;
+  float fov;
+  glm::vec3 viewCenter;
+  NavigateStyle navigateStyle;
+  UpDir upDir;
+  FrontDir frontDir;
+  ProjectionMode projectionMode;
+  float nearClip, farClip;
+  float moveScale;
+  ViewRelativeMode viewRelativeMode;
+  std::array<float, 4> bgColor;
+  int bufferWidth, bufferHeight;
+  int windowWidth, windowHeight;
+
+  // Flight state
+  bool midflight;
+  float flightStartTime, flightEndTime;
+  glm::dualquat flightTargetViewR, flightInitialViewR;
+  glm::vec3 flightTargetViewT, flightInitialViewT;
+  float flightTargetFov, flightInitialFov;
+};
+
+// Save/restore the current global view state
+ViewStateSnapshot saveViewState();
+void restoreViewState(const ViewStateSnapshot& snapshot);
+
+
+class Viewport {
+public:
+  Viewport(std::string name, int gridRow, int gridCol);
+  ~Viewport();
+
+  // === Identity
+  std::string name;
+  int gridRow, gridCol;
+
+  // === Camera state (independent per viewport)
+  glm::mat4x4 viewMat;
+  float fov;
+  glm::vec3 viewCenter;
+  NavigateStyle navigateStyle;
+  UpDir upDir;
+  FrontDir frontDir;
+  ProjectionMode projectionMode;
+  float nearClip, farClip;
+  float moveScale;
+  ViewRelativeMode viewRelativeMode;
+  std::array<float, 4> bgColor;
+
+  // Flight state
+  bool midflight;
+  float flightStartTime, flightEndTime;
+  glm::dualquat flightTargetViewR, flightInitialViewR;
+  glm::vec3 flightTargetViewT, flightInitialViewT;
+  float flightTargetFov, flightInitialFov;
+
+  // === Pixel region (computed from grid layout + window size)
+  int pixelX, pixelY;          // lower-left corner in buffer coords
+  int pixelWidth, pixelHeight; // size in buffer pixels
+  int windowX, windowY;        // lower-left corner in window coords
+  int windowW, windowH;        // size in window pixels
+
+  // === Framebuffers (per-viewport)
+  std::shared_ptr<render::FrameBuffer> sceneBuffer;
+  std::shared_ptr<render::FrameBuffer> sceneBufferFinal;
+  std::shared_ptr<render::FrameBuffer> sceneDepthMinFrame;
+  std::shared_ptr<render::TextureBuffer> sceneColor, sceneColorFinal, sceneDepth, sceneDepthMin;
+  std::shared_ptr<render::ShaderProgram> compositePeel;
+
+  // === Methods
+
+  // Push this viewport's camera state into the global view:: variables
+  void pushViewState();
+
+  // Store the current global view state back into this viewport
+  void pullViewState();
+
+  // Recompute pixel dimensions from grid layout and window size
+  void updateLayout(int totalBufferW, int totalBufferH, int totalWindowW, int totalWindowH, int gridRows, int gridCols);
+
+  // Create or resize per-viewport framebuffers
+  void ensureBuffersAllocated();
+  void resizeBuffers();
+
+  // Reset camera to the home view for this viewport
+  void resetCameraToHomeView();
+
+  // Set navigate style with proper camera adjustment (use instead of setting navigateStyle directly)
+  void setNavigateStyle(NavigateStyle newStyle, bool animateFlight = false);
+
+  // Set up direction with proper camera adjustment (use instead of setting upDir directly)
+  void setUpDir(UpDir newUpDir, bool animateFlight = false);
+
+  // Check if screen coordinates (in window space) fall within this viewport
+  bool containsScreenCoords(float x, float y) const;
+};
+
+} // namespace polyscope

src/CMakeLists.txt

@@ -165,6 +165,7 @@ SET(SRCS
   group.cpp
   utilities.cpp
   view.cpp
+  viewport.cpp
   screenshot.cpp
   messages.cpp
   pick.cpp
@@ -352,6 +353,7 @@ SET(HEADERS
   ${INCLUDE_ROOT}/types.h
   ${INCLUDE_ROOT}/utilities.h
   ${INCLUDE_ROOT}/view.h
+  ${INCLUDE_ROOT}/viewport.h
   ${INCLUDE_ROOT}/vector_quantity.h
   ${INCLUDE_ROOT}/vector_quantity.ipp
   ${INCLUDE_ROOT}/volume_mesh.h