libfluidsynth  2.0.1
Macros | Typedefs | Enumerations | Functions
settings.h File Reference

Synthesizer settings. More...

Macros

#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_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_TOGGLED   0x4
 Hint FLUID_HINT_TOGGLED indicates that the data item should be considered a Boolean toggle. More...
 
#define FLUID_HINT_OPTIONLIST   0x02
 Setting is a list of string options.
 

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...
 

Functions

FLUIDSYNTH_API fluid_settings_tnew_fluid_settings (void)
 Create a new settings object. More...
 
FLUIDSYNTH_API void delete_fluid_settings (fluid_settings_t *settings)
 Delete the provided settings object. More...
 
FLUIDSYNTH_API int fluid_settings_get_type (fluid_settings_t *settings, const char *name)
 Get the type of the setting with the given name. More...
 
FLUIDSYNTH_API 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...
 
FLUIDSYNTH_API int fluid_settings_is_realtime (fluid_settings_t *settings, const char *name)
 Ask whether the setting is changeable in real-time. More...
 
FLUIDSYNTH_API int fluid_settings_setstr (fluid_settings_t *settings, const char *name, const char *str)
 Set a string value for a named setting. More...
 
FLUIDSYNTH_API 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...
 
FLUIDSYNTH_API int fluid_settings_dupstr (fluid_settings_t *settings, const char *name, char **str)
 Duplicate the value of a string setting. More...
 
FLUIDSYNTH_API int fluid_settings_getstr_default (fluid_settings_t *settings, const char *name, char **def)
 Get the default value of a string setting. More...
 
FLUIDSYNTH_API int fluid_settings_str_equal (fluid_settings_t *settings, const char *name, const char *value)
 Test a string setting for some value. More...
 
FLUIDSYNTH_API int fluid_settings_setnum (fluid_settings_t *settings, const char *name, double val)
 Set a numeric value for a named setting. More...
 
FLUIDSYNTH_API int fluid_settings_getnum (fluid_settings_t *settings, const char *name, double *val)
 Get the numeric value of a named setting. More...
 
FLUIDSYNTH_API 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...
 
FLUIDSYNTH_API 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...
 
FLUIDSYNTH_API int fluid_settings_setint (fluid_settings_t *settings, const char *name, int val)
 Set an integer value for a setting. More...
 
FLUIDSYNTH_API int fluid_settings_getint (fluid_settings_t *settings, const char *name, int *val)
 Get an integer value setting. More...
 
FLUIDSYNTH_API int fluid_settings_getint_default (fluid_settings_t *settings, const char *name, int *val)
 Get the default value of an integer setting. More...
 
FLUIDSYNTH_API 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...
 
FLUIDSYNTH_API 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...
 
FLUIDSYNTH_API int fluid_settings_option_count (fluid_settings_t *settings, const char *name)
 Count option string values for a string setting. More...
 
FLUIDSYNTH_API 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...
 
FLUIDSYNTH_API 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...
 

Detailed Description

Synthesizer settings.

Macro Definition Documentation

◆ 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.

Referenced by delete_fluid_settings().

◆ 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.

Referenced by delete_fluid_settings().

◆ 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.

Referenced by delete_fluid_player(), fluid_get_sysconf(), fluid_settings_copystr(), fluid_settings_dupstr(), fluid_settings_getstr_default(), and fluid_settings_str_equal().

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
dataUser defined data pointer
nameSetting name
optionA 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
dataUser defined data pointer
nameSetting name
typeSetting type (fluid_types_enum)

Enumeration Type Documentation

◆ 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

◆ new_fluid_settings()

FLUIDSYNTH_API 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.

◆ delete_fluid_settings()

FLUIDSYNTH_API void delete_fluid_settings ( fluid_settings_t settings)

◆ fluid_settings_get_type()

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

Get the type of the setting with the given name.

Parameters
settingsa settings object
namea setting's name
Returns
the type for the named setting (see fluid_types_enum), or FLUID_NO_TYPE when it does not exist

References FLUID_NO_TYPE, and FLUID_OK.

Referenced by fluid_get_sysconf().

◆ fluid_settings_get_hints()

FLUIDSYNTH_API 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
settingsa settings object
namea setting's name
hintsset to the hints associated to the setting if it exists
Returns
FLUID_OK if hints associated to the named setting exist, FLUID_FAILED otherwise

References FLUID_FAILED, FLUID_INT_TYPE, FLUID_NUM_TYPE, FLUID_OK, and FLUID_STR_TYPE.

Referenced by fluid_get_sysconf().

◆ fluid_settings_is_realtime()

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

Ask whether the setting is changeable in real-time.

Parameters
settingsa settings object
namea setting's name
Returns
TRUE if the setting is changeable in real-time, FALSE otherwise

References FLUID_INT_TYPE, FLUID_NUM_TYPE, FLUID_OK, and FLUID_STR_TYPE.

Referenced by fluid_get_sysconf().

◆ fluid_settings_setstr()

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

Set a string value for a named setting.

Parameters
settingsa settings object
namea setting's name
strnew string value
Returns
FLUID_OK if the value has been set, FLUID_FAILED otherwise
Examples:
fluidsynth_register_adriver.c.

References FLUID_ERR, FLUID_FAILED, FLUID_OK, and FLUID_STR_TYPE.

Referenced by fluid_get_sysconf().

◆ fluid_settings_copystr()

FLUIDSYNTH_API 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
settingsa settings object
namea setting's name
strCaller supplied buffer to copy string value to
lenSize 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
Since
1.1.0
Note
A size of 256 should be more than sufficient for the string buffer.

References FLUID_FAILED, FLUID_HINT_TOGGLED, FLUID_INT_TYPE, FLUID_OK, and FLUID_STR_TYPE.

◆ fluid_settings_dupstr()

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

Duplicate the value of a string setting.

Parameters
settingsa settings object
namea setting's name
strLocation to store pointer to allocated duplicate string
Returns
FLUID_OK if the value exists and was successfully duplicated, FLUID_FAILED otherwise
Since
1.1.0

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

References FLUID_ERR, FLUID_FAILED, FLUID_HINT_TOGGLED, FLUID_INT_TYPE, FLUID_OK, and FLUID_STR_TYPE.

Referenced by delete_fluid_shell(), fluid_get_sysconf(), new_fluid_file_renderer(), and new_fluid_synth().

◆ fluid_settings_getstr_default()

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

Get the default value of a string setting.

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

Parameters
settingsa settings object
namea setting's name
defthe default string value of the setting if it exists
Returns
FLUID_OK on success, FLUID_FAILED otherwise

References FLUID_FAILED, FLUID_HINT_OPTIONLIST, FLUID_HINT_TOGGLED, FLUID_INT_TYPE, FLUID_OK, and FLUID_STR_TYPE.

Referenced by fluid_get_sysconf().

◆ fluid_settings_str_equal()

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

Test a string setting for some value.

Parameters
settingsa settings object
namea setting's name
sa string to be tested
Returns
TRUE if the value exists and is equal to 's', FALSE otherwise

References FLUID_HINT_TOGGLED, FLUID_INT_TYPE, FLUID_OK, and FLUID_STR_TYPE.

Referenced by new_fluid_midi_driver(), new_fluid_player(), and new_fluid_synth().

◆ fluid_settings_setnum()

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

Set a numeric value for a named setting.

Parameters
settingsa settings object
namea setting's name
valnew setting's value
Returns
FLUID_OK if the value has been set, FLUID_FAILED otherwise

References FLUID_DBG, FLUID_FAILED, FLUID_NUM_TYPE, and FLUID_OK.

Referenced by fluid_get_sysconf().

◆ fluid_settings_getnum()

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

Get the numeric value of a named setting.

Parameters
settingsa settings object
namea setting's name
valvariable pointer to receive the setting's numeric value
Returns
FLUID_OK if the value exists, FLUID_FAILED otherwise

References FLUID_FAILED, FLUID_NUM_TYPE, and FLUID_OK.

Referenced by fluid_get_sysconf(), new_fluid_file_renderer(), and new_fluid_synth().

◆ fluid_settings_getnum_default()

FLUIDSYNTH_API 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
settingsa settings object
namea setting's name
valset to the default value if the named setting exists
Returns
FLUID_OK if the default value of the named setting exists, FLUID_FAILED otherwise

References FLUID_FAILED, FLUID_NUM_TYPE, and FLUID_OK.

Referenced by fluid_get_sysconf().

◆ fluid_settings_getnum_range()

FLUIDSYNTH_API 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
settingsa settings object
namea setting's name
minsetting's range lower limit
maxsetting's range upper limit
Returns
FLUID_OK if the setting's range exists, FLUID_FAILED otherwise

References FLUID_FAILED, FLUID_NUM_TYPE, and FLUID_OK.

Referenced by fluid_get_sysconf().

◆ fluid_settings_setint()

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

Set an integer value for a setting.

Parameters
settingsa settings object
namea setting's name
valnew setting's integer value
Returns
FLUID_OK if the value has been set, FLUID_FAILED otherwise

References FLUID_DBG, FLUID_FAILED, FLUID_INT_TYPE, and FLUID_OK.

Referenced by fluid_get_sysconf(), and new_fluid_synth().

◆ fluid_settings_getint()

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

Get an integer value setting.

Parameters
settingsa settings object
namea setting's name
valpointer to a variable to receive the setting's integer value
Returns
FLUID_OK if the value exists, FLUID_FAILED otherwise

References FLUID_FAILED, FLUID_INT_TYPE, and FLUID_OK.

Referenced by fluid_get_sysconf(), new_fluid_defsfloader(), new_fluid_file_renderer(), new_fluid_midi_router(), new_fluid_player(), new_fluid_server(), and new_fluid_synth().

◆ fluid_settings_getint_default()

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

Get the default value of an integer setting.

Parameters
settingsa settings object
namea setting's name
valset to the setting's default integer value if it exists
Returns
FLUID_OK if the setting's default integer value exists, FLUID_FAILED otherwise

References FLUID_FAILED, FLUID_INT_TYPE, and FLUID_OK.

Referenced by fluid_get_sysconf().

◆ fluid_settings_getint_range()

FLUIDSYNTH_API 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
settingsa settings object
namea setting's name
minsetting's range lower limit
maxsetting's range upper limit
Returns
FLUID_OK if the setting's range exists, FLUID_FAILED otherwise

References FLUID_FAILED, FLUID_INT_TYPE, and FLUID_OK.

Referenced by fluid_get_sysconf().

◆ fluid_settings_foreach_option()

FLUIDSYNTH_API 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
settingsa settings object
namea setting's name
dataany user provided pointer
funccallback 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.

References FLUID_OK, and FLUID_STR_TYPE.

Referenced by fluid_get_sysconf().

◆ fluid_settings_option_count()

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

Count option string values for a string setting.

Parameters
settingsa settings object
nameName 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

References FLUID_OK, and FLUID_STR_TYPE.

◆ fluid_settings_option_concat()

FLUIDSYNTH_API 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
settingsSettings object
nameSettings name
separatorString 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.
Since
1.1.0

References FLUID_ERR, FLUID_INT_TYPE, FLUID_NUM_TYPE, FLUID_OK, FLUID_SET_TYPE, and FLUID_STR_TYPE.

Referenced by new_fluid_midi_driver().

◆ fluid_settings_foreach()

FLUIDSYNTH_API 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
settingsa settings object
dataany user provided pointer
funccallback 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.

References FLUID_ERR, and FLUID_OK.

Referenced by fluid_get_sysconf().