#include <audio_backend.h>

Inheritance diagram for ARDOUR::AudioBackend:

Classes
struct	DeviceStatus

Public Member Functions
	AudioBackend (AudioEngine &e, AudioBackendInfo &i)

virtual	~AudioBackend ()

AudioBackendInfo &	info () const

virtual std::string	name () const =0

virtual bool	is_realtime () const =0

virtual bool	requires_driver_selection () const

virtual std::vector< std::string >	enumerate_drivers () const

virtual int	set_driver (const std::string &)

virtual std::vector< DeviceStatus >	enumerate_devices () const =0

virtual std::vector< float >	available_sample_rates (const std::string &device) const =0

virtual float	default_sample_rate () const

virtual std::vector< uint32_t >	available_buffer_sizes (const std::string &device) const =0

virtual uint32_t	default_buffer_size (const std::string &device) const

virtual uint32_t	available_input_channel_count (const std::string &device) const =0

virtual uint32_t	available_output_channel_count (const std::string &device) const =0

virtual bool	can_change_sample_rate_when_running () const =0

virtual bool	can_change_buffer_size_when_running () const =0

virtual int	set_device_name (const std::string &)=0

virtual int	drop_device ()

virtual int	set_sample_rate (float)=0

virtual int	set_buffer_size (uint32_t)=0

virtual int	set_interleaved (bool yn)=0

virtual int	set_input_channels (uint32_t)=0

virtual int	set_output_channels (uint32_t)=0

virtual int	set_systemic_input_latency (uint32_t)=0

virtual int	set_systemic_output_latency (uint32_t)=0

virtual int	set_systemic_midi_input_latency (std::string const, uint32_t)=0

virtual int	set_systemic_midi_output_latency (std::string const, uint32_t)=0

virtual std::string	device_name () const =0

virtual float	sample_rate () const =0

virtual uint32_t	buffer_size () const =0

virtual bool	interleaved () const =0

virtual uint32_t	input_channels () const =0

virtual uint32_t	output_channels () const =0

virtual uint32_t	systemic_input_latency () const =0

virtual uint32_t	systemic_output_latency () const =0

virtual uint32_t	systemic_midi_input_latency (std::string const) const =0

virtual uint32_t	systemic_midi_output_latency (std::string const) const =0

virtual std::string	driver_name () const

virtual std::string	control_app_name () const =0

virtual void	launch_control_app ()=0

virtual std::vector< std::string >	enumerate_midi_options () const =0

virtual int	set_midi_option (const std::string &option)=0

virtual std::string	midi_option () const =0

virtual std::vector< DeviceStatus >	enumerate_midi_devices () const =0

virtual int	set_midi_device_enabled (std::string const, bool)=0

virtual bool	midi_device_enabled (std::string const) const =0

virtual bool	can_set_systemic_midi_latencies () const =0

int	start (bool for_latency_measurement=false)

virtual int	stop ()=0

virtual int	reset_device ()=0

virtual int	freewheel (bool start_stop)=0

virtual float	dsp_load () const =0

virtual void	transport_start ()

virtual void	transport_stop ()

virtual TransportState	transport_state () const

virtual void	transport_locate (framepos_t)

virtual framepos_t	transport_frame () const

virtual int	set_time_master (bool)

virtual int	usecs_per_cycle () const

virtual size_t	raw_buffer_size (DataType t)=0

virtual framepos_t	sample_time ()=0

virtual framepos_t	sample_time_at_cycle_start ()=0

virtual pframes_t	samples_since_cycle_start ()=0

virtual bool	get_sync_offset (pframes_t &) const

virtual int	create_process_thread (boost::function< void()> func)=0

virtual int	join_process_threads ()=0

virtual bool	in_process_thread ()=0

virtual uint32_t	process_thread_count ()=0

virtual void	update_latencies ()=0

virtual bool	speed_and_position (double &speed, framepos_t &position)

Public Member Functions inherited from ARDOUR::PortEngine
	PortEngine (PortManager &pm)

virtual	~PortEngine ()

virtual void *	private_handle () const =0

virtual const std::string &	my_name () const =0

virtual bool	available () const =0

virtual uint32_t	port_name_size () const =0

virtual int	set_port_name (PortHandle port, const std::string &name)=0

virtual std::string	get_port_name (PortHandle) const =0

virtual int	get_port_property (PortHandle, const std::string &key, std::string &value, std::string &type) const

virtual PortHandle	get_port_by_name (const std::string &) const =0

virtual int	get_ports (const std::string &port_name_pattern, DataType type, PortFlags flags, std::vector< std::string > &ports) const =0

virtual DataType	port_data_type (PortHandle port) const =0

virtual PortHandle	register_port (const std::string &shortname, ARDOUR::DataType type, ARDOUR::PortFlags flags)=0

virtual void	unregister_port (PortHandle)=0

virtual int	connect (const std::string &src, const std::string &dst)=0

virtual int	disconnect (const std::string &src, const std::string &dst)=0

virtual int	connect (PortHandle src, const std::string &dst)=0

virtual int	disconnect (PortHandle src, const std::string &dst)=0

virtual int	disconnect_all (PortHandle port)=0

virtual bool	connected (PortHandle port, bool process_callback_safe=true)=0

virtual bool	connected_to (PortHandle, const std::string &name, bool process_callback_safe=true)=0

virtual bool	physically_connected (PortHandle port, bool process_callback_safe=true)=0

virtual int	get_connections (PortHandle port, std::vector< std::string > &names, bool process_callback_safe=true)=0

virtual int	midi_event_get (pframes_t &timestamp, size_t &size, uint8_t *buf, void port_buffer, uint32_t event_index)=0

virtual int	midi_event_put (void port_buffer, pframes_t timestamp, const uint8_t buffer, size_t size)=0

virtual uint32_t	get_midi_event_count (void *port_buffer)=0

virtual void	midi_clear (void *port_buffer)=0

virtual bool	can_monitor_input () const =0

virtual int	request_input_monitoring (PortHandle port, bool yn)=0

virtual int	ensure_input_monitoring (PortHandle port, bool yn)=0

virtual bool	monitoring_input (PortHandle port)=0

virtual void	set_latency_range (PortHandle port, bool for_playback, LatencyRange r)=0

virtual LatencyRange	get_latency_range (PortHandle port, bool for_playback)=0

virtual bool	port_is_physical (PortHandle port) const =0

virtual void	get_physical_outputs (DataType type, std::vector< std::string > &names)=0

virtual void	get_physical_inputs (DataType type, std::vector< std::string > &names)=0

virtual ChanCount	n_physical_outputs () const =0

virtual ChanCount	n_physical_inputs () const =0

virtual void *	get_buffer (PortHandle, pframes_t)=0

Static Public Member Functions
static size_t	thread_stack_size ()

Protected Member Functions
virtual int	_start (bool for_latency_measurement)=0

Protected Attributes
AudioBackendInfo &	_info

AudioEngine &	engine

Protected Attributes inherited from ARDOUR::PortEngine
PortManager &	manager

Additional Inherited Members
Public Types inherited from ARDOUR::PortEngine
typedef void *	PortHandle

Detailed Description

Definition at line 83 of file audio_backend.h.

Constructor & Destructor Documentation

ARDOUR::AudioBackend::AudioBackend	(	AudioEngine &	e,
		AudioBackendInfo &	i
	)

inline

Definition at line 86 of file audio_backend.h.

virtual ARDOUR::AudioBackend::~AudioBackend ( )

inlinevirtual

Definition at line 87 of file audio_backend.h.

Member Function Documentation

virtual int ARDOUR::AudioBackend::_start ( bool for_latency_measurement )

protectedpure virtual

virtual std::vector<uint32_t> ARDOUR::AudioBackend::available_buffer_sizes ( const std::string & device ) const

pure virtual

Returns a collection of uint32 identifying buffer sizes that are potentially usable with the hardware identified by

Parameters

device. Any of these values may be supplied in other calls to this backend as the desired buffer size to use with the name device, but the requested buffer size may turn out to be unavailable, or become invalid at any time.

virtual uint32_t ARDOUR::AudioBackend::available_input_channel_count ( const std::string & device ) const

pure virtual

Returns the maximum number of input channels that are potentially usable with the hardware identified by

Parameters

device. Any number from 1 to the value returned may be supplied in other calls to this backend as the input channel count to use with the name device, but the requested count may turn out to be unavailable, or become invalid at any time.

virtual uint32_t ARDOUR::AudioBackend::available_output_channel_count ( const std::string & device ) const

pure virtual

Returns the maximum number of output channels that are potentially usable with the hardware identified by

Parameters

device. Any number from 1 to the value returned may be supplied in other calls to this backend as the output channel count to use with the name device, but the requested count may turn out to be unavailable, or become invalid at any time.

virtual std::vector<float> ARDOUR::AudioBackend::available_sample_rates ( const std::string & device ) const

pure virtual

Returns a collection of float identifying sample rates that are potentially usable with the hardware identified by

Parameters

device. Any of these values may be supplied in other calls to this backend as the desired sample rate to use with the name device, but the requested sample rate may turn out to be unavailable, or become invalid at any time.

virtual uint32_t ARDOUR::AudioBackend::buffer_size ( ) const

pure virtual

virtual bool ARDOUR::AudioBackend::can_change_buffer_size_when_running ( ) const

pure virtual

virtual bool ARDOUR::AudioBackend::can_change_sample_rate_when_running ( ) const

pure virtual

virtual bool ARDOUR::AudioBackend::can_set_systemic_midi_latencies ( ) const

pure virtual

if backend supports systemic_midi_[in|ou]tput_latency()

virtual std::string ARDOUR::AudioBackend::control_app_name ( ) const

pure virtual

Return the name of a control application for the selected/in-use device. If no such application exists, or if no device has been selected or is in-use, return an empty string.

virtual int ARDOUR::AudioBackend::create_process_thread ( boost::function< void()> func )

pure virtual

Create a new thread suitable for running part of the buffer process cycle (i.e. Realtime scheduling, memory allocation, etc. etc are all correctly setup), with a stack size given in bytes by specified

Parameters

stacksize.	The thread will begin executing
func,and	will exit when that function returns.

virtual uint32_t ARDOUR::AudioBackend::default_buffer_size ( const std::string & device ) const

inlinevirtual

Definition at line 189 of file audio_backend.h.

virtual float ARDOUR::AudioBackend::default_sample_rate ( ) const

inlinevirtual

Definition at line 170 of file audio_backend.h.

virtual std::string ARDOUR::AudioBackend::device_name ( ) const

pure virtual

virtual std::string ARDOUR::AudioBackend::driver_name ( ) const

inlinevirtual

override this if this implementation returns true from requires_driver_selection()

Definition at line 299 of file audio_backend.h.

virtual int ARDOUR::AudioBackend::drop_device ( )

inlinevirtual

Deinitialize and destroy current device

Definition at line 236 of file audio_backend.h.

virtual float ARDOUR::AudioBackend::dsp_load ( ) const

pure virtual

return the fraction of the time represented by the current buffer size that is being used for each buffer process cycle, as a value from 0.0 to 1.0

E.g. if the buffer size represents 5msec and current processing takes 1msec, the returned value should be 0.2.

Implementations can feel free to smooth the values returned over time (e.g. high pass filtering, or its equivalent).

virtual std::vector<DeviceStatus> ARDOUR::AudioBackend::enumerate_devices ( ) const

pure virtual

Returns a collection of DeviceStatuses identifying devices discovered by this backend since the start of the process.

Any of the names in each DeviceStatus may be used to identify a device in other calls to the backend, though any of them may become invalid at any time.

virtual std::vector<std::string> ARDOUR::AudioBackend::enumerate_drivers ( ) const

inlinevirtual

If the return value of requires_driver_selection() is true, then this function can return the list of known driver names.

If the return value of requires_driver_selection() is false, then this function should not be called. If it is called its return value is an empty vector of strings.

Definition at line 126 of file audio_backend.h.

virtual std::vector<DeviceStatus> ARDOUR::AudioBackend::enumerate_midi_devices ( ) const

pure virtual

Detailed MIDI device list - if available

virtual std::vector<std::string> ARDOUR::AudioBackend::enumerate_midi_options ( ) const

pure virtual

virtual int ARDOUR::AudioBackend::freewheel ( bool start_stop )

pure virtual

While remaining connected to the device, and without changing its configuration, start (or stop) calling the process_callback() of

Parameters

engine without waiting for the device. Once process_callback() has returned, it will be called again immediately, thus allowing for faster-than-realtime processing.

All registered ports remain in existence and all connections remain unaltered. However, any physical ports should NOT be used by the process_callback() during freewheeling - the data behaviour is undefined.

If

Parameters

start_stop	is true, begin this behaviour; otherwise cease this behaviour if it currently occuring, and return to calling process_callback() of
engine	by waiting for the device.

Return zero on success, non-zero otherwise.

virtual bool ARDOUR::AudioBackend::get_sync_offset ( pframes_t & ) const

inlinevirtual

Return true if it possible to determine the offset in samples of the first video frame that starts within the current buffer process cycle, measured from the first sample of the cycle. If returning true, set

Parameters

offset to that offset.

Eg. if it can be determined that the first video frame within the cycle starts 28 samples after the first sample of the cycle, then this method should return true and set

Parameters

offset to 28.

May be impossible to support outside of JACK, which has specific support (in some cases, hardware support) for this feature.

Can ONLY be called from within a process() callback tree (which implies that it can only be called by a process thread)

Definition at line 510 of file audio_backend.h.

virtual bool ARDOUR::AudioBackend::in_process_thread ( )

pure virtual

Return true if execution context is in a backend thread

AudioBackendInfo& ARDOUR::AudioBackend::info ( ) const

inline

Return the AudioBackendInfo object from which this backend was constructed.

Definition at line 92 of file audio_backend.h.

virtual uint32_t ARDOUR::AudioBackend::input_channels ( ) const

pure virtual

virtual bool ARDOUR::AudioBackend::interleaved ( ) const

pure virtual

virtual bool ARDOUR::AudioBackend::is_realtime ( ) const

pure virtual

Return true if the callback from the underlying mechanism/API (CoreAudio, JACK, ASIO etc.) occurs in a thread subject to realtime constraints. Return false otherwise.

virtual int ARDOUR::AudioBackend::join_process_threads ( )

pure virtual

Wait for all processing threads to exit.

Return zero on success, non-zero on failure.

virtual void ARDOUR::AudioBackend::launch_control_app ( )

pure virtual

Launch the control app for the currently in-use or selected device. May do nothing if the control app is undefined or cannot be launched.

virtual bool ARDOUR::AudioBackend::midi_device_enabled ( std::string const ) const

pure virtual

query if a midi-device is enabled

virtual std::string ARDOUR::AudioBackend::midi_option ( ) const

pure virtual

virtual std::string ARDOUR::AudioBackend::name ( ) const

pure virtual

Return the name of this backend.

Should use a well-known, unique term. Expected examples might include "JACK", "CoreAudio", "ASIO" etc.

virtual uint32_t ARDOUR::AudioBackend::output_channels ( ) const

pure virtual

virtual uint32_t ARDOUR::AudioBackend::process_thread_count ( )

pure virtual

Return number of processing threads

virtual size_t ARDOUR::AudioBackend::raw_buffer_size ( DataType t )

pure virtual

virtual bool ARDOUR::AudioBackend::requires_driver_selection ( ) const

inlinevirtual

Return true if this backend requires the selection of a "driver" before any device can be selected. Return false otherwise.

Intended mainly to differentiate between meta-APIs like JACK which can still expose different backends (such as ALSA or CoreAudio or FFADO or netjack) and those like ASIO or CoreAudio which do not.

Definition at line 117 of file audio_backend.h.

virtual int ARDOUR::AudioBackend::reset_device ( )

pure virtual

Reset device.

Return zero if successful, negative values on error

virtual float ARDOUR::AudioBackend::sample_rate ( ) const

pure virtual

virtual framepos_t ARDOUR::AudioBackend::sample_time ( )

pure virtual

return the time according to the sample clock in use, measured in samples since an arbitrary zero time in the past. The value should increase monotonically and linearly, without interruption from any source (including CPU frequency scaling).

It is extremely likely that any implementation will use a DLL, since this function can be called from any thread, at any time, and must be able to accurately determine the correct sample time.

Can be called from any thread.

virtual framepos_t ARDOUR::AudioBackend::sample_time_at_cycle_start ( )

pure virtual

Return the time according to the sample clock in use when the most recent buffer process cycle began. Can be called from any thread.

Implements ARDOUR::PortEngine.

virtual pframes_t ARDOUR::AudioBackend::samples_since_cycle_start ( )

pure virtual

Return the time since the current buffer process cycle started, in samples, according to the sample clock in use.

Can ONLY be called from within a process() callback tree (which implies that it can only be called by a process thread)

virtual int ARDOUR::AudioBackend::set_buffer_size ( uint32_t )

pure virtual

Set the buffer size to be used.

The device is assumed to use a double buffering scheme, so that one buffer's worth of data can be processed by hardware while software works on the other buffer. All known suitable audio APIs support this model (though ALSA allows for alternate numbers of buffers, and CoreAudio doesn't directly expose the concept).

virtual int ARDOUR::AudioBackend::set_device_name ( const std::string & )

pure virtual

Set the name of the device to be used

virtual int ARDOUR::AudioBackend::set_driver ( const std::string & )

inlinevirtual

Returns zero if the backend can successfully use

Parameters

name	as the driver, non-zero otherwise.

Should not be used unless the backend returns true from requires_driver_selection()

Definition at line 134 of file audio_backend.h.

virtual int ARDOUR::AudioBackend::set_input_channels ( uint32_t )

pure virtual

Set the number of input channels that should be used

virtual int ARDOUR::AudioBackend::set_interleaved ( bool yn )

pure virtual

Set the preferred underlying hardware data layout. If

Parameters

yn	is true, then the hardware will interleave samples for successive channels; otherwise, the hardware will store samples for a single channel contiguously.

Setting this does not change the fact that all data streams to and from Ports are mono (essentially, non-interleaved)

virtual int ARDOUR::AudioBackend::set_midi_device_enabled	(	std::string	const,
		bool
	)

pure virtual

mark a midi-devices as enabled

virtual int ARDOUR::AudioBackend::set_midi_option ( const std::string & option )

pure virtual

virtual int ARDOUR::AudioBackend::set_output_channels ( uint32_t )

pure virtual

Set the number of output channels that should be used

virtual int ARDOUR::AudioBackend::set_sample_rate ( float )

pure virtual

Set the sample rate to be used

virtual int ARDOUR::AudioBackend::set_systemic_input_latency ( uint32_t )

pure virtual

Set the (additional) input latency that cannot be determined via the implementation's underlying code (e.g. latency from external D-A/D-A converters. Units are samples.

virtual int ARDOUR::AudioBackend::set_systemic_midi_input_latency	(	std::string	const,
		uint32_t
	)

pure virtual

Set the (additional) input latency for a specific midi device, or if the identifier is empty, apply to all midi devices.

virtual int ARDOUR::AudioBackend::set_systemic_midi_output_latency	(	std::string	const,
		uint32_t
	)

pure virtual

Set the (additional) output latency for a specific midi device, or if the identifier is empty, apply to all midi devices.

virtual int ARDOUR::AudioBackend::set_systemic_output_latency ( uint32_t )

pure virtual

Set the (additional) output latency that cannot be determined via the implementation's underlying code (e.g. latency from external D-A/D-A converters. Units are samples.

virtual int ARDOUR::AudioBackend::set_time_master ( bool )

inlinevirtual

If

Parameters

yn	is true, become the time master for any inter-application transport timebase, otherwise cease to be the time master for the same.

Return zero on success, non-zero otherwise

JACK is the only currently known audio API with the concept of a shared transport timebase.

Definition at line 462 of file audio_backend.h.

virtual bool ARDOUR::AudioBackend::speed_and_position	(	double &	speed,
		framepos_t &	position
	)

inlinevirtual

Set

Parameters

speed	and
position	to the current speed and position indicated by some transport sync signal. Return whether the current transport state is pending, or finalized.

Derived classes only need implement this if they provide some way to sync to a transport sync signal (e.g. Sony 9 Pin) that is not handled by Ardour itself (LTC and MTC are both handled by Ardour). The canonical example is JACK Transport.

Definition at line 549 of file audio_backend.h.

int ARDOUR::AudioBackend::start ( bool for_latency_measurement = false )

inline

Start using the device named in the most recent call to set_device(), with the parameters set by various the most recent calls to set_sample_rate() etc. etc.

At some undetermined time after this function is successfully called, the backend will start calling the ::process_callback() method of the AudioEngine referenced by

Parameters

engine.	These calls will occur in a thread created by and/or under the control of the backend.
for_latency_measurement	if true, the device is being started to carry out latency measurements and the backend should this take care to return latency numbers that do not reflect any existing systemic latency settings.

Return zero if successful, negative values otherwise.

Why is this non-virtual but ::_start() is virtual ? Virtual methods with default parameters create possible ambiguity because a derived class may implement the same method with a different type or value of default parameter.

So we make this non-virtual method to avoid possible overrides of default parameters. See Scott Meyers or other books on C++ to understand this pattern, or possibly just this:

http://stackoverflow.com/questions/12139786/good-pratice-default-arguments-for-pure-virtual-method

Definition at line 377 of file audio_backend.h.

virtual int ARDOUR::AudioBackend::stop ( )

pure virtual

Stop using the device currently in use.

If the function is successfully called, no subsequent calls to the process_callback() of

Parameters

engine will be made after the function returns, until parameters are reset and start() are called again.

The backend is considered to be un-configured after a successful return, and requires calls to set hardware parameters before it can be start()-ed again. See pause() for a way to avoid this. stop() should only be used when reconfiguration is required OR when there are no plans to use the backend in the future with a reconfiguration.

Return zero if successful, 1 if the device is not in use, negative values on error

virtual uint32_t ARDOUR::AudioBackend::systemic_input_latency ( ) const

pure virtual

virtual uint32_t ARDOUR::AudioBackend::systemic_midi_input_latency ( std::string const ) const

pure virtual

virtual uint32_t ARDOUR::AudioBackend::systemic_midi_output_latency ( std::string const ) const

pure virtual

virtual uint32_t ARDOUR::AudioBackend::systemic_output_latency ( ) const

pure virtual

static size_t ARDOUR::AudioBackend::thread_stack_size ( )

inlinestatic

Return the minimum stack size of audio threads in bytes

Definition at line 532 of file audio_backend.h.

virtual framepos_t ARDOUR::AudioBackend::transport_frame ( ) const

inlinevirtual

Return the current transport location, in samples measured from the origin (defined by the transport time master)

Definition at line 452 of file audio_backend.h.

virtual void ARDOUR::AudioBackend::transport_locate ( framepos_t )

inlinevirtual

Attempt to locate the transport to

Parameters

pos

Definition at line 448 of file audio_backend.h.

virtual void ARDOUR::AudioBackend::transport_start ( )

inlinevirtual

Attempt to change the transport state to TransportRolling.

Definition at line 439 of file audio_backend.h.

virtual TransportState ARDOUR::AudioBackend::transport_state ( ) const

inlinevirtual

return the current transport state

Definition at line 445 of file audio_backend.h.

virtual void ARDOUR::AudioBackend::transport_stop ( )

inlinevirtual

Attempt to change the transport state to TransportStopped.

Definition at line 442 of file audio_backend.h.

virtual void ARDOUR::AudioBackend::update_latencies ( )

pure virtual

virtual int ARDOUR::AudioBackend::usecs_per_cycle ( ) const

inlinevirtual

Definition at line 464 of file audio_backend.h.

Member Data Documentation

AudioBackendInfo& ARDOUR::AudioBackend::_info

protected

Definition at line 556 of file audio_backend.h.

AudioEngine& ARDOUR::AudioBackend::engine

protected

Definition at line 557 of file audio_backend.h.

The documentation for this class was generated from the following file:

/usr/local/music/src/ardour/4.0/libs/ardour/ardour/audio_backend.h

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation