The Heavy Audio Programming Language Specification - GUI Intermediate Representation
GUI Intermediate Representation
GUI elements and objects in PD patchers are translated into an intermediate representation (IR) that generators and other integrations can use to create a custom user interface.
The top level GraphRoot is a dictionary that consists of four keys:
- version
- size
- graphs
- objects
version
The version, e.g. 0.14.0, indicates the format of the IR file. The version is tied to the release of heavy. It is only stored in the root graph.
size
Width (x) and height (y) can be used to determine the (relative) size of the generated GUI
graphs
The list of other graphs that are nested in the current graph.
A Graph can have the following keys:
- position
- gop_start
- gop_size
- graphs
- objects
The position are the starting coordinates inside the parent graph. Graph on Parent (GoP) start and size are relative to the local coordinates.
Each graph can contain other graphs and objects. If a graph, including its subgraphs, does not contain any objects it will be filtered out of the GUI IR to minimize the result. Subgraphs that are outside the local GoP are also removed.
Example of a project containing a single subpatch with a basic canvas object:
{
"objects": [],
"graphs": [
{
"objects": [
{
"type": "canvas",
"position": {
"x": -52,
"y": -29
},
"size": {
"x": 329,
"y": 224
},
"label": null,
"bg_color": "#006200"
}
],
"graphs": [],
"position": {
"x": 110,
"y": 94
},
"gop_start": {
"x": 0,
"y": 0
},
"gop_size": {
"x": 200,
"y": 140
}
}
],
"size": {
"x": 734,
"y": 565
},
"version": "0.14.0"
}
objects
The list of objects on this level of the GUI graph. Each object lists its type, position relative to the GoP window and object size. The parser filters objects that are not in view of the GoP in order to minimize the graph.
Interactive objects need to be connected to an externed parameter and some objects optionally have a label attached to them.
The order of objects determines the visibility where top-to-bottom in the list equals back-to-front.
The following GUI objects are currently supported:
Comment
Floating text comment. Size-x/width is extrapolated from the string length and default font size.
{
"type": "comment",
"position": {
"x": 131,
"y": 86
},
"size": {
"x": 10,
"y": 120
},
"text": "some text here"
}
Canvas
Basic colored square.
{
"type": "canvas",
"position": {
"x": -89,
"y": -83
},
"size": {
"x": 521,
"y": 343
},
"label": null,
"bg_color": "#0daa00"
}
Bang
Bang or bng object.
{
"type": "bang",
"position": {
"x": 117,
"y": 45
},
"size": {
"x": 25,
"y": 25
},
"parameter": "testparam",
"label": {
"text": "testbang",
"position": {
"x": 17,
"y": 7
},
"color": "#ff0018",
"font": 0,
"font_size": 10
},
"fg_color": "white",
"bg_color": "#191919"
}
Toggle
Toggle or tgl object.
{
"type": "toggle",
"position": {
"x": 51,
"y": 82
},
"size": {
"x": 25,
"y": 25
},
"parameter": "testparam",
"label": {
"text": "testtoggle",
"position": {
"x": 17,
"y": 7
},
"color": "#00ff0d",
"font": 0,
"font_size": 10
},
"fg_color": "white",
"bg_color": "#191919",
"non_zero": 1.2
}
Radio
vradio and hradio objects.
The configuration for vertical and horizontal radio buttons is identical.
{
"type": "hradio",
"position": {
"x": 139,
"y": 69
},
"size": {
"x": 180,
"y": 20
},
"parameter": "testparam",
"label": {
"text": "testradio",
"position": {
"x": 1,
"y": -8
},
"color": "#ffec00",
"font": 0,
"font_size": 10
},
"fg_color": "white",
"bg_color": "#191919",
"options": 9
}
Slider
vsl and hsl objects.
The configuration for vertical and horizontal radio sliders is identical.
{
"type": "hslider",
"position": {
"x": 110,
"y": 90
},
"size": {
"x": 173,
"y": 17
},
"parameter": "testparam",
"label": {
"text": "testslider",
"position": {
"x": 18,
"y": -28
},
"color": "#f11fff",
"font": 0,
"font_size": 50
},
"min": 36.0,
"max": 127.0,
"fg_color": "white",
"bg_color": "#191919",
"logarithmic": false,
"steady": true
}
Knob
Originating from ELSE library.
{
"type": "knob",
"position": {
"x": 57,
"y": 79
},
"size": {
"x": 136,
"y": 136
},
"parameter": "testparam",
"label_size": 11,
"label_pos": {
"x": 6,
"y": -15
},
"label_show": 1,
"min": 5.5,
"max": 127.0,
"fg_color": "white",
"bg_color": "#191919",
"init_val": 5.5,
"ang_range": 270,
"ang_offset": 2,
"log_mode": "exp",
"exp_fact": 12.0,
"discrete": true,
"ticks": true,
"steps": 11,
"circular": true,
"jump": false,
"square": false,
"arc": "#626262",
"arc_start": 5.5,
"arc_show": false
}
Number
Number box or nbx object.
{
"type": "number",
"position": {
"x": 170,
"y": 46
},
"size": {
"x": 40,
"y": 16
},
"parameter": "testparam",
"label": {
"text": "testnumber",
"position": {
"x": -5,
"y": -8
},
"color": "#ff0f00",
"font": 0,
"font_size": 10
},
"fg_color": "white",
"bg_color": "#191919",
"log_mode": true,
"log_height": 0
}
Float
Float or floatatom object.