Settings

Functions for settings management. More...

Macros
#define	FLUID_HINT_BOUNDED_ABOVE   0x2
	Hint FLUID_HINT_BOUNDED_ABOVE indicates that the UpperBound field of the FLUID_PortRangeHint should be considered meaningful. More...
#define	FLUID_HINT_BOUNDED_BELOW   0x1
	Hint FLUID_HINT_BOUNDED_BELOW indicates that the LowerBound field of the FLUID_PortRangeHint should be considered meaningful. More...
#define	FLUID_HINT_OPTIONLIST   0x02
	Setting is a list of string options.
#define	FLUID_HINT_TOGGLED   0x4
	Hint FLUID_HINT_TOGGLED indicates that the data item should be considered a Boolean toggle. More...

Typedefs
typedef void(*	fluid_settings_foreach_option_t) (void *data, const char *name, const char *option)
	Callback function type used with fluid_settings_foreach_option() More...
typedef void(*	fluid_settings_foreach_t) (void *data, const char *name, int type)
	Callback function type used with fluid_settings_foreach() More...

Enumerations
enum	fluid_types_enum {   FLUID_NO_TYPE = -1 ,   FLUID_NUM_TYPE ,   FLUID_INT_TYPE ,   FLUID_STR_TYPE ,   FLUID_SET_TYPE }
	Settings type. More...

Lifecycle Functions for Settings_linebr@{
fluid_settings_t *	new_fluid_settings (void)
	Create a new settings object. More...
void	delete_fluid_settings (fluid_settings_t *settings)
	Delete the provided settings object. More...

Functions
int	fluid_settings_copystr (fluid_settings_t *settings, const char *name, char *str, int len)
	Copy the value of a string setting into the provided buffer (thread safe) More...
int	fluid_settings_dupstr (fluid_settings_t *settings, const char *name, char **str)
	Duplicate the value of a string setting. More...
void	fluid_settings_foreach (fluid_settings_t *settings, void *data, fluid_settings_foreach_t func)
	Iterate the existing settings defined in a settings object, calling the provided callback function for each setting. More...
void	fluid_settings_foreach_option (fluid_settings_t *settings, const char *name, void *data, fluid_settings_foreach_option_t func)
	Iterate the available options for a named string setting, calling the provided callback function for each existing option. More...
int	fluid_settings_get_hints (fluid_settings_t *settings, const char *name, int *val)
	Get the hints for the named setting as an integer bitmap. More...
int	fluid_settings_get_type (fluid_settings_t *settings, const char *name)
	Get the type of the setting with the given name. More...
int	fluid_settings_getint (fluid_settings_t *settings, const char *name, int *val)
	Get an integer value setting. More...
int	fluid_settings_getint_default (fluid_settings_t *settings, const char *name, int *val)
	Get the default value of an integer setting. More...
int	fluid_settings_getint_range (fluid_settings_t *settings, const char *name, int *min, int *max)
	Get the range of values of an integer setting. More...
int	fluid_settings_getnum (fluid_settings_t *settings, const char *name, double *val)
	Get the numeric value of a named setting. More...
int	fluid_settings_getnum_default (fluid_settings_t *settings, const char *name, double *val)
	Get the default value of a named numeric (double) setting. More...
int	fluid_settings_getnum_range (fluid_settings_t *settings, const char *name, double *min, double *max)
	Get the range of values of a numeric setting. More...
int	fluid_settings_getstr_default (fluid_settings_t *settings, const char *name, char **def)
	Get the default value of a string setting. More...
int	fluid_settings_is_realtime (fluid_settings_t *settings, const char *name)
	Ask whether the setting is changeable in real-time. More...
char *	fluid_settings_option_concat (fluid_settings_t *settings, const char *name, const char *separator)
	Concatenate options for a string setting together with a separator between. More...
int	fluid_settings_option_count (fluid_settings_t *settings, const char *name)
	Count option string values for a string setting. More...
int	fluid_settings_setint (fluid_settings_t *settings, const char *name, int val)
	Set an integer value for a setting. More...
int	fluid_settings_setnum (fluid_settings_t *settings, const char *name, double val)
	Set a numeric value for a named setting. More...
int	fluid_settings_setstr (fluid_settings_t *settings, const char *name, const char *str)
	Set a string value for a named setting. More...
int	fluid_settings_str_equal (fluid_settings_t *settings, const char *name, const char *value)
	Test a string setting for some value. More...
fluid_settings_t *	fluid_synth_get_settings (fluid_synth_t *synth)
	Get settings assigned to a synth. More...

Detailed Description

Functions for settings management.

To create a synthesizer object you will have to specify its settings. These settings are stored in a fluid_settings_t object.

void
my_synthesizer ()
{
  fluid_settings_t *settings;
  fluid_synth_t *synth;
  fluid_audio_driver_t *adriver;
 
  settings = new_fluid_settings ();
  fluid_settings_setstr(settings, "audio.driver", "alsa");
  // ... change settings ...
  synth = new_fluid_synth (settings);
  adriver = new_fluid_audio_driver (settings, synth);
  // ...
}

All string settings are encoded in UTF-8. This includes the names of the audio and MIDI devices, exposed as setting options.

See also

Creating and changing the settings

Macro Definition Documentation

FLUID_HINT_BOUNDED_ABOVE

#define FLUID_HINT_BOUNDED_ABOVE   0x2

Hint FLUID_HINT_BOUNDED_ABOVE indicates that the UpperBound field of the FLUID_PortRangeHint should be considered meaningful.

The value in this field should be considered the (inclusive) upper bound of the valid range. If FLUID_HINT_SAMPLE_RATE is also specified then the value of UpperBound should be multiplied by the sample rate.

FLUID_HINT_BOUNDED_BELOW

#define FLUID_HINT_BOUNDED_BELOW   0x1

Hint FLUID_HINT_BOUNDED_BELOW indicates that the LowerBound field of the FLUID_PortRangeHint should be considered meaningful.

The value in this field should be considered the (inclusive) lower bound of the valid range. If FLUID_HINT_SAMPLE_RATE is also specified then the value of LowerBound should be multiplied by the sample rate.

FLUID_HINT_TOGGLED

#define FLUID_HINT_TOGGLED   0x4

Hint FLUID_HINT_TOGGLED indicates that the data item should be considered a Boolean toggle.

Data less than or equal to zero should be considered ‘off’ or ‘false,’ and data above zero should be considered ‘on’ or ‘true.’ FLUID_HINT_TOGGLED may not be used in conjunction with any other hint.

Typedef Documentation

fluid_settings_foreach_option_t

typedef void(* fluid_settings_foreach_option_t) (void *data, const char *name, const char *option)

Callback function type used with fluid_settings_foreach_option()

Parameters

data	User defined data pointer
name	Setting name
option	A string option for this setting (iterates through the list)

fluid_settings_foreach_t

typedef void(* fluid_settings_foreach_t) (void *data, const char *name, int type)

Callback function type used with fluid_settings_foreach()

Parameters

data	User defined data pointer
name	Setting name
type	Setting type (fluid_types_enum)

Enumeration Type Documentation

fluid_types_enum

enum fluid_types_enum

Settings type.

Each setting has a defined type: numeric (double), integer, string or a set of values. The type of each setting can be retrieved using the function fluid_settings_get_type()

Enumerator
FLUID_NO_TYPE	Undefined type.
FLUID_NUM_TYPE	Numeric (double)
FLUID_INT_TYPE	Integer.
FLUID_STR_TYPE	String.
FLUID_SET_TYPE	Set of values.

Function Documentation

delete_fluid_settings()

void delete_fluid_settings

(

fluid_settings_t *

settings

)

Delete the provided settings object.

Parameters

settings

a settings object

Examples

example.c, fluidsynth_arpeggio.c, fluidsynth_fx.c, fluidsynth_metronome.c, fluidsynth_register_adriver.c, fluidsynth_sfload_mem.c, and fluidsynth_simple.c.

fluid_settings_copystr()

int fluid_settings_copystr	(	fluid_settings_t *	settings,
		const char *	name,
		char *	str,
		int	len
	)

Copy the value of a string setting into the provided buffer (thread safe)

Parameters

settings	a settings object
name	a setting's name
str	Caller supplied buffer to copy string value to
len	Size of 'str' buffer (no more than len bytes will be written, which will always include a zero terminator)

Returns

FLUID_OK if the value exists, FLUID_FAILED otherwise

Note

A size of 256 should be more than sufficient for the string buffer.

Since

1.1.0

fluid_settings_dupstr()

int fluid_settings_dupstr	(	fluid_settings_t *	settings,
		const char *	name,
		char **	str
	)

Duplicate the value of a string setting.

Parameters

settings	a settings object
name	a setting's name
str	Location to store pointer to allocated duplicate string

Returns

FLUID_OK if the value exists and was successfully duplicated, FLUID_FAILED otherwise

Like fluid_settings_copystr() but allocates a new copy of the string. Caller owns the string and should free it with fluid_free() when done using it.

Since

1.1.0

fluid_settings_foreach()

void fluid_settings_foreach	(	fluid_settings_t *	settings,
		void *	data,
		fluid_settings_foreach_t	func
	)

Iterate the existing settings defined in a settings object, calling the provided callback function for each setting.

Parameters

settings	a settings object
data	any user provided pointer
func	callback function to be called on each iteration

Note

Starting with FluidSynth 1.1.0 the func callback is called for each setting in alphabetical order. Sort order was undefined in previous versions.

fluid_settings_foreach_option()

void fluid_settings_foreach_option	(	fluid_settings_t *	settings,
		const char *	name,
		void *	data,
		fluid_settings_foreach_option_t	func
	)

Iterate the available options for a named string setting, calling the provided callback function for each existing option.

Parameters

settings	a settings object
name	a setting's name
data	any user provided pointer
func	callback function to be called on each iteration

Note

Starting with FluidSynth 1.1.0 the func callback is called for each option in alphabetical order. Sort order was undefined in previous versions.

fluid_settings_get_hints()

int fluid_settings_get_hints	(	fluid_settings_t *	settings,
		const char *	name,
		int *	hints
	)

Get the hints for the named setting as an integer bitmap.

Parameters

settings	a settings object
name	a setting's name
hints	set to the hints associated to the setting if it exists

Returns

FLUID_OK if hints associated to the named setting exist, FLUID_FAILED otherwise

fluid_settings_get_type()

int fluid_settings_get_type	(	fluid_settings_t *	settings,
		const char *	name
	)

Get the type of the setting with the given name.

Parameters

settings	a settings object
name	a setting's name

Returns

the type for the named setting (see fluid_types_enum), or FLUID_NO_TYPE when it does not exist

fluid_settings_getint()

int fluid_settings_getint	(	fluid_settings_t *	settings,
		const char *	name,
		int *	val
	)

Get an integer value setting.

Parameters

settings	a settings object
name	a setting's name
val	pointer to a variable to receive the setting's integer value

Returns

FLUID_OK if the value exists, FLUID_FAILED otherwise

fluid_settings_getint_default()

int fluid_settings_getint_default	(	fluid_settings_t *	settings,
		const char *	name,
		int *	val
	)

Get the default value of an integer setting.

Parameters

settings	a settings object
name	a setting's name
val	set to the setting's default integer value if it exists

Returns

FLUID_OK if the setting's default integer value exists, FLUID_FAILED otherwise

fluid_settings_getint_range()

int fluid_settings_getint_range	(	fluid_settings_t *	settings,
		const char *	name,
		int *	min,
		int *	max
	)

Get the range of values of an integer setting.

Parameters

settings	a settings object
name	a setting's name
min	setting's range lower limit
max	setting's range upper limit

Returns

FLUID_OK if the setting's range exists, FLUID_FAILED otherwise

fluid_settings_getnum()

int fluid_settings_getnum	(	fluid_settings_t *	settings,
		const char *	name,
		double *	val
	)

Get the numeric value of a named setting.

Parameters

settings	a settings object
name	a setting's name
val	variable pointer to receive the setting's numeric value

Returns

FLUID_OK if the value exists, FLUID_FAILED otherwise

fluid_settings_getnum_default()

int fluid_settings_getnum_default	(	fluid_settings_t *	settings,
		const char *	name,
		double *	val
	)

Get the default value of a named numeric (double) setting.

Parameters

settings	a settings object
name	a setting's name
val	set to the default value if the named setting exists

Returns

FLUID_OK if the default value of the named setting exists, FLUID_FAILED otherwise

fluid_settings_getnum_range()

int fluid_settings_getnum_range	(	fluid_settings_t *	settings,
		const char *	name,
		double *	min,
		double *	max
	)

Get the range of values of a numeric setting.

Parameters

settings	a settings object
name	a setting's name
min	setting's range lower limit
max	setting's range upper limit

Returns

FLUID_OK if the setting's range exists, FLUID_FAILED otherwise

fluid_settings_getstr_default()

int fluid_settings_getstr_default	(	fluid_settings_t *	settings,
		const char *	name,
		char **	def
	)

Get the default value of a string setting.

Parameters

settings	a settings object
name	a setting's name
def	the default string value of the setting if it exists

Returns

FLUID_OK if a default value exists, FLUID_FAILED otherwise

Note

The returned string is not owned by the caller and should not be modified or freed.

fluid_settings_is_realtime()

int fluid_settings_is_realtime	(	fluid_settings_t *	settings,
		const char *	name
	)

Ask whether the setting is changeable in real-time.

Parameters

settings	a settings object
name	a setting's name

Returns

TRUE if the setting is changeable in real-time, FALSE otherwise

Note

Before using this function, make sure the settings object has already been used to create a synthesizer, a MIDI driver, an audio driver, a MIDI player, or a command handler (depending on which settings you want to query).

fluid_settings_option_concat()

char* fluid_settings_option_concat	(	fluid_settings_t *	settings,
		const char *	name,
		const char *	separator
	)

Concatenate options for a string setting together with a separator between.

Parameters

settings	Settings object
name	Settings name
separator	String to use between options (NULL to use ", ")

Returns

Newly allocated string or NULL on error (out of memory, not a valid setting name or not a string setting). Free the string when finished with it by using fluid_free().

Since

1.1.0

fluid_settings_option_count()

int fluid_settings_option_count	(	fluid_settings_t *	settings,
		const char *	name
	)

Count option string values for a string setting.

Parameters

settings	a settings object
name	Name of setting

Returns

Count of options for this string setting (0 if none, -1 if not found or not a string setting)

Since

1.1.0

fluid_settings_setint()

int fluid_settings_setint	(	fluid_settings_t *	settings,
		const char *	name,
		int	val
	)

Set an integer value for a setting.

Parameters

settings	a settings object
name	a setting's name
val	new setting's integer value

Returns

FLUID_OK if the value has been set, FLUID_FAILED otherwise

fluid_settings_setnum()

int fluid_settings_setnum	(	fluid_settings_t *	settings,
		const char *	name,
		double	val
	)

Set a numeric value for a named setting.

Parameters

settings	a settings object
name	a setting's name
val	new setting's value

Returns

FLUID_OK if the value has been set, FLUID_FAILED otherwise

fluid_settings_setstr()

int fluid_settings_setstr	(	fluid_settings_t *	settings,
		const char *	name,
		const char *	str
	)

Set a string value for a named setting.

Parameters

settings	a settings object
name	a setting's name
str	new string value

Returns

FLUID_OK if the value has been set, FLUID_FAILED otherwise

Examples

fluidsynth_register_adriver.c.

fluid_settings_str_equal()

int fluid_settings_str_equal	(	fluid_settings_t *	settings,
		const char *	name,
		const char *	s
	)

Test a string setting for some value.

Parameters

settings	a settings object
name	a setting's name
s	a string to be tested

Returns

TRUE if the value exists and is equal to s, FALSE otherwise

fluid_synth_get_settings()

fluid_settings_t* fluid_synth_get_settings

(

fluid_synth_t *

synth

)

Get settings assigned to a synth.

Parameters

synth

FluidSynth instance

Returns

FluidSynth settings which are assigned to the synth

new_fluid_settings()

fluid_settings_t* new_fluid_settings

(

void

)

Create a new settings object.

Returns

the pointer to the settings object

Examples

example.c, fluidsynth_arpeggio.c, fluidsynth_fx.c, fluidsynth_metronome.c, fluidsynth_register_adriver.c, fluidsynth_sfload_mem.c, and fluidsynth_simple.c.