improve OSC documentation

libtascar/src/acousticmodel.cc

@@ -1055,7 +1055,7 @@ void receiver_t::add_variables(TASCAR::osc_server_t* srv)
   }
   srv->set_variable_owner("receiver_t");
   // uint32_t scatterreflections = 0;
-  srv->add_float_degree("/scatterspread", &scatterspread,
+  srv->add_float_degree("/scatterspread", &scatterspread, "",
                         "Spatial spread of scattering");
   srv->add_float("/scatterstructuresize", &scatterstructuresize, "[0,10]",
                  "size of scatter structure in m");

libtascar/src/osc_helper.cc

@@ -615,10 +615,12 @@ osc_server_t::osc_server_t(const std::string& multicast,
     if(verbose)
       std::cerr << "listening on \"" << osc_srv_url << "\"" << std::endl;
   }
+  set_variable_owner("session_t");
   add_method("/sendvarsto", "ss", osc_send_variables, this);
   add_method("/sendvarsto", "sss", osc_send_variables, this);
   add_method("/timedmessages/add", "fs", osc_tm_add, this);
   add_method("/timedmessages/clear", "", osc_tm_clear, this);
+  unset_variable_owner();
 }
 
 int osc_server_t::dispatch_data(void* data, size_t size)
@@ -1223,15 +1225,16 @@ void osc_server_t::generate_osc_documentation_files()
     ofh << "\\hline\n";
     ofh << "path & fmt. & range & r. & description\\\\\n\\hline\n";
     for(const auto& varpath : owner.second) {
-      ofh << TASCAR::to_latex(pref +
+      ofh << "\\attr{"
+          << TASCAR::to_latex(pref +
                               TASCAR::strrep(varpath.second.relpath, pat, rep))
-          << " & " << varpath.second.typespec << " & "
+          << "} & " << varpath.second.typespec << " & "
           << TASCAR::to_latex(varpath.second.rangehint) << " & "
           << (varpath.second.readable ? "yes" : "no") << " & "
           << varpath.second.comment << "\\\\" << std::endl;
     }
     ofh << "\\hline\n\\end{tabularx}\n";
-    ofh << "}\n\\end{snugshade}\n";
+    ofh << "}\n\\end{snugshade}\n\\definecolor{shadecolor}{RGB}{255,230,204}\n";
   }
 }
 

libtascar/src/osc_scene.cc

@@ -213,36 +213,51 @@ int osc_set_receiver_fade(const char*, const char* types, lo_arg** argv,
 void osc_scene_t::add_object_methods(TASCAR::osc_server_t* srv,
                                      TASCAR::Scene::object_t* o)
 {
-  srv->add_method("/" + scene->name + "/" + o->get_name() + "/pos", "fff",
-                  osc_set_object_position, o);
-  srv->add_method("/" + scene->name + "/" + o->get_name() + "/pos", "ffffff",
-                  osc_set_object_position, o);
-  srv->add_method("/" + scene->name + "/" + o->get_name() + "/zyxeuler", "fff",
-                  osc_set_object_orientation, o);
-  srv->add_float("/" + scene->name + "/" + o->get_name() + "/scale",
-                 &(o->scale), "object scale");
+  std::string oldpref(srv->get_prefix());
+  std::string ctlname = "/" + scene->name + "/" + o->get_name();
+  srv->set_prefix(ctlname);
+  srv->set_variable_owner("object_t");
+  srv->add_method("/pos", "fff", osc_set_object_position, o, true, false, "",
+                  "XYZ Translation in m");
+  srv->add_method("/pos", "ffffff", osc_set_object_position, o, true, false, "",
+                  "XYZ Translation in m and ZYX Euler angles in degree");
+  srv->add_method("/zyxeuler", "fff", osc_set_object_orientation, o, true,
+                  false, "", "ZYX Euler angles in degree");
+  srv->add_float("/scale", &(o->scale), "", "object scale");
+  srv->set_prefix(oldpref);
+  srv->unset_variable_owner();
 }
 
 void osc_scene_t::add_face_object_methods(TASCAR::osc_server_t* srv,
                                           TASCAR::Scene::face_object_t* o)
 {
-  srv->add_float("/" + scene->name + "/" + o->get_name() + "/reflectivity",
-                 &(o->reflectivity), "[0,1]", "Reflectivity of object");
-  srv->add_float("/" + scene->name + "/" + o->get_name() + "/damping",
-                 &(o->damping), "[0,1[", "Damping coefficient");
-  srv->add_float("/" + scene->name + "/" + o->get_name() + "/scattering",
-                 &(o->scattering), "[0,1]", "Scattering coefficient");
+  std::string oldpref(srv->get_prefix());
+  std::string ctlname = "/" + scene->name + "/" + o->get_name();
+  srv->set_prefix(ctlname);
+  srv->set_variable_owner("face_t");
+  srv->add_float("/reflectivity", &(o->reflectivity), "[0,1]",
+                 "Reflectivity of object");
+  srv->add_float("/damping", &(o->damping), "[0,1[", "Damping coefficient");
+  srv->add_float("/scattering", &(o->scattering), "[0,1]",
+                 "Scattering coefficient");
+  srv->set_prefix(oldpref);
+  srv->unset_variable_owner();
 }
 
 void osc_scene_t::add_face_group_methods(TASCAR::osc_server_t* srv,
                                          TASCAR::Scene::face_group_t* o)
 {
-  srv->add_float("/" + scene->name + "/" + o->get_name() + "/reflectivity",
-                 &(o->reflectivity), "[0,1]", "Reflectivity of object");
-  srv->add_float("/" + scene->name + "/" + o->get_name() + "/damping",
-                 &(o->damping), "[0,1[", "Damping coefficient");
-  srv->add_float("/" + scene->name + "/" + o->get_name() + "/scattering",
-                 &(o->scattering), "[0,1]", "Scattering coefficient");
+  std::string oldpref(srv->get_prefix());
+  std::string ctlname = "/" + scene->name + "/" + o->get_name();
+  srv->set_prefix(ctlname);
+  srv->set_variable_owner("face_t");
+  srv->add_float("/reflectivity", &(o->reflectivity), "[0,1]",
+                 "Reflectivity of object");
+  srv->add_float("/damping", &(o->damping), "[0,1[", "Damping coefficient");
+  srv->add_float("/scattering", &(o->scattering), "[0,1]",
+                 "Scattering coefficient");
+  srv->set_prefix(oldpref);
+  srv->unset_variable_owner();
 }
 
 void osc_scene_t::add_route_methods(TASCAR::osc_server_t* srv,
@@ -258,7 +273,8 @@ void osc_scene_t::add_route_methods(TASCAR::osc_server_t* srv,
   srv->set_variable_owner("route_t");
   srv->add_bool("/mute", &(o->mute), "mute flag, 1 = muted, 0 = unmuted");
   srv->add_method("/solo", "i", osc_route_solo, rs);
-  srv->add_float("/targetlevel", &o->targetlevel);
+  srv->add_float("/targetlevel", &o->targetlevel, "dB",
+                 "Indicator position in level meter display");
   srv->set_prefix(oldpref);
   srv->unset_variable_owner();
 }

libtascar/src/session.cc

@@ -1161,6 +1161,7 @@ namespace OSCSession {
 
 void TASCAR::session_t::add_transport_methods()
 {
+  osc_server_t::set_variable_owner("session_t");
   osc_server_t::add_method("/sendxmlto", "ss", OSCSession::_osc_send_xml, this);
   osc_server_t::add_method("/transport/locate", "f", OSCSession::_locate, this);
   osc_server_t::add_method("/transport/locatei", "i", OSCSession::_locatei,
@@ -1173,8 +1174,11 @@ void TASCAR::session_t::add_transport_methods()
   osc_server_t::add_method("/transport/stop", "", OSCSession::_stop, this);
   osc_server_t::add_method("/transport/unload", "", OSCSession::_unload_modules,
                            this);
-  osc_server_t::add_method("/runscript", "s", OSCSession::_runscript, this);
+  osc_server_t::add_method("/runscript", "s", OSCSession::_runscript, this,
+                           true, false, "string",
+                           "Name of OSC script file to be loaded.");
   osc_server_t::add_string("/scriptpath", &scriptpath);
+  osc_server_t::unset_variable_owner();
 }
 
 void TASCAR::session_t::send_xml(const std::string& url,

manual/apmodflanger.tex

@@ -0,0 +1,5 @@
+Flanger plugin.
+
+\input{tabflanger.tex}
+
+\input{oscdoc_tascar_ap_flanger.tex}

manual/manual.tex

@@ -629,6 +629,9 @@ \subsection{The {\tt <session>...</session>} element}\label{sec:session}\index{s
   /transport/start}, {\tt /transport/stop} and {\tt
   /transport/locate}.
 
+\input{oscdoc_session_t.tex}
+
+
 A special sub-element \elem{include} can be used to include scenes
 and other elements from another session file, given by the attribute
 \indattr{name}. Example:
@@ -792,6 +795,10 @@ \subsection{Common attributes of objects}
 
 \input{tabroutes.tex}
 
+All objects have these OSC variables:
+
+\input{oscdoc_object_t.tex}
+
 Objects which represent an audio object have these OSC variables:
 
 \input{oscdoc_route_t.tex}
@@ -1410,6 +1417,11 @@ \subsection{Reflectors: {\tt <face .../>} and {\tt <facegroup .../>} elements}\l
   }
 \end{table}
 
+Some properties can be changed via OSC messages:
+
+\input{oscdoc_face_t.tex}
+
+
 Element \elem{facegroup} behaves also as an object, since it also has
 a position and orientation in space.
 %

manual/moddatalogging.tex

@@ -108,6 +108,9 @@ \subsubsection*{OSC control}
 The output directory can be set with \verb!/session_outputdir!. This is
 possible up to the \verb!/session_stop! event.
 
+\input{oscdoc_tascarmod_datalogging.tex}
+
+
 \subsubsection*{Timeline control and data logging}
 
 With the default settings the datalogging will start the timeline

manual/modglabsensors.tex

@@ -145,6 +145,9 @@
 %\indattr{on\_alive}   & System command to be executed if the incoming messages are active again \\
 %\end{tscattributes}
 
+\input{oscdoc_glabsensor_emergency.tex}
+
+
 \label{sec:espheadtracker}For the custom-made ESP-based combined head tracking and EOG
 amplifier of the Gesture Lab, the module {\bf espheadtracker} was
 developed. This module requires a session port number of 9800 to work,

manual/oscdoc_face_t.tex

@@ -0,0 +1,18 @@
+\definecolor{shadecolor}{RGB}{236,236,255}\begin{snugshade}
+{\footnotesize
+\label{osctab:facet}
+OSC variables:
+\nopagebreak
+
+\begin{tabularx}{\textwidth}{llllX}
+\hline
+path & fmt. & range & r. & description\\
+\hline
+\attr{/.../damping} & f & [0,1[ & yes & Damping coefficient\\
+\attr{/.../reflectivity} & f & [0,1] & yes & Reflectivity of object\\
+\attr{/.../scattering} & f & [0,1] & yes & Scattering coefficient\\
+\hline
+\end{tabularx}
+}
+\end{snugshade}
+\definecolor{shadecolor}{RGB}{255,230,204}

manual/oscdoc_glabsensor_emergency.tex

@@ -8,8 +8,9 @@
 \hline
 path & fmt. & range & r. & description\\
 \hline
-/.../noemergency & f &  & no & \\
+\attr{/.../noemergency} & f &  & no & \\
 \hline
 \end{tabularx}
 }
 \end{snugshade}
+\definecolor{shadecolor}{RGB}{255,230,204}

manual/oscdoc_object_t.tex

@@ -0,0 +1,19 @@
+\definecolor{shadecolor}{RGB}{236,236,255}\begin{snugshade}
+{\footnotesize
+\label{osctab:objectt}
+OSC variables:
+\nopagebreak
+
+\begin{tabularx}{\textwidth}{llllX}
+\hline
+path & fmt. & range & r. & description\\
+\hline
+\attr{/.../pos} & fff &  & no & XYZ Translation in m\\
+\attr{/.../pos} & ffffff &  & no & XYZ Translation in m and ZYX Euler angles in degree\\
+\attr{/.../scale} & f &  & yes & object scale\\
+\attr{/.../zyxeuler} & fff &  & no & ZYX Euler angles in degree\\
+\hline
+\end{tabularx}
+}
+\end{snugshade}
+\definecolor{shadecolor}{RGB}{255,230,204}

manual/oscdoc_receiver_t.tex

@@ -8,25 +8,26 @@
 \hline
 path & fmt. & range & r. & description\\
 \hline
-/.../caliblevel & f & [0,120] & yes & \\
-/.../diffusegain & f & [-30,30] & yes & relative gain of diffuse sound field model\\
-/.../fade & ff &  & no & \\
-/.../fade & fff &  & no & \\
-/.../gain & f &  & no & \\
-/.../ismmax & i &  & yes & \\
-/.../ismmin & i &  & yes & \\
-/.../layers & i &  & yes & \\
-/.../lingain & f &  & no & \\
-/.../proxy/airabsorption & i & bool & yes & Use proxy position for air absorption\\
-/.../proxy/delay & i & bool & yes & Use proxy position for delay\\
-/.../proxy/direction & i & bool & yes & Use proxy position for direction\\
-/.../proxy/gain & i & bool & yes & Use proxy position for gain\\
-/.../proxy/is\_relative & i & bool & yes & Proxy is relative to receiver (true) or in absolute coordinates (false)\\
-/.../proxy/position & fff &  & yes & Proxy position in m\\
-/.../scatterdamping & f & [0,1] & yes & damping of scatter reflection filter\\
-/.../scatterspread & f & Spatial spread of scattering & yes & \\
-/.../scatterstructuresize & f & [0,10] & yes & size of scatter structure in m\\
+\attr{/.../caliblevel} & f & [0,120] & yes & \\
+\attr{/.../diffusegain} & f & [-30,30] & yes & relative gain of diffuse sound field model\\
+\attr{/.../fade} & ff &  & no & \\
+\attr{/.../fade} & fff &  & no & \\
+\attr{/.../gain} & f &  & no & \\
+\attr{/.../ismmax} & i &  & yes & \\
+\attr{/.../ismmin} & i &  & yes & \\
+\attr{/.../layers} & i &  & yes & \\
+\attr{/.../lingain} & f &  & no & \\
+\attr{/.../proxy/airabsorption} & i & bool & yes & Use proxy position for air absorption\\
+\attr{/.../proxy/delay} & i & bool & yes & Use proxy position for delay\\
+\attr{/.../proxy/direction} & i & bool & yes & Use proxy position for direction\\
+\attr{/.../proxy/gain} & i & bool & yes & Use proxy position for gain\\
+\attr{/.../proxy/is\_relative} & i & bool & yes & Proxy is relative to receiver (true) or in absolute coordinates (false)\\
+\attr{/.../proxy/position} & fff &  & yes & Proxy position in m\\
+\attr{/.../scatterdamping} & f & [0,1] & yes & damping of scatter reflection filter\\
+\attr{/.../scatterspread} & f &  & yes & Spatial spread of scattering\\
+\attr{/.../scatterstructuresize} & f & [0,10] & yes & size of scatter structure in m\\
 \hline
 \end{tabularx}
 }
 \end{snugshade}
+\definecolor{shadecolor}{RGB}{255,230,204}

manual/oscdoc_receivermod_base_speaker.tex

@@ -8,9 +8,10 @@
 \hline
 path & fmt. & range & r. & description\\
 \hline
-/.../decorr & i & bool & yes & \\
-/.../densitycorr & i & bool & yes & \\
+\attr{/.../decorr} & i & bool & yes & \\
+\attr{/.../densitycorr} & i & bool & yes & \\
 \hline
 \end{tabularx}
 }
 \end{snugshade}
+\definecolor{shadecolor}{RGB}{255,230,204}

manual/oscdoc_receivermod_hoa2d.tex

@@ -8,11 +8,12 @@
 \hline
 path & fmt. & range & r. & description\\
 \hline
-/.../diffup\_delay & f &  & yes & \\
-/.../diffup\_maxorder & i &  & yes & \\
-/.../diffup\_rot & f & [0,360] & yes & \\
-/.../diffup & i & bool & yes & \\
+\attr{/.../diffup\_delay} & f &  & yes & \\
+\attr{/.../diffup\_maxorder} & i &  & yes & \\
+\attr{/.../diffup\_rot} & f & [0,360] & yes & \\
+\attr{/.../diffup} & i & bool & yes & \\
 \hline
 \end{tabularx}
 }
 \end{snugshade}
+\definecolor{shadecolor}{RGB}{255,230,204}

manual/oscdoc_receivermod_hrtf.tex

@@ -8,27 +8,28 @@
 \hline
 path & fmt. & range & r. & description\\
 \hline
-/.../Q\_notch & f &  & yes & \\
-/.../alphamin\_front & f &  & yes & \\
-/.../alphamin\_up & f &  & yes & \\
-/.../alphamin & f &  & yes & \\
-/.../angle & f &  & yes & \\
-/.../decorr & i & bool & yes & \\
-/.../diffuse\_... & i & bool & yes & \\
-/.../freq\_end & f &  & yes & \\
-/.../freq\_start & f &  & yes & \\
-/.../gaincorr & ff &  & no & channel-wise gain correction\\
-/.../maxgain & f &  & yes & \\
-/.../omega\_front & f &  & yes & \\
-/.../omega\_up & f &  & yes & \\
-/.../omega & f &  & yes & \\
-/.../prewarpingmode & i & [0,1,2] & yes & pre-warping mode, 0 = original, 1 = none, 2 = corrected\\
-/.../radius & f &  & yes & \\
-/.../startangle\_front & f &  & yes & \\
-/.../startangle\_notch & f &  & yes & \\
-/.../startangle\_up & f &  & yes & \\
-/.../thetamin & f &  & yes & \\
+\attr{/.../Q\_notch} & f &  & yes & \\
+\attr{/.../alphamin\_front} & f &  & yes & \\
+\attr{/.../alphamin\_up} & f &  & yes & \\
+\attr{/.../alphamin} & f &  & yes & \\
+\attr{/.../angle} & f &  & yes & \\
+\attr{/.../decorr} & i & bool & yes & \\
+\attr{/.../diffuse\_...} & i & bool & yes & \\
+\attr{/.../freq\_end} & f &  & yes & \\
+\attr{/.../freq\_start} & f &  & yes & \\
+\attr{/.../gaincorr} & ff &  & no & channel-wise gain correction\\
+\attr{/.../maxgain} & f &  & yes & \\
+\attr{/.../omega\_front} & f &  & yes & \\
+\attr{/.../omega\_up} & f &  & yes & \\
+\attr{/.../omega} & f &  & yes & \\
+\attr{/.../prewarpingmode} & i & [0,1,2] & yes & pre-warping mode, 0 = original, 1 = none, 2 = corrected\\
+\attr{/.../radius} & f &  & yes & \\
+\attr{/.../startangle\_front} & f &  & yes & \\
+\attr{/.../startangle\_notch} & f &  & yes & \\
+\attr{/.../startangle\_up} & f &  & yes & \\
+\attr{/.../thetamin} & f &  & yes & \\
 \hline
 \end{tabularx}
 }
 \end{snugshade}
+\definecolor{shadecolor}{RGB}{255,230,204}

manual/oscdoc_receivermod_nsp.tex

@@ -8,8 +8,9 @@
 \hline
 path & fmt. & range & r. & description\\
 \hline
-/.../useall & i & bool & yes & \\
+\attr{/.../useall} & i & bool & yes & \\
 \hline
 \end{tabularx}
 }
 \end{snugshade}
+\definecolor{shadecolor}{RGB}{255,230,204}