improve documentation of OSC variables

libtascar/include/osc_helper.h

@@ -62,6 +62,7 @@ namespace TASCAR {
     class descriptor_t {
     public:
       std::string path;
+      std::string relpath;
       std::string typespec;
       bool readable;
       std::string rangehint;
@@ -326,7 +327,7 @@ namespace TASCAR {
     std::mutex mtxdispatch;
     std::map<double, std::vector<msg_t>> timed_messages;
     std::mutex mtxtimedmessages;
-    std::map<std::string, std::vector<std::string>> owned_vars;
+    std::map<std::string, std::map<std::string,descriptor_t>> owned_vars;
     std::string varowner;
   };
 

libtascar/src/acousticmodel.cc

@@ -597,7 +597,7 @@ receiver_t::receiver_t(tsccfg::node_t xmlsrc, const std::string& name,
                 "Number of reflections created by scattering filter");
   GET_ATTRIBUTE(scatterstructuresize, "m", "size of scatter structure");
   GET_ATTRIBUTE(scatterdamping, "", "damping of scatter reflection filter");
-  GET_ATTRIBUTE_DEG(scatterspread,"Spatial spread of scattering");
+  GET_ATTRIBUTE_DEG(scatterspread, "Spatial spread of scattering");
   // end proxy
   if(avgdist <= 0)
     avgdist = 0.5f * powf(volumetric.boxvolumef(), 0.33333f);
@@ -739,7 +739,7 @@ void receiver_t::postproc(std::vector<wave_t>& output)
         path.dlout.x = scatterallpass_x[kflt].filter(x.x);
         path.dlout.y = scatterallpass_y[kflt].filter(x.y);
         path.dlout.z = scatterallpass_z[kflt].filter(x.z);
-        //path.dlout = x;
+        // path.dlout = x;
         ++kflt;
       }
       scatterfilter->process(scatterfilterpath);
@@ -1053,6 +1053,14 @@ void receiver_t::add_variables(TASCAR::osc_server_t* srv)
     maskplug->add_variables(srv);
     srv->set_prefix(oldpref);
   }
+  srv->set_variable_owner("receiver_t");
+  // uint32_t scatterreflections = 0;
+  srv->add_float_degree("/scatterspread", &scatterspread,
+                        "Spatial spread of scattering");
+  srv->add_float("/scatterstructuresize", &scatterstructuresize, "[0,10]",
+                 "size of scatter structure in m");
+  srv->add_float("/scatterdamping", &scatterdamping, "[0,1]",
+                 "damping of scatter reflection filter");
   srv->add_pos("/proxy/position", &proxy_position, "", "Proxy position in m");
   srv->add_bool("/proxy/is_relative", &proxy_is_relative,
                 "Proxy is relative to receiver (true) or in absolute "
@@ -1063,6 +1071,7 @@ void receiver_t::add_variables(TASCAR::osc_server_t* srv)
   srv->add_bool("/proxy/gain", &proxy_gain, "Use proxy position for gain");
   srv->add_bool("/proxy/direction", &proxy_direction,
                 "Use proxy position for direction");
+  srv->unset_variable_owner();
 }
 
 soundpath_t::soundpath_t(const source_t* src, const soundpath_t* parent_,

libtascar/src/audioplugin.cc

@@ -28,64 +28,60 @@
 using namespace TASCAR;
 
 transport_t::transport_t()
-  : session_time_samples(0), session_time_seconds(0), 
-    object_time_samples(0), object_time_seconds(0), rolling(false)
+    : session_time_samples(0), session_time_seconds(0), object_time_samples(0),
+      object_time_seconds(0), rolling(false)
 {
 }
 
-audioplugin_base_t::audioplugin_base_t( const audioplugin_cfg_t& cfg )
-  : xml_element_t(cfg.xmlsrc),
-    licensed_component_t(typeid(*this).name()),
-    name(cfg.name),
-    parentname(cfg.parentname),
-    modname(cfg.modname)
+audioplugin_base_t::audioplugin_base_t(const audioplugin_cfg_t& cfg)
+    : xml_element_t(cfg.xmlsrc), licensed_component_t(typeid(*this).name()),
+      name(cfg.name), parentname(cfg.parentname), modname(cfg.modname)
 {
 }
 
-audioplugin_base_t::~audioplugin_base_t()
-{
-}
-
-TASCAR_RESOLVER( audioplugin_base_t, const audioplugin_cfg_t& )
+audioplugin_base_t::~audioplugin_base_t() {}
 
+TASCAR_RESOLVER(audioplugin_base_t, const audioplugin_cfg_t&)
 
-TASCAR::audioplugin_t::audioplugin_t( const audioplugin_cfg_t& cfg )
-  : audioplugin_base_t( cfg ),
-    lib(NULL),
-    libdata(NULL)
+TASCAR::audioplugin_t::audioplugin_t(const audioplugin_cfg_t& cfg)
+    : audioplugin_base_t(cfg), lib(NULL), libdata(NULL)
 {
   plugintype = tsccfg::node_get_name(e);
-  if( plugintype == "plugin" )
-    get_attribute("type",plugintype,"","plugin type");
+  if(plugintype == "plugin")
+    get_attribute("type", plugintype, "", "plugin type");
   std::string libname("tascar_ap_");
-  #ifdef PLUGINPREFIX
+#ifdef PLUGINPREFIX
   libname = PLUGINPREFIX + libname;
-  #endif
+#endif
   libname += plugintype + TASCAR::dynamic_lib_extension();
   modname = plugintype;
   audioplugin_cfg_t lcfg(cfg);
   lcfg.modname = modname;
-  lib = dlopen((TASCAR::get_libdir()+libname).c_str(), RTLD_NOW );
-  if( !lib )
-    throw TASCAR::ErrMsg("Unable to open module \""+plugintype+"\": "+dlerror());
-  try{
-    audioplugin_base_t_resolver( &libdata, lcfg, lib, libname );
+  lib = dlopen((TASCAR::get_libdir() + libname).c_str(), RTLD_NOW);
+  if(!lib)
+    throw TASCAR::ErrMsg("Unable to open module \"" + plugintype +
+                         "\": " + dlerror());
+  try {
+    audioplugin_base_t_resolver(&libdata, lcfg, lib, libname);
   }
-  catch( ... ){
+  catch(...) {
     dlclose(lib);
     throw;
   }
 }
 
-void TASCAR::audioplugin_t::ap_process( std::vector<wave_t>& chunk, const TASCAR::pos_t& pos, const TASCAR::zyx_euler_t& o, const TASCAR::transport_t& tp )
+void TASCAR::audioplugin_t::ap_process(std::vector<wave_t>& chunk,
+                                       const TASCAR::pos_t& pos,
+                                       const TASCAR::zyx_euler_t& o,
+                                       const TASCAR::transport_t& tp)
 {
-  libdata->ap_process( chunk, pos, o, tp );
+  libdata->ap_process(chunk, pos, o, tp);
 }
 
 void TASCAR::audioplugin_t::configure()
 {
   audioplugin_base_t::configure();
-  libdata->prepare( cfg() );
+  libdata->prepare(cfg());
 }
 
 void TASCAR::audioplugin_t::post_prepare()
@@ -102,13 +98,13 @@ void TASCAR::audioplugin_t::release()
 
 void TASCAR::audioplugin_t::add_variables(TASCAR::osc_server_t* srv)
 {
-  libdata->add_variables( srv );
+  libdata->add_variables(srv);
 }
 
-void TASCAR::audioplugin_t::add_licenses( licensehandler_t* session )
+void TASCAR::audioplugin_t::add_licenses(licensehandler_t* session)
 {
-  audioplugin_base_t::add_licenses( session );
-  libdata->add_licenses( session );
+  audioplugin_base_t::add_licenses(session);
+  libdata->add_licenses(session);
 }
 
 TASCAR::audioplugin_t::~audioplugin_t()

libtascar/src/maskplugin.cc

@@ -52,7 +52,7 @@ TASCAR::maskplugin_t::maskplugin_t(const maskplugin_cfg_t& cfg)
   modname = plugintype;
   maskplugin_cfg_t lcfg(cfg);
   lcfg.modname = modname;
-  lib = dlopen((TASCAR::get_libdir()+libname).c_str(), RTLD_NOW);
+  lib = dlopen((TASCAR::get_libdir() + libname).c_str(), RTLD_NOW);
   if(!lib)
     throw TASCAR::ErrMsg("Unable to open module \"" + plugintype +
                          "\": " + dlerror());

libtascar/src/osc_helper.cc

@@ -681,6 +681,7 @@ void osc_server_t::add_method(const std::string& path, const char* typespec,
       lo_server_thread_add_method(lost, sPath.c_str(), typespec, h, user_data);
     if(visible) {
       descriptor_t d;
+      d.relpath = path;
       d.path = sPath;
       if(typespec)
         d.typespec = typespec;
@@ -691,9 +692,9 @@ void osc_server_t::add_method(const std::string& path, const char* typespec,
       d.comment = comment;
       variables.push_back(d);
       if(!varowner.empty())
-        owned_vars[varowner].push_back(d.path + d.typespec);
+        owned_vars[varowner][path + d.typespec] = d;
       else {
-        owned_vars["undocumented"].push_back(d.path + d.typespec);
+        owned_vars["undocumented"][path + d.typespec] = d;
       }
     }
   }
@@ -1179,15 +1180,15 @@ void osc_server_t::unset_variable_owner()
 
 void osc_server_t::generate_osc_documentation_files()
 {
-  auto vmap = get_variable_map();
+  // auto vmap = get_variable_map();
   for(const auto& owner : owned_vars) {
     DEBUG(owner.first);
     std::vector<std::string> fullpath;
     bool first = true;
     size_t kmax = fullpath.size();
     for(const auto& varpath : owner.second) {
       std::vector<std::string> fullpath_local =
-          str2vecstr(vmap[varpath].path, "/");
+          str2vecstr(varpath.second.relpath, "/");
       if(first) {
         fullpath = fullpath_local;
         kmax = fullpath.size();
@@ -1200,22 +1201,34 @@ void osc_server_t::generate_osc_documentation_files()
       first = false;
     }
     std::string pat = TASCAR::vecstr2str(fullpath, "/");
+    std::string rep = "...";
+    std::string pref = "";
     if(owner.second.size() < 2)
       pat = "";
+    if((pat.size() == 0) && (fullpath.size() == 1)) {
+      pat = "/";
+      rep = "/.../";
+    }
+    if(fullpath.size() == 0) {
+      pat = "";
+      pref = "/...";
+    }
     std::ofstream ofh("oscdoc_" + owner.first + ".tex");
-    ofh << "\\begin{snugshade}\n{\\footnotesize\n";
+    ofh << "\\definecolor{shadecolor}{RGB}{236,236,255}\\begin{snugshade}\n{"
+           "\\footnotesize\n";
     ofh << "\\label{osctab:" << TASCAR::strrep(owner.first, "_", "") << "}\n";
     ofh << "OSC variables:\n";
     ofh << "\\nopagebreak\n\n";
     ofh << "\\begin{tabularx}{\\textwidth}{llllX}\n";
     ofh << "\\hline\n";
     ofh << "path & fmt. & range & r. & description\\\\\n\\hline\n";
     for(const auto& varpath : owner.second) {
-      ofh << TASCAR::to_latex(TASCAR::strrep(vmap[varpath].path, pat, "..."))
-          << " & " << vmap[varpath].typespec << " & "
-          << TASCAR::to_latex(vmap[varpath].rangehint) << " & "
-          << (vmap[varpath].readable ? "yes" : "no") << " & "
-          << vmap[varpath].comment << "\\\\" << std::endl;
+      ofh << TASCAR::to_latex(pref +
+                              TASCAR::strrep(varpath.second.relpath, pat, rep))
+          << " & " << 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";

libtascar/src/osc_scene.cc

@@ -252,12 +252,15 @@ void osc_scene_t::add_route_methods(TASCAR::osc_server_t* srv,
   rs->route = o;
   rs->anysolo = &(scene->anysolo);
   vprs.push_back(rs);
-  srv->add_bool("/" + scene->name + "/" + o->get_name() + "/mute", &(o->mute),
-                "mute flag, 1 = muted, 0 = unmuted");
-  srv->add_method("/" + scene->name + "/" + o->get_name() + "/solo", "i",
-                  osc_route_solo, rs);
-  srv->add_float("/" + scene->name + "/" + o->get_name() + "/targetlevel",
-                 &o->targetlevel);
+  std::string oldpref(srv->get_prefix());
+  std::string ctlname = "/" + scene->name + "/" + o->get_name();
+  srv->set_prefix(ctlname);
+  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->set_prefix(oldpref);
+  srv->unset_variable_owner();
 }
 
 void osc_scene_t::add_sound_methods(TASCAR::osc_server_t* srv,
@@ -268,6 +271,7 @@ void osc_scene_t::add_sound_methods(TASCAR::osc_server_t* srv,
                       s->get_name());
   srv->set_prefix(ctlname);
   s->set_ctlname(ctlname);
+  srv->set_variable_owner("sound_t");
   srv->add_method("/gain", "f", osc_set_sound_gain, s);
   srv->add_method("/lingain", "f", osc_set_sound_gain_lin, s);
   srv->add_float_dbspl("/caliblevel", &(s->caliblevel), "",
@@ -284,6 +288,7 @@ void osc_scene_t::add_sound_methods(TASCAR::osc_server_t* srv,
   srv->add_method("/zyxeuler", "fff", osc_set_sound_orientation, s);
   srv->add_method("/zeuler", "f", osc_set_sound_orientation, s);
   srv->set_prefix(oldpref);
+  srv->unset_variable_owner();
 }
 
 void osc_scene_t::add_diffuse_methods(TASCAR::osc_server_t* srv,
@@ -309,6 +314,7 @@ void osc_scene_t::add_receiver_methods(TASCAR::osc_server_t* srv,
   s->set_ctlname(ctlname);
   std::string oldpref(srv->get_prefix());
   srv->set_prefix(ctlname);
+  srv->set_variable_owner("receiver_t");
   srv->add_method("/gain", "f", osc_set_receiver_gain, s);
   srv->add_method("/lingain", "f", osc_set_receiver_lingain, s);
   srv->add_float_db("/diffusegain", &(s->diffusegain), "[-30,30]",
@@ -319,6 +325,7 @@ void osc_scene_t::add_receiver_methods(TASCAR::osc_server_t* srv,
   srv->add_uint("/ismmax", &(s->ismmax));
   srv->add_uint("/layers", &(s->layers));
   srv->add_float_dbspl("/caliblevel", &(s->caliblevel));
+  srv->unset_variable_owner();
   s->add_variables(srv);
   srv->set_prefix(oldpref);
 }

libtascar/src/receivermod.cc

@@ -221,8 +221,10 @@ void TASCAR::receivermod_base_speaker_t::add_variables(
     TASCAR::osc_server_t* srv)
 {
   receivermod_base_t::add_variables(srv);
+  srv->set_variable_owner("receivermod_base_speaker");
   srv->add_bool("/decorr", &(spkpos.decorr));
   srv->add_bool("/densitycorr", &(spkpos.densitycorr));
+  srv->unset_variable_owner();
 }
 
 void TASCAR::receivermod_base_speaker_t::validate_attributes(

libtascar/src/tscconfig.cc

@@ -242,7 +242,7 @@ void TASCAR::generate_plugin_documentation_tables(bool latex)
                        fname + "."
                 << std::endl;
       std::ofstream fh(fname);
-      fh << "\\begin{snugshade}\n{\\footnotesize\n";
+      fh << "\\definecolor{shadecolor}{RGB}{255,230,204}\\begin{snugshade}\n{\\footnotesize\n";
       fh << "\\label{attrtab:" << elem.first << "}\n";
       fh << "Attributes of ";
       if(elem.second.type.empty())

manual/.gitignore

@@ -37,3 +37,4 @@ tab*.tex
 autodoc.txt
 cli_*.tex
 clihelp.tex
+oscdoc_undocumented.tex

manual/Makefile

@@ -173,3 +173,6 @@ cli_%.tex: ../apps/build/tascar_% Makefile
 
 modtabs:
 	jackd -d dummy & PID=$$!; sleep 1;(export LD_LIBRARY_PATH="../libtascar/build/:../plugins/build/";export TASCARGENDOC="true";../gui/build/tascar documentation.tsc);kill -9 $$PID
+
+showundoc:
+	for i in oscdoc_*.tex; do grep -q -e "input.$${i}" *.tex || echo "\input{$${i}}"; done

manual/apmodconst.tex

@@ -1,3 +1,5 @@
 Generate constant numbers as audio signal.
 
 \input{tabconst.tex}
+
+\input{oscdoc_tascar_ap_const.tex}

manual/apmodfeedbackdelay.tex

@@ -1,3 +1,5 @@
 Feedback delay line.
 
 \input{tabfeedbackdelay.tex}
+
+\input{oscdoc_tascar_ap_feedbackdelay.tex}

manual/apmodfence.tex

@@ -2,3 +2,5 @@
 outside a given distance from an origin. See \verb!example_fence.tsc! for an example.
 
 \input{tabfence.tex}
+
+\input{oscdoc_tascar_ap_fence.tex}

manual/apmodfilter.tex

@@ -3,3 +3,5 @@
 design.
 
 \input{tabfilter.tex}
+
+\input{oscdoc_tascar_ap_filter.tex}

manual/apmodgain.tex

@@ -1,3 +1,5 @@
 Modify gain.
 
 \input{tabgain.tex}
+
+\input{oscdoc_tascar_ap_gain.tex}

manual/apmodgainramp.tex

@@ -1,3 +1,5 @@
 Modify gain.
 
 \input{tabgainramp.tex}
+
+\input{oscdoc_tascar_ap_gainramp.tex}

manual/apmodgate.tex

@@ -1,3 +1,5 @@
 Gate the vertex audio signal.
 
 \input{tabgate.tex}
+
+\input{oscdoc_tascar_ap_gate.tex}

manual/apmodlipsync.tex

@@ -1,3 +1,5 @@
 Lip synchronization module, similar to \indapmod[lipsync_paper]{lipsync\_paper}.
 
 \input{tablipsync.tex}
+
+\input{oscdoc_tascar_ap_lipsync.tex}

manual/apmodlipsync_paper.tex

@@ -1,3 +1,5 @@
 Module to control lip synchronization as used in \cite{Llorach2016}.
 
 \input{tablipsync_paper.tex}
+
+\input{oscdoc_tascar_ap_lipsync_paper.tex}