Update docs

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.

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
+     * @brief Set the oversampling factor to a new value.
-     * kill all the voices, and trigger a reloading of every file in the FilePool under
+     * It will kill all the voices, and trigger a reloading of every file in
-     * the new oversampling.
+     * 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.
      */

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
+     * @brief Set the oversampling factor to a new value.
-     * kill all the voices, and trigger a reloading of every file in the FilePool under
+     * It will kill all the voices, and trigger a reloading of every file in
-     * the new oversampling.
+     * 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
      */