audio_backend.h

Go to the documentation of this file.

/*
    Copyright (C) 2013 Paul Davis

    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., 675 Mass Ave, Cambridge, MA 02139, USA.

*/

#ifndef __libardour_audiobackend_h__
#define __libardour_audiobackend_h__

#include <string>
#include <vector>

#include <stdint.h>
#include <stdlib.h>

#include <boost/function.hpp>

#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 {

struct LIBARDOUR_API AudioBackendInfo {
    const char* name;

    int (*instantiate) (const std::string& arg1, const std::string& arg2);

    int (*deinstantiate) (void);

    boost::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 () {}
    
    AudioBackendInfo& info() const { return _info; }

    virtual std::string name() const = 0;

    virtual bool is_realtime () const = 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 std::vector<DeviceStatus> enumerate_devices () const = 0;

    virtual std::vector<float> available_sample_rates (const std::string& device) const = 0;

    /* 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;
    }

    virtual std::vector<uint32_t> available_buffer_sizes (const std::string& device) const = 0;

    /* 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;
    }

    virtual uint32_t available_input_channel_count (const std::string& device) const = 0;

    virtual uint32_t available_output_channel_count (const std::string& device) const = 0;

    /* 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;

    /* 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 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_input_channels (uint32_t) = 0;
    virtual int set_output_channels (uint32_t) = 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 float        sample_rate () const = 0;
    virtual uint32_t     buffer_size () 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 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 @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;

    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 (framepos_t /*pos*/) {}
    virtual framepos_t transport_frame() 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 framepos_t sample_time () = 0;

    virtual framepos_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 (boost::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, 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__ */