sam/sfizz
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Doxygen documentation update [skip ci]

Browse source
This commit is contained in:
redtide 2020-09-05 16:14:51 +02:00
parent 0849a1b5e5
commit 19469c5c1f
3 changed files with 483 additions and 333 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
doxygen/scripts/Doxyfile.in
View file

@ -252,13 +252,8 @@ TAB_SIZE = 4
# a double escape (\\{ and \\}) # a double escape (\\{ and \\})
ALIASES = "true=<b style=\"color:blue\">true</b>" \ ALIASES = "true=<b style=\"color:blue\">true</b>" \
"false=<b style=\"color:blue\">false</b>" "false=<b style=\"color:blue\">false</b>" \
"null=<b>NULL</b>
# This tag can be used to specify a number of word-keyword mappings (TCL only).
# A mapping has the form "name=value". For example adding "class=itcl::class"
# will allow you to use the command class in the itcl::class meaning.
TCL_SUBST =
# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
# only. Doxygen will then generate output that is more tailored for C. For # only. Doxygen will then generate output that is more tailored for C. For
@ -892,7 +887,7 @@ EXCLUDE_PATTERNS =
# Note that the wildcards are matched against the file with absolute path, so to # Note that the wildcards are matched against the file with absolute path, so to
# exclude all test directories use the pattern */test/* # exclude all test directories use the pattern */test/*
EXCLUDE_SYMBOLS = EXCLUDE_SYMBOLS = SFIZZ_EXPORTED_API
# The EXAMPLE_PATH tag can be used to specify one or more files or directories # The EXAMPLE_PATH tag can be used to specify one or more files or directories
# that contain example code fragments that are included (see the \include # that contain example code fragments that are included (see the \include
@ -1103,7 +1098,7 @@ GENERATE_HTML = YES
# The default directory is: html. # The default directory is: html.
# This tag requires that the tag GENERATE_HTML is set to YES. # This tag requires that the tag GENERATE_HTML is set to YES.
HTML_OUTPUT = _api HTML_OUTPUT = html
# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
# generated HTML page (for example: .htm, .php, .asp). # generated HTML page (for example: .htm, .php, .asp).

604
src/sfizz.h
View file

@ -6,7 +6,7 @@
/** /**
@file @file
@brief sfizz public C API @brief sfizz public C API.
*/ */
#pragma once #pragma once
@ -28,11 +28,14 @@ extern "C" {
#endif #endif
/** /**
* @brief Synth handle * @brief Synth handle.
* @since 0.2.0
*/ */
typedef struct sfizz_synth_t sfizz_synth_t; typedef struct sfizz_synth_t sfizz_synth_t;
/** /**
* @brief Oversampling factor * @brief Oversampling factor
* @since 0.2.0
*/ */
typedef enum { typedef enum {
SFIZZ_OVERSAMPLING_X1 = 1, SFIZZ_OVERSAMPLING_X1 = 1,
@ -40,8 +43,10 @@ typedef enum {
SFIZZ_OVERSAMPLING_X4 = 4, SFIZZ_OVERSAMPLING_X4 = 4,
SFIZZ_OVERSAMPLING_X8 = 8 SFIZZ_OVERSAMPLING_X8 = 8
} sfizz_oversampling_factor_t; } sfizz_oversampling_factor_t;
/** /**
* @brief Processing mode * @brief Processing mode
* @since 0.4.1
*/ */
typedef enum { typedef enum {
SFIZZ_PROCESS_LIVE, SFIZZ_PROCESS_LIVE,
@ -49,47 +54,52 @@ typedef enum {
} sfizz_process_mode_t; } sfizz_process_mode_t;
/** /**
* @brief Creates a sfizz synth. This object has to be freed by the caller * @brief Creates a sfizz synth.
* using sfizz_free(). The synth by default is set at 48 kHz *
* and a maximum block size of 1024. You should change these values * This object has to be freed by the caller using sfizz_free().
* if they are not correct for your application. * The synth by default is set at 48 kHz and a maximum block size of 1024.
* You should change these values if they are not correct for your application.
* @since 0.2.0
*/ */
SFIZZ_EXPORTED_API sfizz_synth_t* sfizz_create_synth(); SFIZZ_EXPORTED_API sfizz_synth_t* sfizz_create_synth();
/** /**
* @brief Frees an existing sfizz synth. * @brief Frees an existing sfizz synth.
* @since 0.2.0
* *
* @param synth The synth to destroy. * @param synth The synth to destroy.
*/ */
SFIZZ_EXPORTED_API void sfizz_free(sfizz_synth_t* synth); SFIZZ_EXPORTED_API void sfizz_free(sfizz_synth_t* synth);
/** /**
* @brief Loads an SFZ file. The file path can be absolute or relative. All * @brief Loads an SFZ file.
* file operations for this SFZ file will be relative to the parent
* directory of the SFZ file.
* *
* @param synth The sfizz synth. * The file path can be absolute or relative. All file operations for this SFZ
* @param path A null-terminated string representing a path to an SFZ * file will be relative to the parent directory of the SFZ file.
* file. * @since 0.2.0
* *
* @return @true when file loading went OK, * @param synth The synth.
* @false if some error occured while loading. * @param path A null-terminated string representing a path to an SFZ file.
*
* @return @true when file loading went OK,
* @false if some error occured while loading.
*/ */
SFIZZ_EXPORTED_API bool sfizz_load_file(sfizz_synth_t* synth, const char* path); SFIZZ_EXPORTED_API bool sfizz_load_file(sfizz_synth_t* synth, const char* path);
/** /**
* @brief Loads an SFZ file from textual data. This accepts a virtual * @brief Loads an SFZ file from textual data.
* path name for the imaginary sfz file, which is not required to *
* exist on disk. The purpose of the virtual path is to locate * This accepts a virtual path name for the imaginary sfz file, which is not
* samples with relative paths. * required to exist on disk. The purpose of the virtual path is to locate
* samples with relative paths.
* @since 0.4.0 * @since 0.4.0
* *
* @param synth The sfizz synth. * @param synth The synth.
* @param path The virtual path of the SFZ file. * @param path The virtual path of the SFZ file.
* @param text The contents of the virtual SFZ file. * @param text The contents of the virtual SFZ file.
* *
* @return @true when file loading went OK, * @return @true when file loading went OK,
* @false if some error occured while loading. * @false if some error occured while loading.
*/ */
SFIZZ_EXPORTED_API bool sfizz_load_string(sfizz_synth_t* synth, const char* path, const char* text); SFIZZ_EXPORTED_API bool sfizz_load_string(sfizz_synth_t* synth, const char* path, const char* text);
@ -97,10 +107,11 @@ SFIZZ_EXPORTED_API bool sfizz_load_string(sfizz_synth_t* synth, const char* path
* @brief Sets the tuning from a Scala file loaded from the file system. * @brief Sets the tuning from a Scala file loaded from the file system.
* @since 0.4.0 * @since 0.4.0
* *
* @param synth The sfizz synth. * @param synth The synth.
* @param path The path to the file in Scala format. * @param path The path to the file in Scala format.
* @return @true when tuning scale loaded OK, *
* @false if some error occurred. * @return @true when tuning scale loaded OK,
* @false if some error occurred.
*/ */
SFIZZ_EXPORTED_API bool sfizz_load_scala_file(sfizz_synth_t* synth, const char* path); SFIZZ_EXPORTED_API bool sfizz_load_scala_file(sfizz_synth_t* synth, const char* path);
@ -108,10 +119,11 @@ SFIZZ_EXPORTED_API bool sfizz_load_scala_file(sfizz_synth_t* synth, const char*
* @brief Sets the tuning from a Scala file loaded from memory. * @brief Sets the tuning from a Scala file loaded from memory.
* @since 0.4.0 * @since 0.4.0
* *
* @param synth The sfizz synth. * @param synth The synth.
* @param text The contents of the file in Scala format. * @param text The contents of the file in Scala format.
* @return @true when tuning scale loaded OK, *
* @false if some error occurred. * @return @true when tuning scale loaded OK,
* @false if some error occurred.
*/ */
SFIZZ_EXPORTED_API bool sfizz_load_scala_string(sfizz_synth_t* synth, const char* text); SFIZZ_EXPORTED_API bool sfizz_load_scala_string(sfizz_synth_t* synth, const char* text);
@ -119,8 +131,8 @@ SFIZZ_EXPORTED_API bool sfizz_load_scala_string(sfizz_synth_t* synth, const char
* @brief Sets the scala root key. * @brief Sets the scala root key.
* @since 0.4.0 * @since 0.4.0
* *
* @param synth The sfizz synth. * @param synth The synth.
* @param root_key The MIDI number of the Scala root key (default 60 for C4). * @param root_key The MIDI number of the Scala root key (default 60 for C4).
*/ */
SFIZZ_EXPORTED_API void sfizz_set_scala_root_key(sfizz_synth_t* synth, int root_key); SFIZZ_EXPORTED_API void sfizz_set_scala_root_key(sfizz_synth_t* synth, int root_key);
@ -128,8 +140,9 @@ SFIZZ_EXPORTED_API void sfizz_set_scala_root_key(sfizz_synth_t* synth, int root_
* @brief Gets the scala root key. * @brief Gets the scala root key.
* @since 0.4.0 * @since 0.4.0
* *
* @param synth The sfizz synth. * @param synth The synth.
* @return The MIDI number of the Scala root key (default 60 for C4). *
* @return The MIDI number of the Scala root key (default 60 for C4).
*/ */
SFIZZ_EXPORTED_API int sfizz_get_scala_root_key(sfizz_synth_t* synth); SFIZZ_EXPORTED_API int sfizz_get_scala_root_key(sfizz_synth_t* synth);
@ -137,8 +150,8 @@ SFIZZ_EXPORTED_API int sfizz_get_scala_root_key(sfizz_synth_t* synth);
* @brief Sets the reference tuning frequency. * @brief Sets the reference tuning frequency.
* @since 0.4.0 * @since 0.4.0
* *
* @param synth The sfizz synth. * @param synth The synth.
* @param frequency The frequency which indicates where standard tuning A4 is (default 440 Hz). * @param frequency The frequency which indicates where standard tuning A4 is (default 440 Hz).
*/ */
SFIZZ_EXPORTED_API void sfizz_set_tuning_frequency(sfizz_synth_t* synth, float frequency); SFIZZ_EXPORTED_API void sfizz_set_tuning_frequency(sfizz_synth_t* synth, float frequency);
@ -146,231 +159,269 @@ SFIZZ_EXPORTED_API void sfizz_set_tuning_frequency(sfizz_synth_t* synth, float f
* @brief Gets the reference tuning frequency. * @brief Gets the reference tuning frequency.
* @since 0.4.0 * @since 0.4.0
* *
* @param synth The sfizz synth. * @param synth The synth.
* @return The frequency which indicates where standard tuning A4 is (default 440 Hz). *
* @return The frequency which indicates where standard tuning A4 is (default 440 Hz).
*/ */
SFIZZ_EXPORTED_API float sfizz_get_tuning_frequency(sfizz_synth_t* synth); SFIZZ_EXPORTED_API float sfizz_get_tuning_frequency(sfizz_synth_t* synth);
/** /**
* @brief Configure stretch tuning using a predefined parametric Railsback curve. * @brief Configure stretch tuning using a predefined parametric Railsback curve.
* A ratio 1/2 is supposed to match the average piano; 0 disables (the default). *
* A ratio 1/2 is supposed to match the average piano; 0 disables (the default).
* @since 0.4.0 * @since 0.4.0
* *
* @param synth The sfizz synth. * @param synth The synth.
* @param ratio The parameter in domain 0-1. * @param ratio The parameter in domain 0-1.
*/ */
SFIZZ_EXPORTED_API void sfizz_load_stretch_tuning_by_ratio(sfizz_synth_t* synth, float ratio); SFIZZ_EXPORTED_API void sfizz_load_stretch_tuning_by_ratio(sfizz_synth_t* synth, float ratio);
/** /**
* @brief Return the number of regions in the currently loaded SFZ file. * @brief Return the number of regions in the currently loaded SFZ file.
* @since 0.2.0
* *
* @param synth The synth. * @param synth The synth.
*/ */
SFIZZ_EXPORTED_API int sfizz_get_num_regions(sfizz_synth_t* synth); SFIZZ_EXPORTED_API int sfizz_get_num_regions(sfizz_synth_t* synth);
/** /**
* @brief Return the number of groups in the currently loaded SFZ file. * @brief Return the number of groups in the currently loaded SFZ file.
* @since 0.2.0
* *
* @param synth The synth. * @param synth The synth.
*/ */
SFIZZ_EXPORTED_API int sfizz_get_num_groups(sfizz_synth_t* synth); SFIZZ_EXPORTED_API int sfizz_get_num_groups(sfizz_synth_t* synth);
/** /**
* @brief Return the number of masters in the currently loaded SFZ file. * @brief Return the number of masters in the currently loaded SFZ file.
* @since 0.2.0
* *
* @param synth The synth. * @param synth The synth.
*/ */
SFIZZ_EXPORTED_API int sfizz_get_num_masters(sfizz_synth_t* synth); SFIZZ_EXPORTED_API int sfizz_get_num_masters(sfizz_synth_t* synth);
/** /**
* @brief Return the number of curves in the currently loaded SFZ file. * @brief Return the number of curves in the currently loaded SFZ file.
* @since 0.2.0
* *
* @param synth The synth. * @param synth The synth.
*/ */
SFIZZ_EXPORTED_API int sfizz_get_num_curves(sfizz_synth_t* synth); SFIZZ_EXPORTED_API int sfizz_get_num_curves(sfizz_synth_t* synth);
/** /**
* @brief Export a MIDI Name document describing the the currently loaded * @brief Export a MIDI Name document describing the currently loaded SFZ file.
* SFZ file. * @since 0.3.1
* *
* @param synth The synth. * @param synth The synth.
* @param model The model name used if a non-empty string, otherwise generated. * @param model The model name used if a non-empty string, otherwise generated.
* *
* @return A newly allocated XML string, which must be freed after use. * @return A newly allocated XML string, which must be freed after use.
*/ */
SFIZZ_EXPORTED_API char* sfizz_export_midnam(sfizz_synth_t* synth, const char* model); SFIZZ_EXPORTED_API char* sfizz_export_midnam(sfizz_synth_t* synth, const char* model);
/** /**
* @brief Return the number of preloaded samples for the current SFZ file. * @brief Return the number of preloaded samples for the current SFZ file.
* @since 0.2.0
* *
* @param synth The synth. * @param synth The synth.
*/ */
SFIZZ_EXPORTED_API size_t sfizz_get_num_preloaded_samples(sfizz_synth_t* synth); SFIZZ_EXPORTED_API size_t sfizz_get_num_preloaded_samples(sfizz_synth_t* synth);
/** /**
* @brief Return the number of active voices. Note that this function is a * @brief Return the number of active voices.
* basic indicator and does not aim to be perfect. In particular, it
* runs on the calling thread so voices may well start or stop while
* the function is checking which voice is active.
* *
* @param synth The synth. * Note that this function is a basic indicator and does not aim to be perfect.
* In particular, it runs on the calling thread so voices may well start or stop
* while the function is checking which voice is active.
* @since 0.2.0
*
* @param synth The synth.
*/ */
SFIZZ_EXPORTED_API int sfizz_get_num_active_voices(sfizz_synth_t* synth); SFIZZ_EXPORTED_API int sfizz_get_num_active_voices(sfizz_synth_t* synth);
/** /**
* @brief Set the expected number of samples per block. If unsure, give an * @brief Set the expected number of samples per block.
* upper bound since right now ugly things may happen if you go over
* this number.
* *
* @param synth The synth. * If unsure, give an upper bound since right now ugly things may happen if you
* @param samples_per_block The number of samples per block. * go over this number.
* @since 0.2.0
*
* @param synth The synth.
* @param samples_per_block The number of samples per block.
*/ */
SFIZZ_EXPORTED_API void sfizz_set_samples_per_block(sfizz_synth_t* synth, int samples_per_block); SFIZZ_EXPORTED_API void sfizz_set_samples_per_block(sfizz_synth_t* synth, int samples_per_block);
/** /**
* @brief Set the sample rate for the synth. This is the output sample * @brief Set the sample rate for the synth.
* rate. This setting does not affect the internal processing.
* *
* @param synth The synth * This is the output sample rate. This setting does not affect the internal processing.
* @param sample_rate The sample rate. * @since 0.2.0
*
* @param synth The synth
* @param sample_rate The sample rate.
*/ */
SFIZZ_EXPORTED_API void sfizz_set_sample_rate(sfizz_synth_t* synth, float sample_rate); SFIZZ_EXPORTED_API void sfizz_set_sample_rate(sfizz_synth_t* synth, float sample_rate);
/** /**
* @brief Send a note on event to the synth. As with all MIDI events, this * @brief Send a note on event to the synth.
* needs to happen before the call to sfizz_render_block in each
* block and should appear in order of the delays.
* *
* @param synth The synth. * As with all MIDI events, this needs to happen before the call to
* @param delay The delay of the event in the block, in samples. * sfizz_render_block() in each block and should appear in order of the delays.
* @param note_number The MIDI note number. * @since 0.2.0
* @param velocity The MIDI velocity. *
* @param synth The synth.
* @param delay The delay of the event in the block, in samples.
* @param note_number The MIDI note number.
* @param velocity The MIDI velocity.
*/ */
SFIZZ_EXPORTED_API void sfizz_send_note_on(sfizz_synth_t* synth, int delay, int note_number, char velocity); SFIZZ_EXPORTED_API void sfizz_send_note_on(sfizz_synth_t* synth, int delay, int note_number, char velocity);
/** /**
* @brief Send a note off event to the synth. As with all MIDI events, this * @brief Send a note off event to the synth.
* needs to happen before the call to sfizz_render_block in each
* block and should appear in order of the delays.
* As per the SFZ spec the velocity of note-off events is usually replaced by
* the note-on velocity.
* *
* @param synth The synth. * As with all MIDI events, this needs to happen before the call to
* @param delay The delay of the event in the block, in samples. * sfizz_render_block() in each block and should appear in order of the delays.
* @param note_number The MIDI note number. * As per the SFZ spec the velocity of note-off events is usually replaced by
* @param velocity The MIDI velocity. * the note-on velocity.
* @since 0.2.0
*
* @param synth The synth.
* @param delay The delay of the event in the block, in samples.
* @param note_number The MIDI note number.
* @param velocity The MIDI velocity.
*/ */
SFIZZ_EXPORTED_API void sfizz_send_note_off(sfizz_synth_t* synth, int delay, int note_number, char velocity); SFIZZ_EXPORTED_API void sfizz_send_note_off(sfizz_synth_t* synth, int delay, int note_number, char velocity);
/** /**
* @brief Send a CC event to the synth. As with all MIDI events, this needs * @brief Send a CC event to the synth.
* to happen before the call to sfizz_render_block in each block and
* should appear in order of the delays.
* *
* @param synth The synth. * As with all MIDI events, this needs to happen before the call to
* @param delay The delay of the event in the block, in samples. * sfizz_render_block() in each block and should appear in order of the delays.
* @param cc_number The MIDI CC number. * @since 0.2.0
* @param cc_value The MIDI CC value. *
* @param synth The synth.
* @param delay The delay of the event in the block, in samples.
* @param cc_number The MIDI CC number.
* @param cc_value The MIDI CC value.
*/ */
SFIZZ_EXPORTED_API void sfizz_send_cc(sfizz_synth_t* synth, int delay, int cc_number, char cc_value); SFIZZ_EXPORTED_API void sfizz_send_cc(sfizz_synth_t* synth, int delay, int cc_number, char cc_value);
/** /**
* @brief Send a high precision CC event to the synth. As with all MIDI * @brief Send a high precision CC event to the synth.
* events, this needs to happen before the call to
* sfizz_render_block in each block and should appear in order of
* the delays.
* *
* @param synth The synth. * As with all MIDI events, this needs to happen before the call to
* @param delay The delay of the event in the block, in samples. * sfizz_render_block() in each block and should appear in order of the delays.
* @param cc_number The MIDI CC number. * @since 0.4.0
* @param norm_value The normalized CC value, in domain 0 to 1. *
* @param synth The synth.
* @param delay The delay of the event in the block, in samples.
* @param cc_number The MIDI CC number.
* @param norm_value The normalized CC value, in domain 0 to 1.
*/ */
SFIZZ_EXPORTED_API void sfizz_send_hdcc(sfizz_synth_t* synth, int delay, int cc_number, float norm_value); SFIZZ_EXPORTED_API void sfizz_send_hdcc(sfizz_synth_t* synth, int delay, int cc_number, float norm_value);
/** /**
* @brief Send a pitch wheel event. As with all MIDI events, this needs * @brief Send a pitch wheel event.
* to happen before the call to sfizz_render_block in each block and *
* should appear in order of the delays. * As with all MIDI events, this needs to happen before the call to
* sfizz_render_block() in each block and should appear in order of the delays.
* @since 0.4.0 * @since 0.4.0
* *
* @param synth The synth. * @param synth The synth.
* @param delay The delay. * @param delay The delay.
* @param pitch The pitch. * @param pitch The pitch.
*/ */
SFIZZ_EXPORTED_API void sfizz_send_pitch_wheel(sfizz_synth_t* synth, int delay, int pitch); SFIZZ_EXPORTED_API void sfizz_send_pitch_wheel(sfizz_synth_t* synth, int delay, int pitch);
/** /**
* @brief Send an aftertouch event. (CURRENTLY UNIMPLEMENTED) * @brief Send an aftertouch event. (CURRENTLY UNIMPLEMENTED)
* @since 0.2.0
* *
* @param synth * @param synth The synth.
* @param delay * @param delay The delay at which the event occurs; this should be lower
* @param aftertouch * than the size of the block in the next call to renderBlock().
* @param aftertouch The aftertouch value.
*/ */
SFIZZ_EXPORTED_API void sfizz_send_aftertouch(sfizz_synth_t* synth, int delay, char aftertouch); SFIZZ_EXPORTED_API void sfizz_send_aftertouch(sfizz_synth_t* synth, int delay, char aftertouch);
/** /**
* @brief Send a tempo event. * @brief Send a tempo event.
* @since 0.2.0
* *
* @param synth The synth. * @param synth The synth.
* @param delay The delay. * @param delay The delay.
* @param seconds_per_beat The seconds per beat. * @param seconds_per_beat The seconds per beat.
*/ */
SFIZZ_EXPORTED_API void sfizz_send_tempo(sfizz_synth_t* synth, int delay, float seconds_per_beat); SFIZZ_EXPORTED_API void sfizz_send_tempo(sfizz_synth_t* synth, int delay, float seconds_per_beat);
/** /**
* @brief Send the time signature. * @brief Send the time signature.
* @since 0.4.1
* *
* @param synth The synth. * @param synth The synth.
* @param delay The delay. * @param delay The delay.
* @param beats_per_bar The number of beats per bar, or time signature numerator. * @param beats_per_bar The number of beats per bar, or time signature numerator.
* @param beat_unit The note corresponding to one beat, or time signature denominator. * @param beat_unit The note corresponding to one beat, or time signature denominator.
*/ */
SFIZZ_EXPORTED_API void sfizz_send_time_signature(sfizz_synth_t* synth, int delay, int beats_per_bar, int beat_unit); SFIZZ_EXPORTED_API void sfizz_send_time_signature(sfizz_synth_t* synth, int delay, int beats_per_bar, int beat_unit);
/** /**
* @brief Send the time position. * @brief Send the time position.
* @since 0.4.1
* *
* @param synth The synth. * @param synth The synth.
* @param delay The delay. * @param delay The delay.
* @param bar The current bar. * @param bar The current bar.
* @param bar_beat The fractional position of the current beat within the bar. * @param bar_beat The fractional position of the current beat within the bar.
*/ */
SFIZZ_EXPORTED_API void sfizz_send_time_position(sfizz_synth_t* synth, int delay, int bar, float bar_beat); SFIZZ_EXPORTED_API void sfizz_send_time_position(sfizz_synth_t* synth, int delay, int bar, float bar_beat);
/** /**
* @brief Send the playback state. * @brief Send the playback state.
* @since 0.4.1
* *
* @param synth The synth. * @param synth The synth.
* @param delay The delay. * @param delay The delay.
* @param playback_state The playback state, 1 if playing, 0 if stopped. * @param playback_state The playback state, 1 if playing, 0 if stopped.
*/ */
SFIZZ_EXPORTED_API void sfizz_send_playback_state(sfizz_synth_t* synth, int delay, int playback_state); SFIZZ_EXPORTED_API void sfizz_send_playback_state(sfizz_synth_t* synth, int delay, int playback_state);
/** /**
* @brief Render a block audio data into a stereo channel. No other channel * @brief Render a block audio data into a stereo channel.
* configuration is supported. The synth will gracefully ignore your
* request if you provide a value. You should pass all the relevant
* events for the block (midi notes, CCs, ...) before rendering each
* block. The synth will memorize the inputs and render sample
* accurates envelopes depending on the input events passed to it.
* *
* @param synth The synth. * No other channel configuration is supported. The synth will gracefully ignore
* @param channels Pointers to the left and right channel of the * your request if you provide a value. You should pass all the relevant events
* output. * for the block (midi notes, CCs, ...) before rendering each block.
* @param num_channels Should be equal to 2 for the time being. * The synth will memorize the inputs and render sample accurates envelopes
* @param num_frames Number of frames to fill. This should be less than * depending on the input events passed to it.
* or equal to the expected samples_per_block. * @since 0.2.0
*
* @param synth The synth.
* @param channels Pointers to the left and right channel of the output.
* @param num_channels Should be equal to 2 for the time being.
* @param num_frames Number of frames to fill. This should be less than
* or equal to the expected samples_per_block.
*/ */
SFIZZ_EXPORTED_API void sfizz_render_block(sfizz_synth_t* synth, float** channels, int num_channels, int num_frames); SFIZZ_EXPORTED_API void sfizz_render_block(sfizz_synth_t* synth, float** channels, int num_channels, int num_frames);
/** /**
* @brief Get the size of the preloaded data. This returns the number of * @brief Get the size of the preloaded data.
* floats used in the preloading buffers.
* *
* @param synth The synth. * This returns the number of floats used in the preloading buffers.
* @since 0.2.0
*
* @param synth The synth.
*/ */
SFIZZ_EXPORTED_API unsigned int sfizz_get_preload_size(sfizz_synth_t* synth); SFIZZ_EXPORTED_API unsigned int sfizz_get_preload_size(sfizz_synth_t* synth);
/** /**
* @brief Set the size of the preloaded data in number of floats (not * @brief Set the size of the preloaded data in number of floats (not bytes).
* bytes). This will disable the callbacks for the duration of the *
* load. This function takes a lock ; prefer calling * This will disable the callbacks for the duration of the load.
* it out of the RT thread. It can also take a long time to return. * This function takes a lock ; prefer calling it out of the RT thread.
* If the new preload size is the same as the current one, it will * It can also take a long time to return. If the new preload size is the same
* release the lock immediately and exit. * as the current one, it will release the lock immediately and exit.
* @since 0.2.0
* *
* @param synth The synth. * @param synth The synth.
* @param[in] preload_size The preload size. * @param[in] preload_size The preload size.
@ -378,199 +429,231 @@ SFIZZ_EXPORTED_API unsigned int sfizz_get_preload_size(sfizz_synth_t* synth);
SFIZZ_EXPORTED_API void sfizz_set_preload_size(sfizz_synth_t* synth, unsigned int preload_size); SFIZZ_EXPORTED_API void sfizz_set_preload_size(sfizz_synth_t* synth, unsigned int preload_size);
/** /**
* @brief Get the internal oversampling rate. This is the sampling rate of * @brief Get the internal oversampling rate.
* the engine, not the output or expected rate of the calling
* function. For the latter use the `get_sample_rate()` functions.
* *
* @param synth The synth. * This is the sampling rate of the engine, not the output or expected rate of
* the calling function. For the latter use the sfizz_get_sample_rate() function.
* @since 0.2.0
*
* @param synth The synth.
*/ */
SFIZZ_EXPORTED_API sfizz_oversampling_factor_t sfizz_get_oversampling_factor(sfizz_synth_t* synth); SFIZZ_EXPORTED_API sfizz_oversampling_factor_t sfizz_get_oversampling_factor(sfizz_synth_t* synth);
/** /**
* @brief Set the internal oversampling rate. This is the sampling rate of * @brief Set the internal oversampling rate.
* the engine, not the output or expected rate of the calling
* function. For the latter use the `set_sample_rate()` functions.
* *
* Increasing this value (up to x8 oversampling) improves the * This is the sampling rate of the engine, not the output or expected rate of
* quality of the output at the expense of memory consumption and * the calling function. For the latter use the sfizz_set_sample_rate() function.
* background loading speed. The main render path still uses the
* same linear interpolation algorithm and should not see its
* performance decrease, but the files are oversampled upon loading
* which increases the stress on the background loader and reduce
* the loading speed. You can tweak the size of the preloaded data
* to compensate for the memory increase, but the full loading will
* need to take place anyway.
* *
* This function takes a lock and disables the callback; prefer calling * Increasing this value (up to x8 oversampling) improves the quality of the
* it out of the RT thread. It can also take a long time to return. * output at the expense of memory consumption and background loading speed.
* If the new oversampling factor is the same as the current one, it will * The main render path still uses the same linear interpolation algorithm and
* release the lock immediately and exit. * should not see its performance decrease, but the files are oversampled upon
* loading which increases the stress on the background loader and reduce
* the loading speed. You can tweak the size of the preloaded data to compensate
* for the memory increase, but the full loading will need to take place anyway.
*
* This function takes a lock and disables the callback; prefer calling it out
* of the RT thread. It can also take a long time to return.
* If the new oversampling factor is the same as the current one, it will
* release the lock immediately and exit.
* @since 0.2.0
* *
* @param synth The synth. * @param synth The synth.
* @param[in] oversampling The oversampling factor. * @param[in] oversampling The oversampling factor.
* *
* @return @true if the oversampling factor was correct, @false otherwise. * @return @true if the oversampling factor was correct, @false otherwise.
*/ */
SFIZZ_EXPORTED_API bool sfizz_set_oversampling_factor(sfizz_synth_t* synth, sfizz_oversampling_factor_t oversampling); SFIZZ_EXPORTED_API bool sfizz_set_oversampling_factor(sfizz_synth_t* synth, sfizz_oversampling_factor_t oversampling);
/** /**
* @brief Get the default resampling quality. This is the quality setting * @brief Get the default resampling quality.
* which the engine uses when the instrument does not use the *
* opcode `sample_quality`. The engine uses distinct default quality * This is the quality setting which the engine uses when the instrument
* settings for live mode and freewheeling mode, which both can be * does not use the opcode `sample_quality`. The engine uses distinct
* accessed by the means of this function. * default quality settings for live mode and freewheeling mode,
* which both can be accessed by the means of this function.
* @since 0.4.0 * @since 0.4.0
* *
* @param synth The synth. * @param synth The synth.
* @param[in] mode The processing mode. * @param[in] mode The processing mode.
* *
* @return The sample quality for the given mode, in the range 1 to 10. * @return The sample quality for the given mode, in the range 1 to 10.
*/ */
SFIZZ_EXPORTED_API int sfizz_get_sample_quality(sfizz_synth_t* synth, sfizz_process_mode_t mode); SFIZZ_EXPORTED_API int sfizz_get_sample_quality(sfizz_synth_t* synth, sfizz_process_mode_t mode);
/** /**
* @brief Set the default resampling quality. This is the quality setting * @brief Set the default resampling quality.
* which the engine uses when the instrument does not use the *
* opcode `sample_quality`. The engine uses distinct default quality * This is the quality setting which the engine uses when the instrument
* settings for live mode and freewheeling mode, which both can be * does not use the opcode `sample_quality`. The engine uses distinct
* accessed by the means of this function. * default quality settings for live mode and freewheeling mode,
* which both can be accessed by the means of this function.
* @since 0.4.0 * @since 0.4.0
* *
* @param synth The synth. * @param synth The synth.
* @param[in] mode The processing mode. * @param[in] mode The processing mode.
* @param[in] quality The desired sample quality, in the range 1 to 10. * @param[in] quality The desired sample quality, in the range 1 to 10.
*/ */
SFIZZ_EXPORTED_API void sfizz_set_sample_quality(sfizz_synth_t* synth, sfizz_process_mode_t mode, int quality); SFIZZ_EXPORTED_API void sfizz_set_sample_quality(sfizz_synth_t* synth, sfizz_process_mode_t mode, int quality);
/** /**
* @brief Set the global instrument volume. * @brief Set the global instrument volume.
* @since 0.2.0
* *
* @param synth The synth. * @param synth The synth.
* @param volume The new volume. * @param volume The new volume.
*/ */
SFIZZ_EXPORTED_API void sfizz_set_volume(sfizz_synth_t* synth, float volume); SFIZZ_EXPORTED_API void sfizz_set_volume(sfizz_synth_t* synth, float volume);
/** /**
* @brief Return the global instrument volume. * @brief Return the global instrument volume.
* @since 0.2.0
* *
* @param synth The synth. * @param synth The synth.
*/ */
SFIZZ_EXPORTED_API float sfizz_get_volume(sfizz_synth_t* synth); SFIZZ_EXPORTED_API float sfizz_get_volume(sfizz_synth_t* synth);
/** /**
* @brief Set the number of voices used by the synth. * @brief Set the number of voices used by the synth.
* This function takes a lock and disables the callback; prefer calling
* it out of the RT thread. It can also take a long time to return.
* If the new number of voices is the same as the current one, it will
* release the lock immediately and exit.
* *
* @param synth The synth. * This function takes a lock and disables the callback; prefer calling
* @param num_voices The number of voices. * it out of the RT thread. It can also take a long time to return.
* If the new number of voices is the same as the current one, it will
* release the lock immediately and exit.
* @since 0.2.0
*
* @param synth The synth.
* @param num_voices The number of voices.
*/ */
SFIZZ_EXPORTED_API void sfizz_set_num_voices(sfizz_synth_t* synth, int num_voices); SFIZZ_EXPORTED_API void sfizz_set_num_voices(sfizz_synth_t* synth, int num_voices);
/** /**
* @brief Return the number of voices. * @brief Return the number of voices.
* @since 0.2.0
* *
* @param synth The synth. * @param synth The synth.
*/ */
SFIZZ_EXPORTED_API int sfizz_get_num_voices(sfizz_synth_t* synth); SFIZZ_EXPORTED_API int sfizz_get_num_voices(sfizz_synth_t* synth);
/** /**
* @brief Return the number of allocated buffers from the synth. * @brief Return the number of allocated buffers from the synth.
* @since 0.2.0
* *
* @param synth The synth. * @param synth The synth.
*/ */
SFIZZ_EXPORTED_API int sfizz_get_num_buffers(sfizz_synth_t* synth); SFIZZ_EXPORTED_API int sfizz_get_num_buffers(sfizz_synth_t* synth);
/** /**
* @brief Get the number of bytes allocated from the synth. Note that this * @brief Get the number of bytes allocated from the synth.
* value can be less than the actual memory usage since it only
* counts the buffer objects managed by sfizz.
* *
* @param synth The synth. * Note that this value can be less than the actual memory usage since it only
* counts the buffer objects managed by sfizz.
* @since 0.2.0
*
* @param synth The synth.
*/ */
SFIZZ_EXPORTED_API int sfizz_get_num_bytes(sfizz_synth_t* synth); SFIZZ_EXPORTED_API int sfizz_get_num_bytes(sfizz_synth_t* synth);
/** /**
* @brief Enable freewheeling on the synth. * @brief Enable freewheeling on the synth.
* @since 0.2.0
* *
* @param synth The synth. * @param synth The synth.
*/ */
SFIZZ_EXPORTED_API void sfizz_enable_freewheeling(sfizz_synth_t* synth); SFIZZ_EXPORTED_API void sfizz_enable_freewheeling(sfizz_synth_t* synth);
/** /**
* @brief Disable freewheeling on the synth. * @brief Disable freewheeling on the synth.
* @since 0.2.0
* *
* @param synth The synth. * @param synth The synth.
*/ */
SFIZZ_EXPORTED_API void sfizz_disable_freewheeling(sfizz_synth_t* synth); SFIZZ_EXPORTED_API void sfizz_disable_freewheeling(sfizz_synth_t* synth);
/** /**
* @brief Return a comma separated list of unknown opcodes. * @brief Return a comma separated list of unknown opcodes.
* The caller has to free() the string returned.
* This function allocates memory, do not call on the audio thread.
* *
* @param synth The synth. * The caller has to free() the string returned. This function allocates memory,
* do not call on the audio thread.
* @since 0.2.0
*
* @param synth The synth.
*/ */
SFIZZ_EXPORTED_API char* sfizz_get_unknown_opcodes(sfizz_synth_t* synth); SFIZZ_EXPORTED_API char* sfizz_get_unknown_opcodes(sfizz_synth_t* synth);
/** /**
* @brief Check if the SFZ should be reloaded. * @brief Check if the SFZ should be reloaded.
* Depending on the platform this can create file descriptors.
* *
* @param synth The synth. * Depending on the platform this can create file descriptors.
* @since 0.2.0
* *
* @return @true if any included files (including the root file) have * @param synth The synth.
* been modified since the sfz file was loaded, @false otherwise. *
* @return @true if any included files (including the root file)
have been modified since the sfz file was loaded, @false otherwise.
*/ */
SFIZZ_EXPORTED_API bool sfizz_should_reload_file(sfizz_synth_t* synth); SFIZZ_EXPORTED_API bool sfizz_should_reload_file(sfizz_synth_t* synth);
/** /**
* @brief Check if the scala file should be reloaded. * @brief Check if the scala file should be reloaded.
* Depending on the platform this can create file descriptors.
* *
* @param synth The synth. * Depending on the platform this can create file descriptors.
* @since 0.4.0
* *
* @return @true if the scala file has been modified since loading. * @param synth The synth.
*
* @return @true if the scala file has been modified since loading.
*/ */
SFIZZ_EXPORTED_API bool sfizz_should_reload_scala(sfizz_synth_t* synth); SFIZZ_EXPORTED_API bool sfizz_should_reload_scala(sfizz_synth_t* synth);
/** /**
* @brief Enable logging of timings to sidecar CSV files. This can produce * @brief Enable logging of timings to sidecar CSV files.
* many outputs so use with caution. * @since 0.3.0
* *
* @param synth The synth. * @note This can produce many outputs so use with caution.
*
* @param synth The synth.
*/ */
SFIZZ_EXPORTED_API void sfizz_enable_logging(sfizz_synth_t* synth); SFIZZ_EXPORTED_API void sfizz_enable_logging(sfizz_synth_t* synth);
/** /**
* @brief Disable logging. * @brief Disable logging.
* @since 0.3.0
* *
* @param synth The synth. * @param synth The synth.
*/ */
SFIZZ_EXPORTED_API void sfizz_disable_logging(sfizz_synth_t* synth); SFIZZ_EXPORTED_API void sfizz_disable_logging(sfizz_synth_t* synth);
/** /**
* @brief Enable logging of timings to sidecar CSV files. This can produce * @brief Enable logging of timings to sidecar CSV files.
* many outputs so use with caution. * @since 0.3.2
* *
* @param synth The synth. * @note This can produce many outputs so use with caution.
* @param prefix The prefix. *
* @param synth The synth.
* @param prefix The prefix.
*/ */
SFIZZ_EXPORTED_API void sfizz_set_logging_prefix(sfizz_synth_t* synth, const char* prefix); SFIZZ_EXPORTED_API void sfizz_set_logging_prefix(sfizz_synth_t* synth, const char* prefix);
/** /**
* @brief Shuts down the current processing, clear buffers and reset the voices. * @brief Shuts down the current processing, clear buffers and reset the voices.
* @since 0.3.2
* *
* @param synth The synth. * @param synth The synth.
*/ */
SFIZZ_EXPORTED_API void sfizz_all_sound_off(sfizz_synth_t* synth); SFIZZ_EXPORTED_API void sfizz_all_sound_off(sfizz_synth_t* synth);
/** /**
* @brief Add external definitions prior to loading; * @brief Add external definitions prior to loading.
* Note that these do not get reset by loading or resetting the synth.
* You need to call sfizz_clear_external_definitions() to erase them.
* @since 0.4.0 * @since 0.4.0
* *
* @param synth * @note These do not get reset by loading or resetting the synth.
* @param id * You need to call sfizz_clear_external_definitions() to erase them.
* @param value *
* @param synth The synth.
* @param id The definition variable name.
* @param value The definition value.
*/ */
SFIZZ_EXPORTED_API void sfizz_add_external_definitions(sfizz_synth_t* synth, const char* id, const char* value); SFIZZ_EXPORTED_API void sfizz_add_external_definitions(sfizz_synth_t* synth, const char* id, const char* value);
@ -578,15 +661,21 @@ SFIZZ_EXPORTED_API void sfizz_add_external_definitions(sfizz_synth_t* synth, con
* @brief Clears external definitions for the next file loading. * @brief Clears external definitions for the next file loading.
* @since 0.4.0 * @since 0.4.0
* *
* @param synth * @param synth The synth.
*/ */
SFIZZ_EXPORTED_API void sfizz_clear_external_definitions(sfizz_synth_t* synth); SFIZZ_EXPORTED_API void sfizz_clear_external_definitions(sfizz_synth_t* synth);
/**
* @brief Index out of bound error for the requested CC/key label.
* @since 0.4.0
*/
#define SFIZZ_OUT_OF_BOUNDS_LABEL_INDEX -1 #define SFIZZ_OUT_OF_BOUNDS_LABEL_INDEX -1
/** /**
* @brief Get the number of key labels registered in the current sfz file * @brief Get the number of key labels registered in the current sfz file.
* @since 0.4.0 * @since 0.4.0
*
* @param synth The synth.
*/ */
SFIZZ_EXPORTED_API unsigned int sfizz_get_num_key_labels(sfizz_synth_t* synth); SFIZZ_EXPORTED_API unsigned int sfizz_get_num_key_labels(sfizz_synth_t* synth);
@ -594,6 +683,9 @@ SFIZZ_EXPORTED_API unsigned int sfizz_get_num_key_labels(sfizz_synth_t* synth);
* @brief Get the key number for the label registered at index label_index. * @brief Get the key number for the label registered at index label_index.
* @since 0.4.0 * @since 0.4.0
* *
* @param synth The synth.
* @param label_index The label index.
*
* @returns the number or SFIZZ_OUT_OF_BOUNDS_LABEL_INDEX if the index is out of bounds. * @returns the number or SFIZZ_OUT_OF_BOUNDS_LABEL_INDEX if the index is out of bounds.
*/ */
SFIZZ_EXPORTED_API int sfizz_get_key_label_number(sfizz_synth_t* synth, int label_index); SFIZZ_EXPORTED_API int sfizz_get_key_label_number(sfizz_synth_t* synth, int label_index);
@ -602,7 +694,10 @@ SFIZZ_EXPORTED_API int sfizz_get_key_label_number(sfizz_synth_t* synth, int labe
* @brief Get the key text for the label registered at index label_index. * @brief Get the key text for the label registered at index label_index.
* @since 0.4.0 * @since 0.4.0
* *
* @returns the label or NULL if the index is out of bounds. * @param synth The synth.
* @param label_index The label index.
*
* @returns the label or @null if the index is out of bounds.
*/ */
SFIZZ_EXPORTED_API const char * sfizz_get_key_label_text(sfizz_synth_t* synth, int label_index); SFIZZ_EXPORTED_API const char * sfizz_get_key_label_text(sfizz_synth_t* synth, int label_index);
@ -610,6 +705,7 @@ SFIZZ_EXPORTED_API const char * sfizz_get_key_label_text(sfizz_synth_t* synth, i
* @brief Get the number of CC labels registered in the current sfz file * @brief Get the number of CC labels registered in the current sfz file
* @since 0.4.0 * @since 0.4.0
* *
* @param synth The synth.
*/ */
SFIZZ_EXPORTED_API unsigned int sfizz_get_num_cc_labels(sfizz_synth_t* synth); SFIZZ_EXPORTED_API unsigned int sfizz_get_num_cc_labels(sfizz_synth_t* synth);
@ -617,15 +713,21 @@ SFIZZ_EXPORTED_API unsigned int sfizz_get_num_cc_labels(sfizz_synth_t* synth);
* @brief Get the CC number for the label registered at index label_index. * @brief Get the CC number for the label registered at index label_index.
* @since 0.4.0 * @since 0.4.0
* *
* @param synth The synth.
* @param label_index The label index.
*
* @returns the number or SFIZZ_OUT_OF_BOUNDS_LABEL_INDEX if the index is out of bounds. * @returns the number or SFIZZ_OUT_OF_BOUNDS_LABEL_INDEX if the index is out of bounds.
*/ */
SFIZZ_EXPORTED_API int sfizz_get_cc_label_number(sfizz_synth_t* synth, int label_index); SFIZZ_EXPORTED_API int sfizz_get_cc_label_number(sfizz_synth_t* synth, int label_index);
/** /**
* @brief Get the CC text for the label registered at index label_index. * @brief Get the CC text for the label registered at index label_index.
* @since 0.4.0 * @since 0.4.0
* *
* @returns the label or NULL if the index is out of bounds. * @param synth The synth.
* @param label_index The label index.
*
* @returns the label or @null if the index is out of bounds.
*/ */
SFIZZ_EXPORTED_API const char * sfizz_get_cc_label_text(sfizz_synth_t* synth, int label_index); SFIZZ_EXPORTED_API const char * sfizz_get_cc_label_text(sfizz_synth_t* synth, int label_index);

199
src/sfizz.hpp
View file

@ -6,7 +6,7 @@
/** /**
@file @file
@brief sfizz public C++ API @brief sfizz public C++ API.
*/ */
#pragma once #pragma once
@ -29,22 +29,23 @@ namespace sfz
{ {
class Synth; class Synth;
/** /**
* @brief Main class * @brief Main class.
*/ */
class SFIZZ_EXPORTED_API Sfizz class SFIZZ_EXPORTED_API Sfizz
{ {
public: public:
/** /**
* @brief Construct a new Sfizz object. The synth by default is set at 48 kHz * @brief Construct a new Sfizz object.
* and a block size of 1024. You should change these values if they are not
* suited to your application.
* *
* The synth by default is set at 48 kHz and a block size of 1024.
* You should change these values if they are not suited to your application.
*/ */
Sfizz(); Sfizz();
~Sfizz(); ~Sfizz();
/** /**
* @brief Processing mode * @brief Processing mode.
* @since 0.4.0
*/ */
enum ProcessMode { enum ProcessMode {
ProcessLive, ProcessLive,
@ -57,6 +58,7 @@ public:
* This function will disable all callbacks so it is safe to call from a * This function will disable all callbacks so it is safe to call from a
* UI thread for example, although it may generate a click. However it is * UI thread for example, although it may generate a click. However it is
* not reentrant, so you should not call it from concurrent threads. * not reentrant, so you should not call it from concurrent threads.
* @since 0.2.0
* *
* @param path The path to the file to load, as string. * @param path The path to the file to load, as string.
* *
@ -86,7 +88,8 @@ public:
* @brief Sets the tuning from a Scala file loaded from the file system. * @brief Sets the tuning from a Scala file loaded from the file system.
* @since 0.4.0 * @since 0.4.0
* *
* @param path The path to the file in Scala format. * @param path The path to the file in Scala format.
*
* @return @true when tuning scale loaded OK, * @return @true when tuning scale loaded OK,
* @false if some error occurred. * @false if some error occurred.
*/ */
@ -96,7 +99,8 @@ public:
* @brief Sets the tuning from a Scala file loaded from memory. * @brief Sets the tuning from a Scala file loaded from memory.
* @since 0.4.0 * @since 0.4.0
* *
* @param text The contents of the file in Scala format. * @param text The contents of the file in Scala format.
*
* @return @true when tuning scale loaded OK, * @return @true when tuning scale loaded OK,
* @false if some error occurred. * @false if some error occurred.
*/ */
@ -136,6 +140,7 @@ public:
/** /**
* @brief Configure stretch tuning using a predefined parametric Railsback curve. * @brief Configure stretch tuning using a predefined parametric Railsback curve.
*
* A ratio 1/2 is supposed to match the average piano; 0 disables (the default). * A ratio 1/2 is supposed to match the average piano; 0 disables (the default).
* @since 0.4.0 * @since 0.4.0
* *
@ -145,57 +150,68 @@ public:
/** /**
* @brief Return the current number of regions loaded. * @brief Return the current number of regions loaded.
* @since 0.2.0
*/ */
int getNumRegions() const noexcept; int getNumRegions() const noexcept;
/** /**
* @brief Return the current number of groups loaded. * @brief Return the current number of groups loaded.
* @since 0.2.0
*/ */
int getNumGroups() const noexcept; int getNumGroups() const noexcept;
/** /**
* @brief Return the current number of masters loaded. * @brief Return the current number of masters loaded.
* @since 0.2.0
*/ */
int getNumMasters() const noexcept; int getNumMasters() const noexcept;
/** /**
* @brief Return the current number of curves loaded. * @brief Return the current number of curves loaded.
* @since 0.2.0
*/ */
int getNumCurves() const noexcept; int getNumCurves() const noexcept;
/** /**
* @brief Return a list of unsupported opcodes, if any. * @brief Return a list of unsupported opcodes, if any.
* @since 0.2.0
*/ */
const std::vector<std::string>& getUnknownOpcodes() const noexcept; const std::vector<std::string>& getUnknownOpcodes() const noexcept;
/** /**
* @brief Return the number of preloaded samples in the synth. * @brief Return the number of preloaded samples in the synth.
* @since 0.2.0
*/ */
size_t getNumPreloadedSamples() const noexcept; size_t getNumPreloadedSamples() const noexcept;
/** /**
* @brief Set the maximum size of the blocks for the callback. The actual * @brief Set the maximum size of the blocks for the callback.
* size can be lower in each callback but should not be larger *
* The actual size can be lower in each callback but should not be larger
* than this value. * than this value.
* @since 0.2.0
* *
* @param samplesPerBlock The number of samples per block. * @param samplesPerBlock The number of samples per block.
*/ */
void setSamplesPerBlock(int samplesPerBlock) noexcept; void setSamplesPerBlock(int samplesPerBlock) noexcept;
/** /**
* @brief Set the sample rate. If you do not call it it is initialized * @brief Set the sample rate.
* to sfz::config::defaultSampleRate. *
* If you do not call it it is initialized to `sfz::config::defaultSampleRate`.
* @since 0.2.0
* *
* @param sampleRate The sample rate. * @param sampleRate The sample rate.
*/ */
void setSampleRate(float sampleRate) noexcept; void setSampleRate(float sampleRate) noexcept;
/** /**
* @brief Get the default resampling quality. This is the quality setting * @brief Get the default resampling quality.
* which the engine uses when the instrument does not use the *
* opcode `sample_quality`. The engine uses distinct default quality * This is the quality setting which the engine uses when the instrument
* settings for live mode and freewheeling mode, which both can be * does not use the opcode `sample_quality`. The engine uses distinct
* accessed by the means of this function. * default quality settings for live mode and freewheeling mode,
* which both can be accessed by the means of this function.
* @since 0.4.0 * @since 0.4.0
* *
* @param[in] mode The processing mode. * @param[in] mode The processing mode.
@ -205,11 +221,12 @@ public:
int getSampleQuality(ProcessMode mode); int getSampleQuality(ProcessMode mode);
/** /**
* @brief Set the default resampling quality. This is the quality setting * @brief Set the default resampling quality.
* which the engine uses when the instrument does not use the *
* opcode `sample_quality`. The engine uses distinct default quality * This is the quality setting which the engine uses when the instrument
* settings for live mode and freewheeling mode, which both can be * does not use the opcode `sample_quality`. The engine uses distinct
* accessed by the means of this function. * default quality settings for live mode and freewheeling mode,
* which both can be accessed by the means of this function.
* @since 0.4.0 * @since 0.4.0
* *
* @param[in] mode The processing mode. * @param[in] mode The processing mode.
@ -219,19 +236,23 @@ public:
/** /**
* @brief Return the current value for the volume, in dB. * @brief Return the current value for the volume, in dB.
* @since 0.2.0
*/ */
float getVolume() const noexcept; float getVolume() const noexcept;
/** /**
* @brief Set the value for the volume. This value will be * @brief Set the value for the volume.
* clamped within sfz::default::volumeRange. *
* This value will be clamped within `sfz::default::volumeRange`.
* @since 0.2.0
* *
* @param volume The new volume. * @param volume The new volume.
*/ */
void setVolume(float volume) noexcept; void setVolume(float volume) noexcept;
/** /**
* @brief Send a note on event to the synth * @brief Send a note on event to the synth.
* @since 0.2.0
* *
* @param delay the delay at which the event occurs; this should be lower * @param delay the delay at which the event occurs; this should be lower
* than the size of the block in the next call to renderBlock(). * than the size of the block in the next call to renderBlock().
@ -241,7 +262,8 @@ public:
void noteOn(int delay, int noteNumber, uint8_t velocity) noexcept; void noteOn(int delay, int noteNumber, uint8_t velocity) noexcept;
/** /**
* @brief Send a note off event to the synth * @brief Send a note off event to the synth.
* @since 0.2.0
* *
* @param delay the delay at which the event occurs; this should be lower * @param delay the delay at which the event occurs; this should be lower
* than the size of the block in the next call to renderBlock(). * than the size of the block in the next call to renderBlock().
@ -252,9 +274,10 @@ public:
/** /**
* @brief Send a CC event to the synth * @brief Send a CC event to the synth
* @since 0.2.0
* *
* @param delay the delay at which the event occurs; this should be lower than the size of * @param delay the delay at which the event occurs; this should be lower
* the block in the next call to renderBlock(). * than the size of the block in the next call to renderBlock().
* @param ccNumber the cc number. * @param ccNumber the cc number.
* @param ccValue the cc value. * @param ccValue the cc value.
*/ */
@ -264,8 +287,8 @@ public:
* @brief Send a high precision CC event to the synth * @brief Send a high precision CC event to the synth
* @since 0.4.0 * @since 0.4.0
* *
* @param delay the delay at which the event occurs; this should be lower than the size of * @param delay the delay at which the event occurs; this should be lower
* the block in the next call to renderBlock(). * than the size of the block in the next call to renderBlock().
* @param ccNumber the cc number. * @param ccNumber the cc number.
* @param normValue the normalized cc value, in domain 0 to 1. * @param normValue the normalized cc value, in domain 0 to 1.
*/ */
@ -273,62 +296,69 @@ public:
/** /**
* @brief Send a pitch bend event to the synth * @brief Send a pitch bend event to the synth
* @since 0.2.0
* *
* @param delay the delay at which the event occurs; this should be lower * @param delay the delay at which the event occurs; this should be lower
* than the size of the block in the next call to * than the size of the block in the next call to renderBlock().
* renderBlock().
* @param pitch the pitch value centered between -8192 and 8192. * @param pitch the pitch value centered between -8192 and 8192.
*/ */
void pitchWheel(int delay, int pitch) noexcept; void pitchWheel(int delay, int pitch) noexcept;
/** /**
* @brief Send a aftertouch event to the synth. (CURRENTLY UNIMPLEMENTED) * @brief Send a aftertouch event to the synth. (CURRENTLY UNIMPLEMENTED)
* @since 0.2.0
* *
* @param delay the delay at which the event occurs; this should be lower than the size of * @param delay the delay at which the event occurs; this should be lower
* the block in the next call to renderBlock(). * than the size of the block in the next call to renderBlock().
* @param aftertouch the aftertouch value. * @param aftertouch the aftertouch value.
*/ */
void aftertouch(int delay, uint8_t aftertouch) noexcept; void aftertouch(int delay, uint8_t aftertouch) noexcept;
/** /**
* @brief Send a tempo event to the synth. * @brief Send a tempo event to the synth.
* @since 0.2.0
* *
* @param delay the delay at which the event occurs; this should be lower than the size of * @param delay the delay at which the event occurs; this should be lower
* the block in the next call to renderBlock(). * than the size of the block in the next call to renderBlock().
* @param secondsPerBeat the new period of the beat. * @param secondsPerBeat the new period of the beat.
*/ */
void tempo(int delay, float secondsPerBeat) noexcept; void tempo(int delay, float secondsPerBeat) noexcept;
/** /**
* @brief Send the time signature. * @brief Send the time signature.
* @since 0.4.1
* *
* @param delay The delay. * @param delay The delay.
* @param beats_per_bar The number of beats per bar, or time signature numerator. * @param beatsPerBar The number of beats per bar, or time signature numerator.
* @param beat_unit The note corresponding to one beat, or time signature denominator. * @param beatUnit The note corresponding to one beat, or time signature denominator.
*/ */
void timeSignature(int delay, int beatsPerBar, int beatUnit); void timeSignature(int delay, int beatsPerBar, int beatUnit);
/** /**
* @brief Send the time position. * @brief Send the time position.
* @since 0.4.1
* *
* @param delay The delay. * @param delay The delay.
* @param bar The current bar. * @param bar The current bar.
* @param bar_beat The fractional position of the current beat within the bar. * @param barBeat The fractional position of the current beat within the bar.
*/ */
void timePosition(int delay, int bar, float barBeat); void timePosition(int delay, int bar, float barBeat);
/** /**
* @brief Send the playback state. * @brief Send the playback state.
* @since 0.4.1
* *
* @param delay The delay. * @param delay The delay.
* @param playback_state The playback state, 1 if playing, 0 if stopped. * @param playbackState The playback state, 1 if playing, 0 if stopped.
*/ */
void playbackState(int delay, int playbackState); void playbackState(int delay, int playbackState);
/** /**
* @brief Render an block of audio data in the buffer. This call will reset * @brief Render an block of audio data in the buffer.
* the synth in its waiting state for the next batch of events. The buffers must *
* be float[numSamples][numOutputs * 2]. * This call will reset the synth in its waiting state for the next batch
* of events. The buffers must be float[numSamples][numOutputs * 2].
* @since 0.2.0
* *
* @param buffers the buffers to write the next block into. * @param buffers the buffers to write the next block into.
* @param numFrames the number of stereo frames in the block. * @param numFrames the number of stereo frames in the block.
@ -338,20 +368,24 @@ public:
/** /**
* @brief Return the number of active voices. * @brief Return the number of active voices.
* @since 0.2.0
*/ */
int getNumActiveVoices() const noexcept; int getNumActiveVoices() const noexcept;
/** /**
* @brief Return the total number of voices in the synth (the polyphony). * @brief Return the total number of voices in the synth (the polyphony).
* @since 0.2.0
*/ */
int getNumVoices() const noexcept; int getNumVoices() const noexcept;
/** /**
* @brief Change the number of voices (the polyphony). * @brief Change the number of voices (the polyphony).
*
* This function takes a lock and disables the callback; prefer calling * This function takes a lock and disables the callback; prefer calling
* it out of the RT thread. It can also take a long time to return. * it out of the RT thread. It can also take a long time to return.
* If the new number of voices is the same as the current one, it will * If the new number of voices is the same as the current one, it will
* release the lock immediately and exit. * release the lock immediately and exit.
* @since 0.2.0
* *
* @param numVoices The number of voices. * @param numVoices The number of voices.
*/ */
@ -359,6 +393,7 @@ public:
/** /**
* @brief Set the oversampling factor to a new value. * @brief Set the oversampling factor to a new value.
*
* It will kill all the voices, and trigger a reloading of every file in * It will kill all the voices, and trigger a reloading of every file in
* the FilePool under the new oversampling. * the FilePool under the new oversampling.
* *
@ -376,6 +411,7 @@ public:
* it out of the RT thread. It can also take a long time to return. * it out of the RT thread. It can also take a long time to return.
* If the new oversampling factor is the same as the current one, it will * If the new oversampling factor is the same as the current one, it will
* release the lock immediately and exit. * release the lock immediately and exit.
* @since 0.2.0
* *
* @param factor The oversampling factor. * @param factor The oversampling factor.
* *
@ -385,15 +421,18 @@ public:
/** /**
* @brief Return the current oversampling factor. * @brief Return the current oversampling factor.
* @since 0.2.0
*/ */
int getOversamplingFactor() const noexcept; int getOversamplingFactor() const noexcept;
/** /**
* @brief Set the preloaded file size. * @brief Set the preloaded file size.
*
* This function takes a lock and disables the callback; prefer calling * This function takes a lock and disables the callback; prefer calling
* it out of the RT thread. It can also take a long time to return. * it out of the RT thread. It can also take a long time to return.
* If the new preload size is the same as the current one, it will * If the new preload size is the same as the current one, it will
* release the lock immediately and exit. * release the lock immediately and exit.
* @since 0.2.0
* *
* @param preloadSize The preload size. * @param preloadSize The preload size.
*/ */
@ -401,30 +440,37 @@ public:
/** /**
* @brief Return the current preloaded file size. * @brief Return the current preloaded file size.
* @since 0.2.0
*/ */
uint32_t getPreloadSize() const noexcept; uint32_t getPreloadSize() const noexcept;
/** /**
* @brief Return the number of allocated buffers. * @brief Return the number of allocated buffers.
* @since 0.2.0
*/ */
int getAllocatedBuffers() const noexcept; int getAllocatedBuffers() const noexcept;
/** /**
* @brief Return the number of bytes allocated through the buffers. * @brief Return the number of bytes allocated through the buffers.
* @since 0.2.0
*/ */
int getAllocatedBytes() const noexcept; int getAllocatedBytes() const noexcept;
/** /**
* @brief Enable freewheeling on the synth. This will wait for background * @brief Enable freewheeling on the synth.
* loaded files to finish loading before each render callback to ensure that *
* there will be no dropouts. * This will wait for background loaded files to finish loading
* before each render callback to ensure that there will be no dropouts.
* @since 0.2.0
*/ */
void enableFreeWheeling() noexcept; void enableFreeWheeling() noexcept;
/** /**
* @brief Disable freewheeling on the synth. You should disable freewheeling * @brief Disable freewheeling on the synth.
* before live use of the plugin otherwise the audio thread will lock.
* *
* You should disable freewheeling before live use of the plugin
* otherwise the audio thread will lock.
* @since 0.2.0
*/ */
void disableFreeWheeling() noexcept; void disableFreeWheeling() noexcept;
@ -432,6 +478,7 @@ public:
* @brief Check if the SFZ should be reloaded. * @brief Check if the SFZ should be reloaded.
* *
* Depending on the platform this can create file descriptors. * Depending on the platform this can create file descriptors.
* @since 0.2.0
* *
* @return @true if any included files (including the root file) have * @return @true if any included files (including the root file) have
* been modified since the sfz file was loaded, @false otherwise. * been modified since the sfz file was loaded, @false otherwise.
@ -442,23 +489,27 @@ public:
* @brief Check if the tuning (scala) file should be reloaded. * @brief Check if the tuning (scala) file should be reloaded.
* *
* Depending on the platform this can create file descriptors. * Depending on the platform this can create file descriptors.
* @since 0.4.0
* *
* @return true if a scala file has been loaded and has changed * @return @true if a scala file has been loaded and has changed, @false otherwise.
* @return false
*/ */
bool shouldReloadScala(); bool shouldReloadScala();
/** /**
* @brief Enable logging of timings to sidecar CSV files. This can produce * @brief Enable logging of timings to sidecar CSV files.
* many outputs so use with caution. * @since 0.3.0
*
* @note This can produce many outputs so use with caution.
* *
* @param prefix the file prefix to use for logging. * @param prefix the file prefix to use for logging.
*/ */
void enableLogging() noexcept; void enableLogging() noexcept;
/** /**
* @brief Enable logging of timings to sidecar CSV files. This can produce * @brief Enable logging of timings to sidecar CSV files.
* many outputs so use with caution. * @since 0.3.2
*
* @note This can produce many outputs so use with caution.
* *
* @param prefix the file prefix to use for logging. * @param prefix the file prefix to use for logging.
*/ */
@ -466,52 +517,54 @@ public:
/** /**
* @brief Set the logging prefix. * @brief Set the logging prefix.
* @since 0.3.2
* *
* @param prefix * @param prefix
*/ */
void setLoggingPrefix(const std::string& prefix) noexcept; void setLoggingPrefix(const std::string& prefix) noexcept;
/** /**
* @brief * @brief Disable logging of timings to sidecar CSV files.
* * @since 0.3.0
*/ */
void disableLogging() noexcept; void disableLogging() noexcept;
/** /**
* @brief Shuts down the current processing, clear buffers and reset the voices. * @brief Shuts down the current processing, clear buffers and reset the voices.
* @since 0.3.2
*/ */
void allSoundOff() noexcept; void allSoundOff() noexcept;
/** /**
* @brief Add external definitions prior to loading; * @brief Add external definitions prior to loading.
* Note that these do not get reset by loading or resetting the synth.
* You need to call clearExternalDefintions() to erase them.
* @since 0.4.0 * @since 0.4.0
* *
* @param id * @note These do not get reset by loading or resetting the synth.
* @param value * You need to call clearExternalDefintions() to erase them.
*
* @param id The definition variable name.
* @param value The definition value.
*/ */
void addExternalDefinition(const std::string& id, const std::string& value); void addExternalDefinition(const std::string& id, const std::string& value);
/** /**
* @brief Clears external definitions for the next file loading. * @brief Clears external definitions for the next file loading.
* @since 0.4.0 * @since 0.4.0
*
*/ */
void clearExternalDefinitions(); void clearExternalDefinitions();
/** /**
* @brief Get the key labels, if any * @brief Get the key labels, if any.
* @since 0.4.0 * @since 0.4.0
*
*/ */
const std::vector<std::pair<uint8_t, std::string>>& getKeyLabels() const noexcept; const std::vector<std::pair<uint8_t, std::string>>& getKeyLabels() const noexcept;
/** /**
* @brief Get the CC labels, if any * @brief Get the CC labels, if any.
* @since 0.4.0 * @since 0.4.0
*
*/ */
const std::vector<std::pair<uint16_t, std::string>>& getCCLabels() const noexcept; const std::vector<std::pair<uint16_t, std::string>>& getCCLabels() const noexcept;
private: private:
std::unique_ptr<sfz::Synth> synth; std::unique_ptr<sfz::Synth> synth;
}; };