audio_backend.h

Go to the documentation of this file.

/*
 * Copyright (C) 2013-2016 Tim Mayberry <mojofunk@gmail.com>
 * Copyright (C) 2013-2017 Paul Davis <paul@linuxaudiosystems.com>
 * Copyright (C) 2014-2016 Robin Gareus <robin@gareus.org>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */
 
#pragma once
 
#include <string>
#include <vector>
 
#include <stdint.h>
#include <stdlib.h>
 
 
#include "ardour/audioengine.h"
#include "ardour/libardour_visibility.h"
#include "ardour/port_engine.h"
#include "ardour/types.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
{
struct LIBARDOUR_API AudioBackendInfo {
        const char* name;
 
        int (*instantiate) (const std::string& arg1, const std::string& arg2);
 
        int (*deinstantiate) (void);
 
        std::shared_ptr<AudioBackend> (*factory) (AudioEngine&);
 
        bool (*already_configured) ();
 
        bool (*available) ();
};
 
class LIBARDOUR_API AudioBackend : public PortEngine
{
public:
        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);
 
        AudioBackendInfo& info () const
        {
                return _info;
        }
 
        virtual std::string name () const = 0;
 
        virtual bool is_realtime () const = 0;
 
        virtual bool is_jack () const { return false; }
 
        virtual int client_real_time_priority () { return 0; }
 
        /* Discovering devices and parameters */
 
        virtual bool requires_driver_selection () const
        {
                return false;
        }
 
        virtual std::vector<std::string> enumerate_drivers () const
        {
                return std::vector<std::string> ();
        }
 
        virtual int set_driver (const std::string& drivername)
        {
                return 0;
        }
 
        struct DeviceStatus {
                std::string name;
                bool        available;
 
                DeviceStatus (const std::string& s, bool avail)
                        : name (s)
                        , available (avail)
                {}
        };
 
        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;
        }
 
        virtual std::vector<DeviceStatus> enumerate_devices () const = 0;
 
        virtual std::vector<DeviceStatus> enumerate_input_devices () const
        {
                return std::vector<DeviceStatus> ();
        }
 
        virtual std::vector<DeviceStatus> enumerate_output_devices () const
        {
                return std::vector<DeviceStatus> ();
        }
 
        virtual bool can_set_period_size () const
        {
                return false;
        }
 
        virtual std::vector<uint32_t> available_period_sizes (const std::string& driver, const std::string& device) const
        {
                return std::vector<uint32_t> ();
        }
 
        virtual int set_peridod_size (uint32_t)
        {
                return -1;
        }
 
        virtual bool can_request_update_devices ()
        {
                return false;
        }
 
        virtual bool update_devices ()
        {
                return false;
        }
 
        virtual bool can_use_buffered_io ()
        {
                return false;
        }
 
        virtual void set_use_buffered_io (bool) {}
 
        virtual bool get_use_buffered_io ()
        {
                return false;
        }
 
        virtual std::vector<float> available_sample_rates (const std::string& device) const = 0;
 
        /* backends that suppor586t 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 48kHz is not in the list
         * returned by available_sample_rates()
         */
        virtual float default_sample_rate () const
        {
                return 48000.0;
        }
 
        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;
        }
        /* Return true if the derived class can change the sample rate of the
         * device in use while the device is already being used. Return false
         * otherwise. (example: JACK cannot do this as of September 2013)
         */
        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.
         */
        virtual bool can_change_buffer_size_when_running () const = 0;
 
        virtual bool can_measure_systemic_latency () const = 0;
 
        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.
         *
         * If called while running, the state will change as fast as the
         * implementation allows.
         *
         * All set_*() methods return zero on success, non-zero otherwise.
         */
 
        virtual int set_device_name (const std::string&) = 0;
 
        virtual int set_input_device_name (const std::string&)
        {
                return 0;
        }
 
        virtual int set_output_device_name (const std::string&)
        {
                return 0;
        }
 
        virtual int drop_device ()
        {
                return 0;
        };
 
        virtual int set_sample_rate (float) = 0;
 
        virtual int set_buffer_size (uint32_t) = 0;
 
        virtual int set_interleaved (bool yn) = 0;
 
        virtual int set_systemic_input_latency (uint32_t) = 0;
 
        virtual int set_systemic_output_latency (uint32_t) = 0;
 
        virtual int set_systemic_midi_input_latency (std::string const, uint32_t) = 0;
 
        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 bool     interleaved () 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; }
 
        virtual std::string driver_name () const
        {
                return std::string ();
        }
 
        virtual std::string control_app_name () const = 0;
 
        virtual void launch_control_app () = 0;
 
        /* @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 \p 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;
 
        virtual std::vector<DeviceStatus> enumerate_midi_devices () const = 0;
 
        virtual int set_midi_device_enabled (std::string const, bool) = 0;
 
        virtual bool midi_device_enabled (std::string const) const = 0;
 
        virtual bool can_set_systemic_midi_latencies () const = 0;
 
        /* State Control */
 
        int start (bool for_latency_measurement = false)
        {
                return _start (for_latency_measurement);
        }
 
        virtual int stop () = 0;
 
        virtual int reset_device () = 0;
 
        virtual int freewheel (bool start_stop) = 0;
 
        virtual float dsp_load () const = 0;
 
        /* Transport Control (JACK is the only audio API that currently offers
         * the concept of shared transport control)
         */
 
        virtual void transport_start () {}
 
        virtual void transport_stop () {}
 
        virtual TransportState transport_state () const
        {
                return TransportStopped;
        }
 
        virtual void transport_locate (samplepos_t pos) {}
 
        virtual samplepos_t transport_sample () const
        {
                return 0;
        }
 
        virtual int set_time_master (bool yn)
        {
                return 0;
        }
 
        virtual int usecs_per_cycle () const
        {
                return 1000000 * (buffer_size () / sample_rate ());
        }
        virtual size_t raw_buffer_size (DataType t) = 0;
 
        /* Process time */
 
        virtual samplepos_t sample_time () = 0;
 
        virtual samplepos_t sample_time_at_cycle_start () = 0;
 
        virtual pframes_t samples_since_cycle_start () = 0;
 
        virtual bool get_sync_offset (pframes_t& offset) const
        {
                return false;
        }
 
        virtual int create_process_thread (std::function<void()> func) = 0;
 
        virtual int join_process_threads () = 0;
 
        virtual bool in_process_thread () = 0;
 
        static size_t thread_stack_size ()
        {
                return 100000;
        }
 
        virtual uint32_t process_thread_count () = 0;
 
        virtual void update_latencies () = 0;
 
        virtual bool speed_and_position (double& speed, samplepos_t& position)
        {
                speed    = 0.0;
                position = 0;
                return false;
        }
 
        enum TimingTypes {
                DeviceWait = 0,
                RunLoop,
                /* end */
                NTT
        };
 
        PBD::TimingStats dsp_stats[NTT];
 
protected:
        AudioBackendInfo& _info;
        AudioEngine&      engine;
 
        virtual int _start (bool for_latency_measurement) = 0;
};
 
} // namespace ARDOUR