diff --git a/tools/doxy2json/ardourdoc.sh b/tools/doxy2json/ardourdoc.sh
index 478ae9326d..616e70343f 100755
--- a/tools/doxy2json/ardourdoc.sh
+++ b/tools/doxy2json/ardourdoc.sh
@@ -14,6 +14,8 @@ echo "# analyzing source.. -> $TMPFILE"
$LLVMINCLUDE -I /usr/include/linux \
-I libs/ardour -I libs/pbd -I libs/lua -I gtk2_ardour -I libs/timecode \
-I libs/ltc -I libs/evoral \
+ -X "_" -X "::" -X "sigc" -X "Atk::" -X "Gdk::" -X "Gtk::" -X "Gio::" \
+ -X "Glib::" -X "Pango::" -X "luabridge::" \
libs/ardour/ardour/* libs/pbd/pbd/* \
gtk2_ardour/*.h \
/usr/include/cairomm-1.0/cairomm/context.h \
@@ -28,22 +30,12 @@ php << EOF
\$api = array ();
foreach (json_decode (\$json, true) as \$a) {
if (!isset (\$a['decl'])) { continue; }
- if (empty (\$a['decl'])) { continue; }
- if (\$a['decl'] == '::') { continue; }
- if (substr (\$a['decl'], 0, 1) == '_') { continue; }
- if (substr (\$a['decl'], 0, 2) == '::') { continue; }
- if (substr (\$a['decl'], 0, 4) == 'sigc') { continue; }
- if (substr (\$a['decl'], 0, 5) == 'Atk::') { continue; }
- if (substr (\$a['decl'], 0, 5) == 'Gdk::') { continue; }
- if (substr (\$a['decl'], 0, 5) == 'Gtk::') { continue; }
- if (substr (\$a['decl'], 0, 5) == 'Gio::') { continue; }
- if (substr (\$a['decl'], 0, 6) == 'Glib::') { continue; }
- if (substr (\$a['decl'], 0, 7) == 'Pango::') { continue; }
- if (substr (\$a['decl'], 0, 11) == 'luabridge::') { continue; }
\$a['decl'] = str_replace ('size_t', 'unsigned long', \$a['decl']);
\$a['decl'] = str_replace ('uint32_t', 'unsigned int', \$a['decl']);
+ \$a['decl'] = str_replace ('int32_t', 'int', \$a['decl']);
\$a['decl'] = str_replace ('framepos_t', 'long', \$a['decl']);
+ \$a['decl'] = str_replace ('framecnt_t', 'long', \$a['decl']);
\$a['decl'] = str_replace ('frameoffset_t', 'long', \$a['decl']);
\$a['decl'] = str_replace ('int64_t', 'long', \$a['decl']);
\$a['decl'] = str_replace ('uint8_t', 'unsigned char', \$a['decl']);
@@ -57,7 +49,7 @@ foreach (json_decode (\$json, true) as \$a) {
\$a['decl'] = str_replace ('const unsigned long', 'unsigned long', \$a['decl']);
\$canon = str_replace (' *', '*', \$a['decl']);
\$api[\$canon] = \$a;
- }
+}
\$jout = array ();
foreach (\$api as \$k => \$a) {
\$jout[] = \$a;
diff --git a/tools/doxy2json/doxy2json.cc b/tools/doxy2json/doxy2json.cc
index f8242d5d46..2f28257037 100644
--- a/tools/doxy2json/doxy2json.cc
+++ b/tools/doxy2json/doxy2json.cc
@@ -23,9 +23,49 @@
#include
#include
#include
+#include
Operations are performed on objects. One gets a reference to an object and then calls a method.
-e.g obj = Session:route_by_name("Audio") obj:set_name("Guitar")
+e.g obj = Session:route_by_name("Audio") obj:set_name("Guitar")
.
Object lifetimes are managed by the Session. Most Objects cannot be directly created, but one asks the Session to create or destroy them. This is mainly due to realtime constrains:
you cannot simply remove a track that is currently processing audio. There are various factory methods for object creation or removal.
+Pass by Reference
+
+Since lua functions are closures, C++ methods that pass arguments by reference cannot be used as-is.
+All parameters passed to a C++ method which uses references are returned as Lua Table.
+If the C++ method also returns a value it is prefixed. Two parameters are returned: the value and a Lua Table holding the parameters.
+
+
+
+
C++
+
+
void set_ref (int& var, long& val)
+{
+ printf ("%d %ld\n", var, val);
+ var = 5;
+ val = 7;
+}
+
+
+
+
Lua
+
+
local var = 0;
+ref = set_ref (var, 2);
+-- output from C++ printf()
+
0 2
+-- var is still 0 here
+print (ref[1], ref[2])
+
5 7
+
+
+
+
+
+
+
+
int set_ref2 (int &var, std::string unused)
+{
+ var = 5;
+ return 3;
+}
+
+
+
+
+
rv, ref = set_ref2 (0, "hello");
+print (rv, ref[1], ref[2])
+
3 5 hello
+
+
+
+
+Pointer Classes
+
+Libardour makes extensive use of reference counted boost::shared_ptr
to manage lifetimes.
+The Lua bindings provide a complete abstration of this. There are no pointers in lua.
+For example a =typelink('ARDOUR:Route')?> is a pointer in C++, but lua functions operate on it like it was a class instance.
+
+
+shared_ptr
are reference counted. Once assigned to a lua variable, the C++ object will be kept and remains valid.
+It is good practice to assign references to lua local
variables or reset the variable to nil
to drop the ref.
+
+
+All pointer classes have a isnil ()
method. This is for two cases:
+Construction may fail. e.g. =typelink('ARDOUR:LuaAPI')?>.newplugin()
+may not be able to find the given plugin and hence cannot create an object.
+
+
+The second case if for boost::weak_ptr
. As opposed to boost::shared_ptr
weak-pointers are not reference counted.
+The object may vanish at any time.
+If lua code calls a method on a nil object, the interpreter will raise an exception and the script will not continue.
+This is not unlike a = nil a:test()
which results in en error "attempt to index a nil value".
+
+
+From the lua side of things there is no distinction between weak and shared pointers. They behave identically.
+Below they're inidicated in orange and have an arrow to indicate the pointer type.
+Pointer Classes cannot be created in lua scripts. It always requires a call to C++ to create the Object and obtain a reference to it.
+
+
Class Documentation'.NL;