allanger/ardour
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Activity

Towards fixing luadoc, manual page creation

Browse Source
This commit is contained in:
Robin Gareus
2019-08-24 02:38:14 +02:00
parent 89f0e70b82
commit ab62c8a926
3 changed files with 23 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
tools/fmt-luadoc.php
View File

@@ -105,6 +105,9 @@ function arg2lua ($argtype, $flags = 0) {
if ($arg == 'luabridge::LuaRef') {
return array ('Lua-Function' => $flags | 4);
}
if ($arg == 'LTC_TV_STANDARD') {
$arg = 'ARDOUR::DSP::LTC_TV_STANDARD';
}
# check Class declarations first
foreach (array_merge ($classes, $consts) as $b) {
@@ -871,10 +874,10 @@ Operations are performed on objects. One gets a reference to an object and then
e.g <code>obj = Session:route_by_name("Audio") obj:set_name("Guitar")</code>.
</p>
<p>
Lua automatically follows C++ class inheritance. e.g one can directly call all SessionObject and Route methods on Track object. However lua does not automatically promote objects. A Route object which just happens to be a Track needs to be explicily cast to a Track. Methods for casts are provided with each class. Note that the cast may fail and return a <em>nil</em> reference.
Lua automatically follows C++ class inheritance. e.g one can directly call all SessionObject and Route methods on Track object. However lua does not automatically promote objects. A Route object which just happens to be a Track needs to be explicitly cast to a Track. Methods for casts are provided with each class. Note that the cast may fail and return a <em>nil</em> reference.
</p>
<p>
Likewise multiple inheritance is a <a href="http://www.lua.org/pil/16.3.html">non-trivial issue</a> in lua. To avoid performance penalties involved with lookups, explicit casts are required in this case. One example is <?=typelink('ARDOUR:SessionObject')?> which is-a StatefulDestructible which inhertis from both Stateful and Destructible.
Likewise multiple inheritance is a <a href="http://www.lua.org/pil/16.3.html">non-trivial issue</a> in Lua. To avoid performance penalties involved with lookups, explicit casts are required in this case. One example is <?=typelink('ARDOUR:SessionObject')?> which is-a StatefulDestructible which inherits from both Stateful and Destructible.
</p>
<p>
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:
@@ -882,7 +885,7 @@ you cannot simply remove a track that is currently processing audio. There are v
</p>
<h3>Pass by Reference</h3>
<p>
Since lua functions are closures, C++ methods that pass arguments by reference cannot be used as-is.
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.
</p>
@@ -934,12 +937,12 @@ print (rv, ref[1], ref[2])
<h3>Pointer Classes</h3>
<p>
Libardour makes extensive use of reference counted <code>boost::shared_ptr</code> 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.
The Lua bindings provide a complete abstraction 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.
</p>
<p>
<code>shared_ptr</code> 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 <code>local</code> variables or reset the variable to <code>nil</code> to drop the ref.
<code>shared_ptr</code> 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 <code>local</code> variables or reset the variable to <code>nil</code> to drop the ref.
</p>
<p>
All pointer classes have a <code>isnil ()</code> method. This is for two cases:
@@ -949,13 +952,13 @@ may not be able to find the given plugin and hence cannot create an object.
<p>
The second case if for <code>boost::weak_ptr</code>. As opposed to <code>boost::shared_ptr</code> 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.
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 <code>a = nil a:test()</code> which results in en error "<em>attempt to index a nil value</em>".
</p>
<p>
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.
From the Lua side of things there is no distinction between weak and shared pointers. They behave identically.
Below they're indicated 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.
</p>