fix(colormap2): follow pan via GPU translation instead of freezing

A spectrogram (QCPColorMap2) froze in place while the axes scrolled during a
pan, snapping only when panning stopped — worst on large / log-Y energy
spectrograms. QCPHistogram2D (ViewportIndependent) was unaffected.

Two causes, two parts to the fix:

1. Engage the layer on pan. QCPColorMap2 is ViewportDependent: a range change
   kicks an async resample and the layer was only redrawn on the pipeline's
   finished signal. Interactive drags call markAffectedLayersDirty(), but a pan
   driven by set_range (axis synchronisation) does not — so the synced
   spectrogram was never marked dirty mid-drag and stayed frozen. Mark the
   layer dirty in onViewportChanged().

2. Translate, don't repaint. Marking dirty alone would repaint the CPU staging
   buffer and re-upload the (viewport-sized) texture every frame — exactly what
   the skip-on-translate / Metal pan optimisation avoids for line graphs. Give
   QCPColorMap2 a stallPixelOffset() override so the compositor shifts the
   existing texture by the pan delta instead (no repaint, no re-upload), the
   same fast path QCPGraph2/QCPMultiGraph use. A fresh resample / data /
   gradient change forces a real redraw (guards on mapImageInvalidated).

The zoom-rejection in stallPixelOffset is scale-aware (new
qcp::axisRangeSizeRatio): a pure pan on a log axis changes the *linear* range
size and would otherwise be misread as a zoom and rejected — which is why log-Y
spectrograms were the worst affected.

Tests (test-paintbuffer): pan dirties the colormap layer (fail before, pass
after); stallPixelOffset is non-null on a pan incl. log-Y, and null on a zoom.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: jeandet

src/painting/viewport-offset.h

@@ -2,11 +2,32 @@
 
 #include <QPointF>
 #include <QSize>
+#include <cmath>
 #include <axis/axis.h>
 #include <layoutelements/layoutelement-axisrect.h>
 
 namespace qcp {
 
+// Scale-aware size ratio of an axis' current range vs a previously rendered
+// range. For a logarithmic axis a pure pan changes the *linear* range size
+// (e.g. [1,10]->[2,20] is 2x), so comparing linear sizes would misread a pan as
+// a zoom. Use log-space size on log axes so a pure pan yields ratio == 1.
+inline double axisRangeSizeRatio(const QCPAxis* axis, const QCPRange& renderedRange)
+{
+    if (!axis)
+        return 1.0;
+    const QCPRange cur = axis->range();
+    if (axis->scaleType() == QCPAxis::stLogarithmic
+        && cur.lower > 0 && cur.upper > 0
+        && renderedRange.lower > 0 && renderedRange.upper > 0)
+    {
+        const double oldLog = std::log(renderedRange.upper) - std::log(renderedRange.lower);
+        const double curLog = std::log(cur.upper) - std::log(cur.lower);
+        return oldLog != 0.0 ? curLog / oldLog : 1.0;
+    }
+    return renderedRange.size() != 0.0 ? cur.size() / renderedRange.size() : 1.0;
+}
+
 inline QPointF computeViewportOffset(
     const QCPAxis* keyAxis, const QCPAxis* valueAxis,
     const QCPRange& oldKeyRange, const QCPRange& oldValueRange)

src/plottables/plottable-colormap2.cpp

@@ -8,6 +8,7 @@
 #include <axis/axis.h>
 #include <layer.h>
 #include <datasource/resample.h>
+#include <painting/viewport-offset.h>
 #include <Profiling.hpp>
 
 QCPColorMap2::QCPColorMap2(QCPAxis* keyAxis, QCPAxis* valueAxis)
@@ -231,6 +232,42 @@ void QCPColorMap2::onViewportChanged()
     if (!axisRect) return;
 
     mPipeline.onViewportChanged(ViewportParams::fromAxes(mKeyAxis.data(), mValueAxis.data()));
+
+    // Dirty the layer on every viewport change so a pan is handled even when it
+    // arrives via set_range (axis sync) rather than the interactive drag path
+    // (which already calls markAffectedLayersDirty). stallPixelOffset() then lets
+    // the compositor translate the existing texture instead of repainting it.
+    if (mLayer)
+        mLayer->markDirty();
+}
+
+QPointF QCPColorMap2::stallPixelOffset() const
+{
+    // Only valid when there is a rendered image to shift and no fresher one is
+    // pending (a finished resample / data / gradient change must redraw, not
+    // translate the stale texture).
+    if (!mHasRenderedRange || !mKeyAxis || !mValueAxis
+        || mRenderer.mapImage().isNull() || mRenderer.mapImageInvalidated())
+        return {};
+
+    // Pure translation only: reject genuine zoom. Scale-aware so a pure pan on a
+    // log axis (which changes the linear range size) is not misread as a zoom.
+    if (qAbs(qcp::axisRangeSizeRatio(mKeyAxis.data(), mRenderedKeyRange) - 1.0) > 1e-4
+        || qAbs(qcp::axisRangeSizeRatio(mValueAxis.data(), mRenderedValueRange) - 1.0) > 1e-4)
+        return {};
+
+    const QPointF offset = qcp::computeViewportOffset(
+        mKeyAxis.data(), mValueAxis.data(), mRenderedKeyRange, mRenderedValueRange);
+
+    // Reject if panned beyond the axis rect (texture no longer covers viewport).
+    const bool keyVert = mKeyAxis->orientation() == Qt::Vertical;
+    const double keyDim = keyVert ? mKeyAxis->axisRect()->height() : mKeyAxis->axisRect()->width();
+    const double valDim = keyVert ? mKeyAxis->axisRect()->width() : mKeyAxis->axisRect()->height();
+    if (qAbs(keyVert ? offset.y() : offset.x()) > keyDim
+        || qAbs(keyVert ? offset.x() : offset.y()) > valDim)
+        return {};
+
+    return offset;
 }
 
 bool QCPColorMap2::canProduceContent() const
@@ -277,6 +314,11 @@ void QCPColorMap2::draw(QCPPainter* painter)
     applyDefaultAntialiasingHint(painter);
     mRenderer.draw(painter, mKeyAxis.data(), mValueAxis.data(), keyRange, valueRange);
 
+    // Baseline for stallPixelOffset: the axes this image was just drawn against.
+    mRenderedKeyRange = mKeyAxis->range();
+    mRenderedValueRange = mValueAxis->range();
+    mHasRenderedRange = true;
+
     bool contoursActive = !mContourLevels.isEmpty() || mAutoContourCount > 0;
     if (contoursActive && (imageWasInvalidated || mContourCacheGen != mContourDataGen))
         updateContourGpu(resampledData);

src/plottables/plottable-colormap2.h

@@ -69,6 +69,12 @@ class QCP_LIB_DECL QCPColorMap2 : public QCPAbstractPlottable
     QCPColormapPipeline& pipeline() { return mPipeline; }
     const QCPColormapPipeline& pipeline() const { return mPipeline; }
 
+    // Pure-pan pixel offset of the last-rendered image vs the current axes, so
+    // the compositor can translate the existing texture during a pan instead of
+    // repainting + re-uploading every frame (skip-on-translate fast path).
+    [[nodiscard]] QPointF stallPixelOffset() const override;
+    [[nodiscard]] bool hasRenderedRange() const { return mHasRenderedRange; }
+
     // Contour overlay
     void setContourLevels(const QVector<double>& levels);
     [[nodiscard]] QVector<double> contourLevels() const { return mContourLevels; }
@@ -114,6 +120,10 @@ public Q_SLOTS:
     QCPColormapPipeline mPipeline;
     QCPColormapRenderer mRenderer;
 
+    // Axis ranges at the last full draw — baseline for the pan translation offset.
+    bool mHasRenderedRange = false;
+    QCPRange mRenderedKeyRange, mRenderedValueRange;
+
     // Contour overlay
     QVector<double> mContourLevels;
     QPen mContourPen{Qt::white, 1.0};

tests/auto/test-paintbuffer/test-paintbuffer.cpp

@@ -1,4 +1,6 @@
+#include <vector>
 #include "test-paintbuffer.h"
+#include <painting/viewport-offset.h>
 
 void TestPaintBuffer::init()
 {
@@ -388,3 +390,110 @@ void TestPaintBuffer::skipRepaint_bufferNotReuploadedOnPan()
     // because draw() was NOT called (mRenderedRange not updated)
     QVERIFY(!mainLayer->pixelOffset().isNull());
 }
+
+void TestPaintBuffer::colormap2_panDirtiesLayerBuffer()
+{
+    // A ViewportDependent colormap resamples asynchronously on pan. It must
+    // still dirty its layer on every viewport change so the existing image
+    // redraws repositioned to the current axes — otherwise the spectrogram
+    // freezes in place while the axes scroll until the resample lands.
+    auto* cm = new QCPColorMap2(mPlot->xAxis, mPlot->yAxis);
+    mPlot->xAxis->setRange(0, 10);
+    mPlot->yAxis->setRange(0, 100);
+    std::vector<double> x{0, 5, 10}, y{0, 50, 100};
+    std::vector<double> z(x.size() * y.size(), 1.0);
+    cm->setData(std::move(x), std::move(y), std::move(z));
+
+    mPlot->replot(QCustomPlot::rpImmediateRefresh);
+
+    auto buf = cm->layer()->mPaintBuffer.toStrongRef();
+    QVERIFY(buf);
+    buf->setContentDirty(false);  // clean slate (ignore any queued async redraw)
+
+    mPlot->xAxis->setRange(2, 12);  // pure pan
+    QVERIFY2(buf->contentDirty(),
+             "colormap2 pan did not dirty its layer — spectrogram frozen during drag");
+}
+
+void TestPaintBuffer::colormap2_panDirtiesLayerBufferLogY()
+{
+    // Same, with a logarithmic value axis (energy spectrogram): a pure pan in
+    // log space must still dirty the layer (regression for the reported stuck
+    // log-Y spectrogram).
+    auto* cm = new QCPColorMap2(mPlot->xAxis, mPlot->yAxis);
+    mPlot->xAxis->setRange(0, 10);
+    mPlot->yAxis->setScaleType(QCPAxis::stLogarithmic);
+    mPlot->yAxis->setRange(1, 1000);
+    std::vector<double> x{0, 5, 10}, y{1, 10, 100, 1000};
+    std::vector<double> z(x.size() * y.size(), 1.0);
+    cm->setData(std::move(x), std::move(y), std::move(z));
+
+    mPlot->replot(QCustomPlot::rpImmediateRefresh);
+
+    auto buf = cm->layer()->mPaintBuffer.toStrongRef();
+    QVERIFY(buf);
+    buf->setContentDirty(false);
+
+    mPlot->yAxis->setRange(2, 2000);  // pure pan in log space (×2)
+    QVERIFY2(buf->contentDirty(),
+             "colormap2 log-Y pan did not dirty its layer — spectrogram frozen during drag");
+}
+
+void TestPaintBuffer::colormap2_stallOffsetOnPan()
+{
+    // Skip-on-translate: after a pan the colormap reports a pixel offset so the
+    // compositor shifts the existing texture instead of repainting+re-uploading.
+    auto* cm = new QCPColorMap2(mPlot->xAxis, mPlot->yAxis);
+    mPlot->xAxis->setRange(0, 10);
+    mPlot->yAxis->setRange(0, 100);
+    std::vector<double> x{0, 5, 10}, y{0, 50, 100};
+    std::vector<double> z(x.size() * y.size(), 1.0);
+    cm->setData(std::move(x), std::move(y), std::move(z));
+    (void)mPlot->toPixmap(400, 300);  // synchronous draw establishes the rendered range
+    QVERIFY(cm->hasRenderedRange());
+    QCOMPARE(cm->stallPixelOffset(), QPointF(0, 0));  // no pan yet
+
+    const QCPRange oldKey(0, 10), oldVal(0, 100);
+    mPlot->xAxis->setRange(2, 12);  // pure pan
+    const QPointF expected =
+        qcp::computeViewportOffset(mPlot->xAxis, mPlot->yAxis, oldKey, oldVal);
+    QVERIFY(!expected.isNull());
+    QCOMPARE(cm->stallPixelOffset(), expected);
+    QCOMPARE(mPlot->layer("main")->pixelOffset(), expected);  // layer aggregates it
+}
+
+void TestPaintBuffer::colormap2_stallOffsetOnLogYPan()
+{
+    // A pure pan on a log Y axis must still translate (regression for the stuck
+    // log-Y energy spectrogram): the zoom check is scale-aware.
+    auto* cm = new QCPColorMap2(mPlot->xAxis, mPlot->yAxis);
+    mPlot->xAxis->setRange(0, 10);
+    mPlot->yAxis->setScaleType(QCPAxis::stLogarithmic);
+    mPlot->yAxis->setRange(1, 1000);
+    std::vector<double> x{0, 5, 10}, y{1, 10, 100, 1000};
+    std::vector<double> z(x.size() * y.size(), 1.0);
+    cm->setData(std::move(x), std::move(y), std::move(z));
+    (void)mPlot->toPixmap(400, 300);
+    QVERIFY(cm->hasRenderedRange());
+
+    mPlot->yAxis->setRange(2, 2000);  // pure pan in log space (x2)
+    QVERIFY2(!cm->stallPixelOffset().isNull(),
+             "log-Y pan misread as zoom — colormap would repaint+reupload every frame");
+}
+
+void TestPaintBuffer::colormap2_stallOffsetNullOnZoom()
+{
+    // A genuine zoom must NOT translate (texture would be wrongly scaled); fall
+    // back to a real repaint.
+    auto* cm = new QCPColorMap2(mPlot->xAxis, mPlot->yAxis);
+    mPlot->xAxis->setRange(0, 10);
+    mPlot->yAxis->setRange(0, 100);
+    std::vector<double> x{0, 5, 10}, y{0, 50, 100};
+    std::vector<double> z(x.size() * y.size(), 1.0);
+    cm->setData(std::move(x), std::move(y), std::move(z));
+    (void)mPlot->toPixmap(400, 300);
+    QVERIFY(cm->hasRenderedRange());
+
+    mPlot->xAxis->setRange(0, 20);  // zoom out 2x
+    QVERIFY(cm->stallPixelOffset().isNull());
+}

tests/auto/test-paintbuffer/test-paintbuffer.h

@@ -30,6 +30,12 @@ private slots:
     void setVisible_dirtiesLayerBuffer();
     void setVisible_noOpWhenUnchanged();
 
+    void colormap2_panDirtiesLayerBuffer();
+    void colormap2_panDirtiesLayerBufferLogY();
+    void colormap2_stallOffsetOnPan();
+    void colormap2_stallOffsetOnLogYPan();
+    void colormap2_stallOffsetNullOnZoom();
+
 private:
     QCustomPlot* mPlot;
 };