CDSPProcessor.h

//$ nobt
//$ nocpp

/**
 * @file CDSPProcessor.h
 *
 * @brief The base virtual class for DSP processing algorithms.
 *
 * This file includes the base virtual class for DSP processing algorithm
 * classes like FIR filtering and interpolation.
 *
 * r8brain-free-src Copyright (c) 2013-2025 Aleksey Vaneev
 *
 * See the "LICENSE" file for license.
 */

#ifndef R8B_CDSPPROCESSOR_INCLUDED
#define R8B_CDSPPROCESSOR_INCLUDED

#include "r8bbase.h"

namespace r8b {

/**
 * @brief The base virtual class for DSP processing algorithms.
 *
 * This class can be used as a base class for various DSP processing
 * algorithms (processors). DSP processors that are derived from this class
 * can be seamlessly integrated into various DSP processing graphs.
 */

class CDSPProcessor : public R8B_DSPBASECLASS
{
	R8BNOCTOR( CDSPProcessor )

public:
	CDSPProcessor()
	{
	}

	virtual ~CDSPProcessor()
	{
	}

	/**
	 * @brief Returns the number of input samples required to advance to
	 * the specified output sample position (so that the next process() call
	 * passes this output position).

	 * Assumes starting at the cleared or after-construction state of *this*
	 * object.
	 *
	 * Note that the implementation of this function assumes the caller only
	 * needs to estimate an initial buffering requirement; passing a full
	 * sample length value (e.g., greater than 100000) may overflow the
	 * calculation or cause rounding errors.
	 *
	 * @param ReqOutPos The required output position. Set to 0 to obtain
	 * "input length before output start" latency. Must be a non-negative
	 * value.
	 * @return The number of input samples required.
	 */

	virtual int getInLenBeforeOutPos( const int ReqOutPos ) const = 0;

	/**
	 * @brief Return the latency, in samples, which is present in the output
	 * signal.
	 *
	 * This value is usually zero if the DSP processor "consumes" the latency
	 * automatically.
	 */

	virtual int getLatency() const = 0;

	/**
	 * @brief Returns fractional latency, in samples, which is present in the
	 * output signal.
	 *
	 * This value is usually zero if a linear-phase filtering is used. With
	 * minimum-phase filters in use, this value can be non-zero even if
	 * the getLatency() function returns zero.
	 */

	virtual double getLatencyFrac() const = 0;

	/**
	 * @brief Returns the maximal length of the output buffer required when
	 * processing the `MaxInLen` number of input samples.
	 *
	 * @param MaxInLen The number of samples planned to process at once, at
	 * most.
	 */

	virtual int getMaxOutLen( const int MaxInLen ) const = 0;

	/**
	 * @brief Clears (resets) the state of *this* object and returns it to
	 * the state after construction.
	 *
	 * All input data accumulated in the internal buffer so far will be
	 * discarded.
	 */

	virtual void clear() = 0;

	/**
	 * @brief Performs DSP processing.
	 *
	 * @param ip Input data pointer.
	 * @param l0 How many samples to process.
	 * @param[out] op0 Output data pointer. The capacity of this buffer should
	 * be equal to the value returned by the getMaxOutLen() function for the
	 * given `l0`. This buffer can be equal to `ip` only if the
	 * `getMaxOutLen( l0 )` call returned a value lesser than `l0`. This
	 * pointer can be incremented on function's return if latency compensation
	 * was performed by the processor. Note that on function's return, this
	 * pointer may point to some internal buffers, including the `ip` buffer,
	 * ignoring the originally passed value.
	 * @return The number of output samples written to the `op0` buffer and
	 * available after processing. This value can be smaller or larger in
	 * comparison to the original `l0` value due to processing and filter's
	 * latency compensation that took place, and due to resampling if it was
	 * performed.
	 */

	virtual int process( double* ip, int l0, double*& op0 ) = 0;
};

} // namespace r8b

#endif // R8B_CDSPPROCESSOR_INCLUDED