From 8bf68a16c40274fd464dbcb96fc9523fb8b0e6e8 Mon Sep 17 00:00:00 2001 From: David Runge Date: Wed, 21 Jun 2017 17:14:06 +0200 Subject: thesis/thesis.tex: Adding subsubsection about workflow examples. Improving table captions. Various small fixes. --- thesis/thesis.tex | 141 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file 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} -- cgit v1.2.3-54-g00ecf