X-Git-Url: https://main.carlh.net/gitweb/?a=blobdiff_plain;f=libs%2Fardour%2Fardour%2Faudio_backend.h;h=73310bddb63ea1cae25e5b26e4a08b7b60413bdd;hb=4dc63966f0872efe768dad61eb9b8785d06b92d1;hp=6c4a54da3e2a6c84d420fc60e127debafba17a21;hpb=4a6412aebe4f18578f201e99ddc74fc5d9cb6bfc;p=ardour.git diff --git a/libs/ardour/ardour/audio_backend.h b/libs/ardour/ardour/audio_backend.h index 6c4a54da3e..73310bddb6 100644 --- a/libs/ardour/ardour/audio_backend.h +++ b/libs/ardour/ardour/audio_backend.h @@ -28,20 +28,115 @@ #include +#include "ardour/libardour_visibility.h" #include "ardour/types.h" +#include "ardour/audioengine.h" +#include "ardour/port_engine.h" + +#ifdef ARDOURBACKEND_DLL_EXPORTS // defined if we are building the ARDOUR Panners DLLs (instead of using them) + #define ARDOURBACKEND_API LIBARDOUR_DLL_EXPORT +#else + #define ARDOURBACKEND_API LIBARDOUR_DLL_IMPORT +#endif +#define ARDOURBACKEND_LOCAL LIBARDOUR_DLL_LOCAL namespace ARDOUR { -class AudioEngine; -class PortEngine; -class PortManager; +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 (*factory) (AudioEngine&); -class AudioBackend { + /** 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)(); +}; + +class LIBARDOUR_API AudioBackend : public PortEngine { public: - AudioBackend (AudioEngine& 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 @@ -49,17 +144,6 @@ class AudioBackend { */ virtual std::string name() const = 0; - /** Return a private, type-free pointer to any data - * that might be useful to a concrete implementation - */ - virtual void* private_handle() const = 0; - - /** Return true if the underlying mechanism/API is still available - * for us to utilize. return false if some or all of the AudioBackend - * API can no longer be effectively used. - */ - virtual bool connected() const = 0; - /** Return true if the callback from the underlying mechanism/API * (CoreAudio, JACK, ASIO etc.) occurs in a thread subject to realtime * constraints. Return false otherwise. @@ -72,7 +156,7 @@ class AudioBackend { * 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. */ @@ -96,7 +180,7 @@ class AudioBackend { 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; @@ -105,6 +189,16 @@ class AudioBackend { 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; } + /** Returns a collection of DeviceStatuses identifying devices discovered * by this backend since the start of the process. * @@ -114,6 +208,40 @@ class AudioBackend { */ virtual std::vector 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 enumerate_input_devices () const + { return std::vector(); } + + /** 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 enumerate_output_devices () const + { return std::vector(); } + + /** + * @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; } + /** 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 @@ -122,6 +250,31 @@ class AudioBackend { * at any time. */ virtual std::vector 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 available_sample_rates2 (const std::string& input_device, const std::string& output_device) const { + std::vector input_sizes = available_sample_rates (input_device); + std::vector output_sizes = available_sample_rates (output_device); + std::vector 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 @@ -131,6 +284,29 @@ class AudioBackend { */ virtual std::vector 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 available_buffer_sizes2 (const std::string& input_device, const std::string& output_device) const { + std::vector input_rates = available_buffer_sizes (input_device); + std::vector output_rates = available_buffer_sizes (output_device); + std::vector 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 @@ -154,12 +330,12 @@ class AudioBackend { 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; /* 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. * @@ -172,6 +348,24 @@ class AudioBackend { /** 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; @@ -184,17 +378,11 @@ class AudioBackend { * 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) */ @@ -205,30 +393,46 @@ class AudioBackend { /** 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; - /** Return the name of a control application for the + /** 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 * selected/in-use device. If no such application exists, * or if no device has been selected or is in-use, * return an empty string. @@ -239,50 +443,96 @@ class AudioBackend { * 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 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 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 @@ -307,21 +557,21 @@ class AudioBackend { * 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 @@ -339,7 +589,7 @@ class AudioBackend { * 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. */ @@ -347,30 +597,30 @@ class AudioBackend { 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) */ @@ -399,40 +649,51 @@ class AudioBackend { * stacksize. The thread will begin executing @param func, and will exit * when that function returns. */ - virtual int create_process_thread (boost::function func, AudioBackendNativeThread*, size_t stacksize) = 0; + virtual int create_process_thread (boost::function 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; + virtual int join_process_threads () = 0; - protected: - AudioEngine& engine; -}; + /** Return true if execution context is in a backend thread + */ + virtual bool in_process_thread () = 0; -struct AudioBackendInfo { - const char* name; + /** Return the minimum stack size of audio threads in bytes + */ + static size_t thread_stack_size () { return 100000; } - int (*instantiate) (const std::string& arg1, const std::string& arg2); - int (*deinstantiate) (void); + /** Return number of processing threads + */ + virtual uint32_t process_thread_count () = 0; - boost::shared_ptr (*backend_factory) (AudioEngine&); - boost::shared_ptr (*portengine_factory) (PortManager&); + virtual void update_latencies () = 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. + /** 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__ */ - +