#include <boost/function.hpp>
+#include "ardour/libardour_visibility.h"
#include "ardour/types.h"
#include "ardour/audioengine.h"
#include "ardour/port_engine.h"
-#include "ardour/visibility.h"
#ifdef ARDOURBACKEND_DLL_EXPORTS // defined if we are building the ARDOUR Panners DLLs (instead of using them)
- #define ARDOURBACKEND_API LIBARDOUR_HELPER_DLL_EXPORT
+ #define ARDOURBACKEND_API LIBARDOUR_DLL_EXPORT
#else
- #define ARDOURBACKEND_API LIBARDOUR_HELPER_DLL_IMPORT
-#endif
-#define ARDOURBACKEND_LOCAL LIBARDOUR_HELPER_DLL_LOCAL
+ #define ARDOURBACKEND_API LIBARDOUR_DLL_IMPORT
+#endif
+#define ARDOURBACKEND_LOCAL LIBARDOUR_DLL_LOCAL
namespace ARDOUR {
-class AudioBackend : public PortEngine {
+struct LIBARDOUR_API AudioBackendInfo {
+ const char* name;
+
+ /** Using arg1 and arg2, initialize this audiobackend.
+ *
+ * Returns zero on success, non-zero otherwise.
+ */
+ int (*instantiate) (const std::string& arg1, const std::string& arg2);
+
+ /** Release all resources associated with this audiobackend
+ */
+ int (*deinstantiate) (void);
+
+ /** Factory method to create an AudioBackend-derived class.
+ *
+ * Returns a valid shared_ptr to the object if successfull,
+ * or a "null" shared_ptr otherwise.
+ */
+ boost::shared_ptr<AudioBackend> (*factory) (AudioEngine&);
+
+ /** Return true if the underlying mechanism/API has been
+ * configured and does not need (re)configuration in order
+ * to be usable. Return false otherwise.
+ *
+ * Note that this may return true if (re)configuration, even though
+ * not currently required, is still possible.
+ */
+ bool (*already_configured)();
+
+ /** Return true if the underlying mechanism/API can be
+ * used on the given system.
+ *
+ * If this function returns false, the backend is not
+ * listed in the engine dialog.
+ */
+ bool (*available)();
+};
+
+/** AudioBackend is an high-level abstraction for interacting with the operating system's
+ * audio and midi I/O.
+ */
+class LIBARDOUR_API AudioBackend : public PortEngine {
public:
- AudioBackend (AudioEngine& e) : PortEngine (e), engine (e) {}
+ AudioBackend (AudioEngine& e, AudioBackendInfo& i) : PortEngine (e), _info (i), engine (e) {}
virtual ~AudioBackend () {}
+ enum ErrorCode {
+ NoError = 0,
+ BackendInitializationError = -64,
+ BackendDeinitializationError,
+ BackendReinitializationError,
+ AudioDeviceOpenError,
+ AudioDeviceCloseError,
+ AudioDeviceInvalidError,
+ AudioDeviceNotAvailableError,
+ AudioDeviceNotConnectedError,
+ AudioDeviceReservationError,
+ AudioDeviceIOError,
+ MidiDeviceOpenError,
+ MidiDeviceCloseError,
+ MidiDeviceNotAvailableError,
+ MidiDeviceNotConnectedError,
+ MidiDeviceIOError,
+ SampleFormatNotSupportedError,
+ SampleRateNotSupportedError,
+ RequestedInputLatencyNotSupportedError,
+ RequestedOutputLatencyNotSupportedError,
+ PeriodSizeNotSupportedError,
+ PeriodCountNotSupportedError,
+ DeviceConfigurationNotSupportedError,
+ ChannelCountNotSupportedError,
+ InputChannelCountNotSupportedError,
+ OutputChannelCountNotSupportedError,
+ AquireRealtimePermissionError,
+ SettingAudioThreadPriorityError,
+ SettingMIDIThreadPriorityError,
+ ProcessThreadStartError,
+ FreewheelThreadStartError,
+ PortRegistrationError,
+ PortReconnectError,
+ OutOfMemoryError,
+ };
+
+ static std::string get_error_string (ErrorCode);
+
+ enum StandardDeviceName {
+ DeviceNone,
+ DeviceDefault
+ };
+
+ static std::string get_standard_device_name (StandardDeviceName);
+
+ /** Return the AudioBackendInfo object from which this backend
+ was constructed.
+ */
+ AudioBackendInfo& info() const { return _info; }
+
/** Return the name of this backend.
*
* Should use a well-known, unique term. Expected examples
* before any device can be selected. Return false otherwise.
*
* Intended mainly to differentiate between meta-APIs like JACK
- * which can still expose different backends (such as ALSA or CoreAudio
+ * which can still expose different backends (such as ALSA or CoreAudio
* or FFADO or netjack) and those like ASIO or CoreAudio which
* do not.
*/
virtual int set_driver (const std::string& /*drivername*/) { return 0; }
/** used to list device names along with whether or not they are currently
- * available.
+ * available.
*/
struct DeviceStatus {
std::string name;
DeviceStatus (const std::string& s, bool avail) : name (s), available (avail) {}
};
+ /** An optional alternate interface for backends to provide a facility to
+ * select separate input and output devices.
+ *
+ * If a backend returns true then enumerate_input_devices() and
+ * enumerate_output_devices() will be used instead of enumerate_devices()
+ * to enumerate devices. Similarly set_input/output_device_name() should
+ * be used to set devices instead of set_device_name().
+ */
+ virtual bool use_separate_input_and_output_devices () const { return false; }
+
+ /* Return true if the backend uses separate I/O devices only for the case
+ * of allowing one to be "None".
+ *
+ * ie. Input Device must match Output Device, except if either of them
+ * is get_standard_device_name (DeviceNone).
+ */
+ virtual bool match_input_output_devices_or_none () const { return false; }
+
/** Returns a collection of DeviceStatuses identifying devices discovered
* by this backend since the start of the process.
*
*/
virtual std::vector<DeviceStatus> enumerate_devices () const = 0;
+ /** Returns a collection of DeviceStatuses identifying input devices
+ * discovered by this backend since the start of the process.
+ *
+ * Any of the names in each DeviceStatus may be used to identify a
+ * device in other calls to the backend, though any of them may become
+ * invalid at any time.
+ */
+ virtual std::vector<DeviceStatus> enumerate_input_devices () const
+ { return std::vector<DeviceStatus>(); }
+
+ /** Returns a collection of DeviceStatuses identifying output devices
+ * discovered by this backend since the start of the process.
+ *
+ * Any of the names in each DeviceStatus may be used to identify a
+ * device in other calls to the backend, though any of them may become
+ * invalid at any time.
+ */
+ virtual std::vector<DeviceStatus> enumerate_output_devices () const
+ { return std::vector<DeviceStatus>(); }
+
+
+ /** An interface to set buffers/period for playback latency.
+ * useful for ALSA or JACK/ALSA on Linux.
+ *
+ * @return true if the backend supports period-size configuration
+ */
+ virtual bool can_set_period_size () const { return false; }
+
+ /** Returns a vector of supported period-sizes for the given driver */
+ virtual std::vector<uint32_t> available_period_sizes (const std::string& driver) const { return std::vector<uint32_t>(); }
+
+ /** Set the period size to be used.
+ * must be called before starting the backend.
+ */
+ virtual int set_peridod_size (uint32_t) { return -1; }
+
+ /**
+ * @return true if backend supports requesting an update to the device list
+ * and any cached properties associated with the devices.
+ */
+ virtual bool can_request_update_devices () { return false; }
+
+ /**
+ * Request an update to the list of devices returned in the enumerations.
+ * The Backend must return true from can_request_update_devices to support
+ * this interface.
+ * @return true if the devices were updated
+ */
+ virtual bool update_devices () { return false; }
+
+ /**
+ * @return true if backend supports a blocking or buffered mode, false by
+ * default unless implemented by a derived class.
+ */
+ virtual bool can_use_buffered_io () { return false; }
+
+ /**
+ * Set the backend to use a blocking or buffered I/O mode
+ */
+ virtual void set_use_buffered_io (bool) { }
+
+ /**
+ * @return Set the backend to use a blocking or buffered I/O mode, false by
+ * default unless implemented by a derived class.
+ */
+ virtual bool get_use_buffered_io () { return false; }
+
/** Returns a collection of float identifying sample rates that are
* potentially usable with the hardware identified by @param device.
* Any of these values may be supplied in other calls to this backend
* at any time.
*/
virtual std::vector<float> available_sample_rates (const std::string& device) const = 0;
+
+ /* backends that support separate input and output devices should
+ * implement this function and return an intersection (not union) of available
+ * sample rates valid for the given input + output device combination.
+ */
+ virtual std::vector<float> available_sample_rates2 (const std::string& input_device, const std::string& output_device) const {
+ std::vector<float> input_sizes = available_sample_rates (input_device);
+ std::vector<float> output_sizes = available_sample_rates (output_device);
+ std::vector<float> rv;
+ std::set_union (input_sizes.begin (), input_sizes.end (),
+ output_sizes.begin (), output_sizes.end (),
+ std::back_inserter (rv));
+ return rv;
+ }
+
+ /* Returns the default sample rate that will be shown to the user when
+ * configuration options are first presented. If the derived class
+ * needs or wants to override this, it can. It also MUST override this
+ * if there is any chance that an SR of 44.1kHz is not in the list
+ * returned by available_sample_rates()
+ */
+ virtual float default_sample_rate () const {
+ return 44100.0;
+ }
+
/** Returns a collection of uint32 identifying buffer sizes that are
* potentially usable with the hardware identified by @param device.
* Any of these values may be supplied in other calls to this backend
*/
virtual std::vector<uint32_t> available_buffer_sizes (const std::string& device) const = 0;
+ /* backends that support separate input and output devices should
+ * implement this function and return an intersection (not union) of available
+ * buffer sizes valid for the given input + output device combination.
+ */
+ virtual std::vector<uint32_t> available_buffer_sizes2 (const std::string& input_device, const std::string& output_device) const {
+ std::vector<uint32_t> input_rates = available_buffer_sizes (input_device);
+ std::vector<uint32_t> output_rates = available_buffer_sizes (output_device);
+ std::vector<uint32_t> rv;
+ std::set_union (input_rates.begin (), input_rates.end (),
+ output_rates.begin (), output_rates.end (),
+ std::back_inserter (rv));
+ return rv;
+ }
+ /* Returns the default buffer size that will be shown to the user when
+ * configuration options are first presented. If the derived class
+ * needs or wants to override this, it can. It also MUST override this
+ * if there is any chance that a buffer size of 1024 is not in the list
+ * returned by available_buffer_sizes()
+ */
+ virtual uint32_t default_buffer_size (const std::string& device) const {
+ return 1024;
+ }
+
/** Returns the maximum number of input channels that are potentially
* usable with the hardware identified by @param device. Any number from 1
* to the value returned may be supplied in other calls to this backend as
virtual bool can_change_sample_rate_when_running () const = 0;
/* Return true if the derived class can change the buffer size of the
* device in use while the device is already being used. Return false
- * otherwise.
+ * otherwise.
*/
virtual bool can_change_buffer_size_when_running () const = 0;
+ /** return true if the backend can measure and update
+ * systemic latencies without restart.
+ */
+ virtual bool can_change_systemic_latency_when_running () const { return false; }
+
/* Set the hardware parameters.
- *
+ *
* If called when the current state is stopped or paused,
* the changes will not take effect until the state changes to running.
*
/** Set the name of the device to be used
*/
virtual int set_device_name (const std::string&) = 0;
+
+ /** Set the name of the input device to be used if using separate
+ * input/output devices.
+ *
+ * @see use_separate_input_and_output_devices()
+ */
+ virtual int set_input_device_name (const std::string&) { return 0;}
+
+ /** Set the name of the output device to be used if using separate
+ * input/output devices.
+ *
+ * @see use_separate_input_and_output_devices()
+ */
+ virtual int set_output_device_name (const std::string&) { return 0;}
+
+ /** Deinitialize and destroy current device
+ */
+ virtual int drop_device() {return 0;};
/** Set the sample rate to be used
*/
virtual int set_sample_rate (float) = 0;
* doesn't directly expose the concept).
*/
virtual int set_buffer_size (uint32_t) = 0;
- /** Set the preferred underlying hardware sample format
- *
- * This does not change the sample format (32 bit float) read and
- * written to the device via the Port API.
- */
- virtual int set_sample_format (SampleFormat) = 0;
/** Set the preferred underlying hardware data layout.
* If @param yn is true, then the hardware will interleave
* samples for successive channels; otherwise, the hardware will store
* samples for a single channel contiguously.
- *
+ *
* Setting this does not change the fact that all data streams
* to and from Ports are mono (essentially, non-interleaved)
*/
/** Set the number of output channels that should be used
*/
virtual int set_output_channels (uint32_t) = 0;
- /** Set the (additional) input latency that cannot be determined via
+ /** Set the (additional) input latency that cannot be determined via
* the implementation's underlying code (e.g. latency from
* external D-A/D-A converters. Units are samples.
*/
virtual int set_systemic_input_latency (uint32_t) = 0;
- /** Set the (additional) output latency that cannot be determined via
+ /** Set the (additional) output latency that cannot be determined via
* the implementation's underlying code (e.g. latency from
* external D-A/D-A converters. Units are samples.
*/
virtual int set_systemic_output_latency (uint32_t) = 0;
+ /** Set the (additional) input latency for a specific midi device,
+ * or if the identifier is empty, apply to all midi devices.
+ */
+ virtual int set_systemic_midi_input_latency (std::string const, uint32_t) = 0;
+ /** Set the (additional) output latency for a specific midi device,
+ * or if the identifier is empty, apply to all midi devices.
+ */
+ virtual int set_systemic_midi_output_latency (std::string const, uint32_t) = 0;
/* Retrieving parameters */
virtual std::string device_name () const = 0;
+ virtual std::string input_device_name () const { return std::string(); }
+ virtual std::string output_device_name () const { return std::string(); }
virtual float sample_rate () const = 0;
virtual uint32_t buffer_size () const = 0;
- virtual SampleFormat sample_format () const = 0;
virtual bool interleaved () const = 0;
virtual uint32_t input_channels () const = 0;
virtual uint32_t output_channels () const = 0;
virtual uint32_t systemic_input_latency () const = 0;
virtual uint32_t systemic_output_latency () const = 0;
+ virtual uint32_t systemic_midi_input_latency (std::string const) const = 0;
+ virtual uint32_t systemic_midi_output_latency (std::string const) const = 0;
+ virtual uint32_t period_size () const { return 0; }
/** override this if this implementation returns true from
* requires_driver_selection()
*/
virtual std::string driver_name() const { return std::string(); }
- /** Return the name of a control application for the
+ /** Return the name of a control application for the
* selected/in-use device. If no such application exists,
* or if no device has been selected or is in-use,
* return an empty string.
* app is undefined or cannot be launched.
*/
virtual void launch_control_app () = 0;
- /* Basic state control */
+
+ /* @return a vector of strings that describe the available
+ * MIDI options.
+ *
+ * These can be presented to the user to decide which
+ * MIDI drivers, options etc. can be used. The returned strings
+ * should be thought of as the key to a map of possible
+ * approaches to handling MIDI within the backend. Ensure that
+ * the strings will make sense to the user.
+ */
+ virtual std::vector<std::string> enumerate_midi_options () const = 0;
+
+ /* Request the use of the MIDI option named @param option, which
+ * should be one of the strings returned by enumerate_midi_options()
+ *
+ * @return zero if successful, non-zero otherwise
+ */
+ virtual int set_midi_option (const std::string& option) = 0;
+
+ virtual std::string midi_option () const = 0;
+
+ /** Detailed MIDI device list - if available */
+ virtual std::vector<DeviceStatus> enumerate_midi_devices () const = 0;
+
+ /** mark a midi-devices as enabled */
+ virtual int set_midi_device_enabled (std::string const, bool) = 0;
+
+ /** query if a midi-device is enabled */
+ virtual bool midi_device_enabled (std::string const) const = 0;
+
+ /** if backend supports systemic_midi_[in|ou]tput_latency() */
+ virtual bool can_set_systemic_midi_latencies () const = 0;
+
+ /* State Control */
/** Start using the device named in the most recent call
* to set_device(), with the parameters set by various
* the most recent calls to set_sample_rate() etc. etc.
- *
+ *
* At some undetermined time after this function is successfully called,
* the backend will start calling the ::process_callback() method of
* the AudioEngine referenced by @param engine. These calls will
* occur in a thread created by and/or under the control of the backend.
*
+ * @param for_latency_measurement if true, the device is being started
+ * to carry out latency measurements and the backend should this
+ * take care to return latency numbers that do not reflect
+ * any existing systemic latency settings.
+ *
* Return zero if successful, negative values otherwise.
+ *
+ *
+ *
+ *
+ * Why is this non-virtual but ::_start() is virtual ?
+ * Virtual methods with default parameters create possible ambiguity
+ * because a derived class may implement the same method with a different
+ * type or value of default parameter.
+ *
+ * So we make this non-virtual method to avoid possible overrides of
+ * default parameters. See Scott Meyers or other books on C++ to understand
+ * this pattern, or possibly just this:
+ *
+ * http://stackoverflow.com/questions/12139786/good-pratice-default-arguments-for-pure-virtual-method
*/
- virtual int start () = 0;
+ int start (bool for_latency_measurement=false) {
+ return _start (for_latency_measurement);
+ }
- /** Stop using the device currently in use.
+ /** Stop using the device currently in use.
*
* If the function is successfully called, no subsequent calls to the
* process_callback() of @param engine will be made after the function
* returns, until parameters are reset and start() are called again.
- *
+ *
* The backend is considered to be un-configured after a successful
* return, and requires calls to set hardware parameters before it can be
* start()-ed again. See pause() for a way to avoid this. stop() should
- * only be used when reconfiguration is required OR when there are no
+ * only be used when reconfiguration is required OR when there are no
* plans to use the backend in the future with a reconfiguration.
*
* Return zero if successful, 1 if the device is not in use, negative values on error
*/
virtual int stop () = 0;
- /** Temporarily cease using the device named in the most recent call to set_parameters().
- *
- * If the function is successfully called, no subsequent calls to the
- * process_callback() of @param engine will be made after the function
- * returns, until start() is called again.
- *
- * The backend will retain its existing parameter configuration after a successful
- * return, and does NOT require any calls to set hardware parameters before it can be
- * start()-ed again.
+ /** Reset device.
*
- * Return zero if successful, 1 if the device is not in use, negative values on error
+ * Return zero if successful, negative values on error
*/
- virtual int pause () = 0;
+ virtual int reset_device() = 0;
/** While remaining connected to the device, and without changing its
* configuration, start (or stop) calling the process_callback() of @param engine
* from 0.0 to 1.0
*
* E.g. if the buffer size represents 5msec and current processing
- * takes 1msec, the returned value should be 0.2.
- *
+ * takes 1msec, the returned value should be 0.2.
+ *
* Implementations can feel free to smooth the values returned over
* time (e.g. high pass filtering, or its equivalent).
*/
- virtual float cpu_load() const = 0;
+ virtual float dsp_load() const = 0;
/* Transport Control (JACK is the only audio API that currently offers
the concept of shared transport control)
*/
-
- /** Attempt to change the transport state to TransportRolling.
+
+ /** Attempt to change the transport state to TransportRolling.
*/
virtual void transport_start () {}
- /** Attempt to change the transport state to TransportStopped.
+ /** Attempt to change the transport state to TransportStopped.
*/
virtual void transport_stop () {}
/** return the current transport state
* timebase, otherwise cease to be the time master for the same.
*
* Return zero on success, non-zero otherwise
- *
+ *
* JACK is the only currently known audio API with the concept of a shared
* transport timebase.
*/
virtual int usecs_per_cycle () const { return 1000000 * (buffer_size() / sample_rate()); }
virtual size_t raw_buffer_size (DataType t) = 0;
-
+
/* Process time */
-
+
/** return the time according to the sample clock in use, measured in
* samples since an arbitrary zero time in the past. The value should
* increase monotonically and linearly, without interruption from any
* source (including CPU frequency scaling).
*
* It is extremely likely that any implementation will use a DLL, since
- * this function can be called from any thread, at any time, and must be
+ * this function can be called from any thread, at any time, and must be
* able to accurately determine the correct sample time.
*
* Can be called from any thread.
*/
- virtual pframes_t sample_time () = 0;
+ virtual framepos_t sample_time () = 0;
/** Return the time according to the sample clock in use when the most
* recent buffer process cycle began. Can be called from any thread.
*/
- virtual pframes_t sample_time_at_cycle_start () = 0;
+ virtual framepos_t sample_time_at_cycle_start () = 0;
/** Return the time since the current buffer process cycle started,
* in samples, according to the sample clock in use.
- *
+ *
* Can ONLY be called from within a process() callback tree (which
* implies that it can only be called by a process thread)
*/
* stacksize. The thread will begin executing @param func, and will exit
* when that function returns.
*/
- virtual int create_process_thread (boost::function<void()> func, AudioBackendNativeThread*, size_t stacksize) = 0;
+ virtual int create_process_thread (boost::function<void()> func) = 0;
- /** Wait for the thread specified by @param thread to exit.
- *
+ /** Wait for all processing threads to exit.
+ *
* Return zero on success, non-zero on failure.
*/
- virtual int wait_for_process_thread_exit (AudioBackendNativeThread thread) = 0;
-
- virtual void update_latencies () = 0;
-
- protected:
- AudioEngine& engine;
-};
-
-struct AudioBackendInfo {
- const char* name;
+ virtual int join_process_threads () = 0;
- /** Using arg1 and arg2, initialize this audiobackend.
- *
- * Returns zero on success, non-zero otherwise.
+ /** Return true if execution context is in a backend thread
*/
- int (*instantiate) (const std::string& arg1, const std::string& arg2);
+ virtual bool in_process_thread () = 0;
- /** Release all resources associated with this audiobackend
+ /** Return the minimum stack size of audio threads in bytes
*/
- int (*deinstantiate) (void);
+ static size_t thread_stack_size () { return 100000; }
- /** Factory method to create an AudioBackend-derived class.
- *
- * Returns a valid shared_ptr to the object if successfull,
- * or a "null" shared_ptr otherwise.
+ /** Return number of processing threads
*/
- boost::shared_ptr<AudioBackend> (*factory) (AudioEngine&);
+ virtual uint32_t process_thread_count () = 0;
- /** Return true if the underlying mechanism/API has been
- * configured and does not need (re)configuration in order
- * to be usable. Return false otherwise.
+ virtual void update_latencies () = 0;
+
+ /** Set @param speed and @param position to the current speed and position
+ * indicated by some transport sync signal. Return whether the current
+ * transport state is pending, or finalized.
*
- * Note that this may return true if (re)configuration, even though
- * not currently required, is still possible.
+ * Derived classes only need implement this if they provide some way to
+ * sync to a transport sync signal (e.g. Sony 9 Pin) that is not
+ * handled by Ardour itself (LTC and MTC are both handled by Ardour).
+ * The canonical example is JACK Transport.
*/
- bool (*already_configured)();
+ virtual bool speed_and_position (double& speed, framepos_t& position) {
+ speed = 0.0;
+ position = 0;
+ return false;
+ }
+
+ protected:
+ AudioBackendInfo& _info;
+ AudioEngine& engine;
+
+ virtual int _start (bool for_latency_measurement) = 0;
};
} // namespace
#endif /* __libardour_audiobackend_h__ */
-
+
projects / ardour.git / blobdiff