Merge branch 'loek/research'

6 files changed, 108 insertions, 36 deletions

diff --git a/glossary.bib b/glossary.bib
index 8bf48ac..fda634f 100644
--- a/glossary.bib
+++ b/glossary.bib
@@ -46,3 +46,9 @@
 	long = {definition of done},
 }
 
+@abbreviation{poc,
+	short = {POC},
+	long = {proof-of-concept},
+}
+
+
diff --git a/projdoc.cls b/projdoc.cls
index ee94835..16b1790 100644
--- a/projdoc.cls
+++ b/projdoc.cls
@@ -397,3 +397,6 @@
 }
 \makeatother
 
+% missing reference marker
+\def\mref{\textsuperscript{\textit{\,ref?}}}
+
diff --git a/reqs.toml b/reqs.toml
index 35c7a96..ed0b451 100644
--- a/reqs.toml
+++ b/reqs.toml
@@ -62,7 +62,9 @@ The public audio \gls{api} allows the game programmer to control the volume of
 audio samples.
 '''
 
-[aux:license]
+# TODO: audio encoding support?
+
+[lib:license]
 type = 'system'
 priority = 'must'
 description = '''
@@ -70,3 +72,15 @@ External libraries must have a license that is MIT-compatible, or one that
 allows linking against MIT code.
 '''
 
+[lib:platform]
+type = 'system'
+priority = 'must'
+description = '''
+External libraries must have cross-platform support for at least Linux and
+Windows.
+'''
+
+# TODO: library popularity as quality factor?
+# TODO: library documentation as quality factor?
+# TODO: modularity over less libraries? (i.e. why don't we just SDL2 everything?)
+
diff --git a/research.tex b/research.tex
index 1f55d70..228f3ac 100644
--- a/research.tex
+++ b/research.tex
@@ -354,45 +354,50 @@ for audio some options could be: FMOD, Wwise, or iirKlang
 
 \subsection{Conclusion}
 
-% TODO: this entire section
 \section{Audio}
 
-% should audio research be scoped down to SDL2 (if that's what we're going with) or
-% standalone libraries only (for modularity?).
-
-The game engine is required to have an audio system with support for playing multiple
-audio streams (i.e.~tracks or samples) simultaniously. Since writing a custom live
-audio mixing engine is outside the scope of this project, this section compares
-various standalone audio engines that could be used in the engine.
+The game engine is required to have an audio system
+\autocite[\ref{req:audio}]{crepe:requirements}. Since writing a custom real-time
+audio mixing engine is outside the scope of this project\mref, this section compares
+various standalone audio libraries for suitability in the engine.
+
+\subsection{Libraries}
+\label{sec:audio:libs}
+
+After searching for libraries (search terms: `dynamic/adaptive audio', `real-time
+audio', `audio library', `game audio engine'), several libraries were found. These
+libraries were checked against the audio engine requirements
+\autocite{crepe:requirements} and then tested by writing the same benchmark-style
+\gls{poc} using the remaining qualifying libraries:\noparbreak
+\begin{enumerate}
+	\item Load a background track (Ogg Vorbis)
+	\item Load three short samples (WAV)
+	\item Start the background track
+	\item Play each sample sequentially while pausing and resuming the background track
+	\item Play all samples simultaniously
+	\item Stop all audio and exit
+\end{enumerate}
+
+Of these libraries the following were determined to be unsuitable for use in this
+project due to various reasons:\noparbreak
+\begin{description}
+	\item[FMOD \autocite{lib:fmod}] Is proprietary (violates \cref{req:lib:license})
+	\item[PortAudio \autocite{lib:portaudio}] Does not handle mixing
+	\item[miniaudio \autocite{lib:miniaudio}] With finished \gls{poc}, but dropped due
+		to very limited codec support (WAV, MP3 and FLAC only); Also does not have an
+		\gls{api} reference (only programming manual)
+	\item[YSE \autocite{lib:yse}] Attempted to write \gls{poc}, but CMake configuration
+		in repository is broken; This project seems to have been abandoned
+\end{description}
 
-% TODO: requirements first!
+The only library that remained after these tests is SoLoud \autocite{lib:soloud}. It
+is Zlib/LibPng licensed and provides a high-level object-oriented C++ \gls{api}.
 
-% REQ ~ is cross-platform
-% REQ ~ supports multiple audio formats (TODO: which)
-% REQ ~ supports simultanious playback / mixing
-% REQ ~ has an open-source license
-\begin{table}
-	\centering
-	\begin{tabular}{llc}
-		\toprule
-		\textbf{Library} & \textbf{License} & \textbf{API}\\
-		\midrule
-		miniaudio & MIT-0 & C\\
-		YSE & EPL & C++\\
-		SoLoud & Zlip/LibPng & C++\\
-		\bottomrule
-	\end{tabular}
-	\caption{Audio engine library comparison}
-	\label{tab:audio-engines}
-\end{table}
-% TODO: ref https://miniaud.io/
-% TODO: ref https://www.attr-x.net/yse/
+\subsection{Conclusion}
+\label{sec:audio:conclusion}
 
-Not considered further:
-\begin{description}
-	\item[FMOD] is proprietary
-	\item[PortAudio] requires manual mixing
-\end{description}
+Due to a severe shortage of libraries that fit our requirements, SoLoud appears to be
+the most suitable (and only) audio library for use in this project.
 
 \section{Physics}
 
diff --git a/scripts/reqs2tex.py b/scripts/reqs2tex.py
index 31303ff..2bab558 100755
--- a/scripts/reqs2tex.py
+++ b/scripts/reqs2tex.py
@@ -75,7 +75,7 @@ def convert(reqs):
   reqs = [item for item in reqs if item[KEY.DELETED] == False]
 
   # sort by label
-  reqs = sorted(reqs, key=lambda req: req[KEY.LABEL])
+  reqs = sorted(reqs, key=lambda item: item[KEY.LABEL])
 
   return reqs
 
diff --git a/sources.bib b/sources.bib
index f48e8c3..586af9c 100644
--- a/sources.bib
+++ b/sources.bib
@@ -47,6 +47,50 @@
 	date = {2024-09-10},
 }
 
+@report{crepe:requirements,
+	author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink},
+	title = {Requirements},
+	date = {2024-09-18},
+}
+
+@online{lib:miniaudio,
+	title = {miniaudio - A single file audio playback and capture library.},
+	% author = {David Reid},
+	url = {https://miniaud.io/docs/manual/index.html},
+	urldate = {2024-09-22},
+}
+
+@online{lib:yse,
+	title = {YSE - cross-platform sound engine},
+	url = {https://www.attr-x.net/yse},
+	urldate = {2024-09-18},
+}
+
+@online{lib:soloud,
+	title = {SoLoud},
+	% author = {Jari Komppa},
+	url = {https://solhsa.com/soloud},
+	urldate = {2024-09-18},
+}
+
+@online{lib:fmod,
+	title = {FMOD},
+	url = {https://www.fmod.com},
+	urldate = {2024-09-18},
+}
+
+@online{lib:portaudio,
+	title = {PortAudio - an Open-Source Cross-Platform Audio API},
+	url = {https://www.portaudio.com},
+	urldate = {2024-09-18},
+}
+
+@online{tool:perf,
+	title = {\texttt{perf:} Linux profiling with performance counters},
+	url = {https://perf.wiki.kernel.org/index.php/Main_Page},
+	urldate = {2024-09-18},
+}
+
 @misc{github:awesome-ecs,
 	author = {Sangjun Lee},
 	title = {Awesome Entity Component System},