From 4709880402413a2ba4a3a2d06e0f2e9a199b4b30 Mon Sep 17 00:00:00 2001 From: Pedro Lopez-Cabanillas Date: Fri, 1 May 2009 17:26:42 +0000 Subject: [PATCH] Doxygen documentation: license changed to CC-BY-SA 3.0 Modules created: audio and settings --- fluidsynth/ChangeLog | 55 ++++--- fluidsynth/doc/Doxyfile | 1 + fluidsynth/doc/fluidsynth-v11-devdoc.txt | 12 +- fluidsynth/doc/fluidsynth_arpeggio.c | 151 +++++++++++++++++ fluidsynth/doc/fluidsynth_metronome.c | 137 ++++++++++++++++ fluidsynth/include/fluidsynth.h | 16 +- fluidsynth/include/fluidsynth/audio.h | 18 ++- fluidsynth/include/fluidsynth/settings.h | 181 +++++++++------------ fluidsynth/src/fluid_settings.c | 196 ++++++++++++++++++++--- 9 files changed, 607 insertions(+), 160 deletions(-) create mode 100644 fluidsynth/doc/fluidsynth_arpeggio.c create mode 100644 fluidsynth/doc/fluidsynth_metronome.c diff --git a/fluidsynth/ChangeLog b/fluidsynth/ChangeLog index 32579831..3e3214c5 100644 --- a/fluidsynth/ChangeLog +++ b/fluidsynth/ChangeLog @@ -1,3 +1,12 @@ +2009-05-01 Pedro Lopez-Cabanillas + * doc/Doxyfile: added fluid_filerenderer.c to Doxygen documentation. + * doc/fluidsynth-v11-devdoc.txt: license changed to CC-BY-SA 3.0 + * doc/fluidsynth_arpeggio.c: new example added. + * doc/fluidsynth_metronome.c: new example added. + * include/fluidsynth.h, include/fluidsynth/audio.h, + include/fluidsynth/settings.h: Doxygen documentation. + * src/fluid_settings.c: Doxygen documentation. + 2009-04-27 Josh Green * include/fluidsynth/audio.h: Moved new filerenderer documentation to source file. * src/config_win32.h.in: Added 'typedef int socklen_t;' to the correct place. @@ -7,25 +16,25 @@ config_win32.h.in. 2009-04-26 Josh Green - * configure.ac: Added glib 2.10 as a dependency, added notes in output - for LASH, LADCCA and READLINE that they are GPL. - * src/fluid_io.c: Moved code to fluid_sys.c and removed. - * src/config_win32.h: Added "typedef int socklen_t" definition. - * src/fluid_defsfont.h: Removed glib ripped code. - * src/fluid_oss.c: Fixed warnings where return value of write() was - being ignored. - * src/fluid_sys.c: Re-organized, implemented portable fluid_curtime() and - fluid_utime() using glib functions and removed old platform specific - code, implemented fluid_thread functionality using glib and removed - old platform specific code, fluid_istream_readline(), fluid_istream_gets() - and fluid_ostream_printf() should now work on WIN32 also, added code - for WIN32 for TCP sockets (not yet tested). - * src/fluid_sys.h: Added fluid_gerror_message() macro to extract message - safely from GError structures, replaced fluid_mutex macros with - portable implementations using glib, removed new_fluid_client_socket() - and delete_fluid_client_socket() which were never implemented or used. - * src/fluidsynth.c: Added call to g_thread_init(). - * src/fluidsynth_priv.h: Integer types now use glib integer types. + * configure.ac: Added glib 2.10 as a dependency, added notes in output + for LASH, LADCCA and READLINE that they are GPL. + * src/fluid_io.c: Moved code to fluid_sys.c and removed. + * src/config_win32.h: Added "typedef int socklen_t" definition. + * src/fluid_defsfont.h: Removed glib ripped code. + * src/fluid_oss.c: Fixed warnings where return value of write() was + being ignored. + * src/fluid_sys.c: Re-organized, implemented portable fluid_curtime() and + fluid_utime() using glib functions and removed old platform specific + code, implemented fluid_thread functionality using glib and removed + old platform specific code, fluid_istream_readline(), fluid_istream_gets() + and fluid_ostream_printf() should now work on WIN32 also, added code + for WIN32 for TCP sockets (not yet tested). + * src/fluid_sys.h: Added fluid_gerror_message() macro to extract message + safely from GError structures, replaced fluid_mutex macros with + portable implementations using glib, removed new_fluid_client_socket() + and delete_fluid_client_socket() which were never implemented or used. + * src/fluidsynth.c: Added call to g_thread_init(). + * src/fluidsynth_priv.h: Integer types now use glib integer types. 2009-04-11 Josh Green * FluidSynth release 1.0.9 "A Sound Future" @@ -52,12 +61,12 @@ * README-OSX: Update from Ebrahim Mayat. 2009-02-28 Pedro Lopez-Cabanillas - * src/fluid_midi.c: Fix for ticket #22 (Wrong tempo changes) - * src/fluid_midi.h: delta-time accumulator moved to fluid_midi_file struct. + * src/fluid_midi.c: Fix for ticket #22 (Wrong tempo changes) + * src/fluid_midi.h: delta-time accumulator moved to fluid_midi_file struct. 2009-02-03 Josh Green - * Applied patch from KO Myung-Hun for OS/2 support including Dart audio - driver. + * Applied patch from KO Myung-Hun for OS/2 support including Dart audio + driver. 2009-01-29 Josh Green * src/Makefile.am: Added PortAudio driver conditional build. diff --git a/fluidsynth/doc/Doxyfile b/fluidsynth/doc/Doxyfile index 55be1799..02bbd4f4 100644 --- a/fluidsynth/doc/Doxyfile +++ b/fluidsynth/doc/Doxyfile @@ -118,6 +118,7 @@ FILE_PATTERNS = fluidsynth.h \ fluid_adriver.c \ fluid_cmd.c \ fluid_event.c \ + fluid_filerenderer.c \ fluid_gen.c \ fluid_sys.c \ fluid_mdriver.c \ diff --git a/fluidsynth/doc/fluidsynth-v11-devdoc.txt b/fluidsynth/doc/fluidsynth-v11-devdoc.txt index bb0f8913..82c90f54 100644 --- a/fluidsynth/doc/fluidsynth-v11-devdoc.txt +++ b/fluidsynth/doc/fluidsynth-v11-devdoc.txt @@ -8,7 +8,7 @@ \version Revision 1.1.0 \date 2009-mm-dd -All the source code examples in this document are in the public domain; you can use them as you please. This document is licensed under the Creative Commons Attribution License. To view a copy of this license, visit http://creativecommons.org/licenses/by/1.0/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA. The FluidSynth library is distributed under the GNU Library General Public License. A copy of the GNU Library General Public License is contained in the FluidSynth package; if not, visit http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt or write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +All the source code examples in this document are in the public domain; you can use them as you please. This document is licensed under the Creative Commons Attribution-Share Alike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ . The FluidSynth library is distributed under the GNU Library General Public License. A copy of the GNU Library General Public License is contained in the FluidSynth package; if not, visit http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt or write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. \section Abstract @@ -840,3 +840,13 @@ A basic example of using fluidsynth to play a single note \example fluidsynth_fx.c Example of using effects with fluidsynth */ + +/*! +\example fluidsynth_metronome.c +Example of a simple metronome using the MIDI sequencer API +*/ + +/*! +\example fluidsynth_arpeggio.c +Example of an arpeggio generated using the MIDI sequencer API +*/ diff --git a/fluidsynth/doc/fluidsynth_arpeggio.c b/fluidsynth/doc/fluidsynth_arpeggio.c new file mode 100644 index 00000000..71f004a4 --- /dev/null +++ b/fluidsynth/doc/fluidsynth_arpeggio.c @@ -0,0 +1,151 @@ +/* FluidSynth Arpeggio - Sequencer API example + * + * This code is in the public domain. + * + * To compile: + * gcc -o fluidsynth_arpeggio -lfluidsynth fluidsynth_arpeggio.c + * + * To run: + * fluidsynth_arpeggio soundfont [steps [duration]] + * + * [Pedro Lopez-Cabanillas ] + */ + +#include +#include +#include + +fluid_synth_t *synth; +fluid_audio_driver_t *audiodriver; +fluid_sequencer_t *sequencer; +short synth_destination, client_destination; +unsigned int time_marker; +/* duration of the pattern in ticks. */ +unsigned int duration = 1440; +/* notes of the arpeggio */ +unsigned int notes[] = { 60, 64, 67, 72, 76, 79, 84, 79, 76, 72, 67, 64 }; +/* number of notes in one pattern */ +unsigned int pattern_size; +/* prototype */ +void +sequencer_callback (unsigned int time, fluid_event_t *event, + fluid_sequencer_t *seq, void *data); + +/* schedule a note on message */ +void +schedule_noteon (int chan, short key, unsigned int ticks) +{ + fluid_event_t *ev = new_fluid_event (); + fluid_event_set_source (ev, -1); + fluid_event_set_dest (ev, synth_destination); + fluid_event_noteon (ev, chan, key, 127); + fluid_sequencer_send_at (sequencer, ev, ticks, 1); + delete_fluid_event (ev); +} + +/* schedule a note off message */ +void +schedule_noteoff (int chan, short key, unsigned int ticks) +{ + fluid_event_t *ev = new_fluid_event (); + fluid_event_set_source (ev, -1); + fluid_event_set_dest (ev, synth_destination); + fluid_event_noteoff (ev, chan, key); + fluid_sequencer_send_at (sequencer, ev, ticks, 1); + delete_fluid_event (ev); +} + +/* schedule a timer event (shall trigger the callback) */ +void +schedule_timer_event () +{ + fluid_event_t *ev = new_fluid_event (); + fluid_event_set_source (ev, -1); + fluid_event_set_dest (ev, client_destination); + fluid_event_timer (ev, NULL); + fluid_sequencer_send_at (sequencer, ev, time_marker, 1); + delete_fluid_event (ev); +} + +/* schedule the arpeggio's notes */ +void +schedule_pattern () +{ + int i, note_time, note_duration; + note_time = time_marker; + note_duration = duration / pattern_size; + for (i = 0; i < pattern_size; ++i) { + schedule_noteon (0, notes[i], note_time); + note_time += note_duration; + schedule_noteoff (0, notes[i], note_time); + } + time_marker += duration; +} + +void +sequencer_callback (unsigned int time, fluid_event_t *event, + fluid_sequencer_t *seq, void *data) +{ + schedule_timer_event (); + schedule_pattern (); +} + +void +usage (char* prog_name) +{ + printf ("Usage: %s soundfont.sf2 [steps [duration]]\n", prog_name); + printf ("\t(optional) steps: number of pattern notes, from 2 to %d\n", + pattern_size); + printf ("\t(optional) duration: of the pattern in ticks, default %d\n", + duration); +} + +int +main (int argc, char* argv[]) +{ + int n; + fluid_settings_t *settings; + settings = new_fluid_settings (); + pattern_size = sizeof(notes) / sizeof(int); + if (argc < 2) { + usage (argv[0]); + } else { + /* create the synth, driver and sequencer instances */ + synth = new_fluid_synth (settings); + audiodriver = new_fluid_audio_driver (settings, synth); + sequencer = new_fluid_sequencer (); + /* register the synth with the sequencer */ + synth_destination = fluid_sequencer_register_fluidsynth (sequencer, + synth); + /* register the client name and callback */ + client_destination = fluid_sequencer_register_client (sequencer, + "arpeggio", sequencer_callback, NULL); + /* load a SoundFont */ + n = fluid_synth_sfload (synth, argv[1], 1); + if (n != -1) { + if (argc > 2) { + n = atoi (argv[2]); + if ((n > 1) && (n <= pattern_size)) pattern_size = n; + } + if (argc > 3) { + n = atoi (argv[3]); + if (n > 0) duration = n; + } + /* get the current time in ticks */ + time_marker = fluid_sequencer_get_tick (sequencer); + /* schedule patterns */ + schedule_pattern (); + schedule_timer_event (); + schedule_pattern (); + /* wait for user input */ + printf ("press to stop\n"); + n = getchar (); + } + /* clean and exit */ + delete_fluid_sequencer (sequencer); + delete_fluid_audio_driver (audiodriver); + delete_fluid_synth (synth); + } + delete_fluid_settings (settings); + return 0; +} diff --git a/fluidsynth/doc/fluidsynth_metronome.c b/fluidsynth/doc/fluidsynth_metronome.c new file mode 100644 index 00000000..af00bfd4 --- /dev/null +++ b/fluidsynth/doc/fluidsynth_metronome.c @@ -0,0 +1,137 @@ +/* FluidSynth Metronome - Sequencer API example + * + * This code is in the public domain. + * + * To compile: + * gcc -o fluidsynth_metronome -lfluidsynth fluidsynth_metronome.c + * + * To run: + * fluidsynth_metronome soundfont [beats [tempo]] + * + * [Pedro Lopez-Cabanillas ] + */ + +#include +#include +#include + +fluid_synth_t *synth; +fluid_audio_driver_t *audiodriver; +fluid_sequencer_t *sequencer; +short synth_destination, client_destination; +unsigned int time_marker; +/* default tempo, beats per minute */ +#define TEMPO 120 +unsigned int note_duration = 60000 / TEMPO; +/* metronome click/bell */ +unsigned int weak_note = 33; +unsigned int strong_note = 34; +/* number of notes in one pattern */ +unsigned int pattern_size = 4; +/* prototype */ +void +sequencer_callback (unsigned int time, fluid_event_t *event, + fluid_sequencer_t *seq, void *data); + +/* schedule a note on message */ +void +schedule_noteon (int chan, short key, unsigned int ticks) +{ + fluid_event_t *ev = new_fluid_event (); + fluid_event_set_source (ev, -1); + fluid_event_set_dest (ev, synth_destination); + fluid_event_noteon (ev, chan, key, 127); + fluid_sequencer_send_at (sequencer, ev, ticks, 1); + delete_fluid_event (ev); +} + +/* schedule a timer event (shall trigger the callback) */ +void +schedule_timer_event () +{ + fluid_event_t *ev = new_fluid_event (); + fluid_event_set_source (ev, -1); + fluid_event_set_dest (ev, client_destination); + fluid_event_timer (ev, NULL); + fluid_sequencer_send_at (sequencer, ev, time_marker, 1); + delete_fluid_event (ev); +} + +/* schedule the metronome pattern */ +void +schedule_pattern () +{ + int i, note_time; + note_time = time_marker; + for (i = 0; i < pattern_size; ++i) { + schedule_noteon (9, i ? weak_note : strong_note, note_time); + note_time += note_duration; + } + time_marker = note_time; +} + +void +sequencer_callback (unsigned int time, fluid_event_t *event, + fluid_sequencer_t *seq, void *data) +{ + schedule_timer_event (); + schedule_pattern (); +} + +void +usage (char* prog_name) +{ + printf ("Usage: %s soundfont.sf2 [beats [tempo]]\n", prog_name); + printf ("\t(optional) beats: number of pattern beats, default %d\n", + pattern_size); + printf ("\t(optional) tempo: BPM (Beats Per Minute), default %d\n", TEMPO); +} + +int +main (int argc, char *argv[]) +{ + int n; + fluid_settings_t *settings; + settings = new_fluid_settings (); + if (argc < 2) { + usage (argv[0]); + } else { + /* create the synth, driver and sequencer instances */ + synth = new_fluid_synth (settings); + audiodriver = new_fluid_audio_driver (settings, synth); + sequencer = new_fluid_sequencer (); + /* register the synth with the sequencer */ + synth_destination = fluid_sequencer_register_fluidsynth (sequencer, + synth); + /* register the client name and callback */ + client_destination = fluid_sequencer_register_client (sequencer, + "fluidsynth_metronome", sequencer_callback, NULL); + /* load a SoundFont */ + n = fluid_synth_sfload (synth, argv[1], 1); + if (n != -1) { + if (argc > 2) { + n = atoi (argv[2]); + if (n > 0) pattern_size = n; + } + if (argc > 3) { + n = atoi (argv[3]); + if (n > 0) note_duration = 60000 / n; + } + /* get the current time in ticks */ + time_marker = fluid_sequencer_get_tick (sequencer); + /* schedule patterns */ + schedule_pattern (); + schedule_timer_event (); + schedule_pattern (); + /* wait for user input */ + printf ("press to stop\n"); + n = getchar (); + } + /* clean and exit */ + delete_fluid_sequencer (sequencer); + delete_fluid_audio_driver (audiodriver); + delete_fluid_synth (synth); + } + delete_fluid_settings (settings); + return 0; +} diff --git a/fluidsynth/include/fluidsynth.h b/fluidsynth/include/fluidsynth.h index ef40f824..106e0740 100644 --- a/fluidsynth/include/fluidsynth.h +++ b/fluidsynth/include/fluidsynth.h @@ -11,7 +11,7 @@ * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. - * + * * You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the Free * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA @@ -31,7 +31,7 @@ extern "C" { #if defined(FLUIDSYNTH_DLL_EXPORTS) #define FLUIDSYNTH_API __declspec(dllexport) #elif defined(FLUIDSYNTH_NOT_A_DLL) -#define FLUIDSYNTH_API +#define FLUIDSYNTH_API #else #define FLUIDSYNTH_API __declspec(dllimport) #endif @@ -55,23 +55,23 @@ extern "C" { * will need different API functions. You probably do not need all * of them. Here is what you might want to do: * - * o Embedded synthesizer: create a new synthesizer and send MIDI + * - Embedded synthesizer: create a new synthesizer and send MIDI * events to it. The sound goes directly to the audio output of * your system. * - * o Plugin synthesizer: create a synthesizer and send MIDI events + * - Plugin synthesizer: create a synthesizer and send MIDI events * but pull the audio back into your application. * - * o SoundFont plugin: create a new type of "SoundFont" and allow + * - SoundFont plugin: create a new type of "SoundFont" and allow * the synthesizer to load your type of SoundFonts. * - * o MIDI input: Create a MIDI handler to read the MIDI input on your + * - MIDI input: Create a MIDI handler to read the MIDI input on your * machine and send the MIDI events directly to the synthesizer. * - * o MIDI files: Open MIDI files and send the MIDI events to the + * - MIDI files: Open MIDI files and send the MIDI events to the * synthesizer. * - * o Command lines: You can send textual commands to the synthesizer. + * - Command lines: You can send textual commands to the synthesizer. * * SoundFont(R) is a registered trademark of E-mu Systems, Inc. */ diff --git a/fluidsynth/include/fluidsynth/audio.h b/fluidsynth/include/fluidsynth/audio.h index 2dfe49a1..48ab6295 100644 --- a/fluidsynth/include/fluidsynth/audio.h +++ b/fluidsynth/include/fluidsynth/audio.h @@ -11,7 +11,7 @@ * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. - * + * * You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the Free * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA @@ -28,12 +28,16 @@ extern "C" { /** * @file audio.h * @brief Functions for audio driver output. + * @defgroup AudioFunctions Functions for audio output * * Defines functions for creating audio driver output. Use * new_fluid_audio_driver() to create a new audio driver for a given synth * and configuration settings. The function new_fluid_audio_driver2() can be * used if custom audio processing is desired before the audio is sent to the * audio driver (although it is not as efficient). + * + * @sa @ref CreatingAudioDriver + * @{ */ /** @@ -48,20 +52,20 @@ extern "C" { * @param out Output buffers, one for each channel * @return Should return 0 on success, non-zero if an error occured. */ -typedef int (*fluid_audio_func_t)(void* data, int len, - int nin, float** in, +typedef int (*fluid_audio_func_t)(void* data, int len, + int nin, float** in, int nout, float** out); -FLUIDSYNTH_API fluid_audio_driver_t* new_fluid_audio_driver(fluid_settings_t* settings, +FLUIDSYNTH_API fluid_audio_driver_t* new_fluid_audio_driver(fluid_settings_t* settings, fluid_synth_t* synth); -FLUIDSYNTH_API fluid_audio_driver_t* new_fluid_audio_driver2(fluid_settings_t* settings, +FLUIDSYNTH_API fluid_audio_driver_t* new_fluid_audio_driver2(fluid_settings_t* settings, fluid_audio_func_t func, void* data); FLUIDSYNTH_API void delete_fluid_audio_driver(fluid_audio_driver_t* driver); -FLUIDSYNTH_API fluid_file_renderer_t* new_fluid_file_renderer(fluid_synth_t* synth, +FLUIDSYNTH_API fluid_file_renderer_t* new_fluid_file_renderer(fluid_synth_t* synth, char* filename, int period_size); FLUIDSYNTH_API int fluid_file_renderer_process_block(fluid_file_renderer_t* dev); FLUIDSYNTH_API void delete_fluid_file_renderer(fluid_file_renderer_t* dev); @@ -70,4 +74,6 @@ FLUIDSYNTH_API void delete_fluid_file_renderer(fluid_file_renderer_t* dev); } #endif +/** @} */ + #endif /* _FLUIDSYNTH_AUDIO_H */ diff --git a/fluidsynth/include/fluidsynth/settings.h b/fluidsynth/include/fluidsynth/settings.h index 61f04313..03d016fc 100644 --- a/fluidsynth/include/fluidsynth/settings.h +++ b/fluidsynth/include/fluidsynth/settings.h @@ -11,7 +11,7 @@ * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. - * + * * You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the Free * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA @@ -25,38 +25,34 @@ extern "C" { #endif - /** - * - * Synthesizer settings - * - * - * The create a synthesizer object you will have to specify its - * settings. These settings are stored in the structure below. +/** + * @file settings.h + * @brief Synthesizer settings + * @defgroup SettingsFunctions 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. + * @code + * 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); + * // ... + * } + * @endcode + * @sa @ref CreatingSettings + * @{ + */ - * 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); - * - * ... - * - * } - * - * - */ - - - - -/* Hint FLUID_HINT_BOUNDED_BELOW indicates that the LowerBound field +/** 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 @@ -64,7 +60,7 @@ extern "C" { sample rate. */ #define FLUID_HINT_BOUNDED_BELOW 0x1 -/* Hint FLUID_HINT_BOUNDED_ABOVE indicates that the UpperBound field +/** 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 @@ -72,7 +68,7 @@ extern "C" { sample rate. */ #define FLUID_HINT_BOUNDED_ABOVE 0x2 -/* Hint FLUID_HINT_TOGGLED indicates that the data item should be +/** 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 @@ -80,7 +76,7 @@ extern "C" { FLUID_HINT_DEFAULT_1. */ #define FLUID_HINT_TOGGLED 0x4 -/* Hint FLUID_HINT_SAMPLE_RATE indicates that any bounds specified +/** Hint FLUID_HINT_SAMPLE_RATE indicates that any bounds specified should be interpreted as multiples of the sample rate. For instance, a frequency range from 0Hz to the Nyquist frequency (half the sample rate) could be requested by this hint in conjunction @@ -88,12 +84,12 @@ extern "C" { at all must support this hint to retain meaning. */ #define FLUID_HINT_SAMPLE_RATE 0x8 -/* Hint FLUID_HINT_LOGARITHMIC indicates that it is likely that the +/** Hint FLUID_HINT_LOGARITHMIC indicates that it is likely that the user will find it more intuitive to view values using a logarithmic scale. This is particularly useful for frequencies and gains. */ #define FLUID_HINT_LOGARITHMIC 0x10 -/* Hint FLUID_HINT_INTEGER indicates that a user interface would +/** Hint FLUID_HINT_INTEGER indicates that a user interface would probably wish to provide a stepped control taking only integer values. Any bounds set should be slightly wider than the actual integer range required to avoid floating point rounding errors. For @@ -106,118 +102,95 @@ extern "C" { #define FLUID_HINT_OPTIONLIST 0x02 - +/** + * 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() + */ enum fluid_types_enum { - FLUID_NO_TYPE = -1, - FLUID_NUM_TYPE, - FLUID_INT_TYPE, - FLUID_STR_TYPE, - FLUID_SET_TYPE + FLUID_NO_TYPE = -1,//!< Undefined type + FLUID_NUM_TYPE, //!< Numeric (double) + FLUID_INT_TYPE, //!< Integer + FLUID_STR_TYPE, //!< String + FLUID_SET_TYPE //!< Set of values }; FLUIDSYNTH_API fluid_settings_t* new_fluid_settings(void); FLUIDSYNTH_API void delete_fluid_settings(fluid_settings_t* settings); - - -FLUIDSYNTH_API +FLUIDSYNTH_API int fluid_settings_get_type(fluid_settings_t* settings, char* name); -FLUIDSYNTH_API +FLUIDSYNTH_API int fluid_settings_get_hints(fluid_settings_t* settings, char* name); -/** Returns whether the setting is changeable in real-time. */ -FLUIDSYNTH_API int fluid_settings_is_realtime(fluid_settings_t* settings, char* name); +FLUIDSYNTH_API +int fluid_settings_is_realtime(fluid_settings_t* settings, char* name); - -/** returns 1 if the value has been set, 0 otherwise */ -FLUIDSYNTH_API +FLUIDSYNTH_API int fluid_settings_setstr(fluid_settings_t* settings, char* name, char* str); -/** - Get the value of a string setting. If the value does not exists, - 'str' is set to NULL. Otherwise, 'str' will point to the - value. The application does not own the returned value. Instead, - the application should make a copy of the value if it needs it - later. - - \returns 1 if the value exists, 0 otherwise -*/ -FLUIDSYNTH_API +FLUIDSYNTH_API int fluid_settings_getstr(fluid_settings_t* settings, char* name, char** str); -/** Get the default value of a string setting. */ -FLUIDSYNTH_API +FLUIDSYNTH_API char* fluid_settings_getstr_default(fluid_settings_t* settings, char* name); -/** Get the value of a numeric setting. - - \returns 1 if the value exists and is equal to 'value', 0 - otherwise -*/ -FLUIDSYNTH_API +FLUIDSYNTH_API int fluid_settings_str_equal(fluid_settings_t* settings, char* name, char* value); - -/** returns 1 if the value has been set, 0 otherwise */ -FLUIDSYNTH_API +FLUIDSYNTH_API int fluid_settings_setnum(fluid_settings_t* settings, char* name, double val); -/** returns 1 if the value exists, 0 otherwise */ -FLUIDSYNTH_API +FLUIDSYNTH_API int fluid_settings_getnum(fluid_settings_t* settings, char* name, double* val); -/** Get the default value of a string setting. */ -FLUIDSYNTH_API +FLUIDSYNTH_API double fluid_settings_getnum_default(fluid_settings_t* settings, char* name); - -/** Get the range of values of a numeric settings. */ -FLUIDSYNTH_API -void fluid_settings_getnum_range(fluid_settings_t* settings, char* name, + +FLUIDSYNTH_API +void fluid_settings_getnum_range(fluid_settings_t* settings, char* name, double* min, double* max); - -/** returns 1 if the value has been set, 0 otherwise */ -FLUIDSYNTH_API +FLUIDSYNTH_API int fluid_settings_setint(fluid_settings_t* settings, char* name, int val); -/** returns 1 if the value exists, 0 otherwise */ -FLUIDSYNTH_API +FLUIDSYNTH_API int fluid_settings_getint(fluid_settings_t* settings, char* name, int* val); -/** Get the default value of a string setting. */ -FLUIDSYNTH_API +FLUIDSYNTH_API int fluid_settings_getint_default(fluid_settings_t* settings, char* name); - -/** Get the range of values of a numeric settings. */ -FLUIDSYNTH_API -void fluid_settings_getint_range(fluid_settings_t* settings, char* name, + +FLUIDSYNTH_API +void fluid_settings_getint_range(fluid_settings_t* settings, char* name, int* min, int* max); - - +/** + * Callback function type used with fluid_settings_foreach_option() + */ typedef void (*fluid_settings_foreach_option_t)(void* data, char* name, char* option); - - -FLUIDSYNTH_API -void fluid_settings_foreach_option(fluid_settings_t* settings, - char* name, void* data, +FLUIDSYNTH_API +void fluid_settings_foreach_option(fluid_settings_t* settings, + char* name, void* data, fluid_settings_foreach_option_t func); - +/** + * Callback function type used with fluid_settings_foreach() + */ typedef void (*fluid_settings_foreach_t)(void* data, char* s, int type); FLUIDSYNTH_API -void fluid_settings_foreach(fluid_settings_t* settings, void* data, +void fluid_settings_foreach(fluid_settings_t* settings, void* data, fluid_settings_foreach_t func); - - - #ifdef __cplusplus } #endif +/** @} */ + #endif /* _FLUIDSYNTH_SETTINGS_H */ diff --git a/fluidsynth/src/fluid_settings.c b/fluidsynth/src/fluid_settings.c index d92015b0..2f15c0b3 100644 --- a/fluidsynth/src/fluid_settings.c +++ b/fluidsynth/src/fluid_settings.c @@ -158,7 +158,10 @@ static void delete_fluid_int_setting(fluid_int_setting_t* setting) } - +/** + * Create a new settings object + * @return the pointer to the setting object + */ fluid_settings_t* new_fluid_settings() { fluid_settings_t* settings = new_fluid_hashtable(fluid_settings_hash_delete); @@ -169,6 +172,10 @@ fluid_settings_t* new_fluid_settings() return settings; } +/** + * Delete the provided settings object + * @param settings a settings object + */ void delete_fluid_settings(fluid_settings_t* settings) { delete_fluid_hashtable(settings); @@ -231,7 +238,16 @@ static int fluid_settings_tokenize(char* s, char *buf, char** ptr) return n; } -/** returns 1 if the value exists, 0 otherwise */ +/** + * Get a setting name, value and type + * + * @param settings a settings object + * @param name a setting's name + * @param len + * @param value + * @param type + * @return 1 if the value exists, 0 otherwise + */ static int fluid_settings_get(fluid_settings_t* settings, char** name, int len, void** value, int* type) @@ -265,7 +281,16 @@ static int fluid_settings_get(fluid_settings_t* settings, return 1; } -/** returns 1 if the value has been set, zero otherwise */ +/** + * Set a setting name, value and type, replacing it if already exists + * + * @param settings a settings object + * @param name a setting's name + * @param len + * @param value + * @param type + * @return 1 if the value has been set, zero otherwise + */ static int fluid_settings_set(fluid_settings_t* settings, char** name, int len, void* value, int type) @@ -415,7 +440,15 @@ int fluid_settings_register_int(fluid_settings_t* settings, char* name, int def, } } -int fluid_settings_get_type(fluid_settings_t* settings, char* name) +/** + * Get the type of the setting with the given name + * + * @param settings a settings object + * @param name a setting's name + * @return the type for the named setting, or FLUID_NO_TYPE when it does not exists + */ +int +fluid_settings_get_type(fluid_settings_t* settings, char* name) { int type; void* value; @@ -428,7 +461,15 @@ int fluid_settings_get_type(fluid_settings_t* settings, char* name) return (fluid_settings_get(settings, tokens, ntokens, &value, &type))? type : FLUID_NO_TYPE; } -int fluid_settings_get_hints(fluid_settings_t* settings, char* name) +/** + * Get the hints for the named setting as an integer bitmap + * + * @param settings a settings object + * @param name a setting's name + * @return the hints associated to the named setting if it exists, zero otherwise + */ +int +fluid_settings_get_hints(fluid_settings_t* settings, char* name) { int type; void* value; @@ -453,7 +494,15 @@ int fluid_settings_get_hints(fluid_settings_t* settings, char* name) } } -int fluid_settings_is_realtime(fluid_settings_t* settings, char* name) +/** + * Ask whether the setting is changeable in real-time. + * + * @param settings a settings object + * @param name a setting's name + * @return non zero if the setting is changeable in real-time + */ +int +fluid_settings_is_realtime(fluid_settings_t* settings, char* name) { int type; void* value; @@ -479,6 +528,14 @@ int fluid_settings_is_realtime(fluid_settings_t* settings, char* name) } } +/** + * Set a string value for a named setting + * + * @param settings a settings object + * @param name a setting's name + * @param str new string value + * @return 1 if the value has been set, 0 otherwise + */ int fluid_settings_setstr(fluid_settings_t* settings, char* name, char* str) { char* tokens[MAX_SETTINGS_TOKENS]; @@ -517,7 +574,20 @@ int fluid_settings_setstr(fluid_settings_t* settings, char* name, char* str) } } -int fluid_settings_getstr(fluid_settings_t* settings, char* name, char** str) +/** + * Get the value of a string setting. + * + * If the value does not exists, 'str' is set to NULL. Otherwise, 'str' will + * point to the value. The application does not own the returned value. Instead, + * the application should make a copy of the value if it needs it later. + * + * @param settings a settings object + * @param name a setting's name + * @param str pointer to the string containing the setting's value + * @return 1 if the value exists, 0 otherwise + */ +int +fluid_settings_getstr(fluid_settings_t* settings, char* name, char** str) { int type; void* value; @@ -537,6 +607,14 @@ int fluid_settings_getstr(fluid_settings_t* settings, char* name, char** str) return 0; } +/** + * Test a string setting for some value. + * + * @param settings a settings object + * @param name a setting's name + * @param s a string to be tested + * @return 1 if the value exists and is equal to 's', 0 otherwise + */ int fluid_settings_str_equal(fluid_settings_t* settings, char* name, char* s) { int type; @@ -555,6 +633,13 @@ int fluid_settings_str_equal(fluid_settings_t* settings, char* name, char* s) return 0; } +/** + * Get the default value of a string setting. + * + * @param settings a settings object + * @param name a setting's name + * @return the default string value of the setting if it exists, NULL otherwise + */ char* fluid_settings_getstr_default(fluid_settings_t* settings, char* name) { @@ -628,6 +713,14 @@ int fluid_settings_remove_option(fluid_settings_t* settings, char* name, char* s } } +/** + * Set a numeric value for a named setting. + * + * @param settings a settings object + * @param name a setting's name + * @param val new setting's value + * @return 1 if the value has been set, 0 otherwise + */ int fluid_settings_setnum(fluid_settings_t* settings, char* name, double val) { int type; @@ -670,6 +763,14 @@ int fluid_settings_setnum(fluid_settings_t* settings, char* name, double val) } } +/** + * Get the numeric value of a named setting + * + * @param settings a settings object + * @param name a setting's name + * @param val variable pointer to receive the setting's numeric value + * @return 1 if the value exists, 0 otherwise + */ int fluid_settings_getnum(fluid_settings_t* settings, char* name, double* val) { int type; @@ -689,8 +790,16 @@ int fluid_settings_getnum(fluid_settings_t* settings, char* name, double* val) return 0; } - -void fluid_settings_getnum_range(fluid_settings_t* settings, char* name, double* min, double* max) +/** + * Get the range of values of a numeric setting + * + * @param settings a settings object + * @param name a setting's name + * @param min setting's range lower limit + * @param max setting's range upper limit + */ +void +fluid_settings_getnum_range(fluid_settings_t* settings, char* name, double* min, double* max) { int type; void* value; @@ -708,6 +817,13 @@ void fluid_settings_getnum_range(fluid_settings_t* settings, char* name, double* } } +/** + * Get the default value of a named numeric (double) setting + * + * @param settings a settings object + * @param name a setting's name + * @return the default value if the named setting exists, 0.0f otherwise + */ double fluid_settings_getnum_default(fluid_settings_t* settings, char* name) { @@ -728,7 +844,14 @@ fluid_settings_getnum_default(fluid_settings_t* settings, char* name) } } - +/** + * Set an integer value for a setting + * + * @param settings a settings object + * @param name a setting's name + * @param val new setting's integer value + * @return 1 if the value has been set, 0 otherwise + */ int fluid_settings_setint(fluid_settings_t* settings, char* name, int val) { int type; @@ -771,6 +894,14 @@ int fluid_settings_setint(fluid_settings_t* settings, char* name, int val) } } +/** + * Get an integer value setting. + * + * @param settings a settings object + * @param name a setting's name + * @param val pointer to a variable to receive the setting's integer value + * @return 1 if the value exists, 0 otherwise + */ int fluid_settings_getint(fluid_settings_t* settings, char* name, int* val) { int type; @@ -790,7 +921,13 @@ int fluid_settings_getint(fluid_settings_t* settings, char* name, int* val) return 0; } - +/** + * Get the range of values of an integer setting + * @param settings a settings object + * @param name a setting's name + * @param min setting's range lower limit + * @param max setting's range upper limit + */ void fluid_settings_getint_range(fluid_settings_t* settings, char* name, int* min, int* max) { int type; @@ -809,6 +946,13 @@ void fluid_settings_getint_range(fluid_settings_t* settings, char* name, int* mi } } +/** + * Get the default value of an integer setting. + * + * @param settings a settings object + * @param name a setting's name + * @return the setting's default integer value it it exists, zero otherwise + */ int fluid_settings_getint_default(fluid_settings_t* settings, char* name) { @@ -825,15 +969,22 @@ fluid_settings_getint_default(fluid_settings_t* settings, char* name) fluid_int_setting_t* setting = (fluid_int_setting_t*) value; return setting->def; } else { - return 0.0f; + return 0; } } - - - -void fluid_settings_foreach_option(fluid_settings_t* settings, char* name, void* data, - fluid_settings_foreach_option_t func) +/** + * Iterate the available options for a named setting, calling the provided + * callback function for each existing option. + * + * @param settings a settings object + * @param name a setting's name + * @param data any user provided pointer + * @param func callback function to be called on each iteration + */ +void +fluid_settings_foreach_option (fluid_settings_t* settings, char* name, void* data, + fluid_settings_foreach_option_t func) { int type; void* value; @@ -890,7 +1041,16 @@ int fluid_settings_foreach_iter(char* key, void* value, int type, void* data) return 0; } -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. + * + * @param settings a settings object + * @param data any user provided pointer + * @param func callback function to be called on each iteration + */ +void +fluid_settings_foreach(fluid_settings_t* settings, void* data, fluid_settings_foreach_t func) { fluid_settings_foreach_func = func; fluid_settings_foreach_data = data;