From c37f21e48f17abe9fb6bf1549f680e6f730aed8c Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Wed, 18 Sep 2024 16:52:40 +0200 Subject: WIP research --- projdoc.cls | 3 +++ reqs.toml | 16 ++++++++++- research.tex | 34 ++++++++++------------- scripts/reqs2tex.py | 3 +++ sources.bib | 77 +++++++++++++++++++++++++++++++++++++++-------------- 5 files changed, 92 insertions(+), 41 deletions(-) diff --git a/projdoc.cls b/projdoc.cls index fccf8c1..05e401c 100644 --- a/projdoc.cls +++ b/projdoc.cls @@ -389,3 +389,6 @@ } \makeatother +% missing reference marker +\def\mref{\textsuperscript{\textit{\,ref?}}} + diff --git a/reqs.toml b/reqs.toml index 6645ea4..2da91ac 100644 --- a/reqs.toml +++ b/reqs.toml @@ -67,7 +67,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 = ''' @@ -75,3 +77,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 ad33d10..abfde3b 100644 --- a/research.tex +++ b/research.tex @@ -201,44 +201,38 @@ 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 +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 engines that could be used in the engine. -% TODO: requirements first! +\subsection{Libraries} + +\Cref{tab:audio-engines} compares several standalone audio engine libraries that fit +\cref{req:audio,req:lib:license}. -% 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++\\ + miniaudio \autocite{lib:miniaudio} & MIT-0 & C\\ + YSE \autocite{lib:yse} & EPL & C++\\ + SoLoud \autocite{lib: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/ -Not considered further: +Other popular libraries that were researched but are unsuitable for this project +include:\noparbreak \begin{description} - \item[FMOD] is proprietary - \item[PortAudio] requires manual mixing + \item[FMOD \autocite{lib:fmod}] Is proprietary (violates \cref{req:lib:license}) + \item[PortAudio \autocite{lib:portaudio}] Does not handle mixing \end{description} \section{Physics} diff --git a/scripts/reqs2tex.py b/scripts/reqs2tex.py index e5f063d..6984466 100755 --- a/scripts/reqs2tex.py +++ b/scripts/reqs2tex.py @@ -94,6 +94,9 @@ def convert(data): # skip deleted requirements (but process for make_id) reqs = [item for item in reqs if item[KEY.DELETED] == False] + # sort by label + reqs = sorted(reqs, key=lambda item: item[KEY.LABEL]) + return reqs def fmt_aux(data): diff --git a/sources.bib b/sources.bib index 50f5ead..6f5ce0c 100644 --- a/sources.bib +++ b/sources.bib @@ -13,38 +13,75 @@ } @misc{miro:scrum-board, - author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, - title = {Scrum Board on Miro}, - url = {https://miro.com/app/board/uXjVKjtdM64=/?share_link_id=303851465474}, - date = {2024-09-10}, + author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, + title = {Scrum Board on Miro}, + url = {https://miro.com/app/board/uXjVKjtdM64=/?share_link_id=303851465474}, + date = {2024-09-10}, } @misc{crepe:code-repo, - author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, - title = {Crepe Code Repository}, - url = {https://github.com/lonkaars/crepe}, - date = {2024-09-10}, + author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, + title = {Crepe Code Repository}, + url = {https://github.com/lonkaars/crepe}, + date = {2024-09-10}, } @misc{crepe:docs-repo, - author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, - title = {Crepe Documentation Repository}, - url = {https://github.com/lonkaars}, - date = {2024-09-10}, + author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, + title = {Crepe Documentation Repository}, + url = {https://github.com/lonkaars}, + date = {2024-09-10}, } @misc{crepe:docs-standard, - author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, - title = {Crepe Documentation Standard}, - url = {https://github.com/lonkaars/crepe-docs/blob/master/contributing.md}, - date = {2024-09-10}, + author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, + title = {Crepe Documentation Standard}, + url = {https://github.com/lonkaars/crepe-docs/blob/master/contributing.md}, + date = {2024-09-10}, } @misc{crepe:code-standard, - author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, - title = {Crepe Code Standard}, - url = {https://github.com/lonkaars/crepe/blob/master/contributing.md}, - date = {2024-09-10}, + author = {Loek Le Blansch and Wouter Boerenkamps and Jaro Rutjes and Max Smits and Niels Stunnebrink}, + title = {Crepe Code Standard}, + url = {https://github.com/lonkaars/crepe/blob/master/contributing.md}, + 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}, + urldate = {2024-09-18}, +} + +@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}, +} -- cgit v1.2.3 From 395ef912d0b5d398874cc37021ea0e6c0e94f38a Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Wed, 18 Sep 2024 17:39:53 +0200 Subject: WIP research --- research.tex | 49 ++++++++++++++++++++++++++++++++++++++++++++++--- sources.bib | 6 ++++++ 2 files changed, 52 insertions(+), 3 deletions(-) diff --git a/research.tex b/research.tex index abfde3b..175c92b 100644 --- a/research.tex +++ b/research.tex @@ -206,11 +206,17 @@ for audio some options could be: FMOD, Wwise, or iirKlang 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 engines that could be used in the engine. +various standalone audio libraries for suitability in the engine. + +\Cref{sec:audio:libs} details which libraries were considered, +\cref{sec:audio:benchmark} compares their performance, and +\cref{sec:audio:conclusion} concludes with a recommendation for most performant audio +library. \subsection{Libraries} +\label{sec:audio:libs} -\Cref{tab:audio-engines} compares several standalone audio engine libraries that fit +\Cref{tab:audio:libs} lists the standalone audio engine libraries that fit \cref{req:audio,req:lib:license}. \begin{table} @@ -225,7 +231,7 @@ various standalone audio engines that could be used in the engine. \bottomrule \end{tabular} \caption{Audio engine library comparison} - \label{tab:audio-engines} + \label{tab:audio:libs} \end{table} Other popular libraries that were researched but are unsuitable for this project @@ -235,6 +241,43 @@ include:\noparbreak \item[PortAudio \autocite{lib:portaudio}] Does not handle mixing \end{description} +\subsection{Benchmarks} +\label{sec:audio:benchmark} + +The same benchmark application was written for each of the libraries listed in +\cref{tab:audio:libs}. The application does the following:\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} + +Each benchmark was profiled using \emph{perf} \autocite{tool:perf} and compared based +on total CPU and memory utilization. The results of these benchmarks are listed in +\cref{tab:audio:benchmark}. + +\begin{table} + \centering + \begin{tabular}{lr} + \toprule + \textbf{Library} & \textbf{???}\\ + \midrule + miniaudio &\\ + YSE &\\ + SoLoud &\\ + \bottomrule + \end{tabular} + \caption{Audio engine library benchmark results} + \label{tab:audio:benchmark} +\end{table} + +\subsection{Conclusion} +\label{sec:audio:conclusion} + + \section{Physics} \subsection{Introduction} diff --git a/sources.bib b/sources.bib index 6f5ce0c..33f3a2e 100644 --- a/sources.bib +++ b/sources.bib @@ -85,3 +85,9 @@ 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}, +} + -- cgit v1.2.3 From 46d07c2c9e68597f3f6af76b4f8e837786781029 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 22 Sep 2024 19:25:02 +0200 Subject: finish audio research --- glossary.bib | 6 +++++ research.tex | 72 +++++++++++++++++------------------------------------------- sources.bib | 4 ++-- 3 files changed, 28 insertions(+), 54 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/research.tex b/research.tex index f3424c4..4ca3d3d 100644 --- a/research.tex +++ b/research.tex @@ -247,44 +247,14 @@ The game engine is required to have an audio system audio mixing engine is outside the scope of this project\mref, this section compares various standalone audio libraries for suitability in the engine. -\Cref{sec:audio:libs} details which libraries were considered, -\cref{sec:audio:benchmark} compares their performance, and -\cref{sec:audio:conclusion} concludes with a recommendation for most performant audio -library. - \subsection{Libraries} \label{sec:audio:libs} -\Cref{tab:audio:libs} lists the standalone audio engine libraries that fit -\cref{req:audio,req:lib:license}. - -\begin{table} - \centering - \begin{tabular}{llc} - \toprule - \textbf{Library} & \textbf{License} & \textbf{API}\\ - \midrule - miniaudio \autocite{lib:miniaudio} & MIT-0 & C\\ - YSE \autocite{lib:yse} & EPL & C++\\ - SoLoud \autocite{lib:soloud} & Zlip/LibPng & C++\\ - \bottomrule - \end{tabular} - \caption{Audio engine library comparison} - \label{tab:audio:libs} -\end{table} - -Other popular libraries that were researched but are unsuitable for this project -include:\noparbreak -\begin{description} - \item[FMOD \autocite{lib:fmod}] Is proprietary (violates \cref{req:lib:license}) - \item[PortAudio \autocite{lib:portaudio}] Does not handle mixing -\end{description} - -\subsection{Benchmarks} -\label{sec:audio:benchmark} - -The same benchmark application was written for each of the libraries listed in -\cref{tab:audio:libs}. The application does the following:\noparbreak +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) @@ -294,28 +264,26 @@ The same benchmark application was written for each of the libraries listed in \item Stop all audio and exit \end{enumerate} -Each benchmark was profiled using \emph{perf} \autocite{tool:perf} and compared based -on total CPU and memory utilization. The results of these benchmarks are listed in -\cref{tab:audio:benchmark}. +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} -\begin{table} - \centering - \begin{tabular}{lr} - \toprule - \textbf{Library} & \textbf{???}\\ - \midrule - miniaudio &\\ - YSE &\\ - SoLoud &\\ - \bottomrule - \end{tabular} - \caption{Audio engine library benchmark results} - \label{tab:audio:benchmark} -\end{table} +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}. \subsection{Conclusion} \label{sec:audio:conclusion} +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/sources.bib b/sources.bib index bb68067..adcfdd5 100644 --- a/sources.bib +++ b/sources.bib @@ -56,8 +56,8 @@ @online{lib:miniaudio, title = {miniaudio - A single file audio playback and capture library.}, % author = {David Reid}, - url = {https://miniaud.io}, - urldate = {2024-09-18}, + url = {https://miniaud.io/docs/manual/index.html}, + urldate = {2024-09-22}, } @online{lib:yse, -- cgit v1.2.3