Exporting functions for ReaScript

[Jeff0S]

From fingersmcgarnickle on December 14, 2011 13:17:09

I wrote a bit of throwaway code to test accessing ReaScript from reaper_sws.dll. Basically you export functions from the dll and then you can call them from ReaScript using the ctypes module.

This will enable users to edit MIDI events using ReaScript from the MIDI editor, without chunk editing. It also opens up new levels of customization capabilities, beyond this.

I am thinking I'll just export one function called ReaScriptImport which will return function pointers to functions from a table. The python import module could be generated from an action or shipped in the installer.

Does this sound okay to implement here or should I start a new project to do this. I think a fair few people would use this as Python is a pretty simple language to get your head around, given some examples.

Original issue: http://code.google.com/p/sws-extension/issues/detail?id=432

[Jeff0S]

From jeffos...@gmail.com on December 14, 2011 05:30:01

Excellent idea! Also, "delegating" chunk edition to a C++ extension will break the the 1 Mo limitation for ReaScript (show stopper with real projects..).

Personnaly, I would vote for the SWS solution rather than a distinct project: many, many things could be shared with ReaScript users!

[Jeff0S]

From fingersmcgarnickle on December 14, 2011 06:23:54

For sure. It is not only the 1Mb limit it is also the speed of chunk editing in C++. Plus most useful stuff has been coded already so writing Python wrappers is alot less work then reimplementing in Python. There is a lot of other stuff which could be done like:

• Session based storage of data for scripts
• Creating custom dialogs (would be a bit of work but possible)

I think the best way to do it is to have one function exported for Python to call, as described above, and one action to write a python file in the plugins or Reaper folder. This will be similar to how Reaper exports the reaper_plugin_functions.h file. This means nothing new is added to the installer and the python module is always up-to-date, or can be generated again if not.

[Jeff0S]

From swstim on December 14, 2011 07:49:50

Yeah for sure add this sort of thing to SWS. While I understand what you mean by exporting functions, have you considered using:

// register("myAPIfunc",funcaddress) then other plug-ins can use GetFunc("myAPIfunc")
// (use "-myAPIfunc" to unregister)

(from reaper_plugin_functions.h)

Then maybe all you have to do is call RPR_SomeFunc() in Python and it automatically sets up the call? Schwa would know about this, I can ask him if you like.

As an added bonus then functions could be available to other C++ Reaper extensions.

[Jeff0S]

From fingersmcgarnickle on December 14, 2011 11:52:35

Hmmm... but you still need the function signature. Python needs to know the calling convention, parameters and return type. So there still needs to be some python ctypes code to call the function, which the inbuilt ReaScript code would not know.

[Jeff0S]

From swstim on December 14, 2011 12:07:25

Right, I wonder if there's a way that you could "communicate" the function sig to reaper and have it spit it out into the same place it puts all the RPR_ function signatures. (Which is where we need help from schwa) There's already something in place in Reaper for it, it would be nice if we could leverage it in this situation.

[Jeff0S]

From fingersmcgarnickle on December 14, 2011 12:44:38

That would be the file reaper_python.py in the new 4.14 pre-releases. It has all the ctypes code in there for each RPR function. It is now installed as part of Reaper (not generated). The idea would be to generate a new file which does something similar to reaper_python.py.

I guess we could ask Schwa how he generates the reaper_python.py file. We couldn't extend this module, just create another similar one.

I agree it would be nice to use existing Reaper functionality for this, but I can't really see a way to do this with the new way ReaScript is implemented.

Also, the functions exposed would just be the basis for helper python code to stop memory leaks and make it easy to use. For example a function like openMidiTake would alloc memory and a function closeMidiTake would free it. Expecting ReaScripters to handle this sort of stuff is not ideal. So a python class which opens a midi take on construction and closes it on deletion is needed.

[Jeff0S]

From schw...@gmail.com on December 14, 2011 14:23:06

We explored a lot of different ways to do the embedding and settled on what is in REAPER 4.14: a static .py module that wraps each function, and a dynamic table of function addresses that is generated at run-time. The extension could do the same thing: package a reaper_sws.py module and generate a run-time function address table. I think we could share the compile-time script that generates reaper_python.py from metadata. I'm happy to answer any questions about why/how we implemented this, either here or on the REAPER forums.

[Jeff0S]

From schw...@gmail.com on December 14, 2011 15:25:23

Thinking more, REAPER could put the sws functions into the single dynamic function address table. The extension could package reaper_sws.py, generated at compile time, similar to reaper_python.py. At run time, the extension could register reascript export functions with REAPER, so that REAPER can add those entries to the dynamic function address table. reaper_python.py currently keeps a file-local array with those addresses, all we would have to do is expose that array so that reaper_sws.py could access it.

[Jeff0S]

From fingersmcgarnickle on December 14, 2011 23:58:02

That sounds like a nicer way to do it. At the moment in reaper_python.py there is a dictionary _ft, keyed by the function name. So, maybe REAPER could add any registered API functions to that table (as Tim describes above). Then in reaper_sws.py we just import reaper_python, pull the function addresses from the table and write/generate the ctypes code for the functions.

[Jeff0S]

From schw...@gmail.com on December 15, 2011 05:06:10

Right. We'll make the change to the next REAPER release so that extension functions registered with "myAPIfunc" are added to the function address table, and we'll add an accessor function for _ft. What you guys will need to do is generate reaper_sws.py at compile time.

[Jeff0S]

From schw...@gmail.com on December 15, 2011 05:24:58

Correction: the comment is wrong in the REAPER API documentation. If you want to register/expose a function called myfunc() for reascript or other extensions to use, the syntax is register("API_myfunc"). Other extensions then get the function pointer with GetFunc("myfunc"). reascript users would get the function with RPR_myfunc.

Of course, other extensions will need your header in order to know the function signature, and reascript users will need your .py module, which contains the actual RPR_myfunc wrapper definition.

[Jeff0S]

From pyt...@yahoo.com on December 15, 2011 06:38:32

WOW !!! I hope this all works out.., it would open so many possibilities.

[Jeff0S]

From schw...@gmail.com on December 15, 2011 07:42:11

http://www.landoleet.org/dev/sws/ has a test build of REAPER:

Extension function addresses can be added with "API_myfunc" as before.

Extension function declarations and help text can be added with "APIdef_myfunc". Generate the API C++ header from REAPER to see more information about how to do this. After you add the declarations/help, it will be written to the API C++ header and the generated ReaScript documentation.

These functions will be added to the run-time function table. A python module that imports reaper_python.py can use rpr_getfp(myfunc) to get the function address.

Parameter wrapping/unwrapping functions in reaper_python.py are exposed to other python modules.

reascript_python.pl is what we run at compile-time to parse the exported REAPER functions and generate reaper_python.py. It is scanning a particular .cpp file for this struct:

APIdef g_apidefs[] =
{
{ APIFUNC(functionname), "rettype", "parmtype1,parmtype2,..." },
};

Each line can contain additional information, such as function names and help (for your programming convenience), but only the name, return type, and parameter types will be parsed by the script.

Yes, that is a Perl script reading C++ to generate Python. Feel free to edit the script however you like.

Let me know if anything seems wrong or doesn't make sense!

[Jeff0S]

From fingersmcgarnickle on December 15, 2011 12:32:48

That was quick! Thanks Schwa, I'll give it a go.

[Jeff0S]

From jeffos...@gmail.com on December 15, 2011 14:07:02

Thank you schwa!