libs/ardour/ardour/lua_api.h

   1 /*
   2  * Copyright (C) 2016 Robin Gareus <robin@gareus.org>
   3  *
   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.
   8  *
   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.
  13  *
  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.
  17  *
  18  */
  19 #ifndef _ardour_lua_api_h_
  20 #define _ardour_lua_api_h_
  21
  22 #include <string>
  23 #include <lo/lo.h>
  24 #include <boost/shared_ptr.hpp>
  25
  26 #include "ardour/libardour_visibility.h"
  27
  28 #include "ardour/processor.h"
  29 #include "ardour/session.h"
  30
  31 namespace ARDOUR { namespace LuaAPI {
  32
  33         /** convenience constructor for DataType::NIL with managed lifetime
  34          * @returns DataType::NIL
  35          */
  36         int datatype_ctor_null (lua_State *lua);
  37         /** convenience constructor for DataType::AUDIO with managed lifetime
  38          * @returns DataType::AUDIO
  39          */
  40         int datatype_ctor_audio (lua_State *L);
  41         /** convenience constructor for DataType::MIDI with managed lifetime
  42          * @returns DataType::MIDI
  43          */
  44         int datatype_ctor_midi (lua_State *L);
  45
  46         /** Create a null processor shared pointer
  47          *
  48          * This is useful for Track:bounce() to indicate no processing.
  49          */
  50         boost::shared_ptr<ARDOUR::Processor> nil_processor ();
  51
  52         /** create a new Lua Processor (Plugin)
  53          *
  54          * @param s Session Handle
  55          * @param p Identifier or Name of the Processor
  56          * @returns Processor object (may be nil)
  57          */
  58         boost::shared_ptr<ARDOUR::Processor> new_luaproc (ARDOUR::Session *s, const std::string& p);
  59
  60         /** search a Plugin
  61          *
  62          * @param id Plugin Name, ID or URI
  63          * @param type Plugin Type
  64          * @returns PluginInfo or nil if not found
  65          */
  66         boost::shared_ptr<ARDOUR::PluginInfo> new_plugin_info (const std::string& id, ARDOUR::PluginType type);
  67
  68         /** create a new Plugin Instance
  69          *
  70          * @param s Session Handle
  71          * @param id Plugin Name, ID or URI
  72          * @param type Plugin Type
  73          * @returns Processor or nil
  74          */
  75         boost::shared_ptr<ARDOUR::Processor> new_plugin (ARDOUR::Session *s, const std::string& id, ARDOUR::PluginType type, const std::string& preset = "");
  76
  77         /** set a plugin control-input parameter value
  78          *
  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
  83          */
  84         bool set_processor_param (boost::shared_ptr<ARDOUR::Processor> proc, uint32_t which, float val);
  85
  86         /** get a plugin control parameter value
  87          *
  88          * @param proc Plugin-Processor
  89          * @param which control port to set (starting at 0, including ports of type input and output))
  90          * @param ok boolean variable contains true or false after call returned. to be checked by caller before using value.
  91          * @returns value
  92          */
  93         float get_processor_param (boost::shared_ptr<Processor> proc, uint32_t which, bool &ok);
  94
  95         /** set a plugin control-input parameter value
  96          *
  97          * This is a wrapper around set_processor_param which looks up the Processor by plugin-insert.
  98          *
  99          * @param proc Plugin-Insert
 100          * @param which control-input to set (starting at 0)
 101          * @param value value to set
 102          * @returns true on success, false on error or out-of-bounds value
 103          */
 104         bool set_plugin_insert_param (boost::shared_ptr<ARDOUR::PluginInsert> pi, uint32_t which, float val);
 105
 106         /** get a plugin control parameter value
 107          *
 108          * @param proc Plugin-Insert
 109          * @param which control port to query (starting at 0, including ports of type input and output)
 110          * @param ok boolean variable contains true or false after call returned. to be checked by caller before using value.
 111          * @returns value
 112          */
 113         float get_plugin_insert_param (boost::shared_ptr<ARDOUR::PluginInsert> pi, uint32_t which, bool &ok);
 114
 115         /**
 116          * A convenience function to get a Automation Lists and ParamaterDescriptor
 117          * for a given plugin control.
 118          *
 119          * This is equivalent to the following lua code
 120          * @code
 121          * function (processor, param_id)
 122          *  local plugininsert = processor:to_insert ()
 123          *  local plugin = plugininsert:plugin(0)
 124          *  local _, t = plugin:get_parameter_descriptor(param_id, ARDOUR.ParameterDescriptor ())
 125          *  local ctrl = Evoral.Parameter (ARDOUR.AutomationType.PluginAutomation, 0, param_id)
 126          *  local ac = pi:automation_control (ctrl, false)
 127          *  local acl = ac:alist()
 128          *  return ac:alist(), ac:to_ctrl():list(), t[2]
 129          * end
 130          * @endcode
 131          *
 132          * Example usage: get the third input parameter of first plugin on the given route
 133          * (Ardour starts counting at zero).
 134          * @code
 135          * local al, cl, pd = ARDOUR.LuaAPI.plugin_automation (route:nth_plugin (0), 3)
 136          * @endcode
 137          * @returns 3 parameters: AutomationList, ControlList, ParamaterDescriptor
 138          */
 139         int plugin_automation (lua_State *lua);
 140
 141         /**
 142          * A convenience function for colorspace HSL to RGB conversion.
 143          * All ranges are 0..1
 144          *
 145          * Example:
 146          * @code
 147          * local r, g, b, a = ARDOUR.LuaAPI.hsla_to_rgba (hue, saturation, luminosity, alpha)
 148          * @endcode
 149          * @returns 4 parameters: red, green, blue, alpha (in range 0..1)
 150          */
 151         int hsla_to_rgba (lua_State *lua);
 152
 153         /* Creates a filename from a series of elements using the correct separator for filenames.
 154          *
 155          * No attempt is made to force the resulting filename to be an absolute path.
 156          * If the first element is a relative path, the result will be a relative path.
 157          */
 158         int build_filename (lua_State *lua);
 159
 160 } } /* namespace */
 161
 162 namespace ARDOUR { namespace LuaOSC {
 163         /** OSC transmitter
 164          *
 165          * A Class to send OSC messages.
 166          */
 167         class Address {
 168                 /*
 169                  * OSC is kinda special, lo_address is a void* and lo_send() has varags
 170                  * and typed arguments which makes it hard to bind, even lo_cpp.
 171                  */
 172                 public:
 173                         /** Construct a new OSC transmitter object
 174                          * @param uri the destination uri e.g. "osc.udp://localhost:7890"
 175                          */
 176                         Address (std::string uri) {
 177                                 _addr = lo_address_new_from_url (uri.c_str());
 178                         }
 179
 180                         ~Address () { if (_addr) { lo_address_free (_addr); } }
 181                         /** Transmit an OSC message
 182                          *
 183                          * Path (string) and type (string) must always be given.
 184                          * The number of following args must match the type.
 185                          * Supported types are:
 186                          *
 187                          *  'i': integer (lua number)
 188                          *
 189                          *  'f': float (lua number)
 190                          *
 191                          *  'd': double (lua number)
 192                          *
 193                          *  'h': 64bit integer (lua number)
 194                          *
 195                          *  's': string (lua string)
 196                          *
 197                          *  'c': character (lua string)
 198                          *
 199                          *  'T': boolean (lua bool) -- this is not implicily True, a lua true/false must be given
 200                          *
 201                          *  'F': boolean (lua bool) -- this is not implicily False, a lua true/false must be given
 202                          *
 203                          * @param lua: lua arguments: path, types, ...
 204                          * @returns boolean true if successful, false on error.
 205                          */
 206                         int send (lua_State *lua);
 207                 private:
 208                         lo_address _addr;
 209         };
 210
 211 }
 212
 213 class LuaTableRef {
 214         public:
 215                 LuaTableRef ();
 216                 ~LuaTableRef ();
 217
 218                 int get (lua_State* L);
 219                 int set (lua_State* L);
 220
 221         private:
 222                 struct LuaTableEntry {
 223                         LuaTableEntry (int kt, int vt)
 224                                 : keytype (kt)
 225                                 , valuetype (vt)
 226                         { }
 227
 228                         int keytype;
 229                         std::string k_s;
 230                         unsigned int k_n;
 231
 232                         int valuetype;
 233                         // LUA_TUSERDATA
 234                         const void* c;
 235                         void* p;
 236                         // LUA_TBOOLEAN
 237                         bool b;
 238                         // LUA_TSTRING:
 239                         std::string s;
 240                         // LUA_TNUMBER:
 241                         double n;
 242                 };
 243
 244                 std::vector<LuaTableEntry> _data;
 245
 246                 static void* findclasskey (lua_State *L, const void* key);
 247                 template<typename T>
 248                 static void assign (luabridge::LuaRef* rv, T key, const LuaTableEntry& s);
 249 };
 250
 251 } /* namespace */
 252
 253 #endif // _ardour_lua_api_h_