diff --git a/src/sfizz.h b/src/sfizz.h index 5e5c6af8..42585a9d 100644 --- a/src/sfizz.h +++ b/src/sfizz.h @@ -27,7 +27,13 @@ extern "C" { #endif +/** + * @brief Synth handle + */ typedef struct sfizz_synth_t sfizz_synth_t; +/** + * @brief Oversampling factor + */ typedef enum { SFIZZ_OVERSAMPLING_X1 = 1, SFIZZ_OVERSAMPLING_X2 = 2, @@ -40,14 +46,13 @@ typedef enum { * 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. - * - * @return sfizz_synth_t* */ SFIZZ_EXPORTED_API sfizz_synth_t* sfizz_create_synth(); + /** * @brief Frees an existing sfizz synth. * - * @param synth The synth to destroy + * @param synth The synth to destroy. */ SFIZZ_EXPORTED_API void sfizz_free(sfizz_synth_t* synth); @@ -60,88 +65,76 @@ SFIZZ_EXPORTED_API void sfizz_free(sfizz_synth_t* synth); * @param path A null-terminated string representing a path to an SFZ * file. * - * @return true when file loading went OK. - * @return 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_file(sfizz_synth_t* synth, const char* path); /** - * @brief Returns the number of regions in the currently loaded SFZ file. + * @brief Return the number of regions in the currently loaded SFZ file. * - * @param synth The synth - * - * @return int the number of regions + * @param synth The synth. */ SFIZZ_EXPORTED_API int sfizz_get_num_regions(sfizz_synth_t* synth); /** - * @brief Returns the number of groups in the currently loaded SFZ file. + * @brief Return the number of groups in the currently loaded SFZ file. * - * @param synth The synth - * - * @return int the number of groups + * @param synth The synth. */ SFIZZ_EXPORTED_API int sfizz_get_num_groups(sfizz_synth_t* synth); /** - * @brief Returns the number of masters in the currently loaded SFZ file. + * @brief Return the number of masters in the currently loaded SFZ file. * - * @param synth The synth - * - * @return int the number of masters + * @param synth The synth. */ SFIZZ_EXPORTED_API int sfizz_get_num_masters(sfizz_synth_t* synth); /** - * @brief Returns the number of curves in the currently loaded SFZ file. + * @brief Return the number of curves in the currently loaded SFZ file. * - * @param synth The synth - * - * @return int the number of curves + * @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. * - * @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 char* 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 Returns the number of preloaded samples for the current SFZ file. + * @brief Return the number of preloaded samples for the current SFZ file. * - * @param synth The synth - * - * @return int the number of preloaded samples + * @param synth The synth. */ SFIZZ_EXPORTED_API size_t sfizz_get_num_preloaded_samples(sfizz_synth_t* synth); /** - * @brief Returns the number of active voices. Note that this function is a + * @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. * - * @param synth The synth - * - * @return size_t the number of playing voices + * @param synth The synth. */ SFIZZ_EXPORTED_API int sfizz_get_num_active_voices(sfizz_synth_t* synth); /** - * @brief Sets the expected number of samples per block. If unsure, give an + * @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. * - * @param synth The synth - * @param samples_per_block the number of samples per block + * @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 Sets the sample rate for the synth. This is the output sample + * @brief Set the sample rate for the synth. This is the output sample * rate. This setting does not affect the internal processing. * * @param synth The synth - * @param sample_rate the sample rate + * @param sample_rate The sample rate. */ SFIZZ_EXPORTED_API void sfizz_set_sample_rate(sfizz_synth_t* synth, float sample_rate); @@ -150,10 +143,10 @@ SFIZZ_EXPORTED_API void sfizz_set_sample_rate(sfizz_synth_t* synth, float sample * 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 - * @param delay the delay of the event in the block, in samples. - * @param note_number the MIDI note number - * @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); @@ -164,10 +157,10 @@ SFIZZ_EXPORTED_API void sfizz_send_note_on(sfizz_synth_t* synth, int delay, int * As per the SFZ spec the velocity of note-off events is usually replaced by * the note-on 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 + * @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); @@ -176,38 +169,39 @@ SFIZZ_EXPORTED_API void sfizz_send_note_off(sfizz_synth_t* synth, int delay, int * to happen before the call to sfizz_render_block in each block and * should appear in order of the delays. * - * @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 + * @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 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. * - * @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) * - * @param synth - * @param delay - * @param aftertouch + * @param synth + * @param delay + * @param aftertouch */ SFIZZ_EXPORTED_API void sfizz_send_aftertouch(sfizz_synth_t* synth, int delay, char aftertouch); /** * @brief Send a tempo event. (CURRENTLY UNIMPLEMENTED) * - * @param synth The synth - * @param delay The delay - * @param seconds_per_quarter The seconds per quarter + * @param synth The synth. + * @param delay The delay. + * @param seconds_per_quarter The seconds per quarter. */ SFIZZ_EXPORTED_API void sfizz_send_tempo(sfizz_synth_t* synth, int delay, float seconds_per_quarter); @@ -219,11 +213,11 @@ SFIZZ_EXPORTED_API void sfizz_send_tempo(sfizz_synth_t* synth, int delay, float * block. The synth will memorize the inputs and render sample * accurates envelopes depending on the input events passed to it. * - * @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 + * @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); @@ -232,18 +226,16 @@ SFIZZ_EXPORTED_API void sfizz_render_block(sfizz_synth_t* synth, float** channel * @brief Get the size of the preloaded data. This returns the number of * floats used in the preloading buffers. * - * @param synth The synth - * - * @return the preloaded data size in sizeof(floats) + * @param synth The synth. */ SFIZZ_EXPORTED_API unsigned int sfizz_get_preload_size(sfizz_synth_t* synth); /** - * @brief Sets 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). This will disable the callbacks for the duration of the * load. * - * @param synth The synth - * @param[in] preload_size The preload size + * @param synth The synth. + * @param[in] preload_size The preload size. */ SFIZZ_EXPORTED_API void sfizz_set_preload_size(sfizz_synth_t* synth, unsigned int preload_size); @@ -252,9 +244,7 @@ SFIZZ_EXPORTED_API void sfizz_set_preload_size(sfizz_synth_t* synth, unsigned in * 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 - * - * @return The internal sample rate of the engine + * @param synth The synth. */ SFIZZ_EXPORTED_API sfizz_oversampling_factor_t sfizz_get_oversampling_factor(sfizz_synth_t* synth); /** @@ -272,51 +262,46 @@ 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. * - * @param synth The synth - * @param[in] preload_size The preload size + * @param synth The synth. + * @param[in] oversampling The oversampling factor. * - * @return True if the oversampling factor was correct + * @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 Set the global instrument volume. * - * @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 Get the global instrument volume. + * @brief Return the global instrument volume. * - * @param synth The synth - * - * @return float the instrument volume + * @param synth The synth. */ SFIZZ_EXPORTED_API float sfizz_get_volume(sfizz_synth_t* synth); /** - * @brief Sets the number of voices used by the synth + * @brief Set the number of voices used by the synth. * - * @param synth The synth - * @param num_voices The number voices + * @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 Returns the number of voices + * @brief Return the number of voices. * - * @param synth - * @return num_voices + * @param synth The synth. */ SFIZZ_EXPORTED_API int sfizz_get_num_voices(sfizz_synth_t* synth); /** - * @brief Get the number of allocated buffers from the synth. + * @brief Return the number of allocated buffers from the synth. * - * @param synth The synth - * - * @return The number of buffers held by the synth + * @param synth The synth. */ SFIZZ_EXPORTED_API int sfizz_get_num_buffers(sfizz_synth_t* synth); /** @@ -324,73 +309,70 @@ SFIZZ_EXPORTED_API int sfizz_get_num_buffers(sfizz_synth_t* synth); * value can be less than the actual memory usage since it only * counts the buffer objects managed by sfizz. * - * @param synth The synth - * - * @return The number of bytes held by the synth in buffers; + * @param synth The synth. */ SFIZZ_EXPORTED_API int sfizz_get_num_bytes(sfizz_synth_t* synth); /** - * @brief Enables freewheeling on the synth. + * @brief Enable freewheeling on the synth. * - * @param synth + * @param synth The synth. */ SFIZZ_EXPORTED_API void sfizz_enable_freewheeling(sfizz_synth_t* synth); /** - * @brief Disables freewheeling on the synth. + * @brief Disable freewheeling on the synth. * - * @param synth + * @param synth The synth. */ SFIZZ_EXPORTED_API void sfizz_disable_freewheeling(sfizz_synth_t* synth); /** - * @brief Get 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. + * The caller has to free() the string returned. + * This function allocates memory, do not call on the audio thread. * - * @param synth - * @return char* + * @param synth The 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. * - * Depending on the platform this can create file descriptors. + * @param synth The synth. * - * @param synth - * @return true if any included files (including the root file) have - * been modified since the sfz file was loaded. - * @return false + * @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 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. This can produce + * many outputs so use with caution. * - * @param synth + * @param synth The synth. */ SFIZZ_EXPORTED_API void sfizz_enable_logging(sfizz_synth_t* synth); /** - * @brief Disable logging + * @brief Disable logging. * - * @param 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. This can produce + * many outputs so use with caution. * - * @param synth + * @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. * - * @param synth + * @param synth The synth. */ SFIZZ_EXPORTED_API void sfizz_all_sound_off(sfizz_synth_t* synth); diff --git a/src/sfizz.hpp b/src/sfizz.hpp index d0e62e37..b2af98c1 100644 --- a/src/sfizz.hpp +++ b/src/sfizz.hpp @@ -4,6 +4,11 @@ // license. You should have receive a LICENSE.md file along with the code. // If not, contact the sfizz maintainers at https://github.com/sfztools/sfizz +/** + @file + @brief sfizz public C++ API +*/ + #include #include #include @@ -21,6 +26,9 @@ namespace sfz { class Synth; +/** + * @brief Main class + */ class SFIZZ_EXPORTED_API Sfizz { public: @@ -32,6 +40,7 @@ public: */ Sfizz(); ~Sfizz(); + /** * @brief Empties the current regions and load a new SFZ file into the synth. * @@ -39,68 +48,70 @@ public: * UI thread for example, although it may generate a click. However it is * not reentrant, so you should not call it from concurrent threads. * - * @param file - * @return true - * @return false if the file was not found or no regions were loaded. + * @param path The path to the file to load, as string. + * + * @return @false if the file was not found or no regions were loaded, + * @true otherwise. */ bool loadSfzFile(const std::string& path); + /** - * @brief Get the current number of regions loaded - * - * @return int + * @brief Return the current number of regions loaded. */ int getNumRegions() const noexcept; + /** - * @brief Get the current number of groups loaded - * - * @return int + * @brief Return the current number of groups loaded. */ int getNumGroups() const noexcept; + /** - * @brief Get the current number of masters loaded - * - * @return int + * @brief Return the current number of masters loaded. */ int getNumMasters() const noexcept; + /** - * @brief Get the current number of curves loaded - * - * @return int + * @brief Return the current number of curves loaded. */ int getNumCurves() const noexcept; - const std::vector& getUnknownOpcodes() const noexcept; + /** - * @brief Get the number of preloaded samples in the synth - * - * @return size_t + * @brief Return a list of unsupported opcodes, if any. + */ + const std::vector& getUnknownOpcodes() const noexcept; + + /** + * @brief Return the number of preloaded samples in the synth. */ 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 * than this value. * - * @param samplesPerBlock + * @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. * - * @param sampleRate + * @param sampleRate The sample rate. */ void setSampleRate(float sampleRate) noexcept; + /** - * @brief Get the current value for the volume, in dB. - * - * @return float + * @brief Return the current value for the volume, in dB. */ float getVolume() const noexcept; - /** + + /** * @brief Set the value for the volume. This value will be * clamped within sfz::default::volumeRange. * - * @param volume + * @param volume The new volume. */ void setVolume(float volume) noexcept; @@ -109,125 +120,122 @@ public: * * @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 noteNumber the midi note number - * @param velocity the midi note velocity + * @param noteNumber the midi note number. + * @param velocity the midi note velocity. */ void noteOn(int delay, int noteNumber, uint8_t velocity) noexcept; + /** * @brief Send a note off event to 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 noteNumber the midi note number - * @param velocity the midi note velocity + * @param noteNumber the midi note number. + * @param velocity the midi note velocity. */ void noteOff(int delay, int noteNumber, uint8_t velocity) noexcept; + /** * @brief Send a CC event to 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 ccNumber the cc number - * @param ccValue the cc value + * @param ccNumber the cc number. + * @param ccValue the cc value. */ void cc(int delay, int ccNumber, uint8_t ccValue) noexcept; + /** * @brief Send a pitch bend event to 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 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; + /** - * @brief Send a aftertouch event to the synth + * @brief Send a aftertouch event to the synth. (CURRENTLY UNIMPLEMENTED) * * @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 + * @param aftertouch the aftertouch value. */ void aftertouch(int delay, uint8_t aftertouch) noexcept; + /** - * @brief Send a tempo event to the synth + * @brief Send a tempo event to the synth. (CURRENTLY UNIMPLEMENTED) * * @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 secondsPerQuarter the new period of the quarter note + * @param secondsPerQuarter the new period of the quarter note. */ void tempo(int delay, float secondsPerQuarter) noexcept; + /** * @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]. * - * @param buffers the buffers to write the next block into - * @param numSamples the number of stereo frames in the block - * @param numOutputs the number of stereo outputs + * @param buffers the buffers to write the next block into. + * @param numFrames the number of stereo frames in the block. + * @param numOutputs the number of stereo outputs. */ void renderBlock(float** buffers, size_t numFrames, int numOutputs = 1) noexcept; /** - * @brief Get the number of active voices - * - * @return int + * @brief Return the number of active voices. */ int getNumActiveVoices() const noexcept; + /** - * @brief Get the total number of voices in the synth (the polyphony) - * - * @return int + * @brief Return the total number of voices in the synth (the polyphony). */ int getNumVoices() const noexcept; + /** - * @brief Change the number of voices (the polyphony) + * @brief Change the number of voices (the polyphony). * - * @param numVoices + * @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. * - * @param factor - * @return true if the factor did indeed change + * @param factor The oversampling factor. + * + * @return @true if the factor did indeed change, @false otherwise. */ bool setOversamplingFactor(int factor) noexcept; /** - * @brief get the current oversampling factor - * - * @return Oversampling + * @brief Return the current oversampling factor. */ int getOversamplingFactor() const noexcept; /** * @brief Set the preloaded file size. This will disable the callback. * - * @param factor + * @param preloadSize The preload size. */ void setPreloadSize(uint32_t preloadSize) noexcept; /** - * @brief get the current preloaded file size - * - * @return Oversampling + * @brief Return the current preloaded file size. */ uint32_t getPreloadSize() const noexcept; /** - * @brief Gets the number of allocated buffers. - * - * @return The allocated buffers. + * @brief Return the number of allocated buffers. */ int getAllocatedBuffers() const noexcept; /** - * @brief Gets the number of bytes allocated through the buffers - * - * @return The allocated bytes. + * @brief Return the number of bytes allocated through the buffers. */ int getAllocatedBytes() const noexcept; @@ -235,55 +243,59 @@ public: * @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. - * */ 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. * */ void disableFreeWheeling() noexcept; + /** * @brief Check if the SFZ should be reloaded. * * Depending on the platform this can create file descriptors. * - * @return true if any included files (including the root file) have - * been modified since the sfz file was loaded. - * @return false + * @return @true if any included files (including the root file) have + * been modified since the sfz file was loaded, @false otherwise. */ bool shouldReloadFile(); + /** * @brief Enable logging of timings to sidecar CSV files. 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; + /** * @brief Enable logging of timings to sidecar CSV files. 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(const std::string& prefix) noexcept; + /** - * @brief Set the logging prefix + * @brief Set the logging prefix. * * @param prefix */ void setLoggingPrefix(const std::string& prefix) noexcept; + /** - * @brief Disable logging; - * + * @brief Disable logging. */ void disableLogging() noexcept; + /** * @brief Shuts down the current processing, clear buffers and reset the voices. - * */ void allSoundOff() noexcept; + private: std::unique_ptr synth; };