ITADataSourceRealization.h 7.4 KB
Newer Older
Jonas Stienen's avatar
Jonas Stienen committed
1
/*
2 3 4 5
 * ----------------------------------------------------------------
 *
 *		ITA core libs
 *		(c) Copyright Institute of Technical Acoustics (ITA)
6
 *		RWTH Aachen University, Germany, 2015-2018
7 8 9 10 11 12 13 14 15 16 17
 *
 * ----------------------------------------------------------------
 *				    ____  __________  _______
 *				   //  / //__   ___/ //  _   |
 *				  //  /    //  /    //  /_|  |
 *				 //  /    //  /    //  ___   |
 *				//__/    //__/    //__/   |__|
 *
 * ----------------------------------------------------------------
 *
 */
Jonas Stienen's avatar
Jonas Stienen committed
18

19 20
#ifndef INCLUDE_WATCHER_ITA_DATA_SOURCES_REALIZATION
#define INCLUDE_WATCHER_ITA_DATA_SOURCES_REALIZATION
Jonas Stienen's avatar
Jonas Stienen committed
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51

#include <ITADataSourcesDefinitions.h>

#include <ITADataSource.h>
#include <ITAStreamProperties.h>
#include <ITAAtomicPrimitives.h>

// Vorwrtsdeklarationen
class ITADatasourceRealizationEventHandler;

//! Grndgerst fr die Implementierung von Datenquellen
/**
 * Die Klasse ITADatasourceRealization ist ein Grundgerst fr die Implementierung
 * von Datenquellen. Sie bietet dem Entwickler einen Einstiegspunkt eigene
 * Datenquellen zu konstruieren und fat einige grundlegende Funktionalitt
 * zusammen. ITADatasourceRealization realisiert die abstrakten Methoden
 * der Oberklasse ITADatasource und bietet darber hinaus konkrete Methoden
 * fr das Bereitstellen von Daten seitens der Datenquelle.
 *
 * Intern enthlt ein ITADatasourceRealization einen Puffer in dem die 
 * freizusetzenden Daten zwischengespeichert werden. Dieser Puffer
 * kann nach beliebig dimensioniert werden (fr die Thread-Sicherheit mu er
 * aber mindestens die Gre 2 haben). Die Klasse stellt Methoden bereit
 * um Zeiger auf diesen Puffer abzurufen und diese zu inkrementieren (analog
 * der publizierten Schnittstelle von ITADatasource). Dabei werden komplexe
 * Aspekte der Thread-Sicherheit bercksichtigt und mssen nicht vom Entwickler
 * selbst programmiert werden.
 *
 * \ingroup datasources
 */

52 53
class ITA_DATA_SOURCES_API ITADatasourceRealization : public ITADatasource
{
Jonas Stienen's avatar
Jonas Stienen committed
54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
public:
	//! Konstruktor
	/**
	 * \param uiChannels    Anzahl der Kanle
	 * \param uiBlocklength Blocklnge (in Samples)
	 * \param uiCapacity    Gre des internen Puffers in Anzahl Blcken
	 *                      (Optional, Standardwert: 2, Minimalwert: 2)
	 *
	 * \note Bei Fehlern werden ITAExceptions aufgelst.
	 */
	/*
	ITADatasourceRealization(unsigned int uiChannels,
		                     unsigned int uiBlocklength,
				             unsigned int uiCapacity=2);
	*/

	//! Konstruktor
	/**
	 * \param uiChannels    Anzahl der Kanle
	 * \param dSamplerate	Abtastrate (in Hertz)
	 * \param uiBlocklength Blocklnge (in Samples)
	 * \param uiCapacity    Gre des internen Puffers in Anzahl Blcken
	 *                      (Optional, Standardwert: 2, Minimalwert: 2)
	 *
	 * \note Bei Fehlern werden ITAExceptions aufgelst.
	 */
	ITADatasourceRealization(unsigned int uiChannels,
							 double dSamplerate,
		                     unsigned int uiBlocklength,
				             unsigned int uiCapacity=2);

	virtual ~ITADatasourceRealization();

	//! -= Zurcksetzen =-
	/**
	 * \important Darf nur aufgerufen werden, wenn das Streaming nicht luft!
	 */
	virtual void Reset();

	//! Gibt zurck, ob Fehler whrend der Stream-Verarbeitung auftraten
	bool HasStreamErrors() const;

	//! Handler fr Stream-Event setzen
	/**
	 * \important Darf nur aufgerufen werden, wenn das Streaming nicht luft!
	 */
	ITADatasourceRealizationEventHandler* GetStreamEventHandler() const;

	//! Handler fr Stream-Event setzen
	/**
	 * \important Darf nur aufgerufen werden, wenn das Streaming nicht luft!
	 */
	void SetStreamEventHandler(ITADatasourceRealizationEventHandler* pHandler);

	// -= Realisierung der abstrakten Methoden von "ITADatasource" =-

110 111 112 113
	inline const ITAStreamProperties* GetStreamProperties() const { return &m_oStreamProps; }
	inline unsigned int GetBlocklength() const { return m_uiBlocklength; }
	inline unsigned int GetNumberOfChannels() const { return m_uiChannels; }
	inline double GetSampleRate() const { return m_dSampleRate; }
Jonas Stienen's avatar
Jonas Stienen committed
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142

    virtual const float* GetBlockPointer(unsigned int uiChannel, const ITAStreamInfo* pStreamInfo);
	virtual void IncrementBlockPointer();

	//! Schreibzeiger abrufen
	/**
	 * Diese Methode gibt den Zeiger die aktuelle Schreibposition im internen Puffer zurck.
	 * Der Rckgabewert ist niemals NULL.
	 *
	 * \param uiChannel Index des Kanals (Wertebereich: [0, Kanle-1])
	 * \return Zeiger auf die aktuelle Position des internen Puffers
	 */
	virtual float* GetWritePointer(unsigned int uiChannel);
	
	//! Schreibzeiger inkrementieren
	/**
	 * Der Aufruf dieser Methode inkrementiert den internen Schreibzeiger.
	 * Dadurch stellt die Datenquelle die nchsten Daten bereit. Wenn Sie die
	 * Schreiboperationen auf den Ausgabeblcken der Datenquelle abgeschlossen
	 * haben, <b>mssen</b> Sie diese Methode aufrufen, um diese Daten durch die
	 * Datenquelle bereitzustellen.
	 */ 
	virtual void IncrementWritePointer();

	//! Nachrichten-Methode
	/*
	 * Wird aufgerufen, wenn GetBlockPointer vom Stream aufgerufen wird,
	 * noch bevor intern Daten verarbeitert werden (also noch vor ProcessStream)
	 */
143
	inline virtual void PreGetBlockPointer() {};
Jonas Stienen's avatar
Jonas Stienen committed
144 145 146 147 148

	//! Nachrichten-Methode
	/*
	 * Wird aufgerufen, nachdem IncrementBlockPointer vom Stream aufgerufen wurde.
	 */
149
	inline virtual void PostIncrementBlockPointer() {};
Jonas Stienen's avatar
Jonas Stienen committed
150 151 152 153 154 155 156

	//! Verarbeitungsmethode
	/**
	 * Diese Hook-Methode wird von der Klasse aufgerufen, wenn neue Stream-Daten
	 * produziert werden sollen. Unterklassen sollten diese Methode redefinieren, 
	 * um die Verarbeitung von Samples zu realisieren.
	 */
157
	inline virtual void ProcessStream(const ITAStreamInfo* ) {};
Jonas Stienen's avatar
Jonas Stienen committed
158 159 160 161 162 163 164 165 166

protected:
	
	/*
	 *  [fwe] Der Einfachheit halber werden diese Variablen hier
	 *        protected zugnglich gemacht. Dies erspart hufige
	 *        Tipparbeit in Unterklassen. Bitte diese Werte aber
	 *        nur lesend [read-only] benutzen!!
	 */
167
	double m_dSampleRate;				// Abtastrate [Hz]
Jonas Stienen's avatar
Jonas Stienen committed
168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192
	unsigned int m_uiChannels;			// Anzahl Kanle
	unsigned int m_uiBlocklength;		// Streaming Puffergre [Samples]
	
private:
	ITAStreamProperties m_oStreamProps;	// Audiostream-Parameter

	unsigned int m_uiBufferSize;		// Puffergre
	unsigned int m_uiReadCursor;		// Leseposition
	unsigned int m_uiWriteCursor;		// Schreibposition

	float* m_pfBuffer;					// Puffer (Kanle interleaved!)
	ITAAtomicInt m_iGBPEntrances;		// Anzahl paralleler Eintritte in GBP
	ITAAtomicBool m_bGBPFirst;			// Erster Eintritt in GBP seit letztem IBP (=> Daten produzieren)
	int m_iBufferUnderflows;			// DEBUG: Zhler fr Buffer-Leerlufe
	int m_iBufferOverflows;				// DEBUG: Zhler fr Buffer-berlufe
	int m_iGBPReentrances;				// DEBUG: Zhler parallele Wiedereintritte in GBP
	int m_iIBPReentrances;				// DEBUG: Zhler parallele Wiedereintritte in IBP
	ITADatasourceRealizationEventHandler* m_pEventHandler;	// Handler fr Stream-Events

	void Init(unsigned int uiChannels,
			  unsigned int uiBlocklength,
			  unsigned int uiCapacity);
};

//! Schnittstelle fr Nachrichten-Verarbeitung der Klasse ITADatasourceRealization
193 194
class ITA_DATA_SOURCES_API ITADatasourceRealizationEventHandler
{
Jonas Stienen's avatar
Jonas Stienen committed
195
public:
196
	inline virtual ~ITADatasourceRealizationEventHandler() {};
Jonas Stienen's avatar
Jonas Stienen committed
197 198 199 200 201 202

	virtual void HandlePreGetBlockPointer(ITADatasourceRealization* pSender, unsigned int uiChannel);
	virtual void HandlePostIncrementBlockPointer(ITADatasourceRealization* pSender);
	virtual void HandleProcessStream(ITADatasourceRealization* pSender, const ITAStreamInfo* pStreamInfo);
};

203
#endif // INCLUDE_WATCHER_ITA_DATA_SOURCES_REALIZATION