2 Copyright (C) 2013 Paul Davis
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.
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.
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.
20 #ifndef __libardour_port_engine_h__
21 #define __libardour_port_engine_h__
28 #include "ardour/data_type.h"
29 #include "ardour/types.h"
35 /** PortEngine is an abstract base class that defines the functionality
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.
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.
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.
60 * Ports also have latency associated with them. Each port has a playback
61 * latency and a capture latency:
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.
69 * <b>playback latency</b>: how long until the data written to the buffer of
70 * port will reach a terminal port.
73 * For more detailed questions about the PortEngine API, consult the JACK API
74 * documentation, on which this entire object is based.
79 PortEngine (PortManager& pm) : manager (pm) {}
80 virtual ~PortEngine() {}
82 /* We use void* here so that the API can be defined for any implementation.
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>.
90 typedef void* PortHandle;
92 /** Return a typeless pointer to an object that may be of interest
93 * that understands the internals of a particular PortEngine
96 * XXX the existence of this method is a band-aid over some design
97 * issues and will it will be removed in the future
99 virtual void* private_handle() const = 0;
101 /** Return the name of this process as used by the port manager
104 virtual const std::string& my_name() const = 0;
106 /** Return the maximum size of a port name
108 virtual uint32_t port_name_size() const = 0;
110 /** Returns zero if the port referred to by @param port was set to @param
111 * name. Return non-zero otherwise.
113 virtual int set_port_name (PortHandle port, const std::string& name) = 0;
114 /** Return the name of the port referred to by @param port. If the port
115 * does not exist, return an empty string.
117 virtual std::string get_port_name (PortHandle) const = 0;
118 /** Return a reference to a port with the fullname @param name. Return
119 * a null pointer if no such port exists.
121 virtual PortHandle* get_port_by_name (const std::string&) const = 0;
123 /** Find the set of ports whose names, types and flags match
124 * specified values, place the names of each port into @param ports,
125 * and return the count of the number found.
127 * To avoid selecting by name, pass an empty string for @param
130 * To avoid selecting by type, pass DataType::NIL as @param type.
132 * To avoid selecting by flags, pass PortFlags (0) as @param flags.
134 virtual int get_ports (const std::string& port_name_pattern, DataType type, PortFlags flags, std::vector<std::string>& ports) const = 0;
136 /** Return the Ardour data type handled by the port referred to by @param
137 * port. Returns DataType::NIL if the port does not exist.
139 virtual DataType port_data_type (PortHandle port) const = 0;
141 /** Create a new port whose fullname will be the conjuction of my_name(),
142 * ":" and @param shortname. The port will handle data specified by @param
143 * type and will have the flags given by @param flags. If successfull,
144 * return a reference to the port, otherwise return a null pointer.
146 virtual PortHandle register_port (const std::string& shortname, ARDOUR::DataType type, ARDOUR::PortFlags flags) = 0;
148 /* Destroy the port referred to by @param port, including all resources
149 * associated with it. This will also disconnect @param port from any ports it
152 virtual void unregister_port (PortHandle) = 0;
154 /* Connection management */
156 /** Ensure that data written to the port named by @param src will be
157 * readable from the port named by @param dst. Return zero on success,
158 * non-zero otherwise.
160 virtual int connect (const std::string& src, const std::string& dst) = 0;
162 /** Remove any existing connection between the ports named by @param src and
163 * @param dst. Return zero on success, non-zero otherwise.
165 virtual int disconnect (const std::string& src, const std::string& dst) = 0;
168 /** Ensure that data written to the port referenced by @param portwill be
169 * readable from the port named by @param dst. Return zero on success,
170 * non-zero otherwise.
172 virtual int connect (PortHandle src, const std::string& dst) = 0;
173 /** Remove any existing connection between the port referenced by @param src and
174 * the port named @param dst. Return zero on success, non-zero otherwise.
176 virtual int disconnect (PortHandle src, const std::string& dst) = 0;
178 /** Remove all connections between the port referred to by @param port and
179 * any other ports. Return zero on success, non-zero otherwise.
181 virtual int disconnect_all (PortHandle port) = 0;
183 /** Return true if the port referred to by @param port has any connections
184 * to other ports. Return false otherwise.
186 virtual bool connected (PortHandle port) = 0;
187 /** Return true if the port referred to by @param port is connected to
188 * the port named by @param name. Return false otherwise.
190 virtual bool connected_to (PortHandle, const std::string& name) = 0;
192 /** Return true if the port referred to by @param port has any connections
193 * to ports marked with the PortFlag IsPhysical. Return false otherwise.
195 virtual bool physically_connected (PortHandle port) = 0;
197 /** Place the names of all ports connected to the port named by @param
198 * ports into @param names, and return the number of connections.
200 virtual int get_connections (PortHandle port, std::vector<std::string>& names) = 0;
204 /** Retrieve a MIDI event from the data at @param port_buffer. The event
205 number to be retrieved is given by @param event_index (a value of zero
206 indicates that the first event in the port_buffer should be retrieved).
208 * The data associated with the event will be copied into the buffer at
209 * @param buf and the number of bytes written will be stored in @param
210 * size. The timestamp of the event (which is always relative to the start
211 * of the current process cycle, in samples) will be stored in @param
214 virtual int midi_event_get (pframes_t& timestamp, size_t& size, uint8_t** buf, void* port_buffer, uint32_t event_index) = 0;
216 /** Place a MIDI event consisting of @param size bytes copied from the data
217 * at @param buf into the port buffer referred to by @param
218 * port_buffer. The MIDI event will be marked with a time given by @param
219 * timestamp. Return zero on success, non-zero otherwise.
221 * Events must be added monotonically to a port buffer. An attempt to
222 * add a non-monotonic event (e.g. out-of-order) will cause this method
223 * to return a failure status.
225 virtual int midi_event_put (void* port_buffer, pframes_t timestamp, const uint8_t* buffer, size_t size) = 0;
227 /** Return the number of MIDI events in the data at @param port_buffer
229 virtual uint32_t get_midi_event_count (void* port_buffer) = 0;
231 /** Clear the buffer at @param port_buffer of all MIDI events.
233 * After a call to this method, an immediate, subsequent call to
234 * get_midi_event_count() with the same @param port_buffer argument must
237 virtual void midi_clear (void* port_buffer) = 0;
241 /** Return true if the implementation can offer input monitoring.
243 * Input monitoring involves the (selective) routing of incoming data
244 * to an outgoing data stream, without the data being passed to the CPU.
246 * Only certain audio hardware can provide this, and only certain audio
249 virtual bool can_monitor_input() const = 0;
250 /** Increment or decrement the number of requests to monitor the input
251 * of the hardware channel represented by the port referred to by @param
254 * If the number of requests rises above zero, input monitoring will
255 * be enabled (if can_monitor_input() returns true for the implementation).
257 * If the number of requests falls to zero, input monitoring will be
258 * disabled (if can_monitor_input() returns true for the implementation)
260 virtual int request_input_monitoring (PortHandle port, bool yn) = 0;
261 /* Force input monitoring of the hardware channel represented by the port
262 * referred to by @param port to be on or off, depending on the true/false
263 * status of @param yn. The request count is ignored when using this
264 * method, so if this is called with yn set to false, input monitoring will
265 * be disabled regardless of the number of requests to enable it.
267 virtual int ensure_input_monitoring (PortHandle port, bool yn) = 0;
268 /** Return true if input monitoring is enabled for the hardware channel
269 * represented by the port referred to by @param port. Return false
272 virtual bool monitoring_input (PortHandle port) = 0;
274 /* Latency management
277 /** Set the latency range for the port referred to by @param port to @param
278 * r. The playback range will be set if @param for_playback is true,
279 * otherwise the capture range will be set.
281 virtual void set_latency_range (PortHandle port, bool for_playback, LatencyRange r) = 0;
282 /** Return the latency range for the port referred to by @param port.
283 * The playback range will be returned if @param for_playback is true,
284 * otherwise the capture range will be returned.
286 virtual LatencyRange get_latency_range (PortHandle port, bool for_playback) = 0;
288 /* Discovering physical ports */
290 /** Return true if the port referred to by @param port has the IsPhysical
291 * flag set. Return false otherwise.
293 virtual bool port_is_physical (PortHandle port) const = 0;
295 /** Store into @param names the names of all ports with the IsOutput and
296 * IsPhysical flag set, that handle data of type @param type.
298 * This can be used to discover outputs associated with hardware devices.
300 virtual void get_physical_outputs (DataType type, std::vector<std::string>& names) = 0;
301 /** Store into @param names the names of all ports with the IsInput and
302 * IsPhysical flags set, that handle data of type @param type.
304 * This can be used to discover inputs associated with hardware devices.
306 virtual void get_physical_inputs (DataType type, std::vector<std::string>& names) = 0;
307 /** Return the total count (possibly mixed between different data types)
308 of the number of ports with the IsPhysical and IsOutput flags set.
310 virtual ChanCount n_physical_outputs () const = 0;
311 /** Return the total count (possibly mixed between different data types)
312 of the number of ports with the IsPhysical and IsInput flags set.
314 virtual ChanCount n_physical_inputs () const = 0;
316 /** Return the address of the memory area where data for the port can be
317 * written (if the port has the PortFlag IsOutput set) or read (if the port
318 * has the PortFlag IsInput set).
320 * The return value is untyped because buffers containing different data
321 * depending on the port type.
323 virtual void* get_buffer (PortHandle, pframes_t) = 0;
325 /* MIDI ports (the ones in libmidi++) need this to be able to correctly
326 * schedule MIDI events within their buffers. It is a bit odd that we
327 * expose this here, because it is also exposed by AudioBackend, but they
328 * only have access to a PortEngine object, not an AudioBackend.
330 * Return the time according to the sample clock in use when the current
331 * buffer process cycle began.
333 * XXX to be removed after some more design cleanup.
335 virtual pframes_t sample_time_at_cycle_start () = 0;
338 PortManager& manager;
343 #endif /* __libardour_port_engine_h__ */