zdoom/fluidsynth
0
0
Fork 0
mirror of https://github.com/ZDoom/fluidsynth.git synced 2025-04-14 11:50:58 +00:00
Code Issues Projects Releases Packages Wiki Activity

Structure the large synth header into subgroups

Browse source 
Also include version.h and ladspa.h in the Synthesizer group.
This commit is contained in:
Marcus Weseloh 2020-11-12 21:11:42 +01:00
parent 4ea5d64eb7
commit a9135faf70
6 changed files with 292 additions and 253 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
include/fluidsynth/ladspa.h
View file

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

323
include/fluidsynth/synth.h
View file

@ -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
}

2
include/fluidsynth/version.h.in
View file

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

77
src/bindings/fluid_ladspa.c
View file

@ -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)

3
src/sfloader/fluid_sffile.c
View file

@ -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.
*/

130
src/synth/fluid_synth.c
View file

@ -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 <code>0 <= nfx/2 <= (fluid_synth_count_effects_channels() * fluid_synth_count_effects_groups())</code>.
* 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 <code>0 <= nout/2 <= fluid_synth_count_audio_channels()</code>.
* 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,
* - <code>fx == NULL</code> while <code>nfx > 0</code>, or <code>out == NULL</code> while <code>nout > 0</code>.
* - \c nfx or \c nout not multiple of 2.
* - <code>len < 0</code>.
* - \c nfx or \c nout exceed the range explained above.
*
* Synthesize and <strong>mix</strong> audio to a given number of planar audio buffers.
* Therefore pass <code>nout = N*2</code> 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
*
* <code>k = chan % fluid_synth_count_effects_groups()</code>
*
* @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 <code>0 <= nfx/2 <= (fluid_synth_count_effects_channels() * fluid_synth_count_effects_groups())</code>.
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 <code>0 <= nout/2 <= fluid_synth_count_audio_channels()</code>.
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,
* - <code>fx == NULL</code> while <code>nfx > 0</code>, or <code>out == NULL</code> while <code>nout > 0</code>.
* - \c nfx or \c nout not multiple of 2.
* - <code>len < 0</code>.
* - \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)
{