From 2e8b637f09e47518248f9b6c0dc5529039963b15 Mon Sep 17 00:00:00 2001 From: Paul Ferrand Date: Wed, 13 May 2020 22:10:02 +0200 Subject: [PATCH] Update docs --- src/sfizz.h | 14 +++++++++++++- src/sfizz.hpp | 31 +++++++++++++++++++++++++++---- src/sfizz/Synth.h | 22 +++++++++++++++++----- 3 files changed, 57 insertions(+), 10 deletions(-) diff --git a/src/sfizz.h b/src/sfizz.h index 69be1a4a..13432f5d 100644 --- a/src/sfizz.h +++ b/src/sfizz.h @@ -247,7 +247,10 @@ 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. + * 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. * * @param synth The synth. * @param[in] preload_size The preload size. @@ -277,6 +280,11 @@ SFIZZ_EXPORTED_API sfizz_oversampling_factor_t sfizz_get_oversampling_factor(sfi * 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. + * * @param synth The synth. * @param[in] oversampling The oversampling factor. * @@ -301,6 +309,10 @@ 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. * * @param synth The synth. * @param num_voices The number of voices. diff --git a/src/sfizz.hpp b/src/sfizz.hpp index 4c58fe81..63bd8173 100644 --- a/src/sfizz.hpp +++ b/src/sfizz.hpp @@ -214,15 +214,34 @@ public: /** * @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. * * @param numVoices The number of voices. */ void setNumVoices(int numVoices) noexcept; /** - * @brief Set the oversampling factor to a new value. This will disable all callbacks - * kill all the voices, and trigger a reloading of every file in the FilePool under - * the new oversampling. + * @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. + * + * 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. * * @param factor The oversampling factor. * @@ -236,7 +255,11 @@ public: int getOversamplingFactor() const noexcept; /** - * @brief Set the preloaded file size. This will disable the callback. + * @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. * * @param preloadSize The preload size. */ diff --git a/src/sfizz/Synth.h b/src/sfizz/Synth.h index bc73dc46..5cbeb455 100644 --- a/src/sfizz/Synth.h +++ b/src/sfizz/Synth.h @@ -286,7 +286,11 @@ public: */ 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 + * 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 numVoices */ @@ -302,9 +306,13 @@ public: void garbageCollect() noexcept; /** - * @brief Set the oversampling factor to a new value. This will disable all callbacks - * kill all the voices, and trigger a reloading of every file in the FilePool under - * the new oversampling. + * @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. + * 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. * * @param factor */ @@ -318,7 +326,11 @@ public: Oversampling getOversamplingFactor() const noexcept; /** - * @brief Set the preloaded file size. This will disable the callback. + * @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. * * @param factor */