diff --git a/include/fluidsynth/ladspa.h b/include/fluidsynth/ladspa.h index 6de87a69..05b1942d 100644 --- a/include/fluidsynth/ladspa.h +++ b/include/fluidsynth/ladspa.h @@ -26,18 +26,19 @@ extern "C" { #endif /** - * @defgroup LADSPA LADSPA Interface - * @brief Functions for manipulating the ladspa effects unit + * @defgroup ladspa Effect - LADSPA + * @ingroup synth + * + * Functions for configuring the LADSPA effects unit * * This header defines useful functions for programmatically manipulating the ladspa * effects unit of the synth that can be retrieved via fluid_synth_get_ladspa_fx(). * - * Using any of those functions requires fluidsynth to be compiled with ladspa support. + * Using any of those functions requires fluidsynth to be compiled with LADSPA support. * Else all of those functions are useless dummies. * * @{ */ - FLUIDSYNTH_API int fluid_ladspa_is_active(fluid_ladspa_fx_t *fx); FLUIDSYNTH_API int fluid_ladspa_activate(fluid_ladspa_fx_t *fx); FLUIDSYNTH_API int fluid_ladspa_deactivate(fluid_ladspa_fx_t *fx); @@ -58,7 +59,6 @@ FLUIDSYNTH_API int fluid_ladspa_effect_set_control(fluid_ladspa_fx_t *fx, const const char *port_name, float val); FLUIDSYNTH_API int fluid_ladspa_effect_link(fluid_ladspa_fx_t *fx, const char *effect_name, const char *port_name, const char *name); - /* @} */ #ifdef __cplusplus diff --git a/include/fluidsynth/synth.h b/include/fluidsynth/synth.h index bb2550b0..14346fcc 100644 --- a/include/fluidsynth/synth.h +++ b/include/fluidsynth/synth.h @@ -28,8 +28,9 @@ extern "C" { /** - * @defgroup Synth Synthesizer - * @brief Embeddable SoundFont synthesizer + * @defgroup synth Synthesizer + * + * SoundFont synthesizer * * You create a new synthesizer with new_fluid_synth() and you destroy * it with delete_fluid_synth(). Use the fluid_settings_t structure to specify @@ -46,21 +47,23 @@ extern "C" { * * @{ */ - - FLUIDSYNTH_API fluid_synth_t *new_fluid_synth(fluid_settings_t *settings); FLUIDSYNTH_API void delete_fluid_synth(fluid_synth_t *synth); -FLUIDSYNTH_API fluid_settings_t *fluid_synth_get_settings(fluid_synth_t *synth); +FLUIDSYNTH_API double fluid_synth_get_cpu_load(fluid_synth_t *synth); +FLUID_DEPRECATED FLUIDSYNTH_API const char *fluid_synth_error(fluid_synth_t *synth); /* @} */ /** - * @defgroup MIDIChannel MIDI channel messages - * @ingroup Synth + * @defgroup midi_messages MIDI Channel Messages + * @ingroup synth + * + * The MIDI channel message functions are mostly directly named after their + * counterpart MIDI messages. They are a high-level interface to controlling + * the synthesizer, playing notes and changing note and channel parameters. * * @{ */ - FLUIDSYNTH_API int fluid_synth_noteon(fluid_synth_t *synth, int chan, int key, int vel); FLUIDSYNTH_API int fluid_synth_noteoff(fluid_synth_t *synth, int chan, int key); FLUIDSYNTH_API int fluid_synth_cc(fluid_synth_t *synth, int chan, int ctrl, int val); @@ -93,48 +96,35 @@ FLUIDSYNTH_API int fluid_synth_system_reset(fluid_synth_t *synth); FLUIDSYNTH_API int fluid_synth_all_notes_off(fluid_synth_t *synth, int chan); FLUIDSYNTH_API int fluid_synth_all_sounds_off(fluid_synth_t *synth, int chan); -/* @} */ +FLUIDSYNTH_API int fluid_synth_set_gen(fluid_synth_t *synth, int chan, + int param, float value); +FLUIDSYNTH_API float fluid_synth_get_gen(fluid_synth_t *synth, int chan, int param); +/* @} MIDI Channel Messages */ /** - * @defgroup DynamicSampleLoading Dynamic sample loading - * @ingroup Synth + * @defgroup voice_control Synthesis Voice Control + * @ingroup synth * * @{ */ - -FLUIDSYNTH_API -int fluid_synth_pin_preset(fluid_synth_t *synth, int sfont_id, int bank_num, int preset_num); - -FLUIDSYNTH_API -int fluid_synth_unpin_preset(fluid_synth_t *synth, int sfont_id, int bank_num, int preset_num); - -/* @} */ - - -/** - * The midi channel type used by fluid_synth_set_channel_type() - */ -enum fluid_midi_channel_type -{ - CHANNEL_TYPE_MELODIC = 0, /**< Melodic midi channel */ - CHANNEL_TYPE_DRUM = 1 /**< Drum midi channel */ -}; - -FLUIDSYNTH_API int fluid_synth_set_channel_type(fluid_synth_t *synth, int chan, int type); - - -/* Low level access */ -FLUIDSYNTH_API fluid_preset_t *fluid_synth_get_channel_preset(fluid_synth_t *synth, int chan); FLUIDSYNTH_API int fluid_synth_start(fluid_synth_t *synth, unsigned int id, fluid_preset_t *preset, int audio_chan, int midi_chan, int key, int vel); FLUIDSYNTH_API int fluid_synth_stop(fluid_synth_t *synth, unsigned int id); +FLUIDSYNTH_API fluid_voice_t *fluid_synth_alloc_voice(fluid_synth_t *synth, + fluid_sample_t *sample, + int channum, int key, int vel); +FLUIDSYNTH_API void fluid_synth_start_voice(fluid_synth_t *synth, fluid_voice_t *voice); +FLUIDSYNTH_API void fluid_synth_get_voicelist(fluid_synth_t *synth, + fluid_voice_t *buf[], int bufsize, int ID); +/* @} Voice Control */ + /** - * @defgroup SoundFontManagement SoundFont management - * @ingroup Synth + * @defgroup soundfont_management SoundFont Management + * @ingroup synth * * @{ */ @@ -151,18 +141,14 @@ FLUIDSYNTH_API fluid_sfont_t *fluid_synth_get_sfont_by_name(fluid_synth_t *synth const char *name); FLUIDSYNTH_API int fluid_synth_set_bank_offset(fluid_synth_t *synth, int sfont_id, int offset); FLUIDSYNTH_API int fluid_synth_get_bank_offset(fluid_synth_t *synth, int sfont_id); -/* @} */ +/* @} Soundfont Management */ /** - * @defgroup Effects Effects - * @ingroup Synth - */ - - -/** - * @defgroup Reverb Reverb - * @ingroup Effects + * @defgroup reverb_effect Effect - Reverb + * @ingroup synth + * + * Functions for configuring the built-in reverb effect * * @{ */ @@ -178,12 +164,14 @@ FLUIDSYNTH_API double fluid_synth_get_reverb_roomsize(fluid_synth_t *synth); FLUIDSYNTH_API double fluid_synth_get_reverb_damp(fluid_synth_t *synth); FLUIDSYNTH_API double fluid_synth_get_reverb_level(fluid_synth_t *synth); FLUIDSYNTH_API double fluid_synth_get_reverb_width(fluid_synth_t *synth); -/* @} */ +/* @} Reverb */ /** - * @defgroup Chrous Chrous - * @ingroup Effects + * @defgroup chorus_effect Effect - Chorus + * @ingroup synth + * + * Functions for configuring the built-in chorus effect * * @{ */ @@ -211,12 +199,12 @@ FLUIDSYNTH_API double fluid_synth_get_chorus_level(fluid_synth_t *synth); FLUIDSYNTH_API double fluid_synth_get_chorus_speed(fluid_synth_t *synth); FLUIDSYNTH_API double fluid_synth_get_chorus_depth(fluid_synth_t *synth); FLUIDSYNTH_API int fluid_synth_get_chorus_type(fluid_synth_t *synth); /* see fluid_chorus_mod */ -/* @} Chorus */ +/* @} Chrous */ /** - * @defgroup ChannelManagement Audio and MIDI channels - * @ingroup Synth + * @defgroup synthesis_params Synthesis Parameters + * @ingroup synth * * @{ */ @@ -225,15 +213,6 @@ FLUIDSYNTH_API int fluid_synth_count_audio_channels(fluid_synth_t *synth); FLUIDSYNTH_API int fluid_synth_count_audio_groups(fluid_synth_t *synth); FLUIDSYNTH_API int fluid_synth_count_effects_channels(fluid_synth_t *synth); FLUIDSYNTH_API int fluid_synth_count_effects_groups(fluid_synth_t *synth); -/* @} */ - - -/** - * @defgroup SynthParams Synthesis parameters - * @ingroup Synth - * - * @{ - */ FLUID_DEPRECATED FLUIDSYNTH_API void fluid_synth_set_sample_rate(fluid_synth_t *synth, float sample_rate); FLUIDSYNTH_API void fluid_synth_set_gain(fluid_synth_t *synth, float gain); @@ -260,29 +239,28 @@ enum fluid_interp FLUID_INTERP_HIGHEST = FLUID_INTERP_7THORDER, /**< Highest interpolation method */ }; -/* @} */ - /** - * @defgroup Generator Generator interface - * @ingroup Synth - * - * @{ + * Enum used with fluid_synth_add_default_mod() to specify how to handle duplicate modulators. */ +enum fluid_synth_add_mod +{ + FLUID_SYNTH_OVERWRITE, /**< Overwrite any existing matching modulator */ + FLUID_SYNTH_ADD, /**< Sum up modulator amounts */ +}; -FLUIDSYNTH_API int fluid_synth_set_gen(fluid_synth_t *synth, int chan, - int param, float value); -FLUIDSYNTH_API float fluid_synth_get_gen(fluid_synth_t *synth, int chan, int param); - -/* @} */ +FLUIDSYNTH_API int fluid_synth_add_default_mod(fluid_synth_t *synth, const fluid_mod_t *mod, int mode); +FLUIDSYNTH_API int fluid_synth_remove_default_mod(fluid_synth_t *synth, const fluid_mod_t *mod); +/* @} Synthesis Parameters */ /** - * @defgroup Tuning Tuning - * @ingroup Synth + * @defgroup tuning MIDI Tuning + * @ingroup synth + * + * The functions in this section implement the MIDI Tuning Standard interface. * * @{ */ - FLUIDSYNTH_API int fluid_synth_activate_key_tuning(fluid_synth_t *synth, int bank, int prog, const char *name, const double *pitch, int apply); @@ -302,53 +280,23 @@ FLUIDSYNTH_API int fluid_synth_tuning_iteration_next(fluid_synth_t *synth, int *bank, int *prog); FLUIDSYNTH_API int fluid_synth_tuning_dump(fluid_synth_t *synth, int bank, int prog, char *name, int len, double *pitch); - -/* @} */ +/* @} MIDI Tuning */ /** - * @addtogroup Misc + * @defgroup audio_rendering Audio Rendering + * @ingroup synth + * + * The functions in this section can be used to render audio directly to + * memory buffers. They are used internally by the \ref audio_driver and \ref file_renderer, + * but can also be used manually for custom processing of the rendered audio. + * + * @note Please note that all following functions block during rendering. If your goal is to + * render real-time audio, ensure that you call these functions from a high-priority + * thread with little to no other duties other than calling the rendering functions. * * @{ */ -FLUIDSYNTH_API double fluid_synth_get_cpu_load(fluid_synth_t *synth); -FLUID_DEPRECATED FLUIDSYNTH_API const char *fluid_synth_error(fluid_synth_t *synth); -/* @} */ - - -/** - * @defgroup DefaultModulators Default modulators - * @ingroup Synth - * - * @{ - */ - -/** - * Enum used with fluid_synth_add_default_mod() to specify how to handle duplicate modulators. - */ -enum fluid_synth_add_mod -{ - FLUID_SYNTH_OVERWRITE, /**< Overwrite any existing matching modulator */ - FLUID_SYNTH_ADD, /**< Sum up modulator amounts */ -}; - -FLUIDSYNTH_API int fluid_synth_add_default_mod(fluid_synth_t *synth, const fluid_mod_t *mod, int mode); -FLUIDSYNTH_API int fluid_synth_remove_default_mod(fluid_synth_t *synth, const fluid_mod_t *mod); - -/* @} */ - - -/** - * @defgroup SynthPlugin Synthesizer plugin - * @ingroup Synth - * - * To create a synthesizer plugin, create the synthesizer as - * explained above. Once the synthesizer is created you can call - * any of the functions below to get the audio. - * - * @{ - */ - FLUIDSYNTH_API int fluid_synth_write_s16(fluid_synth_t *synth, int len, void *lout, int loff, int lincr, void *rout, int roff, int rincr); @@ -361,32 +309,14 @@ FLUID_DEPRECATED FLUIDSYNTH_API int fluid_synth_nwrite_float(fluid_synth_t *synt FLUIDSYNTH_API int fluid_synth_process(fluid_synth_t *synth, int len, int nfx, float *fx[], int nout, float *out[]); - -/* @} */ +/* @} Audio Rendering */ /** - * @defgroup SynthSoundFontLoader SoundFont Loader - * @brief Synthesizer's interface to handle SoundFont loaders + * @defgroup iir_filter Effect - IIR Filter + * @ingroup synth * - * @{ - */ - -FLUIDSYNTH_API void fluid_synth_add_sfloader(fluid_synth_t *synth, fluid_sfloader_t *loader); -FLUIDSYNTH_API fluid_voice_t *fluid_synth_alloc_voice(fluid_synth_t *synth, - fluid_sample_t *sample, - int channum, int key, int vel); -FLUIDSYNTH_API void fluid_synth_start_voice(fluid_synth_t *synth, fluid_voice_t *voice); -FLUIDSYNTH_API void fluid_synth_get_voicelist(fluid_synth_t *synth, - fluid_voice_t *buf[], int bufsize, int ID); -FLUIDSYNTH_API int fluid_synth_handle_midi_event(void *data, fluid_midi_event_t *event); - -/* @} */ - - -/** - * @defgroup CustomIIR IIR Filter - * @ingroup Effects + * Functions for configuring the built-in IIR filter effect * * @{ */ @@ -413,29 +343,43 @@ enum fluid_iir_filter_flags }; FLUIDSYNTH_API int fluid_synth_set_custom_filter(fluid_synth_t *, int type, int flags); +/* @} IIR Filter */ + -/* @} */ /** - * @addtogroup LADSPA - * @ingroup Effects + * @defgroup channel_setup MIDI Channel Setup + * @ingroup synth * - * @{ - */ -FLUIDSYNTH_API fluid_ladspa_fx_t *fluid_synth_get_ladspa_fx(fluid_synth_t *synth); -/* @} */ - - -/** - * @defgroup ChannelModes Channel modes - * @ingroup Synth + * The functions in this section provide interfaces to change the channel type + * and to configure basic channels, legato and portamento setups. * * @{ */ -/** Interface to poly/mono mode variables - * +/** @name Channel Type + * @{ + */ + +/** + * The midi channel type used by fluid_synth_set_channel_type() + */ +enum fluid_midi_channel_type +{ + CHANNEL_TYPE_MELODIC = 0, /**< Melodic midi channel */ + CHANNEL_TYPE_DRUM = 1 /**< Drum midi channel */ +}; + +FLUIDSYNTH_API int fluid_synth_set_channel_type(fluid_synth_t *synth, int chan, int type); +/** @} Channel Type */ + + +/** @name Basic Channel Mode + * @{ + */ + +/** * Channel mode bits OR-ed together so that it matches with the midi spec: poly omnion (0), mono omnion (1), poly omnioff (2), mono omnioff (3) */ enum fluid_channel_mode_flags @@ -444,15 +388,9 @@ enum fluid_channel_mode_flags FLUID_CHANNEL_OMNI_OFF = 0x02, /**< if flag is set, the basic channel is in omni off state, if not set omni is on */ }; -/** Indicates the breath mode a channel is set to */ -enum fluid_channel_breath_flags -{ - FLUID_CHANNEL_BREATH_POLY = 0x10, /**< when channel is poly, this flag indicates that the default velocity to initial attenuation modulator is replaced by a breath to initial attenuation modulator */ - FLUID_CHANNEL_BREATH_MONO = 0x20, /**< when channel is mono, this flag indicates that the default velocity to initial attenuation modulator is replaced by a breath modulator */ - FLUID_CHANNEL_BREATH_SYNC = 0x40, /**< when channel is mono, this flag indicates that the breath controller(MSB)triggers noteon/noteoff on the running note */ -}; - -/** Indicates the mode a basic channel is set to */ +/** + * Indicates the mode a basic channel is set to + */ enum fluid_basic_channel_modes { FLUID_CHANNEL_MODE_MASK = (FLUID_CHANNEL_OMNI_OFF | FLUID_CHANNEL_POLY_OFF), /**< Mask Poly and Omni bits of #fluid_channel_mode_flags, usually only used internally */ @@ -471,8 +409,13 @@ FLUIDSYNTH_API int fluid_synth_get_basic_channel(fluid_synth_t *synth, int chan int *basic_val_out); FLUIDSYNTH_API int fluid_synth_set_basic_channel(fluid_synth_t *synth, int chan, int mode, int val); -/** Interface to mono legato mode - * +/** @} Basic Channel Mode */ + +/** @name Legato Mode + * @{ + */ + +/** * Indicates the legato mode a channel is set to * n1,n2,n3,.. is a legato passage. n1 is the first note, and n2,n3,n4 are played legato with previous note. */ enum fluid_channel_legato_mode @@ -484,9 +427,13 @@ enum fluid_channel_legato_mode FLUIDSYNTH_API int fluid_synth_set_legato_mode(fluid_synth_t *synth, int chan, int legatomode); FLUIDSYNTH_API int fluid_synth_get_legato_mode(fluid_synth_t *synth, int chan, int *legatomode); +/** @} Legato Mode */ -/** Interface to portamento mode - * +/** @name Portamento Mode + * @{ + */ + +/** * Indicates the portamento mode a channel is set to */ enum fluid_channel_portamento_mode @@ -494,21 +441,61 @@ enum fluid_channel_portamento_mode FLUID_CHANNEL_PORTAMENTO_MODE_EACH_NOTE, /**< Mode 0 - Portamento on each note (staccato or legato) */ FLUID_CHANNEL_PORTAMENTO_MODE_LEGATO_ONLY, /**< Mode 1 - Portamento only on legato note */ FLUID_CHANNEL_PORTAMENTO_MODE_STACCATO_ONLY, /**< Mode 2 - Portamento only on staccato note */ - FLUID_CHANNEL_PORTAMENTO_MODE_LAST /**< @internal Value defines the count of portamento modes (#fluid_channel_portamento_mode) @warning This symbol is not part of the public API and ABI stability guarantee and may change at any time! */ + FLUID_CHANNEL_PORTAMENTO_MODE_LAST /**< @internal Value defines the count of portamento modes + @warning This symbol is not part of the public API and ABI + stability guarantee and may change at any time! */ }; FLUIDSYNTH_API int fluid_synth_set_portamento_mode(fluid_synth_t *synth, int chan, int portamentomode); FLUIDSYNTH_API int fluid_synth_get_portamento_mode(fluid_synth_t *synth, int chan, int *portamentomode); +/** @} Portamento Mode */ + +/**@name Breath Mode + * @{ + */ + +/** + * Indicates the breath mode a channel is set to + */ +enum fluid_channel_breath_flags +{ + FLUID_CHANNEL_BREATH_POLY = 0x10, /**< when channel is poly, this flag indicates that the default velocity to initial attenuation modulator is replaced by a breath to initial attenuation modulator */ + FLUID_CHANNEL_BREATH_MONO = 0x20, /**< when channel is mono, this flag indicates that the default velocity to initial attenuation modulator is replaced by a breath modulator */ + FLUID_CHANNEL_BREATH_SYNC = 0x40, /**< when channel is mono, this flag indicates that the breath controller(MSB)triggers noteon/noteoff on the running note */ +}; -/* Interface to breath mode */ FLUIDSYNTH_API int fluid_synth_set_breath_mode(fluid_synth_t *synth, int chan, int breathmode); FLUIDSYNTH_API int fluid_synth_get_breath_mode(fluid_synth_t *synth, int chan, int *breathmode); +/** @} Breath Mode */ +/* @} MIDI Channel Setup */ -/* @} */ + +/** @ingroup settings */ +FLUIDSYNTH_API fluid_settings_t *fluid_synth_get_settings(fluid_synth_t *synth); + +/** @ingroup soundfont_loader */ +FLUIDSYNTH_API void fluid_synth_add_sfloader(fluid_synth_t *synth, fluid_sfloader_t *loader); + +/** @ingroup soundfont_loader */ +FLUIDSYNTH_API fluid_preset_t *fluid_synth_get_channel_preset(fluid_synth_t *synth, int chan); + +/** @ingroup midi_input */ +FLUIDSYNTH_API int fluid_synth_handle_midi_event(void *data, fluid_midi_event_t *event); + +/** @ingroup soundfonts */ +FLUIDSYNTH_API +int fluid_synth_pin_preset(fluid_synth_t *synth, int sfont_id, int bank_num, int preset_num); + +/** @ingroup soundfonts */ +FLUIDSYNTH_API +int fluid_synth_unpin_preset(fluid_synth_t *synth, int sfont_id, int bank_num, int preset_num); + +/** @ingroup ladspa */ +FLUIDSYNTH_API fluid_ladspa_fx_t *fluid_synth_get_ladspa_fx(fluid_synth_t *synth); #ifdef __cplusplus } diff --git a/include/fluidsynth/version.h.in b/include/fluidsynth/version.h.in index 34db6ea7..6eee0b5d 100644 --- a/include/fluidsynth/version.h.in +++ b/include/fluidsynth/version.h.in @@ -31,7 +31,6 @@ extern "C" { * * @{ */ - #define FLUIDSYNTH_VERSION @FLUIDSYNTH_VERSION@ /**< String constant of libfluidsynth version. */ #define FLUIDSYNTH_VERSION_MAJOR @FLUIDSYNTH_VERSION_MAJOR@ /**< libfluidsynth major version integer constant. */ #define FLUIDSYNTH_VERSION_MINOR @FLUIDSYNTH_VERSION_MINOR@ /**< libfluidsynth minor version integer constant. */ @@ -39,7 +38,6 @@ extern "C" { FLUIDSYNTH_API void fluid_version(int *major, int *minor, int *micro); FLUIDSYNTH_API char* fluid_version_str(void); - /* @} */ #ifdef __cplusplus diff --git a/src/bindings/fluid_ladspa.c b/src/bindings/fluid_ladspa.c index 5f68de4a..65587f36 100644 --- a/src/bindings/fluid_ladspa.c +++ b/src/bindings/fluid_ladspa.c @@ -227,15 +227,16 @@ error_recovery: } /** - * Destroys and frees a LADSPA effects unit previously created - * with new_fluid_ladspa_fx. + * Destroy and free a LADSPA effects unit previously created + * with new_fluid_ladspa_fx(). + * + * @param fx LADSPA effects instance * * @note This function does not check the engine state for * possible users, so make sure that you only call this * if you are sure nobody is using the engine anymore (especially * that nobody calls fluid_ladspa_run) * - * @param fx LADSPA effects instance */ void delete_fluid_ladspa_fx(fluid_ladspa_fx_t *fx) { @@ -268,15 +269,16 @@ void delete_fluid_ladspa_fx(fluid_ladspa_fx_t *fx) /** * Add host buffers to the LADSPA engine. * - * @note The size of the buffers pointed to by the buffers array must be - * at least as large as the buffer size given to new_fluid_ladspa_fx. - * * @param fx LADSPA fx instance * @param prefix common name prefix for the created nodes * @param num_buffers number of of buffers buffer array * @param buffers array of sample buffers * @param buf_stride number of samples contained in one buffer * @return FLUID_OK on success, otherwise FLUID_FAILED + * + * @note The size of the buffers pointed to by the buffers array must be + * at least as large as the buffer size given to new_fluid_ladspa_fx. + * */ int fluid_ladspa_add_host_ports(fluid_ladspa_fx_t *fx, const char *prefix, int num_buffers, fluid_real_t buffers[], int buf_stride) @@ -319,12 +321,13 @@ int fluid_ladspa_add_host_ports(fluid_ladspa_fx_t *fx, const char *prefix, /** * Set the sample rate of the LADSPA effects. * - * Resets the LADSPA effects if the sample rate is different from the - * previous sample rate. - * * @param fx LADSPA fx instance * @param sample_rate new sample rate * @return FLUID_OK on success, otherwise FLUID_FAILED + * + * Resets the LADSPA effects if the sample rate is different from the + * previous sample rate. + * */ int fluid_ladspa_set_sample_rate(fluid_ladspa_fx_t *fx, fluid_real_t sample_rate) { @@ -357,13 +360,13 @@ int fluid_ladspa_set_sample_rate(fluid_ladspa_fx_t *fx, fluid_real_t sample_rate /** * Check if the LADSPA engine is currently used to render audio * + * @param fx LADSPA fx instance + * @return TRUE if LADSPA effects engine is active, otherwise FALSE + * * If an engine is active, the only allowed user actions are deactivation or * setting values of control ports on effects. Anything else, especially * adding or removing effects, buffers or ports, is only allowed in deactivated * state. - * - * @param fx LADSPA fx instance - * @return TRUE if LADSPA effects engine is active, otherwise FALSE */ int fluid_ladspa_is_active(fluid_ladspa_fx_t *fx) { @@ -424,10 +427,10 @@ int fluid_ladspa_activate(fluid_ladspa_fx_t *fx) /** * Deactivate a LADSPA fx instance and all configured effects. * - * @note This function may sleep. - * * @param fx LADSPA fx instance * @return FLUID_OK if deactivation succeeded, otherwise FLUID_FAILED + * + * @note This function may sleep. */ int fluid_ladspa_deactivate(fluid_ladspa_fx_t *fx) { @@ -468,11 +471,13 @@ int fluid_ladspa_deactivate(fluid_ladspa_fx_t *fx) } /** - * Reset the LADSPA effects engine: Deactivate LADSPA if currently active, remove all - * effects, remove all user nodes and unload all libraries. + * Reset the LADSPA effects engine. * * @param fx LADSPA fx instance * @return FLUID_OK on success, otherwise FLUID_FAILED + * + * Deactivate LADSPA if currently active, remove all + * effects, remove all user nodes and unload all libraries. */ int fluid_ladspa_reset(fluid_ladspa_fx_t *fx) { @@ -496,15 +501,15 @@ int fluid_ladspa_reset(fluid_ladspa_fx_t *fx) /** * Processes audio data via the LADSPA effects unit. * + * @param fx LADSPA effects instance + * @param block_count number of blocks to render + * @param block_size number of samples in a block + * * FluidSynth calls this function during main output mixing, just after * the internal reverb and chorus effects have been processed. * * It copies audio data from the supplied buffers, runs all effects and copies the * resulting audio back into the same buffers. - * - * @param fx LADSPA effects instance - * @param block_count number of blocks to render - * @param block_size number of samples in a block */ void fluid_ladspa_run(fluid_ladspa_fx_t *fx, int block_count, int block_size) { @@ -862,7 +867,7 @@ int fluid_ladspa_effect_set_control(fluid_ladspa_fx_t *fx, const char *effect_na } /** - * Create an effect, i.e. an instance of a LADSPA plugin + * Create an instance of a LADSPA plugin as an effect * * @param fx LADSPA effects instance * @param effect_name name of the effect @@ -922,14 +927,14 @@ int fluid_ladspa_add_effect(fluid_ladspa_fx_t *fx, const char *effect_name, /** * Connect an effect port to a host port or buffer * - * @note There is no corresponding disconnect function. If the connections need to be changed, - * clear everything with fluid_ladspa_reset and start again from scratch. - * * @param fx LADSPA effects instance * @param effect_name name of the effect * @param port_name the port name to connect to (case-insensitive prefix match) * @param name the host port or buffer to connect to (case-insensitive) * @return FLUID_OK on success, otherwise FLUID_FAILED + * + * @note There is no corresponding disconnect function. If the connections need to be changed, + * clear everything with fluid_ladspa_reset and start again from scratch. */ int fluid_ladspa_effect_link(fluid_ladspa_fx_t *fx, const char *effect_name, const char *port_name, const char *name) @@ -1009,13 +1014,13 @@ int fluid_ladspa_effect_link(fluid_ladspa_fx_t *fx, const char *effect_name, /** * Do a sanity check for problems in the LADSPA setup * - * If the check detects problems and the err pointer is not NULL, a description of the first found - * problem is written to that string (up to err_size - 1 characters). - * * @param fx LADSPA fx instance * @param err externally provided buffer for the error message. Set to NULL if you don't need an error message. * @param err_size size of the err buffer * @return FLUID_OK if setup is valid, otherwise FLUID_FAILED (err will contain the error message) + * + * If the check detects problems and the err pointer is not NULL, a description of the first found + * problem is written to that string (up to err_size - 1 characters). */ int fluid_ladspa_check(fluid_ladspa_fx_t *fx, char *err, int err_size) { @@ -1139,13 +1144,13 @@ static fluid_ladspa_node_t *get_node(fluid_ladspa_fx_t *fx, const char *name) /** * Return a LADSPA effect port index by name, using a 'fuzzy match'. * - * Returns the first effect port which matches the name. If no exact match is - * found, returns the port that starts with the specified name, but only if there is - * only one such match. - * * @param effect pointer to fluid_ladspa_effect_t * @param name the port name * @return index of the port in the effect or -1 on error + * + * Returns the first effect port which matches the name. If no exact match is + * found, returns the port that starts with the specified name, but only if there is + * only one such match. */ static int get_effect_port_idx(const fluid_ladspa_effect_t *effect, const char *name) { @@ -1178,11 +1183,11 @@ static int get_effect_port_idx(const fluid_ladspa_effect_t *effect, const char * /** * Return a LADSPA descriptor structure for a plugin in a LADSPA library. * - * If name is optional if the library contains only one plugin. - * * @param lib pointer to the dynamically loaded library * @param name name (LADSPA Label) of the plugin * @return pointer to LADSPA_Descriptor, NULL on error or if not found + * + * The name is optional if the library contains only one plugin. */ static const LADSPA_Descriptor *get_plugin_descriptor(fluid_module_t *lib, const char *name) { @@ -1233,13 +1238,13 @@ static const LADSPA_Descriptor *get_plugin_descriptor(fluid_module_t *lib, const * Instantiate a LADSPA plugin from a library and set up the associated * control structures needed by the LADSPA fx engine. * - * If the library contains only one plugin, then the name is optional. - * Plugins are identified by their "Label" in the plugin descriptor structure. - * * @param fx LADSPA fx instance * @param lib_name file path of the plugin library * @param plugin_name (optional) string name of the plugin (the LADSPA Label) * @return pointer to the new ladspa_plugin_t structure or NULL on error + * + * If the library contains only one plugin, then the name is optional. + * Plugins are identified by their "Label" in the plugin descriptor structure. */ static fluid_ladspa_effect_t * new_fluid_ladspa_effect(fluid_ladspa_fx_t *fx, const char *lib_name, const char *plugin_name) diff --git a/src/sfloader/fluid_sffile.c b/src/sfloader/fluid_sffile.c index d03ca033..339de53f 100644 --- a/src/sfloader/fluid_sffile.c +++ b/src/sfloader/fluid_sffile.c @@ -331,10 +331,11 @@ static int fluid_sffile_read_wav(SFData *sf, unsigned int start, unsigned int en /** * Check if a file is a SoundFont file. * - * If fluidsynth was built with DLS support, this function will also identify DLS files. * @param filename Path to the file to check * @return TRUE if it could be a SF2, SF3 or DLS file, FALSE otherwise * + * If fluidsynth was built with DLS support, this function will also identify DLS files. + * * @note This function only checks whether header(s) in the RIFF chunk are present. * A call to fluid_synth_sfload() might still fail. */ diff --git a/src/synth/fluid_synth.c b/src/synth/fluid_synth.c index c3863f9f..bf3ac21a 100644 --- a/src/synth/fluid_synth.c +++ b/src/synth/fluid_synth.c @@ -600,7 +600,7 @@ static FLUID_INLINE unsigned int fluid_synth_get_min_note_length_LOCAL(fluid_syn * @note The @p settings parameter is used directly and should freed after * the synth has been deleted. Further note that you may modify FluidSettings of the * @p settings instance. However, only those FluidSettings marked as 'realtime' will - * affect the synth immediately. + * affect the synth immediately. See the \ref fluidsettings for more details. */ fluid_synth_t * new_fluid_synth(fluid_settings_t *settings) @@ -3461,7 +3461,8 @@ fluid_synth_program_reset(fluid_synth_t *synth) } /** - * Synthesize a block of floating point audio to separate audio buffers (multichannel rendering). First effect channel used by reverb, second for chorus. + * Synthesize a block of floating point audio to separate audio buffers (multi-channel rendering). + * * @param synth FluidSynth instance * @param len Count of audio frames to synthesize * @param left Array of float buffers to store left channel of planar audio (as many as \c synth.audio-channels buffers, each of \c len in size) @@ -3470,9 +3471,13 @@ fluid_synth_program_reset(fluid_synth_t *synth) * @param fx_right Since 1.1.7: If not \c NULL, array of float buffers to store right effect channels (size: dito) * @return #FLUID_OK on success, #FLUID_FAILED otherwise * + * First effect channel used by reverb, second for chorus. + * * @note Should only be called from synthesis thread. * - * @deprecated fluid_synth_nwrite_float() is deprecated and will be removed in a future release. It may continue to work or it may return #FLUID_FAILED in the future. Consider using the more powerful and flexible fluid_synth_process(). + * @deprecated fluid_synth_nwrite_float() is deprecated and will be removed in a future release. + * It may continue to work or it may return #FLUID_FAILED in the future. Consider using the more + * powerful and flexible fluid_synth_process(). * * Usage example: * @code{.cpp} @@ -3484,14 +3489,17 @@ fluid_synth_program_reset(fluid_synth_t *synth) // we need twice as many (mono-)buffers channels *= 2; - // fluid_synth_nwrite_float renders planar audio, e.g. if synth.audio-channels==16: each midi channel gets rendered to its own stereo buffer, rather than having one buffer and interleaved PCM + // fluid_synth_nwrite_float renders planar audio, e.g. if synth.audio-channels==16: + // each midi channel gets rendered to its own stereo buffer, rather than having + // one buffer and interleaved PCM float** mix_buf = new float*[channels]; for(int i = 0; i < channels; i++) { mix_buf[i] = new float[FramesToRender]; } - // retrieve number of (stereo) effect channels (internally hardcoded to reverb (first chan) and chrous (second chan)) + // retrieve number of (stereo) effect channels (internally hardcoded to reverb (first chan) + // and chrous (second chan)) fluid_settings_getint(settings, "synth.effects-channels", &channels); channels *= 2; @@ -3709,7 +3717,34 @@ static FLUID_INLINE void fluid_synth_mix_single_buffer(float *FLUID_RESTRICT out } /** - * @brief Synthesize floating point audio to stereo audio channels (implements the default interface #fluid_audio_func_t). + * Synthesize floating point audio to stereo audio channels + * (implements the default interface #fluid_audio_func_t). + * + * @param synth FluidSynth instance + * + * @param len Count of audio frames to synthesize and store in every single buffer provided by \p out and \p fx. + * Zero value is permitted, the function does nothing and return FLUID_OK. + * + * @param nfx Count of arrays in \c fx. Must be a multiple of 2 (because of stereo). + * and in the range 0 <= nfx/2 <= (fluid_synth_count_effects_channels() * fluid_synth_count_effects_groups()). + * Note that zero value is valid and allows to skip mixing effects in all fx output buffers. + * + * @param fx Array of buffers to store effects audio to. Buffers may + * alias with buffers of \c out. Individual NULL buffers are permitted and will cause to skip mixing any audio into that buffer. + * + * @param nout Count of arrays in \c out. Must be a multiple of 2 + * (because of stereo) and in the range 0 <= nout/2 <= fluid_synth_count_audio_channels(). + * Note that zero value is valid and allows to skip mixing dry audio in all out output buffers. + * + * @param out Array of buffers to store (dry) audio to. Buffers may + * alias with buffers of \c fx. Individual NULL buffers are permitted and will cause to skip mixing any audio into that buffer. + * + * @return #FLUID_OK on success, + * #FLUID_FAILED otherwise, + * - fx == NULL while nfx > 0, or out == NULL while nout > 0. + * - \c nfx or \c nout not multiple of 2. + * - len < 0. + * - \c nfx or \c nout exceed the range explained above. * * Synthesize and mix audio to a given number of planar audio buffers. * Therefore pass nout = N*2 float buffers to \p out in order to render @@ -3757,26 +3792,6 @@ fx[ ((k * fluid_synth_count_effects_channels() + j) * 2 + 1) % nfx ] = right_bu * * k = chan % fluid_synth_count_effects_groups() * - * @param synth FluidSynth instance - * @param len Count of audio frames to synthesize and store in every single buffer provided by \p out and \p fx. - * Zero value is permitted, the function does nothing and return FLUID_OK. - * @param nfx Count of arrays in \c fx. Must be a multiple of 2 (because of stereo). - * and in the range 0 <= nfx/2 <= (fluid_synth_count_effects_channels() * fluid_synth_count_effects_groups()). - Note that zero value is valid and allows to skip mixing effects in all fx output buffers. - * @param fx Array of buffers to store effects audio to. Buffers may -alias with buffers of \c out. Individual NULL buffers are permitted and will cause to skip mixing any audio into that buffer. - * @param nout Count of arrays in \c out. Must be a multiple of 2 -(because of stereo) and in the range 0 <= nout/2 <= fluid_synth_count_audio_channels(). - Note that zero value is valid and allows to skip mixing dry audio in all out output buffers. - * @param out Array of buffers to store (dry) audio to. Buffers may -alias with buffers of \c fx. Individual NULL buffers are permitted and will cause to skip mixing any audio into that buffer. - * @return #FLUID_OK on success, - * #FLUID_FAILED otherwise, - * - fx == NULL while nfx > 0, or out == NULL while nout > 0. - * - \c nfx or \c nout not multiple of 2. - * - len < 0. - * - \c nfx or \c nout exceed the range explained above. - * * @parblock * @note The owner of the sample buffers must zero them out before calling this * function, because any synthesized audio is mixed (i.e. added) to the buffers. @@ -5488,6 +5503,7 @@ fluid_synth_set_reverb_preset(fluid_synth_t *synth, unsigned int num) /** * Set reverb parameters. + * * @param synth FluidSynth instance * @param roomsize Reverb room size value (0.0-1.0) * @param damping Reverb damping value (0.0-1.0) @@ -5507,7 +5523,10 @@ fluid_synth_set_reverb(fluid_synth_t *synth, double roomsize, double damping, } /** - * Set reverb roomsize. See fluid_synth_set_reverb() for further info. + * Set reverb roomsize. + * + * @param synth FluidSynth instance + * @param roomsize Reverb room size value (0.0-1.0) * @return #FLUID_OK on success, #FLUID_FAILED otherwise */ int fluid_synth_set_reverb_roomsize(fluid_synth_t *synth, double roomsize) @@ -5516,7 +5535,10 @@ int fluid_synth_set_reverb_roomsize(fluid_synth_t *synth, double roomsize) } /** - * Set reverb damping. See fluid_synth_set_reverb() for further info. + * Set reverb damping. + * + * @param synth FluidSynth instance + * @param damping Reverb damping value (0.0-1.0) * @return #FLUID_OK on success, #FLUID_FAILED otherwise */ int fluid_synth_set_reverb_damp(fluid_synth_t *synth, double damping) @@ -5525,7 +5547,10 @@ int fluid_synth_set_reverb_damp(fluid_synth_t *synth, double damping) } /** - * Set reverb width. See fluid_synth_set_reverb() for further info. + * Set reverb width. + * + * @param synth FluidSynth instance + * @param width Reverb width value (0.0-100.0) * @return #FLUID_OK on success, #FLUID_FAILED otherwise */ int fluid_synth_set_reverb_width(fluid_synth_t *synth, double width) @@ -5534,7 +5559,10 @@ int fluid_synth_set_reverb_width(fluid_synth_t *synth, double width) } /** - * Set reverb level. See fluid_synth_set_reverb() for further info. + * Set reverb level. + * + * @param synth FluidSynth instance + * @param level Reverb level value (0.0-1.0) * @return #FLUID_OK on success, #FLUID_FAILED otherwise */ int fluid_synth_set_reverb_level(fluid_synth_t *synth, double level) @@ -5544,6 +5572,7 @@ int fluid_synth_set_reverb_level(fluid_synth_t *synth, double level) /** * Set one or more reverb parameters. + * * @param synth FluidSynth instance * @param set Flags indicating which parameters should be set (#fluid_revmodel_set_t) * @param roomsize Reverb room size value (0.0-1.2) @@ -5684,8 +5713,8 @@ fluid_synth_set_chorus_on(fluid_synth_t *synth, int on) } /** - * Set chorus parameters. It should be turned on with fluid_synth_set_chorus_on(). - * Keep in mind, that the needed CPU time is proportional to 'nr'. + * Set chorus parameters. + * * @param synth FluidSynth instance * @param nr Chorus voice count (0-99, CPU time consumption proportional to * this value) @@ -5695,6 +5724,9 @@ fluid_synth_set_chorus_on(fluid_synth_t *synth, int on) * 0.0-21.0 is safe for sample-rate values up to 96KHz) * @param type Chorus waveform type (#fluid_chorus_mod) * @return #FLUID_OK on success, #FLUID_FAILED otherwise + * + * It should be turned on with fluid_synth_set_chorus_on(). + * Keep in mind, that the needed CPU time is proportional to 'nr'. */ int fluid_synth_set_chorus(fluid_synth_t *synth, int nr, double level, double speed, double depth_ms, int type) @@ -5704,7 +5736,11 @@ int fluid_synth_set_chorus(fluid_synth_t *synth, int nr, double level, } /** - * Set the chorus voice count. See fluid_synth_set_chorus() for further info. + * Set the chorus voice count. + * + * @param synth FluidSynth instance + * @param nr Chorus voice count (0-99, CPU time consumption proportional to + * this value) * @return #FLUID_OK on success, #FLUID_FAILED otherwise */ int fluid_synth_set_chorus_nr(fluid_synth_t *synth, int nr) @@ -5713,7 +5749,10 @@ int fluid_synth_set_chorus_nr(fluid_synth_t *synth, int nr) } /** - * Set the chorus level. See fluid_synth_set_chorus() for further info. + * Set the chorus level. + * + * @param synth FluidSynth instance + * @param level Chorus level (0.0-10.0) * @return #FLUID_OK on success, #FLUID_FAILED otherwise */ int fluid_synth_set_chorus_level(fluid_synth_t *synth, double level) @@ -5722,7 +5761,10 @@ int fluid_synth_set_chorus_level(fluid_synth_t *synth, double level) } /** - * Set the chorus speed. See fluid_synth_set_chorus() for further info. + * Set the chorus speed. + * + * @param synth FluidSynth instance + * @param speed Chorus speed in Hz (0.1-5.0) * @return #FLUID_OK on success, #FLUID_FAILED otherwise */ int fluid_synth_set_chorus_speed(fluid_synth_t *synth, double speed) @@ -5731,7 +5773,11 @@ int fluid_synth_set_chorus_speed(fluid_synth_t *synth, double speed) } /** - * Set the chorus depth. See fluid_synth_set_chorus() for further info. + * Set the chorus depth. + * + * @param synth FluidSynth instance + * @param depth_ms Chorus depth (max value depends on synth sample-rate, + * 0.0-21.0 is safe for sample-rate values up to 96KHz) * @return #FLUID_OK on success, #FLUID_FAILED otherwise */ int fluid_synth_set_chorus_depth(fluid_synth_t *synth, double depth_ms) @@ -5740,7 +5786,10 @@ int fluid_synth_set_chorus_depth(fluid_synth_t *synth, double depth_ms) } /** - * Set the chorus type. See fluid_synth_set_chorus() for further info. + * Set the chorus type. + * + * @param synth FluidSynth instance + * @param type Chorus waveform type (#fluid_chorus_mod) * @return #FLUID_OK on success, #FLUID_FAILED otherwise */ int fluid_synth_set_chorus_type(fluid_synth_t *synth, int type) @@ -6938,14 +6987,13 @@ fluid_ladspa_fx_t *fluid_synth_get_ladspa_fx(fluid_synth_t *synth) /** * Configure a general-purpose IIR biquad filter. * - * This is an optional, additional filter that operates independently from the default low-pass filter required by the Soundfont2 standard. - * By default this filter is off (#FLUID_IIR_DISABLED). - * * @param synth FluidSynth instance * @param type Type of the IIR filter to use (see #fluid_iir_filter_type) * @param flags Additional flags to customize this filter or zero to stay with the default (see #fluid_iir_filter_flags) - * * @return #FLUID_OK if the settings have been successfully applied, otherwise #FLUID_FAILED + * + * This is an optional, additional filter that operates independently from the default low-pass filter required by the Soundfont2 standard. + * By default this filter is off (#FLUID_IIR_DISABLED). */ int fluid_synth_set_custom_filter(fluid_synth_t *synth, int type, int flags) {