finalized bw_balance + examples

examples/fx_balance/src/bw_example_fx_balance.c

@@ -33,8 +33,8 @@ void bw_example_fx_balance_set_sample_rate(bw_example_fx_balance *instance, floa
 void bw_example_fx_balance_reset(bw_example_fx_balance *instance) {
 	bw_balance_reset_coeffs(&instance->balance_coeffs);
 	bw_ppm_reset_coeffs(&instance->ppm_coeffs);
-	bw_ppm_reset_state(&instance->ppm_coeffs, &instance->ppm_l_state);
+	bw_ppm_reset_state(&instance->ppm_coeffs, &instance->ppm_l_state, 0.f);
-	bw_ppm_reset_state(&instance->ppm_coeffs, &instance->ppm_r_state);
+	bw_ppm_reset_state(&instance->ppm_coeffs, &instance->ppm_r_state, 0.f);
 }
 
 void bw_example_fx_balance_process(bw_example_fx_balance *instance, const float** x, float** y, int n_samples) {

examples/fx_balance/vst3/Makefile

@@ -4,3 +4,6 @@ NAME := bw_example_fx_balance
 SOURCES = ${SOURCES_COMMON} ${ROOT_DIR}/../src/bw_example_fx_balance.c
 
 include ${ROOT_DIR}/../../common/vst3/vst3.mk
+
+CXXFLAGS += -DRELEASE=1 -DNDEBUG -DBW_NO_DEBUG
+#CXXFLAGS += -DDEVELOPMENT=1 -DBW_DEBUG_DEEP

examples/fxpp_balance/vst3/Makefile

@@ -4,3 +4,6 @@ NAME := bw_example_fxpp_balance
 SOURCES = ${SOURCES_COMMON} ${ROOT_DIR}/../src/bw_example_fxpp_balance.cpp
 
 include ${ROOT_DIR}/../../common/vst3/vst3.mk
+
+CXXFLAGS += -DRELEASE=1 -DNDEBUG -DBW_NO_DEBUG
+#CXXFLAGS += -DDEVELOPMENT=1 -DBW_DEBUG_DEEP

include/bw_balance.h

@@ -38,6 +38,8 @@
  *          <li>Added overloaded C++ <code>process()</code> function taking
  *              C-style arrays as arguments.</li>
  *          <li>Removed usage of reserved identifiers.</li>
+ *          <li>Clearly specified parameter validity ranges.</li>
+ *          <li>Added debugging code.</li>
  *        </ul>
  *      </li>
  *      <li>Version <strong>0.6.0</strong>:
@@ -81,37 +83,48 @@ typedef struct bw_balance_coeffs bw_balance_coeffs;
  *
  *    #### bw_balance_init()
  *  ```>>> */
-static inline void bw_balance_init(bw_balance_coeffs *BW_RESTRICT coeffs);
+static inline void bw_balance_init(
+	bw_balance_coeffs * BW_RESTRICT coeffs);
 /*! <<<```
  *    Initializes input parameter values in `coeffs`.
  *
  *    #### bw_balance_set_sample_rate()
  *  ```>>> */
-static inline void bw_balance_set_sample_rate(bw_balance_coeffs *BW_RESTRICT coeffs, float sample_rate);
+static inline void bw_balance_set_sample_rate(
+	bw_balance_coeffs * BW_RESTRICT coeffs,
+	float                           sample_rate);
 /*! <<<```
  *    Sets the `sample_rate` (Hz) value in `coeffs`.
  *
  *    #### bw_balance_reset_coeffs()
  *  ```>>> */
-static inline void bw_balance_reset_coeffs(bw_balance_coeffs *BW_RESTRICT coeffs);
+static inline void bw_balance_reset_coeffs(
+	bw_balance_coeffs * BW_RESTRICT coeffs);
 /*! <<<```
  *    Resets coefficients in `coeffs` to assume their target values.
  *
  *    #### bw_balance_update_coeffs_ctrl()
  *  ```>>> */
-static inline void bw_balance_update_coeffs_ctrl(bw_balance_coeffs *BW_RESTRICT coeffs);
+static inline void bw_balance_update_coeffs_ctrl(
+	bw_balance_coeffs * BW_RESTRICT coeffs);
 /*! <<<```
  *    Triggers control-rate update of coefficients in `coeffs`.
  *
  *    #### bw_balance_update_coeffs_audio()
  *  ```>>> */
-static inline void bw_balance_update_coeffs_audio(bw_balance_coeffs *BW_RESTRICT coeffs);
+static inline void bw_balance_update_coeffs_audio(
+	bw_balance_coeffs * BW_RESTRICT coeffs);
 /*! <<<```
  *    Triggers audio-rate update of coefficients in `coeffs`.
  *
  *    #### bw_balance_process1()
  *  ```>>> */
-static inline void bw_balance_process1(const bw_balance_coeffs *BW_RESTRICT coeffs, float x_l, float x_r, float *BW_RESTRICT y_l, float *BW_RESTRICT y_r);
+static inline void bw_balance_process1(
+	const bw_balance_coeffs * BW_RESTRICT coeffs,
+	float                                 x_l,
+	float                                 x_r,
+	float * BW_RESTRICT                   y_l,
+	float * BW_RESTRICT                   y_r);
 /*! <<<```
  *    Processes one set of input samples `x_l` (left) and `x_r` (right) using
  *    `coeffs`. The left and right output samples are put into `y_l` (left) and
@@ -119,7 +132,13 @@ static inline void bw_balance_process1(const bw_balance_coeffs *BW_RESTRICT coef
  *
  *    #### bw_balance_process()
  *  ```>>> */
-static inline void bw_balance_process(bw_balance_coeffs *BW_RESTRICT coeffs, const float *x_l, const float *x_r, float *y_l, float *y_r, size_t n_samples);
+static inline void bw_balance_process(
+	bw_balance_coeffs * BW_RESTRICT coeffs,
+	const float *                   x_l,
+	const float *                   x_r,
+	float *                         y_l,
+	float *                         y_r,
+	size_t                          n_samples);
 /*! <<<```
  *    Processes the first `n_samples` of the input buffers `x_l` (left) and
  *    `x_r` (right) and fills the first `n_samples` of the output buffers `y_l`
@@ -128,7 +147,14 @@ static inline void bw_balance_process(bw_balance_coeffs *BW_RESTRICT coeffs, con
  *
  *    #### bw_balance_process_multi()
  *  ```>>> */
-static inline void bw_balance_process_multi(bw_balance_coeffs *BW_RESTRICT coeffs, const float * const *x_l, const float * const *x_r, float * const *y_l, float * const *y_r, size_t n_channels, size_t n_samples);
+static inline void bw_balance_process_multi(
+	bw_balance_coeffs * BW_RESTRICT coeffs,
+	const float * const *           x_l,
+	const float * const *           x_r,
+	float * const *                 y_l,
+	float * const *                 y_r,
+	size_t                          n_channels,
+	size_t                          n_samples);
 /*! <<<```
  *    Processes the first `n_samples` of the `n_channels` input buffers `x_l`
  *    (left) and `x_r` (right) and fills the first `n_samples` of the
@@ -137,12 +163,28 @@ static inline void bw_balance_process_multi(bw_balance_coeffs *BW_RESTRICT coeff
  *
  *    #### bw_balance_set_balance()
  *  ```>>> */
-static inline void bw_balance_set_balance(bw_balance_coeffs *BW_RESTRICT coeffs, float value);
+static inline void bw_balance_set_balance(
+	bw_balance_coeffs * BW_RESTRICT coeffs,
+	float                           value);
 /*! <<<```
  *    Sets the balance `value`, where `-1.f` corresponds to hard left balance,
  *    `0.f` to center balance, and `1.f` to hard right balance.
  *
+ *    Valid range: [`-1.f` (hard left balance), `1.f` (hard right balance)].
+ *
  *    Default value: `0.f`.
+ *
+ *    #### bw_balance_coeffs_is_valid()
+ *  ```>>> */
+static inline char bw_balance_coeffs_is_valid(
+	const bw_balance_coeffs * BW_RESTRICT coeffs);
+/*! <<<```
+ *    Tries to determine whether `coeffs` is valid and returns non-`0` if it
+ *    seems to be the case and `0` if it is certainly not. False positives are
+ *    possible, false negatives are not.
+ *
+ *    `coeffs` must at least point to a readable memory block of size greater
+ *    than or equal to that of `bw_balance_coeffs`.
  *  }}} */
 
 #ifdef __cplusplus
@@ -161,7 +203,21 @@ static inline void bw_balance_set_balance(bw_balance_coeffs *BW_RESTRICT coeffs,
 extern "C" {
 #endif
 
+#ifdef BW_DEBUG_DEEP
+enum bw_balance_coeffs_state {
+	bw_balance_coeffs_state_invalid,
+	bw_balance_coeffs_state_init,
+	bw_balance_coeffs_state_set_sample_rate,
+	bw_balance_coeffs_state_reset_coeffs
+};
+#endif
+
 struct bw_balance_coeffs {
+#ifdef BW_DEBUG_DEEP
+	uint32_t			hash;
+	enum bw_balance_coeffs_state	state;
+#endif
+
 	// Sub-components
 	bw_gain_coeffs			l_coeffs;
 	bw_gain_coeffs			r_coeffs;
@@ -171,18 +227,43 @@ struct bw_balance_coeffs {
 	float				balance_prev;
 };
 
-static inline void bw_balance_init(bw_balance_coeffs *BW_RESTRICT coeffs) {
+static inline void bw_balance_init(
+		bw_balance_coeffs * BW_RESTRICT coeffs) {
+	BW_ASSERT(coeffs != NULL);
+
 	bw_gain_init(&coeffs->l_coeffs);
 	bw_gain_init(&coeffs->r_coeffs);
 	coeffs->balance = 0.f;
+
+#ifdef BW_DEBUG_DEEP
+	coeffs->hash = bw_hash_sdbm("bw_balance_coeffs");
+	coeffs->state = bw_balance_coeffs_state_init;
+#endif
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state == bw_balance_coeffs_state_init);
 }
 
-static inline void bw_balance_set_sample_rate(bw_balance_coeffs *BW_RESTRICT coeffs, float sample_rate) {
+static inline void bw_balance_set_sample_rate(
+		bw_balance_coeffs * BW_RESTRICT coeffs,
+		float                           sample_rate) {
+	BW_ASSERT(coeffs != NULL);
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state >= bw_balance_coeffs_state_init);
+	BW_ASSERT(bw_is_finite(sample_rate) && sample_rate > 0.f);
+
 	bw_gain_set_sample_rate(&coeffs->l_coeffs, sample_rate);
 	bw_gain_set_sample_rate(&coeffs->r_coeffs, sample_rate);
+
+#ifdef BW_DEBUG_DEEP
+	coeffs->state = bw_balance_coeffs_state_set_sample_rate;
+#endif
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state == bw_balance_coeffs_state_set_sample_rate);
 }
 
-static inline void bw_balance_do_update_coeffs(bw_balance_coeffs *BW_RESTRICT coeffs, char force) {
+static inline void bw_balance_do_update_coeffs(
+		bw_balance_coeffs * BW_RESTRICT coeffs,
+		char                            force) {
 	if (force || coeffs->balance != coeffs->balance_prev) {
 		bw_gain_set_gain_lin(&coeffs->l_coeffs, bw_minf(1.f - coeffs->balance, 1.f));
 		bw_gain_set_gain_lin(&coeffs->r_coeffs, bw_minf(1.f + coeffs->balance, 1.f));
@@ -190,47 +271,164 @@ static inline void bw_balance_do_update_coeffs(bw_balance_coeffs *BW_RESTRICT co
 	}
 }
 
-static inline void bw_balance_reset_coeffs(bw_balance_coeffs *BW_RESTRICT coeffs) {
+static inline void bw_balance_reset_coeffs(
+		bw_balance_coeffs * BW_RESTRICT coeffs) {
+	BW_ASSERT(coeffs != NULL);
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state >= bw_balance_coeffs_state_set_sample_rate);
+
 	bw_balance_do_update_coeffs(coeffs, 1);
 	bw_gain_reset_coeffs(&coeffs->l_coeffs);
 	bw_gain_reset_coeffs(&coeffs->r_coeffs);
+
+#ifdef BW_DEBUG_DEEP
+	coeffs->state = bw_balance_coeffs_state_reset_coeffs;
+#endif
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state == bw_balance_coeffs_state_reset_coeffs);
 }
 
-static inline void bw_balance_update_coeffs_ctrl(bw_balance_coeffs *BW_RESTRICT coeffs) {
+static inline void bw_balance_update_coeffs_ctrl(
+		bw_balance_coeffs * BW_RESTRICT coeffs) {
+	BW_ASSERT(coeffs != NULL);
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state >= bw_balance_coeffs_state_reset_coeffs);
+
 	bw_balance_do_update_coeffs(coeffs, 0);
 	bw_gain_update_coeffs_ctrl(&coeffs->l_coeffs);
 	bw_gain_update_coeffs_ctrl(&coeffs->r_coeffs);
+
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state >= bw_balance_coeffs_state_reset_coeffs);
 }
 
-static inline void bw_balance_update_coeffs_audio(bw_balance_coeffs *BW_RESTRICT coeffs) {
+static inline void bw_balance_update_coeffs_audio(
+		bw_balance_coeffs * BW_RESTRICT coeffs) {
+	BW_ASSERT(coeffs != NULL);
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state >= bw_balance_coeffs_state_reset_coeffs);
+
 	bw_gain_update_coeffs_audio(&coeffs->l_coeffs);
 	bw_gain_update_coeffs_audio(&coeffs->r_coeffs);
+
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state >= bw_balance_coeffs_state_reset_coeffs);
 }
 
-static inline void bw_balance_process1(const bw_balance_coeffs *BW_RESTRICT coeffs, float x_l, float x_r, float *BW_RESTRICT y_l, float *BW_RESTRICT y_r) {
+static inline void bw_balance_process1(
+		const bw_balance_coeffs * BW_RESTRICT coeffs,
+		float                                 x_l,
+		float                                 x_r,
+		float * BW_RESTRICT                   y_l,
+		float * BW_RESTRICT                   y_r) {
+	BW_ASSERT(coeffs != NULL);
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state >= bw_balance_coeffs_state_reset_coeffs);
+	BW_ASSERT(bw_is_finite(x_l));
+	BW_ASSERT(bw_is_finite(x_r));
+
 	*y_l = bw_gain_process1(&coeffs->l_coeffs, x_l);
 	*y_r = bw_gain_process1(&coeffs->r_coeffs, x_r);
+
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state >= bw_balance_coeffs_state_reset_coeffs);
+	BW_ASSERT(bw_is_finite(*y_l));
+	BW_ASSERT(bw_is_finite(*y_r));
 }
 
-static inline void bw_balance_process(bw_balance_coeffs *BW_RESTRICT coeffs, const float *x_l, const float *x_r, float *y_l, float *y_r, size_t n_samples){
+static inline void bw_balance_process(
+		bw_balance_coeffs * BW_RESTRICT coeffs,
+		const float *                   x_l,
+		const float *                   x_r,
+		float *                         y_l,
+		float *                         y_r,
+		size_t                          n_samples){
+	BW_ASSERT(coeffs != NULL);
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state >= bw_balance_coeffs_state_reset_coeffs);
+	BW_ASSERT(x_l != NULL);
+	BW_ASSERT_DEEP(bw_has_only_finite(x_l, n_samples));
+	BW_ASSERT(x_r != NULL);
+	BW_ASSERT_DEEP(bw_has_only_finite(x_r, n_samples));
+	BW_ASSERT(y_l != NULL);
+	BW_ASSERT(y_r != NULL);
+
 	bw_balance_update_coeffs_ctrl(coeffs);
 	for (size_t i = 0; i < n_samples; i++) {
 		bw_balance_update_coeffs_audio(coeffs);
 		bw_balance_process1(coeffs, x_l[i], x_r[i], y_l + i, y_r + i);
 	}
+
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state >= bw_balance_coeffs_state_reset_coeffs);
+	BW_ASSERT_DEEP(bw_has_only_finite(y_l, n_samples));
+	BW_ASSERT_DEEP(bw_has_only_finite(y_r, n_samples));
 }
 
-static inline void bw_balance_process_multi(bw_balance_coeffs *BW_RESTRICT coeffs, const float * const *x_l, const float * const *x_r, float * const *y_l, float * const *y_r, size_t n_channels, size_t n_samples) {
+static inline void bw_balance_process_multi(
+		bw_balance_coeffs * BW_RESTRICT coeffs,
+		const float * const *           x_l,
+		const float * const *           x_r,
+		float * const *                 y_l,
+		float * const *                 y_r,
+		size_t                          n_channels,
+		size_t                          n_samples) {
+	BW_ASSERT(coeffs != NULL);
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state >= bw_balance_coeffs_state_reset_coeffs);
+	BW_ASSERT(x_l != NULL);
+	BW_ASSERT(x_r != NULL);
+	BW_ASSERT(y_l != NULL);
+	BW_ASSERT(y_r != NULL);
+
 	bw_balance_update_coeffs_ctrl(coeffs);
 	for (size_t i = 0; i < n_samples; i++) {
 		bw_balance_update_coeffs_audio(coeffs);
 		for (size_t j = 0; j < n_channels; j++)
 			bw_balance_process1(coeffs, x_l[j][i], x_r[j][i], y_l[j] + i, y_r[j] + i);
 	}
+
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state >= bw_balance_coeffs_state_reset_coeffs);
 }
 
-static inline void bw_balance_set_balance(bw_balance_coeffs *BW_RESTRICT coeffs, float value) {
+static inline void bw_balance_set_balance(
+		bw_balance_coeffs * BW_RESTRICT coeffs,
+		float                           value) {
+	BW_ASSERT(coeffs != NULL);
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state >= bw_balance_coeffs_state_init);
+	BW_ASSERT(bw_is_finite(value));
+	BW_ASSERT(value >= -1.f && value <= 1.f);
+
 	coeffs->balance = value;
+
+	BW_ASSERT_DEEP(bw_balance_coeffs_is_valid(coeffs));
+	BW_ASSERT_DEEP(coeffs->state >= bw_balance_coeffs_state_init);
+}
+
+static inline char bw_balance_coeffs_is_valid(
+		const bw_balance_coeffs * BW_RESTRICT coeffs) {
+	BW_ASSERT(coeffs != NULL);
+
+#ifdef BW_DEBUG_DEEP
+	if (coeffs->hash != bw_hash_sdbm("bw_balance_coeffs"))
+		return 0;
+	if (coeffs->state < bw_balance_coeffs_state_init || coeffs->state > bw_balance_coeffs_state_reset_coeffs)
+		return 0;
+#endif
+
+	if (!bw_is_finite(coeffs->balance) || coeffs->balance < -1.f || coeffs->balance > 1.f)
+		return 0;
+
+#ifdef BW_DEBUG_DEEP
+	if (coeffs->state >= bw_balance_coeffs_state_reset_coeffs) {
+		if (!bw_is_finite(coeffs->balance_prev) || coeffs->balance_prev < -1.f || coeffs->balance_prev > 1.f)
+			return 0;
+	}
+#endif
+
+	return bw_gain_coeffs_is_valid(&coeffs->l_coeffs) && bw_gain_coeffs_is_valid(&coeffs->r_coeffs);
 }
 
 #ifdef __cplusplus
@@ -250,22 +448,27 @@ class Balance {
 public:
 	Balance();
 
-	void setSampleRate(float sampleRate);
+	void setSampleRate(
+		float sampleRate);
+
 	void reset();
+
 	void process(
-		const float * const *x_l,
+		const float * const * xL,
-		const float * const *x_r,
+		const float * const * xR,
-		float * const *y_l,
+		float * const *       yL,
-		float * const *y_r,
+		float * const *       yR,
-		size_t nSamples);
-	void process(
-		const std::array<const float *, N_CHANNELS> x_l,
-		const std::array<const float *, N_CHANNELS> x_r,
-		const std::array<float *, N_CHANNELS> y_l,
-		const std::array<float *, N_CHANNELS> y_r,
 		size_t                nSamples);
 
-	void setBalance(float value);
+	void process(
+		std::array<const float *, N_CHANNELS> xL,
+		std::array<const float *, N_CHANNELS> xR,
+		std::array<float *, N_CHANNELS>       yL,
+		std::array<float *, N_CHANNELS>       yR,
+		size_t                                nSamples);
+
+	void setBalance(
+		float value);
 /*! <<<...
  *  }
  *  ```
@@ -286,7 +489,8 @@ inline Balance<N_CHANNELS>::Balance() {
 }
 
 template<size_t N_CHANNELS>
-inline void Balance<N_CHANNELS>::setSampleRate(float sampleRate) {
+inline void Balance<N_CHANNELS>::setSampleRate(
+		float sampleRate) {
 	bw_balance_set_sample_rate(&coeffs, sampleRate);
 }
 
@@ -297,26 +501,27 @@ inline void Balance<N_CHANNELS>::reset() {
 
 template<size_t N_CHANNELS>
 inline void Balance<N_CHANNELS>::process(
-		const float * const *x_l,
+		const float * const * xL,
-		const float * const *x_r,
+		const float * const * xR,
-		float * const *y_l,
+		float * const *       yL,
-		float * const *y_r,
+		float * const *       yR,
 		size_t                nSamples) {
-	bw_balance_process_multi(&coeffs, x_l, x_r, y_l, y_r, N_CHANNELS, nSamples);
+	bw_balance_process_multi(&coeffs, xL, xR, yL, yR, N_CHANNELS, nSamples);
 }
 
 template<size_t N_CHANNELS>
 inline void Balance<N_CHANNELS>::process(
-		const std::array<const float *, N_CHANNELS> x_l,
+		std::array<const float *, N_CHANNELS> xL,
-		const std::array<const float *, N_CHANNELS> x_r,
+		std::array<const float *, N_CHANNELS> xR,
-		const std::array<float *, N_CHANNELS> y_l,
+		std::array<float *, N_CHANNELS>       yL,
-		const std::array<float *, N_CHANNELS> y_r,
+		std::array<float *, N_CHANNELS>       yR,
 		size_t                                nSamples) {
-	process(x_l.data(), x_r.data(), y_l.data(), y_r.data(), nSamples);
+	process(xL.data(), xR.data(), yL.data(), yR.data(), nSamples);
 }
 
 template<size_t N_CHANNELS>
-inline void Balance<N_CHANNELS>::setBalance(float value) {
+inline void Balance<N_CHANNELS>::setBalance(
+		float value) {
 	bw_balance_set_balance(&coeffs, value);
 }