libs/ardour/ardour/tempo.h

   1 /*
   2     Copyright (C) 2000 Paul Davis
   3
   4     This program is free software; you can redistribute it and/or modify
   5     it under the terms of the GNU General Public License as published by
   6     the Free Software Foundation; either version 2 of the License, or
   7     (at your option) any later version.
   8
   9     This program is distributed in the hope that it will be useful,
  10     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12     GNU General Public License for more details.
  13
  14     You should have received a copy of the GNU General Public License
  15     along with this program; if not, write to the Free Software
  16     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17
  18 */
  19
  20 #ifndef __ardour_tempo_h__
  21 #define __ardour_tempo_h__
  22
  23 #include <list>
  24 #include <string>
  25 #include <vector>
  26 #include <cmath>
  27 #include <glibmm/threads.h>
  28
  29 #include "pbd/undo.h"
  30
  31 #include "pbd/stateful.h"
  32 #include "pbd/statefuldestructible.h"
  33
  34 #include "evoral/Beats.hpp"
  35
  36 #include "ardour/ardour.h"
  37
  38 class BBTTest;
  39 class FrameposPlusBeatsTest;
  40 class TempoTest;
  41 class XMLNode;
  42
  43 namespace ARDOUR {
  44
  45 class Meter;
  46 class TempoMap;
  47
  48 /** Tempo, the speed at which musical time progresses (BPM). */
  49 class LIBARDOUR_API Tempo {
  50   public:
  51         /**
  52          * @param bpm Beats Per Minute
  53          * @param type Note Type (default `4': quarter note)
  54          */
  55         Tempo (double bpm, double type=4.0) // defaulting to quarter note
  56                 : _beats_per_minute (bpm), _note_type(type) {}
  57
  58         double beats_per_minute () const { return _beats_per_minute; }
  59
  60         double ticks_per_minute () const { return _beats_per_minute * Timecode::BBT_Time::ticks_per_beat;}
  61         double note_type () const { return _note_type;}
  62         /** audio samples per beat
  63          * @param sr samplerate
  64          */
  65         double frames_per_beat (framecnt_t sr) const {
  66                 return (60.0 * sr) / _beats_per_minute;
  67         }
  68
  69   protected:
  70         double _beats_per_minute;
  71         double _note_type;
  72 };
  73
  74 /** Meter, or time signature (beats per bar, and which note type is a beat). */
  75 class LIBARDOUR_API Meter {
  76   public:
  77         Meter (double dpb, double bt)
  78                 : _divisions_per_bar (dpb), _note_type (bt) {}
  79
  80         double divisions_per_bar () const { return _divisions_per_bar; }
  81         double note_divisor() const { return _note_type; }
  82
  83         double frames_per_bar (const Tempo&, framecnt_t sr) const;
  84         double frames_per_grid (const Tempo&, framecnt_t sr) const;
  85
  86   protected:
  87         /** The number of divisions in a bar.  This is a floating point value because
  88             there are musical traditions on our planet that do not limit
  89             themselves to integral numbers of beats per bar.
  90         */
  91         double _divisions_per_bar;
  92
  93         /** The type of "note" that a division represents.  For example, 4.0 is
  94             a quarter (crotchet) note, 8.0 is an eighth (quaver) note, etc.
  95         */
  96         double _note_type;
  97 };
  98
  99 /** A section of timeline with a certain Tempo or Meter. */
 100 class LIBARDOUR_API MetricSection {
 101   public:
 102         MetricSection (double start)
 103                 : _beat (start), _frame (0), _movable (true), _position_lock_style (MusicTime) {}
 104         MetricSection (framepos_t frame)
 105                 : _beat (0), _frame (frame), _movable (true), _position_lock_style (MusicTime) {}
 106
 107         virtual ~MetricSection() {}
 108
 109         const double start () const { return _beat; }
 110         const double& beat () const { return _beat; }
 111         void set_beat (double beat) { _beat = beat;}
 112
 113         framepos_t frame() const { return _frame; }
 114         virtual void set_frame (framepos_t f) {
 115                 _frame = f;
 116         }
 117
 118         void set_movable (bool yn) { _movable = yn; }
 119         bool movable() const { return _movable; }
 120
 121         /* MeterSections are not stateful in the full sense,
 122            but we do want them to control their own
 123            XML state information.
 124         */
 125         virtual XMLNode& get_state() const = 0;
 126
 127         PositionLockStyle position_lock_style () const { return _position_lock_style; }
 128         void set_position_lock_style (PositionLockStyle ps) { _position_lock_style = ps; }
 129
 130 private:
 131         double             _beat;
 132         framepos_t         _frame;
 133         bool               _movable;
 134         PositionLockStyle  _position_lock_style;
 135 };
 136
 137 /** A section of timeline with a certain Meter. */
 138 class LIBARDOUR_API MeterSection : public MetricSection, public Meter {
 139   public:
 140         MeterSection (double start, const Timecode::BBT_Time& bbt, double bpb, double note_type)
 141                 : MetricSection (start), Meter (bpb, note_type), _bbt (bbt) {}
 142         MeterSection (framepos_t frame, double bpb, double note_type)
 143                 : MetricSection (frame), Meter (bpb, note_type) {}
 144         MeterSection (const XMLNode&);
 145
 146         static const std::string xml_state_node_name;
 147
 148         XMLNode& get_state() const;
 149
 150         void set_start (std::pair<double, Timecode::BBT_Time>& w) {
 151                 set_beat (w.first);
 152                 _bbt = w.second;
 153         }
 154         const Timecode::BBT_Time& bbt() const { return _bbt; }
 155 private:
 156         Timecode::BBT_Time _bbt;
 157 };
 158
 159 /** A section of timeline with a certain Tempo. */
 160 class LIBARDOUR_API TempoSection : public MetricSection, public Tempo {
 161   public:
 162         enum Type {
 163                 Ramp,
 164                 Constant,
 165         };
 166
 167         TempoSection (const double& start, double qpm, double note_type, Type tempo_type)
 168                 : MetricSection (start), Tempo (qpm, note_type), _bar_offset (-1.0), _type (tempo_type)  {}
 169         TempoSection (framepos_t frame, double qpm, double note_type, Type tempo_type)
 170                 : MetricSection (frame), Tempo (qpm, note_type), _bar_offset (-1.0), _type (tempo_type) {}
 171         TempoSection (const XMLNode&);
 172
 173         static const std::string xml_state_node_name;
 174
 175         XMLNode& get_state() const;
 176
 177         void set_start (const double& w) {
 178                 set_beat (w);
 179         }
 180
 181         void update_bar_offset_from_bbt (const Meter&);
 182         void update_bbt_time_from_bar_offset (const Meter&);
 183         double bar_offset() const { return _bar_offset; }
 184
 185         void set_type (Type type);
 186         Type type () const { return _type; }
 187
 188         double tempo_at_frame (framepos_t frame, double end_bpm, framepos_t end_frame, framecnt_t frame_rate) const;
 189         framepos_t frame_at_tempo (double tempo, double end_bpm, framepos_t end_frame, framecnt_t frame_rate) const;
 190
 191         double tick_at_frame (framepos_t frame, double end_bpm, framepos_t end_frame, framecnt_t frame_rate) const;
 192         framepos_t frame_at_tick (double tick, double end_bpm, framepos_t end_frame, framecnt_t frame_rate) const;
 193
 194         double beat_at_frame (framepos_t frame, double end_bpm, framepos_t end_frame, framecnt_t frame_rate) const;
 195         framepos_t frame_at_beat (double beat, double end_bpm, framepos_t end_frame, framecnt_t frame_rate) const;
 196
 197         Timecode::BBT_Time legacy_bbt () { return _legacy_bbt; }
 198
 199   private:
 200
 201         framecnt_t minute_to_frame (double time, framecnt_t frame_rate) const;
 202         double frame_to_minute (framecnt_t frame, framecnt_t frame_rate) const;
 203
 204         /*  tempo ramp functions. zero-based with time in minutes,
 205          * 'tick tempo' in ticks per minute and tempo in bpm.
 206          *  time relative to section start.
 207          */
 208         double c_func (double end_tpm, double end_time) const;
 209         double a_func (double end_tpm, double c_func) const;
 210
 211         double tick_tempo_at_time (double time, double end_tpm, double end_time) const;
 212         double time_at_tick_tempo (double tick_tempo, double end_tpm, double end_time) const;
 213
 214         double tick_at_time (double time, double end_tpm, double end_time) const;
 215         double time_at_tick (double tick, double end_tpm, double end_time) const;
 216
 217         double beat_at_time (double time, double end_tpm, double end_time) const;
 218         double time_at_beat (double beat, double end_tpm, double end_time) const;
 219
 220         /* this value provides a fractional offset into the bar in which
 221            the tempo section is located in. A value of 0.0 indicates that
 222            it occurs on the first beat of the bar, a value of 0.5 indicates
 223            that it occurs halfway through the bar and so on.
 224
 225            this enables us to keep the tempo change at the same relative
 226            position within the bar if/when the meter changes.
 227         */
 228         double _bar_offset;
 229         Type _type;
 230         Timecode::BBT_Time _legacy_bbt;
 231 };
 232
 233 typedef std::list<MetricSection*> Metrics;
 234
 235 /** Helper class to keep track of the Meter *AND* Tempo in effect
 236     at a given point in time.
 237 */
 238 class LIBARDOUR_API TempoMetric {
 239   public:
 240         TempoMetric (const Meter& m, const Tempo& t)
 241                 : _meter (&m), _tempo (&t), _frame (0) {}
 242
 243         void set_tempo (const Tempo& t)              { _tempo = &t; }
 244         void set_meter (const Meter& m)              { _meter = &m; }
 245         void set_frame (framepos_t f)                { _frame = f; }
 246         void set_start (const double& t)             { _start = t; }
 247
 248         void set_metric (const MetricSection* section) {
 249                 const MeterSection* meter;
 250                 const TempoSection* tempo;
 251                 if ((meter = dynamic_cast<const MeterSection*>(section))) {
 252                         set_meter(*meter);
 253                 } else if ((tempo = dynamic_cast<const TempoSection*>(section))) {
 254                         set_tempo(*tempo);
 255                 }
 256
 257                 set_frame(section->frame());
 258                 set_start(section->start());
 259         }
 260
 261         const Meter&              meter() const { return *_meter; }
 262         const Tempo&              tempo() const { return *_tempo; }
 263         framepos_t                frame() const { return _frame; }
 264         const double& start() const { return _start; }
 265
 266   private:
 267         const Meter*       _meter;
 268         const Tempo*       _tempo;
 269         framepos_t         _frame;
 270         double             _start;
 271 };
 272
 273 /** Tempo Map - mapping of timecode to musical time.
 274  * convert audio-samples, sample-rate to Bar/Beat/Tick, Meter/Tempo
 275  */
 276 class LIBARDOUR_API TempoMap : public PBD::StatefulDestructible
 277 {
 278   public:
 279         TempoMap (framecnt_t frame_rate);
 280         ~TempoMap();
 281
 282         /* measure-based stuff */
 283
 284         enum BBTPointType {
 285                 Bar,
 286                 Beat,
 287         };
 288
 289         struct BBTPoint {
 290                 framepos_t          frame;
 291                 const MeterSection* meter;
 292                 const Tempo* tempo;
 293                 uint32_t            bar;
 294                 uint32_t            beat;
 295
 296                 BBTPoint (const MeterSection& m, const Tempo& t, framepos_t f,
 297                           uint32_t b, uint32_t e)
 298                         : frame (f), meter (&m), tempo (&t), bar (b), beat (e) {}
 299
 300                 Timecode::BBT_Time bbt() const { return Timecode::BBT_Time (bar, beat, 0); }
 301                 operator Timecode::BBT_Time() const { return bbt(); }
 302                 operator framepos_t() const { return frame; }
 303                 bool is_bar() const { return beat == 1; }
 304         };
 305
 306         template<class T> void apply_with_metrics (T& obj, void (T::*method)(const Metrics&)) {
 307                 Glib::Threads::RWLock::ReaderLock lm (lock);
 308                 (obj.*method)(metrics);
 309         }
 310
 311         void get_grid (std::vector<BBTPoint>&,
 312                        framepos_t start, framepos_t end);
 313
 314         /* TEMPO- AND METER-SENSITIVE FUNCTIONS
 315
 316            bbt_time(), beat_at_frame(), frame_at_beat(), tick_at_frame(),
 317            frame_at_tick(),frame_time() and bbt_duration_at()
 318            are all sensitive to tempo and meter, and will give answers
 319            that align with the grid formed by tempo and meter sections.
 320
 321            They SHOULD NOT be used to determine the position of events
 322            whose location is canonically defined in beats.
 323         */
 324
 325         void bbt_time (framepos_t when, Timecode::BBT_Time&);
 326
 327         double tick_at_frame (framecnt_t frame) const;
 328         framecnt_t frame_at_tick (double tick) const;
 329
 330         double beat_at_frame (framecnt_t frame) const;
 331         framecnt_t frame_at_beat (double beat) const;
 332
 333         framepos_t frame_time (const Timecode::BBT_Time&);
 334         framecnt_t bbt_duration_at (framepos_t, const Timecode::BBT_Time&, int dir);
 335
 336         /* TEMPO-SENSITIVE FUNCTIONS
 337
 338            These next 4 functions will all take tempo in account and should be
 339            used to determine position (and in the last case, distance in beats)
 340            when tempo matters but meter does not.
 341
 342            They SHOULD be used to determine the position of events
 343            whose location is canonically defined in beats.
 344         */
 345
 346         framepos_t framepos_plus_bbt (framepos_t pos, Timecode::BBT_Time b) const;
 347         framepos_t framepos_plus_beats (framepos_t, Evoral::Beats) const;
 348         framepos_t framepos_minus_beats (framepos_t, Evoral::Beats) const;
 349         Evoral::Beats framewalk_to_beats (framepos_t pos, framecnt_t distance) const;
 350
 351         static const Tempo& default_tempo() { return _default_tempo; }
 352         static const Meter& default_meter() { return _default_meter; }
 353
 354         const Tempo tempo_at (framepos_t) const;
 355         double frames_per_beat_at (framepos_t, framecnt_t sr) const;
 356
 357         const Meter& meter_at (framepos_t) const;
 358
 359         const TempoSection& tempo_section_at (framepos_t) const;
 360         const MeterSection& meter_section_at (framepos_t) const;
 361
 362         void add_tempo (const Tempo&, double where, TempoSection::Type type);
 363         void add_meter (const Meter&, double start, Timecode::BBT_Time where);
 364
 365         void remove_tempo (const TempoSection&, bool send_signal);
 366         void remove_meter (const MeterSection&, bool send_signal);
 367
 368         void replace_tempo (const TempoSection&, const Tempo&, const double& where, TempoSection::Type type);
 369         void gui_set_tempo_frame (TempoSection&, framepos_t where, double beat);
 370         void replace_meter (const MeterSection&, const Meter&, const double& start, const Timecode::BBT_Time& where);
 371
 372         framepos_t round_to_bar  (framepos_t frame, RoundMode dir);
 373         framepos_t round_to_beat (framepos_t frame, RoundMode dir);
 374         framepos_t round_to_beat_subdivision (framepos_t fr, int sub_num, RoundMode dir);
 375
 376         void set_length (framepos_t frames);
 377
 378         XMLNode& get_state (void);
 379         int set_state (const XMLNode&, int version);
 380
 381         void dump (std::ostream&) const;
 382         void clear ();
 383
 384         TempoMetric metric_at (Timecode::BBT_Time bbt) const;
 385
 386         /** Return the TempoMetric at frame @p t, and point @p last to the latest
 387          * metric change <= t, if it is non-NULL.
 388          */
 389         TempoMetric metric_at (framepos_t, Metrics::const_iterator* last=NULL) const;
 390
 391         Metrics::const_iterator metrics_end() { return metrics.end(); }
 392
 393         void change_existing_tempo_at (framepos_t, double bpm, double note_type);
 394         void change_initial_tempo (double bpm, double note_type);
 395
 396         void insert_time (framepos_t, framecnt_t);
 397         bool remove_time (framepos_t where, framecnt_t amount);  //returns true if anything was moved
 398
 399         int n_tempos () const;
 400         int n_meters () const;
 401
 402         framecnt_t frame_rate () const { return _frame_rate; }
 403
 404         PBD::Signal0<void> MetricPositionChanged;
 405
 406         double bbt_to_beats (Timecode::BBT_Time bbt);
 407
 408 private:
 409
 410         friend class ::BBTTest;
 411         friend class ::FrameposPlusBeatsTest;
 412         friend class ::TempoTest;
 413
 414         static Tempo    _default_tempo;
 415         static Meter    _default_meter;
 416
 417         Metrics                       metrics;
 418         framecnt_t                    _frame_rate;
 419         mutable Glib::Threads::RWLock lock;
 420
 421         void recompute_map (bool reassign_tempo_bbt, framepos_t end = -1);
 422
 423         void _extend_map (TempoSection* tempo, MeterSection* meter,
 424                           Metrics::iterator next_metric,
 425                           Timecode::BBT_Time current, framepos_t current_frame, framepos_t end);
 426
 427         framepos_t round_to_type (framepos_t fr, RoundMode dir, BBTPointType);
 428
 429         const MeterSection& first_meter() const;
 430         MeterSection&       first_meter();
 431         const TempoSection& first_tempo() const;
 432         TempoSection&       first_tempo();
 433
 434         Timecode::BBT_Time beats_to_bbt (double beats);
 435
 436         void do_insert (MetricSection* section);
 437
 438         void add_tempo_locked (const Tempo&, double where, bool recompute, TempoSection::Type type);
 439         void add_meter_locked (const Meter&, double start, Timecode::BBT_Time where, bool recompute);
 440
 441         bool remove_tempo_locked (const TempoSection&);
 442         bool remove_meter_locked (const MeterSection&);
 443
 444 };
 445
 446 }; /* namespace ARDOUR */
 447
 448 std::ostream& operator<< (std::ostream&, const ARDOUR::Meter&);
 449 std::ostream& operator<< (std::ostream&, const ARDOUR::Tempo&);
 450 std::ostream& operator<< (std::ostream&, const ARDOUR::MetricSection&);
 451
 452 #endif /* __ardour_tempo_h__ */