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