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