fix: prevent viewport export clipping at high resolutions (#1311)

The viewport export renders once and reads back immediately. The VkSplat renderer sizes its per-frame visible-primitive and tile-instance scratch from deferred, one-frame-late high-water marks, so the first render at a new viewpoint/resolution can exceed them and render capacity-clamped (the depth/tile-ordered tail is dropped). That produces the curved clip that worsens with resolution. The live viewport hides this because it self-heals on the next frame, but a one-shot export saves the clamped frame; re-exporting from the same view works because the marks have since grown.

Drive that self-heal synchronously for one-shot captures: re-render the Preview slot until the renderer confirms the previous pass produced complete, unclamped content (bounded by a max pass count), then read back. A new VksplatViewportRenderer::previewCaptureSettled() signal reports this from the deferred poll, rejecting the macro warm-up frame and requiring the steady-state chain; a pass>=1 guard keeps the signal tied to the current view so the tiled path stays correct. Settling is scoped to the export capture overloads, leaving film-strip thumbnails, asset previews, and depth captures on single-render behavior.

Closes #1304

Co-authored-by: Oz <oz-agent@warp.dev>

Author: jacobvanbeets

src/visualizer/rendering/rendering_manager.hpp

@@ -550,7 +550,8 @@ namespace lfs::vis {
             std::optional<bool> orthographic_override,
             std::optional<float> ortho_scale_override,
             std::optional<glm::vec3> background_color_override,
-            PreviewImageReadback readback);
+            PreviewImageReadback readback,
+            bool settle_capacity = false);
         [[nodiscard]] std::expected<void, std::string> renderPreviewImageToPreviewSlotWithState(
             SceneManager* scene_manager,
             const lfs::core::SplatData& model,
@@ -567,7 +568,8 @@ namespace lfs::vis {
             std::optional<bool> orthographic_override,
             std::optional<float> ortho_scale_override,
             std::optional<glm::vec3> background_color_override,
-            std::optional<bool> transparent_background_override);
+            std::optional<bool> transparent_background_override,
+            bool settle_capacity = false);
         [[nodiscard]] std::expected<void, std::string> renderDepthCaptureToPreviewSlotWithState(
             SceneManager* scene_manager,
             const lfs::core::SplatData& model,

src/visualizer/rendering/rendering_manager_viewport.cpp

@@ -26,6 +26,11 @@ namespace lfs::vis {
         constexpr std::size_t kMaxNativePreviewPixelStateBytes =
             (std::size_t{4} << 30) - (std::size_t{64} << 20);
         constexpr float kMaxValidDepth = 1e9f;
+        // Upper bound on the synchronous capacity self-heal passes a one-shot
+        // preview/export capture will run before reading back (see
+        // renderPreviewImageToPreviewSlotWithState). Typical convergence is
+        // 2-4 passes; the cap only guards a pathological non-converging case.
+        constexpr int kMaxPreviewSettlePasses = 8;
 
         [[nodiscard]] std::optional<std::shared_lock<std::shared_mutex>> acquireLiveModelRenderLock(
             const SceneManager* const scene_manager) {
@@ -572,7 +577,8 @@ namespace lfs::vis {
             orthographic_override,
             ortho_scale_override,
             background_color_override,
-            PreviewImageReadback::UInt8Rgb);
+            PreviewImageReadback::UInt8Rgb,
+            /*settle_capacity=*/true);
     }
 
     std::shared_ptr<lfs::core::Tensor> RenderingManager::renderPreviewImageRgba8(SceneManager* const scene_manager,
@@ -624,7 +630,8 @@ namespace lfs::vis {
             orthographic_override,
             ortho_scale_override,
             std::nullopt,
-            PreviewImageReadback::UInt8Rgba);
+            PreviewImageReadback::UInt8Rgba,
+            /*settle_capacity=*/true);
     }
 
     std::shared_ptr<lfs::core::Tensor> RenderingManager::renderPreviewImage(const lfs::core::SplatData& model,
@@ -787,7 +794,8 @@ namespace lfs::vis {
         std::optional<bool> orthographic_override,
         std::optional<float> ortho_scale_override,
         std::optional<glm::vec3> background_color_override,
-        const PreviewImageReadback readback) {
+        const PreviewImageReadback readback,
+        const bool settle_capacity) {
         const auto readback_config =
             previewImageReadbackConfig(readback, background_color_override.has_value());
 
@@ -807,7 +815,8 @@ namespace lfs::vis {
             orthographic_override,
             ortho_scale_override,
             background_color_override,
-            readback_config.transparent_background_override);
+            readback_config.transparent_background_override,
+            settle_capacity);
         if (!rendered) {
             LOG_ERROR("Gaussian preview image render failed: {}", rendered.error());
             return {};
@@ -852,7 +861,8 @@ namespace lfs::vis {
         std::optional<bool> orthographic_override,
         std::optional<float> ortho_scale_override,
         std::optional<glm::vec3> background_color_override,
-        std::optional<bool> transparent_background_override) {
+        std::optional<bool> transparent_background_override,
+        const bool settle_capacity) {
         if (width <= 0 || height <= 0) {
             return std::unexpected("invalid preview render dimensions");
         }
@@ -922,15 +932,34 @@ namespace lfs::vis {
             vksplat_viewport_renderer_ = std::make_unique<VksplatViewportRenderer>();
         }
 
-        auto render_result = vksplat_viewport_renderer_->render(
-            *last_vulkan_context_,
-            model,
-            request,
-            false,
-            VksplatViewportRenderer::OutputSlot::Preview,
-            false);
-        if (!render_result) {
-            return std::unexpected(render_result.error());
+        // One-shot preview/export captures read the image back immediately, so
+        // they cannot rely on the interactive viewport's one-frame capacity
+        // self-heal. The renderer sizes per-frame scratch (visible-primitive and
+        // tile-instance capacity) from deferred, one-frame-late high-water marks;
+        // the first render at a new viewpoint/resolution — e.g. a high-res export
+        // after the live viewport established marks at a smaller size — can clamp
+        // the depth/tile-ordered tail, dropping content along an irregular edge.
+        // Re-render the Preview slot until the renderer confirms the previous
+        // pass produced complete, unclamped content (each pass grows the marks
+        // via the deferred readback). The pass >= 1 guard ensures the settle
+        // signal reflects this exact view (critical for the tiled path, where
+        // each tile is a different sub-view); max_passes bounds a pathological
+        // case. Non-settling callers (e.g. depth capture) render exactly once.
+        const int max_passes = settle_capacity ? kMaxPreviewSettlePasses : 1;
+        for (int pass = 0; pass < max_passes; ++pass) {
+            auto render_result = vksplat_viewport_renderer_->render(
+                *last_vulkan_context_,
+                model,
+                request,
+                false,
+                VksplatViewportRenderer::OutputSlot::Preview,
+                false);
+            if (!render_result) {
+                return std::unexpected(render_result.error());
+            }
+            if (pass >= 1 && vksplat_viewport_renderer_->previewCaptureSettled()) {
+                break;
+            }
         }
         return {};
     }
@@ -1000,7 +1029,8 @@ namespace lfs::vis {
                 orthographic_override,
                 ortho_scale_override,
                 background_color_override,
-                readback_config.transparent_background_override);
+                readback_config.transparent_background_override,
+                /*settle_capacity=*/true);
             if (!rendered) {
                 LOG_TRACE("Gaussian preview tiled render failed at tile y={} height={}: {}",
                           tile_y,

src/visualizer/rendering/vksplat_viewport_renderer.cpp

@@ -6069,7 +6069,12 @@ namespace lfs::vis {
         if (auto ok = waitForRingSlot(ring_slot, "render"); !ok) {
             return std::unexpected(ok.error());
         }
+        // Track whether each deferred capacity readback produced fresh stats
+        // this frame; feeds the one-shot-capture settle signal computed below.
+        bool visibility_stats_polled = false;
+        bool instance_stats_polled = false;
         if (const auto visibility_stats = renderer_.pollDeferredPrimitiveVisibilityStats()) {
+            visibility_stats_polled = true;
             const double ratio = visibility_stats->num_splats == 0
                                      ? 0.0
                                      : static_cast<double>(visibility_stats->visible_count) /
@@ -6097,6 +6102,7 @@ namespace lfs::vis {
             }
         }
         if (const auto macro_stats = renderer_.pollDeferredMacroInstanceStats()) {
+            instance_stats_polled = true;
             // One frame stale; drives the capacity high-water mark. A clamped
             // frame (raw > clamped) grows the mark so the next frames render
             // complete content.
@@ -6114,6 +6120,30 @@ namespace lfs::vis {
                          macro_stats->instance_count);
             }
         }
+        {
+            // Settle signal for one-shot preview/export captures. The interactive
+            // loop tolerates a capacity-clamped frame because it self-heals on the
+            // next frame; a single-shot capture reads back immediately, so it must
+            // not present a clamped (partial) frame. Mark "settled" only when the
+            // deferred readback of the previous render — which must have used the
+            // same steady-state chain the next pass will use, so a warm-up frame is
+            // rejected — reports complete, unclamped content.
+            const bool config_uses_macro =
+                !request.gut && renderer_.supportsFloat16Storage() &&
+                !synchronize_input_upload && !depth_capture_mode_;
+            const bool stats_complete =
+                visibility_stats_polled && (!config_uses_macro || instance_stats_polled);
+            const bool clamp_observed =
+                visible_clamp_pending_ || (config_uses_macro && instance_clamp_pending_);
+            // last_render_used_macro_chain_ still reflects the just-polled
+            // (previous) render here; it is updated for the current render only
+            // after rasterization. Requiring it to match the steady-state chain
+            // rejects the legacy warm-up frame as a convergence point.
+            const bool observed_matches_steady_state =
+                last_render_used_macro_chain_ == config_uses_macro;
+            last_preview_capture_settled_ =
+                stats_complete && !clamp_observed && observed_matches_steady_state;
+        }
         if (const auto lod_stats = renderer_.pollDeferredLodSelectionStats()) {
             gpu_lod_last_candidate_count_ = lod_stats->candidate_count;
             gpu_lod_last_overflow_count_ = lod_stats->overflow_count;

src/visualizer/rendering/vksplat_viewport_renderer.hpp

@@ -214,6 +214,13 @@ namespace lfs::vis {
         };
         [[nodiscard]] GpuLodSelectionStatus gpuLodSelectionStatus() const;
 
+        // True when the most recent render's start-of-frame deferred poll
+        // confirmed the previously rendered frame produced complete, unclamped
+        // content using the steady-state rasterizer chain. One-shot preview/
+        // export captures poll this to avoid reading back a capacity-clamped
+        // (partial) frame; see RenderingManager::renderPreviewImageToPreviewSlotWithState.
+        [[nodiscard]] bool previewCaptureSettled() const { return last_preview_capture_settled_; }
+
     private:
         struct ComposePipeline;
         struct InputBindingResult {
@@ -544,6 +551,13 @@ namespace lfs::vis {
         // keeps frames scheduled while idle so the capacity self-heal converges.
         bool visible_clamp_pending_ = false;
         bool instance_clamp_pending_ = false;
+        // Set each render from the start-of-frame deferred poll: true once a
+        // representative frame (one that used the same steady-state rasterizer
+        // chain the next pass will use) is confirmed complete and unclamped.
+        // Drives the synchronous capacity self-heal used by one-shot preview/
+        // export captures, which cannot tolerate the interactive loop's
+        // one-frame clamp transient.
+        bool last_preview_capture_settled_ = false;
 
         // Fallback CUDA-backed input buffers for models that are not already
         // backed by Vulkan-external tensor storage. Direct Vulkan-external