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