developers.html 50.2 KB
Newer Older
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<!DOCTYPE HTML>
<!--
	Landed by HTML5 UP
	html5up.net | @ajlkn
	Free for personal and commercial use under the CCA 3.0 license (html5up.net/license)
-->
<html>
	<head>
		<title>Virtual Acoustics</title>
		<meta charset="utf-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1" />
		<!--[if lte IE 8]><script src="assets/js/ie/html5shiv.js"></script><![endif]-->
		<link rel="stylesheet" href="assets/css/main.css" />
		<!--[if lte IE 9]><link rel="stylesheet" href="assets/css/ie9.css" /><![endif]-->
		<!--[if lte IE 8]><link rel="stylesheet" href="assets/css/ie8.css" /><![endif]-->
	</head>
	<body>
		<div id="page-wrapper">

			<!-- Header -->
				<header id="header">
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
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
					<h1 id="logo"><a href="index.html">Start</a></h1>
					<nav id="nav">
						<ul>
							<li>
								<a href="#">Quick access</a>
								<ul>
									<li><a href="overview.html">Overview</a></li>
									<li><a href="download.html">Download</a></li>
									<li><a href="documentation.html">Documentation</a></li>
									<li>
										<a href="start.html">Getting started</a>
										<ul>
											<li><a href="start.html#configuration">Configuration</a></li>
											<li><a href="start.html#control">Control</a></li>
											<li><a href="start.html#scene_handling">Scene handling</a></li>
											<li><a href="start.html#rendering">Audio rendering</a></li>
											<li><a href="start.html#reproduction">Audio reproduction</a></li>
											<li><a href="start.html#tracking">Tracking</a></li>
											<li><a href="start.html#simulation_recording">Simulation and recording</a></li>
											<li><a href="start.html#examples">Examples</a></li>
										</ul>
									</li>
									<li>
										<a href="help.html">Get help</a>
										<ul>
											<li><a href="help.html#faq">FAQ</a></li>
											<li><a href="help.html#issue_tracker">Issue tracker</a></li>
											<li><a href="help.html#community">Community</a></li>
											<li><a href="help.html#nosupport">No support</a></li>
										</ul>
									</li>
									<li>
										<a href="developers.html">Developers</a>
										<ul>
											<li><a href="developers.html#api">C++ API</a></li>
											<li><a href="developers.html#dependencies">Dependencies</a></li>
											<li><a href="developers.html#configuration">Configuration</a></li>
											<li><a href="developers.html#build_guide">Build guide</a></li>
											<li><a href="developers.html#repositories">Repositories</a></li>
										</ul>
									</li>
									<li>
										<a href="research.html">Research</a>
										<ul>
											<li><a href="research.html#system">System papers</a></li>
											<li><a href="research.html#technology">Technology papers</a></li>
											<li><a href="research.html#applied">Applied papers</a></li>
										</ul>
									</li>
								</ul>
							</li>
							<li><a href="legal.html">Legal notice</a></li>
							<!--<li><a href="#" class="button special">Sign Up</a></li>-->
						</ul>
					</nav>
				</header>
78
					
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
79
80
81
82
83
84
85



			<!-- Main -->
				<div id="main" class="wrapper style1">
					<div class="container">
						<header class="major">
86
87
							<h2>Developer section</h2>
							<p>How to build and extend VA </p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
88
89
90
						</header>

								<!-- Content -->
91
									<section id="preface">
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
92
										
93
										<h3>Preface</h3>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
94
										<p>
95
										VA is based on <b>C++11</b> source code and will compile on any modern architecture with a current C/C++ compiler set. <br />
96
97
98
99
										If you plan to build VA expect to spent a significant amount of time to prepare the <b>required dependencies</b> (see tables below). For Windows users no package manager is available to pull in software packages, hence manual configuration and compiling is required (which can be hard work). <br />
										</p>
										<p>
										VA uses <a href="http://cmake.org" target="_blank">CMake</a> to configure the project. It allows to activate and deactivate rendering and reproduction modules and and offers options to control implementation details of the core.								
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
100
101
102
103
104
105
106
										</p>
										
									</section>
									
									
									<section id="api">
									
107
										<p>&nbsp;</p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
108
109
										<h3>C++ code documentation</h3>
										<p>
110
										Virtual Acoustics is entirely written in C++. However some bindings for other languages like Python and Matlab exist. They have been brought into existence in the spirit of making VA available for a broader user base that is not familiar with C++ programming. For those who are not familiar with C++, see <a href="start.html">getting started section</a>). If you want to embrace VA in your software (instead of only controlling it from the outside), here is what you need to know:<br />
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
111
										</p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
112
										
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
113
114
										<h4>C++ API documentation (generated with Doxygen)</h4>
										<ul>
115
											<!-- @todo launch: remove escape in url -->
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
116
											<a href="../resources/v2018a/doc/html/index.html">Virtual Acoustics C++ API v2018a</a><br />
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
117
118
119
										</ul>
									</section>
									
120
121
122
123
124
125
126
									<section id="dependencies">
									
										
										<p>&nbsp;</p>
								
										<h3>Dependencies</h3>
										
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
127
128
										<h4>Third party dependencies</h4>
										<p>
129
										VA makes extensive use of third party libraries. Parts of the framework can be build with a minimal set of external libs, however the core and applications all require the full dependency tree to be solved. Table 1 below lists the internal and external dependencies (for a description of the projects, see <a href="overview.html">overview</a> and <a href="documentation.html">documentation</a> section).
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
130
131
										</p>
										
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
132
133
134
135
								<div class="table-wrapper">
									<table class="alt">
										<thead>
											<tr>
136
137
												<th width="32%">Project name</th>
												<th width="24%">Internal dependencies (<i>components</i>)</th>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
138
139
140
141
142
143
144
145
146
147
148
149
												<th>External dependencies (<i>components</i>)</th>
											</tr>
										</thead>
										<tbody>
											<tr>
												<td><b>VABase</b></td>
												<td><i>none</i></td>
												<td><i>none</i></td>
											</tr>
											<tr>
												<td><b>VANet</b></td>
												<td>VABase</td>
150
												<td>VistaCoreLibs <i>(Aspects, Base, InterProcComm)</i></td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
151
152
153
											</tr>
											<tr>
												<td><b>VALua</b></td>
154
155
												<td>VABase <br /> VANet</td>
												<td>VistaCoreLibs <i>(Aspects, Base, InterProcComm)</i> <br /> Lua C++ headers and libs</td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
156
157
158
											</tr>
											<tr>
												<td><b>VAMatlab</b></td>
159
160
												<td>VABase <br /> VANet</td>
												<td>VistaCoreLibs <i>(Aspects, Base, InterProcComm)</i> <br /> Matlab C++ headers and libs <br />NaturalPoint OptiTrack C++ headers and libs [optional]</td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
161
162
163
											</tr>
											<tr>
												<td><b>VACS (C#)</b></td>
164
165
												<td>VABase <br /> VANet</td>
												<td>VistaCoreLibs <i>(Aspects, Base, InterProcComm)</i></td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
166
167
168
											</tr>
											<tr>
												<td><b>VAPython</b></td>
169
170
												<td>VABase <br /> VANet</td>
												<td>VistaCoreLibs <i>(Aspects, Base, InterProcComm)</i> <br /> Python C++ headers and libs, Python's distutils</td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
171
172
173
174
											</tr>
											<tr>
												<td><b>VACore</b></td>
												<td>VABase</td>
175
176
177
178
179
180
181
182
183
184
185
												<td>ITACoreLibs <i>(all components)</i><br /> ITAGeometricalAcoustics <i>(all components)</i> [optional]<br /> RAVEN [optional]<br />  VistaCoreLibs <i>(Aspects, Base, InterProcComm)</i> <br /> OpenDAFF C++ headers and libs <br />SPLINE </br /></td>
											</tr>
											<tr>
												<td><b>VAServer</b></td>
												<td>VABase <br /> VANet <br /> VACore</td>
												<td>ncurses (POSIX only)</td>
											</tr>
											<tr>
												<td><b>Redstart</b></td>
												<td>VABase <br /> VANet <br /> VACore</td>
												<td>ITAVTK <br /> ITAQtWidgets <br /> Qt</td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
186
187
188
189
190
191
192
193
194
195
196
											</tr>
										</tbody>
										<tfoot>
											<tr>
												<td colspan="3">Table 1: VA dependency tree</td>
											</tr>
										</tfoot>
									</table>
								</div>
										
										<p>
197
										The <a href="http://git.rwth-aachen.de/ita/projects" target="_blank">ITA projects</a> <b>ITACoreLibs</b>, <b>ITAGeometricalAcoustics</b> and <b>ITAAcousticVisualization</b> are open source projects (see below), <b>RAVEN</b> (Room Acoustics for Virtual ENvironments) however is not available to the public. It is only required as a backend for the room acoustics audio renderer, which is disabled by default.<br />
198
										These projects have a lot of dependencies to smaller projects, which are pulled in if you want to build the <b>VACore</b> of any application using it (cmp. Table 2).
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
199
200
201
202
203
</p>										
								<div class="table-wrapper">
									<table class="alt">
										<thead>
											<tr>
204
205
												<th width="32%">Project name</th>
												<th width="24%">Internal dependencies (<i>components</i>)</th>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
206
207
208
209
210
												<th>External dependencies (<i>components</i>)</th>
											</tr>
										</thead>
										<tbody>
											<tr>
211
												<td><b>ITABase</b> <br /> <i>(ITACoreLibs component)</i></td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
212
												<td><i>none</i></td>
213
												<td>libsamplerate <br /> libsndfile <br /> pcre and pcrecpp <br /> SPLINE <br /> IPP [optional, problematic license] <br /> SimpleINI (in source) </br> pthreads (POSIX only)</td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
214
215
											</tr>
											<tr>
216
												<td><b>ITAFFT</b> <br /> <i>(ITACoreLibs component)</i></td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
217
												<td>ITABase</td>
218
												<td>FFTW3 [optional, but recommended, though forces VA into GPL] <br /> MKL [optional] <br /> FFTS [optional]</td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
219
220
											</tr>
											<tr>
221
												<td><b>ITADataSources</b> <br /> <i>(ITACoreLibs component)</i></td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
222
223
224
225
												<td>ITABase</td>
												<td>VistaCoreLibs <i>(Aspects, Base, InterProcComm)</i> <br /> ASIO [optional, but recommended] <br /> Portaudio [optional]<br /> JACK [optional] </td>
											</tr>
											<tr>
226
227
												<td><b>ITAConvolution</b> <br /> <i>(ITACoreLibs component)</i></td>
												<td>ITABase <br /> ITAFFT</td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
228
229
230
												<td>TBB</td>
											</tr>
											<tr>
231
232
233
												<td><b>ITACTC</b> <br /> <i>(ITACoreLibs component)</i></td>
												<td>ITABase <br /> ITAConvolution <br /> ITADataSources <br /> ITAFFT</td>
												<td>OpenDAFF</td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
234
235
											</tr>
											<tr>
236
237
												<td><b>ITADSP</b> <br /> <i>(ITACoreLibs component)</i></td>
												<td>ITABase <br /> ITAFFT <br /> ITAConvolution</td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
238
239
												<td>TBB <br /> SPLINE</td>
											</tr>
240
241
242
243
244
245
246
247
248
249
250
251
252
											<tr>
												<td><b>ITAGeo</b> <br /> <i>(ITAGeometricalAcoustics component)</i></td>
												<td>ITABase</td>
												<td>VistaCoreLibs <i>(Base, Math)</i> <br /> OpenMesh [optional, recommended] <br /> SketchUp / slapi [optional, recommended]  <br /> libcitygml [optional] <br /> IfcOpenShell [optional] </td>
											</tr>
											<tr>
												<td><b>ITADiffraction</b> <br /> <i>(ITAGeometricalAcoustics component)</i></td>
												<td>ITABase <br /> ITAGeo</td>
												<td><i>none</i></td>
											</tr>
											<tr>
												<td><b>ITAVTK</b> <br /> <i>(ITAAcousticVisualization component)</i></td>
												<td>ITABase <br /> ITAGeo [optional] </td>
253
												<td>VTK [recommended with Qt5 support]</td>
254
255
256
257
											</tr>
											<tr>
												<td><b>ITAQtWidgets</b> <br /> <i>(ITAAcousticVisualization component)</i></td>
												<td>ITABase <br /> ITADataSources <br /> ITAGeo [optional] <br /> ITADiffraction [optional] <br > ITAVTK [optional] </td>
258
												<td>Qt5 <br /> VTK with Qt5 support</td>
259
											</tr>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
260
261
262
										</tbody>
										<tfoot>
											<tr>
263
												<td colspan="3">Table 2: ITA projects dependency tree</td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
264
265
266
267
268
											</tr>
										</tfoot>
									</table>
								</div>
								
269
270
271
									</section>
								
									<section id="configuration">
272
									
273
274
275
										<p>&nbsp;</p>
										<h3>Build configurations</h3>
										
276
277
										<h4>VA configuration options</h4>
										<p>
Michael Kohnen's avatar
Michael Kohnen committed
278
										VA can be configured by a variety of options to meet the needs for different purposes. This is usually required if not all of the dependency tree is available and only some features (like rendering or reproduction modules) should be compiled and linked to the core. Also, if you only want to build the network support to control a remote core or want to build a binding for an uncommon platform, you will find this section helpful.
279
280
										<br />
										<br />
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
281
										All CMake configuration options will have an <code>ITA_</code> prefix. If "Grouped" mode is activated in CMake GUI, the group name is <code>ITA</code> and all relevant options will be listed there.
282
283
284
285
286
287
288
289
290
										</p>
										
										<h5>VA (general)</h5>
										<p>
										</p>
								<div class="table-wrapper">
									<table class="alt">
										<thead>
											<tr>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
291
292
												<th width="50%">Option</th>
												<th>Description</th>
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
											</tr>
										</thead>
										<tbody>
											<tr>
												<td><b>ITA_VA_BUILD_STATIC</b></td>
												<td>Activate, if you want to build static VA libraries. Also, uncheck BUILD_SHARED_LIBS in this case.</td>
											</tr>
											<tr>
												<td><b>ITA_VA_GENERATE_DOCUMENTATION</b></td>
												<td>Generates the documentation using Doxygen</td>
											</tr>
											<tr>
												<td><b>ITA_VA_INSTALL_WITH_DLLS</b></td>
												<td>Will copy all dependent shared libraries (DLLs in Windows) to the <code>bin</code> folder when deploying / installing.</td>
											</tr>
											<tr>
												<td><b>ITA_VA_WITH_BENCHMARKS</b></td>
												<td>Includes benchmarks for all subprojects</td>
											</tr>
											<tr>
												<td><b>ITA_VA_WITH_TESTS</b></td>
												<td>Includes tests for all subprojects</td>
											</tr>
											<tr>
												<td><b>ITA_VA_WITH_SERVER_APPS</b></td>
												<td>Includes server application (VAServer)</td>
											</tr>
											<tr>
												<td><b>ITA_VA_WITH_UNITY_SCRIPTS</b></td>
												<td>Will also deploy Unity extension C# scripts</td>
											</tr>
											<tr>
												<td><b>ITA_VA_WITH_CORE</b></td>
												<td>Includes the core (VACore)</td>
											</tr>
											<tr>
												<td><b>ITA_VA_WITH_BINDING_CS</b></td>
												<td>Includes the C# binding (VACS)</td>
											</tr>
											<tr>
												<td><b>ITA_VA_WITH_BINDING_LUA</b></td>
												<td>Includes the Lua binding (VALua)</td>
											</tr>
											<tr>
												<td><b>ITA_VA_WITH_BINDING_MATLAB</b></td>
												<td>Includes the Matlab binding (VAMatlab)</td>
											</tr>
											<tr>
												<td><b>ITA_VA_WITH_BINDING_PYTHON</b></td>
												<td>Includes the Python binding (VAPython)</td>
											</tr>
										</tbody>
										<tfoot>
											<tr>
Michael Kohnen's avatar
Michael Kohnen committed
347
												<td colspan="2">Table 3: General VA CMake configuration</td>
348
349
350
351
352
353
354
											</tr>
										</tfoot>
									</table>
									
									
										<h5>VANet (network library settings)</h5>
										<p>
355
										</p>
356
357
358
359
								<div class="table-wrapper">
									<table class="alt">
										<thead>
											<tr>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
360
361
												<th width="50%">Option</th>
												<th>Description</th>
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
											</tr>
										</thead>
										<tbody>
											<tr>
												<td><b>ITA_VANET_DEFAULT_PORT</b></td>
												<td>Changes default port (usually 12340)</td>
											</tr>
											<tr>
												<td><b>ITA_VANET_VERSION_MAJOR</b></td>
												<td>VANet version major part, e.g. v2018</td>
											</tr>
											<tr>
												<td><b>ITA_VANET_VERSION_MINOR</b></td>
												<td>VANet version minor part, e.g. a,b,c,d ...</td>
											</tr>
											<tr>
												<td><b>ITA_VANET_WITH_NETAUDIO_STREAM_SERVER_EXTENSION</b></td>
												<td>Includes a network streaming server extension for custom signal sources</td>
											</tr>
										</tbody>
										<tfoot>
											<tr>
												<td colspan="2">Table 4: VANet specific CMake configuration</td>
											</tr>
										</tfoot>
									</table>
388
										
389
390
391
392
393
394
395
396
397
									
									
										<h5>VAMatlab (Matlab binding)</h5>
										<p>
										</p>
								<div class="table-wrapper">
									<table class="alt">
										<thead>
											<tr>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
398
399
												<th width="50%">Option</th>
												<th>Description</th>
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
											</tr>
										</thead>
										<tbody>
											<tr>
												<td><b>ITA_VAMATLAB_SHOW_BANNER</b></td>
												<td>Includes VA banner on first creation in Matlab</td>
											</tr>
											<tr>
												<td><b>ITA_VAMATLAB_VERSION_MAJOR</b></td>
												<td>VAMatlab version major part, e.g. v2018</td>
											</tr>
											<tr>
												<td><b>ITA_VAMATLAB_VERSION_MINOR</b></td>
												<td>VAMatlab version minor part, e.g. a,b,c,d ...</td>
											</tr>
											<tr>
												<td><b>ITA_VAMATLAB_DEPLOY_MATLAB_EXECUTABLE</b></td>
												<td>Additionally deploy matlab executable to <code>bin</code> folder</td>
											</tr>
											<tr>
												<td><b>ITA_VAMATLAB_BUILD_WITH_OPTITRACK_TRACKING_SUPPORT</b></td>
												<td>Include OptiTrack tracking support to enable integrated update of sound receivers and sound sources</td>
											</tr>
											<tr>
												<td><b>ITA_VAMATLAB_BUILD_WITH_INTEGRATED_CORE</b></td>
												<td>Link core into Matlab executable (no server application required, but VA behaviour can not be monitored, anymore)</td>
											</tr>
											<tr>
												<td><b>ITA_VAMATLAB_POSTBUILD_CREATE_MATLAB_CLASS</b></td>
												<td>Auto-create Matlab convenience class after build [for future use]</td>
											</tr>
										</tbody>
										<tfoot>
											<tr>
												<td colspan="2">Table 5: VAMatlab specific CMake configuration</td>
											</tr>
										</tfoot>
									</table>
									
										<h5>VAPython (Python binding)</h5>
										<p>
										</p>
								<div class="table-wrapper">
									<table class="alt">
										<thead>
											<tr>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
446
447
												<th width="50%">Option</th>
												<th>Description</th>
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
											</tr>
										</thead>
										<tbody>
											<tr>
												<td><b>ITA_VAPYTHON_VERSION_MAJOR</b></td>
												<td>VAPython version major part, e.g. v2018</td>
											</tr>
											<tr>
												<td><b>ITA_VAPYTHON_VERSION_MINOR</b></td>
												<td>VAPython version minor part, e.g. a,b,c,d ...</td>
											</tr>
										</tbody>
										<tfoot>
											<tr>
												<td colspan="2">Table 6: VAPython specific CMake configuration</td>
											</tr>
										</tfoot>
									</table>
									
									
										<h5>VACore (core functionality)</h5>
										<p>
										</p>
								<div class="table-wrapper">
									<table class="alt">
										<thead>
											<tr>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
475
476
												<th width="50%">Option</th>
												<th>Description</th>
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
											</tr>
										</thead>
										<tbody>
											<tr>
												<td><b>ITA_VACORE_DEPLOY_WITH_COMMON_CONFIGS</b></td>
												<td>Copies configuration files along when deploying / installing</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_DEPLOY_WITH_COMMON_DATA</b></td>
												<td>Copies data files along when deploying / installing</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_DEPLOY_WITH_COMMON_SCRIPTS</b></td>
												<td>Copies scripts along when deploying / installing</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_TESTS</b></td>
												<td>Includes tests for core only</td>
											</tr>
											<tr>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
497
498
												<td><b>ITA_VACORE_VERSION_MAJOR</b></td>
												<td>VACore version major part, e.g. v2018</td>
499
500
											</tr>
											<tr>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
501
502
												<td><b>ITA_VACORE_VERSION_MINOR</b></td>
												<td>VACore version minor part, e.g. a,b,c,d ...</td>
503
504
											</tr>
											<tr>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
505
506
												<td><b>ITA_VACORE_DEFAULT_CONFIG_FILE_NAME</b></td>
												<td>Default VACore configuration file name (INI file)</td>
507
508
											</tr>
											<tr>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
509
510
												<td><b>ITA_VACORE_DEFAULT_DEBUG_LEVEL</b></td>
												<td>Default VACore debug level (0-5)</td>
511
512
											</tr>
											<tr>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
513
514
												<td><b>ITA_VACORE_MODULE_INTERFACE_ENABLED</b></td>
												<td>Build VACore with module interface</td>
515
516
											</tr>
											<tr>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
												<td><b>ITA_VACORE_NO_MODULE_INTERFACE_THROW_EXCEPTION</b></td>
												<td>Throw exception during module call attempt if VACore was build without module interface</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_EVENTS_ENABLED</b></td>
												<td>VACore event handling</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_MAX_NUM_SOUND_SOURCES</b></td>
												<td>VACore maximum number of sound sources ( 0 = unlimited )</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_MAX_NUM_SOUND_RECEIVERS</b></td>
												<td>VACore maximum number of sound receivers ( 0 = unlimited )</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_TTS_SIGNAL_SOURCE</b></td>
												<td>VACore with text-to-speech signal source support (requires TTSReleay)</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_BIG_DATA_DIR</b></td>
												<td>VACore big data dir with more files for auralization (will be added to search path)</td>
											</tr>
											<tr>
												<td><b>INSIDE_SCENE_DATA</b></td>
												<td>InsideSceneData folder for Inside scenes</td>
											</tr>
											<tr>
												<td><b>ITA_RAVEN_DATA_PATH</b></td>
												<td>RAVEN data base path (where to find models, HRTFs, materials etc. ...)</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_AUDIO_BACKEND_ASIO</b></td>
												<td>Build VACore with ASIO audio backend support</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_AUDIO_BACKEND_PORTAUDIO</b></td>
												<td>Build VACore with Portaudio audio backend support</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_AUDIO_BACKEND_DUMMY</b></td>
												<td>Build VACore with dummy audio backend support</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_RENDERER_AMBIENT_MIXER</b></td>
												<td>Build VACore with rendering module: ambient mixer</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_RENDERER_AMBISONICS_FREE_FIELD</b></td>
												<td>Build VACore with rendering module: ambisonics free-field</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_RENDERER_BINAURAL_FREE_FIELD</b></td>
												<td>Build VACore with rendering module: binaural free-field</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_RENDERER_BINAURAL_ARTIFICIAL_REVERB</b></td>
												<td>Build VACore with rendering module: artificial reverb</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_RENDERER_BINAURAL_ROOM_ACOUSTICS</b></td>
												<td>Build VACore with rendering module: room acoustics</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_RENDERER_BINAURAL_AIR_TRAFFIC_NOISE</b></td>
												<td>Build VACore with rendering module: air traffic noise (VATSS project)</td>
											</tr>
											<tr>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
585
586
												<td><b>ITA_VACORE_WITH_RENDERER_PROTOTYPE_FREE_FIELD</b></td>
												<td>Build VACore with rendering module: prototype free-field</td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_RENDERER_PROTOTYPE_DUMMY</b></td>
												<td>Build VACore with rendering module: prototype dummy</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_RENDERER_PROTOTYPE_HEARING_AID</b></td>
												<td>Build VACore with rendering module: prototype hearing aid (iCARE project)</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_RENDERER_PROTOTYPE_GENERIC_PATH</b></td>
												<td>Build VACore with rendering module: prototype generic path</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_RENDERER_VBAP_FREE_FIELD</b></td>
												<td>Build VACore with rendering module: vector-base amplitude panning free-field</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_REPRODUCTION_TALKTHROUGH</b></td>
												<td>Build VACore with reproduction module: talkthrough</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_REPRODUCTION_HEADPHONES</b></td>
												<td>Build VACore with reproduction module: headphones (equalization)</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_REPRODUCTION_AMBISONICS</b></td>
												<td>Build VACore with reproduction module: ambisonics (B-format decoder)</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_REPRODUCTION_BINAURAL_NCTC</b></td>
												<td>Build VACore with reproduction module: binaural N-CTC</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_REPRODUCTION_BINAURAL_MIXDOWN</b></td>
												<td>Build VACore with reproduction module: binaural mixdown</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_REPRODUCTION_AMBISONICS_BINAURAL_MIXDOWN</b></td>
												<td>Build VACore with reproduction module: ambisonics binaural mixdown (B-format decoder)</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_WITH_REPRODUCTION_MIXER_LOW_FREQUENCY</b></td>
												<td>Build VACore with reproduction module: low frequency (subwoofer) mixer</td>
											</tr>
											<tr>
												<td><b>ITA_VACORE_REPRODUCTION_NCTC_WITH_SWEET_SPOT_WIDENING</b></td>
												<td>Cross-talk cancellation sweet spot widening</td>
635
636
637
638
639
640
641
642
											</tr>
										</tbody>
										<tfoot>
											<tr>
												<td colspan="2">Table 7: VACore specific CMake configuration</td>
											</tr>
										</tfoot>
									</table>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
643

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
									
										<h5>VAServer (CLI server application)</h5>
										<p>
										</p>
								<div class="table-wrapper">
									<table class="alt">
										<thead>
											<tr>
												<th width="50%">Option</th>
												<th>Description</th>
											</tr>
										</thead>
										<tbody>
											<tr>
												<td><b>ITA_VASERVER_DEFAULT_SERVER_ADDRESS</b></td>
												<td>Default address for scripts and when running out of dev env (e.g. Visual Studio)</td>
											</tr>
											<tr>
												<td><b>ITA_VASERVER_DEFAULT_SERVER_PORT</b></td>
												<td>Default port for scripts and when running out of dev env (e.g. Visual Studio)</td>
											</tr>
											<tr>
												<td><b>ITA_VASERVER_DEPLOY_WITH_COMMON_SCRIPTS</b></td>
												<td>Include start scripts when installing / deploying</td>
											</tr>
											<tr>
												<td><b>ITA_VASERVER_VC_COMMAND_LINE_ARGUMENTS</b></td>
												<td>Command line arguments when starting server from within Visual Studio</td>
											</tr>
										</tbody>
										<tfoot>
											<tr>
												<td colspan="2">Table 8: VAServer specific CMake configuration</td>
											</tr>
										</tfoot>
									</table>

									
										<h5>Redstart (Qt GUI server application)</h5>
										<p>
										</p>
								<div class="table-wrapper">
									<table class="alt">
										<thead>
											<tr>
												<th width="50%">Option</th>
												<th>Description</th>
											</tr>
										</thead>
										<tbody>
											<tr>
												<td><b>ITA_REDSTART_DEFAULT_SERVER_ADDRESS</b></td>
												<td>Default address for scripts and when running out of dev env (e.g. Visual Studio)</td>
											</tr>
											<tr>
Dipl.-Ing. Jonas Stienen's avatar
WIP    
Dipl.-Ing. Jonas Stienen committed
699
												<td><b>ITA_REDSTART_DEFAULT_SERVER_PORT</b></td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
												<td>Default port for scripts and when running out of dev env (e.g. Visual Studio)</td>
											</tr>
											<tr>
												<td><b>ITA_REDSTART_DEPLOY_WITH_COMMON_SCRIPTS</b></td>
												<td>Include start scripts when installing / deploying</td>
											</tr>
											<tr>
												<td><b>ITA_REDSTART_VC_COMMAND_LINE_ARGUMENTS</b></td>
												<td>Command line arguments when starting Redstart from within Visual Studio</td>
											</tr>
										</tbody>
										<tfoot>
											<tr>
												<td colspan="2">Table 9: Redstart specific CMake configuration</td>
											</tr>
										</tfoot>
									</table>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
717

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
718
719
									</section>
									
720
721
722
									<section id="build_guide">
										
										<p>&nbsp;</p>
723
724
725
726
727
										
										<h3>Build guide</h3>
										
										<h4>CMake</h4>
										<p>
Dipl.-Ing. Jonas Stienen's avatar
WIP    
Dipl.-Ing. Jonas Stienen committed
728
										VA relies on <a href="http://cmake.org" target="_blank">CMake</a> to generate project files of your choice that will let you build the project in your preferred development environment. At least in theory. So far, we have only build VA using diverse Microsoft <b>Visual Studio</b> versions and MS compiler versions on <b>Windows platforms</b>, and on <b>Linux platforms</b> using <b>Makefiles</b> and <b>GCC</b>.<br />
729
										CMake is fine, but the <a href="http://www.itc.rwth-aachen.de/cms/IT-Center/Forschung-Projekte/Virtuelle-Realitaet/Infrastruktur/%7Efgmo/ViSTA-Virtual-Reality-Toolkit/" target="_blank">Vista VR Toolkit</a> practically improves it by its VistaCMakeCommon scripts. VA uses a lot of ViSTA functionality, and we have also adopted the build methods. It takes a little effort to set some paths to the environment, but it pays off especially of you want to add tests, benchmarks and your own applications that require the VA libraries (and its dependencies).
730
731
732
733
734
735
										</p>
										
										<h4>Where to start</h4>
										<p>
										Start with installing CMake, GIT and your development environment. Create an empty folder, let's call it <code>dev</code>, and let's assuming the absolute path is <code>C:/dev</code> or <code>/home/username/dev</code>.
										Switch to this folder, and clone <code>ViSTA</code> here using<br />
736
										<code>git clone https://devhub.vr.rwth-aachen.de/VR-Group/ViSTA</code><br />
737
738
										<br />
										Now, clone <code>VistaCMakeCommon</code>, the CMake extensions to ease finding dependencies and ViSTA-compatible projects.<br />
739
										<code>git clone https://devhub.vr.rwth-aachen.de/VR-Group/VistaCMakeCommon</code><br />
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
										<br />
										Additionally, add a folder that will contain all your dependencies and call it <code>ExternalLibs</code>.
										Your folder structure should look like this<br />
										<pre><code>- dev
  - ExternalLibs
  + ViSTA
  + VistaCMakeCommon</code></pre>
										<br />
										Finally, we have to add environment variables to point to the <code>VistaCMakeCommon</code> and <code>ExternalLibs</code> folder (otherwise CMake will not find these paths). For further information see the ViSTA documentation.<br />
										For Windows, edit the environment variables for this user (google it) and add the following variables (adjust for deviating paths and test if they are valid, otherwise nothing will work)<br />
										<br />
										<pre><code>VISTA_CMAKE_COMMON = C:/dev/VistaCMakeCommon
VISTA_EXTERNAL_LIBS = C:/dev/ExternalLibs</code></pre>
										<br />
										For Linux, add the <code>export VAR</code> lines e.g. to your <code>~/.bashrc</code> or find other ways using Google.<br /><br />
										<pre><code>export VISTA_CMAKE_COMMON = ~/dev/VistaCMakeCommon
export VISTA_EXTERNAL_LIBS = ~/dev/ExternalLibs</code></pre>
										
										Now follow <i>the ViSTA way</i> to build <code>ViSTA</code>, or more precisely the <code>VistaCoreLibs</code>, the libraries we need for VA. By default, <code>ViSTA</code> has no additional dependencies, and VA only requires those libraries and not - for example - the entire rendering kernel and the device drivers.<br />
										You build ViSTA by opening the <b>CMake GUI</b> and put in the source code path and the <code>build</code> directory. There is no strict rule how to name the build folder, but as good practice use <code>build</code> prefix followed by <code>win32-x64</code> for a Windows 64bit build, and add <code>.vc14</code> for the Visual C Compiler Version 14. Adopt for diverging version. For Linux, use <code>LINUX.X64</code>, and if preferred, use the cmake command line tool instead.<br />
										<br />
										As an example for a Windows machine with Visual Studio 2015 (using Visual Studio 14 compiler), this is the CMake setup<br />
										<br />
763
764
										<pre><code>Source: C:/dev/VistaCoreLibs
Build:  C:/dev/VistaCoreLibs/build_win32-x64.vc14</code></pre>
765
										<br />
Michael Kohnen's avatar
Michael Kohnen committed
766
										If you now configure and generate the project files, you can open the project solution and build the <code>VistaCoreLibs</code> (or run <code>make</code> on Linux). CMake will automatically find <code>VistaCMakeCommon</code> and from now on also knows where to look for <code>VistaCoreLibs</code> libraries, if you want to add a dependency to it in your project (like VA does).
767
768
										</p>
										
769
770
771
772
										<blockquote>Notes on building <b>static libraries</b>: disable the <code>BUILD_SHARED_LIBS</code> flag and disable ViSTA drivers and demos (they are not required for VA).
										<br />In the process of building VA, activate <code>ITA_VISTA_BUILD_STATIC</code>, <code>ITA_VA_BUILD_STATIC</code>, <code>ITA_CORE_LIBS_BUILD_STATIC</code> and so on.
										</blockquote>
										
773
774
775
776
777
778
779
780
781
782
783
784
785
										<h4>Compiling VA base and network library</h4>
										<p>
										Now that you have set up <code>ViSTA</code>, we can proceed with building VA. Clone <code>VA</code> into the <code>dev</code> folder above, and use the <code>--recursive</code> flag to also clone the submodules:<br />
										<code>git clone --recursive http://git.rwth-aachen.de/ita/VA</code><br />
										<br />
										Run CMake with the following parameters:<br />
										<pre><code>Source: C:/dev/VA
Build:  C:/dev/VA/build_win32-x64.vc14</code></pre>
										Make sure, that no further settings are activated. For now we want to build <code>VABase</code> and <code>VANet</code>, which depend on <code>VistaCoreLibs</code> only. As usual in CMake: configure, generate and open the project to build it (or run <code>make</code> on Linux).
										</p>
										
										<h4>Compiling the binding(s)</h4>
										<p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
786
										The base libraries are ready, now continue with bindings for Matlab, Lua, C# and/or Python. C# has no further dependency, but for the others you will have to provide third party libraries. You can activate the respective binding in CMake (Linux users use <code>ccmake</code>) as described in the section above.
787
										</p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
788
										
789
790
										<h5>VAPython</h5>
										<p>
Michael Kohnen's avatar
Michael Kohnen committed
791
										To build a <code>Python 3.x</code> extension using Windows, install Python and the Python build sets that come with Visual Studio. You can compile the VAPython project from within Visual Studio, but the resulting library will not be used - it is only to conveniently code in Visual Studio and refactor efficiently. Instead, the final Python VA extension will be generated by a call to </code>distutils</code>, that will generate the compatible library. It is highly recommended to use static linking to VA and further dependencies.
792
										</p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
793
										
794
795
										<h5>VAMatlab</h5>
										<p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
796
797
798
799
800
801
802
803
										To build a <code>Matlab</code> executable (mex), you need a Matlab installation ad the corresponding headers and libraries. You can compile the Matlab extension directly out of your development environment, however currently only Visual Studio has been tested.<br />
										To generate the <code>itaVA</code> class to easy using the VAMatlab executable, currently a manual step is required because auto-generation calling Matlab out of the development environment is still under construction. To create the class, run the <code>itaVA_build.m</code> script in Matlab once. The class will be included into the deployment and can be found in the <code>matlab</code> folder (along with some examples).
										</p>
										
										
										<h4>VACore</h4>
										<p>
										The core of VA is the most challenging part. It requires the entire dependency tree and also pulls in the <code>ITACoreLibs</code> libraries. Please note the dependency table in the sections above. Provide the dependencies e.g. to <code>fftw3</code>, <code>libsndfile</code>, <code>libsamplerate</code> and others. Before starting, configure the <code>ITACoreLibs</code> as described below.
804
										</p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
805
806
807
										
										<h5>ITACoreLibs</h5>
										<p>
808
809
										Obtain the source code using <pre><code>git clone --recursive http://git.rwth-aachen.de/ita/ITACoreLibs</code></pre>
										Configure the <code>ITACoreLibs</code> using CMake. It is recommended to use static linking to avoid mix ups with other library versions (that potentially have the same name). Please activate the following switches:<br /><br />
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
810
811
812
813
814
815
816
817
818
819
820
821
822
823
										
<pre><code>ITA_BASE_WITH_CONFIG_OLD_IMPL
ITA_BASE_WITH_REGULAR_EXPRESSIONS
ITA_BASE_WITH_SAMPLERATE
ITA_BASE_WITH_SNDFILE
ITA_BASE_WITH_OLD_ATOMICS (only required for RAVEN backend)
ITA_BASE_WITH_OLD_RAVEN_OPS (only required for RAVEN backend)
ITA_CTC_WITH_N_CTC
ITA_DATA_SOURCES_WITH_INTEGRATED_ASIO (optional, recommended for Windows users)
ITA_DATA_SOURCES_WITH_INTEGRATED_PORTAUDIO
ITA_DATA_SOURCES_WITH_INTEGRATED_JACK (optional, for Linux users only)
ITA_DATA_SOURCES_WITH_NET_AUDIO
ITA_FFT_WITH_FFTW3 (recommended)</code></pre>
										Now generate and build the project to make it available for the next step.
824
										</p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
825
826
827
828
829
										
										<h5>VACore</h5>
										<p>
										Activate the core flag in CMake and configure <code>VA</code>.
										<pre><code>ITA_VA_WITH_CORE</code></pre>
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
										Now, a lot of further configuration options will appear, which might have to be altered to fit your needs. However, the default setting should be sufficient to begin. It will include the most important rendering and reproduction modules that do not depend on further projects, like room acoustics and <code>RAVEN</code> or outdoor noise renderers using <code>ITAGeometricalAcoustics</code>. See section above for more details.<br />
										After generating, the <code>VACore</code> project appears in your development environment.
										</p>
										
										
										<h4>VAServer</h4>
										<p>
										Activate the server app flag in CMake and configure <code>VA</code>.
										<pre><code>ITA_VA_WITH_SERVER_APP</code></pre>										
										After generating, the <code>VAServer</code> project appears in your development environment.
										</p>
										
										
										<h4>Redstart VA GUI</h4>
										<p>
										Redstart, the graphical user interface application for VA, uses <a href="http://qt.io" target="_blank">Qt5</a>. Obtain and install a current version first. Also, because the <code>ITAAcousticVisualization</code> project is required for some widgets, obtain the current <code>VTK</code> source code and build it with <code>Qt5</code> support activated (it is also based on CMake).
										</p>
										
										<h5>ITAAcousticVisualization</h5>
										<p>
										Obtain the source code using <pre><code>git clone --recursive http://git.rwth-aachen.de/ita/ITAAcousticVisualization</code></pre>
										Configure, generate and build <code>ITAAcousticVisualization</code> using CMake.
										</p>
										
										<h5>Redstart</h5>
										<p>
										Now, activate the Redstart app flag in CMake and configure <code>VA</code>.
										<pre><code>ITA_VA_WITH_REDSTART_APP</code></pre>										
										After generating, the <code>Redstart</code> project appears in your development environment.
										</p>
										
										
										<h4>Special features</h4>
										<p>
										VA provides some special features.
										</p>
										
										<h5>Rendering module with room acoustics simulation backend</h5>
										<p>
Dipl.-Ing. Jonas Stienen's avatar
WIP    
Dipl.-Ing. Jonas Stienen committed
869
										This module requires <code>RAVEN</code>, which is copyright protected and not available for the public. Please <a href="disclaimer.html">contact us</a> if you are working for a university and want to use it for academic purposes, only. If you have been granted access, obtain the source code using <pre><code>git clone --recursive http://git.rwth-aachen.de/ita/RAVEN</code></pre>
870
871
872
873
874
875
876
877
878
879
880
881
										Configure, generate and build <code>RAVEN</code> using CMake.<br />
										Now you can activate the room acoustics rendering module<br /><br />
										<pre><code>ITA_VACORE_WITH_RENDERER_BINAURAL_ROOM_ACOUSTICS</code></pre>										
										</p>
										
										<h5>Rendering module with outdoor noise simulation</h5>
										<p>
										This module requires <code>ITAGeometricalAcoustics</code>. Obtain the source code using <pre><code>git clone --recursive http://git.rwth-aachen.de/ita/ITAGeometricalAcoustics</code></pre>
										Configure, generate and build <code>ITAGeometricalAcoustics</code> using CMake.<br />
										Now you can activate the outdoor noise acoustics rendering module (under construction)<br /><br />
										<pre><code>ITA_VACORE_WITH_RENDERER_BINAURAL_OUTDOOR_NOISE</code></pre>										
										</p>
882
883
884
														
									<section id="build_guide_unity">
									<p>&nbsp;</p>
885
886
887
										<h5>Unity</h5>
										<p>
										VA provides <b>C# scripts</b> for <a href="http://www.unity3d.org" target="_blank">Unity</a>. You can connect Unity GameObjects with VA sound sources, sound receivers, signal sources, auralization modes, etc. Also, some basic interfaces to control the core (gains, muting) as well es special scripts for rendering and reproduction modules exist.<br /><br />
Michael Kohnen's avatar
Michael Kohnen committed
888
										Either copy the entire scripts from <code>VAUnity</code> into your Assets folder or clone it directly there using <pre><code>git clone http://git.rwth-aachen.de/ita/VAUnity</code></pre>
889
										All unity scripts require the <b>VA C# class</b>, which uses a C++ wrapping library called <code>VANetCSWrapper</code> together with the C# class <code>VACS.cs</code>, which can be found in the <code>VACS</code> binding project. To create it activate the C# binding<br /><br />
Dipl.-Ing. Jonas Stienen's avatar
WIP    
Dipl.-Ing. Jonas Stienen committed
890
										<pre><code>ITA_VA_WITH_BINDING_CS</code></pre>
891
892
										Make the <code>VANetCSWrapper</code> shared library (.dll on Windows) available in your Assets folder. Unity usually expects external libraries under the <code>Plugins</code> folder. Note, that if you build shared <code>VA</code> and <code>VistaCoreLibs</code> libraries they have to be placed next to the <code>VANetCSWrapper</code> library. The list usually comprises <code>VABase VANet VANetCSWrapper VistaAspects VistaBase VistaInterProcComm</code>. For convenience, these files are copied into the <code>csharp</code> folder of the deploy directory, which is created when building the <code>INSTALL</code> target (or <code>INSTALL</code> project in Visual Studio).<br /><br />
										You will find this <code>csharp</code> folder in all VA packages that were build with the C# binding - just drag'n'drop it into the Assets folder (or in a subfolder commonly called <code>Plugins</code>). For further details, see the corresponding <code>README</code> files of <code>VAUnity</code> (<a href="http://git.rwth-aachen.de/ita/VAUnity" target="_blank">open in repository</a>).
893
894
										<br /><br />
										VA also provides <b>extensions for Unity</b> that require additional assets like <b>VRTK</b> or <b>SteamVR</b>. They have been placed into <code>VAUnityExtensions</code> to strictly separate the <code>VAUnity</code> C# scripts, which only require VA. If you are planning to use Unity with HMDs and interactive input devices, check out the VA 3D menus for the Vive that lets you control VA in Virtual Reality. You will also find templates for multi-modal experiments that can be used for alternate forced choice tests (3-AFC tests), which are common for quality assessments and perceptional threshold evaluations.
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
895
										</p>
896
										</section>
897
898
899
										
										<h4>Extending VA</h4>
										<p>
Dipl.-Ing. Jonas Stienen's avatar
WIP    
Dipl.-Ing. Jonas Stienen committed
900
										You can extend VA to create modules for your purpose. Best practice is to derive a class or method from an existing implementation and modify it accordingly. Wherever possible, use generic methods (<code>Set..Parameters()</code> <code>Get..Parameters()</code> <code>Create...FromParameters()</code>) instead of extending the VA interface. It will make your life easier, because repercussions of new virtual interface methods are significant. Changes to the entire VA collection will be necessary, and a slight mistake will lead to a lot of trouble that is difficult to debug. Furthermore, choose a module that is closest to what you are planning and use refactoring tools to detect where and how to register your new class in the core as a signal source, a rendering module or a reproduction module. If you want to start from scratch, look out for <b>dummy</b> classes that only implement required virtual methods.
901
902
903
										</p>
										
										
904
905
906
907
908
909
										<h4>Wrap up</h4>
										<p>
										If you have come this far, your development environment folder structure will look similar to this:
										<pre><code>- dev
  + ExternalLibs
  + ITAAcousticVisualization
910
    - ITAQtWidgets
911
  + ITAGeometricalAcoustics (optional)
912
913
    - ITAGeo
	- ITADiffraction
914
  + ITACoreLibs
915
916
917
918
919
920
    - ITABase
	- ITAConvolution
	- ITACTC
	- ITADataSources
	- ITAFFT
	- ITA
921
922
  + RAVEN (optional, protected)
  + VA
923
924
925
926
927
928
929
930
931
932
    - Redstart
    - VABase
	- VACore
	- VACS
	- VAMatlab
	- VANet
	- VAPython
	- VAServer
	- VAUnity
	- VAUnityExtensions
933
  + ViSTA
934
    - VistaCoreLibs
935
936
  + VistaCMakeCommon</code></pre>
										</p>
937
938
939
940
941
942
										<!--
										<p>
										CMake GUI settings will look similar to this (Windows)
										<img src="img/va_cmake_config.png" />
										</p>
										-->
943
944
945
946
947
										
										<h4>Get help</h4>
										<p>
										If you are stuck, get help from the <a href="help.html#community">community</a>.
										</p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
948
										
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
949
950
									</section>

951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
									
									<section id="repositories">
										
										<p>&nbsp;</p>
										
										<h3>Code repositories</h3>
										<p>The ITA and VA repositories link to submodules. Use <code>git clone --recursive <i>URL</i></code> to include submodule contents, too. Also, because the referenced submodules are <i>detached from HEAD</i>, it is recommended to use the <code>foreach</code> statement to switch branches and update code. Common calls are
<pre><code>git submodule foreach git status
git submodule foreach git checkout master
git submodule foreach git branch
git submodule foreach git pull</code></pre>
										
								<div class="table-wrapper">
									<table class="alt">
										<thead>
											<tr>
												<th width="20%">Name</th>
												<th>URL</th>
												<th width="10%">Webinterface</th>
											</tr>
										</thead>
										<tbody>
											<tr>
												<td>VA</td>
												<td><code>https://git.rwth-aachen.de/ita/VA.git</code></td>
												<td><a href="https://git.rwth-aachen.de/ita/VA" target="_blank">GitLab</a></td>
											</tr>
											<tr>
												<td>ViSTA</td>
980
981
												<td><code>https://devhub.vr.rwth-aachen.de/VR-Group/ViSTA.git</code></td>
												<td><a href="https://devhub.vr.rwth-aachen.de/VR-Group/ViSTA" target="_blank">GitLab</a></td>
982
983
											</tr>
											<tr>
984
												<td>VistaCMakeCommon</td>
985
986
												<td><code>https://devhub.vr.rwth-aachen.de/VR-Group/VistaCMakeCommon.git</code></td>
												<td><a href="https://devhub.vr.rwth-aachen.de/VR-Group/VistaCMakeCommon" target="_blank">GitLab</a></td>
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
											</tr>
											<tr>
												<td>ITACoreLibs</td>
												<td><code>https://git.rwth-aachen.de/ita/ITACoreLibs.git</code></td>
												<td><a href="https://git.rwth-aachen.de/ita/ITACoreLibs" target="_blank">GitLab</a></td>
											</tr>
											<tr>
												<td>ITAGeometricalAcoustics</td>
												<td><code>https://git.rwth-aachen.de/ita/ITAGeometricalAcoustics.git</code></td>
												<td><a href="https://git.rwth-aachen.de/ita/ITAGeometricalAcoustics" target="_blank">GitLab</a></td>
											</tr>
											<tr>
												<td>ITAAcousticVisualization</td>
												<td><code>https://git.rwth-aachen.de/ita/ITAAcousticVisualization.git</code></td>
												<td><a href="https://git.rwth-aachen.de/ita/ITAAcousticVisualization" target="_blank">GitLab</a></td>
											</tr>
1003
1004
1005
1006
1007
											<tr>
												<td>RAVEN (non-public)</td>
												<td><code>https://git.rwth-aachen.de/ita/RAVEN.git</code></td>
												<td><a href="https://git.rwth-aachen.de/ita/RAVEN" target="_blank">GitLab</a></td>
											</tr>
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
										</tbody>
										<tfoot>
											<tr>
												<td colspan="3">Table 1: open access GIT repositories</td>
											</tr>
										</tfoot>
									</table>
								</div>
								
										
										<h4>Get them all</h4>
										<p>
										<pre><code>git clone --recursive https://git.rwth-aachen.de/ita/VA
git clone --recursive https://git.rwth-aachen.de/ita/ITACoreLibs
git clone --recursive https://git.rwth-aachen.de/ita/ITAGeometricalAcoustics
git clone --recursive https://git.rwth-aachen.de/ita/ITAAcousticVisualization
1024
1025
git clone https://devhub.vr.rwth-aachen.de/VR-Group/ViSTA
git clone https://devhub.vr.rwth-aachen.de/VR-Group/VistaCMakeCommon</code></pre>
1026
1027
</p>
									</section>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
					</div>
				</div>

			<!-- Footer -->
				<footer id="footer" style="background-color:black">
					<ul class="icons">
						<li><a href="http://www.akustik.rwth-aachen.de" class="icon alt fa-globe"><span class="label">ITA website</span></a></li>
						<li><a href="http://blog.rwth-aachen.de/akustik/category/va" class="icon alt fa-comments-o"><span class="label">Akustik-Blog</span></a></li>
						<li><a href="http://git.rwth-aachen.de/ita" class="icon alt fa-github"><span class="label">ITA GitLab</span></a></li>
					</ul>
					
					<span class="image"><img src="images/rwth_ita_akustik_en_institute_weiss_rgb_blackbg_small.jpg" alt="Institute of Technical Acoustics (ITA), RWTH Aachen University" /></span>
					
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1041
					<ul class="copyright">&copy; 2017-2018 Institute of Technical Acoustics (ITA), RWTH Aachen University</ul>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
				</footer>


		</div>

		<!-- Scripts -->
			<script src="assets/js/jquery.min.js"></script>
			<script src="assets/js/jquery.scrolly.min.js"></script>
			<script src="assets/js/jquery.dropotron.min.js"></script>
			<script src="assets/js/jquery.scrollex.min.js"></script>
			<script src="assets/js/skel.min.js"></script>
			<script src="assets/js/util.js"></script>
			<!--[if lte IE 8]><script src="assets/js/ie/respond.min.js"></script><![endif]-->
			<script src="assets/js/main.js"></script>

	</body>
</html>