Tidy up tempo.h and add some documentation.

Fix some const violating casts.
No functional changes.

git-svn-id: svn://localhost/ardour2/branches/3.0@13512 d708f5d6-7413-0410-9779-e7cbd77b26cf

2 files changed, 78 insertions, 72 deletions

diff --git a/libs/ardour/ardour/tempo.h b/libs/ardour/ardour/tempo.h
index 8e4f1bc420..65e488d9a5 100644
--- a/libs/ardour/ardour/tempo.h
+++ b/libs/ardour/ardour/tempo.h
@@ -34,17 +34,17 @@
 
 #include "ardour/ardour.h"
 
-class XMLNode;
-
 class BBTTest;
 class FrameposPlusBeatsTest;
 class TempoTest;
+class XMLNode;
 
 namespace ARDOUR {
 
 class Meter;
 class TempoMap;
 
+/** Tempo, the speed at which musical time progresses (BPM). */
 class Tempo {
   public:
 	Tempo (double bpm, double type=4.0) // defaulting to quarter note
@@ -52,13 +52,16 @@ class Tempo {
 
 	double beats_per_minute () const { return _beats_per_minute;}
 	double note_type () const { return _note_type;}
-	double frames_per_beat (framecnt_t sr) const;
+	double frames_per_beat (framecnt_t sr) const {
+		return (60.0 * sr) / _beats_per_minute;
+	}
 
   protected:
 	double _beats_per_minute;
 	double _note_type;
 };
 
+/** Meter, or time signature (beats per bar, and which note type is a beat). */
 class Meter {
   public:
 	Meter (double dpb, double bt)
@@ -83,6 +86,7 @@ class Meter {
 	double _note_type;
 };
 
+/** A section of timeline with a certain Tempo or Meter. */
 class MetricSection {
   public:
 	MetricSection (const Timecode::BBT_Time& start)
@@ -118,6 +122,7 @@ class MetricSection {
 	bool               _movable;
 };
 
+/** A section of timeline with a certain Meter. */
 class MeterSection : public MetricSection, public Meter {
   public:
 	MeterSection (const Timecode::BBT_Time& start, double bpb, double note_type)
@@ -131,6 +136,7 @@ class MeterSection : public MetricSection, public Meter {
 	XMLNode& get_state() const;
 };
 
+/** A section of timeline with a certain Tempo. */
 class TempoSection : public MetricSection, public Tempo {
   public:
 	TempoSection (const Timecode::BBT_Time& start, double qpm, double note_type)
@@ -161,21 +167,22 @@ class TempoSection : public MetricSection, public Tempo {
 
 typedef std::list<MetricSection*> Metrics;
 
-/** Helper class that we use to be able to keep track of which
-    meter *AND* tempo are in effect at a given point in time.
+/** Helper class to keep track of the Meter *AND* Tempo in effect
+    at a given point in time.
 */
 class TempoMetric {
   public:
-	TempoMetric (const Meter& m, const Tempo& t) : _meter (&m), _tempo (&t), _frame (0) {}
+	TempoMetric (const Meter& m, const Tempo& t)
+		: _meter (&m), _tempo (&t), _frame (0) {}
 
-	void set_tempo (const Tempo& t)    { _tempo = &t; }
-	void set_meter (const Meter& m)    { _meter = &m; }
-	void set_frame (framepos_t f)      { _frame = f; }
+	void set_tempo (const Tempo& t)              { _tempo = &t; }
+	void set_meter (const Meter& m)              { _meter = &m; }
+	void set_frame (framepos_t f)                { _frame = f; }
 	void set_start (const Timecode::BBT_Time& t) { _start = t; }
 
-	const Meter&    meter() const { return *_meter; }
-	const Tempo&    tempo() const { return *_tempo; }
-	framepos_t      frame() const { return _frame; }
+	const Meter&              meter() const { return *_meter; }
+	const Tempo&              tempo() const { return *_tempo; }
+	framepos_t                frame() const { return _frame; }
 	const Timecode::BBT_Time& start() const { return _start; }
 
   private:
@@ -199,20 +206,20 @@ class TempoMap : public PBD::StatefulDestructible
 	};
 
 	struct BBTPoint {
-            framepos_t  frame;
-            const MeterSection* meter;
-            const TempoSection* tempo;
-            uint32_t bar;
-            uint32_t beat;
+		framepos_t          frame;
+		const MeterSection* meter;
+		const TempoSection* tempo;
+		uint32_t            bar;
+		uint32_t            beat;
             
-            BBTPoint (const MeterSection& m, const TempoSection& t, framepos_t f,
-                      uint32_t b, uint32_t e)
-                    : frame (f), meter (&m), tempo (&t), bar (b), beat (e) {}
-
-            Timecode::BBT_Time bbt() const { return Timecode::BBT_Time (bar, beat, 0); }
-            operator Timecode::BBT_Time() const { return bbt(); }
-            operator framepos_t() const { return frame; }
-	    bool is_bar() const { return beat == 1; }
+		BBTPoint (const MeterSection& m, const TempoSection& t, framepos_t f,
+		          uint32_t b, uint32_t e)
+			: frame (f), meter (&m), tempo (&t), bar (b), beat (e) {}
+		
+		Timecode::BBT_Time bbt() const { return Timecode::BBT_Time (bar, beat, 0); }
+		operator Timecode::BBT_Time() const { return bbt(); }
+		operator framepos_t() const { return frame; }
+		bool is_bar() const { return beat == 1; }
 	};
 
 	typedef std::vector<BBTPoint> BBTPointList;
@@ -223,7 +230,7 @@ class TempoMap : public PBD::StatefulDestructible
 	}
 
 	void get_grid (BBTPointList::const_iterator&, BBTPointList::const_iterator&, 
-		       framepos_t start, framepos_t end);
+	               framepos_t start, framepos_t end);
 	
 	/* TEMPO- AND METER-SENSITIVE FUNCTIONS 
 
@@ -235,13 +242,14 @@ class TempoMap : public PBD::StatefulDestructible
 	   whose location is canonically defined in beats.
 	*/
 
-	void       bbt_time (framepos_t when, Timecode::BBT_Time&);
+	void bbt_time (framepos_t when, Timecode::BBT_Time&);
+
 	/* realtime safe variant of ::bbt_time(), will throw 
 	   std::logic_error if the map is not large enough
 	   to provide an answer.
 	*/
 	void       bbt_time_rt (framepos_t when, Timecode::BBT_Time&);
-        framepos_t frame_time (const Timecode::BBT_Time&);
+	framepos_t frame_time (const Timecode::BBT_Time&);
 	framecnt_t bbt_duration_at (framepos_t, const Timecode::BBT_Time&, int dir);
 
 	/* TEMPO-SENSITIVE FUNCTIONS
@@ -267,11 +275,11 @@ class TempoMap : public PBD::StatefulDestructible
 
 	const TempoSection& tempo_section_at (framepos_t) const;
 
-	void add_tempo(const Tempo&, Timecode::BBT_Time where);
-	void add_meter(const Meter&, Timecode::BBT_Time where);
+	void add_tempo (const Tempo&, Timecode::BBT_Time where);
+	void add_meter (const Meter&, Timecode::BBT_Time where);
 
-	void remove_tempo(const TempoSection&, bool send_signal);
-	void remove_meter(const MeterSection&, bool send_signal);
+	void remove_tempo (const TempoSection&, bool send_signal);
+	void remove_meter (const MeterSection&, bool send_signal);
 
 	void replace_tempo (const TempoSection&, const Tempo&, const Timecode::BBT_Time& where);
 	void replace_meter (const MeterSection&, const Meter&, const Timecode::BBT_Time& where);
@@ -292,7 +300,6 @@ class TempoMap : public PBD::StatefulDestructible
 	TempoMetric metric_at (Timecode::BBT_Time bbt) const;
 	TempoMetric metric_at (framepos_t) const;
 
-
 	void change_existing_tempo_at (framepos_t, double bpm, double note_type);
 	void change_initial_tempo (double bpm, double note_type);
 
@@ -312,25 +319,25 @@ class TempoMap : public PBD::StatefulDestructible
 	static Tempo    _default_tempo;
 	static Meter    _default_meter;
 
-	Metrics              metrics;
-	framecnt_t          _frame_rate;
+	Metrics                       metrics;
+	framecnt_t                    _frame_rate;
 	mutable Glib::Threads::RWLock lock;
-	BBTPointList        _map;
+	BBTPointList                  _map;
 
 	void recompute_map (bool reassign_tempo_bbt, framepos_t end = -1);
 	void extend_map (framepos_t end);
-        void require_map_to (framepos_t pos);
-        void require_map_to (const Timecode::BBT_Time&);
+	void require_map_to (framepos_t pos);
+	void require_map_to (const Timecode::BBT_Time&);
 	void _extend_map (TempoSection* tempo, MeterSection* meter, 
-			  Metrics::iterator next_metric,
-			  Timecode::BBT_Time current, framepos_t current_frame, framepos_t end);
+	                  Metrics::iterator next_metric,
+	                  Timecode::BBT_Time current, framepos_t current_frame, framepos_t end);
 
 	BBTPointList::const_iterator bbt_before_or_at (framepos_t);
 	BBTPointList::const_iterator bbt_before_or_at (const Timecode::BBT_Time&);
 	BBTPointList::const_iterator bbt_after_or_at (framepos_t);
 	
 	framepos_t round_to_type (framepos_t fr, int dir, BBTPointType);
-        void bbt_time (framepos_t, Timecode::BBT_Time&, const BBTPointList::const_iterator&);
+	void bbt_time (framepos_t, Timecode::BBT_Time&, const BBTPointList::const_iterator&);
 	framecnt_t bbt_duration_at_unlocked (const Timecode::BBT_Time& when, const Timecode::BBT_Time& bbt, int dir);
 	
 	const MeterSection& first_meter() const;
diff --git a/libs/ardour/tempo.cc b/libs/ardour/tempo.cc
index 0a90acec46..80091e7eec 100644
--- a/libs/ardour/tempo.cc
+++ b/libs/ardour/tempo.cc
@@ -43,12 +43,6 @@ using Timecode::BBT_Time;
 Meter    TempoMap::_default_meter (4.0, 4.0);
 Tempo    TempoMap::_default_tempo (120.0);
 
-double 
-Tempo::frames_per_beat (framecnt_t sr) const
-{
-	return  (60.0 * sr) / _beats_per_minute;
-}
-
 /***********************************************************************/
 
 double 
@@ -920,7 +914,7 @@ TempoMap::_extend_map (TempoSection* tempo, MeterSection* meter,
 
 			if (!(current < (*next_metric)->start())) {
 
-			  set_metrics:
+		set_metrics:
 				if (((ts = dynamic_cast<TempoSection*> (*next_metric)) != 0)) {
 
 					tempo = ts;
@@ -945,7 +939,7 @@ TempoMap::_extend_map (TempoSection* tempo, MeterSection* meter,
 						double next_beat_frames = tempo->frames_per_beat (_frame_rate);					
 						
 						DEBUG_TRACE (DEBUG::TempoMath, string_compose ("bumped into non-beat-aligned tempo metric at %1 = %2, adjust next beat using %3\n",
-											       tempo->start(), current_frame, tempo->bar_offset()));
+						                                               tempo->start(), current_frame, tempo->bar_offset()));
 						
 						/* back up to previous beat */
 						current_frame -= beat_frames;
@@ -955,7 +949,7 @@ TempoMap::_extend_map (TempoSection* tempo, MeterSection* meter,
 						 * bar start 
 						 */
 						tempo->set_frame (bar_start_frame + 
-								  llrint ((ts->bar_offset() * meter->divisions_per_bar() * beat_frames)));
+						                  llrint ((ts->bar_offset() * meter->divisions_per_bar() * beat_frames)));
 						
 						/* advance to the location of
 						 * the new (adjusted) beat. do
@@ -980,7 +974,7 @@ TempoMap::_extend_map (TempoSection* tempo, MeterSection* meter,
 					} else {
 						
 						DEBUG_TRACE (DEBUG::TempoMath, string_compose ("bumped into beat-aligned tempo metric at %1 = %2\n",
-											       tempo->start(), current_frame));
+						                                               tempo->start(), current_frame));
 						tempo->set_frame (current_frame);
 					}
 
@@ -993,7 +987,7 @@ TempoMap::_extend_map (TempoSection* tempo, MeterSection* meter,
 					 */
 					
 					DEBUG_TRACE (DEBUG::TempoMath, string_compose ("bumped into meter section at %1 vs %2 (%3)\n",
-										       meter->start(), current, current_frame));
+					                                               meter->start(), current, current_frame));
 					
 					assert (current.beats == 1);
 
@@ -1003,13 +997,13 @@ TempoMap::_extend_map (TempoSection* tempo, MeterSection* meter,
 				beat_frames = meter->frames_per_grid (*tempo, _frame_rate);
 				
 				DEBUG_TRACE (DEBUG::TempoMath, string_compose ("New metric with beat frames = %1 dpb %2 meter %3 tempo %4\n", 
-									       beat_frames, meter->divisions_per_bar(), *((Meter*)meter), *((Tempo*)tempo)));
+				                                               beat_frames, meter->divisions_per_bar(), *((Meter*)meter), *((Tempo*)tempo)));
 			
 				++next_metric;
 
 				if (next_metric != metrics.end() && ((*next_metric)->start() == current)) {
 					/* same position so go back and set this one up before advancing
-					*/
+					 */
 					goto set_metrics;
 				}
 
@@ -1029,7 +1023,7 @@ TempoMap::_extend_map (TempoSection* tempo, MeterSection* meter,
 			/* no more metrics - we've timestamped them all, stop here */
 			if (end == max_framepos) {
 				DEBUG_TRACE (DEBUG::TempoMath, string_compose ("stop extending map now that we've reach the end @ %1|%2 = %3\n",
-									       current.bars, current.beats, current_frame));
+				                                               current.bars, current.beats, current_frame));
 				break;
 			}
 		}
@@ -1152,7 +1146,7 @@ TempoMap::bbt_time (framepos_t frame, BBT_Time& bbt, const BBTPointList::const_i
 		bbt.ticks = 0;
 	} else {
 		bbt.ticks = llrint (((frame - (*i).frame) / (*i).tempo->frames_per_beat(_frame_rate)) *
-				    BBT_Time::ticks_per_beat);
+		                    BBT_Time::ticks_per_beat);
 	}
 }
 
@@ -1856,8 +1850,9 @@ TempoMap::framepos_plus_beats (framepos_t pos, Evoral::MusicalTime beats) const
 	   next_tempo  -> first tempo after "pos", possibly metrics.end()
 	*/
 
-	DEBUG_TRACE (DEBUG::TempoMath, string_compose ("frame %1 plus %2 beats, start with tempo = %3 @ %4\n",
-						       pos, beats, *((Tempo*)tempo), tempo->frame()));
+	DEBUG_TRACE (DEBUG::TempoMath,
+	             string_compose ("frame %1 plus %2 beats, start with tempo = %3 @ %4\n",
+	                             pos, beats, *((const Tempo*)tempo), tempo->frame()));
 
 	while (beats) {
 
@@ -1887,7 +1882,7 @@ TempoMap::framepos_plus_beats (framepos_t pos, Evoral::MusicalTime beats) const
 			tempo = dynamic_cast<const TempoSection*>(*next_tempo);
 
 			DEBUG_TRACE (DEBUG::TempoMath, string_compose ("\tnew tempo = %1 @ %2 fpb = %3\n",
-								       *((Tempo*)tempo), tempo->frame(),
+								       *((const Tempo*)tempo), tempo->frame(),
 								       tempo->frames_per_beat (_frame_rate)));
 
 			while (next_tempo != metrics.end ()) {
@@ -1955,9 +1950,10 @@ TempoMap::framepos_minus_beats (framepos_t pos, Evoral::MusicalTime beats) const
 		}
 	}
 
-	DEBUG_TRACE (DEBUG::TempoMath, string_compose ("frame %1 minus %2 beats, start with tempo = %3 @ %4 prev at beg? %5\n",
-						       pos, beats, *((Tempo*)tempo), tempo->frame(),
-						       prev_tempo == metrics.rend()));
+	DEBUG_TRACE (DEBUG::TempoMath,
+	             string_compose ("frame %1 minus %2 beats, start with tempo = %3 @ %4 prev at beg? %5\n",
+	                             pos, beats, *((const Tempo*)tempo), tempo->frame(),
+	                             prev_tempo == metrics.rend()));
 
 	/* We now have:
 
@@ -1992,9 +1988,10 @@ TempoMap::framepos_minus_beats (framepos_t pos, Evoral::MusicalTime beats) const
 
 			tempo = dynamic_cast<const TempoSection*>(*prev_tempo);
 
-			DEBUG_TRACE (DEBUG::TempoMath, string_compose ("\tnew tempo = %1 @ %2 fpb = %3\n",
-								       *((Tempo*)tempo), tempo->frame(),
-								       tempo->frames_per_beat (_frame_rate)));
+			DEBUG_TRACE (DEBUG::TempoMath,
+			             string_compose ("\tnew tempo = %1 @ %2 fpb = %3\n",
+			                             *((const Tempo*)tempo), tempo->frame(),
+			                             tempo->frames_per_beat (_frame_rate)));
 
 			while (prev_tempo != metrics.rend ()) {
 
@@ -2184,8 +2181,9 @@ TempoMap::framewalk_to_beats (framepos_t pos, framecnt_t distance) const
 
 	assert (tempo);
 
-	DEBUG_TRACE (DEBUG::TempoMath, string_compose ("frame %1 walk by %2 frames, start with tempo = %3 @ %4\n",
-						       pos, distance, *((Tempo*)tempo), tempo->frame()));
+	DEBUG_TRACE (DEBUG::TempoMath,
+	             string_compose ("frame %1 walk by %2 frames, start with tempo = %3 @ %4\n",
+	                             pos, distance, *((const Tempo*)tempo), tempo->frame()));
 	
 	Evoral::MusicalTime beats = 0;
 
@@ -2226,9 +2224,10 @@ TempoMap::framewalk_to_beats (framepos_t pos, framecnt_t distance) const
 
 			tempo = dynamic_cast<const TempoSection*>(*next_tempo);
 
-			DEBUG_TRACE (DEBUG::TempoMath, string_compose ("\tnew tempo = %1 @ %2 fpb = %3\n",
-								       *((Tempo*)tempo), tempo->frame(),
-								       tempo->frames_per_beat (_frame_rate)));
+			DEBUG_TRACE (DEBUG::TempoMath,
+			             string_compose ("\tnew tempo = %1 @ %2 fpb = %3\n",
+			                             *((const Tempo*)tempo), tempo->frame(),
+			                             tempo->frames_per_beat (_frame_rate)));
 
 			while (next_tempo != metrics.end ()) {
 
@@ -2335,9 +2334,9 @@ operator<< (std::ostream& o, const MetricSection& section) {
 	const MeterSection* ms;
 
 	if ((ts = dynamic_cast<const TempoSection*> (&section)) != 0) {
-		o << *((Tempo*) ts);
+		o << *((const Tempo*) ts);
 	} else if ((ms = dynamic_cast<const MeterSection*> (&section)) != 0) {
-		o << *((Meter*) ms);
+		o << *((const Meter*) ms);
 	}
 
 	return o;