Contributing To the MRuby-Zest Toolkit (and/or the zyn-fusion GUI)
==================================================================


When working with mruby-zest a number of concepts are useful.
LAC paper: https://lac.linuxaudio.org/2018/pdf/38-paper.pdf

This file contains some basic developer level information on Linux.

In theory you shouldn't have to mess with anything in deps/.

src/mruby-zest
--------------

'src/mruby-zest' contains all the widget code with 'qml/' containing the
 base set of widgets and
'example/' containing widgets specific to Zyn-Fusion.

These widgets use a qml like formatting, but use ruby code to define drawing
routines, event handling, etc.
When working with these widgets you're likely going to want to enable code
hotloading. Code hotloading makes the GUI reload any changed widget and update
the running GUI without restarting. Saving a file with errors may result in the
running GUI crashing, but that's not a major issue as the GUI is out-of-process
compared to the synthesis backend.

To enable code hotloading, simply use the `linux-hotload` target instead of the
default one: 

--------------------------------------------------------------------------------
make linux-hotload
--------------------------------------------------------------------------------

This will slow down the GUI's execution somewhat as the GUI will
occasionally probe widget .qml files to see if they need to be
reloaded.


src/mruby-widget-lib
--------------------

Basically if it's not a widget, but something that the toolkit needs to manage,
e.g. draw order it's handled in this module. You'll likely not have to mess
with this module much.

src/osc-bridge
--------------

This is the module that handles all communications with external processes via
OSC. This code is reasonably complete, but it also handles the OSC schema which
specifies a lot of information from the zynaddsubfx core (without needing to
ask about it over UDP/OSC). Once in a while 'src/osc-bridge/schema/test.json'
will need to be updated, but that only needs to be done if the rtosc based
dispatch tree is getting modified (subject for later details)


Running the app
---------------

In one terminal start a zyn instance without a GUI bound to it with a known UDP
port:

--------------------------------------------------------------------------------
zynaddsubfx -U -P 1337
--------------------------------------------------------------------------------

Add -I null -O null if you're using your sound device for other stuff during
dev (e.g. listening to some music).


Then from the mruby-zest-build repo:

--------------------------------------------------------------------------------
make linux-hotload
make run
--------------------------------------------------------------------------------

This will build the GUI and connect it to the remote zyn.

Ok, now the GUI is running and it should be connected to a running instance of
zynaddsubfx. Now what?
Well, let's do a change and verify that everything is working correctly.

First, open up 'src/mruby-zest/qml/Knob.qml'

This defines a knob, it derives from the valuator base class.
Let's take a look at the draw() function.
Within the draw function add `background color("ffffff")` and then save the
file.
If hotloading is working you should see the background behind each one of the
knobs change to white. If you aren't using hotloading, then closing and running
`make && make run` should get you to the same spot.

From there, it's possible to probe other parts of the drawing process.
Comment out the background change with `#` and then let's try changing the
color of something that is drawn.

Go to the first 'vg.path' section and change the fill_color to
`color("550000")` and in the next 'vg.path' section change the color to
`color(:red)`.
Save the file and you should now see the new drawing changes in the live GUI.
This is just a quick example, but you should get the idea.

In general theme information is stored over in
'src/mruby-zest/mrblib/draw-common.rb', but colors can also be defined inline.

If you're working on basic GUI drawing code, then I'd recommend taking a look
at some quick tutorial on javascripts canvas as that's what the nanovg opengl
render is based off of (mruby-zest uses nanovg for rendering the full UI with
vector graphics). Once you have a feel for it have fun.
