libs/ardour/ardour/audio_backend.h

   1 /*
   2     Copyright (C) 2013 Paul Davis
   3
   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.
   8
   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.
  13
  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.
  17
  18 */
  19
  20 #ifndef __libardour_audiobackend_h__
  21 #define __libardour_audiobackend_h__
  22
  23 #include <string>
  24 #include <vector>
  25
  26 #include <stdint.h>
  27 #include <stdlib.h>
  28
  29 #include <boost/function.hpp>
  30
  31 #include "ardour/libardour_visibility.h"
  32 #include "ardour/types.h"
  33 #include "ardour/audioengine.h"
  34 #include "ardour/port_engine.h"
  35 #include "ardour/visibility.h"
  36
  37 #ifdef ARDOURBACKEND_DLL_EXPORTS // defined if we are building the ARDOUR Panners DLLs (instead of using them)
  38     #define ARDOURBACKEND_API LIBARDOUR_HELPER_DLL_EXPORT
  39 #else
  40     #define ARDOURBACKEND_API LIBARDOUR_HELPER_DLL_IMPORT
  41 #endif
  42 #define ARDOURBACKEND_LOCAL LIBARDOUR_HELPER_DLL_LOCAL
  43
  44 namespace ARDOUR {
  45
  46 class LIBARDOUR_API AudioBackend : public PortEngine {
  47   public:
  48
  49     AudioBackend (AudioEngine& e) : PortEngine (e), engine (e) {}
  50     virtual ~AudioBackend () {}
  51
  52     /** Return the name of this backend.
  53      *
  54      * Should use a well-known, unique term. Expected examples
  55      * might include "JACK", "CoreAudio", "ASIO" etc.
  56      */
  57     virtual std::string name() const = 0;
  58
  59     /** Return true if the callback from the underlying mechanism/API
  60      * (CoreAudio, JACK, ASIO etc.) occurs in a thread subject to realtime
  61      * constraints. Return false otherwise.
  62     */
  63     virtual bool is_realtime () const = 0;
  64
  65     /* Discovering devices and parameters */
  66
  67     /** Return true if this backend requires the selection of a "driver"
  68      * before any device can be selected. Return false otherwise.
  69      *
  70      * Intended mainly to differentiate between meta-APIs like JACK
  71      * which can still expose different backends (such as ALSA or CoreAudio
  72      * or FFADO or netjack) and those like ASIO or CoreAudio which
  73      * do not.
  74      */
  75     virtual bool requires_driver_selection() const { return false; }
  76
  77     /** If the return value of requires_driver_selection() is true,
  78      * then this function can return the list of known driver names.
  79      *
  80      * If the return value of requires_driver_selection() is false,
  81      * then this function should not be called. If it is called
  82      * its return value is an empty vector of strings.
  83      */
  84     virtual std::vector<std::string> enumerate_drivers() const { return std::vector<std::string>(); }
  85
  86     /** Returns zero if the backend can successfully use @param name as the
  87      * driver, non-zero otherwise.
  88      *
  89      * Should not be used unless the backend returns true from
  90      * requires_driver_selection()
  91      */
  92     virtual int set_driver (const std::string& /*drivername*/) { return 0; }
  93
  94     /** used to list device names along with whether or not they are currently
  95      *  available.
  96     */
  97     struct DeviceStatus {
  98         std::string name;
  99         bool        available;
 100
 101         DeviceStatus (const std::string& s, bool avail) : name (s), available (avail) {}
 102     };
 103
 104     /** Returns a collection of DeviceStatuses identifying devices discovered
 105      * by this backend since the start of the process.
 106      *
 107      * Any of the names in each DeviceStatus may be used to identify a
 108      * device in other calls to the backend, though any of them may become
 109      * invalid at any time.
 110      */
 111     virtual std::vector<DeviceStatus> enumerate_devices () const = 0;
 112
 113     /** Returns a collection of float identifying sample rates that are
 114      * potentially usable with the hardware identified by @param device.
 115      * Any of these values may be supplied in other calls to this backend
 116      * as the desired sample rate to use with the name device, but the
 117      * requested sample rate may turn out to be unavailable, or become invalid
 118      * at any time.
 119      */
 120     virtual std::vector<float> available_sample_rates (const std::string& device) const = 0;
 121     /** Returns a collection of uint32 identifying buffer sizes that are
 122      * potentially usable with the hardware identified by @param device.
 123      * Any of these values may be supplied in other calls to this backend
 124      * as the desired buffer size to use with the name device, but the
 125      * requested buffer size may turn out to be unavailable, or become invalid
 126      * at any time.
 127      */
 128     virtual std::vector<uint32_t> available_buffer_sizes (const std::string& device) const = 0;
 129
 130     /** Returns the maximum number of input channels that are potentially
 131      * usable with the hardware identified by @param device.  Any number from 1
 132      * to the value returned may be supplied in other calls to this backend as
 133      * the input channel count to use with the name device, but the requested
 134      * count may turn out to be unavailable, or become invalid at any time.
 135      */
 136     virtual uint32_t available_input_channel_count (const std::string& device) const = 0;
 137
 138     /** Returns the maximum number of output channels that are potentially
 139      * usable with the hardware identified by @param device.  Any number from 1
 140      * to the value returned may be supplied in other calls to this backend as
 141      * the output channel count to use with the name device, but the requested
 142      * count may turn out to be unavailable, or become invalid at any time.
 143      */
 144     virtual uint32_t available_output_channel_count (const std::string& device) const = 0;
 145
 146     /* Return true if the derived class can change the sample rate of the
 147      * device in use while the device is already being used. Return false
 148      * otherwise. (example: JACK cannot do this as of September 2013)
 149      */
 150     virtual bool can_change_sample_rate_when_running () const = 0;
 151     /* Return true if the derived class can change the buffer size of the
 152      * device in use while the device is already being used. Return false
 153      * otherwise.
 154      */
 155     virtual bool can_change_buffer_size_when_running () const = 0;
 156
 157     /* Set the hardware parameters.
 158      *
 159      * If called when the current state is stopped or paused,
 160      * the changes will not take effect until the state changes to running.
 161      *
 162      * If called while running, the state will change as fast as the
 163      * implementation allows.
 164      *
 165      * All set_*() methods return zero on success, non-zero otherwise.
 166      */
 167
 168     /** Set the name of the device to be used
 169      */
 170     virtual int set_device_name (const std::string&) = 0;
 171     /** Set the sample rate to be used
 172      */
 173     virtual int set_sample_rate (float) = 0;
 174     /** Set the buffer size to be used.
 175      *
 176      * The device is assumed to use a double buffering scheme, so that one
 177      * buffer's worth of data can be processed by hardware while software works
 178      * on the other buffer. All known suitable audio APIs support this model
 179      * (though ALSA allows for alternate numbers of buffers, and CoreAudio
 180      * doesn't directly expose the concept).
 181      */
 182     virtual int set_buffer_size (uint32_t) = 0;
 183     /** Set the preferred underlying hardware sample format
 184      *
 185      * This does not change the sample format (32 bit float) read and
 186      * written to the device via the Port API.
 187      */
 188     virtual int set_sample_format (SampleFormat) = 0;
 189     /** Set the preferred underlying hardware data layout.
 190      * If @param yn is true, then the hardware will interleave
 191      * samples for successive channels; otherwise, the hardware will store
 192      * samples for a single channel contiguously.
 193      *
 194      * Setting this does not change the fact that all data streams
 195      * to and from Ports are mono (essentially, non-interleaved)
 196      */
 197     virtual int set_interleaved (bool yn) = 0;
 198     /** Set the number of input channels that should be used
 199      */
 200     virtual int set_input_channels (uint32_t) = 0;
 201     /** Set the number of output channels that should be used
 202      */
 203     virtual int set_output_channels (uint32_t) = 0;
 204     /** Set the (additional) input latency that cannot be determined via
 205      * the implementation's underlying code (e.g. latency from
 206      * external D-A/D-A converters. Units are samples.
 207      */
 208     virtual int set_systemic_input_latency (uint32_t) = 0;
 209     /** Set the (additional) output latency that cannot be determined via
 210      * the implementation's underlying code (e.g. latency from
 211      * external D-A/D-A converters. Units are samples.
 212      */
 213     virtual int set_systemic_output_latency (uint32_t) = 0;
 214
 215     /* Retrieving parameters */
 216
 217     virtual std::string  device_name () const = 0;
 218     virtual float        sample_rate () const = 0;
 219     virtual uint32_t     buffer_size () const = 0;
 220     virtual SampleFormat sample_format () const = 0;
 221     virtual bool         interleaved () const = 0;
 222     virtual uint32_t     input_channels () const = 0;
 223     virtual uint32_t     output_channels () const = 0;
 224     virtual uint32_t     systemic_input_latency () const = 0;
 225     virtual uint32_t     systemic_output_latency () const = 0;
 226
 227     /** override this if this implementation returns true from
 228      * requires_driver_selection()
 229      */
 230     virtual std::string  driver_name() const { return std::string(); }
 231
 232     /** Return the name of a control application for the
 233      * selected/in-use device. If no such application exists,
 234      * or if no device has been selected or is in-use,
 235      * return an empty string.
 236      */
 237     virtual std::string control_app_name() const = 0;
 238     /** Launch the control app for the currently in-use or
 239      * selected device. May do nothing if the control
 240      * app is undefined or cannot be launched.
 241      */
 242     virtual void launch_control_app () = 0;
 243
 244     /* @return a vector of strings that describe the available
 245      * MIDI options.
 246      *
 247      * These can be presented to the user to decide which
 248      * MIDI drivers, options etc. can be used. The returned strings
 249      * should be thought of as the key to a map of possible
 250      * approaches to handling MIDI within the backend. Ensure that
 251      * the strings will make sense to the user.
 252      */
 253     virtual std::vector<std::string> enumerate_midi_options () const = 0;
 254
 255     /* Request the use of the MIDI option named @param option, which
 256      * should be one of the strings returned by enumerate_midi_options()
 257      *
 258      * @return zero if successful, non-zero otherwise
 259      */
 260     virtual int set_midi_option (const std::string& option) = 0;
 261
 262     virtual std::string midi_option () const = 0;
 263
 264     /* State Control */
 265
 266     /* non-virtual method to avoid possible overrides of default
 267      * parameters. See Scott Meyers or other books on C++ to
 268      * understand this pattern, or possibly just this:
 269      *
 270      * http://stackoverflow.com/questions/12139786/good-pratice-default-arguments-for-pure-virtual-method
 271      */
 272     int start (bool for_latency_measurement=false) {
 273             return _start (for_latency_measurement);
 274     }
 275
 276     /** Start using the device named in the most recent call
 277      * to set_device(), with the parameters set by various
 278      * the most recent calls to set_sample_rate() etc. etc.
 279      *
 280      * At some undetermined time after this function is successfully called,
 281      * the backend will start calling the ::process_callback() method of
 282      * the AudioEngine referenced by @param engine. These calls will
 283      * occur in a thread created by and/or under the control of the backend.
 284      *
 285      * @param for_latency_measurement if true, the device is being started
 286      *        to carry out latency measurements and the backend should this
 287      *        take care to return latency numbers that do not reflect
 288      *        any existing systemic latency settings.
 289      *
 290      * Return zero if successful, negative values otherwise.
 291      */
 292     virtual int _start (bool for_latency_measurement) = 0;
 293
 294     /** Stop using the device currently in use.
 295      *
 296      * If the function is successfully called, no subsequent calls to the
 297      * process_callback() of @param engine will be made after the function
 298      * returns, until parameters are reset and start() are called again.
 299      *
 300      * The backend is considered to be un-configured after a successful
 301      * return, and requires calls to set hardware parameters before it can be
 302      * start()-ed again. See pause() for a way to avoid this. stop() should
 303      * only be used when reconfiguration is required OR when there are no
 304      * plans to use the backend in the future with a reconfiguration.
 305      *
 306      * Return zero if successful, 1 if the device is not in use, negative values on error
 307      */
 308     virtual int stop () = 0;
 309
 310     /** Temporarily cease using the device named in the most recent call to set_parameters().
 311      *
 312      * If the function is successfully called, no subsequent calls to the
 313      * process_callback() of @param engine will be made after the function
 314      * returns, until start() is called again.
 315      *
 316      * The backend will retain its existing parameter configuration after a successful
 317      * return, and does NOT require any calls to set hardware parameters before it can be
 318      * start()-ed again.
 319      *
 320      * Return zero if successful, 1 if the device is not in use, negative values on error
 321      */
 322     virtual int pause () = 0;
 323
 324     /** While remaining connected to the device, and without changing its
 325      * configuration, start (or stop) calling the process_callback() of @param engine
 326      * without waiting for the device. Once process_callback() has returned, it
 327      * will be called again immediately, thus allowing for faster-than-realtime
 328      * processing.
 329      *
 330      * All registered ports remain in existence and all connections remain
 331      * unaltered. However, any physical ports should NOT be used by the
 332      * process_callback() during freewheeling - the data behaviour is undefined.
 333      *
 334      * If @param start_stop is true, begin this behaviour; otherwise cease this
 335      * behaviour if it currently occuring, and return to calling
 336      * process_callback() of @param engine by waiting for the device.
 337      *
 338      * Return zero on success, non-zero otherwise.
 339      */
 340     virtual int freewheel (bool start_stop) = 0;
 341
 342     /** return the fraction of the time represented by the current buffer
 343      * size that is being used for each buffer process cycle, as a value
 344      * from 0.0 to 1.0
 345      *
 346      * E.g. if the buffer size represents 5msec and current processing
 347      * takes 1msec, the returned value should be 0.2.
 348      *
 349      * Implementations can feel free to smooth the values returned over
 350      * time (e.g. high pass filtering, or its equivalent).
 351      */
 352     virtual float cpu_load() const  = 0;
 353
 354     /* Transport Control (JACK is the only audio API that currently offers
 355        the concept of shared transport control)
 356     */
 357
 358     /** Attempt to change the transport state to TransportRolling.
 359      */
 360     virtual void transport_start () {}
 361     /** Attempt to change the transport state to TransportStopped.
 362      */
 363     virtual void transport_stop () {}
 364     /** return the current transport state
 365      */
 366     virtual TransportState transport_state () const { return TransportStopped; }
 367     /** Attempt to locate the transport to @param pos
 368      */
 369     virtual void transport_locate (framepos_t /*pos*/) {}
 370     /** Return the current transport location, in samples measured
 371      * from the origin (defined by the transport time master)
 372      */
 373     virtual framepos_t transport_frame() const { return 0; }
 374
 375     /** If @param yn is true, become the time master for any inter-application transport
 376      * timebase, otherwise cease to be the time master for the same.
 377      *
 378      * Return zero on success, non-zero otherwise
 379      *
 380      * JACK is the only currently known audio API with the concept of a shared
 381      * transport timebase.
 382      */
 383     virtual int set_time_master (bool /*yn*/) { return 0; }
 384
 385     virtual int        usecs_per_cycle () const { return 1000000 * (buffer_size() / sample_rate()); }
 386     virtual size_t     raw_buffer_size (DataType t) = 0;
 387
 388     /* Process time */
 389
 390     /** return the time according to the sample clock in use, measured in
 391      * samples since an arbitrary zero time in the past. The value should
 392      * increase monotonically and linearly, without interruption from any
 393      * source (including CPU frequency scaling).
 394      *
 395      * It is extremely likely that any implementation will use a DLL, since
 396      * this function can be called from any thread, at any time, and must be
 397      * able to accurately determine the correct sample time.
 398      *
 399      * Can be called from any thread.
 400      */
 401     virtual pframes_t sample_time () = 0;
 402
 403     /** Return the time according to the sample clock in use when the most
 404      * recent buffer process cycle began. Can be called from any thread.
 405      */
 406     virtual pframes_t sample_time_at_cycle_start () = 0;
 407
 408     /** Return the time since the current buffer process cycle started,
 409      * in samples, according to the sample clock in use.
 410      *
 411      * Can ONLY be called from within a process() callback tree (which
 412      * implies that it can only be called by a process thread)
 413      */
 414     virtual pframes_t samples_since_cycle_start () = 0;
 415
 416     /** Return true if it possible to determine the offset in samples of the
 417      * first video frame that starts within the current buffer process cycle,
 418      * measured from the first sample of the cycle. If returning true,
 419      * set @param offset to that offset.
 420      *
 421      * Eg. if it can be determined that the first video frame within the cycle
 422      * starts 28 samples after the first sample of the cycle, then this method
 423      * should return true and set @param offset to 28.
 424      *
 425      * May be impossible to support outside of JACK, which has specific support
 426      * (in some cases, hardware support) for this feature.
 427      *
 428      * Can ONLY be called from within a process() callback tree (which implies
 429      * that it can only be called by a process thread)
 430      */
 431     virtual bool get_sync_offset (pframes_t& /*offset*/) const { return false; }
 432
 433     /** Create a new thread suitable for running part of the buffer process
 434      * cycle (i.e. Realtime scheduling, memory allocation, etc. etc are all
 435      * correctly setup), with a stack size given in bytes by specified @param
 436      * stacksize. The thread will begin executing @param func, and will exit
 437      * when that function returns.
 438      */
 439     virtual int create_process_thread (boost::function<void()> func) = 0;
 440
 441     /** Wait for all processing threads to exit.
 442      *
 443      * Return zero on success, non-zero on failure.
 444      */
 445     virtual int join_process_threads () = 0;
 446
 447     /** Return true if execution context is in a backend thread
 448      */
 449     virtual bool in_process_thread () = 0;
 450
 451     /** Return the minimum stack size of audio threads in bytes
 452      */
 453     static size_t thread_stack_size () { return 100000; }
 454
 455     /** Return number of processing threads
 456      */
 457     virtual uint32_t process_thread_count () = 0;
 458
 459     virtual void update_latencies () = 0;
 460
 461   protected:
 462     AudioEngine&          engine;
 463 };
 464
 465 struct LIBARDOUR_API AudioBackendInfo {
 466     const char* name;
 467
 468     /** Using arg1 and arg2, initialize this audiobackend.
 469      *
 470      * Returns zero on success, non-zero otherwise.
 471      */
 472     int (*instantiate) (const std::string& arg1, const std::string& arg2);
 473
 474     /** Release all resources associated with this audiobackend
 475      */
 476     int (*deinstantiate) (void);
 477
 478     /** Factory method to create an AudioBackend-derived class.
 479      *
 480      * Returns a valid shared_ptr to the object if successfull,
 481      * or a "null" shared_ptr otherwise.
 482      */
 483     boost::shared_ptr<AudioBackend> (*factory) (AudioEngine&);
 484
 485     /** Return true if the underlying mechanism/API has been
 486      * configured and does not need (re)configuration in order
 487      * to be usable. Return false otherwise.
 488      *
 489      * Note that this may return true if (re)configuration, even though
 490      * not currently required, is still possible.
 491      */
 492     bool (*already_configured)();
 493 };
 494
 495 } // namespace
 496
 497 #endif /* __libardour_audiobackend_h__ */
 498