zoom-window.hpp

Go to the documentation of this file.

/*
  ZOOM-WINDOW.hpp  -  generic translation from domain to screen coordinates

  Copyright (C)         Lumiera.org
    2018,               Hermann Vosseler <Ichthyostega@web.de>

  This program is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License as
  published by the Free Software Foundation; either version 2 of
  the License, or (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

*/


#ifndef STAGE_MODEL_ZOOM_WINDOW_H
#define STAGE_MODEL_ZOOM_WINDOW_H


#include "lib/error.hpp"
#include "lib/rational.hpp"
#include "lib/time/timevalue.hpp"
#include "lib/nocopy.hpp"
#include "lib/util.hpp"

#include <limits>
#include <functional>
#include <array>


namespace stage {
namespace model {
  
  using lib::time::TimeValue;
  using lib::time::TimeSpan;
  using lib::time::Duration;
  using lib::time::TimeVar;
  using lib::time::Offset;
  using lib::time::FSecs;
  using lib::time::Time;
  
  using util::Rat;
  using util::rational_cast;
  using util::can_represent_Product;
  using util::reQuant;
  
  using util::min;
  using util::max;
  using util::sgn;
  
  namespace { 

    inline FSecs
    _FSecs (TimeValue const& timeVal)
    {
      return FSecs{_raw(timeVal), TimeValue::SCALE};
    }
    
    inline bool
    isMicroGridAligned (FSecs duration)
    {
      return 0 == Time::SCALE % duration.denominator();
    }
    
    inline double
    approx (Rat r)
      {
        return util::rational_cast<double> (r);
      }
    

    inline TimeVar
    operator+ (Time const& tval, TimeVar const& tvar)
    {
      return TimeVar(tval) += tvar;
    }
    inline TimeVar
    operator- (Time const& tval, TimeVar const& tvar)
    {
      return TimeVar(tval) -= tvar;
    }
  }
  
  
  const Rat ZOOM_MAX_RESOLUTION = 2 * TimeValue::SCALE;
  
  namespace {// initial values (rather arbitrary)
    const FSecs DEFAULT_CANVAS{23};
    const Rat   DEFAULT_METRIC{25};
    const uint  MAX_PX_WIDTH{100000};
    const FSecs MAX_TIMESPAN{_FSecs(Duration::MAX)};
    const FSecs MICRO_TICK{1_r/Time::SCALE};
    
    const int64_t LIM_HAZARD   {int64_t{1} << 40 };
    const int64_t HAZARD_DEGREE{util::ilog2(LIM_HAZARD)};
    const int64_t MAXDIM       {util::ilog2 (std::numeric_limits<int64_t>::max())};
    
    inline int
    toxicDegree (Rat poison, const int64_t THRESHOLD =HAZARD_DEGREE)
    {
      int64_t magNum = util::ilog2(abs(poison.numerator()));
      int64_t magDen = util::ilog2(abs(poison.denominator()));
      int64_t degree = max (magNum, magDen);
      return max (0, degree - THRESHOLD);
    }
  }
  
  
  
  
  
  /******************************************************/
  class ZoomWindow
    : util::NonCopyable
    {
      TimeVar startAll_, afterAll_,
              startWin_, afterWin_;
      Rat px_per_sec_;
      
      std::function<void()> changeSignal_{};
      
    public:
      ZoomWindow (uint pxWidth, TimeSpan timeline =TimeSpan{Time::ZERO, DEFAULT_CANVAS})
        : startAll_{ensureNonEmpty(timeline).start()}
        , afterAll_{ensureNonEmpty(timeline).end()}
        , startWin_{startAll_}
        , afterWin_{afterAll_}
        , px_per_sec_{establishMetric (pxWidth, startWin_, afterWin_)}
        {
          pxWidth = this->pxWidth();
          ASSERT (0 < pxWidth);
          conformWindowToMetricLimits (pxWidth);
          ensureInvariants(pxWidth);
        }
      
      ZoomWindow (TimeSpan timeline =TimeSpan{Time::ZERO, DEFAULT_CANVAS})
        : ZoomWindow{0, timeline}  //see establishMetric()
        { }
      
      TimeSpan
      overallSpan()  const
        {
          return TimeSpan{startAll_, afterAll_};
        }
      
      TimeSpan
      visible()  const
        {
          return TimeSpan{startWin_, afterWin_};
        }
      
      Rat
      px_per_sec()  const
        {
          return px_per_sec_;
        }
      
      uint
      pxWidth()  const
        {
          REQUIRE (startWin_  < afterWin_);
          return calcPixelsForDurationAtScale (px_per_sec(), afterWin_-startWin_);
        }
      
      
      
      /* === Mutators === */
      
      void
      calibrateExtension (uint pxWidth)
        {
          adaptWindowToPixels (pxWidth);
          fireChangeNotification();
        }
      
      void
      setMetric (Rat px_per_sec)
        {
          mutateScale (px_per_sec);
          fireChangeNotification();
        }
      
      void
      nudgeMetric (int steps)
        {
          setMetric(
              steps > 0 ? Rat{px_per_sec_.numerator() << steps
                             ,px_per_sec_.denominator()}
                        : Rat{px_per_sec_.numerator()
                             ,px_per_sec_.denominator() << -steps});
        }
      
      void
      setRanges (TimeSpan overall, TimeSpan visible)
        {
          mutateRanges (overall, visible);
          fireChangeNotification();
        }
      
      void
      setOverallRange (TimeSpan range)
        {
          mutateCanvas (range);
          fireChangeNotification();
        }
      
      void
      setOverallStart (TimeValue start)
        {
          mutateCanvas (TimeSpan{start, Duration(afterAll_-startAll_)});
          fireChangeNotification();
        }
      
      void
      setOverallDuration (Duration duration)
        {
          mutateCanvas (TimeSpan{startAll_, duration});
          fireChangeNotification();
        }
      
      void
      setVisibleStart (TimeValue start)
        {
          mutateWindow (TimeSpan{start, Duration(afterWin_-startWin_)});
          fireChangeNotification();
        }
      
      void
      setVisibleRange (TimeSpan newWindow)
        {
          mutateWindow (newWindow);
          fireChangeNotification();
        }

      void
      expandVisibleRange (TimeSpan target)
        {
          // Formulation: Assuming the current window was generated from TimeSpan
          //              by applying an affine-linear transformation f = a·x + b
          FSecs tarDur = _FSecs(target.end()-target.start());
          Rat a = FSecs{afterWin_-startWin_};
          Rat b = FSecs{startWin_}*_FSecs(target.end()) - FSecs{afterWin_}*_FSecs((target.start()));
          a /= tarDur;
          b /= tarDur;
          Time startNew {a * FSecs{startWin_} + b};
          Time afterNew {a * FSecs{afterWin_} + b};
          
          mutateWindow(TimeSpan{startNew, afterNew});
          fireChangeNotification();
        }
      
      void
      setVisibleDuration (Duration duration)
        {
          mutateDuration (_FSecs(duration));
          fireChangeNotification();
        }
      
      void
      offsetVisiblePos (Offset offset)
        {
          mutateWindow (TimeSpan{startWin_+offset, Duration{afterWin_-startWin_}});
          fireChangeNotification();
        }
      
      void
      nudgeVisiblePos (int64_t steps)
        {
          FSecs dur{afterWin_-startWin_};
          int64_t limPages = 2 * rational_cast<int64_t> (MAX_TIMESPAN/dur);
          steps = util::limited(-limPages, steps, +limPages);
          FSecs scroll = steps * dur/2;  // move by half window sized steps
          if (abs(scroll) < MICRO_TICK) scroll = sgn(steps) * MICRO_TICK;
          setVisibleRange (TimeSpan{Time{startWin_+Offset(scroll)}, dur});
        }
      
      void
      setVisiblePos (Time posToShow)
        {
          FSecs canvasOffset{posToShow - startAll_};
          anchorWindowAtPosition (canvasOffset);
          fireChangeNotification();
        }

      void
      setVisiblePos (Rat percentage)
        {
          FSecs canvasDuration{afterAll_-startAll_};
          anchorWindowAtPosition (scaleSafe (canvasDuration, percentage));
          fireChangeNotification();
        }
      
      void
      setVisiblePos (double percentage)
        { // use some arbitrary yet significantly large work scale
          int64_t scale = max (_raw(afterAll_-startAll_), MAX_PX_WIDTH);
          Rat factor{int64_t(scale*percentage), scale};
          setVisiblePos (factor);
        }
      
      void
      navHistory()
        {
          UNIMPLEMENTED ("navigate Zoom History");
        }
      
      
      template<class FUN>
      void
      attachChangeNotification (FUN&& trigger)
        {
          changeSignal_ = std::forward<FUN> (trigger);
        }
      
      void
      detachChangeNotification()
        {
          changeSignal_ = std::function<void()>();
        }
      
      
    private:
      void
      fireChangeNotification()
        {
          if (changeSignal_) changeSignal_();
        }
      
      
      /* === utility functions to handle dangerous fractional values === */
      
      static Rat
      detox (Rat poison)
        {
          int toxicity = toxicDegree (poison);
          return toxicity ? reQuant (poison, max (poison.denominator() >> toxicity, 64))
                          : poison;
        }
      
      static FSecs
      scaleSafe (FSecs duration, Rat factor)
        {
          if (util::can_represent_Product(duration, factor))
            // just calculate ordinary numbers...
            return duration * factor;
          else
            {
              auto guess{approx(duration) * approx (factor)};
              if (approx(MAX_TIMESPAN) < abs(guess))
                return MAX_TIMESPAN * sgn(guess); // exceeds limits of time representation => cap the result
              if (0 == guess)
                return 0;
                        struct ReductionStrategy
                          {
                            int64_t f1;  
                            int64_t u;   
                            int64_t q;   
                            int64_t f2;  
                            bool invert; 
                            
                            int64_t
                            determineLimit()
                              {
                                REQUIRE (u != 0);
                                return isFeasible()? u : 0;
                              }
                            
                            Rat
                            calculateResult()
                              {
                                REQUIRE (isFeasible());
                                f2 = reQuant (f2, q, u);
                                return invert? Rat{f2, f1}
                                             : Rat{f1, f2};
                              }
                            
                            bool
                            isFeasible()
                              {                           // Note: factors are nonzero,
                                REQUIRE (u and q and f2);//        otherwise exit after pre-check above
                                int dim_u = util::ilog2 (abs (u));
                                int dim_q = util::ilog2 (abs (q));
                                if (dim_q > dim_u) return true; // requantisation will reduce size and thus no danger
                                int dim_f = util::ilog2 (abs (f2));
                                int deltaQ = dim_u - dim_q;     // how much q must be increased to match u
                                int headroom = MAXDIM - dim_f;  // how much the counter factor f2 can be increased
                                return headroom > deltaQ;
                              }
                          };
              using Cases = std::array<ReductionStrategy, 4>;
              // There are four possible strategy configurations.
              // One case stands out, insofar this factor is guaranteed to be present:
              // because one of the numbers is a quantised Time, it has Time::SCALE as denominator,
              // maybe after cancelling out some further common integral factors
              auto [reduction,rem] = util::iDiv (Time::SCALE, duration.denominator());
              if (rem != 0) reduction = 1;  // when duration is not µ-Tick quantised
              int64_t durationQuant = duration.denominator()*reduction;
              int64_t durationTicks = duration.numerator()*reduction;
              
                         //-f1--------------------+-u-------------------+-q---------------------+-f2--------------------+-invert--
              Cases cases{{{durationTicks         , durationQuant       , factor.numerator()    , factor.denominator()  , false}
                          ,{factor.numerator()    , factor.denominator(), duration.numerator()  , duration.denominator(), false}
                          ,{duration.denominator(), duration.numerator(), factor.denominator()  , factor.numerator()    , true}
                          ,{factor.denominator()  , factor.numerator()  , duration.denominator(), duration.numerator()  , true}
                         }};
              // However, some of the other cases may yield a larger denominator to be cancelled out,
              // and thus lead to a smaller error margin. Attempt thus to find the best strategy...
              ReductionStrategy* solution{nullptr};
              int64_t maxLimit = 0;
              for (auto& candidate: cases)
                {
                  int64_t limit = candidate.determineLimit();
                  if (limit > maxLimit)
                    {
                      maxLimit = limit;
                      solution = &candidate;
                    }
                }
              
              ASSERT (solution and maxLimit > 0);
              return detox (solution->calculateResult());
            }
        }
      
      static FSecs
      addSafe (FSecs t1, FSecs t2)
        {
          if (util::can_represent_Sum (t1,t2))
            // directly calculate ordinary numbers...
            return t1 + t2;
          else
            {
              auto guess{approx(t1) + approx(t2)};
              if (approx(MAX_TIMESPAN) < abs(guess))
                return MAX_TIMESPAN * sgn(guess); // exceeds limits => cap the result
              
              // re-Quantise numbers to achieve a common denominator,
              // thus avoiding to multiply numerators for normalisation
              int64_t n1 = t1.numerator();
              int64_t d1 = t1.denominator();
              int s1 = sgn(n1)*sgn(d1);
              n1 = abs(n1); d1 = abs(d1);
              int64_t n2 = t2.numerator();
              int64_t d2 = t2.denominator();
              int s2 = sgn(n2)*sgn(d2);
              n2 = abs(n2); d2 = abs(d2);
              // quantise to smaller denominator to avoid increasing any numerator
              int64_t u = d1<d2? d1:d2;
              if (u < Time::SCALE)
                // regarding precision, quantising to µ-grid is the better solution
                u = Time::SCALE;
              else //re-quantise to common denominator more fine-grained than µ-grid
                if (s1*s2 > 0  // check numerators to detect danger of wrap-around
                    and (MAXDIM<=util::ilog2(n1) or MAXDIM<=util::ilog2(n2)))
                  u >>= 1;   // danger zone! wrap-around imminent
              
              n1 = d1==u? n1 : reQuant (n1,d1, u);
              n2 = d2==u? n2 : reQuant (n2,d2, u);
              FSecs res{s1*n1 + s2*n2, u};
              
              auto f128 = [](Rat n){ return rational_cast<long double>(n); }; // can't use the guess from above,
              ENSURE (abs (f128(res) - (f128(t1)+f128(t2))) < 1.0/u);        //  double precision is not sufficient
              return detox (res);
            }
        }
      
      
      
      
      /* === establish and maintain invariants === */
      /*
       * - oriented and non-empty windows
       * - never alter given pxWidth
       * - zoom metric factor < max zoom
       * - visibleWindow ⊂ Canvas
       */
      
      static TimeSpan
      ensureNonEmpty (TimeSpan const& span)
        {
          return TimeSpan{span.start()
                         ,util::isnil(span.duration())? Duration{DEFAULT_CANVAS}
                                                      : span.duration()
                         }.conform();
        }
      
      static void
      ENSURE_matchesExpectedPixWidth (Rat zoomFactor, FSecs duration, uint pxWidth)
        {
          auto sizeAtRequestedScale = approx(zoomFactor) * approx(duration);
          ENSURE (abs(pxWidth - sizeAtRequestedScale) <= 1
                 ,"ZoomWindow: established size or metric misses expectation "
                  "by more than 1px. %upx != %1.6f expected pixel."
                 , pxWidth, sizeAtRequestedScale);
        }
      
      static int64_t
      calcPixelsForDurationAtScale (Rat zoomFactor, FSecs duration)
        {// break down the integer division into several steps...
          auto zn = zoomFactor.numerator();
          auto zd = zoomFactor.denominator();
          auto dn = duration.numerator();
          auto dd = duration.denominator();
          auto [secs,r] = util::iDiv (dn, dd);        // split duration in full seconds and rest
          auto [px1,r1] = util::iDiv (secs*zn, zd);   // calc pixels required for full seconds
          auto [px2,r2] = util::iDiv (r*zn, dd*zd);   // calc pixels required for rest duration
          auto pxr      = (r1*dd +r2) /(dd*zd);       // and calculate integer div for combined remainders
          ENSURE (0 <= px1 and 0 <= px2 and 0<= pxr);
          return px1 + px2 + pxr;
        }
      
      static FSecs
      maxSaneWinExtension (uint pxWidth)
        {
          return min (FSecs{LIM_HAZARD * pxWidth, 1000}, MAX_TIMESPAN);
        }     // Note: denominator 1000 is additional safety margin
             //        wouldn't be necessary, but makes detox(largeTime) more precise
      
      Rat
      optimiseMetric (uint pxWidth, FSecs dur, Rat rawMetric)
        {
          using util::ilog2;
          REQUIRE (0 < pxWidth and 0 < dur and 0 < rawMetric);
          REQUIRE (isMicroGridAligned (dur));
          // circumvent numeric problems due to excessive large factors
          int64_t magDen = ilog2(rawMetric.denominator());
          int reduction = toxicDegree (rawMetric);
          int quant     = max (magDen-reduction, 16);
          //  re-quantise metric into power of two <= 2^40 (headroom 22 bit)
          //  Known to work always, since 9e-10 < metric < 2e+6
          Rat adjMetric = util::reQuant (rawMetric, int64_t(1) << quant);
          
            // Correct that metric to reproduce expected pxWidth...
           //  Retain reduced denominator, but optimise the numerator
          //   pixel = trunc{ metric*duration }
          double epsilon = std::numeric_limits<double>::epsilon()
               , dn = dur.numerator()
               , dd = dur.denominator()
               , md = adjMetric.denominator()
               , mn = (pxWidth+epsilon)*md*dd/dn;
          // construct optimised zoom metric result
          int64_t num = mn, den = adjMetric.denominator();
          if (epsilon < mn - num)
            {// optimisation found inter-grid result -- increase precision
              int headroom = max (1, HAZARD_DEGREE - max (ilog2(num), ilog2(den)));
              int64_t scale = int64_t(1) << headroom;
              num = scale*mn;                 // quantise again with increased resolution
              den = scale*den;               //  at least factor 2 to get some improvement
              if (pxWidth > dn/dd*num/den)  //   If still some remaining error....
                ++num; // round up to be sure to hit the next higher pixel count
            }
          adjMetric = Rat{num, den};
          ENSURE (pxWidth == calcPixelsForDurationAtScale (adjMetric, dur));
          double impliedDur = double(pxWidth)*den/num;
          double relError   = abs(dn/dd /impliedDur -1);
          double quantErr   = 1.0/(num-1);
          ENSURE (quantErr  > relError, "metric misses duration by "
                  "%3.2f%% > %3.2f%% (=relative quantisation error)"
                 ,100*relError, 100.0*quantErr);
          return adjMetric;
        }
      
      
      static Rat
      establishMetric (uint pxWidth, Time startWin, Time afterWin)
        {
          REQUIRE (startWin < afterWin);
          FSecs dur = _FSecs(afterWin-startWin);
          if (pxWidth == 0 or pxWidth > MAX_PX_WIDTH) // default to sane pixel width
              pxWidth = max<uint> (1, rational_cast<uint> (DEFAULT_METRIC * dur));
          Rat metric = Rat(pxWidth) / dur;
          // rational arithmetic ensures we can always reproduce the pxWidth
          ENSURE (pxWidth == calcPixelsForDurationAtScale (metric, dur));
          ENSURE (0 < metric);
          return metric;
        }
      
      void
      conformWindowToMetric (Rat changedMetric)
        {
          REQUIRE (changedMetric > 0);
          REQUIRE (afterWin_> startWin_);
          FSecs dur{afterWin_-startWin_};
          uint pxWidth = calcPixelsForDurationAtScale (px_per_sec_, dur);
          dur = Rat(pxWidth) / detox (changedMetric);
          dur = min (dur, MAX_TIMESPAN);// limit maximum window size
          dur = max (dur, MICRO_TICK); //  prevent window going void
          TimeVar timeDur{Duration{dur}};
          // prefer bias towards increased window instead of increased metric
          if (not isMicroGridAligned (dur))
            timeDur = timeDur + TimeValue(1);
          // resize window relative to anchor point
          placeWindowRelativeToAnchor (dur);
          establishWindowDuration (Duration{timeDur});
          // re-check metric to maintain precise pxWidth
          px_per_sec_ = conformMetricToWindow (pxWidth);
          ENSURE (_FSecs(afterWin_-startWin_) <= MAX_TIMESPAN);
          ENSURE_matchesExpectedPixWidth (changedMetric, afterWin_-startWin_, pxWidth);
        }
      
      Rat
      conformMetricToWindow (uint pxWidth)
        {
          REQUIRE (pxWidth > 0);
          REQUIRE (afterWin_> startWin_);
          FSecs dur{afterWin_-startWin_};
          Rat adjMetric = Rat(pxWidth) / dur;
          if (not toxicDegree(adjMetric)
              and pxWidth == calcPixelsForDurationAtScale (adjMetric, dur))
            return adjMetric;
          else
            return optimiseMetric(pxWidth, dur, adjMetric);
        }
      
      void
      conformWindowToMetricLimits (uint pxWidth)
        {
          REQUIRE (pxWidth > 0);
          FSecs dur{afterWin_-startWin_};
          if (dur > maxSaneWinExtension (pxWidth))
            {
              dur = maxSaneWinExtension (pxWidth);
              placeWindowRelativeToAnchor (dur);
              establishWindowDuration (dur);
            }
        }
      
      void
      conformWindowToCanvas()
        {
          FSecs dur{afterWin_-startWin_};
          REQUIRE (dur <= MAX_TIMESPAN);
          startAll_ = max (startAll_, Time::MIN);
          afterAll_ = min (afterAll_, Time::MAX);
          if (dur <= _FSecs(afterAll_-startAll_))
            {//possibly shift into current canvas
              if (afterWin_ > afterAll_)
                {
                  Offset shift{afterWin_ - afterAll_};
                  startWin_ -= shift;
                  afterWin_ -= shift;
                }
              else
              if (startWin_ < startAll_)
                {
                  Offset shift{startAll_ - startWin_};
                  startWin_ += shift;
                  afterWin_ += shift;
                }
            }
          else
            {//need to cap window to fit into canvas
              startWin_ = startAll_;
              afterWin_ = afterAll_;
            }
          ENSURE (startAll_ <= startWin_);
          ENSURE (afterWin_ <= afterAll_);
          ENSURE (Time::MIN <= startWin_);
          ENSURE (afterWin_ <= Time::MAX);
        }
      
      void
      conformToBounds (Rat changedMetric)
        {
          if (changedMetric > ZOOM_MAX_RESOLUTION)
            {
              changedMetric = ZOOM_MAX_RESOLUTION;
              conformWindowToMetric (changedMetric);
            }
          startAll_ = min (startAll_, startWin_);
          afterAll_ = max (afterAll_, afterWin_);
          ENSURE (Time::MIN <= startWin_);
          ENSURE (afterWin_ <= Time::MAX);
          ENSURE (startAll_ <= startWin_);
          ENSURE (afterWin_ <= afterAll_);
          ENSURE (px_per_sec_ <= ZOOM_MAX_RESOLUTION);
          ENSURE (px_per_sec_ <= changedMetric); // bias
        }
      
      void
      ensureInvariants(uint px =0)
        {
          if (px==0) px = pxWidth();
          conformWindowToCanvas();
          px_per_sec_ = conformMetricToWindow (px);
          conformToBounds (px_per_sec_);
        }
      
      
      
      /* === adjust and coordinate window parameters === */
      
      void
      mutateCanvas (TimeSpan canvas)
        {
          startAll_ = ensureNonEmpty(canvas).start();
          afterAll_ = ensureNonEmpty(canvas).end();
          ensureInvariants();
        }
      
      void
      mutateWindow (TimeSpan window)
        {
          uint px{pxWidth()};
          startWin_ = ensureNonEmpty(window).start();
          afterWin_ = ensureNonEmpty(window).end();
          conformWindowToMetricLimits (px);
          startAll_ = min (startAll_, startWin_);
          afterAll_ = max (afterAll_, afterWin_);
          ensureInvariants (px);
        }
      
      void
      mutateRanges (TimeSpan canvas, TimeSpan window)
        {
          uint px{pxWidth()};
          startAll_ = ensureNonEmpty(canvas).start();
          afterAll_ = ensureNonEmpty(canvas).end();
          startWin_ = ensureNonEmpty(window).start();
          afterWin_ = ensureNonEmpty(window).end();
          conformWindowToMetricLimits (px);
          ensureInvariants (px);
        }
      
      void
      mutateScale (Rat changedMetric)
        {
          uint px{pxWidth()};
          changedMetric = max (changedMetric, px / maxSaneWinExtension(px));
          changedMetric = min (detox(changedMetric), ZOOM_MAX_RESOLUTION);
          if (changedMetric == px_per_sec_) return;
          conformWindowToMetric (changedMetric);
          ensureInvariants (px);
        }
      
      void
      mutateDuration (FSecs duration, uint px =0)
        {
          if (px==0)
            px = pxWidth();
          if (duration <= 0)
            duration = DEFAULT_CANVAS;
          else if (duration > maxSaneWinExtension (px))
            duration = maxSaneWinExtension (px);
          placeWindowRelativeToAnchor (duration);
          establishWindowDuration (duration);
          px_per_sec_ = conformMetricToWindow (px);
          ensureInvariants (px);
        }
      
      void
      adaptWindowToPixels (uint pxWidth)
        {
          pxWidth = util::limited (1u, pxWidth, MAX_PX_WIDTH);
          FSecs adaptedWindow{Rat{pxWidth} / px_per_sec_};
          adaptedWindow = max (adaptedWindow, MICRO_TICK); // prevent void window
          adaptedWindow = min (adaptedWindow, maxSaneWinExtension (pxWidth));
          establishWindowDuration (adaptedWindow);
          ensureInvariants (pxWidth);
        }
      
      void
      anchorWindowAtPosition (FSecs canvasOffset)
        {
          REQUIRE (afterWin_ > startWin_);
          REQUIRE (afterAll_ > startAll_);
          uint px{pxWidth()};
          FSecs duration{afterWin_-startWin_};
          Rat posFactor = canvasOffset / FSecs{afterAll_-startAll_};
          posFactor = parabolicAnchorRule (posFactor); // also limited 0...1
          FSecs partBeforeAnchor = scaleSafe (duration, posFactor);
          startWin_ = startAll_ + Offset{addSafe (canvasOffset, -partBeforeAnchor)};
          establishWindowDuration (duration);
          startAll_ = min (startAll_, startWin_);
          afterAll_ = max (afterAll_, afterWin_);
          ensureInvariants (px);
        }
      
      
      void
      placeWindowRelativeToAnchor (FSecs duration)
        {
          FSecs partBeforeAnchor = scaleSafe(duration, relativeAnchor());
          startWin_ = Time{anchorPoint()} - Time{partBeforeAnchor};
        }
      
      void
      establishWindowDuration (Duration duration)
        {
          if (startWin_<= Time::MAX - duration)
              afterWin_ = startWin_ + duration;
          else
            {
              startWin_ = Time::MAX - duration;
              afterWin_ = Time::MAX;
            }
        }
      
      
      
      FSecs
      anchorPoint()  const
        {
          return startWin_ + Offset{scaleSafe (afterWin_-startWin_, relativeAnchor())};
        }
      
      Rat
      relativeAnchor()  const
        {
          // the visible window itself has to fit in, which reduces the action range
          FSecs possibleRange = (afterAll_-startAll_) - (afterWin_-startWin_);
          if (possibleRange <= 0) // if there is no room for scrolling...
            return 1_r/2;        //  then anchor zooming in the middle
          
          // use a 3rd degree parabola to favour positions in the middle
          Rat posFactor = FSecs{startWin_-startAll_} / possibleRange;
          return parabolicAnchorRule (posFactor);
        }
      
      static Rat
      parabolicAnchorRule (Rat posFactor)
        {
          posFactor = util::limited (0, posFactor, 1);
          if (toxicDegree(posFactor, 20))      //  prevent integer wrap
            posFactor = util::reQuant(posFactor, 1 << 20);
          posFactor = (2*posFactor - 1);             // -1 ... +1
          posFactor = posFactor*posFactor*posFactor; // -1 ... +1 but accelerating towards boundaries
          posFactor = (posFactor + 1) / 2;           //  0 ... 1
          posFactor = util::limited (0, posFactor, 1);
          return detox (posFactor);
        }
    };
  
  
  
}} // namespace stage::model
#endif /*STAGE_MODEL_ZOOM_WINDOW_H*/