linuxsampler 2.3.1
LinuxSampler::DeviceCreationParameter Class Referenceabstract

Abstract base class for parameters at driver instanciation time. More...

#include <DeviceParameter.h>

Inheritance diagram for LinuxSampler::DeviceCreationParameter:
LinuxSampler::DeviceRuntimeParameter LinuxSampler::DeviceCreationParameterBool LinuxSampler::DeviceCreationParameterFloat LinuxSampler::DeviceCreationParameterInt LinuxSampler::DeviceCreationParameterString LinuxSampler::DeviceCreationParameterStrings LinuxSampler::AudioOutputDevice::ParameterActive LinuxSampler::MidiInputDevice::ParameterActive LinuxSampler::AudioOutputDevice::ParameterChannels LinuxSampler::AudioOutputDevice::ParameterSampleRate LinuxSampler::MidiInputDevice::ParameterPorts

Public Member Functions

 DeviceCreationParameter (void)
 Constructor.
 
virtual bool Mandatory ()=0
 Whether the parameter must be supplied by the user at device creation time.
 
virtual optional< StringDepends ()
 Might return a comma separated list of parameter names this parameter depends on.
 
virtual std::map< String, DeviceCreationParameter * > DependsAsParameters ()=0
 Might return a unique key-value pair list (map) reflecting the dependencies of this parameter to other parameters.
 
virtual optional< StringDefault ()
 Might return a default value for this parameter.
 
virtual optional< StringDefault (std::map< String, String > Parameters)=0
 Might return a default value for this parameter.
 
virtual optional< StringRangeMin ()
 Might return a minimum value for this parameter.
 
virtual optional< StringRangeMin (std::map< String, String > Parameters)=0
 Might return a minimum value for this parameter.
 
virtual optional< StringRangeMax ()
 Might return a maximum value for this parameter.
 
virtual optional< StringRangeMax (std::map< String, String > Parameters)=0
 Might return a maximum value for this parameter.
 
virtual optional< StringPossibilities ()
 Might return a comma separated list as String with possible values for this parameter.
 
virtual optional< StringPossibilities (std::map< String, String > Parameters)=0
 Might return a comma separated list as String with possible values for this parameter.
 
void Attach (Device *pDevice)
 Sets the internal device pointer to a specific device (driver instance) for this parameter object.
 
virtual String Type ()=0
 Some name reflecting the parameter's value type, like "BOOL, "INT", "FLOAT", "STRING", "STRINGS".
 
virtual String Description ()=0
 A human readable description, explaining the exact purpose of the driver parameter.
 
virtual bool Fix ()=0
 Whether the parameter is read only.
 
virtual bool Multiplicity ()=0
 Whether the parameter only allows to set one scalar value, or if true is returned here, the parameter allows to manage a list of values instead.
 
virtual String Value ()=0
 The current value of this parameter (encoded as String).
 
virtual void SetValue (String val) throw (Exception) =0
 Alter the parameter with the value given by val.
 

Protected Attributes

DevicepDevice
 

Detailed Description

Abstract base class for parameters at driver instanciation time.

Device "creation" parameters are special parameters, that are meant to be only set when a device (driver instance) is created. After device creation those parameters act as read only parameters. See DeviceRuntimeParameter for a discussion about this topic.

In addition to "runtime" parameters, "creation" parameters also handle additional meta informations required in the specific situations of creating a device (driver instance). For example "creation" parameters might indicate whether they MUST be provided explicitly ( Mandatory() ) by the user (i.e. a parameter "CARD" selecting a specific sound card) for being able to create an instance of the driver. And "creation" parameters might indicate being dependent to other parameters, i.e. a parameter "SAMPLERATE" might depend on a parameter "CARD", to be able to actually provide a list of meaningful possibilities for sample rates the respective sound card supports.

Definition at line 580 of file DeviceParameter.h.

Constructor & Destructor Documentation

◆ DeviceCreationParameter()

LinuxSampler::DeviceCreationParameter::DeviceCreationParameter ( void  )
inline

Constructor.

Definition at line 583 of file DeviceParameter.h.

Member Function Documentation

◆ Attach()

void LinuxSampler::DeviceCreationParameter::Attach ( Device pDevice)
inline

Sets the internal device pointer to a specific device (driver instance) for this parameter object.

Descendants usually use that internal pointer to interact with their specific driver implementation class.

Definition at line 751 of file DeviceParameter.h.

◆ Default() [1/2]

virtual optional< String > LinuxSampler::DeviceCreationParameter::Default ( )
virtual

Might return a default value for this parameter.

The default value will be used if the user does not provide a specific value for this parameter at device creation time. If the parameter does not have a reasonable default value, it will return optional<String>::nothing.

This method already provides an implementation, which usually is not overridden by descendants. A descendant would rather implement the other Default() method taking arguments.

◆ Default() [2/2]

virtual optional< String > LinuxSampler::DeviceCreationParameter::Default ( std::map< String, String Parameters)
pure virtual

Might return a default value for this parameter.

The default value will be used if the user does not provide a specific value for this parameter at device creation time.

This method must be implemented by descendants. If the parameter does not have a reasonable default value, it should return optional<String>::nothing.

As arguments, the parameters are passed to this method automatically, which the user already provided. For example a parameter "CARD" the user already did set for selecting a specific sound card. So such arguments resolve dependencies of this parameter.

Parameters
Parameters- other parameters which the user already supplied

Implemented in LinuxSampler::DeviceCreationParameterBool, LinuxSampler::DeviceCreationParameterInt, LinuxSampler::DeviceCreationParameterFloat, LinuxSampler::DeviceCreationParameterString, and LinuxSampler::DeviceCreationParameterStrings.

◆ Depends()

virtual optional< String > LinuxSampler::DeviceCreationParameter::Depends ( )
virtual

Might return a comma separated list of parameter names this parameter depends on.

See this class's introduction about a discussion of parameters with dependencies. If this method returns optional<String>::nothing, then it does not have any dependencies to other parameters.

This method already provides an implementation, which usually is not overridden by descendants. A descendant would rather implement DependsAsParameters() instead.

See also
DependsAsParameters()

◆ DependsAsParameters()

virtual std::map< String, DeviceCreationParameter * > LinuxSampler::DeviceCreationParameter::DependsAsParameters ( )
pure virtual

Might return a unique key-value pair list (map) reflecting the dependencies of this parameter to other parameters.

Each entry in the map consists of a key-value pair, the key being the parameter name of the respective dependent parameter, and the value being an instance of the dependency parameter of that name.

A descendant MUST implement this method, informing about its dependencies. If the parameter does not have any dependencies it should return an empty map.

See this class's introduction about a discussion of parameters with dependencies.

Implemented in LinuxSampler::AudioOutputDevice::ParameterActive, LinuxSampler::AudioOutputDevice::ParameterSampleRate, LinuxSampler::AudioOutputDevice::ParameterChannels, LinuxSampler::MidiInputDevice::ParameterActive, and LinuxSampler::MidiInputDevice::ParameterPorts.

◆ Description()

virtual String LinuxSampler::DeviceRuntimeParameter::Description ( )
pure virtualinherited

◆ Fix()

virtual bool LinuxSampler::DeviceRuntimeParameter::Fix ( )
pure virtualinherited

Whether the parameter is read only.

Not to be confused with "creation" parameters! A driver parameter which returns true here can never be set or altered at any time. Not even at instanciation time of the driver! A typical example would be a parameter "SAMPLERATE" for a specific sound card, where the specific sound card does not allow to switch the sound card's sample rate in any way. Yet the value returned by the parameter (read only) might be different, depending on the actual sound card the user selected with the audio driver.

Implemented in LinuxSampler::AudioChannel::ParameterName, LinuxSampler::AudioChannel::ParameterIsMixChannel, LinuxSampler::AudioChannel::ParameterMixChannelDestination, LinuxSampler::AudioOutputDevice::ParameterActive, LinuxSampler::AudioOutputDevice::ParameterSampleRate, LinuxSampler::AudioOutputDevice::ParameterChannels, LinuxSampler::MidiInputDevice::ParameterActive, LinuxSampler::MidiInputDevice::ParameterPorts, and LinuxSampler::MidiInputPort::ParameterName.

◆ Mandatory()

virtual bool LinuxSampler::DeviceCreationParameter::Mandatory ( )
pure virtual

Whether the parameter must be supplied by the user at device creation time.

If this method return false, then the parameter is optional

Implemented in LinuxSampler::AudioOutputDevice::ParameterActive, LinuxSampler::AudioOutputDevice::ParameterSampleRate, LinuxSampler::AudioOutputDevice::ParameterChannels, LinuxSampler::MidiInputDevice::ParameterActive, and LinuxSampler::MidiInputDevice::ParameterPorts.

◆ Multiplicity()

virtual bool LinuxSampler::DeviceRuntimeParameter::Multiplicity ( )
pure virtualinherited

Whether the parameter only allows to set one scalar value, or if true is returned here, the parameter allows to manage a list of values instead.

A typical example of multiplicity parameter is i.e. a "ROUTING" parameter, that would allow a user to interconnect the sampler with other apps and devices with drivers that support such concepts (like JACK and ALSA MIDI do).

Implemented in LinuxSampler::DeviceRuntimeParameterBool, LinuxSampler::DeviceRuntimeParameterInt, LinuxSampler::DeviceRuntimeParameterFloat, LinuxSampler::DeviceRuntimeParameterString, LinuxSampler::DeviceRuntimeParameterStrings, LinuxSampler::DeviceCreationParameterBool, LinuxSampler::DeviceCreationParameterInt, LinuxSampler::DeviceCreationParameterFloat, LinuxSampler::DeviceCreationParameterString, and LinuxSampler::DeviceCreationParameterStrings.

◆ Possibilities() [1/2]

virtual optional< String > LinuxSampler::DeviceCreationParameter::Possibilities ( )
virtual

Might return a comma separated list as String with possible values for this parameter.

If the parameter does not have reasonable, specific possible values, it will return optional<String>::nothing.

This method already provides an implementation, which usually is not overridden by descendants. A descendant would rather implement the other Possibilities() method taking arguments.

Implements LinuxSampler::DeviceRuntimeParameter.

◆ Possibilities() [2/2]

virtual optional< String > LinuxSampler::DeviceCreationParameter::Possibilities ( std::map< String, String Parameters)
pure virtual

Might return a comma separated list as String with possible values for this parameter.

This method must be implemented by descendants. If the parameter does not have reasonable, specific possible values, it should return optional<String>::nothing.

As arguments, the parameters are passed to this method automatically, which the user already provided. For example a parameter "CARD" the user already did set for selecting a specific sound card. So such arguments resolve dependencies of this parameter.

Parameters
Parameters- other parameters which the user already supplied

Implemented in LinuxSampler::DeviceCreationParameterBool, LinuxSampler::DeviceCreationParameterInt, LinuxSampler::DeviceCreationParameterFloat, LinuxSampler::DeviceCreationParameterString, and LinuxSampler::DeviceCreationParameterStrings.

◆ RangeMax() [1/2]

virtual optional< String > LinuxSampler::DeviceCreationParameter::RangeMax ( )
virtual

Might return a maximum value for this parameter.

If the parameter does not have a reasonable maximum value, it will return optional<String>::nothing.

This method already provides an implementation, which usually is not overridden by descendants. A descendant would rather implement the other RangeMax() method taking arguments.

Implements LinuxSampler::DeviceRuntimeParameter.

◆ RangeMax() [2/2]

virtual optional< String > LinuxSampler::DeviceCreationParameter::RangeMax ( std::map< String, String Parameters)
pure virtual

Might return a maximum value for this parameter.

This method must be implemented by descendants. If the parameter does not have a reasonable maximum value, it should return optional<String>::nothing.

As arguments, the parameters are passed to this method automatically, which the user already provided. For example a parameter "CARD" the user already did set for selecting a specific sound card. So such arguments resolve dependencies of this parameter.

Parameters
Parameters- other parameters which the user already supplied

Implemented in LinuxSampler::DeviceCreationParameterBool, LinuxSampler::DeviceCreationParameterInt, LinuxSampler::DeviceCreationParameterFloat, LinuxSampler::DeviceCreationParameterString, and LinuxSampler::DeviceCreationParameterStrings.

◆ RangeMin() [1/2]

virtual optional< String > LinuxSampler::DeviceCreationParameter::RangeMin ( )
virtual

Might return a minimum value for this parameter.

If the parameter does not have a reasonable minimum value, it will return optional<String>::nothing.

This method already provides an implementation, which usually is not overridden by descendants. A descendant would rather implement the other RangeMin() method taking arguments.

Implements LinuxSampler::DeviceRuntimeParameter.

◆ RangeMin() [2/2]

virtual optional< String > LinuxSampler::DeviceCreationParameter::RangeMin ( std::map< String, String Parameters)
pure virtual

Might return a minimum value for this parameter.

This method must be implemented by descendants. If the parameter does not have a reasonable minimum value, it should return optional<String>::nothing.

As arguments, the parameters are passed to this method automatically, which the user already provided. For example a parameter "CARD" the user already did set for selecting a specific sound card. So such arguments resolve dependencies of this parameter.

Parameters
Parameters- other parameters which the user already supplied

Implemented in LinuxSampler::DeviceCreationParameterBool, LinuxSampler::DeviceCreationParameterInt, LinuxSampler::DeviceCreationParameterFloat, LinuxSampler::DeviceCreationParameterString, and LinuxSampler::DeviceCreationParameterStrings.

◆ SetValue()

virtual void LinuxSampler::DeviceRuntimeParameter::SetValue ( String  val)
throw (Exception
)
pure virtualinherited

Alter the parameter with the value given by val.

The respective deriving parameter class automatically parses the String value supplied here, and converts it into its native value type like int, float or String vector ("Strings").

Parameters
-new parameter value encoded as string
Exceptions
Exception- if val is out of bounds, not encoded correctly in its string representation or any other reason the driver might not want to accept the given value.

Implemented in LinuxSampler::DeviceRuntimeParameterBool, LinuxSampler::DeviceRuntimeParameterInt, LinuxSampler::DeviceRuntimeParameterFloat, LinuxSampler::DeviceRuntimeParameterString, LinuxSampler::DeviceRuntimeParameterStrings, LinuxSampler::DeviceCreationParameterBool, LinuxSampler::DeviceCreationParameterInt, LinuxSampler::DeviceCreationParameterFloat, LinuxSampler::DeviceCreationParameterString, and LinuxSampler::DeviceCreationParameterStrings.

◆ Type()

virtual String LinuxSampler::DeviceRuntimeParameter::Type ( )
pure virtualinherited

◆ Value()

virtual String LinuxSampler::DeviceRuntimeParameter::Value ( )
pure virtualinherited

Member Data Documentation

◆ pDevice

Device* LinuxSampler::DeviceCreationParameter::pDevice
protected

Definition at line 753 of file DeviceParameter.h.


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