X-Git-Url: https://main.carlh.net/gitweb/?a=blobdiff_plain;f=libs%2Fardour%2Fardour%2Fslave.h;h=74cf4371b0e801e592512514a22aacfad0e44d76;hb=ba0458cf1f6c69366e89631d8fff916ad183d768;hp=80fac38a2a2c8035f019f1754c395134a8a8f33c;hpb=75e918080093a6ca88abe010c07d883afc697520;p=ardour.git diff --git a/libs/ardour/ardour/slave.h b/libs/ardour/ardour/slave.h index 80fac38a2a..74cf4371b0 100644 --- a/libs/ardour/ardour/slave.h +++ b/libs/ardour/ardour/slave.h @@ -22,30 +22,38 @@ #include +#include +#include + #include -#include -#include -#include -#include +#include "pbd/signals.h" + +#include "ardour/types.h" +#include "midi++/parser.h" +#include "midi++/types.h" + +class PIChaser; namespace MIDI { class Port; } namespace ARDOUR { + +class TempoMap; class Session; /** * @class Slave - * - * @brief The class Slave can be used to sync ardours tempo to an external source + * + * @brief The Slave interface can be used to sync ARDOURs tempo to an external source * like MTC, MIDI Clock, etc. - * - * The name of the class may be a bit misleading: A subclass of Slave actually - * acts as a master for Ardour, that means Ardour will try to follow the + * + * The name of the interface may be a bit misleading: A subclass of Slave actually + * acts as a time master for ARDOUR, that means ARDOUR will try to follow the * speed and transport position of the implementation of Slave. - * Therefor it is rather that class, that makes Ardour a slave by connecting it + * Therefore it is rather that class, that makes ARDOUR a slave by connecting it * to its external time master. */ class Slave { @@ -57,121 +65,170 @@ class Slave { * This is the most important function to implement: * Each process cycle, Session::follow_slave will call this method. * and after the method call they should - * + * * Session::follow_slave will then try to follow the given - * position using a delay locked loop (DLL), + * position using a delay locked loop (DLL), * starting with the first given transport speed. * If the values of speed and position contradict each other, - * ardour will always follow the position and disregard the speed. - * Although, a correct speed is important so that ardour + * ARDOUR will always follow the position and disregard the speed. + * Although, a correct speed is important so that ARDOUR * can sync to the master time source quickly. - * - * For background information on delay locked loops, + * + * For background information on delay locked loops, * see http://www.kokkinizita.net/papers/usingdll.pdf - * + * * The method has the following precondition: *
    - *
  • - * Slave::ok() should return true, otherwise playback will stop + *
  • + * Slave::ok() should return true, otherwise playback will stop * immediately and the method will not be called - *
    • + * *
  • * when the references speed and position are passed into the Slave * they are uninitialized *
    • *
- * + * * After the method call the following postconditions should be met: *
    - *
  • + *
  • * The first position value on transport start should be 0, - * otherwise ardour will try to locate to the new position + * otherwise ARDOUR will try to locate to the new position * rather than move to it *
    • - *
  • - * the references speed and position should be assigned + *
  • + * the references speed and position should be assigned * to the Slaves current requested transport speed * and transport position. *
    • *
  • - * Slave::resolution() should be greater than the maximum distance of - * ardours transport position to the slaves requested transport position. - * (Otherwise Session:average_slave_delta will become negative, and - * the transport will move silently) + * Slave::resolution() should be greater than the maximum distance of + * ARDOURs transport position to the slaves requested transport position. *
    • - *
  • Slave::locked() should return true, otherwise Session::no_roll will be called
    • - *
  • Slave::starting() should be false, otherwise the transport will not move until it becomes true
    • * + *
  • Slave::locked() should return true, otherwise Session::no_roll will be called
    • + *
  • Slave::starting() should be false, otherwise the transport will not move until it becomes true
    • * *
- * + * * @param speed - The transport speed requested * @param position - The transport position requested + * @return - The return value is currently ignored (see Session::follow_slave) */ - virtual bool speed_and_position (float& speed, nframes_t& position) = 0; - + virtual bool speed_and_position (double& speed, framepos_t& position) = 0; + /** - * reports to ardour whether the Slave is currently synced to its external + * reports to ARDOUR whether the Slave is currently synced to its external * time source. - * + * * @return - when returning false, the transport will stop rolling */ virtual bool locked() const = 0; - + /** - * reports to ardour whether the slave is in a sane state - * - * @return - when returning false, the transport will be stopped and the slave - * disconnected from ardour. + * reports to ARDOUR whether the slave is in a sane state + * + * @return - when returning false, the transport will be stopped and the slave + * disconnected from ARDOUR. */ virtual bool ok() const = 0; - + /** - * reports to ardour whether the slave is in the process of starting + * reports to ARDOUR whether the slave is in the process of starting * to roll - * + * * @return - when returning false, transport will not move until this method returns true */ virtual bool starting() const { return false; } - + /** - * @return - the timing resolution of the Slave - If the distance of ardours transport - * to the slave becomes negative or greater than the resolution, sound will stop - * (Session::follow_slave label silent_motion) + * @return - the timing resolution of the Slave - If the distance of ARDOURs transport + * to the slave becomes greater than the resolution, sound will stop */ virtual nframes_t resolution() const = 0; - + /** - * @return - when returning true, ardour will wait for one second before transport + * @return - when returning true, ARDOUR will wait for seekahead_distance() before transport * starts rolling */ virtual bool requires_seekahead () const = 0; - + + /** + * @return the number of frames that this slave wants to seek ahead. Relevant + * only if requires_seekahead() returns true. + */ + + virtual framepos_t seekahead_distance() const { return 0; } + /** - * @return - when returning true, ardour will use transport speed 1.0 no matter what + * @return - when returning true, ARDOUR will use transport speed 1.0 no matter what * the slave returns */ virtual bool is_always_synced() const { return false; } + + /** + * @return - whether ARDOUR should use the slave speed without any adjustments + */ + virtual bool give_slave_full_control_over_transport_speed() const { return false; } +}; + +/// We need this wrapper for testability, it's just too hard to mock up a session class +class ISlaveSessionProxy { + public: + virtual ~ISlaveSessionProxy() {} + virtual TempoMap& tempo_map() const { return *((TempoMap *) 0); } + virtual nframes_t frame_rate() const { return 0; } + virtual framepos_t audible_frame () const { return 0; } + virtual framepos_t transport_frame () const { return 0; } + virtual nframes_t frames_since_cycle_start () const { return 0; } + virtual framepos_t frame_time () const { return 0; } + + virtual void request_locate (framepos_t /*frame*/, bool with_roll = false) { + (void) with_roll; + } + virtual void request_transport_speed (double /*speed*/) {} }; -struct SafeTime { - int guard1; - nframes_t position; - nframes_t timestamp; - int guard2; +/// The Session Proxy for use in real Ardour +class SlaveSessionProxy : public ISlaveSessionProxy { + Session& session; + + public: + SlaveSessionProxy(Session &s) : session(s) {} + + TempoMap& tempo_map() const; + nframes_t frame_rate() const; + framepos_t audible_frame () const; + framepos_t transport_frame () const; + nframes_t frames_since_cycle_start () const; + framepos_t frame_time () const; + + void request_locate (framepos_t frame, bool with_roll = false); + void request_transport_speed (double speed); +}; + +struct SafeTime { + volatile int guard1; + framepos_t position; + framepos_t timestamp; + double speed; + volatile int guard2; + SafeTime() { guard1 = 0; - guard2 = 0; + position = 0; timestamp = 0; + speed = 0; + guard2 = 0; } }; -class MTC_Slave : public Slave, public sigc::trackable { +class MTC_Slave : public Slave { public: MTC_Slave (Session&, MIDI::Port&); ~MTC_Slave (); void rebind (MIDI::Port&); - bool speed_and_position (float&, nframes_t&); + bool speed_and_position (double&, framepos_t&); bool locked() const; bool ok() const; @@ -179,114 +236,141 @@ class MTC_Slave : public Slave, public sigc::trackable { nframes_t resolution() const; bool requires_seekahead () const { return true; } + framepos_t seekahead_distance() const; + bool give_slave_full_control_over_transport_speed() const; private: Session& session; MIDI::Port* port; - std::vector connections; + PBD::ScopedConnectionList port_connections; bool can_notify_on_unknown_rate; - - SafeTime current; - nframes_t mtc_frame; /* current time */ - nframes_t last_inbound_frame; /* when we got it; audio clocked */ - - float mtc_speed; - nframes_t first_mtc_frame; - nframes_t first_mtc_time; - - static const int32_t accumulator_size = 128; - float accumulator[accumulator_size]; - int32_t accumulator_index; - bool have_first_accumulated_speed; - - void reset (); - void update_mtc_qtr (MIDI::Parser&); - void update_mtc_time (const MIDI::byte *, bool); - void update_mtc_status (MIDI::Parser::MTC_Status); + PIChaser* pic; + + static const int frame_tolerance; + + SafeTime current; + framepos_t mtc_frame; /* current time */ + framepos_t last_inbound_frame; /* when we got it; audio clocked */ + MIDI::byte last_mtc_fps_byte; + framepos_t window_begin; + framepos_t window_end; + framepos_t last_mtc_timestamp; + framepos_t last_mtc_frame; + bool did_reset_tc_format; + TimecodeFormat saved_tc_format; + size_t speed_accumulator_size; + double* speed_accumulator; + size_t speed_accumulator_cnt; + bool have_first_speed_accumulator; + double average_speed; + Glib::Mutex reset_lock; + uint32_t reset_pending; + bool reset_position; + + void reset (bool with_pos); + void queue_reset (bool with_pos); + void maybe_reset (); + + void update_mtc_qtr (MIDI::Parser&, int, nframes_t); + void update_mtc_time (const MIDI::byte *, bool, nframes_t); + void update_mtc_status (MIDI::MTC_Status); void read_current (SafeTime *) const; + void reset_window (framepos_t); + bool outside_window (framepos_t) const; + void process_apparent_speed (double); }; -class MIDIClock_Slave : public Slave, public sigc::trackable { +class MIDIClock_Slave : public Slave { public: MIDIClock_Slave (Session&, MIDI::Port&, int ppqn = 24); + + /// Constructor for unit tests + MIDIClock_Slave (ISlaveSessionProxy* session_proxy = 0, int ppqn = 24); ~MIDIClock_Slave (); void rebind (MIDI::Port&); - bool speed_and_position (float&, nframes_t&); + bool speed_and_position (double&, framepos_t&); bool locked() const; bool ok() const; - bool starting() const { return false; } + bool starting() const; nframes_t resolution() const; bool requires_seekahead () const { return false; } + bool give_slave_full_control_over_transport_speed() const { return true; } - private: - Session& session; + void set_bandwidth (double a_bandwith) { bandwidth = a_bandwith; } + + protected: + ISlaveSessionProxy* session; MIDI::Port* port; - std::vector connections; + PBD::ScopedConnectionList port_connections; /// pulses per quarter note for one MIDI clock frame (default 24) int ppqn; - + /// the duration of one ppqn in frame time double one_ppqn_in_frames; - /// the time stamp and transport position of the last inbound MIDI clock message - SafeTime current; - - /// The duration of the current MIDI clock frame in frames - nframes_t current_midi_clock_frame_duration; - /// the timestamp of the last inbound MIDI clock message - nframes_t last_inbound_frame; - - /// how many MIDI clock frames to average over - static const int32_t accumulator_size = 4; - float accumulator[accumulator_size]; - int32_t accumulator_index; - - /// the running average of current_midi_clock_frame_duration - float average_midi_clock_frame_duration; + /// the timestamp of the first MIDI clock message + nframes_t first_timestamp; + + /// the time stamp and should-be transport position of the last inbound MIDI clock message + nframes_t last_timestamp; + double should_be_position; + + /// the number of midi clock messages received (zero-based) + /// since start + long midi_clock_count; + + //the delay locked loop (DLL), see www.kokkinizita.net/papers/usingdll.pdf + + /// time at the beginning of the MIDI clock frame + double t0; + + /// calculated end of the MIDI clock frame + double t1; + + /// loop error = real value - expected value + double e; + + /// second order loop error + double e2; + + /// DLL filter bandwidth + double bandwidth; + + /// DLL filter coefficients + double b, c, omega; void reset (); - void start (MIDI::Parser& parser, nframes_t timestamp); - void stop (MIDI::Parser& parser, nframes_t timestamp); - void update_midi_clock (MIDI::Parser& parser, nframes_t timestamp); + void start (MIDI::Parser& parser, framepos_t timestamp); + void contineu (MIDI::Parser& parser, framepos_t timestamp); + void stop (MIDI::Parser& parser, framepos_t timestamp); + void position (MIDI::Parser& parser, MIDI::byte* message, size_t size); + // we can't use continue because it is a C++ keyword + void calculate_one_ppqn_in_frames_at(framepos_t time); + framepos_t calculate_song_position(uint16_t song_position_in_sixteenth_notes); + void calculate_filter_coefficients(); + void update_midi_clock (MIDI::Parser& parser, framepos_t timestamp); void read_current (SafeTime *) const; + bool stop_if_no_more_clock_events(framepos_t& pos, framepos_t now); /// whether transport should be rolling bool _started; - + /// is true if the MIDI Start message has just been received until - /// the first call of speed_and_position(...) + /// the first MIDI Clock Event bool _starting; }; -class ADAT_Slave : public Slave -{ - public: - ADAT_Slave () {} - ~ADAT_Slave () {} - - bool speed_and_position (float& speed, nframes_t& pos) { - speed = 0; - pos = 0; - return false; - } - - bool locked() const { return false; } - bool ok() const { return false; } - nframes_t resolution() const { return 1; } - bool requires_seekahead () const { return true; } -}; - class JACK_Slave : public Slave { public: JACK_Slave (jack_client_t*); ~JACK_Slave (); - bool speed_and_position (float& speed, nframes_t& pos); + bool speed_and_position (double& speed, framepos_t& pos); bool starting() const { return _starting; } bool locked() const; @@ -298,7 +382,7 @@ class JACK_Slave : public Slave private: jack_client_t* jack; - float speed; + double speed; bool _starting; };