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/types.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         Tempo (double bpm, double type=4.0) // defaulting to quarter note
  51                 : _beats_per_minute (bpm), _note_type(type) {}
  52
  53         double beats_per_minute () const { return _beats_per_minute;}
  54         double note_type () const { return _note_type;}
  55         double frames_per_beat (framecnt_t sr) const {
  56                 return (60.0 * sr) / _beats_per_minute;
  57         }
  58
  59   protected:
  60         double _beats_per_minute;
  61         double _note_type;
  62 };
  63
  64 /** Meter, or time signature (beats per bar, and which note type is a beat). */
  65 class LIBARDOUR_API Meter {
  66   public:
  67         Meter (double dpb, double bt)
  68                 : _divisions_per_bar (dpb), _note_type (bt) {}
  69
  70         double divisions_per_bar () const { return _divisions_per_bar; }
  71         double note_divisor() const { return _note_type; }
  72
  73         double frames_per_bar (const Tempo&, framecnt_t sr) const;
  74         double frames_per_grid (const Tempo&, framecnt_t sr) const;
  75
  76   protected:
  77         /** The number of divisions in a bar.  This is a floating point value because
  78             there are musical traditions on our planet that do not limit
  79             themselves to integral numbers of beats per bar.
  80         */
  81         double _divisions_per_bar;
  82
  83         /** The type of "note" that a division represents.  For example, 4.0 is
  84             a quarter (crotchet) note, 8.0 is an eighth (quaver) note, etc.
  85         */
  86         double _note_type;
  87 };
  88
  89 /** A section of timeline with a certain Tempo or Meter. */
  90 class LIBARDOUR_API MetricSection {
  91   public:
  92         MetricSection (const Timecode::BBT_Time& start)
  93                 : _start (start), _frame (0), _movable (true) {}
  94         MetricSection (framepos_t start)
  95                 : _frame (start), _movable (true) {}
  96
  97         virtual ~MetricSection() {}
  98
  99         const Timecode::BBT_Time& start() const { return _start; }
 100         framepos_t                frame() const { return _frame; }
 101
 102         void set_movable (bool yn) { _movable = yn; }
 103         bool movable() const { return _movable; }
 104
 105         virtual void set_frame (framepos_t f) {
 106                 _frame = f;
 107         }
 108
 109         virtual void set_start (const Timecode::BBT_Time& w) {
 110                 _start = w;
 111         }
 112
 113         /* MeterSections are not stateful in the full sense,
 114            but we do want them to control their own
 115            XML state information.
 116         */
 117         virtual XMLNode& get_state() const = 0;
 118
 119   private:
 120         Timecode::BBT_Time _start;
 121         framepos_t         _frame;
 122         bool               _movable;
 123 };
 124
 125 /** A section of timeline with a certain Meter. */
 126 class LIBARDOUR_API MeterSection : public MetricSection, public Meter {
 127   public:
 128         MeterSection (const Timecode::BBT_Time& start, double bpb, double note_type)
 129                 : MetricSection (start), Meter (bpb, note_type) {}
 130         MeterSection (framepos_t start, double bpb, double note_type)
 131                 : MetricSection (start), Meter (bpb, note_type) {}
 132         MeterSection (const XMLNode&);
 133
 134         static const std::string xml_state_node_name;
 135
 136         XMLNode& get_state() const;
 137 };
 138
 139 /** A section of timeline with a certain Tempo. */
 140 class LIBARDOUR_API TempoSection : public MetricSection, public Tempo {
 141   public:
 142         TempoSection (const Timecode::BBT_Time& start, double qpm, double note_type)
 143                 : MetricSection (start), Tempo (qpm, note_type), _bar_offset (-1.0)  {}
 144         TempoSection (framepos_t start, double qpm, double note_type)
 145                 : MetricSection (start), Tempo (qpm, note_type), _bar_offset (-1.0) {}
 146         TempoSection (const XMLNode&);
 147
 148         static const std::string xml_state_node_name;
 149
 150         XMLNode& get_state() const;
 151
 152         void update_bar_offset_from_bbt (const Meter&);
 153         void update_bbt_time_from_bar_offset (const Meter&);
 154         double bar_offset() const { return _bar_offset; }
 155
 156   private:
 157         /* this value provides a fractional offset into the bar in which
 158            the tempo section is located in. A value of 0.0 indicates that
 159            it occurs on the first beat of the bar, a value of 0.5 indicates
 160            that it occurs halfway through the bar and so on.
 161
 162            this enables us to keep the tempo change at the same relative
 163            position within the bar if/when the meter changes.
 164         */
 165         double _bar_offset;
 166 };
 167
 168 typedef std::list<MetricSection*> Metrics;
 169
 170 /** Helper class to keep track of the Meter *AND* Tempo in effect
 171     at a given point in time.
 172 */
 173 class LIBARDOUR_API TempoMetric {
 174   public:
 175         TempoMetric (const Meter& m, const Tempo& t)
 176                 : _meter (&m), _tempo (&t), _frame (0) {}
 177
 178         void set_tempo (const Tempo& t)              { _tempo = &t; }
 179         void set_meter (const Meter& m)              { _meter = &m; }
 180         void set_frame (framepos_t f)                { _frame = f; }
 181         void set_start (const Timecode::BBT_Time& t) { _start = t; }
 182
 183         void set_metric (const MetricSection* section) {
 184                 const MeterSection* meter;
 185                 const TempoSection* tempo;
 186                 if ((meter = dynamic_cast<const MeterSection*>(section))) {
 187                         set_meter(*meter);
 188                 } else if ((tempo = dynamic_cast<const TempoSection*>(section))) {
 189                         set_tempo(*tempo);
 190                 }
 191
 192                 set_frame(section->frame());
 193                 set_start(section->start());
 194         }
 195
 196         const Meter&              meter() const { return *_meter; }
 197         const Tempo&              tempo() const { return *_tempo; }
 198         framepos_t                frame() const { return _frame; }
 199         const Timecode::BBT_Time& start() const { return _start; }
 200
 201   private:
 202         const Meter*       _meter;
 203         const Tempo*       _tempo;
 204         framepos_t         _frame;
 205         Timecode::BBT_Time _start;
 206 };
 207
 208 class LIBARDOUR_API TempoMap : public PBD::StatefulDestructible
 209 {
 210   public:
 211         TempoMap (framecnt_t frame_rate);
 212         ~TempoMap();
 213
 214         /* measure-based stuff */
 215
 216         enum BBTPointType {
 217                 Bar,
 218                 Beat,
 219         };
 220
 221         struct BBTPoint {
 222                 framepos_t          frame;
 223                 const MeterSection* meter;
 224                 const TempoSection* tempo;
 225                 uint32_t            bar;
 226                 uint32_t            beat;
 227
 228                 BBTPoint (const MeterSection& m, const TempoSection& t, framepos_t f,
 229                           uint32_t b, uint32_t e)
 230                         : frame (f), meter (&m), tempo (&t), bar (b), beat (e) {}
 231
 232                 Timecode::BBT_Time bbt() const { return Timecode::BBT_Time (bar, beat, 0); }
 233                 operator Timecode::BBT_Time() const { return bbt(); }
 234                 operator framepos_t() const { return frame; }
 235                 bool is_bar() const { return beat == 1; }
 236         };
 237
 238         typedef std::vector<BBTPoint> BBTPointList;
 239
 240         template<class T> void apply_with_metrics (T& obj, void (T::*method)(const Metrics&)) {
 241                 Glib::Threads::RWLock::ReaderLock lm (lock);
 242                 (obj.*method)(metrics);
 243         }
 244
 245         void get_grid (BBTPointList::const_iterator&, BBTPointList::const_iterator&,
 246                        framepos_t start, framepos_t end);
 247
 248         /* TEMPO- AND METER-SENSITIVE FUNCTIONS
 249
 250            bbt_time(), bbt_time_rt(), frame_time() and bbt_duration_at()
 251            are all sensitive to tempo and meter, and will give answers
 252            that align with the grid formed by tempo and meter sections.
 253
 254            They SHOULD NOT be used to determine the position of events
 255            whose location is canonically defined in beats.
 256         */
 257
 258         void bbt_time (framepos_t when, Timecode::BBT_Time&);
 259
 260         /* realtime safe variant of ::bbt_time(), will throw
 261            std::logic_error if the map is not large enough
 262            to provide an answer.
 263         */
 264         void       bbt_time_rt (framepos_t when, Timecode::BBT_Time&);
 265         framepos_t frame_time (const Timecode::BBT_Time&);
 266         framecnt_t bbt_duration_at (framepos_t, const Timecode::BBT_Time&, int dir);
 267
 268         /* TEMPO-SENSITIVE FUNCTIONS
 269
 270            These next 4 functions will all take tempo in account and should be
 271            used to determine position (and in the last case, distance in beats)
 272            when tempo matters but meter does not.
 273
 274            They SHOULD be used to determine the position of events
 275            whose location is canonically defined in beats.
 276         */
 277
 278         framepos_t framepos_plus_bbt (framepos_t pos, Timecode::BBT_Time b) const;
 279         framepos_t framepos_plus_beats (framepos_t, Evoral::MusicalTime) const;
 280         framepos_t framepos_minus_beats (framepos_t, Evoral::MusicalTime) const;
 281         Evoral::MusicalTime framewalk_to_beats (framepos_t pos, framecnt_t distance) const;
 282
 283         static const Tempo& default_tempo() { return _default_tempo; }
 284         static const Meter& default_meter() { return _default_meter; }
 285
 286         const Tempo& tempo_at (framepos_t) const;
 287         const Meter& meter_at (framepos_t) const;
 288
 289         const TempoSection& tempo_section_at (framepos_t) const;
 290
 291         void add_tempo (const Tempo&, Timecode::BBT_Time where);
 292         void add_meter (const Meter&, Timecode::BBT_Time where);
 293
 294         void remove_tempo (const TempoSection&, bool send_signal);
 295         void remove_meter (const MeterSection&, bool send_signal);
 296
 297         void replace_tempo (const TempoSection&, const Tempo&, const Timecode::BBT_Time& where);
 298         void replace_meter (const MeterSection&, const Meter&, const Timecode::BBT_Time& where);
 299
 300         framepos_t round_to_bar  (framepos_t frame, int dir);
 301         framepos_t round_to_beat (framepos_t frame, int dir);
 302         framepos_t round_to_beat_subdivision (framepos_t fr, int sub_num, int dir);
 303         framepos_t round_to_tick (framepos_t frame, int dir);
 304
 305         void set_length (framepos_t frames);
 306
 307         XMLNode& get_state (void);
 308         int set_state (const XMLNode&, int version);
 309
 310         void dump (std::ostream&) const;
 311         void clear ();
 312
 313         TempoMetric metric_at (Timecode::BBT_Time bbt) const;
 314
 315         /** Return the TempoMetric at frame @p t, and point @p last to the latest
 316          * metric change <= t, if it is non-NULL.
 317          */
 318         TempoMetric metric_at (framepos_t, Metrics::const_iterator* last=NULL) const;
 319
 320         Metrics::const_iterator metrics_end() { return metrics.end(); }
 321
 322         void change_existing_tempo_at (framepos_t, double bpm, double note_type);
 323         void change_initial_tempo (double bpm, double note_type);
 324
 325         void insert_time (framepos_t, framecnt_t);
 326
 327         int n_tempos () const;
 328         int n_meters () const;
 329
 330         framecnt_t frame_rate () const { return _frame_rate; }
 331
 332   private:
 333
 334         friend class ::BBTTest;
 335         friend class ::FrameposPlusBeatsTest;
 336         friend class ::TempoTest;
 337
 338         static Tempo    _default_tempo;
 339         static Meter    _default_meter;
 340
 341         Metrics                       metrics;
 342         framecnt_t                    _frame_rate;
 343         mutable Glib::Threads::RWLock lock;
 344         BBTPointList                  _map;
 345
 346         void recompute_map (bool reassign_tempo_bbt, framepos_t end = -1);
 347         void extend_map (framepos_t end);
 348         void require_map_to (framepos_t pos);
 349         void require_map_to (const Timecode::BBT_Time&);
 350         void _extend_map (TempoSection* tempo, MeterSection* meter,
 351                           Metrics::iterator next_metric,
 352                           Timecode::BBT_Time current, framepos_t current_frame, framepos_t end);
 353
 354         BBTPointList::const_iterator bbt_before_or_at (framepos_t);
 355         BBTPointList::const_iterator bbt_before_or_at (const Timecode::BBT_Time&);
 356         BBTPointList::const_iterator bbt_after_or_at (framepos_t);
 357
 358         framepos_t round_to_type (framepos_t fr, int dir, BBTPointType);
 359         void bbt_time (framepos_t, Timecode::BBT_Time&, const BBTPointList::const_iterator&);
 360         framecnt_t bbt_duration_at_unlocked (const Timecode::BBT_Time& when, const Timecode::BBT_Time& bbt, int dir);
 361
 362         const MeterSection& first_meter() const;
 363         const TempoSection& first_tempo() const;
 364
 365         void do_insert (MetricSection* section);
 366 };
 367
 368 }; /* namespace ARDOUR */
 369
 370 std::ostream& operator<< (std::ostream&, const ARDOUR::Meter&);
 371 std::ostream& operator<< (std::ostream&, const ARDOUR::Tempo&);
 372 std::ostream& operator<< (std::ostream&, const ARDOUR::MetricSection&);
 373
 374 #endif /* __ardour_tempo_h__ */