diff --git a/doxygen/scripts/Doxyfile.in b/doxygen/scripts/Doxyfile.in
index 0f7eb945..0465a14e 100644
--- a/doxygen/scripts/Doxyfile.in
+++ b/doxygen/scripts/Doxyfile.in
@@ -252,13 +252,8 @@ TAB_SIZE = 4
# a double escape (\\{ and \\})
ALIASES = "true=true" \
- "false=false"
-
-# 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 =
+ "false=false" \
+ "null=NULL
# 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
@@ -892,7 +887,7 @@ EXCLUDE_PATTERNS =
# Note that the wildcards are matched against the file with absolute path, so to
# 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
# that contain example code fragments that are included (see the \include
@@ -1103,7 +1098,7 @@ GENERATE_HTML = YES
# The default directory is: html.
# 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
# generated HTML page (for example: .htm, .php, .asp).
diff --git a/src/sfizz.h b/src/sfizz.h
index 5c8f7d1a..5b2ea170 100644
--- a/src/sfizz.h
+++ b/src/sfizz.h
@@ -6,7 +6,7 @@
/**
@file
- @brief sfizz public C API
+ @brief sfizz public C API.
*/
#pragma once
@@ -28,11 +28,14 @@ extern "C" {
#endif
/**
- * @brief Synth handle
+ * @brief Synth handle.
+ * @since 0.2.0
*/
typedef struct sfizz_synth_t sfizz_synth_t;
+
/**
* @brief Oversampling factor
+ * @since 0.2.0
*/
typedef enum {
SFIZZ_OVERSAMPLING_X1 = 1,
@@ -40,8 +43,10 @@ typedef enum {
SFIZZ_OVERSAMPLING_X4 = 4,
SFIZZ_OVERSAMPLING_X8 = 8
} sfizz_oversampling_factor_t;
+
/**
* @brief Processing mode
+ * @since 0.4.1
*/
typedef enum {
SFIZZ_PROCESS_LIVE,
@@ -49,47 +54,52 @@ typedef enum {
} sfizz_process_mode_t;
/**
- * @brief Creates a sfizz synth. This object has to be freed by the caller
- * using sfizz_free(). 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.
+ * @brief Creates a sfizz synth.
+ *
+ * This object has to be freed by the caller using sfizz_free().
+ * 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();
/**
- * @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);
/**
- * @brief Loads an SFZ file. The file path can be absolute or relative. All
- * file operations for this SFZ file will be relative to the parent
- * directory of the SFZ file.
+ * @brief Loads an SFZ file.
*
- * @param synth The sfizz synth.
- * @param path A null-terminated string representing a path to an SFZ
- * file.
+ * The file path can be absolute or relative. All file operations for this SFZ
+ * file will be relative to the parent directory of the SFZ file.
+ * @since 0.2.0
*
- * @return @true when file loading went OK,
- * @false if some error occured while loading.
+ * @param synth The synth.
+ * @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);
/**
- * @brief Loads an SFZ file from textual data. This accepts a virtual
- * path name for the imaginary sfz file, which is not required to
- * exist on disk. The purpose of the virtual path is to locate
- * samples with relative paths.
+ * @brief Loads an SFZ file from textual data.
+ *
+ * This accepts a virtual path name for the imaginary sfz file, which is not
+ * required to exist on disk. The purpose of the virtual path is to locate
+ * samples with relative paths.
* @since 0.4.0
*
- * @param synth The sfizz synth.
- * @param path The virtual path of the SFZ file.
- * @param text The contents of the virtual SFZ file.
+ * @param synth The synth.
+ * @param path The virtual path of the SFZ file.
+ * @param text The contents of the virtual SFZ file.
*
- * @return @true when file loading went OK,
- * @false if some error occured while loading.
+ * @return @true when file loading went OK,
+ * @false if some error occured while loading.
*/
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.
* @since 0.4.0
*
- * @param synth The sfizz synth.
- * @param path The path to the file in Scala format.
- * @return @true when tuning scale loaded OK,
- * @false if some error occurred.
+ * @param synth The synth.
+ * @param path The path to the file in Scala format.
+ *
+ * @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);
@@ -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.
* @since 0.4.0
*
- * @param synth The sfizz synth.
- * @param text The contents of the file in Scala format.
- * @return @true when tuning scale loaded OK,
- * @false if some error occurred.
+ * @param synth The synth.
+ * @param text The contents of the file in Scala format.
+ *
+ * @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);
@@ -119,8 +131,8 @@ SFIZZ_EXPORTED_API bool sfizz_load_scala_string(sfizz_synth_t* synth, const char
* @brief Sets the scala root key.
* @since 0.4.0
*
- * @param synth The sfizz synth.
- * @param root_key The MIDI number of the Scala root key (default 60 for C4).
+ * @param synth The synth.
+ * @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);
@@ -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.
* @since 0.4.0
*
- * @param synth The sfizz synth.
- * @return The MIDI number of the Scala root key (default 60 for C4).
+ * @param synth The synth.
+ *
+ * @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);
@@ -137,8 +150,8 @@ SFIZZ_EXPORTED_API int sfizz_get_scala_root_key(sfizz_synth_t* synth);
* @brief Sets the reference tuning frequency.
* @since 0.4.0
*
- * @param synth The sfizz synth.
- * @param frequency The frequency which indicates where standard tuning A4 is (default 440 Hz).
+ * @param synth The synth.
+ * @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);
@@ -146,231 +159,269 @@ SFIZZ_EXPORTED_API void sfizz_set_tuning_frequency(sfizz_synth_t* synth, float f
* @brief Gets the reference tuning frequency.
* @since 0.4.0
*
- * @param synth The sfizz synth.
- * @return The frequency which indicates where standard tuning A4 is (default 440 Hz).
+ * @param synth The synth.
+ *
+ * @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);
/**
- * @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).
+ * @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).
* @since 0.4.0
*
- * @param synth The sfizz synth.
- * @param ratio The parameter in domain 0-1.
+ * @param synth The synth.
+ * @param ratio The parameter in domain 0-1.
*/
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);
+
/**
- * @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);
+
/**
- * @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);
+
/**
- * @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);
+
/**
- * @brief Export a MIDI Name document describing the the currently loaded
- * SFZ file.
+ * @brief Export a MIDI Name document describing the currently loaded SFZ file.
+ * @since 0.3.1
*
- * @param synth The synth.
- * @param model The model name used if a non-empty string, otherwise generated.
+ * @param synth The synth.
+ * @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);
+
/**
- * @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);
+
/**
- * @brief Return the number of active voices. 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.
+ * @brief Return the number of active voices.
*
- * @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);
/**
- * @brief Set the expected number of samples per block. If unsure, give an
- * upper bound since right now ugly things may happen if you go over
- * this number.
+ * @brief Set the expected number of samples per block.
*
- * @param synth The synth.
- * @param samples_per_block The number of samples per block.
+ * If unsure, give an upper bound since right now ugly things may happen if you
+ * 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);
+
/**
- * @brief Set the sample rate for the synth. This is the output sample
- * rate. This setting does not affect the internal processing.
+ * @brief Set the sample rate for the synth.
*
- * @param synth The synth
- * @param sample_rate The sample rate.
+ * This is the output sample rate. This setting does not affect the internal processing.
+ * @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);
/**
- * @brief Send a note on event to the synth. 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.
+ * @brief Send a note on event to the synth.
*
- * @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.
+ * 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.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_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
- * 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.
+ * @brief Send a note off event to the synth.
*
- * @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.
+ * 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.
+ * As per the SFZ spec the velocity of note-off events is usually replaced by
+ * 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);
/**
- * @brief Send a CC event to the synth. 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.
+ * @brief Send a CC event to the synth.
*
- * @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.
+ * 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.2.0
+ *
+ * @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);
/**
- * @brief Send a high precision CC event to the synth. 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.
+ * @brief Send a high precision CC event to the synth.
*
- * @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.
+ * 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
+ *
+ * @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);
/**
- * @brief Send a pitch wheel event. 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.
+ * @brief Send a pitch wheel event.
+ *
+ * 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
*
- * @param synth The synth.
- * @param delay The delay.
- * @param pitch The pitch.
+ * @param synth The synth.
+ * @param delay The delay.
+ * @param pitch The 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 delay
- * @param aftertouch
+ * @param synth The synth.
+ * @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().
+ * @param aftertouch The aftertouch value.
*/
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 delay The delay.
- * @param seconds_per_beat The seconds per beat.
+ * @param synth The synth.
+ * @param delay The delay.
+ * @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);
/**
- * @brief Send the time signature.
+ * @brief Send the time signature.
+ * @since 0.4.1
*
- * @param synth The synth.
- * @param delay The delay.
- * @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 synth The synth.
+ * @param delay The delay.
+ * @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.
*/
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 delay The delay.
- * @param bar The current bar.
- * @param bar_beat The fractional position of the current beat within the bar.
+ * @param synth The synth.
+ * @param delay The delay.
+ * @param bar The current 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);
/**
- * @brief Send the playback state.
+ * @brief Send the playback state.
+ * @since 0.4.1
*
- * @param synth The synth.
- * @param delay The delay.
- * @param playback_state The playback state, 1 if playing, 0 if stopped.
+ * @param synth The synth.
+ * @param delay The delay.
+ * @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);
-
/**
- * @brief Render a block audio data into a stereo channel. No other 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.
+ * @brief Render a block audio data into a stereo channel.
*
- * @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.
+ * No other 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.
+ * @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);
/**
- * @brief Get the size of the preloaded data. This returns the number of
- * floats used in the preloading buffers.
+ * @brief Get the size of the preloaded data.
*
- * @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);
+
/**
- * @brief Set the size of the preloaded data in number of floats (not
- * bytes). This will disable the callbacks for the duration of the
- * load. This function takes a lock ; prefer calling
- * 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
- * release the lock immediately and exit.
+ * @brief Set the size of the preloaded data in number of floats (not bytes).
+ *
+ * This will disable the callbacks for the duration of the load.
+ * This function takes a lock ; prefer calling 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 release the lock immediately and exit.
+ * @since 0.2.0
*
* @param synth The synth.
* @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);
/**
- * @brief Get the internal oversampling rate. This is the sampling rate of
- * the engine, not the output or expected rate of the calling
- * function. For the latter use the `get_sample_rate()` functions.
+ * @brief Get the internal oversampling rate.
*
- * @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);
+
/**
- * @brief Set the internal oversampling rate. This is the sampling rate of
- * the engine, not the output or expected rate of the calling
- * function. For the latter use the `set_sample_rate()` functions.
+ * @brief Set the internal oversampling rate.
*
- * Increasing this value (up to x8 oversampling) improves the
- * quality of the output at the expense of memory consumption and
- * 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 is the sampling rate of the engine, not the output or expected rate of
+ * the calling function. For the latter use the sfizz_set_sample_rate() function.
*
- * 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.
+ * Increasing this value (up to x8 oversampling) improves the quality of the
+ * output at the expense of memory consumption and 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 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[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);
/**
- * @brief Get the default resampling quality. This is the quality setting
- * which the engine uses when the instrument does not use the
- * opcode `sample_quality`. The engine uses distinct default quality
- * settings for live mode and freewheeling mode, which both can be
- * accessed by the means of this function.
+ * @brief Get the default resampling quality.
+ *
+ * This is the quality setting which the engine uses when the instrument
+ * does not use the opcode `sample_quality`. The engine uses distinct
+ * default quality settings for live mode and freewheeling mode,
+ * which both can be accessed by the means of this function.
* @since 0.4.0
*
- * @param synth The synth.
- * @param[in] mode The processing mode.
+ * @param synth The synth.
+ * @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);
/**
- * @brief Set the default resampling quality. This is the quality setting
- * which the engine uses when the instrument does not use the
- * opcode `sample_quality`. The engine uses distinct default quality
- * settings for live mode and freewheeling mode, which both can be
- * accessed by the means of this function.
+ * @brief Set the default resampling quality.
+ *
+ * This is the quality setting which the engine uses when the instrument
+ * does not use the opcode `sample_quality`. The engine uses distinct
+ * default quality settings for live mode and freewheeling mode,
+ * which both can be accessed by the means of this function.
* @since 0.4.0
*
- * @param synth The synth.
- * @param[in] mode The processing mode.
- * @param[in] quality The desired sample quality, in the range 1 to 10.
+ * @param synth The synth.
+ * @param[in] mode The processing mode.
+ * @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);
/**
- * @brief Set the global instrument volume.
+ * @brief Set the global instrument volume.
+ * @since 0.2.0
*
- * @param synth The synth.
- * @param volume The new volume.
+ * @param synth The synth.
+ * @param volume The new 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);
/**
- * @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.
+ * @brief Set the number of voices used by the synth.
*
- * @param synth The synth.
- * @param num_voices The number of voices.
+ * 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.
+ * @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);
+
/**
- * @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);
/**
- * @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);
+
/**
- * @brief Get the number of bytes allocated from the synth. Note that this
- * value can be less than the actual memory usage since it only
- * counts the buffer objects managed by sfizz.
+ * @brief Get the number of bytes allocated from the synth.
*
- * @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);
/**
- * @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);
+
/**
- * @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);
+
/**
- * @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.
+ * @brief Return a comma separated list of unknown opcodes.
*
- * @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);
/**
- * @brief Check if the SFZ should be reloaded.
- * Depending on the platform this can create file descriptors.
+ * @brief Check if the SFZ should be reloaded.
*
- * @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
- * been modified since the sfz file was loaded, @false otherwise.
+ * @param synth The synth.
+ *
+ * @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);
/**
- * @brief Check if the scala file should be reloaded.
- * Depending on the platform this can create file descriptors.
+ * @brief Check if the scala file should be reloaded.
*
- * @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);
/**
- * @brief Enable logging of timings to sidecar CSV files. This can produce
- * many outputs so use with caution.
+ * @brief Enable logging of timings to sidecar CSV files.
+ * @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);
/**
- * @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);
/**
- * @brief Enable logging of timings to sidecar CSV files. This can produce
- * many outputs so use with caution.
+ * @brief Enable logging of timings to sidecar CSV files.
+ * @since 0.3.2
*
- * @param synth The synth.
- * @param prefix The prefix.
+ * @note This can produce many outputs so use with caution.
+ *
+ * @param synth The synth.
+ * @param prefix The 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);
/**
- * @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.
+ * @brief Add external definitions prior to loading.
* @since 0.4.0
*
- * @param synth
- * @param id
- * @param value
+ * @note These do not get reset by loading or resetting the synth.
+ * You need to call sfizz_clear_external_definitions() to erase them.
+ *
+ * @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);
@@ -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.
* @since 0.4.0
*
- * @param synth
+ * @param synth The 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
/**
- * @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
+ *
+ * @param synth The 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.
* @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.
*/
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.
* @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);
@@ -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
* @since 0.4.0
*
+ * @param synth The 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.
* @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.
*/
-
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.
* @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);
diff --git a/src/sfizz.hpp b/src/sfizz.hpp
index 957c7d41..ab39323a 100644
--- a/src/sfizz.hpp
+++ b/src/sfizz.hpp
@@ -6,7 +6,7 @@
/**
@file
- @brief sfizz public C++ API
+ @brief sfizz public C++ API.
*/
#pragma once
@@ -29,22 +29,23 @@ namespace sfz
{
class Synth;
/**
- * @brief Main class
+ * @brief Main class.
*/
class SFIZZ_EXPORTED_API Sfizz
{
public:
/**
- * @brief Construct a new Sfizz object. 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.
+ * @brief Construct a new Sfizz object.
*
+ * 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();
/**
- * @brief Processing mode
+ * @brief Processing mode.
+ * @since 0.4.0
*/
enum ProcessMode {
ProcessLive,
@@ -57,6 +58,7 @@ public:
* 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
* 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.
*
@@ -86,7 +88,8 @@ public:
* @brief Sets the tuning from a Scala file loaded from the file system.
* @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,
* @false if some error occurred.
*/
@@ -96,7 +99,8 @@ public:
* @brief Sets the tuning from a Scala file loaded from memory.
* @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,
* @false if some error occurred.
*/
@@ -136,6 +140,7 @@ public:
/**
* @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).
* @since 0.4.0
*
@@ -145,57 +150,68 @@ public:
/**
* @brief Return the current number of regions loaded.
+ * @since 0.2.0
*/
int getNumRegions() const noexcept;
/**
* @brief Return the current number of groups loaded.
+ * @since 0.2.0
*/
int getNumGroups() const noexcept;
/**
* @brief Return the current number of masters loaded.
+ * @since 0.2.0
*/
int getNumMasters() const noexcept;
/**
* @brief Return the current number of curves loaded.
+ * @since 0.2.0
*/
int getNumCurves() const noexcept;
/**
* @brief Return a list of unsupported opcodes, if any.
+ * @since 0.2.0
*/
const std::vector& getUnknownOpcodes() const noexcept;
/**
* @brief Return the number of preloaded samples in the synth.
+ * @since 0.2.0
*/
size_t getNumPreloadedSamples() const noexcept;
/**
- * @brief Set the maximum size of the blocks for the callback. The actual
- * size can be lower in each callback but should not be larger
+ * @brief Set the maximum size of the blocks for the callback.
+ *
+ * The actual size can be lower in each callback but should not be larger
* than this value.
+ * @since 0.2.0
*
* @param samplesPerBlock The number of samples per block.
*/
void setSamplesPerBlock(int samplesPerBlock) noexcept;
/**
- * @brief Set the sample rate. If you do not call it it is initialized
- * to sfz::config::defaultSampleRate.
+ * @brief Set the sample rate.
+ *
+ * If you do not call it it is initialized to `sfz::config::defaultSampleRate`.
+ * @since 0.2.0
*
* @param sampleRate The sample rate.
*/
void setSampleRate(float sampleRate) noexcept;
/**
- * @brief Get the default resampling quality. This is the quality setting
- * which the engine uses when the instrument does not use the
- * opcode `sample_quality`. The engine uses distinct default quality
- * settings for live mode and freewheeling mode, which both can be
- * accessed by the means of this function.
+ * @brief Get the default resampling quality.
+ *
+ * This is the quality setting which the engine uses when the instrument
+ * does not use the opcode `sample_quality`. The engine uses distinct
+ * default quality settings for live mode and freewheeling mode,
+ * which both can be accessed by the means of this function.
* @since 0.4.0
*
* @param[in] mode The processing mode.
@@ -205,11 +221,12 @@ public:
int getSampleQuality(ProcessMode mode);
/**
- * @brief Set the default resampling quality. This is the quality setting
- * which the engine uses when the instrument does not use the
- * opcode `sample_quality`. The engine uses distinct default quality
- * settings for live mode and freewheeling mode, which both can be
- * accessed by the means of this function.
+ * @brief Set the default resampling quality.
+ *
+ * This is the quality setting which the engine uses when the instrument
+ * does not use the opcode `sample_quality`. The engine uses distinct
+ * default quality settings for live mode and freewheeling mode,
+ * which both can be accessed by the means of this function.
* @since 0.4.0
*
* @param[in] mode The processing mode.
@@ -219,19 +236,23 @@ public:
/**
* @brief Return the current value for the volume, in dB.
+ * @since 0.2.0
*/
float getVolume() const noexcept;
/**
- * @brief Set the value for the volume. This value will be
- * clamped within sfz::default::volumeRange.
+ * @brief Set the value for the volume.
+ *
+ * This value will be clamped within `sfz::default::volumeRange`.
+ * @since 0.2.0
*
* @param volume The new volume.
*/
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
* 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;
/**
- * @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
* 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
+ * @since 0.2.0
*
- * @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().
+ * @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().
* @param ccNumber the cc number.
* @param ccValue the cc value.
*/
@@ -264,8 +287,8 @@ public:
* @brief Send a high precision CC event to the synth
* @since 0.4.0
*
- * @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().
+ * @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().
* @param ccNumber the cc number.
* @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
+ * @since 0.2.0
*
* @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().
* @param pitch the pitch value centered between -8192 and 8192.
*/
void pitchWheel(int delay, int pitch) noexcept;
/**
* @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
- * the block in the next call to renderBlock().
+ * @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().
* @param aftertouch the aftertouch value.
*/
void aftertouch(int delay, uint8_t aftertouch) noexcept;
/**
* @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
- * the block in the next call to renderBlock().
+ * @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().
* @param secondsPerBeat the new period of the beat.
*/
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 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 delay The delay.
+ * @param beatsPerBar The number of beats per bar, or time signature numerator.
+ * @param beatUnit The note corresponding to one beat, or time signature denominator.
*/
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 bar The current bar.
- * @param bar_beat The fractional position of the current beat within the bar.
+ * @param delay The delay.
+ * @param bar The current bar.
+ * @param barBeat The fractional position of the current beat within the bar.
*/
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 playback_state The playback state, 1 if playing, 0 if stopped.
+ * @param delay The delay.
+ * @param playbackState The playback state, 1 if playing, 0 if stopped.
*/
void playbackState(int delay, int playbackState);
/**
- * @brief Render an block of audio data in the buffer. This call will reset
- * the synth in its waiting state for the next batch of events. The buffers must
- * be float[numSamples][numOutputs * 2].
+ * @brief Render an block of audio data in the buffer.
+ *
+ * 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 numFrames the number of stereo frames in the block.
@@ -338,20 +368,24 @@ public:
/**
* @brief Return the number of active voices.
+ * @since 0.2.0
*/
int getNumActiveVoices() const noexcept;
/**
* @brief Return the total number of voices in the synth (the polyphony).
+ * @since 0.2.0
*/
int getNumVoices() const noexcept;
/**
* @brief Change the number of voices (the polyphony).
+ *
* 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.
+ * @since 0.2.0
*
* @param numVoices The number of voices.
*/
@@ -359,6 +393,7 @@ public:
/**
* @brief Set the oversampling factor to a new value.
+ *
* It will kill all the voices, and trigger a reloading of every file in
* 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.
* 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 factor The oversampling factor.
*
@@ -385,15 +421,18 @@ public:
/**
* @brief Return the current oversampling factor.
+ * @since 0.2.0
*/
int getOversamplingFactor() const noexcept;
/**
* @brief Set the preloaded file size.
+ *
* 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 preload size is the same as the current one, it will
* release the lock immediately and exit.
+ * @since 0.2.0
*
* @param preloadSize The preload size.
*/
@@ -401,30 +440,37 @@ public:
/**
* @brief Return the current preloaded file size.
+ * @since 0.2.0
*/
uint32_t getPreloadSize() const noexcept;
/**
* @brief Return the number of allocated buffers.
+ * @since 0.2.0
*/
int getAllocatedBuffers() const noexcept;
/**
* @brief Return the number of bytes allocated through the buffers.
+ * @since 0.2.0
*/
int getAllocatedBytes() const noexcept;
/**
- * @brief Enable freewheeling on the synth. This will wait for background
- * loaded files to finish loading before each render callback to ensure that
- * there will be no dropouts.
+ * @brief Enable freewheeling on the synth.
+ *
+ * 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;
/**
- * @brief Disable freewheeling on the synth. You should disable freewheeling
- * before live use of the plugin otherwise the audio thread will lock.
+ * @brief Disable freewheeling on the synth.
*
+ * You should disable freewheeling before live use of the plugin
+ * otherwise the audio thread will lock.
+ * @since 0.2.0
*/
void disableFreeWheeling() noexcept;
@@ -432,6 +478,7 @@ public:
* @brief Check if the SFZ should be reloaded.
*
* Depending on the platform this can create file descriptors.
+ * @since 0.2.0
*
* @return @true if any included files (including the root file) have
* 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.
*
* 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 false
+ * @return @true if a scala file has been loaded and has changed, @false otherwise.
*/
bool shouldReloadScala();
/**
- * @brief Enable logging of timings to sidecar CSV files. This can produce
- * many outputs so use with caution.
+ * @brief Enable logging of timings to sidecar CSV files.
+ * @since 0.3.0
+ *
+ * @note This can produce many outputs so use with caution.
*
* @param prefix the file prefix to use for logging.
*/
void enableLogging() noexcept;
/**
- * @brief Enable logging of timings to sidecar CSV files. This can produce
- * many outputs so use with caution.
+ * @brief Enable logging of timings to sidecar CSV files.
+ * @since 0.3.2
+ *
+ * @note This can produce many outputs so use with caution.
*
* @param prefix the file prefix to use for logging.
*/
@@ -466,52 +517,54 @@ public:
/**
* @brief Set the logging prefix.
+ * @since 0.3.2
*
* @param prefix
*/
void setLoggingPrefix(const std::string& prefix) noexcept;
/**
- * @brief
- *
+ * @brief Disable logging of timings to sidecar CSV files.
+ * @since 0.3.0
*/
void disableLogging() noexcept;
/**
* @brief Shuts down the current processing, clear buffers and reset the voices.
+ * @since 0.3.2
*/
void allSoundOff() noexcept;
/**
- * @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.
+ * @brief Add external definitions prior to loading.
* @since 0.4.0
*
- * @param id
- * @param value
+ * @note These do not get reset by loading or resetting the synth.
+ * 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);
/**
* @brief Clears external definitions for the next file loading.
* @since 0.4.0
- *
*/
void clearExternalDefinitions();
/**
- * @brief Get the key labels, if any
+ * @brief Get the key labels, if any.
* @since 0.4.0
- *
*/
const std::vector>& getKeyLabels() const noexcept;
+
/**
- * @brief Get the CC labels, if any
+ * @brief Get the CC labels, if any.
* @since 0.4.0
- *
*/
const std::vector>& getCCLabels() const noexcept;
+
private:
std::unique_ptr synth;
};