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 (const Timecode::BBT_Time& start)
 103                 : _start (start), _frame (0), _movable (true), _position_lock_style (MusicTime) {}
 104         MetricSection (framepos_t start)
 105                 : _frame (start), _movable (true), _position_lock_style (MusicTime) {}
 106
 107         virtual ~MetricSection() {}
 108
 109         const Timecode::BBT_Time& start() const { return _start; }
 110         framepos_t                frame() const { return _frame; }
 111
 112         void set_movable (bool yn) { _movable = yn; }
 113         bool movable() const { return _movable; }
 114
 115         virtual void set_frame (framepos_t f) {
 116                 _frame = f;
 117         }
 118
 119         virtual void set_start (const Timecode::BBT_Time& w) {
 120                 _start = w;
 121         }
 122
 123         /* MeterSections are not stateful in the full sense,
 124            but we do want them to control their own
 125            XML state information.
 126         */
 127         virtual XMLNode& get_state() const = 0;
 128         PositionLockStyle position_lock_style () const { return _position_lock_style; }
 129         void set_position_lock_style (PositionLockStyle ps) { _position_lock_style = ps; }
 130
 131 private:
 132
 133         Timecode::BBT_Time _start;
 134         framepos_t         _frame;
 135         bool               _movable;
 136         PositionLockStyle  _position_lock_style;
 137 };
 138
 139 /** A section of timeline with a certain Meter. */
 140 class LIBARDOUR_API MeterSection : public MetricSection, public Meter {
 141   public:
 142         MeterSection (const Timecode::BBT_Time& start, double bpb, double note_type)
 143                 : MetricSection (start), Meter (bpb, note_type) {}
 144         MeterSection (framepos_t start, double bpb, double note_type)
 145                 : MetricSection (start), Meter (bpb, note_type) {}
 146         MeterSection (const XMLNode&);
 147
 148         static const std::string xml_state_node_name;
 149
 150         XMLNode& get_state() const;
 151 };
 152
 153 /** A section of timeline with a certain Tempo. */
 154 class LIBARDOUR_API TempoSection : public MetricSection, public Tempo {
 155   public:
 156         enum Type {
 157                 Ramp,
 158                 Constant,
 159         };
 160
 161         TempoSection (const Timecode::BBT_Time& start, double qpm, double note_type, Type tempo_type)
 162                 : MetricSection (start), Tempo (qpm, note_type), _bar_offset (-1.0), _type (tempo_type)  {}
 163         TempoSection (framepos_t start, double qpm, double note_type, Type tempo_type)
 164                 : MetricSection (start), Tempo (qpm, note_type), _bar_offset (-1.0), _type (tempo_type) {}
 165         TempoSection (const XMLNode&);
 166
 167         static const std::string xml_state_node_name;
 168
 169         XMLNode& get_state() const;
 170
 171         void update_bar_offset_from_bbt (const Meter&);
 172         void update_bbt_time_from_bar_offset (const Meter&);
 173         double bar_offset() const { return _bar_offset; }
 174
 175         void set_type (Type type);
 176         Type type () const { return _type; }
 177
 178         double tempo_at_frame (framepos_t frame, double end_bpm, framepos_t end_frame, framecnt_t frame_rate) const;
 179         framepos_t frame_at_tempo (double tempo, double end_bpm, framepos_t end_frame, framecnt_t frame_rate) const;
 180
 181         double tick_at_frame (framepos_t frame, double end_bpm, framepos_t end_frame, framecnt_t frame_rate) const;
 182         framepos_t frame_at_tick (double tick, double end_bpm, framepos_t end_frame, framecnt_t frame_rate) const;
 183
 184         double beat_at_frame (framepos_t frame, double end_bpm, framepos_t end_frame, framecnt_t frame_rate) const;
 185         framepos_t frame_at_beat (double beat, double end_bpm, framepos_t end_frame, framecnt_t frame_rate) const;
 186
 187   private:
 188
 189         framecnt_t minute_to_frame (double time, framecnt_t frame_rate) const;
 190         double frame_to_minute (framecnt_t frame, framecnt_t frame_rate) const;
 191
 192         /*  tempo ramp functions. zero-based with time in minutes,
 193          * 'tick tempo' in ticks per minute and tempo in bpm.
 194          *  time relative to section start.
 195          */
 196         double c_func (double end_tpm, double end_time) const;
 197         double a_func (double begin_tpm, double end_tpm, double end_time) const;
 198
 199         double tempo_at_time (double time, double end_bpm, double end_time) const;
 200         double time_at_tempo (double tempo, double end_bpm, double end_time) const;
 201         double tick_tempo_at_time (double time, double end_tpm, double end_time) const;
 202         double time_at_tick_tempo (double tick_tempo, double end_tpm, double end_time) const;
 203
 204         double tick_at_time (double time, double end_tpm, double end_time) const;
 205         double time_at_tick (double tick, double end_tpm, double end_time) const;
 206
 207         double beat_at_time (double time, double end_tpm, double end_time) const;
 208         double time_at_beat (double beat, double end_tpm, double end_time) const;
 209
 210         /* this value provides a fractional offset into the bar in which
 211            the tempo section is located in. A value of 0.0 indicates that
 212            it occurs on the first beat of the bar, a value of 0.5 indicates
 213            that it occurs halfway through the bar and so on.
 214
 215            this enables us to keep the tempo change at the same relative
 216            position within the bar if/when the meter changes.
 217         */
 218         double _bar_offset;
 219         Type _type;
 220 };
 221
 222 typedef std::list<MetricSection*> Metrics;
 223
 224 /** Helper class to keep track of the Meter *AND* Tempo in effect
 225     at a given point in time.
 226 */
 227 class LIBARDOUR_API TempoMetric {
 228   public:
 229         TempoMetric (const Meter& m, const Tempo& t)
 230                 : _meter (&m), _tempo (&t), _frame (0) {}
 231
 232         void set_tempo (const Tempo& t)              { _tempo = &t; }
 233         void set_meter (const Meter& m)              { _meter = &m; }
 234         void set_frame (framepos_t f)                { _frame = f; }
 235         void set_start (const Timecode::BBT_Time& t) { _start = t; }
 236
 237         void set_metric (const MetricSection* section) {
 238                 const MeterSection* meter;
 239                 const TempoSection* tempo;
 240                 if ((meter = dynamic_cast<const MeterSection*>(section))) {
 241                         set_meter(*meter);
 242                 } else if ((tempo = dynamic_cast<const TempoSection*>(section))) {
 243                         set_tempo(*tempo);
 244                 }
 245
 246                 set_frame(section->frame());
 247                 set_start(section->start());
 248         }
 249
 250         const Meter&              meter() const { return *_meter; }
 251         const Tempo&              tempo() const { return *_tempo; }
 252         framepos_t                frame() const { return _frame; }
 253         const Timecode::BBT_Time& start() const { return _start; }
 254
 255   private:
 256         const Meter*       _meter;
 257         const Tempo*       _tempo;
 258         framepos_t         _frame;
 259         Timecode::BBT_Time _start;
 260 };
 261
 262 /** Tempo Map - mapping of timecode to musical time.
 263  * convert audio-samples, sample-rate to Bar/Beat/Tick, Meter/Tempo
 264  */
 265 class LIBARDOUR_API TempoMap : public PBD::StatefulDestructible
 266 {
 267   public:
 268         TempoMap (framecnt_t frame_rate);
 269         ~TempoMap();
 270
 271         /* measure-based stuff */
 272
 273         enum BBTPointType {
 274                 Bar,
 275                 Beat,
 276         };
 277
 278         struct BBTPoint {
 279                 framepos_t          frame;
 280                 const MeterSection* meter;
 281                 const Tempo* tempo;
 282                 uint32_t            bar;
 283                 uint32_t            beat;
 284
 285                 BBTPoint (const MeterSection& m, const Tempo& t, framepos_t f,
 286                           uint32_t b, uint32_t e)
 287                         : frame (f), meter (&m), tempo (&t), bar (b), beat (e) {}
 288
 289                 Timecode::BBT_Time bbt() const { return Timecode::BBT_Time (bar, beat, 0); }
 290                 operator Timecode::BBT_Time() const { return bbt(); }
 291                 operator framepos_t() const { return frame; }
 292                 bool is_bar() const { return beat == 1; }
 293         };
 294
 295         template<class T> void apply_with_metrics (T& obj, void (T::*method)(const Metrics&)) {
 296                 Glib::Threads::RWLock::ReaderLock lm (lock);
 297                 (obj.*method)(metrics);
 298         }
 299
 300         void get_grid (std::vector<BBTPoint>&,
 301                        framepos_t start, framepos_t end);
 302
 303         /* TEMPO- AND METER-SENSITIVE FUNCTIONS
 304
 305            bbt_time(), beat_at_frame(), frame_at_beat(), tick_at_frame(),
 306            frame_at_tick(),frame_time() and bbt_duration_at()
 307            are all sensitive to tempo and meter, and will give answers
 308            that align with the grid formed by tempo and meter sections.
 309
 310            They SHOULD NOT be used to determine the position of events
 311            whose location is canonically defined in beats.
 312         */
 313
 314         void bbt_time (framepos_t when, Timecode::BBT_Time&);
 315
 316         double tick_at_frame (framecnt_t frame) const;
 317         framecnt_t frame_at_tick (double tick) const;
 318
 319         double beat_at_frame (framecnt_t frame) const;
 320         framecnt_t frame_at_beat (double beat) const;
 321
 322         framepos_t frame_time (const Timecode::BBT_Time&);
 323         framecnt_t bbt_duration_at (framepos_t, const Timecode::BBT_Time&, int dir);
 324
 325         /* TEMPO-SENSITIVE FUNCTIONS
 326
 327            These next 4 functions will all take tempo in account and should be
 328            used to determine position (and in the last case, distance in beats)
 329            when tempo matters but meter does not.
 330
 331            They SHOULD be used to determine the position of events
 332            whose location is canonically defined in beats.
 333         */
 334
 335         framepos_t framepos_plus_bbt (framepos_t pos, Timecode::BBT_Time b) const;
 336         framepos_t framepos_plus_beats (framepos_t, Evoral::Beats) const;
 337         framepos_t framepos_minus_beats (framepos_t, Evoral::Beats) const;
 338         Evoral::Beats framewalk_to_beats (framepos_t pos, framecnt_t distance) const;
 339
 340         static const Tempo& default_tempo() { return _default_tempo; }
 341         static const Meter& default_meter() { return _default_meter; }
 342
 343         const Tempo tempo_at (framepos_t) const;
 344         double frames_per_beat_at (framepos_t, framecnt_t sr) const;
 345
 346         const Meter& meter_at (framepos_t) const;
 347
 348         const TempoSection& tempo_section_at (framepos_t) const;
 349         TempoSection* tempo_section_after (framepos_t) const;
 350         const MeterSection& meter_section_at (framepos_t) const;
 351
 352         void add_tempo (const Tempo&, Timecode::BBT_Time where, TempoSection::Type type);
 353         void add_meter (const Meter&, Timecode::BBT_Time where);
 354
 355         void remove_tempo (const TempoSection&, bool send_signal);
 356         void remove_meter (const MeterSection&, bool send_signal);
 357
 358         void replace_tempo (const TempoSection&, const Tempo&, const Timecode::BBT_Time& where, TempoSection::Type type);
 359         void gui_set_tempo_frame (TempoSection&, framepos_t where);
 360         void replace_meter (const MeterSection&, const Meter&, const Timecode::BBT_Time& where);
 361
 362         framepos_t round_to_bar  (framepos_t frame, RoundMode dir);
 363         framepos_t round_to_beat (framepos_t frame, RoundMode dir);
 364         framepos_t round_to_beat_subdivision (framepos_t fr, int sub_num, RoundMode dir);
 365
 366         void set_length (framepos_t frames);
 367
 368         XMLNode& get_state (void);
 369         int set_state (const XMLNode&, int version);
 370
 371         void dump (std::ostream&) const;
 372         void clear ();
 373
 374         TempoMetric metric_at (Timecode::BBT_Time bbt) const;
 375
 376         /** Return the TempoMetric at frame @p t, and point @p last to the latest
 377          * metric change <= t, if it is non-NULL.
 378          */
 379         TempoMetric metric_at (framepos_t, Metrics::const_iterator* last=NULL) const;
 380
 381         Metrics::const_iterator metrics_end() { return metrics.end(); }
 382
 383         void change_existing_tempo_at (framepos_t, double bpm, double note_type);
 384         void change_initial_tempo (double bpm, double note_type);
 385
 386         void insert_time (framepos_t, framecnt_t);
 387         bool remove_time (framepos_t where, framecnt_t amount);  //returns true if anything was moved
 388
 389         int n_tempos () const;
 390         int n_meters () const;
 391
 392         framecnt_t frame_rate () const { return _frame_rate; }
 393
 394         PBD::Signal0<void> MetricPositionChanged;
 395
 396 private:
 397
 398         friend class ::BBTTest;
 399         friend class ::FrameposPlusBeatsTest;
 400         friend class ::TempoTest;
 401
 402         static Tempo    _default_tempo;
 403         static Meter    _default_meter;
 404
 405         Metrics                       metrics;
 406         framecnt_t                    _frame_rate;
 407         mutable Glib::Threads::RWLock lock;
 408
 409         void recompute_map (bool reassign_tempo_bbt, framepos_t end = -1);
 410
 411         void _extend_map (TempoSection* tempo, MeterSection* meter,
 412                           Metrics::iterator next_metric,
 413                           Timecode::BBT_Time current, framepos_t current_frame, framepos_t end);
 414
 415         framepos_t round_to_type (framepos_t fr, RoundMode dir, BBTPointType);
 416
 417         const MeterSection& first_meter() const;
 418         MeterSection&       first_meter();
 419         const TempoSection& first_tempo() const;
 420         TempoSection&       first_tempo();
 421
 422         Timecode::BBT_Time beats_to_bbt (double beats);
 423         int32_t bars_in_meter_section (MeterSection* ms) const;
 424
 425         void do_insert (MetricSection* section);
 426
 427         void add_tempo_locked (const Tempo&, Timecode::BBT_Time where, bool recompute, TempoSection::Type type);
 428         void add_meter_locked (const Meter&, Timecode::BBT_Time where, bool recompute);
 429
 430         bool remove_tempo_locked (const TempoSection&);
 431         bool remove_meter_locked (const MeterSection&);
 432
 433 };
 434
 435 }; /* namespace ARDOUR */
 436
 437 std::ostream& operator<< (std::ostream&, const ARDOUR::Meter&);
 438 std::ostream& operator<< (std::ostream&, const ARDOUR::Tempo&);
 439 std::ostream& operator<< (std::ostream&, const ARDOUR::MetricSection&);
 440
 441 #endif /* __ardour_tempo_h__ */