2 * Copyright (C) 2016 Robin Gareus <robin@gareus.org>
4 * This program is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU General Public License
6 * as published by the Free Software Foundation; either version 2
7 * of the License, or (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19 #ifndef _ardour_lua_api_h_
20 #define _ardour_lua_api_h_
24 #include <boost/shared_ptr.hpp>
26 #include "ardour/libardour_visibility.h"
28 #include "ardour/processor.h"
29 #include "ardour/session.h"
31 namespace ARDOUR { namespace LuaAPI {
33 /** convenience constructor for DataType::NIL with managed lifetime
34 * @returns DataType::NIL
36 int datatype_ctor_null (lua_State *lua);
37 /** convenience constructor for DataType::AUDIO with managed lifetime
38 * @returns DataType::AUDIO
40 int datatype_ctor_audio (lua_State *L);
41 /** convenience constructor for DataType::MIDI with managed lifetime
42 * @returns DataType::MIDI
44 int datatype_ctor_midi (lua_State *L);
46 /** Create a null processor shared pointer
48 * This is useful for Track:bounce() to indicate no processing.
50 boost::shared_ptr<ARDOUR::Processor> nil_processor ();
52 /** create a new Lua Processor (Plugin)
54 * @param s Session Handle
55 * @param p Identifier or Name of the Processor
56 * @returns Processor object (may be nil)
58 boost::shared_ptr<ARDOUR::Processor> new_luaproc (ARDOUR::Session *s, const std::string& p);
62 * @param id Plugin Name, ID or URI
63 * @param type Plugin Type
64 * @returns PluginInfo or nil if not found
66 boost::shared_ptr<ARDOUR::PluginInfo> new_plugin_info (const std::string& id, ARDOUR::PluginType type);
68 /** create a new Plugin Instance
70 * @param s Session Handle
71 * @param id Plugin Name, ID or URI
72 * @param type Plugin Type
73 * @returns Processor or nil
75 boost::shared_ptr<ARDOUR::Processor> new_plugin (ARDOUR::Session *s, const std::string& id, ARDOUR::PluginType type, const std::string& preset = "");
77 /** set a plugin control-input parameter value
79 * @param proc Plugin-Processor
80 * @param which control-input to set (starting at 0)
81 * @param value value to set
82 * @returns true on success, false on error or out-of-bounds value
84 bool set_processor_param (boost::shared_ptr<ARDOUR::Processor> proc, uint32_t which, float val);
85 /** set a plugin control-input parameter value
87 * This is a wrapper around set_processor_param which looks up the Processor by plugin-insert.
89 * @param proc Plugin-Insert
90 * @param which control-input to set (starting at 0)
91 * @param value value to set
92 * @returns true on success, false on error or out-of-bounds value
94 bool set_plugin_insert_param (boost::shared_ptr<ARDOUR::PluginInsert> pi, uint32_t which, float val);
97 * A convenience function to get a Automation Lists and ParamaterDescriptor
98 * for a given plugin control.
100 * This is equivalent to the following lua code
102 * function (processor, param_id)
103 * local plugininsert = processor:to_insert ()
104 * local plugin = plugininsert:plugin(0)
105 * local _, t = plugin:get_parameter_descriptor(param_id, ARDOUR.ParameterDescriptor ())
106 * local ctrl = Evoral.Parameter (ARDOUR.AutomationType.PluginAutomation, 0, param_id)
107 * local ac = pi:automation_control (ctrl, false)
108 * local acl = ac:alist()
109 * return ac:alist(), ac:to_ctrl():list(), t[2]
113 * Example usage: get the third input parameter of first plugin on the given route
114 * (Ardour starts counting at zero).
116 * local al, cl, pd = ARDOUR.LuaAPI.plugin_automation (route:nth_plugin (0), 3)
118 * @returns 3 parameters: AutomationList, ControlList, ParamaterDescriptor
120 int plugin_automation (lua_State *lua);
123 * A convenience function for colorspace HSL to RGB conversion.
124 * All ranges are 0..1
128 * local r, g, b, a = ARDOUR.LuaAPI.hsla_to_rgba (hue, saturation, luminosity, alpha)
130 * @returns 4 parameters: red, green, blue, alpha (in range 0..1)
132 int hsla_to_rgba (lua_State *lua);
135 namespace ARDOUR { namespace LuaOSC {
138 * A Class to send OSC messages.
142 * OSC is kinda special, lo_address is a void* and lo_send() has varags
143 * and typed arguments which makes it hard to bind, even lo_cpp.
146 /** Construct a new OSC transmitter object
147 * @param uri the destination uri e.g. "osc.udp://localhost:7890"
149 Address (std::string uri) {
150 _addr = lo_address_new_from_url (uri.c_str());
153 ~Address () { if (_addr) { lo_address_free (_addr); } }
154 /** Transmit an OSC message
156 * Path (string) and type (string) must always be given.
157 * The number of following args must match the type.
158 * Supported types are:
160 * 'i': integer (lua number)
162 * 'f': float (lua number)
164 * 'd': double (lua number)
166 * 'h': 64bit integer (lua number)
168 * 's': string (lua string)
170 * 'c': character (lua string)
172 * 'T': boolean (lua bool) -- this is not implicily True, a lua true/false must be given
174 * 'F': boolean (lua bool) -- this is not implicily False, a lua true/false must be given
176 * @param lua: lua arguments: path, types, ...
177 * @returns boolean true if successful, false on error.
179 int send (lua_State *lua);
191 int get (lua_State* L);
192 int set (lua_State* L);
195 struct LuaTableEntry {
196 LuaTableEntry (int kt, int vt)
217 std::vector<LuaTableEntry> _data;
219 static void* findclasskey (lua_State *L, const void* key);
221 static void assign (luabridge::LuaRef* rv, T key, const LuaTableEntry& s);
226 #endif // _ardour_lua_api_h_