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

Documentation work

Browse source
This commit is contained in:
Paul Ferrand 2019-11-23 16:56:16 +01:00
parent d5ea69cea1
commit 0bc587f217
10 changed files with 694 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

70
sfizz/AtomicGuard.h
View file

@ -21,10 +21,63 @@
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
/**
* @brief This file contains a pair of RAII helpers that handle some form
* of lock-free mutex-type protection adapter to audio applications where you have 1 priority thread
* that should never block and would rather return silence than wait, and another low-priority
* thread that handles long computations.
*
* @code{.cpp}
*
* // Somewhere in a class...
* std::atomic<bool> canEnterCallback;
* std::atomic<bool> inCallback;
*
* void functionThatSuspendsCallback()
* {
* AtomicDisabler callbackDisabler { canEnterCallback };
*
* while (inCallback) {
* std::this_thread::sleep_for(1ms);
* }
*
* // Do your thing.
* }
*
* void callback(int samplesPerBlock) noexcept
* {
* AtomicGuard callbackGuard { inCallback };
* if (!canEnterCallback)
* return;
*
* // Do your thing.
* }
* @endcode
* There are probably many ways to improve these and probably even debug them.
* The spinlocking itself could be integrated in the constructor, although the
* check for return in the callback could not.
*/
#include <atomic>
namespace sfz
{
/**
* @brief Simple class to set an atomic to true and automatically set it back to false on
* destruction.
*
* You call it like this assuming you need indicate that you are in e.g. a callback
* @code{.cpp}
* void functionToProtect()
* {
* AtomicGuard { guard };
*
* // Do stuff, the atomic will be set back to false as soon as you're back
* }
* @endcode
* Note that this is not thread-safe at all, in the sense that it is only meant to be
* used with 2 threads along with the AtomicDisabler. One thread uses AtomicGuards, the other
* AtomicDisablers, and no other contending thread can share this pair of atomics.
*/
class AtomicGuard
{
public:
@ -42,6 +95,23 @@ private:
std::atomic<bool>& guard;
};
/**
* @brief Simple class to set an atomic to false and automatically set it back to true on
* destruction.
*
* You call it like this assuming you need to disable e.g. a callback
* @code{.cpp}
* void functionThatDisableAnotherFunction()
* {
* AtomicDisabler { disabler };
*
* // Do stuff, the atomic will be set back to true as soon as you're back
* }
* @endcode
* Note that this is not thread-safe at all, in the sense that it is only meant to be
* used with 2 threads along with the AtomicGuard. One thread uses AtomicGuards, the other
* AtomicDisabler, and no other contending thread can share this pair of atomics.
*/
class AtomicDisabler
{
public:

102
sfizz/AudioBuffer.h
View file

@ -32,7 +32,16 @@
namespace sfz
{
/**
* @brief A class to handle a collection of buffers, where each buffer has the same size.
*
* Unlike AudioSpan, this class *owns* its underlying buffers and they are freed when the buffer
* is destroyed.
*
* @tparam Type the underlying type of the buffers
* @tparam MaxChannels the maximum number of channels in the buffer
* @tparam Alignment the alignment for the buffers
*/
template <class Type, unsigned int MaxChannels = sfz::config::numChannels, unsigned int Alignment = SIMDConfig::defaultAlignment>
class AudioBuffer {
public:
@ -43,9 +52,21 @@ public:
using const_iterator = const_pointer;
using size_type = size_t;
/**
* @brief Construct a new Audio Buffer object
*
*/
AudioBuffer()
{
}
/**
* @brief Construct a new Audio Buffer object with a specified number of
* channels and frames.
*
* @param numChannels
* @param numFrames
*/
AudioBuffer(int numChannels, int numFrames)
: numChannels(numChannels)
, numFrames(numFrames)
@ -54,6 +75,13 @@ public:
buffers[i] = std::make_unique<buffer_type>(numFrames);
}
/**
* @brief Resizes all the underlying buffers to a new size.
*
* @param newSize
* @return true if the resize worked
* @return false otherwise
*/
bool resize(size_type newSize)
{
bool returnedOK = true;
@ -62,6 +90,12 @@ public:
return returnedOK;
}
/**
* @brief Return an iterator to a specific channel with a non-const type.
*
* @param channelIndex
* @return iterator
*/
iterator channelWriter(int channelIndex)
{
ASSERT(channelIndex < numChannels)
@ -71,6 +105,12 @@ public:
return {};
}
/**
* @brief Returns a sentinel for the channelWriter(channelIndex) iterator
*
* @param channelIndex
* @return iterator
*/
iterator channelWriterEnd(int channelIndex)
{
ASSERT(channelIndex < numChannels)
@ -80,6 +120,12 @@ public:
return {};
}
/**
* @brief Returns a const iterator for a specific channel
*
* @param channelIndex
* @return const_iterator
*/
const_iterator channelReader(int channelIndex) const
{
ASSERT(channelIndex < numChannels)
@ -89,6 +135,12 @@ public:
return {};
}
/**
* @brief Returns a sentinel for the channelReader(channelIndex) iterator
*
* @param channelIndex
* @return const_iterator
*/
const_iterator channelReaderEnd(int channelIndex) const
{
ASSERT(channelIndex < numChannels)
@ -98,6 +150,12 @@ public:
return {};
}
/**
* @brief Get a Span for a specific channel
*
* @param channelIndex
* @return absl::Span<value_type>
*/
absl::Span<value_type> getSpan(int channelIndex) const
{
ASSERT(channelIndex < numChannels)
@ -107,32 +165,67 @@ public:
return {};
}
/**
* @brief Get a const Span object for a specific channel
*
* @param channelIndex
* @return absl::Span<const value_type>
*/
absl::Span<const value_type> getConstSpan(int channelIndex) const
{
return getSpan(channelIndex);
}
/**
* @brief Add a channel to the buffer with the current number of frames.
*
*/
void addChannel()
{
if (numChannels < MaxChannels)
buffers[numChannels++] = std::make_unique<buffer_type>(numFrames);
}
/**
* @brief Get the number of elements in each buffer
*
* @return size_type
*/
size_type getNumFrames() const
{
return numFrames;
}
/**
* @brief Get the number of channels
*
* @return int
*/
int getNumChannels() const
{
return numChannels;
}
/**
* @brief Check if the buffers contains no elements
*
* @return true
* @return false
*/
bool empty() const
{
return numFrames == 0;
}
/**
* @brief Get a reference to a given element in a given buffer.
*
* In release builds this is not checked and may touch bad memory.
*
* @param channelIndex
* @param frameIndex
* @return Type&
*/
Type& getSample(int channelIndex, size_type frameIndex)
{
// Uhoh
@ -142,6 +235,13 @@ public:
return *(buffers[channelIndex]->data() + frameIndex);
}
/**
* @brief Alias for getSample(...)
*
* @param channelIndex
* @param frameIndex
* @return Type&
*/
Type& operator()(int channelIndex, size_type frameIndex)
{
return getSample(channelIndex, frameIndex);

59
sfizz/MathHelpers.h
View file

@ -21,6 +21,13 @@
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
/**
* @file MathHelpers.h
* @author Paul Ferrand (paul@ferrand.cc)
* @brief Contains math helper functions and math constants
* @version 0.1
* @date 2019-11-23
*/
#pragma once
#include <algorithm>
#include <cmath>
@ -34,43 +41,91 @@ inline constexpr T min(T op1, T op2, T op3) { return std::min(op1, std::min(op2,
template <class T>
inline constexpr T min(T op1, T op2, T op3, T op4) { return std::min(op1, std::min(op2, std::min(op3, op4))); }
/**
* @brief Converts db values into power (applies 10**(in/10))
*
* @tparam Type
* @param in
* @return Type
*/
template <class Type>
inline constexpr Type db2pow(Type in)
{
return std::pow(static_cast<Type>(10.0), in * static_cast<Type>(0.1));
}
/**
* @brief Converts power values into dB (applies 10log10(in))
*
* @tparam Type
* @param in
* @return Type
*/
template <class Type>
inline constexpr Type pow2db(Type in)
{
return static_cast<Type>(10.0) * std::log10(in);
}
/**
* @brief Converts dB values to magnitude (applies 10**(in/20))
*
* @tparam Type
* @param in
* @return constexpr Type
*/
template <class Type>
inline constexpr Type db2mag(Type in)
{
return std::pow(static_cast<Type>(10.0), in * static_cast<Type>(0.05));
}
/**
* @brief Converts magnitude values into dB (applies 20log10(in))
*
* @tparam Type
* @param in
* @return Type
*/
template <class Type>
inline constexpr Type mag2db(Type in)
{
return static_cast<Type>(20.0) * std::log10(in);
}
/**
* @brief Global random singletons
*
* TODO: could be moved into a singleton class holder
*
*/
namespace Random {
static std::random_device randomDevice;
static std::mt19937 randomGenerator { randomDevice() };
} // namespace Random
/**
* @brief Converts a midi note to a frequency value
*
* @param noteNumber
* @return float
*/
inline float midiNoteFrequency(const int noteNumber)
{
return 440.0f * std::pow(2.0f, (noteNumber - 69) / 12.0f);
}
/**
* @brief Clamps a value between bounds, including the bounds!
*
* @tparam T
* @param v
* @param lo
* @param hi
* @return T
*/
template<class T>
constexpr const T& clamp( const T& v, const T& lo, const T& hi )
constexpr T clamp( const T& v, const T& lo, const T& hi )
{
assert( !(hi < lo) );
return (v < lo) ? lo : (hi < v) ? hi : v;

1
sfizz/Range.h
View file

@ -26,7 +26,6 @@
#include <initializer_list>
#include <type_traits>
namespace sfz
{

120
sfizz/SIMDHelpers.h
View file

@ -21,6 +21,39 @@
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
/**
* @file SIMDHelpers.h
* @author Paul Ferrand (paul@ferrand.cc)
* @brief This file contains useful functions to treat buffers of numerical values
* (e.g. a buffer of floats usually).
*
* These functions are templated to apply on
* various underlying buffer types, and this file contains the generic version of the
* function. Some templates specializations exists for different architecture that try
* to make use of SIMD intrinsics; you can find such a file in SIMDSSE.cpp and possibly
* someday SIMDNEON.cpp for ARM platforms.
*
* If you want to write specializations for float buffers the idea is to start from the SIMDDummy
* file that just calls back the generic implementation, and implement the specializations you
* wish from this list. You can then either activate or deactivate a SIMD version by default
* using the variables in Config.h, or call e.g. writeInterleaved<float, true>(...) to use the
* SIMD version of writeInterleaved. To implement e.g. double template specializations you
* will need to amend this file to pre-declare the specializations, and create a file similar to
* SIMDxxx.cpp.
*
* All the SIMD functions are benchmarked. If you run the benchmark for a given function you can check
* if it is interesting to run the SIMD version by default. The interest is that you can activate
* and deactivate each SIMD specialization with a fine granularity, since SIMD performance
* will be very dependent on the processor architecture. Modern processors can also organize their
* instructions so that scalar non-SIMD code runs sometimes much more efficiently than SIMD code
* especially when the latter does not operate on misaligned buffers.
*
* @version 0.1
* @date 2019-11-23
*
* @copyright Copyright (c) 2019
*
*/
#pragma once
#include "Config.h"
#include "Debug.h"
@ -39,6 +72,17 @@ namespace _internals {
}
}
/**
* @brief Read interleaved stereo data from a buffer and separate it in a left/right pair of buffers.
*
* The output size will be the minimum of the input span and output spans size.
*
* @tparam T the underlying type
* @tparam SIMD use the SIMD version or the scalar version
* @param input
* @param outputLeft
* @param outputRight
*/
template <class T, bool SIMD = SIMDConfig::readInterleaved>
void readInterleaved(absl::Span<const T> input, absl::Span<T> outputLeft, absl::Span<T> outputRight) noexcept
{
@ -62,6 +106,17 @@ namespace _internals {
}
}
/**
* @brief Write a pair of left and right stereo input into a single buffer interleaved.
*
* The output size will be the minimum of the input spans and output span size.
*
* @tparam T the underlying type
* @tparam SIMD use the SIMD version or the scalar version
* @param inputLeft
* @param inputRight
* @param output
*/
template <class T, bool SIMD = SIMDConfig::writeInterleaved>
void writeInterleaved(absl::Span<const T> inputLeft, absl::Span<const T> inputRight, absl::Span<T> output) noexcept
{
@ -81,6 +136,14 @@ void writeInterleaved<float, true>(absl::Span<const float> inputLeft, absl::Span
template <>
void readInterleaved<float, true>(absl::Span<const float> input, absl::Span<float> outputLeft, absl::Span<float> outputRight) noexcept;
/**
* @brief Fill a buffer with a value; comparable to std::fill in essence.
*
* @tparam T the underlying type
* @tparam SIMD use the SIMD version or the scalar version
* @param output
* @param value
*/
template <class T, bool SIMD = SIMDConfig::fill>
void fill(absl::Span<T> output, T value) noexcept
{
@ -90,6 +153,14 @@ void fill(absl::Span<T> output, T value) noexcept
template <>
void fill<float, true>(absl::Span<float> output, float value) noexcept;
/**
* @brief Exp math function
*
* @tparam T the underlying type
* @tparam SIMD use the SIMD version or the scalar version
* @param input
* @param output
*/
template <class Type, bool SIMD = SIMDConfig::mathfuns>
void exp(absl::Span<const Type> input, absl::Span<Type> output) noexcept
{
@ -102,6 +173,16 @@ void exp(absl::Span<const Type> input, absl::Span<Type> output) noexcept
template <>
void exp<float, true>(absl::Span<const float> input, absl::Span<float> output) noexcept;
/**
* @brief Log math function
*
* The output size will be the minimum of the input span and output span size.
*
* @tparam T the underlying type
* @tparam SIMD use the SIMD version or the scalar version
* @param input
* @param output
*/
template <class Type, bool SIMD = SIMDConfig::mathfuns>
void log(absl::Span<const Type> input, absl::Span<Type> output) noexcept
{
@ -114,6 +195,16 @@ void log(absl::Span<const Type> input, absl::Span<Type> output) noexcept
template <>
void log<float, true>(absl::Span<const float> input, absl::Span<float> output) noexcept;
/**
* @brief sin math function
*
* The output size will be the minimum of the input span and output span size.
*
* @tparam T the underlying type
* @tparam SIMD use the SIMD version or the scalar version
* @param input
* @param output
*/
template <class Type, bool SIMD = SIMDConfig::mathfuns>
void sin(absl::Span<const Type> input, absl::Span<Type> output) noexcept
{
@ -126,6 +217,16 @@ void sin(absl::Span<const Type> input, absl::Span<Type> output) noexcept
template <>
void sin<float, true>(absl::Span<const float> input, absl::Span<float> output) noexcept;
/**
* @brief cos math function
*
* The output size will be the minimum of the input span and output span size.
*
* @tparam T the underlying type
* @tparam SIMD use the SIMD version or the scalar version
* @param input
* @param output
*/
template <class Type, bool SIMD = SIMDConfig::mathfuns>
void cos(absl::Span<const Type> input, absl::Span<Type> output) noexcept
{
@ -160,6 +261,25 @@ namespace _internals {
}
}
/**
* @brief Computes an integer index and 2 float coefficients corresponding to the
* linear interpolation procedure. This version will saturate the index to the upper
* bound if the upper bound is reached.
*
* The indices are computed starting from the given floatIndex, and each increment
* is given by the elements of jumps.
* The output size will be the minimum of the inputs span and outputs span size.
*
* @tparam T the underlying type
* @tparam SIMD use the SIMD version or the scalar version
* @param jumps the floating point increments to the index
* @param leftCoeffs the linear interpolation coefficients for the left value
* @param rightCoeffs the linear interpolation coefficients for the right value
* @param indices the integer sample indices for the left values; the right values for interpolation at index i are (indices[i] + 1) and not indices[i+1]
* @param floatIndex the starting floating point index
* @param loopEnd the end of the "loop" which is not really a loop because it saturate.
* @return float
*/
template <class T, bool SIMD = SIMDConfig::saturatingSFZIndex>
float saturatingSFZIndex(absl::Span<const T> jumps, absl::Span<T> leftCoeffs, absl::Span<T> rightCoeffs, absl::Span<int> indices, T floatIndex, T loopEnd) noexcept
{

4
sfizz/ScopedFTZ.h
View file

@ -21,6 +21,10 @@
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
/**
* @brief Flush floating points to zero and disable denormals as an RAII helper.
*
*/
class ScopedFTZ {
public:

43
sfizz/SfzHelpers.h
View file

@ -35,12 +35,27 @@ using CCValueArray = std::array<uint8_t, 128>;
using CCValuePair = std::pair<uint8_t, float> ;
using CCNamePair = std::pair<uint8_t, std::string>;
/**
* @brief Converts cents to a pitch ratio
*
* @tparam T
* @param cents
* @param centsPerOctave
* @return constexpr float
*/
template<class T>
inline constexpr float centsFactor(T cents, T centsPerOctave = 1200)
{
return std::pow(2.0f, static_cast<float>(cents) / centsPerOctave);
}
/**
* @brief Normalize a CC value between (T)0.0 and (T)1.0
*
* @tparam T
* @param ccValue
* @return constexpr float
*/
template<class T>
inline constexpr float normalizeCC(T ccValue)
{
@ -48,18 +63,40 @@ inline constexpr float normalizeCC(T ccValue)
return static_cast<float>(std::min(std::max(ccValue, static_cast<T>(0)), static_cast<T>(127))) / 127.0f;
}
/**
* @brief Normalize a percentage between 0 and 1
*
* @tparam T
* @param percentValue
* @return constexpr float
*/
template<class T>
inline constexpr float normalizePercents(T percentValue)
{
return std::min(std::max(static_cast<float>(percentValue), 0.0f), 100.0f) / 100.0f;
}
/**
* @brief Normalize a possibly negative percentage between -1 and 1
*
* @tparam T
* @param percentValue
* @return constexpr float
*/
template<class T>
inline constexpr float normalizeNegativePercents(T percentValue)
{
return std::min(std::max(static_cast<float>(percentValue), -100.0f), 100.0f) / 100.0f;
}
/**
* @brief If a cc switch exists for the value, returns the value with the CC modifier, otherwise returns the value alone.
*
* @param ccValues
* @param ccSwitch
* @param value
* @return float
*/
inline float ccSwitchedValue(const CCValueArray& ccValues, const absl::optional<CCValuePair>& ccSwitch, float value) noexcept
{
if (ccSwitch)
@ -68,6 +105,12 @@ inline float ccSwitchedValue(const CCValueArray& ccValues, const absl::optional<
return value;
}
/**
* @brief Convert a note in string to its equivalent midi note number
*
* @param value
* @return absl::optional<uint8_t>
*/
absl::optional<uint8_t> readNoteValue(const absl::string_view& value);
} // namespace sfz

40
sfizz/StringViewHelpers.h
View file

@ -21,9 +21,25 @@
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
/**
* @file StringViewHelpers.h
* @author Paul Ferrand (paul@ferrand.cc)
* @brief Contains some helper functions for string views
* @version 0.1
* @date 2019-11-23
*
* @copyright Copyright (c) 2019
*
*/
#pragma once
#include "absl/strings/string_view.h"
/**
* @brief Removes the whitespace on a string_view in place
*
* @param s
*/
inline void trimInPlace(absl::string_view& s)
{
const auto leftPosition = s.find_first_not_of(" \r\t\n\f\v");
@ -36,22 +52,30 @@ inline void trimInPlace(absl::string_view& s)
}
}
/**
* @brief Removes the whitespace on a string_view and return a new string_view
*
* @param s
* @return absl::string_view
*/
inline absl::string_view trim(absl::string_view s)
{
const auto leftPosition = s.find_first_not_of(" \r\t\n\f\v");
if (leftPosition != s.npos) {
s.remove_prefix(leftPosition);
const auto rightPosition = s.find_last_not_of(" \r\t\n\f\v");
s.remove_suffix(s.size() - rightPosition - 1);
} else {
s.remove_suffix(s.size());
}
trimInPlace(s);
return s;
}
constexpr uint64_t Fnv1aBasis = 0x811C9DC5;
constexpr uint64_t Fnv1aPrime = 0x01000193;
/**
* @brief Compile-time hashing function to be used mostly with switch/case statements.
*
* See e.g. the Region.cpp file
*
* @param s the input string to be hashed
* @param h the hashing seed to use
* @return uint64_t
*/
inline constexpr uint64_t hash(absl::string_view s, uint64_t h = Fnv1aBasis)
{
if (s.length() > 0)

13
sfizz/Synth.cpp
View file

@ -320,6 +320,7 @@ void sfz::Synth::garbageCollect() noexcept
void sfz::Synth::setSamplesPerBlock(int samplesPerBlock) noexcept
{
AtomicDisabler callbackDisabler { canEnterCallback };
while (inCallback) {
std::this_thread::sleep_for(1ms);
}
@ -347,11 +348,10 @@ void sfz::Synth::renderBlock(AudioSpan<float> buffer) noexcept
ScopedFTZ ftz;
buffer.fill(0.0f);
AtomicGuard callbackGuard { inCallback };
if (!canEnterCallback)
return;
AtomicGuard callbackGuard { inCallback };
auto tempSpan = AudioSpan<float>(tempBuffer).first(buffer.getNumFrames());
for (auto& voice : voices) {
voice->renderBlock(tempSpan);
@ -369,11 +369,10 @@ void sfz::Synth::noteOn(int delay, int channel, int noteNumber, uint8_t velocity
midiState.noteOn(noteNumber, velocity);
AtomicGuard callbackGuard { inCallback };
if (!canEnterCallback)
return;
AtomicGuard callbackGuard { inCallback };
auto randValue = randNoteDistribution(Random::randomGenerator);
for (auto& region : noteActivationLists[noteNumber]) {
@ -402,11 +401,10 @@ void sfz::Synth::noteOff(int delay, int channel, int noteNumber, uint8_t velocit
ASSERT(noteNumber >= 0);
// DBG("Received note " << noteNumber << "/" << +velocity << " OFF at time " << delay);
AtomicGuard callbackGuard { inCallback };
if (!canEnterCallback)
return;
AtomicGuard callbackGuard { inCallback };
// FIXME: Some keyboards (e.g. Casio PX5S) can send a real note-off velocity. In this case, do we have a
// way in sfz to specify that a release trigger should NOT use the note-on velocity?
// auto replacedVelocity = (velocity == 0 ? sfz::getNoteVelocity(noteNumber) : velocity);
@ -435,11 +433,10 @@ void sfz::Synth::cc(int delay, int channel, int ccNumber, uint8_t ccValue) noexc
ASSERT(ccNumber < 128);
ASSERT(ccNumber >= 0);
AtomicGuard callbackGuard { inCallback };
if (!canEnterCallback)
return;
AtomicGuard callbackGuard { inCallback };
for (auto& voice : voices)
voice->registerCC(delay, channel, ccNumber, ccValue);

266
sfizz/Synth.h
View file

@ -36,38 +36,250 @@
#include <vector>
namespace sfz {
/**
* @brief This class is the core of the sfizz library. In C++ it is the main point
* of entry and in C the interface basically maps the functions of the class into
* C bindings.
*
* The JACK client provides an example of how you can use this class as an entry
* point for your own projects. Just include this header and compile against the
* static library. If you wish to use the shared library you should rather use the
* C bindings.
*
* This class derives from the Parser and provides a specific set of callbacks; see
* the Parser documentation for more precisions.
*
* The Synth object contains:
* - A set of SFZ Regions that get filled up upon parsing
* - A set of Voices that play the sounds of the regions when triggered.
* - Some singleton resources, particularly the midiState which contains the current
* midi status (note is on or off, last note velocity, current CC values, ...)
* as well as a FilePool that preloads and give access to files.
*
* The synth is callback based, in the sense that it renders audio block by block
* using the renderBlock() function. Between each call to renderBlock() you have to
* send the relevent events for the block in the form of MIDI events: noteOn(),
* noteOff(), cc(). You can also send pitchBend(), aftertouch() and bpm()
* events -- but as of 2019 they are not handled.
*
* All events have a delay information, which must be less than the size of the
* next call to renderBlock() in units of frames or samples. For example, if you
* will call to render a block of 256 samples, all the events you send to the
* synth should have a delay parameter strictly lower than 256. Events beyond 256
* may be completely ignored by the synth as the incoming event buffer is cleared
* during the renderBlock() call.
*
* The jack_client.cpp file contains examples of the most classical usage of the
* synth and can be used as a reference.
*/
class Synth : public Parser {
public:
/**
* @brief Construct a new Synth object with no voices. If you want sound
* you will need to call setNumVoices() before playing.
*
*/
Synth();
/**
* @brief Construct a new Synth object with a specified number of voices.
*
* @param numVoices
*/
Synth(int numVoices);
/**
* @brief Empties the current regions and load a new SFZ file into the synth.
*
* 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.
*
* @param file
* @return true
* @return false if the file was not found or no regions were loaded.
*/
bool loadSfzFile(const fs::path& file) final;
/**
* @brief Get the current number of regions loaded
*
* @return int
*/
int getNumRegions() const noexcept;
/**
* @brief Get the current number of groups loaded
*
* @return int
*/
int getNumGroups() const noexcept;
/**
* @brief Get the current number of masters loaded
*
* @return int
*/
int getNumMasters() const noexcept;
/**
* @brief Get the current number of curves loaded
*
* @return int
*/
int getNumCurves() const noexcept;
/**
* @brief Get a raw view into a specific region. This is mostly used
* for testing.
*
* @param idx
* @return const Region*
*/
const Region* getRegionView(int idx) const noexcept;
/**
* @brief Get a list of unknown opcodes. The lifetime of the
* string views in the code are linked to the currently loaded
* sfz file.
*
* TODO: change this to strings we don't really care about performance
* here and this hurts the C interface.
*
* @return std::set<absl::string_view>
*/
std::set<absl::string_view> getUnknownOpcodes() const noexcept;
/**
* @brief Get the number of preloaded samples in the synth
*
* @return size_t
*/
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
*/
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
*/
void setSampleRate(float sampleRate) noexcept;
/**
* @brief Get the current value for the volume, in dB.
*
* @return float
*/
float getVolume() const noexcept;
/**
* @brief Set the value for the volume. This value will be
* clamped within sfz::default::volumeRange.
*
* @param volume
*/
void setVolume(float volume) noexcept;
void renderBlock(AudioSpan<float> buffer) noexcept;
/**
* @brief Send a note on 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 channel the midi channel for the event
* @param noteNumber the midi note number
* @param velocity the midi note velocity
*/
void noteOn(int delay, int channel, 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 channel the midi channel for the event
* @param noteNumber the midi note number
* @param velocity the midi note velocity
*/
void noteOff(int delay, int channel, 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 channel the midi channel for the event
* @param ccNumber the cc number
* @param ccValue the cc value
*/
void cc(int delay, int channel, 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 channel the midi channel for the event
* @param pitch the pitch value
*/
void pitchWheel(int delay, int channel, int pitch) noexcept;
/**
* @brief Send a aftertouch 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 channel the midi channel for the event
* @param aftertouch the aftertouch value
*/
void aftertouch(int delay, int channel, uint8_t aftertouch) noexcept;
/**
* @brief Send a tempo 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 channel the midi channel for the event
* @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 size of the block is integrated
* in the AudioSpan object. You can build an AudioSpan implicitely from a large number
* of source objects; check the AudioSpan reference for more precision.
*
* @param buffer the buffer to write the next block into; this should be a stereo buffer.
*/
void renderBlock(AudioSpan<float> buffer) noexcept;
/**
* @brief Get the number of active voices
*
* @return int
*/
int getNumActiveVoices() const noexcept;
/**
* @brief Get the total number of voices in the synth (the polyphony)
*
* @return int
*/
int getNumVoices() const noexcept;
/**
* @brief Change the number of voices (the polyphony)
*
* @param numVoices
*/
void setNumVoices(int numVoices) noexcept;
/**
* @brief Trigger a garbage collection, which removes the samples that are
* loaded by the FilePool after being requested by the voices. This does
* not concern the preloaded samples, only the samples loaded to be played
* fully. This function is run regularly in a background thread so normally
* you should not need to call it explicitely.
*
*/
void garbageCollect() noexcept;
protected:
/**
* @brief The parser callback; this is called by the parent object each time
* a new region, group, master, global, curve or control set of opcodes
* appears in the parser
*
* @param header the header for the set of opcodes
* @param members the opcode members
*/
void callback(absl::string_view header, const std::vector<Opcode>& members) final;
private:
@ -76,43 +288,89 @@ private:
int numGroups { 0 };
int numMasters { 0 };
int numCurves { 0 };
/**
* @brief Remove all regions, resets all voices and clears everything
* to bring back the synth in its original state.
*
*/
void clear();
/**
* @brief Resets and possibly changes the number of voices (polyphony) in
* the synth.
*
* @param numVoices
*/
void resetVoices(int numVoices);
/**
* @brief Helper function to dispatch <global> opcodes
*
* @param members the opcodes of the <global> block
*/
void handleGlobalOpcodes(const std::vector<Opcode>& members);
/**
* @brief Helper function to dispatch <control> opcodes
*
* @param members the opcodes of the <control> block
*/
void handleControlOpcodes(const std::vector<Opcode>& members);
/**
* @brief Helper function to merge all the currently active opcodes
* as set by the successive callbacks and create a new region to store
* in the synth.
*
* @param regionOpcodes the opcodes that are specific to the region
*/
void buildRegion(const std::vector<Opcode>& regionOpcodes);
// Opcode memory; these are used to build regions, as a new region
// will integrate opcodes from the group, master and global block
std::vector<Opcode> globalOpcodes;
std::vector<Opcode> masterOpcodes;
std::vector<Opcode> groupOpcodes;
// Singletons passed as references to the voices
// TODO: these should probably go in a global singleton holder along with a buffer distribution and LFO/EG stuff...
FilePool filePool;
MidiState midiState;
/**
* @brief Find a voice that is not currently playing
*
* @return Voice*
*/
Voice* findFreeVoice() noexcept;
// Names for the cc as set by the cc_label or cc_name opcodes
std::vector<CCNamePair> ccNames;
// Default active switch if multiple keyswitchable regions are present
absl::optional<uint8_t> defaultSwitch;
std::set<absl::string_view> unknownOpcodes;
using RegionPtrVector = std::vector<Region*>;
using VoicePtrVector = std::vector<Voice*>;
std::vector<std::unique_ptr<Region>> regions;
std::vector<std::unique_ptr<Voice>> voices;
// Views to speed up iteration over the regions and voices when events
// occur in the audio callback
VoicePtrVector voiceViewArray;
std::array<RegionPtrVector, 128> noteActivationLists;
std::array<RegionPtrVector, 128> ccActivationLists;
// Internal temporary buffer
AudioBuffer<float> tempBuffer { 2, config::defaultSamplesPerBlock };
int samplesPerBlock { config::defaultSamplesPerBlock };
float sampleRate { config::defaultSampleRate };
float volume { Default::volume };
int numVoices { config::numVoices };
// Distribution used to generate random value for the *rand opcodes
std::uniform_real_distribution<float> randNoteDistribution { 0, 1 };
unsigned fileTicket { 1 };
// Atomic guards; must be used with AtomicGuard and AtomicDisabler
std::atomic<bool> canEnterCallback { true };
std::atomic<bool> inCallback { false };
int numVoices { config::numVoices };
LEAK_DETECTOR(Synth);
};