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 Library General Public License
   7  * as published by the Free Software Foundation; either version 2 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  * Library General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Library 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 /**
  82  * Hint FLUID_HINT_SAMPLE_RATE indicates that any bounds specified
  83  * should be interpreted as multiples of the sample rate. For
  84  * instance, a frequency range from 0Hz to the Nyquist frequency (half
  85  * the sample rate) could be requested by this hint in conjunction
  86  * with LowerBound = 0 and UpperBound = 0.5. Hosts that support bounds
  87  * at all must support this hint to retain meaning.
  88  */
  89 #define FLUID_HINT_SAMPLE_RATE     0x8
  90
  91 /**
  92  * Hint FLUID_HINT_LOGARITHMIC indicates that it is likely that the
  93  * user will find it more intuitive to view values using a logarithmic
  94  * scale. This is particularly useful for frequencies and gains.
  95  */
  96 #define FLUID_HINT_LOGARITHMIC     0x10
  97
  98 /**
  99  * Hint FLUID_HINT_INTEGER indicates that a user interface would
 100  * probably wish to provide a stepped control taking only integer
 101  * values.
 102  * @deprecated
 103  *
 104  * As there is an integer setting type, this hint is not used.
 105  */
 106 #define FLUID_HINT_INTEGER         0x20
 107
 108
 109 #define FLUID_HINT_FILENAME        0x01         /**< String setting is a file name */
 110 #define FLUID_HINT_OPTIONLIST      0x02         /**< Setting is a list of string options */
 111
 112
 113 /**
 114  * Settings type
 115  *
 116  * Each setting has a defined type: numeric (double), integer, string or a
 117  * set of values. The type of each setting can be retrieved using the
 118  * function fluid_settings_get_type()
 119  */
 120 enum fluid_types_enum {
 121   FLUID_NO_TYPE = -1, /**< Undefined type */
 122   FLUID_NUM_TYPE,     /**< Numeric (double) */
 123   FLUID_INT_TYPE,     /**< Integer */
 124   FLUID_STR_TYPE,     /**< String */
 125   FLUID_SET_TYPE      /**< Set of values */
 126 };
 127
 128
 129 FLUIDSYNTH_API fluid_settings_t* new_fluid_settings(void);
 130 FLUIDSYNTH_API void delete_fluid_settings(fluid_settings_t* settings);
 131
 132 FLUIDSYNTH_API
 133 int fluid_settings_get_type(fluid_settings_t* settings, const char *name);
 134
 135 FLUIDSYNTH_API
 136 int fluid_settings_get_hints(fluid_settings_t* settings, const char *name);
 137
 138 FLUIDSYNTH_API
 139 int fluid_settings_is_realtime(fluid_settings_t* settings, const char *name);
 140
 141 FLUIDSYNTH_API
 142 int fluid_settings_setstr(fluid_settings_t* settings, const char *name, const char *str);
 143
 144 FLUIDSYNTH_API
 145 int fluid_settings_copystr(fluid_settings_t* settings, const char *name, char *str, int len);
 146
 147 FLUIDSYNTH_API
 148 int fluid_settings_dupstr(fluid_settings_t* settings, const char *name, char** str);
 149
 150 FLUIDSYNTH_API
 151 int fluid_settings_getstr(fluid_settings_t* settings, const char *name, char** str);
 152
 153 FLUIDSYNTH_API
 154 char* fluid_settings_getstr_default(fluid_settings_t* settings, const char *name);
 155
 156 FLUIDSYNTH_API
 157 int fluid_settings_str_equal(fluid_settings_t* settings, const char *name, const char *value);
 158
 159 FLUIDSYNTH_API
 160 int fluid_settings_setnum(fluid_settings_t* settings, const char *name, double val);
 161
 162 FLUIDSYNTH_API
 163 int fluid_settings_getnum(fluid_settings_t* settings, const char *name, double* val);
 164
 165 FLUIDSYNTH_API
 166 double fluid_settings_getnum_default(fluid_settings_t* settings, const char *name);
 167
 168 FLUIDSYNTH_API
 169 void fluid_settings_getnum_range(fluid_settings_t* settings, const char *name,
 170                                 double* min, double* max);
 171
 172 FLUIDSYNTH_API
 173 int fluid_settings_setint(fluid_settings_t* settings, const char *name, int val);
 174
 175 FLUIDSYNTH_API
 176 int fluid_settings_getint(fluid_settings_t* settings, const char *name, int* val);
 177
 178 FLUIDSYNTH_API
 179 int fluid_settings_getint_default(fluid_settings_t* settings, const char *name);
 180
 181 FLUIDSYNTH_API
 182 void fluid_settings_getint_range(fluid_settings_t* settings, const char *name,
 183                                 int* min, int* max);
 184
 185 /**
 186  * Callback function type used with fluid_settings_foreach_option()
 187  * @param data User defined data pointer
 188  * @param name Setting name
 189  * @param option A string option for this setting (iterates through the list)
 190  */
 191 typedef void (*fluid_settings_foreach_option_t)(void *data, char *name, char *option);
 192
 193 FLUIDSYNTH_API
 194 void fluid_settings_foreach_option(fluid_settings_t* settings,
 195                                   const char* name, void* data,
 196                                   fluid_settings_foreach_option_t func);
 197 FLUIDSYNTH_API
 198 int fluid_settings_option_count (fluid_settings_t* settings, const char* name);
 199 FLUIDSYNTH_API char *fluid_settings_option_concat (fluid_settings_t* settings,
 200                                                    const char* name,
 201                                                    const char* separator);
 202
 203 /**
 204  * Callback function type used with fluid_settings_foreach()
 205  * @param data User defined data pointer
 206  * @param name Setting name
 207  * @param type Setting type (#fluid_types_enum)
 208  */
 209 typedef void (*fluid_settings_foreach_t)(void *data, char *name, int type);
 210
 211 FLUIDSYNTH_API
 212 void fluid_settings_foreach(fluid_settings_t* settings, void* data,
 213                            fluid_settings_foreach_t func);
 214
 215 #ifdef __cplusplus
 216 }
 217 #endif
 218
 219 #endif /* _FLUIDSYNTH_SETTINGS_H */