gui2dpf templates (#354)

* start working on gui2dpf templates and integration

* merge recursive functions

* move nanovg render to module

* abstract generated send/receive to function call

* implement widget generation and some missing gui type features

* add @hv_event receiver to DPF

* get size from gui_json; add label to canvas object

* update pdvg; tweak knob font_height

* fix ir_file path; tweak font sizes to match plugdata rendering

* escape quotes in comment string

* tweak width of comment object to match plugdata rendering

* deal with misaligned parameter indices

* match on literal empty string; use text.replace to appease mypy

* tweak float font height

* update changelog

* add ADR

Author: dromer

CHANGELOG.md

@@ -11,6 +11,8 @@ Features:
 * Only parse GUI with `--gui` flag
 * Port objects from cyclone
 * Port `pdnam~` external using `MicroNAM`
+* DPF: support `@hv_event` parameters
+* DPF: Generate optional NanoVG UI code from `pd2gui` parser
 
 Bugfixes:
 
@@ -23,6 +25,7 @@ Bugfixes:
 Refactor:
 
 * Migrate to Pathlib (note: Generator signature has changed!)
+* GUI IR: stable IDs for graphs/canvas/comments; updated float/number fields; use specific GUI IR filename
 
 Docs:
 

docs/adr/ADR-006-gui2dpf-Templates.md

@@ -0,0 +1,28 @@
+# ADR-006: gui2dpf Templates
+
+Date: 2026-05-13
+Issue: https://github.com/Wasted-Audio/hvcc/issues/296
+
+## Context
+
+A new [PDVG](https://github.com/Wasted-Audio/PDVG) widget library for DPF was created, which implements Plugdata GUI objects using NanoVG.
+
+We can now use this widget library in combination with the GUI JSON, created by the pd2gui stage in hvcc, to generate an emulated UI for the DPF generator.
+
+## Decision
+
+We create a new c2dpf code-path, with a set of templates, to combine the GUI JSON with the new widget library.
+
+In order to have backwards compatibility with the previous ImGui UI implementation we introduce a new `DPFUIType` in the meta JSON. This allows to keep the old boolean behavior, which selects ImGui as the GUI type, but allows to extend it using integer enumeration. This could allow for other UI extensions in the future as well.
+
+We add the ability to create `@hv_event` based parameters to allow for the same behavior as `[bang]` object. This brings DPF on par with Unity and Javascript implementations.
+
+The GUI JSON will need some minor modifications to better align to the PDVG requirements.
+
+## MVP Definition
+
+The user should be able to generate a GUI for their DPF plugins that matches the basic Plugdata UI as close as possible.
+
+## Future Improvements
+
+More GUI objects and better object behavior may be added in the future. More accuracy in the layout and design may also be required.

docs/generators/custom.md

@@ -32,7 +32,7 @@ class ExampleHvccGenerator(Generator):
         c_src_dir: Path,
         out_dir: Path,
         externs: ExternInfo,
-        patch_name: Optional[str] = None,
+        patch_name: str,
         patch_meta: Meta = Meta(),
         num_input_channels: int = 0,
         num_output_channels: int = 0,

docs/generators/dpf.md

@@ -49,6 +49,11 @@ Other special types can give additional information to the host:
 * `log` - hints `kParameterIsLogarithmic`
 * `log_hz` - unit `Hz` - hints `kParameterIsLogarithmic`
 
+### Events
+
+If you want to receive a bang use `@hv_event` instead of `@hv_param` like `[r banger @hv_event]`.
+On the plugin side this behaves like the `trig` type.
+
 ## Metadata
 
 An accompanying metadata.json file can be included to set additional plugin settings.

docs/getting-started/patching.md

@@ -66,7 +66,7 @@ An intermediate result GUI json is created containing these objects with their l
 
 ## Exposing Events
 
-All (control) `[receive]` and `[r]` objects annotated with `@hv_event` will be exposed as events in the Unity and Javascript targets only.
+All (control) `[receive]` and `[r]` objects annotated with `@hv_event` will be exposed as events in the Unity, Javascript and DPF targets only.
 
 ![events](../img/docs_exposed_events.png)
 

hvcc/compiler.py

@@ -257,12 +257,15 @@ def compile_dataflow(
         search_paths=search_paths,
         verbose=verbose)
 
+    # ensure that the ir filenames have no funky characters in it
+    subst_name = re.sub(r'\W', '_', patch_name)
+
     if gui:
         if verbose:
             print("--> Generating GUI IR")
         results.root["pd2gui"] = pd2gui.pd2gui.compile(
             pd_path=in_path,
-            ir_dir=Path(out_dir, "ir"),
+            ir_file=Path(out_dir, "ir", f"{subst_name}.heavy.gui.json"),
             search_paths=search_paths,
             verbose=verbose)
 
@@ -272,7 +275,6 @@ def compile_dataflow(
     if response.notifs.has_error:
         return results
 
-    subst_name = re.sub(r'\W', '_', patch_name)
     results.root["hv2ir"] = hv2ir.hv2ir.compile(
         hv_file=Path(response.out_dir, response.out_file),
         # ensure that the ir filename has no funky characters in it

hvcc/generators/c2daisy/c2daisy.py

@@ -51,7 +51,7 @@ def compile(
         c_src_dir: Path,
         out_dir: Path,
         externs: ExternInfo,
-        patch_name: Optional[str] = None,
+        patch_name: str,
         patch_meta: Meta = Meta(),
         num_input_channels: int = 0,
         num_output_channels: int = 0,

hvcc/generators/c2dpf/c2dpf.py

@@ -25,7 +25,8 @@
 
 from hvcc.interpreters.pd2hv.NotificationEnum import NotificationEnum
 from hvcc.types.compiler import Generator, CompilerResp, CompilerMsg, CompilerNotif, ExternInfo
-from hvcc.types.meta import Meta, DPF
+from hvcc.types.meta import Meta, DPF, DPFUIType, DPFUISize
+from .nanovg_render import open_gui_json, nanovg_render
 
 
 class c2dpf(Generator):
@@ -38,7 +39,7 @@ def compile(
         c_src_dir: Path,
         out_dir: Path,
         externs: ExternInfo,
-        patch_name: Optional[str] = None,
+        patch_name: str,
         patch_meta: Meta = Meta(),
         num_input_channels: int = 0,
         num_output_channels: int = 0,
@@ -51,6 +52,8 @@ def compile(
         out_dir = Path(out_dir, "plugin")
         receiver_list = externs.parameters.inParam
         sender_list = externs.parameters.outParam
+        event_list = externs.events.inEvent
+        out_event_list = externs.events.outEvent
 
         dpf_meta: DPF = patch_meta.dpf
         dpf_path = dpf_meta.dpf_path
@@ -71,6 +74,13 @@ def compile(
             source_dir = Path(out_dir, "source")
             shutil.copytree(c_src_dir, source_dir)
 
+            if dpf_meta.enable_ui == DPFUIType.NANOVG:
+                gui_json = open_gui_json(patch_name, c_src_dir)
+                dpf_meta.ui_size = DPFUISize(
+                    width=gui_json.size.x,
+                    height=gui_json.size.y
+                )
+
             # initialize the jinja template environment
             env = jinja2.Environment()
             env.filters["uniqueid"] = filter_uniqueid
@@ -89,6 +99,8 @@ def compile(
                     num_output_channels=num_output_channels,
                     receivers=receiver_list,
                     senders=sender_list,
+                    events=event_list,
+                    out_events=out_event_list,
                     copyright=copyright_c))
             dpf_cpp_path = Path(source_dir, f"HeavyDPF_{patch_name}.cpp")
             with open(dpf_cpp_path, "w") as f:
@@ -100,18 +112,48 @@ def compile(
                     num_output_channels=num_output_channels,
                     receivers=receiver_list,
                     senders=sender_list,
+                    events=event_list,
+                    out_events=out_event_list,
                     pool_sizes_kb=externs.memoryPoolSizesKb,
                     copyright=copyright_c))
-            if dpf_meta.enable_ui:
+            if dpf_meta.enable_ui == DPFUIType.IMGUI:
                 dpf_ui_path = Path(source_dir, f"HeavyDPF_{patch_name}_UI.cpp")
                 with open(dpf_ui_path, "w") as f:
-                    f.write(env.get_template("HeavyDPF_UI.cpp").render(
+                    f.write(env.get_template("HeavyDPF_ImGui_UI.cpp").render(
                         name=patch_name,
                         meta=dpf_meta,
                         class_name=f"HeavyDPF_{patch_name}",
                         receivers=receiver_list,
                         senders=sender_list,
                         copyright=copyright_c))
+            elif dpf_meta.enable_ui == DPFUIType.NANOVG:
+                gui_json, widgets, gui_objects_render = nanovg_render(
+                    patch_name, c_src_dir, env, receiver_list, sender_list
+                )
+
+                dpf_ui_header = Path(source_dir, f"HeavyDPF_{patch_name}_UI.hpp")
+                with open(dpf_ui_header, "w") as f:
+                    f.write(env.get_template("HeavyDPF_NanoVG_UI.hpp").render(
+                        name=patch_name,
+                        meta=dpf_meta,
+                        class_name=f"HeavyDPF_{patch_name}_UI",
+                        gui_json=gui_json,
+                        widgets=widgets,
+                        copyright=copyright_c))
+                dpf_ui_path = Path(source_dir, f"HeavyDPF_{patch_name}_UI.cpp")
+                with open(dpf_ui_path, "w") as f:
+                    f.write(env.get_template("HeavyDPF_NanoVG_UI.cpp").render(
+                        name=patch_name,
+                        meta=dpf_meta,
+                        class_name=f"HeavyDPF_{patch_name}_UI",
+                        gui_json=gui_json,
+                        widgets=widgets,
+                        gui_objects=gui_objects_render,
+                        receivers=receiver_list,
+                        senders=sender_list,
+                        events=event_list,
+                        copyright=copyright_c))
+
             dpf_h_path = Path(source_dir, "DistrhoPluginInfo.h")
             with open(dpf_h_path, "w") as f:
                 f.write(env.get_template("DistrhoPluginInfo.h").render(

hvcc/generators/c2dpf/nanovg_render.py

@@ -0,0 +1,84 @@
+import json
+
+from pathlib import Path
+
+import jinja2
+
+from hvcc.types.GUI import Canvas, Comment, GraphRoot, Graph, GUIObjects
+
+
+def open_gui_json(
+    patch_name: str,
+    c_src_dir: Path,
+) -> GraphRoot:
+
+    # load GUI from json file
+    gui_json_path = Path(c_src_dir, "../ir/", f"{patch_name}.heavy.gui.json")
+    with open(gui_json_path, "r") as f:
+        gui_json = GraphRoot(**json.load(f))
+
+    return gui_json
+
+
+def nanovg_render(
+    patch_name: str,
+    c_src_dir: Path,
+    env: jinja2.Environment,
+    recv_list: list,
+    send_list: list
+) -> tuple[
+    GraphRoot,
+    dict[str, list[str]],
+    list[str]
+]:
+    """ Generate nanovg components from the GUI json
+    """
+    gui_json = open_gui_json(patch_name, c_src_dir)
+
+    # widget overview
+    widgets: dict[str, list[str]] = {
+        "graph": [],
+        "canvas": [],
+        "comment": [],
+        "bang": [],
+        "toggle": [],
+        "vradio": [],
+        "hradio": [],
+        "vslider": [],
+        "hslider": [],
+        "knob": [],
+        "number": [],
+        "float": []
+    }
+
+    # render gui objects
+    gui_objects_render = []
+
+    def generate_gui_objects(graphs: list[Graph], objects: list[GUIObjects], parent: str):
+        for w in objects:
+            widgets[w.type].append(w.id if isinstance(w, (Canvas, Comment)) else w.parameter)
+
+        gui_objects_render.append(env.get_template("gui_objects.cpp").render(
+            parent=parent,
+            gui_objects=objects,
+            receivers=recv_list,
+            senders=send_list
+        ))
+
+        for graph in graphs:
+            widgets["graph"].append(graph.id)
+
+            gui_objects_render.append(
+                f"""
+    // subpatch
+    {graph.id} = new PDSubpatch({parent});
+    {graph.id}->setSize({graph.gop_size.x} * scaleFactor, {graph.gop_size.y} * scaleFactor);
+    {graph.id}->setAbsolutePos({graph.position.x} * scaleFactor, {graph.position.y} * scaleFactor);
+    {parent}->addManagedChild({graph.id});
+                """
+                    )
+            generate_gui_objects(graph.graphs, graph.objects, graph.id)
+
+    generate_gui_objects(gui_json.graphs, gui_json.objects, "mainPatch")
+
+    return gui_json, widgets, gui_objects_render

hvcc/generators/c2dpf/templates/DistrhoPluginInfo.h

@@ -30,7 +30,7 @@
 #define DISTRHO_PLUGIN_NUM_INPUTS           {{num_input_channels}}
 #define DISTRHO_PLUGIN_NUM_OUTPUTS          {{num_output_channels}}
 #define DISTRHO_PLUGIN_IS_SYNTH             {{1 if num_output_channels > 0 and meta.midi_input > 0 else 0}}
-#define DISTRHO_PLUGIN_HAS_UI               {{1 if meta.enable_ui is sameas true else 0}}
+#define DISTRHO_PLUGIN_HAS_UI               {{1 if meta.enable_ui > 0 else 0}}
 #define DISTRHO_PLUGIN_IS_RT_SAFE           1
 #define DISTRHO_PLUGIN_WANT_PROGRAMS        0
 #define DISTRHO_PLUGIN_WANT_STATE           0
@@ -51,11 +51,16 @@
 // for level monitoring
 #define DISTRHO_PLUGIN_WANT_DIRECT_ACCESS   0
 
-{% if meta.enable_ui is sameas true %}
+{% if meta.enable_ui > 0 %}
 // if you are using a UI you'll probably want to modify these settings to your needs
+    {%- if meta.enable_ui == 1 %}
 #define DISTRHO_UI_USE_CUSTOM               1
 #define DISTRHO_UI_CUSTOM_INCLUDE_PATH      "DearImGui.hpp"
 #define DISTRHO_UI_CUSTOM_WIDGET_TYPE       DGL_NAMESPACE::ImGuiTopLevelWidget
+    {%- elif meta.enable_ui == 2 %}
+#define DISTRHO_UI_USE_NANOVG               1
+    {%- endif %}
+
     {%- if meta.ui_size != None %}
 #define DISTRHO_UI_DEFAULT_WIDTH            {{meta.ui_size.width}}
 #define DISTRHO_UI_DEFAULT_HEIGHT           {{meta.ui_size.height}}