libs/fluidsynth/fluidsynth/settings.h

   1 /* FluidSynth - A Software Synthesizer
   2  *
   3  * Copyright (C) 2003  Peter Hanappe and others.
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public License
   7  * as published by the Free Software Foundation; either version 2.1 of
   8  * the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the Free
  17  * Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  18  * 02110-1301, USA
  19  */
  20
  21 #ifndef _FLUIDSYNTH_SETTINGS_H
  22 #define _FLUIDSYNTH_SETTINGS_H
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /**
  29  * @file settings.h
  30  * @brief Synthesizer settings
  31  * @defgroup SettingsFunctions Functions for settings management
  32  *
  33  * To create a synthesizer object you will have to specify its
  34  * settings. These settings are stored in a fluid_settings_t object.
  35  * @code
  36  *     void
  37  *     my_synthesizer ()
  38  *     {
  39  *       fluid_settings_t *settings;
  40  *       fluid_synth_t *synth;
  41  *       fluid_audio_driver_t *adriver;
  42  *
  43  *       settings = new_fluid_settings ();
  44  *       fluid_settings_setstr(settings, "audio.driver", "alsa");
  45  *       // ... change settings ...
  46  *       synth = new_fluid_synth (settings);
  47  *       adriver = new_fluid_audio_driver (settings, synth);
  48  *       // ...
  49  *     }
  50  * @endcode
  51  * @sa @ref CreatingSettings
  52  */
  53
  54 /**
  55  * Hint FLUID_HINT_BOUNDED_BELOW indicates that the LowerBound field
  56  * of the FLUID_PortRangeHint should be considered meaningful. The
  57  * value in this field should be considered the (inclusive) lower
  58  * bound of the valid range. If FLUID_HINT_SAMPLE_RATE is also
  59  * specified then the value of LowerBound should be multiplied by the
  60  * sample rate.
  61  */
  62 #define FLUID_HINT_BOUNDED_BELOW   0x1
  63
  64 /** Hint FLUID_HINT_BOUNDED_ABOVE indicates that the UpperBound field
  65    of the FLUID_PortRangeHint should be considered meaningful. The
  66    value in this field should be considered the (inclusive) upper
  67    bound of the valid range. If FLUID_HINT_SAMPLE_RATE is also
  68    specified then the value of UpperBound should be multiplied by the
  69    sample rate. */
  70 #define FLUID_HINT_BOUNDED_ABOVE   0x2
  71
  72 /**
  73  * Hint FLUID_HINT_TOGGLED indicates that the data item should be
  74  * considered a Boolean toggle. Data less than or equal to zero should
  75  * be considered `off' or `false,' and data above zero should be
  76  * considered `on' or `true.' FLUID_HINT_TOGGLED may not be used in
  77  * conjunction with any other hint.
  78  */
  79 #define FLUID_HINT_TOGGLED         0x4
  80
  81 #define FLUID_HINT_OPTIONLIST      0x02         /**< Setting is a list of string options */
  82
  83
  84 /**
  85  * Settings type
  86  *
  87  * Each setting has a defined type: numeric (double), integer, string or a
  88  * set of values. The type of each setting can be retrieved using the
  89  * function fluid_settings_get_type()
  90  */
  91 enum fluid_types_enum
  92 {
  93     FLUID_NO_TYPE = -1, /**< Undefined type */
  94     FLUID_NUM_TYPE,     /**< Numeric (double) */
  95     FLUID_INT_TYPE,     /**< Integer */
  96     FLUID_STR_TYPE,     /**< String */
  97     FLUID_SET_TYPE      /**< Set of values */
  98 };
  99
 100
 101 FLUIDSYNTH_API fluid_settings_t *new_fluid_settings(void);
 102 FLUIDSYNTH_API void delete_fluid_settings(fluid_settings_t *settings);
 103
 104 FLUIDSYNTH_API
 105 int fluid_settings_get_type(fluid_settings_t *settings, const char *name);
 106
 107 FLUIDSYNTH_API
 108 int fluid_settings_get_hints(fluid_settings_t *settings, const char *name, int *val);
 109
 110 FLUIDSYNTH_API
 111 int fluid_settings_is_realtime(fluid_settings_t *settings, const char *name);
 112
 113 FLUIDSYNTH_API
 114 int fluid_settings_setstr(fluid_settings_t *settings, const char *name, const char *str);
 115
 116 FLUIDSYNTH_API
 117 int fluid_settings_copystr(fluid_settings_t *settings, const char *name, char *str, int len);
 118
 119 FLUIDSYNTH_API
 120 int fluid_settings_dupstr(fluid_settings_t *settings, const char *name, char **str);
 121
 122 FLUIDSYNTH_API
 123 int fluid_settings_getstr_default(fluid_settings_t *settings, const char *name, char **def);
 124
 125 FLUIDSYNTH_API
 126 int fluid_settings_str_equal(fluid_settings_t *settings, const char *name, const char *value);
 127
 128 FLUIDSYNTH_API
 129 int fluid_settings_setnum(fluid_settings_t *settings, const char *name, double val);
 130
 131 FLUIDSYNTH_API
 132 int fluid_settings_getnum(fluid_settings_t *settings, const char *name, double *val);
 133
 134 FLUIDSYNTH_API
 135 int fluid_settings_getnum_default(fluid_settings_t *settings, const char *name, double *val);
 136
 137 FLUIDSYNTH_API
 138 int fluid_settings_getnum_range(fluid_settings_t *settings, const char *name,
 139                                 double *min, double *max);
 140
 141 FLUIDSYNTH_API
 142 int fluid_settings_setint(fluid_settings_t *settings, const char *name, int val);
 143
 144 FLUIDSYNTH_API
 145 int fluid_settings_getint(fluid_settings_t *settings, const char *name, int *val);
 146
 147 FLUIDSYNTH_API
 148 int fluid_settings_getint_default(fluid_settings_t *settings, const char *name, int *val);
 149
 150 FLUIDSYNTH_API
 151 int fluid_settings_getint_range(fluid_settings_t *settings, const char *name,
 152                                 int *min, int *max);
 153
 154 /**
 155  * Callback function type used with fluid_settings_foreach_option()
 156  * @param data User defined data pointer
 157  * @param name Setting name
 158  * @param option A string option for this setting (iterates through the list)
 159  */
 160 typedef void (*fluid_settings_foreach_option_t)(void *data, const char *name, const char *option);
 161
 162 FLUIDSYNTH_API
 163 void fluid_settings_foreach_option(fluid_settings_t *settings,
 164                                    const char *name, void *data,
 165                                    fluid_settings_foreach_option_t func);
 166 FLUIDSYNTH_API
 167 int fluid_settings_option_count(fluid_settings_t *settings, const char *name);
 168 FLUIDSYNTH_API char *fluid_settings_option_concat(fluid_settings_t *settings,
 169         const char *name,
 170         const char *separator);
 171
 172 /**
 173  * Callback function type used with fluid_settings_foreach()
 174  * @param data User defined data pointer
 175  * @param name Setting name
 176  * @param type Setting type (#fluid_types_enum)
 177  */
 178 typedef void (*fluid_settings_foreach_t)(void *data, const char *name, int type);
 179
 180 FLUIDSYNTH_API
 181 void fluid_settings_foreach(fluid_settings_t *settings, void *data,
 182                             fluid_settings_foreach_t func);
 183
 184 #ifdef __cplusplus
 185 }
 186 #endif
 187
 188 #endif /* _FLUIDSYNTH_SETTINGS_H */