thesis/thesis.tex: Adding subsubsection about workflow examples. Improving table captions. Various small fixes.

1 files changed, 104 insertions, 37 deletions

diff --git a/thesis/thesis.tex b/thesis/thesis.tex
index b3cf61b..20ec079 100644
--- a/thesis/thesis.tex
+++ b/thesis/thesis.tex
@@ -92,6 +92,7 @@ parskip=never]{paper}
     {\huge\bfseries A Networking Extension for the SoundScape Renderer\par}
     \vspace{2cm}
     {\Large\itshape David Runge\par}
+    \vspace{1.5cm}
     {\large (340592)}\\
     \href{dave@sleepmap.de}{dave@sleepmap.de}\\
     \vfill
@@ -627,7 +628,7 @@ parskip=never]{paper}
 
           \begin{listing}[!htb]
             \begin{mdframed}
-              \begin{minted}[fontsize=\footnotesize]{console}
+              \begin{minted}[fontsize=\footnotesize]{shell}
 ssr-binaural -p “50002”
               \end{minted}
             \end{mdframed}
@@ -637,9 +638,10 @@ ssr-binaural -p “50002”
           \end{listing}
 
           Once started, the client instance waits to receive a poll message
-          from a server instance (or an application, mimicing one), upon which
+          from a server instance (or an application, mimicking one), upon which
           it will subscribe to it. Only then it is possible for the server
-          application to control the client instance to the full extent.
+          application to control the client instance to the full extent via
+          \gls{osc}.
 
         \paragraph{Server instance}
           \label{para:server-instance}
@@ -649,10 +651,12 @@ ssr-binaural -p “50002”
           \textbf{-C} is used to specify an initial client \gls{ip} and its
           port (the flag actually accepts a comma-separated list of
           \gls{ip}-port pairs).\\
+          The \textbf{-p} flag, for setting a specific port is also available,
+          when starting a server instance.
 
           \begin{listing}[!htb]
             \begin{mdframed}
-              \begin{minted}[fontsize=\footnotesize]{console}
+              \begin{minted}[fontsize=\footnotesize]{shell}
 ssr-aap -N “server” -C “127.0.0.1:50002”
               \end{minted}
             \end{mdframed}
@@ -667,9 +671,11 @@ ssr-aap -N “server” -C “127.0.0.1:50002”
           \textbf{-C} flag are considered instantly active.\\
           Additionally it's possible for clients (\gls{ssr} client instances,
           or \gls{osc} capable applications) to subscribe to the server
-          instance, or be subscribed to it by another client.
+          instance, or be subscribed to it by another client, using a message
+          level system further explained in \nameref{subsubsec:message_levels}.
           Every valid \gls{osc} message sent to the server instance will be
-          delegated to all of its clients upon evaluation.
+          delegated to all of its clients upon evaluation, again according to
+          the aforementioned message level system.
 
       \subsubsection{Setups}
         \label{subsubsec:setups}
@@ -841,8 +847,10 @@ ssr-aap -N “server” -C “127.0.0.1:50002”
         \gls{osc} interface conceived in the course of this work.\\
         The \textit{enumeration class} MessageLevel (see
         Listing~\ref{lst:ssr_global.h}) defines the four types \textit{CLIENT},
-        \textit{GUI\_CLIENT}, \textit{SERVER}, \textit{GUI\_SERVER},  (in
-        ascending order).\\
+        \textit{GUI\_CLIENT}, \textit{SERVER}, \textit{GUI\_SERVER}, which are
+        represented as non-negative integers (in ascending order), starting
+        from 0.\\
+
         \begin{listing}[!htb]
           \begin{mdframed}
             \inputminted[numbers=left, firstline=54, lastline=60,
@@ -851,6 +859,7 @@ ssr-aap -N “server” -C “127.0.0.1:50002”
           \caption{src/ssr\_global.h: enum class MessageLevel}
           \label{lst:ssr_global.h}
         \end{listing}\\
+
         \gls{ssr} client instances subscribe to (\gls{ssr}) server instances
         with the \textit{MessageLevel} \textit{CLIENT} by default. Server
         instances get the \textit{MessageLevel} \textit{SERVER} assigned
@@ -897,9 +906,6 @@ ssr-aap -N “server” -C “127.0.0.1:50002”
           \scriptsize
           \centering
           \rowcolors{2}{table-background-one}{table-background-two}
-          \caption*{(Data types and their acronyms are listed in
-            Table~\ref{tab:ssr-osc-data-type-acronyms}.)
-          }
           \begin{tabular}{ p{2cm} | p{1cm} | p{3.5cm} | p{3cm} }
             \textbf{Path} & \textbf{Types} & \textbf{Description} &
             \textbf{Example}\\
@@ -924,7 +930,10 @@ ssr-aap -N “server” -C “127.0.0.1:50002”
           \caption{\gls{osc} messages relevant for subscribing and setting of
             message levels for clients.\\
           }
-          \caption*{Understood by server.}
+          \caption*{Understood by server.\\
+            Data types and their acronyms are listed in
+            Table~\ref{tab:ssr-osc-data-type-acronyms}.
+          }
           \label{tab:ssr-osc-subscribe}
         \end{table}
 
@@ -932,9 +941,6 @@ ssr-aap -N “server” -C “127.0.0.1:50002”
           \scriptsize
           \centering
           \rowcolors{2}{table-background-one}{table-background-two}
-          \caption*{(Data types and their acronyms are listed in
-            Table~\ref{tab:ssr-osc-data-type-acronyms}.)
-          }
           \begin{tabular}{ p{2cm} | p{1cm} | p{3.5cm} | p{3cm} }
             \textbf{Path} & \textbf{Types} & \textbf{Description} &
             \textbf{Example}\\
@@ -946,7 +952,10 @@ ssr-aap -N “server” -C “127.0.0.1:50002”
           \end{tabular}
           \caption{\gls{osc} messages relevant for polling and setting of
             message levels for servers subscribed to.\\
-            Understood by clients.
+          }
+          \caption*{Understood by client.\\
+            Data types and their acronyms are listed in
+            Table~\ref{tab:ssr-osc-data-type-acronyms}.
           }
           \label{tab:ssr-osc-client-poll-message-level}
         \end{table}
@@ -955,9 +964,6 @@ ssr-aap -N “server” -C “127.0.0.1:50002”
           \scriptsize
           \centering
           \rowcolors{2}{table-background-one}{table-background-two}
-          \caption*{(Data types and their acronyms are listed in
-            Table~\ref{tab:ssr-osc-data-type-acronyms}.)
-          }
           \begin{tabular}{ p{3cm} | p{1.2cm} | p{3.5cm} | p{3cm} }
             \textbf{Path} & \textbf{Types} & \textbf{Description} &
             \textbf{Example}\\
@@ -979,17 +985,18 @@ ssr-aap -N “server” -C “127.0.0.1:50002”
           \end{tabular}
           \caption{\gls{osc} messages relevant for processing, tracker and
             (\gls{jack}) transport related settings.\\
-            Understood by server and clients.
+          }
+          \caption*{Understood by server and client.\\
+            Data types and their acronyms are listed in
+            Table~\ref{tab:ssr-osc-data-type-acronyms}.
           }
           \label{tab:ssr-osc-processing-tracker-transport}
         \end{table}
+
         \begin{table}[!htb]
           \scriptsize
           \centering
           \rowcolors{2}{table-background-one}{table-background-two}
-          \caption*{(Data types and their acronyms are listed in
-            Table~\ref{tab:ssr-osc-data-type-acronyms}.)
-          }
           \begin{tabular}{ p{4.3cm} | p{1cm} | p{2.5cm} | p{4.4cm} }
             \textbf{Path} & \textbf{Types} & \textbf{Description} &
             \textbf{Example}\\
@@ -1006,10 +1013,14 @@ ssr-aap -N “server” -C “127.0.0.1:50002”
             2.0]}\\
           \end{tabular}
           \caption{\gls{osc} messages relevant for reference management.\\
-            Understood by server and clients.
+          }
+          \caption*{Understood by server and client.\\
+            Data types and their acronyms are listed in
+            Table~\ref{tab:ssr-osc-data-type-acronyms}.
           }
           \label{tab:ssr-osc-reference}
         \end{table}
+
         \begin{table}[!htb]
           \scriptsize
           \centering
@@ -1047,17 +1058,18 @@ ssr-aap -N “server” -C “127.0.0.1:50002”
             \texttt{[/scene/volume, 0.23]}\\
           \end{tabular}
           \caption{\gls{osc} messages relevant for scene management.\\
-              Understood by server and clients.
+          }
+          \caption*{Understood by server and client.\\
+            Data types and their acronyms are listed in
+            Table~\ref{tab:ssr-osc-data-type-acronyms}.
           }
           \label{tab:ssr-osc-scene}
         \end{table}
+
         \begin{table}[!htb]
           \scriptsize
           \centering
           \rowcolors{2}{table-background-one}{table-background-two}
-          \caption*{(Data types and their acronyms are listed in
-            Table~\ref{tab:ssr-osc-data-type-acronyms}.)
-          }
           \begin{tabular}{ p{3.5cm} | p{1.5cm} | p{2.5cm} | p{4.3cm} }
             \textbf{Path} & \textbf{Types} & \textbf{Description} &
             \textbf{Example} \\
@@ -1066,9 +1078,9 @@ ssr-aap -N “server” -C “127.0.0.1:50002”
             \texttt{[/source/delete, 1]}\\
             \texttt{/source/file\_channel} & ii & Set a source's file channel &
             \texttt{[/source/file\_channel, 1, 2]}\\
-            \texttt{/source/file\_name\_or\_port\_number} & is & Set a source's
+            \texttt{/source/file\_name\_ or\_port\_number} & is & Set a source's
             file name or port number &
-            \texttt{[/source/file\_name\_or\_port\_number, 1, “1”]}\\
+            \texttt{[/source/file\_name\_ or\_port\_number, 1, “1”]}\\
             \texttt{/source/port\_name } & is & Set a source's \gls{jack} input
             port name & \texttt{[/source/port\_name, 1, “system:capture\_2”]}\\
             \texttt{/source/gain} & if & Set a source's gain &
@@ -1107,17 +1119,18 @@ ssr-aap -N “server” -C “127.0.0.1:50002”
             “source-properties.xml”]}\\
           \end{tabular}
           \caption{\gls{osc} messages relevant for source management.\\
-              Understood by server and clients.
+          }
+          \caption*{Understood by server and client.\\
+            Data types and their acronyms are listed in
+            Table~\ref{tab:ssr-osc-data-type-acronyms}.
           }
           \label{tab:ssr-osc-source}
         \end{table}
+
         \begin{table}[!htb]
           \scriptsize
           \centering
           \rowcolors{2}{table-background-one}{table-background-two}
-          \caption*{(Data types and their acronyms are listed in
-            Table~\ref{tab:ssr-osc-data-type-acronyms}.)
-          }
           \begin{tabular}{ p{6.5cm} | p{0.9cm} | p{4.3cm} }
             \textbf{Path} & \textbf{Types} & \textbf{Description} \\
             \hline
@@ -1185,15 +1198,69 @@ ssr-aap -N “server” -C “127.0.0.1:50002”
           \caption{\gls{osc} messages for updating information on \gls{cpu} load,
             processing, reference, scene, source, and transport of clients on a
             server.\\
-            Understood by server.\\
             No examples are given, as they are mostly analogous to the ones in
-            Table~\ref{tab:ssr-osc-processing-tracker-transport},
-            Table~\ref{tab:ssr-osc-scene} and Table~\ref{tab:ssr-osc-source}.
+            Table~\ref{tab:ssr-osc-processing-tracker-transport}
+            ,~\ref{tab:ssr-osc-scene} and~\ref{tab:ssr-osc-source}.
+          }
+          \caption*{Understood by server.\\
+            Data types and their acronyms are listed in
+            Table~\ref{tab:ssr-osc-data-type-acronyms}.
           }
           \label{tab:ssr-osc-update}
         \end{table}
 
   \cleardoublepage
+
+      \subsubsection{Workflow Examples}
+        \label{subsubsec:workflow_examples}
+        Using any \gls{osc} capable programming language or application enables
+        for communication with the \gls{ssr}. The following examples illustrate
+        simple workflows using sclang (the SuperCollider programming language)
+        and should therefore be \gls{os} agnostic.\\
+
+        \begin{listing}[!htb]
+          \begin{mdframed}
+            \inputminted[numbers=left, firstline=3, lastline=29,
+            fontsize=\footnotesize]{supercollider}{../../../../ssr-tests.scd}
+          \end{mdframed}
+          \caption{supercollider/ssr-workflows.scd: sclang as client
+          controlling a \gls{ssr} server instance}
+          \label{lst:ssr-workflow-sclang-controls-server}
+        \end{listing}\\
+
+        As shown in Listing~\ref{lst:ssr-workflow-sclang-controls-server}, it
+        is necessary to subscribe to the server instance with a
+        \textit{MessageLevel} of \textit{SERVER} or higher.\\
+        After doing so, all non-update \gls{osc} messages (i.e.
+        Table~\ref{tab:ssr-osc-source},~\ref{tab:ssr-osc-scene}
+        ,~\ref{tab:ssr-osc-reference},~\ref{tab:ssr-osc-subscribe})
+        are evaluated when sent to the \gls{ssr}.\\
+        The server instance will relay all valid messages from a client with
+        \textit{MessageLevel} \textit{SERVER} to all of its active clients.
+
+        \begin{listing}[!htb]
+          \begin{mdframed}
+            \inputminted[numbers=left, firstline=31, lastline=61,
+            fontsize=\footnotesize]{supercollider}{../../../../ssr-tests.scd}
+          \end{mdframed}
+          \caption{supercollider/ssr-workflows.scd: sclang mimics server,
+          controlling a \gls{ssr} client instance}
+          \label{lst:ssr-workflow-sclang-is-server-controls-client}
+        \end{listing}\\
+
+        When mimicking a \gls{ssr} server instance in a server-less setup (e.g.
+        Figure~\ref{fig:ssr-external-clients-only-shared-output} or
+      Figure~\ref{fig:ssr-external-clients-only-separate-output}), it is
+      necessary to send a poll message to the client instance to make it
+      subscribe (which sets the server's address and port up internally).\\
+      Afterwards again all non-update \gls{osc} messages are accepted by the
+      client instance, when coming from the server address and port.
+      An interesting concept here is to (temporarily) set a different
+      \textit{MessageLevel} for the application acting as a server (e.g.\ to
+        \textit{GUI\_SERVER}, to receive \gls{gui} relevant messages, as
+        explained in \nameref{subsubsec:message_interface}.\\
+
+    \cleardoublepage
   \section{Discussion}
     \label{sec:discussion}
     \subsection{Stress testing the \gls{osc} interface}