slave.h

Go to the documentation of this file.

/*
    Copyright (C) 2002 Paul Davis

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

*/

#ifndef __ardour_slave_h__
#define __ardour_slave_h__

#include <vector>

#include <glibmm/threads.h>

#include <ltc.h>

#include "pbd/signals.h"

#include "timecode/time.h"

#include "ardour/libardour_visibility.h"
#include "ardour/types.h"
#include "midi++/parser.h"
#include "midi++/types.h"


/* used for approximate_current_delta(): */
#define PLUSMINUS(A) ( ((A)<0) ? "-" : (((A)>0) ? "+" : "\u00B1") )
#define LEADINGZERO(A) ( (A)<10 ? "   " : (A)<100 ? "  " : (A)<1000 ? " " : "" )

namespace ARDOUR {

class TempoMap;
class Session;
class AudioEngine;
class MidiPort;

class LIBARDOUR_API Slave {
  public:
        Slave() { }
        virtual ~Slave() {}

        virtual bool speed_and_position (double& speed, framepos_t& position) = 0;

        virtual bool locked() const = 0;

        virtual bool ok() const = 0;

        virtual bool starting() const { return false; }

        virtual framecnt_t resolution() const = 0;

        virtual bool requires_seekahead () const = 0;

        virtual framecnt_t seekahead_distance() const { return 0; }

        virtual bool is_always_synced() const { return false; }

        virtual bool give_slave_full_control_over_transport_speed() const { return false; }

        virtual std::string approximate_current_delta() const { return ""; }

};

class LIBARDOUR_API ISlaveSessionProxy {
  public:
        virtual ~ISlaveSessionProxy() {}
        virtual TempoMap&  tempo_map()                  const   { return *((TempoMap *) 0); }
        virtual framecnt_t frame_rate()                 const   { return 0; }
        virtual pframes_t  frames_per_cycle()           const   { return 0; }
        virtual framepos_t audible_frame ()             const   { return 0; }
        virtual framepos_t transport_frame ()           const   { return 0; }
        virtual pframes_t  frames_since_cycle_start ()  const   { return 0; }
        virtual framepos_t sample_time_at_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*/)                   {}
};


class LIBARDOUR_API SlaveSessionProxy : public ISlaveSessionProxy {
        Session&    session;

  public:
        SlaveSessionProxy(Session &s) : session(s) {}

        TempoMap&  tempo_map()                   const;
        framecnt_t frame_rate()                  const;
        pframes_t  frames_per_cycle()            const;
        framepos_t audible_frame ()              const;
        framepos_t transport_frame ()            const;
        pframes_t  frames_since_cycle_start ()   const;
        framepos_t sample_time_at_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 LIBARDOUR_API SafeTime {
        volatile int guard1;
        framepos_t   position;
        framepos_t   timestamp;
        double       speed;
        volatile int guard2;

        SafeTime() {
                guard1 = 0;
                position = 0;
                timestamp = 0;
                speed = 0;
                guard2 = 0;
        }
};

class LIBARDOUR_API TimecodeSlave : public Slave {
  public:
    TimecodeSlave () {}

    virtual Timecode::TimecodeFormat apparent_timecode_format() const = 0;

    /* this is intended to be used by a UI and polled from a timeout. it should
       return a string describing the current position of the TC source. it
       should NOT do any computation, but should use a cached value
       of the TC source position.
    */
    virtual std::string approximate_current_position() const = 0;

    framepos_t        timecode_offset;
    bool              timecode_negative_offset;
};

class LIBARDOUR_API MTC_Slave : public TimecodeSlave {
  public:
        MTC_Slave (Session&, MidiPort&);
        ~MTC_Slave ();

        void rebind (MidiPort&);
        bool speed_and_position (double&, framepos_t&);

        bool locked() const;
        bool ok() const;
        void handle_locate (const MIDI::byte*);

        framecnt_t resolution () const;
        bool requires_seekahead () const { return false; }
        framecnt_t seekahead_distance() const;
        bool give_slave_full_control_over_transport_speed() const;

        Timecode::TimecodeFormat apparent_timecode_format() const;
        std::string approximate_current_position() const;
        std::string approximate_current_delta() const;

  private:
        Session&    session;
        MidiPort*   port;
        PBD::ScopedConnectionList port_connections;
        PBD::ScopedConnection     config_connection;
        bool        can_notify_on_unknown_rate;

        static const int frame_tolerance;

        SafeTime       current;
        framepos_t     mtc_frame;               /* current time */
        double         mtc_frame_dll;
        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     first_mtc_timestamp;
        bool           did_reset_tc_format;
        Timecode::TimecodeFormat saved_tc_format;
        Glib::Threads::Mutex    reset_lock;
        uint32_t       reset_pending;
        bool           reset_position;
        int            transport_direction;
        int            busy_guard1;
        int            busy_guard2;

        double         speedup_due_to_tc_mismatch;
        double         quarter_frame_duration;
        Timecode::TimecodeFormat mtc_timecode;
        Timecode::TimecodeFormat a3e_timecode;
        Timecode::Time timecode;
        bool           printed_timecode_warning;
        frameoffset_t  current_delta;

        /* DLL - chase MTC */
        double t0; 
        double t1; 
        double e2; 
        double b, c, omega; 

        /* DLL - sync engine */
        int    engine_dll_initstate;
        double te0; 
        double te1; 
        double ee2; 
        double be, ce, oe; 

        void reset (bool with_pos);
        void queue_reset (bool with_pos);
        void maybe_reset ();

        void update_mtc_qtr (MIDI::Parser&, int, framepos_t);
        void update_mtc_time (const MIDI::byte *, bool, framepos_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 init_mtc_dll(framepos_t, double);
        void init_engine_dll (framepos_t, framepos_t);
        void parse_timecode_offset();
        void parameter_changed(std::string const & p);
};

class LIBARDOUR_API LTC_Slave : public TimecodeSlave {
public:
        LTC_Slave (Session&);
        ~LTC_Slave ();

        bool speed_and_position (double&, framepos_t&);

        bool locked() const;
        bool ok() const;

        framecnt_t resolution () const;
        bool requires_seekahead () const { return false; }
        framecnt_t seekahead_distance () const { return 0; }
        bool give_slave_full_control_over_transport_speed() const { return true; }

        Timecode::TimecodeFormat apparent_timecode_format() const;
        std::string approximate_current_position() const;
        std::string approximate_current_delta() const;

  private:
        void parse_ltc(const pframes_t, const Sample* const, const framecnt_t);
        void process_ltc(framepos_t const);
        void init_engine_dll (framepos_t, int32_t);
        bool detect_discontinuity(LTCFrameExt *, int, bool);
        bool detect_ltc_fps(int, bool);
        bool equal_ltc_frame_time(LTCFrame *a, LTCFrame *b);
        void reset();
        void resync_xrun();
        void resync_latency();
        void parse_timecode_offset();
        void parameter_changed(std::string const & p);

        Session&       session;
        bool           did_reset_tc_format;
        Timecode::TimecodeFormat saved_tc_format;

        LTCDecoder *   decoder;
        double         frames_per_ltc_frame;
        Timecode::Time timecode;
        LTCFrameExt    prev_frame;
        bool           fps_detected;

        framecnt_t     monotonic_cnt;
        framecnt_t     last_timestamp;
        framecnt_t     last_ltc_frame;
        double         ltc_speed;
        frameoffset_t  current_delta;
        int            delayedlocked;

        int            ltc_detect_fps_cnt;
        int            ltc_detect_fps_max;
        bool           printed_timecode_warning;
        bool           sync_lock_broken;
        Timecode::TimecodeFormat ltc_timecode;
        Timecode::TimecodeFormat a3e_timecode;

        PBD::ScopedConnectionList port_connections;
        PBD::ScopedConnection     config_connection;
        LatencyRange  ltc_slave_latency;

        /* DLL - chase LTC */
        int    transport_direction;
        int    engine_dll_initstate;
        double t0; 
        double t1; 
        double e2; 
        double b, c; 
};

class LIBARDOUR_API MIDIClock_Slave : public Slave {
  public:
        MIDIClock_Slave (Session&, MidiPort&, int ppqn = 24);

        MIDIClock_Slave (ISlaveSessionProxy* session_proxy = 0, int ppqn = 24);
        ~MIDIClock_Slave ();

        void rebind (MidiPort&);
        bool speed_and_position (double&, framepos_t&);

        bool locked() const;
        bool ok() const;
        bool starting() const;

        framecnt_t resolution () const;
        bool requires_seekahead () const { return false; }
        bool give_slave_full_control_over_transport_speed() const { return true; }

        void set_bandwidth (double a_bandwith) { bandwidth = a_bandwith; }
        std::string approximate_current_delta() const;

  protected:
        ISlaveSessionProxy* session;
        PBD::ScopedConnectionList port_connections;

        int         ppqn;

        double      one_ppqn_in_frames;

        framepos_t  first_timestamp;

        framepos_t  last_timestamp;
        double      should_be_position;

        long midi_clock_count;

        //the delay locked loop (DLL), see www.kokkinizita.net/papers/usingdll.pdf

        double t0;

        double t1;

        double e;

        double e2;

        double bandwidth;

        double b, c, omega;

        frameoffset_t  current_delta;

        void reset ();
        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);

        bool _started;

        bool _starting;
};

class LIBARDOUR_API Engine_Slave : public Slave
{
  public:
        Engine_Slave (AudioEngine&);
        ~Engine_Slave ();

        bool speed_and_position (double& speed, framepos_t& pos);

        bool starting() const { return _starting; }
        bool locked() const;
        bool ok() const;
        framecnt_t resolution () const { return 1; }
        bool requires_seekahead () const { return false; }
        bool is_always_synced() const { return true; }

  private:
        AudioEngine& engine;
        bool _starting;
};

} /* namespace */

#endif /* __ardour_slave_h__ */