GenTable

Gentable displays the contents of a function table, multiple tables, or files. Function tables that have their identifier active() set to one, and use a negative GEN05, GEN07 or GEN02 can be edited by clicking and dragging on the table. Only tables of size less or equal to 16384 points can be manually edited. If you wish to save any tables that you create you can use one of Csound's built-in table saving opcode "ftsave". If you need only display the contents of a static sound file from disk, use soundfiler as it will be fast and use less CPU. If on the other hand you wish to create some user editable envelopes, or display FFT or live waveform data use table.

gentable ampRange(min, max, tableNumber, quantise), bounds(x, y, width, height), tableNumber(val), tableColour:N("colour1"), tableBackgroundColour("colour"), tableGridColour("colour"), file("filename"), scrubberPosition(val), sampleRange(min, max), sampleRange(min, max), fill(val), outlineThickness(value), identChannel("channel"), alpha(val), parent(val), channel("chan"), visible(val), rotate(radians, pivotx, pivoty), rotate(radians, pivotx, pivoty), toFront(), moveBehind("widgetName"), active(val),

Specific Identifiers

ampRange(min, max, tableNumber, quantise) Sets the amplitude range(Y-axis) for a particular table. Min and Max are the minimum and maximum values. Quantise will set the resolution of the Y axis for editing. For example, if quantise is set to 1, all points added to the table will be quantised to integer values. If quantise matches the dynamic range of the table, the table will be drawn as a grid of on/off switches. If only one ampRange() identifier is used, a table number of -1 can be set so that each table displayed will share the same amp range.

If the table is not active this identifier can usually be left out. If it is active, and therefore editable, it is important to use this identifier. Failure to do so may cause unexpected result.

bounds(x, y, width, height) integer values that set position and size on screen(in pixels).

tableNumber(val) Sets the table/tables to be displayed. If multiple tables are specified the tables will be superimposed on top of each other. If multiple tables are specified with a colon between then the tables will be stacked on top of each other along the Y-axis, e.g., tableNumber(1:2:3:4). Note changing table numbers at runtime will incur a slight performance here. It's simpler to copy the contents of a source table to the table gentable or soundfiler are displaying.

tableColour:N("colour1") Sets the colour of the table's waveform, where N is the table number, starting at 0 for the first table. If you leave this identifier out default colours will be chosen for the tables. If the table size is equal or less than two, the colours passed to tableColour() will form a gradient fill or three colours.

The tableColour() identifier will not work with RGBA/RGB values. You must instead use a valid CSS colour name.

tableBackgroundColour("colour") This sets the global background colour. Any CSS or HTML colour string can be passed to this identifier. The colour identifier can also be passed an RBG, or RGBA value. All channel values must be between 0 and 255. For instance colour(0, 0, 255) will create a blue, while colour(0, 255, 0, 255) will create a green with an alpha channel set to full.

The default value for the background colour is rgb(10, 10, 10). If you are superimposing tables on top of each other only one can be seen at any time when using the default background colour. If you wish to show all tables at the same time use a colour with an alpha value. Tables with no alpha channels are drawn faster and use less CPU.

tableGridColour("colour") Sets the colour of the grid to be drawn. If you don't want a grid to be drawn set this colour to transparent, i.e., 0,0,0,0. See above for details on valid colours.

file("filename") This identifier is used across a number of widgets.

combobox and listbox - will load lines from a file as selectable items.
gentable and soundfiler - will load a sound file to display
image - will load an iamge to display (PNG/JPG/SVG)
infobutton - sets the file to display when the button is clicked This can be a local html file, or a URL.
texteditor - sets the file to load, should be a text file.

If a full file path is not given, file() will search in the current directory, i.e., the directory that contains the csd file that is open. It is best to keep all files in the same directory as your csd file. If you wish to keep them in a separate folder use relative paths, i.e, ../../folder.

Avoid absolute path at all costs. Failure to do so will most likely problems with your instruments as soon as you share them.

scrubberPosition(val) Sets the scrubber position where val is an integer value in samples. If you wish to update the scrubberPosition in real time use the cabbageSet opcodes. gentable can also take an optional parameter, tableNum which determine which table the scrubber will be placed on, if you are using multiple table.

sampleRange(min, max) Set the initial range of the samples. For example, sampleRange(0, 255) will cause the gentable widget to display only the first 255 samples from a given table.

fill(val) This will turn on or off the waveform fill. By default this is set to 1, therefore all table will fill in their envelopes.

outlineThickness(value) Sets the thickness of the widget's outline. Set to 0 to disable.

With regards to gentable, this sets the thickness of the waveform's outline. If you are drawing spectrograms setting this to 0 will speed up the process and reduce CPU drain.

Common Identifiers

identChannel("channel") [!!! DEPRECATED !!!] Although identifier channels still work, they are no longer supported. Please use the new guiMode("queue") system and the cabbageGet and cabbageSet opcodes instead. They are far more efficient then identifiers channel.

alpha(val) A value between 0 and 1 will set the alpha blend value for the entire component. Can be useful if you need to fade widgets in and out.

parent(val) This identifier is can be to set a widget's parent. It should only be used when creating widgets dynamically using the cabbageCreate opcode. See plants for more details.

channel("chan") or channel("chan1", "chan2") in the case of widgets that accept two channels such as xypad, soundfiler and range widgets. channel() accepts a string/s that names the channel/s that Cabbage will communicate with Csound on. The current value of this widget can be retrieved in Csound using a chnget, or a cabbageGetValue opcode. Its value can be set using the cabbageSet, or cabbageSetValue opcodes. hrange, vrange, xypad, and soundfiler all take two channels:

hrange, vrange : channel("min", "max") - min and max values

xypad : channel("x", "y") - x and y values

soundfiler : channel("start", "length") - start time and length of user selection, in samples

Channels named should start with a letter and cannot have any white spaces. Note that all widgets should have a unique channel name.

visible(val) A value of 0 will cause the widget to become invisible. Widgets have their visibility set to 1 by default.

rotate(radians, pivotx, pivoty) Rotates the widget by a number of radians(2xPI=full rotation). pivotx and pivoty will determine the rotation pivot points, where 0, 0 represents the component's top-left position.

toFront() Brings a widget to the front of the z order. This identifier takes no arguments and is only intended for use within the Csound orchestra. it makes no sense to call it when declaring the widget.

moveBehind("widgetName") Moves a widget directly behind another. This identifier should only ever be called from your Csound orchestra using a cabbageSet opcode.

This only works with widgets or plants that have the same parent.

active(val) Will deactivate a control if 0 is passed. Controls which are deactivate can still be updated from Csound.

If you need to redraw tables quickly, make sure they don't use negative GEN routines as it will seriously slow down redrawing.

Example

<Cabbage>
form caption("Gentable Example") size(400, 650), guiMode("queue"), colour(2, 145, 209), pluginId("def1")
gentable bounds(13, 7, 370, 200), channel("gentable1"), outlineThickness(3), tableNumber(1.0), tableGridColour(155, 155, 155, 255) tableBackgroundColour(0,0,0,0) tableColour:0(147, 210, 0, 255)
hslider bounds(14, 212, 368, 40), channel("harm1"), range(0, 1, 1, 1, 0.01), textColour(255, 255, 255, 255), text("Harm1")
hslider bounds(14, 244, 368, 40), channel("harm2"), range(0, 1, 0, 1, 0.01), textColour(255, 255, 255, 255), text("Harm2")
hslider bounds(14, 276, 368, 40), channel("harm3"), range(0, 1, 0, 1, 0.01), textColour(255, 255, 255, 255), text("Harm3")
hslider bounds(14, 308, 368, 40), channel("harm4"), range(0, 1, 0, 1, 0.01), textColour(255, 255, 255, 255), text("Harm4")
hslider bounds(14, 340, 368, 40), channel("harm5"), range(0, 1, 0, 1, 0.01), textColour(255, 255, 255, 255), text("Harm5")
checkbox bounds(16, 380, 120, 20), channel("normal"), text("Normalise"), value(1), fontColour:1(255, 255, 255, 255)
checkbox bounds(140, 380, 120, 20), channel("fill"), text("Fill Table"), value(1), fontColour:1(255, 255, 255, 255)
texteditor bounds(16, 410, 367, 219) channel("infoText"), wrap(1), text("A 'GEN' table widget will display the contents of a sound function table. In this example, a basic sine wave is stored in function table 1, which is defined in the CsScore section. Whenever a slider is changed, instr 1 will trigger the 'UpdateTable' instrument, which in turns creates a new function shape accordingly. It writes the shape to the same table number as defined when declaring the gentable widget.", "Although a gentable can be passed new function tables at run-time, it might incur a slight performance hit especially if the new function table is a larger. It is a better idea is to just copy the contents of one table to another using the table copy opcodes in Csound.")
</Cabbage>
<CsoundSynthesizer>
<CsOptions>
-d -n -m0d
</CsOptions>
<CsInstruments>
;sr is set by the host
ksmps       =   32
nchnls      =   2
0dbfs       =   1


; Rory Walsh 2021 
;
; License: CC0 1.0 Universal
; You can copy, modify, and distribute this file, 
; even for commercial purposes, all without asking permission. 


instr   1

    SText  = "A 'GEN' table widget will display the contents of a sound function table. In this example, a basic sine wave is stored in function table 1, which is defined in the CsScore section. Whenever a slider is changed, instr 1 will trigger the 'UpdateTable' instrument, which in turns creates a new function shape accordingly. It writes the shape to the same table number as defined when declaring the gentable widget.\n\nAlthough a gentable can be passed new function tables at run-time, it might incur a slight performance hit especially if the new function table is a larger. It is a better idea is to just copy the contents of one table to another using the table copy opcodes in Csound."
    cabbageSet "infoText", "text", SText

    ;toggle fill
    kFill, kTrig cabbageGetValue "fill"
    cabbageSet kTrig, "gentable1", "fill", kFill 

    k1 chnget "harm1"
    k2 chnget "harm2"
    k3 chnget "harm3"
    k4 chnget "harm4"
    k5 chnget "harm5"

    a1 oscili .5, 200, 1
    outs a1, a1

    kChanged changed k1, k2, k3, k4, k5
    if kChanged==1 then
        ;if a slider changes trigger instrument 2 to update table
        event "i", "UpdateTable", 0, .01, k1, k2, k3, k4, k5
    endif

endin

instr UpdateTable
    iNormal = (chnget:i("normal")==0 ? -1 : 1)
    iTable  ftgen   1, 0,   1024, 10*iNormal, p4, p5, p6, p7, p8
    cabbageSet  "gentable1", "tableNumber", 1   ; update table display
endin

</CsInstruments>
<CsScore>
f1 0 1024 10 1
i1 0 [3600*24*7]
</CsScore>
</CsoundSynthesizer>