libs/ardour/ardour/port_engine.h

   1 /*
   2     Copyright (C) 2013 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 __libardour_port_engine_h__
  21 #define __libardour_port_engine_h__
  22
  23 #include <vector>
  24 #include <string>
  25
  26 #include <stdint.h>
  27
  28 #include "ardour/data_type.h"
  29 #include "ardour/types.h"
  30
  31 namespace ARDOUR {
  32
  33 /** PortEngine is an abstract base class that defines the functionality
  34  * required by Ardour.
  35  *
  36  * A Port is basically an endpoint for a datastream (which can either be
  37  * continuous, like audio, or event-based, like MIDI). Ports have buffers
  38  * associated with them into which data can be written (if they are output
  39  * ports) and from which data can be read (if they input ports). Ports can be
  40  * connected together so that data written to an output port can be read from
  41  * an input port. These connections can be 1:1, 1:N OR N:1.
  42  *
  43  * Ports may be associated with software only, or with hardware.  Hardware
  44  * related ports are often referred to as physical, and correspond to some
  45  * relevant physical entity on a hardware device, such as an audio jack or a
  46  * MIDI connector. Physical ports may be potentially asked to monitor their
  47  * inputs, though some implementations may not support this.
  48  *
  49  * Most physical ports will also be considered "terminal", which means that
  50  * data delivered there or read from there will go to or comes from a system
  51  * outside of the PortEngine implementation's control (e.g. the analog domain
  52  * for audio, or external MIDI devices for MIDI). Non-physical ports can also
  53  * be considered "terminal". For example, the output port of a software
  54  * synthesizer is a terminal port, because the data contained in its buffer
  55  * does not and cannot be considered to come from any other port - it is
  56  * synthesized by its owner.
  57  *
  58  * Ports also have latency associated with them. Each port has a playback
  59  * latency and a capture latency:
  60  *
  61  * <b>capture latency</b>: how long since the data read from the buffer of a
  62  *                  port arrived at at a terminal port.  The data will have
  63  *                  come from the "outside world" if the terminal port is also
  64  *                  physical, or will have been synthesized by the entity that
  65  *                  owns the terminal port.
  66  *
  67  * <b>playback latency</b>: how long until the data written to the buffer of
  68  *                   port will reach a terminal port.
  69  *
  70  *
  71  * For more detailed questions about the PortEngine API, consult the JACK API
  72  * documentation, on which this entire object is based.
  73  */
  74
  75 class PortEngine {
  76   public:
  77     PortEngine() {}
  78     virtual ~PortEngine();
  79
  80     /* We use void* here so that the API can be defined for any implementation.
  81      *
  82      * We could theoretically use a template (PortEngine<T>) and define
  83      * PortHandle as T, but this complicates the desired inheritance
  84      * pattern in which FooPortEngine handles things for the Foo API,
  85      * rather than being a derivative of PortEngine<Foo>.
  86     */
  87
  88     typedef void* PortHandle;
  89
  90     virtual bool  connected() const = 0;
  91     virtual void* private_handle() const = 0;
  92
  93     virtual int         set_port_name (PortHandle, const std::string&) = 0;
  94     virtual std::string get_port_name (PortHandle) const = 0;
  95     virtual PortHandle* get_port_by_name (const std::string&) const = 0;
  96
  97     DataType port_data_type (PortHandle) const;
  98
  99     virtual std::string make_port_name_relative (const std::string& name) const = 0;
 100     virtual std::string make_port_name_non_relative (const std::string& name) const = 0;
 101     virtual bool        port_is_mine (const std::string& fullname) const = 0;
 102
 103     virtual PortHandle register_port (const std::string& shortname, ARDOUR::DataType, ARDOUR::PortFlags) = 0;
 104     virtual void  unregister_port (PortHandle) = 0;
 105
 106     virtual bool  connected (PortHandle) = 0;
 107     virtual bool  connected_to (PortHandle, const std::string&) = 0;
 108     virtual bool  physically_connected (PortHandle) = 0;
 109
 110     virtual int   get_connections (PortHandle, std::vector<std::string>&) = 0;
 111
 112     virtual int   connect (PortHandle, const std::string&) = 0;
 113     virtual int   disconnect (PortHandle, const std::string&) = 0;
 114     virtual int   disconnect_all (PortHandle) = 0;
 115
 116     virtual int   connect (const std::string& src, const std::string& dst) = 0;
 117     virtual int   disconnect (const std::string& src, const std::string& dst) = 0;
 118
 119     /* MIDI */
 120
 121     virtual void     midi_event_get (pframes_t& timestamp, size_t& size, uint8_t** buf, void* port_buffer, uint32_t event_index) = 0;
 122     virtual int      midi_event_put (void* port_buffer, pframes_t timestamp, const uint8_t* buffer, size_t size) = 0;
 123     virtual uint32_t get_midi_event_count (void* port_buffer);
 124     virtual void     midi_clear (void* port_buffer);
 125
 126     /* Monitoring */
 127
 128     virtual bool  can_monitor_input() const = 0;
 129     virtual int   request_input_monitoring (PortHandle, bool) = 0;
 130     virtual int   ensure_input_monitoring (PortHandle, bool) = 0;
 131     virtual bool  monitoring_input (PortHandle) = 0;
 132
 133     /* Latency management
 134      */
 135
 136     virtual void          set_latency_range (PortHandle, bool for_playback, LatencyRange) = 0;
 137     virtual LatencyRange  get_latency_range (PortHandle, bool for_playback) = 0;
 138     virtual LatencyRange  get_connected_latency_range (PortHandle, int dir) = 0;
 139
 140     virtual void* get_buffer (PortHandle, pframes_t) = 0;
 141
 142     virtual pframes_t last_frame_time () const = 0;
 143 };
 144
 145 }
 146
 147 #endif /* __libardour_port_engine_h__ */