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