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