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
  36 #ifdef ARDOURBACKEND_DLL_EXPORTS // defined if we are building the ARDOUR Panners DLLs (instead of using them)
  37     #define ARDOURBACKEND_API LIBARDOUR_DLL_EXPORT
  38 #else
  39     #define ARDOURBACKEND_API LIBARDOUR_DLL_IMPORT
  40 #endif
  41 #define ARDOURBACKEND_LOCAL LIBARDOUR_DLL_LOCAL
  42
  43 namespace ARDOUR {
  44
  45 struct LIBARDOUR_API AudioBackendInfo {
  46     const char* name;
  47
  48     /** Using arg1 and arg2, initialize this audiobackend.
  49      *
  50      * Returns zero on success, non-zero otherwise.
  51      */
  52     int (*instantiate) (const std::string& arg1, const std::string& arg2);
  53
  54     /** Release all resources associated with this audiobackend
  55      */
  56     int (*deinstantiate) (void);
  57
  58     /** Factory method to create an AudioBackend-derived class.
  59      *
  60      * Returns a valid shared_ptr to the object if successfull,
  61      * or a "null" shared_ptr otherwise.
  62      */
  63     boost::shared_ptr<AudioBackend> (*factory) (AudioEngine&);
  64
  65     /** Return true if the underlying mechanism/API has been
  66      * configured and does not need (re)configuration in order
  67      * to be usable. Return false otherwise.
  68      *
  69      * Note that this may return true if (re)configuration, even though
  70      * not currently required, is still possible.
  71      */
  72     bool (*already_configured)();
  73
  74     /** Return true if the underlying mechanism/API can be
  75      * used on the given system.
  76      *
  77      * If this function returns false, the backend is not
  78      * listed in the engine dialog.
  79      */
  80     bool (*available)();
  81 };
  82
  83 class LIBARDOUR_API AudioBackend : public PortEngine {
  84   public:
  85
  86     AudioBackend (AudioEngine& e, AudioBackendInfo& i) : PortEngine (e), _info (i), engine (e) {}
  87     virtual ~AudioBackend () {}
  88
  89         enum ErrorCode {
  90                 NoError = 0,
  91                 BackendInitializationError = -64,
  92                 BackendDeinitializationError,
  93                 BackendReinitializationError,
  94                 AudioDeviceOpenError,
  95                 AudioDeviceCloseError,
  96                 AudioDeviceInvalidError,
  97                 AudioDeviceNotAvailableError,
  98                 AudioDeviceNotConnectedError,
  99                 AudioDeviceReservationError,
 100                 AudioDeviceIOError,
 101                 MidiDeviceOpenError,
 102                 MidiDeviceCloseError,
 103                 MidiDeviceNotAvailableError,
 104                 MidiDeviceNotConnectedError,
 105                 MidiDeviceIOError,
 106                 SampleFormatNotSupportedError,
 107                 SampleRateNotSupportedError,
 108                 RequestedInputLatencyNotSupportedError,
 109                 RequestedOutputLatencyNotSupportedError,
 110                 PeriodSizeNotSupportedError,
 111                 PeriodCountNotSupportedError,
 112                 DeviceConfigurationNotSupportedError,
 113                 ChannelCountNotSupportedError,
 114                 InputChannelCountNotSupportedError,
 115                 OutputChannelCountNotSupportedError,
 116                 AquireRealtimePermissionError,
 117                 SettingAudioThreadPriorityError,
 118                 SettingMIDIThreadPriorityError,
 119                 ProcessThreadStartError,
 120                 FreewheelThreadStartError,
 121                 PortRegistrationError,
 122                 PortReconnectError,
 123                 OutOfMemoryError,
 124         };
 125
 126         static std::string get_error_string (ErrorCode);
 127
 128         enum StandardDeviceName {
 129                 DeviceNone,
 130                 DeviceDefault
 131         };
 132
 133         static std::string get_standard_device_name (StandardDeviceName);
 134
 135     /** Return the AudioBackendInfo object from which this backend
 136         was constructed.
 137     */
 138     AudioBackendInfo& info() const { return _info; }
 139
 140     /** Return the name of this backend.
 141      *
 142      * Should use a well-known, unique term. Expected examples
 143      * might include "JACK", "CoreAudio", "ASIO" etc.
 144      */
 145     virtual std::string name() const = 0;
 146
 147     /** Return true if the callback from the underlying mechanism/API
 148      * (CoreAudio, JACK, ASIO etc.) occurs in a thread subject to realtime
 149      * constraints. Return false otherwise.
 150     */
 151     virtual bool is_realtime () const = 0;
 152
 153     /* Discovering devices and parameters */
 154
 155     /** Return true if this backend requires the selection of a "driver"
 156      * before any device can be selected. Return false otherwise.
 157      *
 158      * Intended mainly to differentiate between meta-APIs like JACK
 159      * which can still expose different backends (such as ALSA or CoreAudio
 160      * or FFADO or netjack) and those like ASIO or CoreAudio which
 161      * do not.
 162      */
 163     virtual bool requires_driver_selection() const { return false; }
 164
 165     /** If the return value of requires_driver_selection() is true,
 166      * then this function can return the list of known driver names.
 167      *
 168      * If the return value of requires_driver_selection() is false,
 169      * then this function should not be called. If it is called
 170      * its return value is an empty vector of strings.
 171      */
 172     virtual std::vector<std::string> enumerate_drivers() const { return std::vector<std::string>(); }
 173
 174     /** Returns zero if the backend can successfully use @param name as the
 175      * driver, non-zero otherwise.
 176      *
 177      * Should not be used unless the backend returns true from
 178      * requires_driver_selection()
 179      */
 180     virtual int set_driver (const std::string& /*drivername*/) { return 0; }
 181
 182     /** used to list device names along with whether or not they are currently
 183      *  available.
 184     */
 185     struct DeviceStatus {
 186         std::string name;
 187         bool        available;
 188
 189         DeviceStatus (const std::string& s, bool avail) : name (s), available (avail) {}
 190     };
 191
 192     /** An optional alternate interface for backends to provide a facility to
 193      * select separate input and output devices.
 194      *
 195      * If a backend returns true then enumerate_input_devices() and
 196      * enumerate_output_devices() will be used instead of enumerate_devices()
 197      * to enumerate devices. Similarly set_input/output_device_name() should
 198      * be used to set devices instead of set_device_name().
 199      */
 200     virtual bool use_separate_input_and_output_devices () const { return false; }
 201
 202     /** Returns a collection of DeviceStatuses identifying devices discovered
 203      * by this backend since the start of the process.
 204      *
 205      * Any of the names in each DeviceStatus may be used to identify a
 206      * device in other calls to the backend, though any of them may become
 207      * invalid at any time.
 208      */
 209     virtual std::vector<DeviceStatus> enumerate_devices () const = 0;
 210
 211     /** Returns a collection of DeviceStatuses identifying input devices
 212      * discovered by this backend since the start of the process.
 213      *
 214      * Any of the names in each DeviceStatus may be used to identify a
 215      * device in other calls to the backend, though any of them may become
 216      * invalid at any time.
 217      */
 218     virtual std::vector<DeviceStatus> enumerate_input_devices () const
 219     { return std::vector<DeviceStatus>(); }
 220
 221     /** Returns a collection of DeviceStatuses identifying output devices
 222      * discovered by this backend since the start of the process.
 223      *
 224      * Any of the names in each DeviceStatus may be used to identify a
 225      * device in other calls to the backend, though any of them may become
 226      * invalid at any time.
 227      */
 228     virtual std::vector<DeviceStatus> enumerate_output_devices () const
 229     { return std::vector<DeviceStatus>(); }
 230
 231
 232         /** An interface to set buffers/period for playback latency.
 233          * useful for ALSA or JACK/ALSA on Linux.
 234          *
 235          * @return true if the backend supports period-size configuration
 236          */
 237         virtual bool can_set_period_size () const { return false; }
 238
 239         /** Returns a vector of supported period-sizes for the given driver */
 240         virtual std::vector<uint32_t> available_period_sizes (const std::string& driver) const { return std::vector<uint32_t>(); }
 241
 242         /** Set the period size to be used.
 243          * must be called before starting the backend.
 244          */
 245         virtual int set_peridod_size (uint32_t) { return -1; }
 246
 247         /**
 248          * @return true if backend supports requesting an update to the device list
 249          * and any cached properties associated with the devices.
 250          */
 251         virtual bool can_request_update_devices () { return false; }
 252
 253         /**
 254          * Request an update to the list of devices returned in the enumerations.
 255          * The Backend must return true from can_request_update_devices to support
 256          * this interface.
 257          * @return true if the devices were updated
 258          */
 259         virtual bool update_devices () { return false; }
 260
 261     /** Returns a collection of float identifying sample rates that are
 262      * potentially usable with the hardware identified by @param device.
 263      * Any of these values may be supplied in other calls to this backend
 264      * as the desired sample rate to use with the name device, but the
 265      * requested sample rate may turn out to be unavailable, or become invalid
 266      * at any time.
 267      */
 268     virtual std::vector<float> available_sample_rates (const std::string& device) const = 0;
 269
 270     /* backends that support separate input and output devices should
 271      * implement this function and return an intersection (not union) of available
 272      * sample rates valid for the given input + output device combination.
 273      */
 274     virtual std::vector<float> available_sample_rates2 (const std::string& input_device, const std::string& output_device) const {
 275             std::vector<float> input_sizes  = available_sample_rates (input_device);
 276             std::vector<float> output_sizes = available_sample_rates (output_device);
 277             std::vector<float> rv;
 278             std::set_union (input_sizes.begin (), input_sizes.end (),
 279                             output_sizes.begin (), output_sizes.end (),
 280                             std::back_inserter (rv));
 281             return rv;
 282     }
 283
 284     /* Returns the default sample rate that will be shown to the user when
 285      * configuration options are first presented. If the derived class
 286      * needs or wants to override this, it can. It also MUST override this
 287      * if there is any chance that an SR of 44.1kHz is not in the list
 288      * returned by available_sample_rates()
 289      */
 290     virtual float default_sample_rate () const {
 291             return 44100.0;
 292     }
 293
 294     /** Returns a collection of uint32 identifying buffer sizes that are
 295      * potentially usable with the hardware identified by @param device.
 296      * Any of these values may be supplied in other calls to this backend
 297      * as the desired buffer size to use with the name device, but the
 298      * requested buffer size may turn out to be unavailable, or become invalid
 299      * at any time.
 300      */
 301     virtual std::vector<uint32_t> available_buffer_sizes (const std::string& device) const = 0;
 302
 303     /* backends that support separate input and output devices should
 304      * implement this function and return an intersection (not union) of available
 305      * buffer sizes valid for the given input + output device combination.
 306      */
 307     virtual std::vector<uint32_t> available_buffer_sizes2 (const std::string& input_device, const std::string& output_device) const {
 308             std::vector<uint32_t> input_rates  = available_buffer_sizes (input_device);
 309             std::vector<uint32_t> output_rates = available_buffer_sizes (output_device);
 310             std::vector<uint32_t> rv;
 311             std::set_union (input_rates.begin (), input_rates.end (),
 312                             output_rates.begin (), output_rates.end (),
 313                             std::back_inserter (rv));
 314             return rv;
 315     }
 316     /* Returns the default buffer size that will be shown to the user when
 317      * configuration options are first presented. If the derived class
 318      * needs or wants to override this, it can. It also MUST override this
 319      * if there is any chance that a buffer size of 1024 is not in the list
 320      * returned by available_buffer_sizes()
 321      */
 322     virtual uint32_t default_buffer_size (const std::string& device) const {
 323             return 1024;
 324     }
 325
 326     /** Returns the maximum number of input channels that are potentially
 327      * usable with the hardware identified by @param device.  Any number from 1
 328      * to the value returned may be supplied in other calls to this backend as
 329      * the input channel count to use with the name device, but the requested
 330      * count may turn out to be unavailable, or become invalid at any time.
 331      */
 332     virtual uint32_t available_input_channel_count (const std::string& device) const = 0;
 333
 334     /** Returns the maximum number of output channels that are potentially
 335      * usable with the hardware identified by @param device.  Any number from 1
 336      * to the value returned may be supplied in other calls to this backend as
 337      * the output channel count to use with the name device, but the requested
 338      * count may turn out to be unavailable, or become invalid at any time.
 339      */
 340     virtual uint32_t available_output_channel_count (const std::string& device) const = 0;
 341
 342     /* Return true if the derived class can change the sample rate of the
 343      * device in use while the device is already being used. Return false
 344      * otherwise. (example: JACK cannot do this as of September 2013)
 345      */
 346     virtual bool can_change_sample_rate_when_running () const = 0;
 347     /* Return true if the derived class can change the buffer size of the
 348      * device in use while the device is already being used. Return false
 349      * otherwise.
 350      */
 351     virtual bool can_change_buffer_size_when_running () const = 0;
 352
 353                 /** return true if the backend can measure and update
 354                  * systemic latencies without restart.
 355                  */
 356                 virtual bool can_change_systemic_latency_when_running () const { return false; }
 357
 358     /* Set the hardware parameters.
 359      *
 360      * If called when the current state is stopped or paused,
 361      * the changes will not take effect until the state changes to running.
 362      *
 363      * If called while running, the state will change as fast as the
 364      * implementation allows.
 365      *
 366      * All set_*() methods return zero on success, non-zero otherwise.
 367      */
 368
 369     /** Set the name of the device to be used
 370      */
 371     virtual int set_device_name (const std::string&) = 0;
 372
 373     /** Set the name of the input device to be used if using separate
 374      * input/output devices.
 375      *
 376      * @see use_separate_input_and_output_devices()
 377      */
 378     virtual int set_input_device_name (const std::string&) { return 0;}
 379
 380     /** Set the name of the output device to be used if using separate
 381      * input/output devices.
 382      *
 383      * @see use_separate_input_and_output_devices()
 384      */
 385     virtual int set_output_device_name (const std::string&) { return 0;}
 386
 387     /** Deinitialize and destroy current device
 388      */
 389         virtual int drop_device() {return 0;};
 390     /** Set the sample rate to be used
 391      */
 392     virtual int set_sample_rate (float) = 0;
 393     /** Set the buffer size to be used.
 394      *
 395      * The device is assumed to use a double buffering scheme, so that one
 396      * buffer's worth of data can be processed by hardware while software works
 397      * on the other buffer. All known suitable audio APIs support this model
 398      * (though ALSA allows for alternate numbers of buffers, and CoreAudio
 399      * doesn't directly expose the concept).
 400      */
 401     virtual int set_buffer_size (uint32_t) = 0;
 402     /** Set the preferred underlying hardware data layout.
 403      * If @param yn is true, then the hardware will interleave
 404      * samples for successive channels; otherwise, the hardware will store
 405      * samples for a single channel contiguously.
 406      *
 407      * Setting this does not change the fact that all data streams
 408      * to and from Ports are mono (essentially, non-interleaved)
 409      */
 410     virtual int set_interleaved (bool yn) = 0;
 411     /** Set the number of input channels that should be used
 412      */
 413     virtual int set_input_channels (uint32_t) = 0;
 414     /** Set the number of output channels that should be used
 415      */
 416     virtual int set_output_channels (uint32_t) = 0;
 417     /** Set the (additional) input latency that cannot be determined via
 418      * the implementation's underlying code (e.g. latency from
 419      * external D-A/D-A converters. Units are samples.
 420      */
 421     virtual int set_systemic_input_latency (uint32_t) = 0;
 422     /** Set the (additional) output latency that cannot be determined via
 423      * the implementation's underlying code (e.g. latency from
 424      * external D-A/D-A converters. Units are samples.
 425      */
 426     virtual int set_systemic_output_latency (uint32_t) = 0;
 427     /** Set the (additional) input latency for a specific midi device,
 428      * or if the identifier is empty, apply to all midi devices.
 429      */
 430     virtual int set_systemic_midi_input_latency (std::string const, uint32_t) = 0;
 431     /** Set the (additional) output latency for a specific midi device,
 432      * or if the identifier is empty, apply to all midi devices.
 433      */
 434     virtual int set_systemic_midi_output_latency (std::string const, uint32_t) = 0;
 435
 436     /* Retrieving parameters */
 437
 438     virtual std::string  device_name () const = 0;
 439     virtual std::string  input_device_name () const { return std::string(); }
 440     virtual std::string  output_device_name () const { return std::string(); }
 441     virtual float        sample_rate () const = 0;
 442     virtual uint32_t     buffer_size () const = 0;
 443     virtual bool         interleaved () const = 0;
 444     virtual uint32_t     input_channels () const = 0;
 445     virtual uint32_t     output_channels () const = 0;
 446     virtual uint32_t     systemic_input_latency () const = 0;
 447     virtual uint32_t     systemic_output_latency () const = 0;
 448     virtual uint32_t     systemic_midi_input_latency (std::string const) const = 0;
 449     virtual uint32_t     systemic_midi_output_latency (std::string const) const = 0;
 450     virtual uint32_t     period_size () const { return 0; }
 451
 452     /** override this if this implementation returns true from
 453      * requires_driver_selection()
 454      */
 455     virtual std::string  driver_name() const { return std::string(); }
 456
 457     /** Return the name of a control application for the
 458      * selected/in-use device. If no such application exists,
 459      * or if no device has been selected or is in-use,
 460      * return an empty string.
 461      */
 462     virtual std::string control_app_name() const = 0;
 463     /** Launch the control app for the currently in-use or
 464      * selected device. May do nothing if the control
 465      * app is undefined or cannot be launched.
 466      */
 467     virtual void launch_control_app () = 0;
 468
 469     /* @return a vector of strings that describe the available
 470      * MIDI options.
 471      *
 472      * These can be presented to the user to decide which
 473      * MIDI drivers, options etc. can be used. The returned strings
 474      * should be thought of as the key to a map of possible
 475      * approaches to handling MIDI within the backend. Ensure that
 476      * the strings will make sense to the user.
 477      */
 478     virtual std::vector<std::string> enumerate_midi_options () const = 0;
 479
 480     /* Request the use of the MIDI option named @param option, which
 481      * should be one of the strings returned by enumerate_midi_options()
 482      *
 483      * @return zero if successful, non-zero otherwise
 484      */
 485     virtual int set_midi_option (const std::string& option) = 0;
 486
 487     virtual std::string midi_option () const = 0;
 488
 489     /** Detailed MIDI device list - if available */
 490     virtual std::vector<DeviceStatus> enumerate_midi_devices () const = 0;
 491
 492     /** mark a midi-devices as enabled */
 493     virtual int set_midi_device_enabled (std::string const, bool) = 0;
 494
 495     /** query if a midi-device is enabled */
 496     virtual bool midi_device_enabled (std::string const) const = 0;
 497
 498     /** if backend supports systemic_midi_[in|ou]tput_latency() */
 499     virtual bool can_set_systemic_midi_latencies () const = 0;
 500
 501     /* State Control */
 502
 503     /** Start using the device named in the most recent call
 504      * to set_device(), with the parameters set by various
 505      * the most recent calls to set_sample_rate() etc. etc.
 506      *
 507      * At some undetermined time after this function is successfully called,
 508      * the backend will start calling the ::process_callback() method of
 509      * the AudioEngine referenced by @param engine. These calls will
 510      * occur in a thread created by and/or under the control of the backend.
 511      *
 512      * @param for_latency_measurement if true, the device is being started
 513      *        to carry out latency measurements and the backend should this
 514      *        take care to return latency numbers that do not reflect
 515      *        any existing systemic latency settings.
 516      *
 517      * Return zero if successful, negative values otherwise.
 518      *
 519      *
 520      *
 521      *
 522      * Why is this non-virtual but ::_start() is virtual ?
 523      * Virtual methods with default parameters create possible ambiguity
 524      * because a derived class may implement the same method with a different
 525      * type or value of default parameter.
 526      *
 527      * So we make this non-virtual method to avoid possible overrides of
 528      * default parameters. See Scott Meyers or other books on C++ to understand
 529      * this pattern, or possibly just this:
 530      *
 531      * http://stackoverflow.com/questions/12139786/good-pratice-default-arguments-for-pure-virtual-method
 532      */
 533     int start (bool for_latency_measurement=false) {
 534             return _start (for_latency_measurement);
 535     }
 536
 537     /** Stop using the device currently in use.
 538      *
 539      * If the function is successfully called, no subsequent calls to the
 540      * process_callback() of @param engine will be made after the function
 541      * returns, until parameters are reset and start() are called again.
 542      *
 543      * The backend is considered to be un-configured after a successful
 544      * return, and requires calls to set hardware parameters before it can be
 545      * start()-ed again. See pause() for a way to avoid this. stop() should
 546      * only be used when reconfiguration is required OR when there are no
 547      * plans to use the backend in the future with a reconfiguration.
 548      *
 549      * Return zero if successful, 1 if the device is not in use, negative values on error
 550      */
 551     virtual int stop () = 0;
 552
 553          /** Reset device.
 554      *
 555      * Return zero if successful, negative values on error
 556      */
 557         virtual int reset_device() = 0;
 558
 559     /** While remaining connected to the device, and without changing its
 560      * configuration, start (or stop) calling the process_callback() of @param engine
 561      * without waiting for the device. Once process_callback() has returned, it
 562      * will be called again immediately, thus allowing for faster-than-realtime
 563      * processing.
 564      *
 565      * All registered ports remain in existence and all connections remain
 566      * unaltered. However, any physical ports should NOT be used by the
 567      * process_callback() during freewheeling - the data behaviour is undefined.
 568      *
 569      * If @param start_stop is true, begin this behaviour; otherwise cease this
 570      * behaviour if it currently occuring, and return to calling
 571      * process_callback() of @param engine by waiting for the device.
 572      *
 573      * Return zero on success, non-zero otherwise.
 574      */
 575     virtual int freewheel (bool start_stop) = 0;
 576
 577     /** return the fraction of the time represented by the current buffer
 578      * size that is being used for each buffer process cycle, as a value
 579      * from 0.0 to 1.0
 580      *
 581      * E.g. if the buffer size represents 5msec and current processing
 582      * takes 1msec, the returned value should be 0.2.
 583      *
 584      * Implementations can feel free to smooth the values returned over
 585      * time (e.g. high pass filtering, or its equivalent).
 586      */
 587     virtual float dsp_load() const  = 0;
 588
 589     /* Transport Control (JACK is the only audio API that currently offers
 590        the concept of shared transport control)
 591     */
 592
 593     /** Attempt to change the transport state to TransportRolling.
 594      */
 595     virtual void transport_start () {}
 596     /** Attempt to change the transport state to TransportStopped.
 597      */
 598     virtual void transport_stop () {}
 599     /** return the current transport state
 600      */
 601     virtual TransportState transport_state () const { return TransportStopped; }
 602     /** Attempt to locate the transport to @param pos
 603      */
 604     virtual void transport_locate (framepos_t /*pos*/) {}
 605     /** Return the current transport location, in samples measured
 606      * from the origin (defined by the transport time master)
 607      */
 608     virtual framepos_t transport_frame() const { return 0; }
 609
 610     /** If @param yn is true, become the time master for any inter-application transport
 611      * timebase, otherwise cease to be the time master for the same.
 612      *
 613      * Return zero on success, non-zero otherwise
 614      *
 615      * JACK is the only currently known audio API with the concept of a shared
 616      * transport timebase.
 617      */
 618     virtual int set_time_master (bool /*yn*/) { return 0; }
 619
 620     virtual int        usecs_per_cycle () const { return 1000000 * (buffer_size() / sample_rate()); }
 621     virtual size_t     raw_buffer_size (DataType t) = 0;
 622
 623     /* Process time */
 624
 625     /** return the time according to the sample clock in use, measured in
 626      * samples since an arbitrary zero time in the past. The value should
 627      * increase monotonically and linearly, without interruption from any
 628      * source (including CPU frequency scaling).
 629      *
 630      * It is extremely likely that any implementation will use a DLL, since
 631      * this function can be called from any thread, at any time, and must be
 632      * able to accurately determine the correct sample time.
 633      *
 634      * Can be called from any thread.
 635      */
 636     virtual framepos_t sample_time () = 0;
 637
 638     /** Return the time according to the sample clock in use when the most
 639      * recent buffer process cycle began. Can be called from any thread.
 640      */
 641     virtual framepos_t sample_time_at_cycle_start () = 0;
 642
 643     /** Return the time since the current buffer process cycle started,
 644      * in samples, according to the sample clock in use.
 645      *
 646      * Can ONLY be called from within a process() callback tree (which
 647      * implies that it can only be called by a process thread)
 648      */
 649     virtual pframes_t samples_since_cycle_start () = 0;
 650
 651     /** Return true if it possible to determine the offset in samples of the
 652      * first video frame that starts within the current buffer process cycle,
 653      * measured from the first sample of the cycle. If returning true,
 654      * set @param offset to that offset.
 655      *
 656      * Eg. if it can be determined that the first video frame within the cycle
 657      * starts 28 samples after the first sample of the cycle, then this method
 658      * should return true and set @param offset to 28.
 659      *
 660      * May be impossible to support outside of JACK, which has specific support
 661      * (in some cases, hardware support) for this feature.
 662      *
 663      * Can ONLY be called from within a process() callback tree (which implies
 664      * that it can only be called by a process thread)
 665      */
 666     virtual bool get_sync_offset (pframes_t& /*offset*/) const { return false; }
 667
 668     /** Create a new thread suitable for running part of the buffer process
 669      * cycle (i.e. Realtime scheduling, memory allocation, etc. etc are all
 670      * correctly setup), with a stack size given in bytes by specified @param
 671      * stacksize. The thread will begin executing @param func, and will exit
 672      * when that function returns.
 673      */
 674     virtual int create_process_thread (boost::function<void()> func) = 0;
 675
 676     /** Wait for all processing threads to exit.
 677      *
 678      * Return zero on success, non-zero on failure.
 679      */
 680     virtual int join_process_threads () = 0;
 681
 682     /** Return true if execution context is in a backend thread
 683      */
 684     virtual bool in_process_thread () = 0;
 685
 686     /** Return the minimum stack size of audio threads in bytes
 687      */
 688     static size_t thread_stack_size () { return 100000; }
 689
 690     /** Return number of processing threads
 691      */
 692     virtual uint32_t process_thread_count () = 0;
 693
 694     virtual void update_latencies () = 0;
 695
 696     /** Set @param speed and @param position to the current speed and position
 697      * indicated by some transport sync signal.  Return whether the current
 698      * transport state is pending, or finalized.
 699      *
 700      * Derived classes only need implement this if they provide some way to
 701      * sync to a transport sync signal (e.g. Sony 9 Pin) that is not
 702      * handled by Ardour itself (LTC and MTC are both handled by Ardour).
 703      * The canonical example is JACK Transport.
 704      */
 705      virtual bool speed_and_position (double& speed, framepos_t& position) {
 706              speed = 0.0;
 707              position = 0;
 708              return false;
 709      }
 710
 711   protected:
 712      AudioBackendInfo&  _info;
 713      AudioEngine&        engine;
 714
 715      virtual int _start (bool for_latency_measurement) = 0;
 716 };
 717
 718 } // namespace
 719
 720 #endif /* __libardour_audiobackend_h__ */
 721