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_audiobackend_h__
21 #define __libardour_audiobackend_h__
29 #include <boost/function.hpp>
31 #include "ardour/libardour_visibility.h"
32 #include "ardour/types.h"
33 #include "ardour/audioengine.h"
34 #include "ardour/port_engine.h"
36 #ifdef ARDOURBACKEND_DLL_EXPORTS // defined if we are building the ARDOUR Panners DLLs (instead of using them)
37 #define ARDOURBACKEND_API LIBARDOUR_DLL_EXPORT
39 #define ARDOURBACKEND_API LIBARDOUR_DLL_IMPORT
41 #define ARDOURBACKEND_LOCAL LIBARDOUR_DLL_LOCAL
45 struct LIBARDOUR_API AudioBackendInfo {
48 /** Using arg1 and arg2, initialize this audiobackend.
50 * Returns zero on success, non-zero otherwise.
52 int (*instantiate) (const std::string& arg1, const std::string& arg2);
54 /** Release all resources associated with this audiobackend
56 int (*deinstantiate) (void);
58 /** Factory method to create an AudioBackend-derived class.
60 * Returns a valid shared_ptr to the object if successfull,
61 * or a "null" shared_ptr otherwise.
63 boost::shared_ptr<AudioBackend> (*factory) (AudioEngine&);
65 /** Return true if the underlying mechanism/API has been
66 * configured and does not need (re)configuration in order
67 * to be usable. Return false otherwise.
69 * Note that this may return true if (re)configuration, even though
70 * not currently required, is still possible.
72 bool (*already_configured)();
74 /** Return true if the underlying mechanism/API can be
75 * used on the given system.
77 * If this function returns false, the backend is not
78 * listed in the engine dialog.
83 /** AudioBackend is an high-level abstraction for interacting with the operating system's
86 class LIBARDOUR_API AudioBackend : public PortEngine {
89 AudioBackend (AudioEngine& e, AudioBackendInfo& i) : PortEngine (e), _info (i), engine (e) {}
90 virtual ~AudioBackend () {}
94 BackendInitializationError = -64,
95 BackendDeinitializationError,
96 BackendReinitializationError,
98 AudioDeviceCloseError,
99 AudioDeviceInvalidError,
100 AudioDeviceNotAvailableError,
101 AudioDeviceNotConnectedError,
102 AudioDeviceReservationError,
105 MidiDeviceCloseError,
106 MidiDeviceNotAvailableError,
107 MidiDeviceNotConnectedError,
109 SampleFormatNotSupportedError,
110 SampleRateNotSupportedError,
111 RequestedInputLatencyNotSupportedError,
112 RequestedOutputLatencyNotSupportedError,
113 PeriodSizeNotSupportedError,
114 PeriodCountNotSupportedError,
115 DeviceConfigurationNotSupportedError,
116 ChannelCountNotSupportedError,
117 InputChannelCountNotSupportedError,
118 OutputChannelCountNotSupportedError,
119 AquireRealtimePermissionError,
120 SettingAudioThreadPriorityError,
121 SettingMIDIThreadPriorityError,
122 ProcessThreadStartError,
123 FreewheelThreadStartError,
124 PortRegistrationError,
129 static std::string get_error_string (ErrorCode);
131 enum StandardDeviceName {
136 static std::string get_standard_device_name (StandardDeviceName);
138 /** Return the AudioBackendInfo object from which this backend
141 AudioBackendInfo& info() const { return _info; }
143 /** Return the name of this backend.
145 * Should use a well-known, unique term. Expected examples
146 * might include "JACK", "CoreAudio", "ASIO" etc.
148 virtual std::string name() const = 0;
150 /** Return true if the callback from the underlying mechanism/API
151 * (CoreAudio, JACK, ASIO etc.) occurs in a thread subject to realtime
152 * constraints. Return false otherwise.
154 virtual bool is_realtime () const = 0;
156 /* Discovering devices and parameters */
158 /** Return true if this backend requires the selection of a "driver"
159 * before any device can be selected. Return false otherwise.
161 * Intended mainly to differentiate between meta-APIs like JACK
162 * which can still expose different backends (such as ALSA or CoreAudio
163 * or FFADO or netjack) and those like ASIO or CoreAudio which
166 virtual bool requires_driver_selection() const { return false; }
168 /** If the return value of requires_driver_selection() is true,
169 * then this function can return the list of known driver names.
171 * If the return value of requires_driver_selection() is false,
172 * then this function should not be called. If it is called
173 * its return value is an empty vector of strings.
175 virtual std::vector<std::string> enumerate_drivers() const { return std::vector<std::string>(); }
177 /** Returns zero if the backend can successfully use @param name as the
178 * driver, non-zero otherwise.
180 * Should not be used unless the backend returns true from
181 * requires_driver_selection()
183 virtual int set_driver (const std::string& /*drivername*/) { return 0; }
185 /** used to list device names along with whether or not they are currently
188 struct DeviceStatus {
192 DeviceStatus (const std::string& s, bool avail) : name (s), available (avail) {}
195 /** An optional alternate interface for backends to provide a facility to
196 * select separate input and output devices.
198 * If a backend returns true then enumerate_input_devices() and
199 * enumerate_output_devices() will be used instead of enumerate_devices()
200 * to enumerate devices. Similarly set_input/output_device_name() should
201 * be used to set devices instead of set_device_name().
203 virtual bool use_separate_input_and_output_devices () const { return false; }
205 /* Return true if the backend uses separate I/O devices only for the case
206 * of allowing one to be "None".
208 * ie. Input Device must match Output Device, except if either of them
209 * is get_standard_device_name (DeviceNone).
211 virtual bool match_input_output_devices_or_none () const { return false; }
213 /** Returns a collection of DeviceStatuses identifying devices discovered
214 * by this backend since the start of the process.
216 * Any of the names in each DeviceStatus may be used to identify a
217 * device in other calls to the backend, though any of them may become
218 * invalid at any time.
220 virtual std::vector<DeviceStatus> enumerate_devices () const = 0;
222 /** Returns a collection of DeviceStatuses identifying input devices
223 * discovered by this backend since the start of the process.
225 * Any of the names in each DeviceStatus may be used to identify a
226 * device in other calls to the backend, though any of them may become
227 * invalid at any time.
229 virtual std::vector<DeviceStatus> enumerate_input_devices () const
230 { return std::vector<DeviceStatus>(); }
232 /** Returns a collection of DeviceStatuses identifying output devices
233 * discovered by this backend since the start of the process.
235 * Any of the names in each DeviceStatus may be used to identify a
236 * device in other calls to the backend, though any of them may become
237 * invalid at any time.
239 virtual std::vector<DeviceStatus> enumerate_output_devices () const
240 { return std::vector<DeviceStatus>(); }
243 /** An interface to set buffers/period for playback latency.
244 * useful for ALSA or JACK/ALSA on Linux.
246 * @return true if the backend supports period-size configuration
248 virtual bool can_set_period_size () const { return false; }
250 /** Returns a vector of supported period-sizes for the given driver */
251 virtual std::vector<uint32_t> available_period_sizes (const std::string& driver) const { return std::vector<uint32_t>(); }
253 /** Set the period size to be used.
254 * must be called before starting the backend.
256 virtual int set_peridod_size (uint32_t) { return -1; }
259 * @return true if backend supports requesting an update to the device list
260 * and any cached properties associated with the devices.
262 virtual bool can_request_update_devices () { return false; }
265 * Request an update to the list of devices returned in the enumerations.
266 * The Backend must return true from can_request_update_devices to support
268 * @return true if the devices were updated
270 virtual bool update_devices () { return false; }
273 * @return true if backend supports a blocking or buffered mode, false by
274 * default unless implemented by a derived class.
276 virtual bool can_use_buffered_io () { return false; }
279 * Set the backend to use a blocking or buffered I/O mode
281 virtual void set_use_buffered_io (bool) { }
284 * @return Set the backend to use a blocking or buffered I/O mode, false by
285 * default unless implemented by a derived class.
287 virtual bool get_use_buffered_io () { return false; }
289 /** Returns a collection of float identifying sample rates that are
290 * potentially usable with the hardware identified by @param device.
291 * Any of these values may be supplied in other calls to this backend
292 * as the desired sample rate to use with the name device, but the
293 * requested sample rate may turn out to be unavailable, or become invalid
296 virtual std::vector<float> available_sample_rates (const std::string& device) const = 0;
298 /* backends that support separate input and output devices should
299 * implement this function and return an intersection (not union) of available
300 * sample rates valid for the given input + output device combination.
302 virtual std::vector<float> available_sample_rates2 (const std::string& input_device, const std::string& output_device) const {
303 std::vector<float> input_sizes = available_sample_rates (input_device);
304 std::vector<float> output_sizes = available_sample_rates (output_device);
305 std::vector<float> rv;
306 std::set_union (input_sizes.begin (), input_sizes.end (),
307 output_sizes.begin (), output_sizes.end (),
308 std::back_inserter (rv));
312 /* Returns the default sample rate that will be shown to the user when
313 * configuration options are first presented. If the derived class
314 * needs or wants to override this, it can. It also MUST override this
315 * if there is any chance that an SR of 44.1kHz is not in the list
316 * returned by available_sample_rates()
318 virtual float default_sample_rate () const {
322 /** Returns a collection of uint32 identifying buffer sizes that are
323 * potentially usable with the hardware identified by @param device.
324 * Any of these values may be supplied in other calls to this backend
325 * as the desired buffer size to use with the name device, but the
326 * requested buffer size may turn out to be unavailable, or become invalid
329 virtual std::vector<uint32_t> available_buffer_sizes (const std::string& device) const = 0;
331 /* backends that support separate input and output devices should
332 * implement this function and return an intersection (not union) of available
333 * buffer sizes valid for the given input + output device combination.
335 virtual std::vector<uint32_t> available_buffer_sizes2 (const std::string& input_device, const std::string& output_device) const {
336 std::vector<uint32_t> input_rates = available_buffer_sizes (input_device);
337 std::vector<uint32_t> output_rates = available_buffer_sizes (output_device);
338 std::vector<uint32_t> rv;
339 std::set_union (input_rates.begin (), input_rates.end (),
340 output_rates.begin (), output_rates.end (),
341 std::back_inserter (rv));
344 /* Returns the default buffer size that will be shown to the user when
345 * configuration options are first presented. If the derived class
346 * needs or wants to override this, it can. It also MUST override this
347 * if there is any chance that a buffer size of 1024 is not in the list
348 * returned by available_buffer_sizes()
350 virtual uint32_t default_buffer_size (const std::string& device) const {
354 /** Returns the maximum number of input channels that are potentially
355 * usable with the hardware identified by @param device. Any number from 1
356 * to the value returned may be supplied in other calls to this backend as
357 * the input channel count to use with the name device, but the requested
358 * count may turn out to be unavailable, or become invalid at any time.
360 virtual uint32_t available_input_channel_count (const std::string& device) const = 0;
362 /** Returns the maximum number of output channels that are potentially
363 * usable with the hardware identified by @param device. Any number from 1
364 * to the value returned may be supplied in other calls to this backend as
365 * the output channel count to use with the name device, but the requested
366 * count may turn out to be unavailable, or become invalid at any time.
368 virtual uint32_t available_output_channel_count (const std::string& device) const = 0;
370 /* Return true if the derived class can change the sample rate of the
371 * device in use while the device is already being used. Return false
372 * otherwise. (example: JACK cannot do this as of September 2013)
374 virtual bool can_change_sample_rate_when_running () const = 0;
375 /* Return true if the derived class can change the buffer size of the
376 * device in use while the device is already being used. Return false
379 virtual bool can_change_buffer_size_when_running () const = 0;
381 /** return true if the backend can measure and update
382 * systemic latencies without restart.
384 virtual bool can_change_systemic_latency_when_running () const { return false; }
386 /* Set the hardware parameters.
388 * If called when the current state is stopped or paused,
389 * the changes will not take effect until the state changes to running.
391 * If called while running, the state will change as fast as the
392 * implementation allows.
394 * All set_*() methods return zero on success, non-zero otherwise.
397 /** Set the name of the device to be used
399 virtual int set_device_name (const std::string&) = 0;
401 /** Set the name of the input device to be used if using separate
402 * input/output devices.
404 * @see use_separate_input_and_output_devices()
406 virtual int set_input_device_name (const std::string&) { return 0;}
408 /** Set the name of the output device to be used if using separate
409 * input/output devices.
411 * @see use_separate_input_and_output_devices()
413 virtual int set_output_device_name (const std::string&) { return 0;}
415 /** Deinitialize and destroy current device
417 virtual int drop_device() {return 0;};
418 /** Set the sample rate to be used
420 virtual int set_sample_rate (float) = 0;
421 /** Set the buffer size to be used.
423 * The device is assumed to use a double buffering scheme, so that one
424 * buffer's worth of data can be processed by hardware while software works
425 * on the other buffer. All known suitable audio APIs support this model
426 * (though ALSA allows for alternate numbers of buffers, and CoreAudio
427 * doesn't directly expose the concept).
429 virtual int set_buffer_size (uint32_t) = 0;
430 /** Set the preferred underlying hardware data layout.
431 * If @param yn is true, then the hardware will interleave
432 * samples for successive channels; otherwise, the hardware will store
433 * samples for a single channel contiguously.
435 * Setting this does not change the fact that all data streams
436 * to and from Ports are mono (essentially, non-interleaved)
438 virtual int set_interleaved (bool yn) = 0;
439 /** Set the number of input channels that should be used
441 virtual int set_input_channels (uint32_t) = 0;
442 /** Set the number of output channels that should be used
444 virtual int set_output_channels (uint32_t) = 0;
445 /** Set the (additional) input latency that cannot be determined via
446 * the implementation's underlying code (e.g. latency from
447 * external D-A/D-A converters. Units are samples.
449 virtual int set_systemic_input_latency (uint32_t) = 0;
450 /** Set the (additional) output latency that cannot be determined via
451 * the implementation's underlying code (e.g. latency from
452 * external D-A/D-A converters. Units are samples.
454 virtual int set_systemic_output_latency (uint32_t) = 0;
455 /** Set the (additional) input latency for a specific midi device,
456 * or if the identifier is empty, apply to all midi devices.
458 virtual int set_systemic_midi_input_latency (std::string const, uint32_t) = 0;
459 /** Set the (additional) output latency for a specific midi device,
460 * or if the identifier is empty, apply to all midi devices.
462 virtual int set_systemic_midi_output_latency (std::string const, uint32_t) = 0;
464 /* Retrieving parameters */
466 virtual std::string device_name () const = 0;
467 virtual std::string input_device_name () const { return std::string(); }
468 virtual std::string output_device_name () const { return std::string(); }
469 virtual float sample_rate () const = 0;
470 virtual uint32_t buffer_size () const = 0;
471 virtual bool interleaved () const = 0;
472 virtual uint32_t input_channels () const = 0;
473 virtual uint32_t output_channels () const = 0;
474 virtual uint32_t systemic_input_latency () const = 0;
475 virtual uint32_t systemic_output_latency () const = 0;
476 virtual uint32_t systemic_midi_input_latency (std::string const) const = 0;
477 virtual uint32_t systemic_midi_output_latency (std::string const) const = 0;
478 virtual uint32_t period_size () const { return 0; }
480 /** override this if this implementation returns true from
481 * requires_driver_selection()
483 virtual std::string driver_name() const { return std::string(); }
485 /** Return the name of a control application for the
486 * selected/in-use device. If no such application exists,
487 * or if no device has been selected or is in-use,
488 * return an empty string.
490 virtual std::string control_app_name() const = 0;
491 /** Launch the control app for the currently in-use or
492 * selected device. May do nothing if the control
493 * app is undefined or cannot be launched.
495 virtual void launch_control_app () = 0;
497 /* @return a vector of strings that describe the available
500 * These can be presented to the user to decide which
501 * MIDI drivers, options etc. can be used. The returned strings
502 * should be thought of as the key to a map of possible
503 * approaches to handling MIDI within the backend. Ensure that
504 * the strings will make sense to the user.
506 virtual std::vector<std::string> enumerate_midi_options () const = 0;
508 /* Request the use of the MIDI option named @param option, which
509 * should be one of the strings returned by enumerate_midi_options()
511 * @return zero if successful, non-zero otherwise
513 virtual int set_midi_option (const std::string& option) = 0;
515 virtual std::string midi_option () const = 0;
517 /** Detailed MIDI device list - if available */
518 virtual std::vector<DeviceStatus> enumerate_midi_devices () const = 0;
520 /** mark a midi-devices as enabled */
521 virtual int set_midi_device_enabled (std::string const, bool) = 0;
523 /** query if a midi-device is enabled */
524 virtual bool midi_device_enabled (std::string const) const = 0;
526 /** if backend supports systemic_midi_[in|ou]tput_latency() */
527 virtual bool can_set_systemic_midi_latencies () const = 0;
531 /** Start using the device named in the most recent call
532 * to set_device(), with the parameters set by various
533 * the most recent calls to set_sample_rate() etc. etc.
535 * At some undetermined time after this function is successfully called,
536 * the backend will start calling the ::process_callback() method of
537 * the AudioEngine referenced by @param engine. These calls will
538 * occur in a thread created by and/or under the control of the backend.
540 * @param for_latency_measurement if true, the device is being started
541 * to carry out latency measurements and the backend should this
542 * take care to return latency numbers that do not reflect
543 * any existing systemic latency settings.
545 * Return zero if successful, negative values otherwise.
550 * Why is this non-virtual but ::_start() is virtual ?
551 * Virtual methods with default parameters create possible ambiguity
552 * because a derived class may implement the same method with a different
553 * type or value of default parameter.
555 * So we make this non-virtual method to avoid possible overrides of
556 * default parameters. See Scott Meyers or other books on C++ to understand
557 * this pattern, or possibly just this:
559 * http://stackoverflow.com/questions/12139786/good-pratice-default-arguments-for-pure-virtual-method
561 int start (bool for_latency_measurement=false) {
562 return _start (for_latency_measurement);
565 /** Stop using the device currently in use.
567 * If the function is successfully called, no subsequent calls to the
568 * process_callback() of @param engine will be made after the function
569 * returns, until parameters are reset and start() are called again.
571 * The backend is considered to be un-configured after a successful
572 * return, and requires calls to set hardware parameters before it can be
573 * start()-ed again. See pause() for a way to avoid this. stop() should
574 * only be used when reconfiguration is required OR when there are no
575 * plans to use the backend in the future with a reconfiguration.
577 * Return zero if successful, 1 if the device is not in use, negative values on error
579 virtual int stop () = 0;
583 * Return zero if successful, negative values on error
585 virtual int reset_device() = 0;
587 /** While remaining connected to the device, and without changing its
588 * configuration, start (or stop) calling the process_callback() of @param engine
589 * without waiting for the device. Once process_callback() has returned, it
590 * will be called again immediately, thus allowing for faster-than-realtime
593 * All registered ports remain in existence and all connections remain
594 * unaltered. However, any physical ports should NOT be used by the
595 * process_callback() during freewheeling - the data behaviour is undefined.
597 * If @param start_stop is true, begin this behaviour; otherwise cease this
598 * behaviour if it currently occuring, and return to calling
599 * process_callback() of @param engine by waiting for the device.
601 * Return zero on success, non-zero otherwise.
603 virtual int freewheel (bool start_stop) = 0;
605 /** return the fraction of the time represented by the current buffer
606 * size that is being used for each buffer process cycle, as a value
609 * E.g. if the buffer size represents 5msec and current processing
610 * takes 1msec, the returned value should be 0.2.
612 * Implementations can feel free to smooth the values returned over
613 * time (e.g. high pass filtering, or its equivalent).
615 virtual float dsp_load() const = 0;
617 /* Transport Control (JACK is the only audio API that currently offers
618 the concept of shared transport control)
621 /** Attempt to change the transport state to TransportRolling.
623 virtual void transport_start () {}
624 /** Attempt to change the transport state to TransportStopped.
626 virtual void transport_stop () {}
627 /** return the current transport state
629 virtual TransportState transport_state () const { return TransportStopped; }
630 /** Attempt to locate the transport to @param pos
632 virtual void transport_locate (samplepos_t /*pos*/) {}
633 /** Return the current transport location, in samples measured
634 * from the origin (defined by the transport time master)
636 virtual samplepos_t transport_sample() const { return 0; }
638 /** If @param yn is true, become the time master for any inter-application transport
639 * timebase, otherwise cease to be the time master for the same.
641 * Return zero on success, non-zero otherwise
643 * JACK is the only currently known audio API with the concept of a shared
644 * transport timebase.
646 virtual int set_time_master (bool /*yn*/) { return 0; }
648 virtual int usecs_per_cycle () const { return 1000000 * (buffer_size() / sample_rate()); }
649 virtual size_t raw_buffer_size (DataType t) = 0;
653 /** return the time according to the sample clock in use, measured in
654 * samples since an arbitrary zero time in the past. The value should
655 * increase monotonically and linearly, without interruption from any
656 * source (including CPU frequency scaling).
658 * It is extremely likely that any implementation will use a DLL, since
659 * this function can be called from any thread, at any time, and must be
660 * able to accurately determine the correct sample time.
662 * Can be called from any thread.
664 virtual samplepos_t sample_time () = 0;
666 /** Return the time according to the sample clock in use when the most
667 * recent buffer process cycle began. Can be called from any thread.
669 virtual samplepos_t sample_time_at_cycle_start () = 0;
671 /** Return the time since the current buffer process cycle started,
672 * in samples, according to the sample clock in use.
674 * Can ONLY be called from within a process() callback tree (which
675 * implies that it can only be called by a process thread)
677 virtual pframes_t samples_since_cycle_start () = 0;
679 /** Return true if it possible to determine the offset in samples of the
680 * first video frame that starts within the current buffer process cycle,
681 * measured from the first sample of the cycle. If returning true,
682 * set @param offset to that offset.
684 * Eg. if it can be determined that the first video frame within the cycle
685 * starts 28 samples after the first sample of the cycle, then this method
686 * should return true and set @param offset to 28.
688 * May be impossible to support outside of JACK, which has specific support
689 * (in some cases, hardware support) for this feature.
691 * Can ONLY be called from within a process() callback tree (which implies
692 * that it can only be called by a process thread)
694 virtual bool get_sync_offset (pframes_t& /*offset*/) const { return false; }
696 /** Create a new thread suitable for running part of the buffer process
697 * cycle (i.e. Realtime scheduling, memory allocation, etc. etc are all
698 * correctly setup), with a stack size given in bytes by specified @param
699 * stacksize. The thread will begin executing @param func, and will exit
700 * when that function returns.
702 virtual int create_process_thread (boost::function<void()> func) = 0;
704 /** Wait for all processing threads to exit.
706 * Return zero on success, non-zero on failure.
708 virtual int join_process_threads () = 0;
710 /** Return true if execution context is in a backend thread
712 virtual bool in_process_thread () = 0;
714 /** Return the minimum stack size of audio threads in bytes
716 static size_t thread_stack_size () { return 100000; }
718 /** Return number of processing threads
720 virtual uint32_t process_thread_count () = 0;
722 virtual void update_latencies () = 0;
724 /** Set @param speed and @param position to the current speed and position
725 * indicated by some transport sync signal. Return whether the current
726 * transport state is pending, or finalized.
728 * Derived classes only need implement this if they provide some way to
729 * sync to a transport sync signal (e.g. Sony 9 Pin) that is not
730 * handled by Ardour itself (LTC and MTC are both handled by Ardour).
731 * The canonical example is JACK Transport.
733 virtual bool speed_and_position (double& speed, samplepos_t& position) {
740 AudioBackendInfo& _info;
743 virtual int _start (bool for_latency_measurement) = 0;
748 #endif /* __libardour_audiobackend_h__ */