developers.html 50.6 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
					<h1 id="logo"><a href="index.html">Home</a></h1>
23 24
					<nav id="nav">
						<ul>
25 26 27 28 29 30 31 32 33 34 35 36 37 38
							<li><a href="overview.html">Overview</a></li>
							<li><a href="download.html">Download</a></li>
							<li><a href="documentation.html">Documentation</a>
								<ul>
									<li><a href="documentation.html#configuration">Configuration</a></li>
									<li><a href="documentation.html#control">Control</a></li>
									<li><a href="documentation.html#scene_handling">Scene handling</a></li>
									<li><a href="documentation.html#rendering">Audio rendering</a></li>
									<li><a href="documentation.html#reproduction">Audio reproduction</a></li>
									<li><a href="documentation.html#tracking">Tracking</a></li>
									<li><a href="documentation.html#simulation_recording">Simulation and recording</a></li>
									<li><a href="documentation.html#examples">Examples</a></li>
								</ul>
							</li>
39
							<li>
40
								<a href="support.html">Support</a>
41
								<ul>
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
									<li><a href="support.html#faq">FAQ</a></li>
									<li><a href="support.html#issue_tracker">Issue tracker</a></li>
									<li><a href="support.html#community">Community</a></li>
									<li><a href="support.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>
64 65 66 67 68 69
								</ul>
							</li>
							<li><a href="legal.html">Legal notice</a></li>
						</ul>
					</nav>
				</header>
70
					
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
71 72 73 74 75 76 77



			<!-- Main -->
				<div id="main" class="wrapper style1">
					<div class="container">
						<header class="major">
78 79
							<h2>Developer section</h2>
							<p>How to build and extend VA </p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
80 81 82
						</header>

								<!-- Content -->
83
									<section id="preface">
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
84
										
85
										<h3>Preface</h3>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
86
										<p>
87
										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 />
88 89 90
										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>
91
										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 offers options to control implementation details of the core.								
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
92 93 94 95 96 97 98
										</p>
										
									</section>
									
									
									<section id="api">
									
99
										<p>&nbsp;</p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
100 101
										<h3>C++ code documentation</h3>
										<p>
102
										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="documentation.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
103
										</p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
104
										
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
105 106
										<h4>C++ API documentation (generated with Doxygen)</h4>
										<ul>
107 108
											<a href="resources/v2019a/doc/html/index.html">Virtual Acoustics C++ API v2019a</a> (current version)<br />
											<a href="resources/v2018b/doc/html/index.html">Virtual Acoustics C++ API v2018b</a><br />
109
											<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
110 111 112
										</ul>
									</section>
									
113 114 115 116 117 118 119
									<section id="dependencies">
									
										
										<p>&nbsp;</p>
								
										<h3>Dependencies</h3>
										
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
120 121
										<h4>Third party dependencies</h4>
										<p>
122
										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 resolved. 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
123 124
										</p>
										
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
125 126 127 128
								<div class="table-wrapper">
									<table class="alt">
										<thead>
											<tr>
129 130
												<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
131 132 133 134 135 136 137 138 139 140 141 142
												<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>
143
												<td>VistaCoreLibs <i>(Aspects, Base, InterProcComm)</i></td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
144 145 146
											</tr>
											<tr>
												<td><b>VALua</b></td>
147 148
												<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
149 150 151
											</tr>
											<tr>
												<td><b>VAMatlab</b></td>
152 153
												<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
154 155 156
											</tr>
											<tr>
												<td><b>VACS (C#)</b></td>
157 158
												<td>VABase <br /> VANet</td>
												<td>VistaCoreLibs <i>(Aspects, Base, InterProcComm)</i></td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
159 160 161
											</tr>
											<tr>
												<td><b>VAPython</b></td>
162 163
												<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
164 165 166 167
											</tr>
											<tr>
												<td><b>VACore</b></td>
												<td>VABase</td>
168 169 170 171 172 173 174 175 176 177 178
												<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
179 180 181 182 183 184 185 186 187 188 189
											</tr>
										</tbody>
										<tfoot>
											<tr>
												<td colspan="3">Table 1: VA dependency tree</td>
											</tr>
										</tfoot>
									</table>
								</div>
										
										<p>
190
										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 />
191
										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
192 193 194 195 196
</p>										
								<div class="table-wrapper">
									<table class="alt">
										<thead>
											<tr>
197 198
												<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
199 200 201 202 203
												<th>External dependencies (<i>components</i>)</th>
											</tr>
										</thead>
										<tbody>
											<tr>
204
												<td><b>ITABase</b> <br /> <i>(ITACoreLibs component)</i></td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
205
												<td><i>none</i></td>
206
												<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
207 208
											</tr>
											<tr>
209
												<td><b>ITAFFT</b> <br /> <i>(ITACoreLibs component)</i></td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
210
												<td>ITABase</td>
211
												<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
212 213
											</tr>
											<tr>
214
												<td><b>ITADataSources</b> <br /> <i>(ITACoreLibs component)</i></td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
215 216 217 218
												<td>ITABase</td>
												<td>VistaCoreLibs <i>(Aspects, Base, InterProcComm)</i> <br /> ASIO [optional, but recommended] <br /> Portaudio [optional]<br /> JACK [optional] </td>
											</tr>
											<tr>
219 220
												<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
221 222 223
												<td>TBB</td>
											</tr>
											<tr>
224 225 226
												<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
227 228
											</tr>
											<tr>
229 230
												<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
231 232
												<td>TBB <br /> SPLINE</td>
											</tr>
233 234 235 236 237
											<tr>
												<td><b>ITASampler</b> <br /> <i>(ITACoreLibs component)</i></td>
												<td>ITABase <br /> ITADataSources</td>
												<td>none</td>
											</tr>
238 239 240 241 242 243
											<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>
244 245 246 247 248 249
												<td><b>ITAPropagationPathSim</b> <br /> <i>(ITAGeometricalAcoustics component)</i></td>
												<td>ITABase <br /> ITAGeo</td>
												<td><i>none</i></td>
											</tr>
											<tr>
												<td><b>ITAPropagationModels</b> <br /> <i>(ITAGeometricalAcoustics component)</i></td>
250 251 252 253 254 255
												<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>
256
												<td>VTK [recommended with Qt5 support]</td>
257 258 259 260
											</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>
261
												<td>Qt5 <br /> VTK with Qt5 support</td>
262
											</tr>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
263 264 265
										</tbody>
										<tfoot>
											<tr>
266
												<td colspan="3">Table 2: ITA projects dependency tree</td>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
267 268 269 270 271
											</tr>
										</tfoot>
									</table>
								</div>
								
272 273 274
									</section>
								
									<section id="configuration">
275
									
276 277 278
										<p>&nbsp;</p>
										<h3>Build configurations</h3>
										
279 280
										<h4>VA configuration options</h4>
										<p>
281
										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.
282 283
										<br />
										<br />
284
										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.
285 286 287 288 289 290 291 292 293
										</p>
										
										<h5>VA (general)</h5>
										<p>
										</p>
								<div class="table-wrapper">
									<table class="alt">
										<thead>
											<tr>
294 295
												<th width="50%">Option</th>
												<th>Description</th>
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 347 348 349
											</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>
350
												<td colspan="2">Table 3: General VA CMake configuration</td>
351 352 353 354 355 356 357
											</tr>
										</tfoot>
									</table>
									
									
										<h5>VANet (network library settings)</h5>
										<p>
358
										</p>
359 360 361 362
								<div class="table-wrapper">
									<table class="alt">
										<thead>
											<tr>
363 364
												<th width="50%">Option</th>
												<th>Description</th>
365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390
											</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>
391
										
392 393 394 395 396 397 398 399 400
									
									
										<h5>VAMatlab (Matlab binding)</h5>
										<p>
										</p>
								<div class="table-wrapper">
									<table class="alt">
										<thead>
											<tr>
401 402
												<th width="50%">Option</th>
												<th>Description</th>
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 446 447 448
											</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>
449 450
												<th width="50%">Option</th>
												<th>Description</th>
451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477
											</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>
478 479
												<th width="50%">Option</th>
												<th>Description</th>
480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499
											</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>
500 501
												<td><b>ITA_VACORE_VERSION_MAJOR</b></td>
												<td>VACore version major part, e.g. v2018</td>
502 503
											</tr>
											<tr>
504 505
												<td><b>ITA_VACORE_VERSION_MINOR</b></td>
												<td>VACore version minor part, e.g. a,b,c,d ...</td>
506 507
											</tr>
											<tr>
508 509
												<td><b>ITA_VACORE_DEFAULT_CONFIG_FILE_NAME</b></td>
												<td>Default VACore configuration file name (INI file)</td>
510 511
											</tr>
											<tr>
512 513
												<td><b>ITA_VACORE_DEFAULT_DEBUG_LEVEL</b></td>
												<td>Default VACore debug level (0-5)</td>
514 515
											</tr>
											<tr>
516 517
												<td><b>ITA_VACORE_MODULE_INTERFACE_ENABLED</b></td>
												<td>Build VACore with module interface</td>
518 519
											</tr>
											<tr>
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 585 586 587
												<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
588 589
												<td><b>ITA_VACORE_WITH_RENDERER_PROTOTYPE_FREE_FIELD</b></td>
												<td>Build VACore with rendering module: prototype free-field</td>
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 635 636 637
											</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>
638 639 640 641 642 643 644 645
											</tr>
										</tbody>
										<tfoot>
											<tr>
												<td colspan="2">Table 7: VACore specific CMake configuration</td>
											</tr>
										</tfoot>
									</table>
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 699 700 701
									
										<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
702
												<td><b>ITA_REDSTART_DEFAULT_SERVER_PORT</b></td>
703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719
												<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>
720

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
721 722
									</section>
									
723 724 725
									<section id="build_guide">
										
										<p>&nbsp;</p>
726 727 728 729 730
										
										<h3>Build guide</h3>
										
										<h4>CMake</h4>
										<p>
Dipl.-Ing. Jonas Stienen's avatar
WIP  
Dipl.-Ing. Jonas Stienen committed
731
										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 />
732
										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).
733 734 735 736 737 738
										</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 />
739
										<code>git clone https://devhub.vr.rwth-aachen.de/VR-Group/ViSTA</code><br />
740 741
										<br />
										Now, clone <code>VistaCMakeCommon</code>, the CMake extensions to ease finding dependencies and ViSTA-compatible projects.<br />
742
										<code>git clone https://devhub.vr.rwth-aachen.de/VR-Group/VistaCMakeCommon</code><br />
743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765
										<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 />
766 767
										<pre><code>Source: C:/dev/VistaCoreLibs
Build:  C:/dev/VistaCoreLibs/build_win32-x64.vc14</code></pre>
768
										<br />
769
										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).
770 771
										</p>
										
772 773 774 775
										<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>
										
776 777 778 779 780 781 782 783 784 785 786 787 788
										<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
789
										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.
790
										</p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
791
										
792 793
										<h5>VAPython</h5>
										<p>
794
										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.
795
										</p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
796
										
797 798
										<h5>VAMatlab</h5>
										<p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
799
										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 />
800
										To generate the <code>VA</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>VA_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).
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
801 802 803 804 805 806
										</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.
807
										</p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
808 809 810
										
										<h5>ITACoreLibs</h5>
										<p>
811 812
										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
813 814 815 816 817 818 819 820 821 822 823 824 825 826
										
<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.
827
										</p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
828 829 830 831 832
										
										<h5>VACore</h5>
										<p>
										Activate the core flag in CMake and configure <code>VA</code>.
										<pre><code>ITA_VA_WITH_CORE</code></pre>
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 869 870 871
										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
872
										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>
873 874 875 876 877 878 879 880 881 882 883 884
										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>
885 886 887
														
									<section id="build_guide_unity">
									<p>&nbsp;</p>
888 889 890
										<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 />
891
										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>
892
										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
893
										<pre><code>ITA_VA_WITH_BINDING_CS</code></pre>
894 895
										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>).
896 897
										<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
898
										</p>
899
										</section>
900 901 902
										
										<h4>Extending VA</h4>
										<p>
Dipl.-Ing. Jonas Stienen's avatar
WIP  
Dipl.-Ing. Jonas Stienen committed
903
										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.
904 905 906
										</p>
										
										
907 908 909 910 911 912
										<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
913
    - ITAQtWidgets
914
  + ITAGeometricalAcoustics (optional)
915
    - ITAGeo
916 917
    - ITAPropagationPathSim
    - ITAPropagationModels
918
  + ITACoreLibs
919
    - ITABase
920 921 922 923 924
    - ITAConvolution
    - ITACTC
    - ITADataSources
    - ITAFFT
    - ITASampler
925 926
  + RAVEN (optional, protected)
  + VA
927 928
    - Redstart
    - VABase
929 930 931 932 933 934 935 936
    - VACore
    - VACS
    - VAMatlab
    - VANet
    - VAPython
    - VAServer
    - VAUnity
    - VAUnityExtensions
937
  + ViSTA
938
    - VistaCoreLibs
939 940
  + VistaCMakeCommon</code></pre>
										</p>
941 942 943 944 945 946
										<!--
										<p>
										CMake GUI settings will look similar to this (Windows)
										<img src="img/va_cmake_config.png" />
										</p>
										-->
947 948 949
										
										<h4>Get help</h4>
										<p>
950
										If you are stuck, get help from the <a href="support.html#community">community</a>.
951
										</p>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
952
										
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
953 954
									</section>

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 980 981 982 983
									
									<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>
984 985
												<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>
986 987
											</tr>
											<tr>
988
												<td>VistaCMakeCommon</td>
989 990
												<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>
991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006
											</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>
1007 1008 1009 1010 1011
											<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>
1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027
										</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
1028 1029
git clone https://devhub.vr.rwth-aachen.de/VR-Group/ViSTA
git clone https://devhub.vr.rwth-aachen.de/VR-Group/VistaCMakeCommon</code></pre>
1030 1031
</p>
									</section>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044
					</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>
					
1045
					<ul class="copyright">&copy; 2017-2019 Institute of Technical Acoustics (ITA), RWTH Aachen University</ul>
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062
				</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>