linuxsampler 2.3.1
LinuxSampler::AudioOutputDevice Class Referenceabstract

Abstract base class for audio output drivers in LinuxSampler. More...

#include <AudioOutputDevice.h>

Inheritance diagram for LinuxSampler::AudioOutputDevice:
LinuxSampler::Device

Classes

class  ParameterActive
 Device Parameter 'ACTIVE'. More...
 
class  ParameterChannels
 Device Parameters 'CHANNELS'. More...
 
class  ParameterSampleRate
 Device Parameter 'SAMPLERATE'. More...
 

Public Member Functions

virtual void Play ()=0
 Start playback of audio signal on the audio device.
 
virtual bool IsPlaying ()=0
 Returns true if the audio device is currently playing back.
 
virtual void Stop ()=0
 Stop playback of audio signal on the audio device.
 
virtual uint MaxSamplesPerCycle ()=0
 Maximum amount of sample points the implementing audio device will ever demand the sampler engines to write in one fragment cycle / period.
 
virtual uint SampleRate ()=0
 Playback samplerate the audio device uses.
 
virtual String Driver ()=0
 Return the audio output device driver name.
 
virtual AudioChannelCreateChannel (uint ChannelNr)=0
 Create new audio channel.
 
virtual float latency ()
 Might be optionally implemented by the deriving driver.
 
void Connect (Engine *pEngine)
 Connect given sampler engine to this audio output device.
 
void Disconnect (Engine *pEngine)
 Disconnect given sampler engine from this audio output device.
 
void ReconnectAll ()
 This method can or should be called by the deriving driver in case some fundamental parameter changed, especially if the values returned by MaxSamplesPerCycle() and SamplerRate() have changed, those are values which the sampler engines assume to be constant for the life time of an audio device !
 
AudioChannelChannel (uint ChannelIndex)
 Returns audio channel with index ChannelIndex or NULL if index out of bounds.
 
void AcquireChannels (uint Channels)
 This method will usually be called by the sampler engines that are connected to this audio device to inform the audio device how much audio channels the engine(s) need.
 
uint ChannelCount ()
 Returns the amount of audio channels (including the so called "mix channels") the device is currently providing.
 
std::map< String, DeviceCreationParameter * > DeviceParameters ()
 Returns all device parameter settings.
 
EffectChainAddSendEffectChain ()
 Add a chain of send effects to this AudioOutputDevice.
 
void RemoveSendEffectChain (uint iChain) throw (Exception)
 Remove the send effect chain given by iChain .
 
EffectChainSendEffectChain (uint iChain) const
 Returns send effect chain given by iChain or NULL if there's no such effect chain.
 
EffectChainSendEffectChainByID (uint iChainID) const
 Returns send effect chain with ID iChainID or NULL if there's no such effect chain.
 
uint SendEffectChainCount () const
 Returns amount of send effect chains this AudioOutputDevice currently provides.
 
EffectChainAddMasterEffectChain () DEPRECATED_API
 
void RemoveMasterEffectChain (uint iChain) DEPRECATED_API throw (Exception)
 
EffectChainMasterEffectChain (uint iChain) const DEPRECATED_API
 
uint MasterEffectChainCount () const DEPRECATED_API
 
virtual bool isAutonomousDevice ()
 Determines whether the device is an autonomous instance of some driver or not autonomous (that is bound to some other entity).
 
int deviceId () const
 Returns the numerical ID of this device instance.
 

Static Public Member Functions

static bool isAutonomousDriver ()
 Whether this is an autonomous device driver.
 

Protected Member Functions

 AudioOutputDevice (std::map< String, DeviceCreationParameter * > DriverParameters)
 
virtual ~AudioOutputDevice ()
 
int RenderAudio (uint Samples)
 This method should be called by the AudioOutputDevice descendant to let all connected engines proceed to render the given amount of sample points.
 
int RenderSilence (uint Samples)
 This can be called as an alternative to RenderAudio() for just writing silence to the audio output buffers and not calling the connected sampler engines for rendering audio, so to provide a method to stop playback if the used audio output system doesn't provide a better way.
 
void setDeviceId (int id)
 

Protected Attributes

SynchronizedConfig< std::set< Engine * > > Engines
 All sampler engines that are connected to the audio output device.
 
SynchronizedConfig< std::set< Engine * > >::Reader EnginesReader
 Audio thread access to Engines.
 
std::vector< AudioChannel * > Channels
 All audio channels of the audio output device. This is just a container; the descendant has to create channels by himself.
 
std::map< String, DeviceCreationParameter * > Parameters
 All device parameters.
 
std::vector< EffectChain * > vEffectChains
 
IDGeneratorEffectChainIDs
 

Friends

class AudioOutputDeviceFactory
 

Detailed Description

Abstract base class for audio output drivers in LinuxSampler.

This class will be derived by specialized classes which implement the connection to a specific audio output system (e.g. Alsa, Jack, CoreAudio).

Definition at line 54 of file AudioOutputDevice.h.

Constructor & Destructor Documentation

◆ AudioOutputDevice()

LinuxSampler::AudioOutputDevice::AudioOutputDevice ( std::map< String, DeviceCreationParameter * >  DriverParameters)
protected

◆ ~AudioOutputDevice()

virtual LinuxSampler::AudioOutputDevice::~AudioOutputDevice ( )
protectedvirtual

Member Function Documentation

◆ AcquireChannels()

void LinuxSampler::AudioOutputDevice::AcquireChannels ( uint  Channels)

This method will usually be called by the sampler engines that are connected to this audio device to inform the audio device how much audio channels the engine(s) need.

It's the responsibility of the audio device to offer that amount of audio channels - again: this is not an option this is a must! The engines will assume to be able to access those audio channels right after. If the audio driver is not able to offer that much channels, it can simply create mix channels which are then just mixed to the 'real' audio channels. See AudioChannel.h for details about channels and mix channels.

Parameters
Channels- amount of output channels required by a sampler engine
Exceptions
AudioOutputExceptionif desired amount of channels cannot be offered
See also
AudioChannel

◆ AddMasterEffectChain()

EffectChain * LinuxSampler::AudioOutputDevice::AddMasterEffectChain ( )
Deprecated:
This method will be removed, use AddSendEffectChain() instead!

◆ AddSendEffectChain()

EffectChain * LinuxSampler::AudioOutputDevice::AddSendEffectChain ( )

Add a chain of send effects to this AudioOutputDevice.

You actually have to add effects to that chain afterwards.

◆ Channel()

AudioChannel * LinuxSampler::AudioOutputDevice::Channel ( uint  ChannelIndex)

Returns audio channel with index ChannelIndex or NULL if index out of bounds.

◆ ChannelCount()

uint LinuxSampler::AudioOutputDevice::ChannelCount ( )

Returns the amount of audio channels (including the so called "mix channels") the device is currently providing.

◆ Connect()

void LinuxSampler::AudioOutputDevice::Connect ( Engine pEngine)

Connect given sampler engine to this audio output device.

The engine will be added to the Engines container of this audio device and the engine will also automatically be informed about the connection.

Parameters
pEngine- sampler engine

◆ CreateChannel()

virtual AudioChannel * LinuxSampler::AudioOutputDevice::CreateChannel ( uint  ChannelNr)
pure virtual

Create new audio channel.

This will be called by AcquireChannels(). Each driver must implement it.

◆ deviceId()

int LinuxSampler::Device::deviceId ( ) const
inherited

Returns the numerical ID of this device instance.

Every device instance has a unique ID among all devices of its category, that is e.g. every MIDI input device has a unique ID among all MIDI input devices and every audio output device has a unique ID among all audio output devices. The IDs are usually generated by the respective factory class.

◆ DeviceParameters()

std::map< String, DeviceCreationParameter * > LinuxSampler::AudioOutputDevice::DeviceParameters ( )

Returns all device parameter settings.

◆ Disconnect()

void LinuxSampler::AudioOutputDevice::Disconnect ( Engine pEngine)

Disconnect given sampler engine from this audio output device.

Removes given sampler engine reference from the Engines container of this audio device.

Parameters
pEngine- sampler engine

◆ Driver()

virtual String LinuxSampler::AudioOutputDevice::Driver ( )
pure virtual

Return the audio output device driver name.

◆ isAutonomousDevice()

virtual bool LinuxSampler::Device::isAutonomousDevice ( )
virtualinherited

Determines whether the device is an autonomous instance of some driver or not autonomous (that is bound to some other entity).

An autonomous device can be created and deleted separately. A non autonomous device only exists in the context of some entity, e.g. in the context of a host plugin (VST, AU, LV2, DSSI, ...) instance, and thus such a device cannot be created or deleted on its own.

By default, this method returns true unless overridden by the descendent.

◆ isAutonomousDriver()

static bool LinuxSampler::Device::isAutonomousDriver ( )
staticinherited

Whether this is an autonomous device driver.

See also
isAutonomousDevice()

◆ IsPlaying()

virtual bool LinuxSampler::AudioOutputDevice::IsPlaying ( )
pure virtual

Returns true if the audio device is currently playing back.

◆ latency()

virtual float LinuxSampler::AudioOutputDevice::latency ( )
virtual

Might be optionally implemented by the deriving driver.

If implemented, this method will return the current audio latency in seconds. The driver might measure the actual latency with timing functions to return the real latency.

If this method is not implemented / overridden by the descending driver, it will simply return the theoretical latency, that is MaxSamplesPerCycle() / SampleRate().

Currently this method is not used by the sampler itself. It can be used however for GUIs built on top of the sampler for example, to i.e. display the user the currently effective audio latency in real-time.

◆ MasterEffectChain()

EffectChain * LinuxSampler::AudioOutputDevice::MasterEffectChain ( uint  iChain) const
Deprecated:
This method will be removed, use SendEffectChain() instead!

◆ MasterEffectChainCount()

uint LinuxSampler::AudioOutputDevice::MasterEffectChainCount ( ) const
Deprecated:
This method will be removed, use SendEffectChainCount() instead!

◆ MaxSamplesPerCycle()

virtual uint LinuxSampler::AudioOutputDevice::MaxSamplesPerCycle ( )
pure virtual

Maximum amount of sample points the implementing audio device will ever demand the sampler engines to write in one fragment cycle / period.

Simple audio device drivers usually have a fixed fragment size, so those devices just would return the fragment size in this method.

Returns
max. amount of sample points ever

◆ Play()

virtual void LinuxSampler::AudioOutputDevice::Play ( )
pure virtual

Start playback of audio signal on the audio device.

It's the responsibility of the implementing audio device to call the RenderAudio(uint Samples) method of all connected engines. This will cause the engines to continue to render 'Samples' number of audio sample points and the engines will automatically add their audio signals to the audio buffers of the audio channels of this audio device. So the implementing audio device just has to access the buffers of it's audio channels.

Exceptions
AudioOutputExceptionif playback can not be started
See also
AudioChannel

◆ ReconnectAll()

void LinuxSampler::AudioOutputDevice::ReconnectAll ( )

This method can or should be called by the deriving driver in case some fundamental parameter changed, especially if the values returned by MaxSamplesPerCycle() and SamplerRate() have changed, those are values which the sampler engines assume to be constant for the life time of an audio device !

By forcing a re-connection with this method, the sampler engines are forced to update those informations metntioned above as well, avoiding crashes or other undesired misbehaviors in such circumstances.

◆ RemoveMasterEffectChain()

void LinuxSampler::AudioOutputDevice::RemoveMasterEffectChain ( uint  iChain)
throw (Exception
)
Deprecated:
This method will be removed, use RemoveSendEffectChain() instead!

◆ RemoveSendEffectChain()

void LinuxSampler::AudioOutputDevice::RemoveSendEffectChain ( uint  iChain)
throw (Exception
)

Remove the send effect chain given by iChain .

Exceptions
Exception- if given send effect chain doesn't exist

◆ RenderAudio()

int LinuxSampler::AudioOutputDevice::RenderAudio ( uint  Samples)
protected

This method should be called by the AudioOutputDevice descendant to let all connected engines proceed to render the given amount of sample points.

The engines will place their calculated audio data by themselfes into the buffers of the respective AudioChannel objects, so the implementing audio output device just has to copy the AudioChannel buffers to the output buffer(s) of its audio system.

Returns
0 on success or the last error return code of one engine

◆ RenderSilence()

int LinuxSampler::AudioOutputDevice::RenderSilence ( uint  Samples)
protected

This can be called as an alternative to RenderAudio() for just writing silence to the audio output buffers and not calling the connected sampler engines for rendering audio, so to provide a method to stop playback if the used audio output system doesn't provide a better way.

Returns
0 on success

◆ SampleRate()

virtual uint LinuxSampler::AudioOutputDevice::SampleRate ( )
pure virtual

Playback samplerate the audio device uses.

The sampler engines currently assume this to be a constant value for the whole life time of an instance of the implementing audio device.

Returns
sample rate in Hz

◆ SendEffectChain()

EffectChain * LinuxSampler::AudioOutputDevice::SendEffectChain ( uint  iChain) const

Returns send effect chain given by iChain or NULL if there's no such effect chain.

◆ SendEffectChainByID()

EffectChain * LinuxSampler::AudioOutputDevice::SendEffectChainByID ( uint  iChainID) const

Returns send effect chain with ID iChainID or NULL if there's no such effect chain.

◆ SendEffectChainCount()

uint LinuxSampler::AudioOutputDevice::SendEffectChainCount ( ) const

Returns amount of send effect chains this AudioOutputDevice currently provides.

◆ setDeviceId()

void LinuxSampler::Device::setDeviceId ( int  id)
protectedinherited

◆ Stop()

virtual void LinuxSampler::AudioOutputDevice::Stop ( )
pure virtual

Stop playback of audio signal on the audio device.

The implementing audio device will stop calling the RenderAudio() method of all connected engines and close it's connection to audio output system.

Friends And Related Symbol Documentation

◆ AudioOutputDeviceFactory

friend class AudioOutputDeviceFactory
friend

Definition at line 366 of file AudioOutputDevice.h.

Member Data Documentation

◆ Channels

std::vector<AudioChannel*> LinuxSampler::AudioOutputDevice::Channels
protected

All audio channels of the audio output device. This is just a container; the descendant has to create channels by himself.

Definition at line 332 of file AudioOutputDevice.h.

◆ EffectChainIDs

IDGenerator* LinuxSampler::AudioOutputDevice::EffectChainIDs
protected

Definition at line 335 of file AudioOutputDevice.h.

◆ Engines

SynchronizedConfig<std::set<Engine*> > LinuxSampler::AudioOutputDevice::Engines
protected

All sampler engines that are connected to the audio output device.

Definition at line 330 of file AudioOutputDevice.h.

◆ EnginesReader

SynchronizedConfig<std::set<Engine*>>::Reader LinuxSampler::AudioOutputDevice::EnginesReader
protected

Audio thread access to Engines.

Definition at line 331 of file AudioOutputDevice.h.

◆ Parameters

std::map<String,DeviceCreationParameter*> LinuxSampler::AudioOutputDevice::Parameters
protected

All device parameters.

Definition at line 333 of file AudioOutputDevice.h.

◆ vEffectChains

std::vector<EffectChain*> LinuxSampler::AudioOutputDevice::vEffectChains
protected

Definition at line 334 of file AudioOutputDevice.h.


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