refine lua-script documentation

diff --git a/scripts/amp1.lua b/scripts/amp1.lua
index fb8387e74ad760012873c7dbac801c12798b2518..128f42a901da9385b230a6874466795ec95bea43 100644 (file)
--- a/scripts/amp1.lua
+++ b/scripts/amp1.lua
@@ -36,8 +36,8 @@ end
 function dsp_runmap (bufs, in_map, out_map, n_samples, offset)
        for c = 1,audio_ins do
                -- Note: lua starts counting at 1, ardour's ChanMapping::get() at 0
-               local ib = in_map:get(ARDOUR.DataType("audio"), c - 1); -- get id of mapped input buffer for given cannel
-               local ob = out_map:get(ARDOUR.DataType("audio"), c - 1); -- get id of mapped output buffer for given cannel
+               local ib = in_map:get(ARDOUR.DataType("audio"), c - 1); -- get id of mapped input buffer for given channel
+               local ob = out_map:get(ARDOUR.DataType("audio"), c - 1); -- get id of mapped output buffer for given channel
                assert (ib ~= ARDOUR.ChanMapping.Invalid);
                assert (ob ~= ARDOUR.ChanMapping.Invalid);
                local a = bufs:get_audio (ib):data (offset):get_table(n_samples) -- copy audio-data from input buffer

diff --git a/scripts/midi_rewite.lua b/scripts/midi_rewite.lua
index 35d2e1ddfce8765395213a62dfb005659836775e..757c6dbaf9a7f1ace5db665ba24c3722e50d0d67 100644 (file)
--- a/scripts/midi_rewite.lua
+++ b/scripts/midi_rewite.lua
@@ -25,7 +25,7 @@ function factory ()
                        mb:silence (n_samples, 0); -- clear existing buffer
 
                        for _,e in pairs (events) do
-                               -- e is an http://ardourman/lua-scripting/class_reference/#Evoral:MidiEvent
+                               -- e is-a http://manual.ardour.org/lua-scripting/class_reference/#Evoral:MidiEvent
                                e:set_channel (2)
                                mb:push_event (e)
                        end

diff --git a/scripts/rawmidi.lua b/scripts/rawmidi.lua
index 73e62ef2436ca4740b3438defa0cb7deefe9b0a9..3b1dfb1d689add192845ff47676a3e0d75828cb4 100644 (file)
--- a/scripts/rawmidi.lua
+++ b/scripts/rawmidi.lua
@@ -16,18 +16,24 @@ end
 function dsp_has_midi_input () return true end
 function dsp_has_midi_output () return true end
 
+-- "dsp_runmap" uses Ardour's internal processor API, eqivalent to
+-- 'connect_and_run()". There is no overhead (mapping, translating buffers).
+-- The lua implementation is responsible to map all the buffers directly.
 function dsp_runmap (bufs, in_map, out_map, n_samples, offset)
-       local ib = in_map:get(ARDOUR.DataType("midi"), 0); -- get id of input buffer
-       local ob = in_map:get(ARDOUR.DataType("midi"), 0); -- get id of output buffer
+       -- see http://manual.ardour.org/lua-scripting/class_reference/#ARDOUR:ChanMapping
+       local ib = in_map:get (ARDOUR.DataType ("midi"), 0); -- get index of the 1st mapped midi input buffer
+       local ob = in_map:get (ARDOUR.DataType ("midi"), 0); -- get index of the 1st mapped midi output buffer
        assert (ib ~= ARDOUR.ChanMapping.Invalid);
-       assert (ib == ob);  -- inplace, buffers are identical
+       assert (ib == ob);  -- require inplace, buffers are identical
 
-       local mb = bufs:get_midi (ib)
-       events = mb:table() -- copy event list into lua table
+       -- http://manual.ardour.org/lua-scripting/class_reference/#ARDOUR:MidiBuffer
+       local mb = bufs:get_midi (ib) -- get the mapped buffer
+       events = mb:table () -- copy event list into a lua table
 
+       -- iterate over all midi events
        for _,e in pairs (events) do
-               -- e is an http://ardourman/lua-scripting/class_reference/#Evoral:MidiEvent
-               --
+               -- e is-a http://manual.ardour.org/lua-scripting/class_reference/#Evoral:MidiEvent
+
                --print (e:channel())
        end
 end

diff --git a/scripts/spectrogram.lua b/scripts/spectrogram.lua
index b0a92df97b57f3cdaf398966e77cfb997b134563..5e7c159aeb2920ffd4a9625c3e773536aaae36ef 100644 (file)
--- a/scripts/spectrogram.lua
+++ b/scripts/spectrogram.lua
@@ -44,8 +44,10 @@ end
 
 -- a C memory area.
 -- It needs to be in global scope.
--- When the variable is set to nil, the allocated memory
--- is free()ed
+-- When the variable is set to nil, the allocated memory is free()ed.
+-- the memory can be interpeted as float* for use in DSP, or read/write
+-- to a C++ Ringbuffer instance.
+-- http://manual.ardour.org/lua-scripting/class_reference/#ARDOUR:DSP:DspShm
 local cmem = nil
 
 function dsp_init (rate)
@@ -54,6 +56,7 @@ function dsp_init (rate)
        dpy_wr = 0
 
        -- create a ringbuffer to hold (float) audio-data
+       -- http://manual.ardour.org/lua-scripting/class_reference/#PBD:RingBufferF
        rb = PBD.RingBufferF (2 * rate)
 
        -- allocate memory, local mix buffer
@@ -72,6 +75,9 @@ function dsp_init (rate)
        self:table ():set (tbl);
 end
 
+-- "dsp_runmap" uses Ardour's internal processor API, eqivalent to
+-- 'connect_and_run()". There is no overhead (mapping, translating buffers).
+-- The lua implementation is responsible to map all the buffers directly.
 function dsp_runmap (bufs, in_map, out_map, n_samples, offset)
        -- here we sum all audio input channels channels and then copy the data to a ringbuffer
        -- for the GUI to process later
@@ -80,10 +86,16 @@ function dsp_runmap (bufs, in_map, out_map, n_samples, offset)
        local ccnt = 0 -- processed channel count
        local mem = cmem:to_float(0) -- a "FloatArray", float* for direct C API usage from the previously allocated buffer
        for c = 1,audio_ins do
+               -- see http://manual.ardour.org/lua-scripting/class_reference/#ARDOUR:ChanMapping
                -- Note: lua starts counting at 1, ardour's ChanMapping::get() at 0
-               local ib = in_map:get (ARDOUR.DataType ("audio"), c - 1) -- get id of mapped input buffer for given cannel
-               local ob = out_map:get (ARDOUR.DataType ("audio"), c - 1) -- get id of mapped output buffer for given cannel
+               local ib = in_map:get (ARDOUR.DataType ("audio"), c - 1) -- get index of mapped input buffer
+               local ob = out_map:get (ARDOUR.DataType ("audio"), c - 1) -- get index of mapped output buffer
+
+               -- check if the input is connected to a buffer
                if (ib ~= ARDOUR.ChanMapping.Invalid) then
+
+                       -- http://manual.ardour.org/lua-scripting/class_reference/#ARDOUR:AudioBuffer
+                       -- http://manual.ardour.org/lua-scripting/class_reference/#ARDOUR:DSP
                        if c == 1 then
                                -- first channel, copy as-is
                                ARDOUR.DSP.copy_vector (mem, bufs:get_audio (ib):data (offset), n_samples)
@@ -104,8 +116,8 @@ function dsp_runmap (bufs, in_map, out_map, n_samples, offset)
        -- In case we're processing in-place some buffers may be identical,
        -- so this must be done  *after processing*.
        for c = 1,audio_ins do
-               local ib = in_map:get (ARDOUR.DataType ("audio"), c - 1) -- get id of mapped input buffer for given cannel
-               local ob = out_map:get (ARDOUR.DataType ("audio"), c - 1) -- get id of mapped output buffer for given cannel
+               local ib = in_map:get (ARDOUR.DataType ("audio"), c - 1)
+               local ob = out_map:get (ARDOUR.DataType ("audio"), c - 1)
                if (ib == ARDOUR.ChanMapping.Invalid and ob ~= ARDOUR.ChanMapping.Invalid) then
                        bufs:get_audio (ob):silence (n_samples, offset)
                end
@@ -122,6 +134,7 @@ function dsp_runmap (bufs, in_map, out_map, n_samples, offset)
        end
 
        -- write data to the ringbuffer
+       -- http://manual.ardour.org/lua-scripting/class_reference/#PBD:RingBufferF
        rb:write (mem, n_samples)
 
        -- emit QueueDraw every FPS