zdoom/fluidsynth
0
0
Fork 0
mirror of https://github.com/ZDoom/fluidsynth.git synced 2024-11-27 06:22:06 +00:00
Code Issues Projects Releases Packages Wiki Activity

cleanup 2.0 API docs

Browse source 
* remove obsolete 1.1.* change history
* increase readability of 2.0 changes
This commit is contained in:
derselbst 2018-05-18 16:28:09 +02:00
parent b07599b6f7
commit b375070768
3 changed files with 51 additions and 224 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
doc/Doxyfile
View file

@ -82,7 +82,7 @@ WARN_LOGFILE =
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = ../doc/fluidsynth-v11-devdoc.txt ../include ../include/fluidsynth ../src
INPUT = ../doc/fluidsynth-v20-devdoc.txt ../include ../include/fluidsynth ../src
INPUT_ENCODING = UTF-8
FILE_PATTERNS = *.c *.h
RECURSIVE = YES

2
doc/Doxyfile.cmake
View file

@ -82,7 +82,7 @@ WARN_LOGFILE =
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = @CMAKE_SOURCE_DIR@/doc/fluidsynth-v11-devdoc.txt @CMAKE_SOURCE_DIR@/include @CMAKE_SOURCE_DIR@/include/fluidsynth @CMAKE_SOURCE_DIR@/src @CMAKE_BINARY_DIR@/include/fluidsynth
INPUT = @CMAKE_SOURCE_DIR@/doc/fluidsynth-v20-devdoc.txt @CMAKE_SOURCE_DIR@/include @CMAKE_SOURCE_DIR@/include/fluidsynth @CMAKE_SOURCE_DIR@/src @CMAKE_BINARY_DIR@/include/fluidsynth
INPUT_ENCODING = UTF-8
FILE_PATTERNS = *.c *.h
RECURSIVE = YES

271
doc/fluidsynth-v11-devdoc.txt → doc/fluidsynth-v20-devdoc.txt
View file

@ -22,16 +22,6 @@ All the source code examples in this document are in the public domain; you can
- \ref Disclaimer
- \ref Introduction
- \ref NewIn2_0_0
- \ref NewIn1_1_9
- \ref NewIn1_1_8
- \ref NewIn1_1_7
- \ref NewIn1_1_6
- \ref NewIn1_1_5
- \ref NewIn1_1_4
- \ref NewIn1_1_3
- \ref NewIn1_1_2
- \ref NewIn1_1_1
- \ref NewIn1_1_0
- \ref CreatingSettings
- \ref CreatingSynth
- \ref CreatingAudioDriver
@ -71,10 +61,57 @@ What is FluidSynth?
\section NewIn2_0_0 Whats new in 2.0.0?
FluidSynths SOVERSION was bumped. The API was reworked, deprecated functions were removed.
FluidSynths major version was bumped. The API was reworked, deprecated functions were removed.
Changes in FluidSynth 2.0.0 concerning developers:
<strong><span style="color:red">Important changes that may not result in a compilation error but may cause your app to misbehave:</span></strong>
- all public \c fluid_settings_* functions that return an integer which is not meant to be interpreted as bool consistently return either FLUID_OK or FLUID_FAILED
- explicit client unregistering is required for fluid_sequencer_register_client() and fluid_sequencer_register_fluidsynth()
- all public functions consistently receive signed integers for soundfont ids, bank and program numbers
- use unique device names for the "audio.portaudio.device" setting
<strong>Other changes in FluidSynth 2.0.0 concerning developers:</strong>
- all public \c delete_* functions return void and are safe when called with NULL
- the shell command handler was decoupled internally, as a consequence the param list of new_fluid_server() and new_fluid_cmd_handler() was adapted
- reverb: roomsize is now limited to an upper threshold of 1.0 to avoid exponential volume increase
- rename fluid_mod_new() and fluid_mod_delete() to match naming conventions: new_fluid_mod() and delete_fluid_mod()
- rename chorus getters to match naming conventions: fluid_synth_get_chorus_speed() and fluid_synth_get_chorus_depth()
- fluid_synth_remove_sfont() returns FLUID_OK or FLUID_FAILED
- introduce a separate data type for sequencer client IDs: #fluid_seq_id_t
<strong>New Features and API additions:</strong>
- add <a href="fluidsettings.xml#midi.autoconnect">"midi.autoconnect"</a> a setting for automatically connecting fluidsynth to available MIDI input ports
- add <a href="fluidsettings.xml#synth.overflow.important">"synth.overflow.important"</a> and <a href="fluidsettings.xml#synth.overflow.important-channels">"synth.overflow.important-channels"</a> settings to take midi channels during overflow calculation into account that are considered to be "important"
- add <a href="fluidsettings.xml#synth.dynamic-sample-loading">"synth.dynamic-sample-loading"</a> a setting for enabling on demand sample loading
- add support for polyphonic key pressure events, see fluid_event_key_pressure() and fluid_synth_key_pressure()
- add fluid_synth_add_default_mod() and fluid_synth_remove_default_mod() for manipulating default modulators
- add individual reverb setters: fluid_synth_set_reverb_roomsize(), fluid_synth_set_reverb_damp(), fluid_synth_set_reverb_width(), fluid_synth_set_reverb_level()
- add individual chorus setters: fluid_synth_set_chorus_nr(), fluid_synth_set_chorus_level(), fluid_synth_set_chorus_speed(), fluid_synth_set_chorus_depth(), fluid_synth_set_chorus_type()
- add realtime settings for <a href="fluidsettings.xml#synth.reverb.damp">reverb</a> and <a href="fluidsettings.xml#synth.chorus.depth">chorus</a> parameters
- add seek support to midi-player, see fluid_player_seek()
- expose functions to manipulate the ladspa effects unit (see ladspa.h)
- add support for text and lyrics midi events, see fluid_midi_event_set_lyrics() and fluid_midi_event_set_text()
- complete rewrite of the soundfont loader API, see sfont.h
- support for 24 bit audio samples, see fluid_sample_set_sound_data()
- expose new_fluid_defsfloader() to support loading soundfonts from memory, see fluid_sfloader_set_callbacks() and <a href="fluidsynth_sfload_mem_8c-example.html">fluidsynth_sfload_mem.c</a>
- remove these structs from the public API and provide proper getter and setter functions instead:
- struct _fluid_sfloader_t
- struct _fluid_sample_t
- struct _fluid_sfont_t
- struct _fluid_preset_t
- add an additional general-purpose IIR filter, see fluid_synth_set_custom_filter()
- add a custom sinusoidal modulator mapping function, see #FLUID_MOD_SIN
- implement polymono support according to MIDI specs:
- add basic channel support, see fluid_synth_reset_basic_channel(), fluid_synth_set_basic_channel(), fluid_synth_get_basic_channel()
- implement MIDI modes Omni On, Omni Off, Poly, Mono, see #fluid_basic_channel_modes
- implement portamento control, see fluid_synth_set_portamento_mode(), fluid_synth_get_portamento_mode()
- implement legato control, see fluid_synth_set_legato_mode(), fluid_synth_get_legato_mode()
- implement breath control, see fluid_synth_set_breath_mode(), fluid_synth_get_breath_mode()
<strong>API cleanups:</strong>
- remove deprecated fluid_synth_get_channel_info() in favour of fluid_synth_get_program() and fluid_synth_get_channel_preset()
- remove deprecated fluid_settings_getstr()
- remove deprecated fluid_synth_set_midi_router(), instead supply the midi-router instance when creating a command handler with new_fluid_cmd_handler()
@ -99,216 +136,6 @@ Changes in FluidSynth 2.0.0 concerning developers:
- LAST_LOG_LEVEL
- FLUID_SEQ_LASTEVENT
- FLUID_MIDI_ROUTER_RULE_COUNT
<br /><br />
- all public \c fluid_settings_* functions that return an integer which is not meant to be interpreted as bool consistently return either FLUID_OK or FLUID_FAILED
- all public delete_* functions return void and are safe when called with NULL
- all public functions consistently receive signed integers for soundfont ids, bank and program numbers
- explicit client unregistering is required for fluid_sequencer_register_client() and fluid_sequencer_register_fluidsynth()
- the shell command handler was decoupled internally, as a consequence the param list of new_fluid_server() and new_fluid_cmd_handler() was adapted
- reverb: roomsize is now limited to an upper threshold of 1.0 to avoid exponential volume increase
- use unique device names for the "audio.portaudio.device" setting
- rename fluid_mod_new() and fluid_mod_delete() to match naming conventions: new_fluid_mod() and delete_fluid_mod()
- rename chorus getters to match naming conventions: fluid_synth_get_chorus_speed() and fluid_synth_get_chorus_depth()
- fluid_synth_remove_sfont() returns FLUID_OK or FLUID_FAILED
<br /><br />
- add <a href="fluidsettings.xml#midi.autoconnect">"midi.autoconnect"</a> a setting for automatically connecting fluidsynth to available MIDI input ports
- add <a href="fluidsettings.xml#synth.overflow.important">"synth.overflow.important"</a> and <a href="fluidsettings.xml#synth.overflow.important-channels">"synth.overflow.important-channels"</a> settings to take midi channels during overflow calculation into account that are considered to be "important"
- add <a href="fluidsettings.xml#synth.dynamic-sample-loading">"synth.dynamic-sample-loading"</a> a setting for enabling on demand sample loading
- add support for polyphonic key pressure events, see fluid_event_key_pressure() and fluid_synth_key_pressure()
- add fluid_synth_add_default_mod() and fluid_synth_remove_default_mod() for manipulating default modulators
- add individual reverb setters: fluid_synth_set_reverb_roomsize(), fluid_synth_set_reverb_damp(), fluid_synth_set_reverb_width(), fluid_synth_set_reverb_level()
- add individual chorus setters: fluid_synth_set_chorus_nr(), fluid_synth_set_chorus_level(), fluid_synth_set_chorus_speed(), fluid_synth_set_chorus_depth(), fluid_synth_set_chorus_type()
- add realtime settings for <a href="fluidsettings.xml#synth.reverb.damp">reverb</a> and <a href="fluidsettings.xml#synth.chorus.depth">chorus</a> parameters
- introduce a separate data type for sequencer client IDs: #fluid_seq_id_t
- add seek support to midi-player, see fluid_player_seek()
- expose functions to manipulate the ladspa effects unit (see ladspa.h)
- add support for text and lyrics midi events, see fluid_midi_event_set_lyrics() and fluid_midi_event_set_text()
- complete rewrite of the soundfont loader API, see sfont.h
- support for 24 bit audio samples, see fluid_sample_set_sound_data()
- expose new_fluid_defsfloader() to support loading soundfonts from memory, see fluid_sfloader_set_callbacks() and <a href="fluidsynth_sfload_mem_8c-example.html">fluidsynth_sfload_mem.c</a>
- remove these structs from the public API and provide proper getter and setter functions instead:
- struct _fluid_sfloader_t
- struct _fluid_sample_t
- struct _fluid_sfont_t
- struct _fluid_preset_t
- add an additional general-purpose IIR filter, see fluid_synth_set_custom_filter()
- add a custom sinusoidal modulator mapping function, see #FLUID_MOD_SIN
- implement polymono support according to MIDI specs:
- add basic channel support, see fluid_synth_reset_basic_channel(), fluid_synth_set_basic_channel(), fluid_synth_get_basic_channel()
- implement MIDI modes Omni On, Omni Off, Poly, Mono, see #fluid_basic_channel_modes
- implement portamento control, see fluid_synth_set_portamento_mode(), fluid_synth_get_portamento_mode()
- implement legato control, see fluid_synth_set_legato_mode(), fluid_synth_get_legato_mode()
- implement breath control, see fluid_synth_set_breath_mode(), fluid_synth_get_breath_mode()
\section NewIn1_1_9 Whats new in 1.1.9?
Changes in FluidSynth 1.1.9 concerning developers:
- add a function for registering audio drivers based on acutal needs: fluid_audio_driver_register()
- implement handling of #FLUID_SEQ_ALLSOUNDSOFF events in fluid_seq_fluidsynth_callback()
- fix return value of fluid_file_set_encoding_quality()
- For a full list of bug fixes, see
https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-119
\section NewIn1_1_8 Whats new in 1.1.8?
Changes in FluidSynth 1.1.8 concerning developers:
- fluid_synth_get_channel_preset() is not deprecated anymore
- deprecate fluid_synth_get_channel_info()
- deprecate fluid_synth_set_midi_router()
- deprecate redundant tuning functions
- deprecate fluid_gen_set_default_values()
- deprecate struct _fluid_mod_t, use the respective getter and setter functions
- For a full list of bug fixes, see
https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-118
\section NewIn1_1_7 Whats new in 1.1.7?
Changes in FluidSynth 1.1.7 concerning developers:
- "synth.parallel-render" has been deprecated
- fluid_synth_set_channel_type() was not exported properly
- "audio.jack.multi" had inverse logic
- fluid_synth_write_*() had timing issues when requesting more than 64 audio frames
- reverb and chorus are routed to distinct buffers in fluid_synth_nwrite_float()
- vorbis-compressed sf3 sound fonts are supported
- the following getters have been added: fluid_voice_is_on(), fluid_voice_is_sustained(), fluid_voice_is_sostenuto(), fluid_voice_get_channel(), fluid_voice_get_key(), fluid_voice_get_actual_key(), fluid_voice_get_velocity(), fluid_voice_get_actual_velocity(), fluid_player_get_current_tick(), fluid_player_get_total_ticks(), fluid_player_get_bpm(), fluid_player_get_midi_tempo()
- the following enum values have been deprecated: \c FLUID_SEQ_LASTEVENT, \c GEN_LAST, \c LAST_LOG_LEVEL
- For a full list of bug fixes, see
https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-117
\section NewIn1_1_6 Whats new in 1.1.6?
Changes in FluidSynth 1.1.6 concerning developers:
- The player will not continue to the next song until all EOT (end of track events) have been reached.
- Enable long arguments on all platforms where getopt.h is available
- Windows: Fluidsynth.pc (pkg-config spec) is now installed.
- Mac OS X Lion: A build failure was fixed.
- For a full list of bug fixes, see
https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-116
\section NewIn1_1_5 Whats new in 1.1.5?
Changes in FluidSynth 1.1.5 concerning developers:
- A change in the Jack driver might require a newer Jack version compared to 1.1.4.
- For a full list of bug fixes, see
https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-115
\section NewIn1_1_4 Whats new in 1.1.4?
Changes in FluidSynth 1.1.4 concerning developers:
- You can now play MIDI files that reside in memory (instead of specifying a filename). See \ref MIDIPlayerMem for an example.
- A hook can be inserted for MIDI file playback, at playback time. This is done through the new fluid_player_set_playback_callback API function. You can use this to both inspect and modify MIDI events as they are being played (or add a MIDI router), just as you can for MIDI input drivers.
- Channel 10 used to be the one and only drum channel, this can now be changed using the fluid_synth_set_channel_type.
- fluid_synth_all_sounds_off and fluid_synth_all_notes_off are new public API functions. You can use them to turn notes off (i e releasing all keys, voices advance to release phase) or sounds off (more like pressing the mute button), for one channel or all channels.
- For Mac OS X users: The CoreAudio driver has been adapted to use AuHAL, and the default build style has changed to "FluidSynth.framework".
- For a full list of other enhancements and bug fixes, see
https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-114
\section NewIn1_1_3 Whats new in 1.1.3?
Changes in FluidSynth 1.1.3 concerning developers:
- There are no new API additions in 1.1.3, this is a pure bug-fix release.
For a list of bugs fixed, see
https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-113
\section NewIn1_1_2 Whats new in 1.1.2?
Changes in FluidSynth 1.1.2 concerning developers:
- Build system has switched from autotools to CMake. For more information, see
README.cmake. The autotools build system is still working, but it is
deprecated. The "winbuild" and "macbuild" directories have been dropped in
favor of CMake's ability to create project files on demand.
- Thread safety has been reworked to overcome the limitations and bugs in
version 1.1.0 and 1.1.1. There are two new settings controlling the thread
safety, synth.threadsafe-api and synth.parallel-render. More information
about these settings is in the \ref CreatingSettings section. Please look
them through and set them appropriately according to your use case.
- Voice overflow, i e what voice to kill when polyphony is exceeded, is now
configurable.
- Possibility to update polyphony and sample rate real-time. Note that
updating polyphony is not hard real-time safe, and updating sample rate will
kill all currently sounding voices.
- MIDI Bank Select handling is now configurable. See the synth.midi-bank-select
setting in the \ref CreatingSettings section for more information.
- Can use RealTimeKit (on Linux) to get real-time priority, if the original
attempt fails. Note that you'll need development headers for DBus to enable
this functionality.
- Shell commands for pitch bend and pitch bend range.
- PulseAudio driver: two new settings allows you to specify media role,
and control whether pulseaudio can adjust latency.
\section NewIn1_1_1 Whats new in 1.1.1?
Changes in FluidSynth 1.1.1 concerning developers:
- fluid_synth_get_channel_preset() marked as deprecated. New function
fluid_synth_get_channel_info() added which is thread safe and should replace
most uses of the older function.
- Added fluid_synth_unset_program() to unset the active preset on a channel.
\section NewIn1_1_0 Whats new in 1.1.0?
Overview of changes in FluidSynth 1.1.0 concerning developers:
- Extensive work to make FluidSynth thread safe. Previous versions had many multi-thread
issues which could lead to crashes or synthesis glitches. Some of the API additions,
deprecations and function recommended conditions of use are related to this work.
- File renderer object for rendering audio to files.
- Sequencer objects can now use the system timer or the sample clock. When using the sample
clock, events are triggered based on the current output audio sample position. This means
that MIDI is synchronized with the audio and identical output will be achieved for the same
MIDI event input.
- libsndfile support for rendering audio to different formats and file types.
- API for using the MIDI router subsystem.
- MIDI Tuning Standard functions were added for specifying whether to activate tuning changes
in realtime or not.
- SYSEX support (MIDI Tuning Standard only at the moment).
- Changed all yes/no boolean string settings to integer #FLUID_HINT_TOGGLED settings with
backwards compatibility (assignment and query of boolean values as strings).
- Many other improvements and bug fixes.
API additions:
- A file renderer can be created with new_fluid_file_renderer(), deleted with
delete_fluid_file_renderer() and a block of audio processed with fluid_file_renderer_process_block().
- Additional functions were added for using the MIDI router subsystem.
To clear all rules from a router use fluid_midi_router_clear_rules() and to set a router to default rules
use fluid_midi_router_set_default_rules().
To create a router rule use new_fluid_midi_router_rule() and to delete a rule use
delete_fluid_midi_router_rule() (seldom used). Set values of a router rule with
fluid_midi_router_rule_set_chan(), fluid_midi_router_rule_set_param1() and fluid_midi_router_rule_set_param2().
fluid_midi_router_add_rule() can be used to add a rule to a router.
- New MIDI event functions were added, including fluid_event_channel_pressure(), fluid_event_system_reset(),
and fluid_event_unregistering().
- Additional sequencer functions include fluid_sequencer_add_midi_event_to_buffer(),
fluid_sequencer_get_use_system_timer() and fluid_sequencer_process(). new_fluid_sequencer2() was added to
allow for the timer type to be specified (system or sample clock).
- The settings subsystem has some new functions for thread safety: fluid_settings_copystr() and fluid_settings_dupstr().
Also there are new convenience functions to count the number of string options for a setting: fluid_settings_option_count()
and for concatenating setting options with a separator: fluid_settings_option_concat().
- MIDI Tuning Standard functions added include: fluid_synth_activate_key_tuning(), fluid_synth_activate_octave_tuning(),
fluid_synth_activate_tuning() and fluid_synth_deactivate_tuning(). All of which provide a parameter for specifying if
tuning changes should occur in realtime (affect existing voices) or not.
- Additional synthesizer API: fluid_synth_get_sfont_by_name() to get a SoundFont by name,
fluid_synth_program_select_by_sfont_name() to select an instrument by SoundFont name/bank/program,
fluid_synth_set_gen2() for specifying additional parameters when assigning a generator value,
fluid_synth_sysex() for sending SYSEX messages to the synth and fluid_synth_get_active_voice_count() to
get the current number of active synthesis voices.
- Miscellaneous additions: fluid_player_set_loop() to set playlist loop count and fluid_player_get_status() to get current player state.
\section CreatingSettings Creating and changing the settings