~marcustomlinson/dspatch/2.62

<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Classes</a></div>

name="MSearchResults" id="MSearchResults">

</iframe>

</div>

<div class="title">Welcome! </div> </div>

</div>

Introduction</h2>

<p><a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a>, pronounced "dispatch", is a powerful C++ flow-based programming library that allows you to create and route (or "patch") high performance data processing circuits. <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> is not limited to any particular type of circuit or signal, its generic object-oriented API allows you to create almost any system imaginable, from simple logic circuits to high performance audio process chains and electronics simulation. <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a>'s simple framework makes development quick and easy, allowing you to hit the ground running on every project.</p>

<p><a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> is designed around the concept of a "circuit" containing "components", interconnected via "wires" that transfer "signals" to and from input and output "buses". For more detail on how <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> works, check out the <a href="spec_page.html"><b>DSPatch Design Specification</b></a>.</p>

<p>The two most important classes to consider are <a class="el" href="class_dsp_component.html" title="Abstract base class for all DSPatch components.">DspComponent</a> and <a class="el" href="class_dsp_circuit.html" title="Workspace for adding and routing components.">DspCircuit</a>. In order to route data to and from DspComponents they can either be added to an <a class="el" href="class_dsp_circuit.html" title="Workspace for adding and routing components.">DspCircuit</a>, where they can be wired together (recommended), or they can be wired directly via public <a class="el" href="class_dsp_component.html" title="Abstract base class for all DSPatch components.">DspComponent</a> methods. The <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> engine takes care of data transfer between interconnected components, when data is ready for a component to process, a callback: "Process_()" is executed in that component. For a component to form part of the <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> framework, designers simply have to derive their component from the <a class="el" href="class_dsp_component.html" title="Abstract base class for all DSPatch components.">DspComponent</a> base class, configure the component's IO buses, and implement the virtual Process_() callback method.</p>

</p>

100

101

Features</h2>

102

<ul>

103

<li><b>Automatic branch synchronization</b> - The result of data diverging across parallel branches is guaranteed to arrive synchronized at a converging point.</li>

104

<li><b>Dynamic thread count adjustment</b> - Specify at run-time, the number of threads in which you require a circuit to process.</li>

105

<li><b>Easy-to-use object-oriented API</b> - <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> is modeled around real-world circuit entities and concepts, making code more readable and easy to understand.</li>

106

<li><b>Feedback loops</b> - Create true closed-circuit systems by feeding resultant signals back into previous component inputs.</li>

107

<li><b>High performance parallel processing</b> - Circuits use advanced multi-threaded scheduling to maximize data flow efficiency.</li>

108

<li><b>Integrated circuits</b> - Build circuits within circuits to encapsulate complex component networks into single circuit components.</li>

109

<li><b>Non-threaded platform support</b> - Develop for (or port to) platforms without multi-threading support and process complex circuit systems in a single thread.</li>

110

<li><b>Run-time circuit wiring</b> - Connect and disconnect wires on the fly whilst maintaining steady data flow through the system.</li>

111

<li><b>Run-time adaptive signal types</b> - Component inputs can accept values of run-time varying types allowing you to create more flexible, multi-purpose component processes.</li>

112

</ul>

113

114

</p>

115

116

Getting Started</h2>

117

118

Step 1: Download DSPatch</h3>

119

<p>The <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> library can be downloaded from the <a href="https://sourceforge.net/projects/dspatch/"><b>SourceForge project page</b></a>. Download the project archive and extract the contents anywhere you like.</p>

120

121

Step 2: Read the Tutorials</h3>

122

<p>The "Tutorials" section below covers 2 vital aspects to developing with <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a>:</p>

123

124

<li>Creating a <a class="el" href="class_dsp_component.html" title="Abstract base class for all DSPatch components.">DspComponent</a> - This tutorial is a start to finish demonstration of how to create a <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> component.</li>

125

<li>Building a <a class="el" href="class_dsp_circuit.html" title="Workspace for adding and routing components.">DspCircuit</a> - In this tutorial you will learn how to use the <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> framework to interconnect and process <a class="el" href="class_dsp_component.html" title="Abstract base class for all DSPatch components.">DspComponent</a> networks using the <a class="el" href="class_dsp_circuit.html" title="Workspace for adding and routing components.">DspCircuit</a> interface.</li>

126

</ol>

127

128

Step 3: Check out the example project</h3>

129

<p>In the "example" folder (in the <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> root directory) you will find a <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> demo project, written to assist developers in understanding the <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> API as well as to demonstrate how it could be used to build audio process chains. This project uses the open-source library RtAudio in order to stream sound to your computer's audio device -Linux users will need to install "libasound2-dev" (ALSA) before attempting to build.</p>

130

131

Step 4: Make your own DspComponents</h3>

132

<p>A fast way to create your own <a class="el" href="class_dsp_component.html" title="Abstract base class for all DSPatch components.">DspComponent</a> could be to copy an existing component to another destination, rename it, and edit the contents to satisfy your component's required behavior. In the "example" folder (from Step 3) you will find 2 source files: "DspAdder.h" and "DspAdder.cpp". These files make up a very simple <a class="el" href="class_dsp_component.html" title="Abstract base class for all DSPatch components.">DspComponent</a> that receives 2 floating-point buffers into it's 2 inputs, adds each buffer element of the 1st buffer to the corresponding element of the 2nd buffer, then passes the resultant buffer to the output. Alternatively, you could just copy / reference the source code from the "Creating a DspComponent" tutorial (found under the "tutorial" folder in the root directory).</p>

133

134

Step 5: Roll your own DSPatch projects</h3>

135

<p>As <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> is not reliant on any non-standard 3rd party sources, getting a <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> project to compile and run is relatively painless. All you need to do from your project is #include "DSPatch.h" from the "include" folder (in the <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> root directory), and link to the <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> library (either by including all <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> source or by linking to a compiled library file). To speed things up you may want to copy, rename, and edit the example project from step 3 to get up and running faster.</p>

136

137

Step 6: Refer to the documentation</h3>

138

<p>Between the example project, the DspAdder component template, and the documentation found here, you should have enough resources to get started with <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> straight away. If you have any questions or wish to report a bug, feel free to email me at <a href="#" onclick="location.href='mai'+'lto:'+'mar'+'cu'+'s@a'+'da'+'pta'+'ud'+'io.'+'co'+'m'; return false;">marcu<span style="display: none;">.nosp@m.</span>s@ad<span style="display: none;">.nosp@m.</span>aptau<span style="display: none;">.nosp@m.</span>dio.<span style="display: none;">.nosp@m.</span>com</a>.</p>

139

140

</p>

141

142

Tutorials</h2>

143

144

1. Creating a DspComponent</h3>

145

<p>In order to create a new <a class="el" href="class_dsp_component.html" title="Abstract base class for all DSPatch components.">DspComponent</a>, we must derive our component class from the <a class="el" href="class_dsp_component.html" title="Abstract base class for all DSPatch components.">DspComponent</a> base class, configure component IO, and implement the inherited virtual "Process_()" method.</p>

146

<p>Lets take a look at how we would go about creating a boolean logic "AND" component. This component will accept 2 boolean input values and output the result of: input 1 && input 2.</p>

147

<p>We begin by deriving our new "DspAnd" component from <a class="el" href="class_dsp_component.html" title="Abstract base class for all DSPatch components.">DspComponent</a>:</p>

148

<div class="fragment"><pre class="fragment"><span class="comment">// 1. Derive component class from DspComponent</span>

149

150

<span class="keyword">class </span>DspAnd : <span class="keyword">public</span> <a class="code" href="class_dsp_component.html" title="Abstract base class for all DSPatch components.">DspComponent</a>

151

{

152

</pre></div><p>The next step is to configure our component's input and output buses. This is achieved by calling the base protected methods AddInput_() and AddOutput_() respectively from our component's constructor. Each method must be called once per input / output required. In our component's case, we require 2 inputs and 1 output, therefore our constructor code will look like this:</p>

153

<div class="fragment"><pre class="fragment"><span class="keyword">public</span>:

154

<span class="comment">// 2. Configure component IO buses</span>

155

156

DspAnd()

157

{

158

<span class="comment">// add 2 inputs</span>

159

AddInput_( <span class="stringliteral">"input1"</span> );

160

AddInput_( <span class="stringliteral">"input2"</span> );

161

162

<span class="comment">// add 1 output</span>

163

AddOutput_( <span class="stringliteral">"output"</span> );

164

}

165

</pre></div><p>The string values passed into the AddInput_() and AddOutput_() method calls are signal names / IDs. As component IO can be referenced by either string ID or index, IO signal names are optional. If we do not require a signal to have a string ID associated with it, we can simply leave the parenthesis empty.</p>

166

<p>Lastly, our component must implement the <a class="el" href="class_dsp_component.html" title="Abstract base class for all DSPatch components.">DspComponent</a> virtual Process_() method. This is where our component does it's work. The Process_() method provides us with 2 parameters: the input bus and the output bus. It is our duty as the component designer to pull the inputs we require out of the input bus, process them accordingly, and populate the output bus with the results. Our component's process method will look something like this:</p>

167

<div class="fragment"><pre class="fragment"><span class="keyword">protected</span>:

168

<span class="comment">// 3. Implement virtual Process_() method</span>

169

170

<span class="keyword">virtual</span> <span class="keywordtype">void</span> Process_( <a class="code" href="class_dsp_signal_bus.html" title="DspSignal container.">DspSignalBus</a>& inputs, <a class="code" href="class_dsp_signal_bus.html" title="DspSignal container.">DspSignalBus</a>& outputs )

171

{

172

<span class="comment">// create local stack variables to hold input values</span>

173

<span class="keywordtype">bool</span> bool1 = <span class="keyword">false</span>;

174

<span class="keywordtype">bool</span> bool2 = <span class="keyword">false</span>;

175

176

<span class="comment">// get values from inputs bus ( GetValue() returns true if successful )</span>

177

<span class="keywordflow">if</span>( inputs.GetValue( 0, bool1 ) && <span class="comment">//OR inputs.GetValue( "input1", bool1 );</span>

178

inputs.GetValue( 1, bool2 ) ) <span class="comment">//OR inputs.GetValue( "input2", bool2 );</span>

179

{

180

<span class="comment">// set output as the result of bool1 AND bool2</span>

181

outputs.SetValue( 0, bool1 && bool2 ); <span class="comment">//OR outputs.SetValue( "output", bool1 && bool2 );</span>

182

}

183

}

184

};

185

</pre></div><p>And that's it! Our component is now ready to form part of the <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> framework. Next we'll look at how we can add our component to a <a class="el" href="class_dsp_circuit.html" title="Workspace for adding and routing components.">DspCircuit</a> and route it to and from other DspComponents.</p>

186

187

</p>

188

189

2. Building a DspCircuit</h3>

190

<p>In order for us to get any real use out of our DspComponents, we need them to interact with each other. This is where the <a class="el" href="class_dsp_circuit.html" title="Workspace for adding and routing components.">DspCircuit</a> class comes in. A <a class="el" href="class_dsp_circuit.html" title="Workspace for adding and routing components.">DspCircuit</a> is a workspace for adding and routing DspComponents. In this section we will have a look at how to create a simple <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> application that generates random boolean pairs, performs a logic AND on each pair, then prints the result to screen.</p>

191

<p>First we must include the <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> header and any other headers that contain DspComponents we wish to use in our application:</p>

192

<div class="fragment"><pre class="fragment"><span class="preprocessor">#include "DSPatch.h"</span>

193

<span class="preprocessor">#include "components.h"</span>

194

</pre></div><p>Next, we must instantiate our <a class="el" href="class_dsp_circuit.html" title="Workspace for adding and routing components.">DspCircuit</a> object and all <a class="el" href="class_dsp_component.html" title="Abstract base class for all DSPatch components.">DspComponent</a> objects needed for our circuit. Lets say we had 2 other components included with "DspAnd" (from the first tutorial): "DspRandBool" (generates a random boolean value then outputs the result) and "DspPrintBool" (receives a boolean value and outputs it to the console):</p>

195

<div class="fragment"><pre class="fragment"><span class="keywordtype">void</span> main()

196

{

197

<span class="comment">// 1. Create a DspCircuit where we can route our components</span>

198

199

<a class="code" href="class_dsp_circuit.html" title="Workspace for adding and routing components.">DspCircuit</a> circuit;

200

201

<span class="comment">// 2. Create instances of the components needed for our circuit</span>

202

203

DspRandBool randBoolGen1;

204

DspRandBool randBoolGen2;

205

DspAnd logicAnd;

206

DspPrintBool boolPrinter;

207

</pre></div><p>Now that we have a circuit and some components, lets add all of our components to the circuit:</p>

208

<div class="fragment"><pre class="fragment"> <span class="comment">// 3. Add component instances to circuit</span>

209

210

circuit.AddComponent( randBoolGen1, <span class="stringliteral">"Bool Generator 1"</span> );

211

circuit.AddComponent( randBoolGen2, <span class="stringliteral">"Bool Generator 2"</span> );

212

circuit.AddComponent( logicAnd, <span class="stringliteral">"Logic AND"</span> );

213

circuit.AddComponent( boolPrinter, <span class="stringliteral">"Bool Printer"</span> );

214

</pre></div><p>The string values passed into the AddComponent() method calls are component names / IDs. Although we still have the option of referencing a component via it's pointer in a circuit, component string IDs can allow circuit objects to be entirely self-contained. This could give us the ability to pass circuits around by reference, allowing the receiver access to all circuit components via their string IDs, without having to manage both component and circuit references everywhere.</p>

215

<p>We are now ready to begin wiring the circuit:</p>

216

<div class="fragment"><pre class="fragment"> <span class="comment">// 4. Wire up the components inside the circuit</span>

217

218

219

circuit.ConnectOutToIn( randBoolGen1, 0, logicAnd, 0 );

220

<span class="comment">//OR circuit.ConnectOutToIn( "Bool Generator 1", 0, "Logic AND", 0 );</span>

221

<span class="comment">//OR circuit.ConnectOutToIn( "Bool Generator 1", 0, "Logic AND", "input1" );</span>

222

223

circuit.ConnectOutToIn( randBoolGen2, 0, logicAnd, 1 );

224

<span class="comment">//OR circuit.ConnectOutToIn( "Bool Generator 2", 0, "Logic AND", 1 );</span>

225

<span class="comment">//OR circuit.ConnectOutToIn( "Bool Generator 2", 0, "Logic AND", "input2" );</span>

226

227

circuit.ConnectOutToIn( logicAnd, 0, boolPrinter, 0 );

228

<span class="comment">//OR circuit.ConnectOutToIn( "Logic AND", 0, "Bool Printer", 0 );</span>

229

<span class="comment">//OR circuit.ConnectOutToIn( "Logic AND", "output", "Bool Printer", 0 );</span>

230

</pre></div><p>The code above results in the following wiring configuration: </p>

231

<div class="fragment"><pre class="fragment"> ___________

232

[<span class="stringliteral">"Bool Generator 1"</span>] 0 ---> 0 | |

233

|<span class="stringliteral">"Logic AND"</span>| 0 ---> 0 [<span class="stringliteral">"Bool Printer"</span>]

234

[<span class="stringliteral">"Bool Generator 2"</span>] 0 ---> 1 |___________|

235

</pre></div><p>*N.B. Each component input can only accept one wire at a time. When another wire is connected to an input that already has a connected wire, that wire is replaced with the new one. One output, on the other hand, can be distributed to multiple inputs.</p>

236

<p>Lastly, in order for our circuit to do any work it must be ticked over. This is performed by repeatedly calling the circuit's Tick() and Reset() methods. These methods can be called manually in a loop from the main application thread, or alternatively, by calling StartAutoTick(), a seperate thread will spawn, automatically calling Tick() and Reset() continuously. A circuit's thread count can be adjusted at runtime, allowing us to increase / decrease the number of threads use by the circuit as required during execution:</p>

237

<div class="fragment"><pre class="fragment"> <span class="comment">// 5. Tick the circuit</span>

238

239

240

<span class="comment">// Circuit tick method 1: Manual</span>

241

<span class="keywordflow">for</span>( <span class="keywordtype">unsigned</span> <span class="keywordtype">short</span> i = 0; i < 10; i++ )

242

{

243

circuit.Tick();

244

circuit.Reset();

245

}

246

247

<span class="comment">// Circuit tick method 2: Automatic</span>

248

std::cout << <span class="stringliteral">"Press any key to begin circuit auto-tick."</span>;

249

getchar();

250

circuit.StartAutoTick();

251

252

<span class="comment">// Increase circuit thread count for higher performance</span>

253

getchar();

254

circuit.SetThreadCount( 4 );

255

256

<span class="comment">// Press any key to quit</span>

257

getchar();

258

</pre></div><p>Lastly, the DSPatch::Finalize() method must be called on application exit in order for <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> to perform its own internal memory cleanup.</p>

259

<div class="fragment"><pre class="fragment"> <span class="comment">// 6. Clean up</span>

260

261

DSPatch::Finalize();

262

}

263

</pre></div><p>(All the source code from these tutorials can be found under the "tutorial" folder in the <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> root directory).</p>

264

265

</p>

266

267

Release Notes</h2>

268

269

v.2.51 (13 September 2013)</h3>

270

<ul>

271

<li>Fixed Unix thread detach error.</li>

272

<li>Improved overall encapsulation.</li>

273

<li>Replaced "Clear" with "Remove" for I/O removal.</li>

274

</ul>

275

276

v.2.50 (14 July 2013)</h3>

277

<ul>

278

<li>Reduced size of distributable.</li>

279

<li>Removed closed source dependency from example project.</li>

280

<li>Added Linux makefiles.</li>

281

</ul>

282

283

v.2.43 (30 June 2013)</h3>

284

<ul>

285

<li>Simplified platform selection macros.</li>

286

</ul>

287

288

v.2.42 (24 June 2013)</h3>

289

<ul>

290

<li>Added vs2008 and vs2010 versions of dspdemo.</li>

291

<li>Code style and performance improvements.</li>

292

</ul>

293

294

v.2.41 (07 February 2013)</h3>

295

<ul>

296

<li>Fixed VS2010 dspdemo linker errors.</li>

297

</ul>

298

299

v.2.40 (04 February 2013)</h3>

300

<ul>

301

<li>Optimized <a class="el" href="class_dsp_run_type.html" title="Dynamically typed variable.">DspRunType</a>.</li>

302

<li>Added Stop() method to <a class="el" href="class_dsp_thread.html" title="Cross-platform, object-oriented thread.">DspThread</a>.</li>

303

<li>Reduced pointer dereferencing and temporaries.</li>

304

</ul>

305

306

v.2.33 (01 February 2013)</h3>

307

<ul>

308

<li>Signal reading / writing optimized.</li>

309

<li>Code cleaned up and re-formatted.</li>

310

</ul>

311

312

v.2.32 (24 January 2013)</h3>

313

<ul>

314

<li>Reduced component thread mutex locking.</li>

315

<li>Fixed <a class="el" href="class_dsp_circuit.html" title="Workspace for adding and routing components.">DspCircuit</a> AddInput() run-time error.</li>

316

<li>Documentation updates.</li>

317

</ul>

318

319

v.2.31 (19 December 2012)</h3>

320

<ul>

321

<li>Improved synchronization in AddComponent().</li>

322

<li>Component routing upgraded to template methods.</li>

323

</ul>

324

325

v.2.30 (15 December 2012)</h3>

326

<ul>

327

<li>Circuit routing simplified.</li>

328

<li>Completed "circuit-less" component processing.</li>

329

<li>Component names now optional.</li>

330

<li><a class="el" href="class_dsp_circuit.html" title="Workspace for adding and routing components.">DspCircuit</a> no longer deletes external memory.</li>

331

<li>Optimized circuit-in-circuit processing.</li>

332

</ul>

333

334

v.2.2 (08 December 2012)</h3>

335

<ul>

336

<li>A component can no longer exist in multiple circuits.</li>

337

<li>Added coding tutorials</li>

338

<li>Cleaned up project directory structure.</li>

339

<li>Comments and documentation updates.</li>

340

<li>Resolved component / circuit thread count clash.</li>

341

</ul>

342

343

v.2.1 (06 November 2012)</h3>

344

<ul>

345

<li>Removed DspSafePointer class.</li>

346

<li>Greatly improved overall performance.</li>

347

<li>Added commenting for doxygen.</li>

348

</ul>

349

350

v.2.0 (02 November 2012)</h3>

351

<ul>

352

<li>Re-licensed <a class="el" href="class_d_s_patch.html" title="System-wide DSPatch functionality.">DSPatch</a> to LGPL.</li>

353

<li>Added support for non-threaded platforms.</li>

354

<li>Circuit routing upgraded to more flexible template methods.</li>

355

</ul>

356

357

v.1.2 (20 October 2012)</h3>

358

<ul>

359

<li>Ported to Unix-based OS's.</li>

360

<li>Completed circuit-in-circuit logic.</li>

361

</ul>

362

363

v.1.1 (17 October 2012)</h3>

364

<ul>

365

<li>Various bug fixes.</li>

366

<li>Added 2 more components to the dspdemo project.</li>

367

<li>Optimized threaded circuit processing.</li>

368

<li>AddComponent() updated to accept pre-constructed DspComponents.</li>

369

</ul>

370

371

v.1.0 (14 October 2012)</h3>

372

<ul>

373

<li>Extracted routing engine behind "Crosstalk" to form: "DSPatch". </li>

374

</ul>

375

</div></div>

376

377

378

379

Generated on Fri Sep 13 2013 07:57:23 for DSPatch by  <a href="http://www.doxygen.org/index.html">

380

381

</a> 1.8.0

382

</small></address>

383

384

</body>

385

</html>

Older »