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