From 3db68b4f9e88658e8130769ee469f2a7b4de97a2 Mon Sep 17 00:00:00 2001 From: nick_m Date: Tue, 1 Nov 2016 04:45:38 +1100 Subject: [PATCH] add some documentation for TempoMap. --- libs/ardour/tempo.cc | 160 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 140 insertions(+), 20 deletions(-) diff --git a/libs/ardour/tempo.cc b/libs/ardour/tempo.cc index b13100a90c..a060b93b34 100644 --- a/libs/ardour/tempo.cc +++ b/libs/ardour/tempo.cc @@ -1490,9 +1490,10 @@ TempoMap::metric_at (BBT_Time bbt) const return m; } -/** Returns the beat duration corresponding to the supplied frame, possibly returning a negative value. +/** Returns the BBT (meter-based) beat corresponding to the supplied frame, possibly returning a negative value. * @param frame The session frame position. * @return The beat duration according to the tempo map at the supplied frame. + * * If the supplied frame lies before the first meter, the returned beat duration will be negative. * The returned beat is obtained using the first meter and the continuation of the tempo curve (backwards). * @@ -1534,6 +1535,12 @@ TempoMap::beat_at_minute_locked (const Metrics& metrics, const double& minute) c return beat; } +/** Returns the frame corresponding to the supplied BBT (meter-based) beat. + * @param beat The BBT (meter-based) beat. + * @return The frame duration according to the tempo map at the supplied BBT (meter-based) beat. + * + * This function uses both tempo and meter. + */ framepos_t TempoMap::frame_at_beat (const double& beat) const { @@ -1577,6 +1584,11 @@ TempoMap::minute_at_beat_locked (const Metrics& metrics, const double& beat) con return prev_t->minute_at_pulse (((beat - prev_m->beat()) / prev_m->note_divisor()) + prev_m->pulse()); } +/** Returns a Tempo corresponding to the supplied frame. + * @param frame The audio frame. + * @return a Tempo according to the tempo map at the supplied frame. + * + */ Tempo TempoMap::tempo_at_frame (const framepos_t& frame) const { @@ -1730,8 +1742,8 @@ TempoMap::pulse_at_tempo_locked (const Metrics& metrics, const Tempo& tempo) con return prev_t->minute(); } -/** more precise than doing tempo_at_frame (frame_at_beat (b)), - * as there is no intermediate frame rounding. +/** Returns a Tempo corresponding to the supplied BBT (meter-based) beat. + * @param beat The BBT (meter-based) beat. */ Tempo TempoMap::tempo_at_beat (const double& beat) const @@ -1743,6 +1755,9 @@ TempoMap::tempo_at_beat (const double& beat) const return Tempo (prev_t->tempo_at_pulse (((beat - prev_m->beat()) / prev_m->note_divisor()) + prev_m->pulse()), prev_t->note_type()); } +/** Returns a BBT (meter-based) beat corresponding to the supplied Tempo. + * @param tempo The tempo. + */ double TempoMap::beat_at_tempo (const Tempo& tempo) const { @@ -1751,7 +1766,13 @@ TempoMap::beat_at_tempo (const Tempo& tempo) const return beat_at_pulse_locked (_metrics, pulse); } - +/** Returns the whole-note pulse corresponding to the supplied BBT (meter-based) beat. + * @param beat The BBT (meter-based) beat. + * + * a pulse or whole note is the base musical position of a MetricSection. + * it is equivalent to four quarter notes. + * + */ double TempoMap::pulse_at_beat (const double& beat) const { @@ -1767,6 +1788,12 @@ TempoMap::pulse_at_beat_locked (const Metrics& metrics, const double& beat) cons return prev_m->pulse() + ((beat - prev_m->beat()) / prev_m->note_divisor()); } +/** Returns the BBT (meter-based) beat corresponding to the supplied whole-note pulse . + * @param pulse the whole-note pulse. + * + * a pulse or whole note is the base musical position of a MetricSection. + * it is equivalent to four quarter notes. + */ double TempoMap::beat_at_pulse (const double& pulse) const { @@ -1871,6 +1898,10 @@ TempoMap::minute_at_pulse_locked (const Metrics& metrics, const double& pulse) c return dtime + prev_t->minute(); } +/** Returns the BBT (meter-based) beat corresponding to the supplied BBT time. + * @param bbt The BBT time (meter-based). + * + */ double TempoMap::beat_at_bbt (const Timecode::BBT_Time& bbt) { @@ -1911,11 +1942,15 @@ TempoMap::beat_at_bbt_locked (const Metrics& metrics, const Timecode::BBT_Time& return ret; } +/** Returns the BBT time corresponding to the supplied BBT (meter-based) beat. + * @param beat The BBT (meter-based) beat. + * + */ Timecode::BBT_Time -TempoMap::bbt_at_beat (const double& beats) +TempoMap::bbt_at_beat (const double& beat) { Glib::Threads::RWLock::ReaderLock lm (lock); - return bbt_at_beat_locked (_metrics, beats); + return bbt_at_beat_locked (_metrics, beat); } Timecode::BBT_Time @@ -1970,6 +2005,13 @@ TempoMap::bbt_at_beat_locked (const Metrics& metrics, const double& b) const return ret; } +/** Returns the whole-note pulse corresponding to the supplied BBT time (meter-based). + * @param bbt The BBT time (meter-based). + * + * a pulse or whole note is the basic musical position of a MetricSection. + * it is equivalent to four quarter notes. + * while the input uses meter, the output does not. + */ double TempoMap::pulse_at_bbt (const Timecode::BBT_Time& bbt) { @@ -2020,7 +2062,13 @@ TempoMap::pulse_at_bbt_locked (const Metrics& metrics, const Timecode::BBT_Time& return ret; } - +/** Returns the BBT time (meter-based) corresponding to the supplied whole-note pulse. + * @param pulse The whole-note pulse. + * + * a pulse or whole note is the basic musical position of a MetricSection. + * it is equivalent to four quarter notes. + * while the input uses meter, the output does not. + */ Timecode::BBT_Time TempoMap::bbt_at_pulse (const double& pulse) { @@ -2082,6 +2130,10 @@ TempoMap::bbt_at_pulse_locked (const Metrics& metrics, const double& pulse) cons return ret; } +/** Returns the BBT time corresponding to the supplied frame position. + * @param frame the position in audio samples. + * + */ BBT_Time TempoMap::bbt_at_frame (framepos_t frame) { @@ -2180,6 +2232,10 @@ TempoMap::bbt_at_minute_locked (const Metrics& metrics, const double& minute) co return ret; } +/** Returns the frame corresponding to the supplied BBT time. + * @param bbt the position in BBT time. + * + */ framepos_t TempoMap::frame_at_bbt (const BBT_Time& bbt) { @@ -2207,17 +2263,17 @@ TempoMap::minute_at_bbt_locked (const Metrics& metrics, const BBT_Time& bbt) con } /** - * Returns the distance from 0 in quarter pulses at the supplied frame. + * Returns the quarter-note beat position corresponding to the supplied frame. + * + * @param frame The distance in frames relative to session 0 whose quarter note distance you would like. + * @return The quarter-note position of the supplied frame. Ignores meter. * * Plugin APIs don't count ticks in the same way PROGRAM_NAME does. * We use ticks per beat whereas the rest of the world uses ticks per quarter note. * This is more or less the VST's ppqPos (a scalar you use to obtain tick position * in whatever ppqn you're using). * - * @param frame The distance in frames relative to session 0 whose quarter note distance you would like. - * @return The quarter note (quarter pulse) distance from session 0 to the supplied frame. Ignores meter. */ - double TempoMap::quarter_note_at_frame (const framepos_t frame) { @@ -2250,6 +2306,14 @@ TempoMap::quarter_note_at_frame_rt (const framepos_t frame) return ret; } +/** + * Returns the frame corresponding to the supplied quarter-note beat position. + * + * @param quarter_note The quarter-note relative to session 0 whose frame position you would like. + * @return The frame position of the supplied quarter-note. Ignores meter. + * + * +*/ framepos_t TempoMap::frame_at_quarter_note (const double quarter_note) { @@ -2268,6 +2332,12 @@ TempoMap::minute_at_quarter_note_locked (const Metrics& metrics, const double qu return ret; } +/** Returns the quarter-note beats corresponding to the supplied BBT (meter-based) beat. + * @param beat The BBT (meter-based) beat. + * + * a quarter-note is the musical unit of Evoral::Beats. + * + */ double TempoMap::quarter_note_at_beat (const double beat) { @@ -2286,6 +2356,12 @@ TempoMap::quarter_note_at_beat_locked (const Metrics& metrics, const double beat return ret; } +/** Returns the BBT (meter-based) beat position corresponding to the supplied quarter-note beats. + * @param quarter_note The position in quarter-note beats. + * + * a quarter-note is the musical unit of Evoral::Beats. + * + */ double TempoMap::beat_at_quarter_note (const double quarter_note) { @@ -2303,6 +2379,15 @@ TempoMap::beat_at_quarter_note_locked (const Metrics& metrics, const double quar return beat_at_pulse_locked (metrics, quarter_note / 4.0); } +/** Returns the distance in frames between two supplied quarter-note beats. + * @param start the first position in quarter-note beats. + * @param end the end position in quarter-note beats. + * + * use this rather than e.g. + * frame_at-quarter_note (end_beats) - frame_at_quarter_note (start_beats). + * frames_between_quarter_notes() doesn't round to audio frames as an intermediate step, + * + */ framecnt_t TempoMap::frames_between_quarter_notes (const double start, const double end) { @@ -2887,7 +2972,7 @@ TempoMap::copy_metrics_and_point (const Metrics& metrics, Metrics& copy, MeterSe /** answers the question "is this a valid beat position for this tempo section?". * it returns true if the tempo section can be moved to the requested bbt position, * leaving the tempo map in a solved state. - * @param section the tempo section to be moved + * @param ts the tempo section to be moved * @param bbt the requested new position for the tempo section * @return true if the tempo section can be moved to the position, otherwise false. */ @@ -2920,7 +3005,7 @@ TempoMap::can_solve_bbt (TempoSection* ts, const BBT_Time& bbt) * This is for a gui that needs to know the pulse or frame of a tempo section if it were to be moved to some bbt time, * taking any possible reordering as a consequence of this into account. * @param section - the section to be altered -* @param bbt - the bbt where the altered tempo will fall +* @param bbt - the BBT time where the altered tempo will fall * @return returns - the position in pulses and frames (as a pair) where the new tempo section will lie. */ pair @@ -2951,6 +3036,22 @@ TempoMap::predict_tempo_position (TempoSection* section, const BBT_Time& bbt) return ret; } +/** moves a TempoSection to a specified position. + * @param ts - the section to be moved + * @param frame - the new position in frames for the tempo + * @param sub_num - the snap division to use if using musical time. + * + * if sub_num is non-zero, the frame position is used to calculate an exact + * musical position. + * sub_num | effect + * -1 | snap to bars (meter-based) + * 0 | no snap - use audio frame for musical position + * 1 | snap to meter-based (BBT) beat + * >1 | snap to quarter-note subdivision (i.e. 4 will snap to sixteenth notes) + * + * this follows the snap convention in the gui. + * if sub_num is zero, the musical position will be taken from the supplied frame. + */ void TempoMap::gui_move_tempo (TempoSection* ts, const framepos_t& frame, const int& sub_num) { @@ -3020,6 +3121,14 @@ TempoMap::gui_move_tempo (TempoSection* ts, const framepos_t& frame, const int& MetricPositionChanged (); // Emit Signal } +/** moves a MeterSection to a specified position. + * @param ms - the section to be moved + * @param frame - the new position in frames for the meter + * + * as a meter cannot snap to anything but bars, + * the supplied frame is rounded to the nearest bar, possibly + * leaving the meter position unchanged. + */ void TempoMap::gui_move_meter (MeterSection* ms, const framepos_t& frame) { @@ -3237,14 +3346,15 @@ TempoMap::gui_dilate_tempo (TempoSection* ts, const framepos_t& frame, const fra MetricPositionChanged (); // Emit Signal } -/** Returns the exact beat corresponding to the bar, beat or quarter note subdivision nearest to +/** Returns the exact bbt-based beat corresponding to the bar, beat or quarter note subdivision nearest to * the supplied frame, possibly returning a negative value. * @param frame The session frame position. * @param sub_num The subdivision to use when rounding the beat. - * A value of -1 indicates rounding to BBT bar. 1 indicates rounding to BBT beats. - * Positive integers indicate quarter note (non BBT) divisions. - * 0 indicates that the returned beat should not be rounded. + * A value of -1 indicates rounding to BBT bar. 1 indicates rounding to BBT beats. + * Positive integers indicate quarter note (non BBT) divisions. + * 0 indicates that the returned beat should not be rounded (equivalent to quarter_note_at_frame()). * @return The beat position of the supplied frame. + * * If the supplied frame lies before the first meter, the return will be negative, * in which case the returned beat uses the first meter (for BBT subdivisions) and * the continuation of the tempo curve (backwards). @@ -3267,12 +3377,16 @@ TempoMap::exact_beat_at_frame_locked (const Metrics& metrics, const framepos_t& /** Returns the exact quarter note corresponding to the bar, beat or quarter note subdivision nearest to * the supplied frame, possibly returning a negative value. + * Supplying a frame position with a non-zero sub_num is equivalent to supplying + * a quarter-note musical position without frame rounding (see below) + * * @param frame The session frame position. * @param sub_num The subdivision to use when rounding the quarter note. - * A value of -1 indicates rounding to BBT bar. 1 indicates rounding to BBT beats. - * Positive integers indicate quarter note (non BBT) divisions. - * 0 indicates that the returned quarter note should not be rounded. + * A value of -1 indicates rounding to BBT bar. 1 indicates rounding to BBT beats. + * Positive integers indicate quarter note (non BBT) divisions. + * 0 indicates that the returned quarter note should not be rounded (equivalent to quarter_note_at_frame()). * @return The quarter note position of the supplied frame. + * * If the supplied frame lies before the first meter, the return will be negative, * in which case the returned quarter note uses the first meter (for BBT subdivisions) and * the continuation of the tempo curve (backwards). @@ -3317,6 +3431,12 @@ TempoMap::exact_qn_at_frame_locked (const Metrics& metrics, const framepos_t& fr return qn; } +/** returns the frame duration of the supplied BBT time at a specified frame position in the tempo map. + * @param pos the frame position in the tempo map. + * @param bbt the distance in BBT time from pos to calculate. + * @param dir the rounding direction.. + * @return the duration in frames between pos and bbt +*/ framecnt_t TempoMap::bbt_duration_at (framepos_t pos, const BBT_Time& bbt, int dir) {