Skip to content

Latest commit

 

History

History
123 lines (90 loc) · 4.73 KB

contributing.adoc

File metadata and controls

123 lines (90 loc) · 4.73 KB
Raw

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 for Linux os and windows-hotload for windows os target instead of the default one:

For Linux:

make linux-hotload

For Windows:

make windows-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:

For Linux:

make linux-hotload
make run

For Windows:

make windows-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.