Mozaic: Scripting Tips & Tricks

This is an old revision of the document!

This wiki page contains programming tips & tricks for Mozaic

Two dimensional Arrays
Multi dimensional Arrays
Store two positive Values into a single Variable
Store three unsigned Bytes into a single Variable
Some Best Practice Tips
Multi-Line Pad Labels
Use the SHIFT Button to toggle to HELP View
Use a Knob to toggle 16 Pads View to HELP View
Knob double-tap Support
Using Logic Operators in Expressions instead of IF cases
Using Inc and Dec in Expressions
Calculate Standard Chords from a Root Note
Include Snippets

<html>From -ki</html> Each variable in Mozaic is in fact an array with a maximum of 1024 elements. Scripting often needs two dimensional arrays, but the variables only offer one dimensional access.

Its is very easy to 'fold' two or more dimensions into a normal array if the row length is fixed:

  xMax = 16

  x = 2
  y = 5
  value = 42

  // write the value to position x,y : 
  twoDimStorage[ x + xMax *y] = value

Retrieval of values is done using the same folding:

  
  // retrieve value from 5,3
  x = 5
  y = 3
  value =   twoDimStorage[ x + xMax *y ]

Mozaics array length is limited to 1024, so 32×32 just fits - but 128×16 (often needed in midi programming) doesn‘t.

There is a single two dimensional array in Mozaic that fits this dimensions, the note state array. Since it is special, there are separate functions:

  ResetNoteState initValue         // Fills all 16x128 elements with the given value
  
  SetNoteState row, column, value  // Sets a value
  value = GetNoteState row, colum  // Retrieves the value

There is only one array of this kind, but sometimes you Need to store multiple values. In such a case, its possible to fold these values into a single value - see the tricks below:

The above folding can be expanded to multiple dimension, here an example for a 3 dimensional array folded into one dimensions:

  array[x + xMax * y + xMax*yMax *z] = value

Since Mozaic arrays are limited to 1024 elements, xMax * yMax * zMax needs to be less or equal 1024.

<html>From -ki</html> It is possible to store two positive values in a single variable if their product is less than 16.777.216 and they both have a known maximum value.

  maxA = 1000  // Maximum value for A plus one
  valA = 723   // allowed range 0 .. 999
  varB = 124   // allowed range 0 .. ~16000
  
  combinedValue = valA + valB * maxA

To later extract the values from their packed format use

  valA = combinedValue % maxA
  valB = Div combinedValue, maxA

<html>From <a href=“https://forum.audiob.us/discussion/comment/724913/#Comment_724913”>espiegel123 @ Audiobus Forum </a></html>

Storing of 3 unsigned bytes (J,K & L, each with the range of 0-255) into a single 24bit integer can be done by using the packing formular:

combinedValue = (J * 0x10000) + (K * 0x100) + (L)

This would pack the bytes 0xAA, 0xBB, 0xCC into the combined value 0xAABBCC

To unpack, you mask off the parts you don't want and then divide to shift things over. Mozaic has an Integer AND that you can use for masking things. Its operator is &.

To mask, use zero in the bytes you don't want and FF in the byte you want. For example, to turn 0xAACC into 0xAA00, do 0xAACC & 0xFF00. Now we can divide by 0x100 to shift our byte to the right two place. 0xAA00/0x100 = 0xAA

Dividing the masked numbers by 0x10000 will shift hex numbers four digits to the right and dividing by 0x100 will shift them two. So, 0xAA0000/0x10000 = 0xAA

If you want the middle byte of 0xAABBCC, do this 0xAABBCC & 0x00FF00, you end up with 0xBB00 divide the result by 0x100 to get 0xBB

You don't need the leading zeros, but I think it makes the code more understandable.

J = (combinedValue & 0xFF0000) / 0x10000 
K = (combinedValue & 0x00FF00) / 0x100
L = (combinedValue & 0x0000FF)

Its helpfull to add the version number right into the title label.
And also add this version number to the script title and patchname if uploaded / updated on PatchStorage so that script-users can notice the version change.
Add a short name to set the icon name. This helps when a project contains multiple Mozaic instances with different scripts
Visually unclutter the scripts gui
- Clear all unused title and knob labels by setting it to empty { }
- Position all knobs to 0
- Position the XY to 0,0

@OnLoad
  ShowLayout 0
  
  SetShortName {DUMMY}
  
  LabelPads { }
  LabelKnobs {My Dummy Script     v0.1}
  LabelXY { }
  
  for _knob = 0 to 9
    LabelKnob _knob, { }
    SetKnobValue _knob,0
  endfor
  SetXYValues 0,0
@End

<html>From -ki</html> You can force multiline pad labels by adding space-filled substrings.

There must be enough spaces to fill the rest of the current line
Too many spaces don't hinder, since mozaic will discard them infront of a new output line - this helps if the text infront of a line break has variable length
You can't force an empty line between two lines
One can use 14 dashes to split the pad into two labels. Don't forget the space infront and behind the dashes, its needed for line-break

@OnLoad
  LabelPad 0,{Line 1},{                     },{Line 2}
  LabelPad 1,{Upper},{ -------------- },{Lower}
@End

@Description
My Sample Plugin

This description will be shown on the HELP page. Longer
texts are possible, as the description box is scrollable.
@End

@OnLoad
  mainLayout = 0
  showsHelp = NO

  ShowLayout mainLayout
  LabelKnobs {My Plugin                  SHIFT to help}
@End

@OnShiftDown
  if showsHelp  
    ShowLayout mainLayout
    LabelKnobs {My Plugin                  SHIFT to help}
    
  else
    ShowLayout 4
    LabelKnobs {SHIFT to main}
    
  endif
  showsHelp = not showsHelp
@End

This script snippet is only applicable for the 16 pads layout (2) as this the only layout where the knobs 0-3 are at the same screen position as on the HELP page.

@Description
My Sample Plugin
This description will be shown on the HELP page. 
@End

@OnLoad
  ShowLayout 2
  SetKnobValue 3,0
  LabelKnob 3,{HELP}
@End

@OnKnobChange
  if LastKnob = 3
    ShowLayout 2 + 2* ( (GetKnobValue LastKnob ) >= 64)   
  endif
@End

The value returned from GetKnobValue is a floating point number, usually it will contain non-zero decimal places when the knob is turned manually. If double tapped the knob-value is set to 64 exactly. This tip exploits the fact, that is very unlikely to manually dial in exactly 64.0000 - if such a knob value is returned, then the knob has probably been double-tapped.

If a knob is only used to toggle between two states like a switch (like the variable isOn in the example), the code for double-tap detection would look like:

@OnKnobChange
  _knob = LastKnob
  _val  = GetKnobValue _knob
  
  if _knob = TOGGLE_KNOB
    if _val = 64
      isOn = not isOn
      SetKnobValue TOGGLE_KNOB,48 + 32*isOn
    else
      isOn = _val > 64  
    endif
    
    if isOn
      LabelKnob TOGGLE_KNOB,  {ON}
    else
      LabelKnob TOGGLE_KNOB,  {OFF}
    endif
  endif
@End

@OnLoad
  ShowLayout 2
  LabelPads {Knob Double-Tap Demo }
  LabelKnobs {Toggle with Double-Tap}
  for _knob = 0 to 3
    SetKnobValue _knob,0
    LabelKnob _knob,  { }
  endfor
  
  if Unassigned isOn
    isOn = NO  
  endif
  
  TOGGLE_KNOB = 1
  
  SetKnobValue TOGGLE_KNOB,48 + 32*isOn
  if isOn
    LabelKnob TOGGLE_KNOB,  {ON}
  else
    LabelKnob TOGGLE_KNOB,  {OFF}
  endif
@End

The script snippet also features

State saving of the toggle variable isOn
Conditional expressions:
- 48 + 32*isOn is either 48 or 80 depending on the state of isOn
- isOn = _val > 64 assigns either 0 or 1 to isOn depending on _val

Boolean expressions compute to either 1 or 0, which are the internal values for TRUE/FALSE or YES/NO. Using this behavior in expressions allows to get rid of some IFs, but on the other hand makes the script a bit more complicated to read and understand for novices.

Instead of the lengthy

  // showHelp  is a boolean with the values YES/NO or TRUE/FALSE

  If showHelp
    ShowLayout 4
  Else
    ShowLayout 2
  Endif

On can write

  ShowLayout 2 + 2*showHelp

.

Here second example where in the 22 knob layout the left most 8 knobs of both rows are used as channel knobs for channels 1 to 16. Since there are 11 knobs per row, the channel computed for the lower row needs to be adjusted:

  chan = LastKnob + 1
  If LastKnob >= 8
    chan = chan - 3
  Endif

This can be written shorter as:

  chan = LastKnob +1 - 3*(LastKnob>=8)

TheOriginalPaulB discovered that Inc and Dec are working as functions. Both Inc and Dec are ‚pre-increment‘ operations like ++var in C, as the function returns the already incremented value. This allows for several interesting language constructs:

In case of a ring buffer index, one could use

  index = (Inc index) % 64

instead of the longer construct

  Inc index
  index = index % 64

Sometimes this trick is also applicable in array initialization, but one has to compensate for the pre-increment.

  idx = -1
  for i = 10 to 19
    array[Inc idx] = 2*i
  endfor

The example fills array[0] to array[9] with the values 20 to 38. To compensate for pre-increment, idx needs to start at -1 since it will be incremented to zero on first usage

It is also possible to construct a post-increment operation by using the inc in the expression itself, but discarding it using multiplication with 0:

  idx = 0
  for i = 10 to 19
    array[idx] = 2*i  + 0*(Inc idx)
  endfor

This is a compact way to build standard chords from just a root note. It turns out that for standard western scales such as Major, Minor, Dorian, Phrygian, etc, normal chord notes can be found by starting at the root and counting up in steps of three semitones then quantizing up to the next scale tone. Repeat this for the number of notes you want in the chord (triad (3), seventh (4), ninth (5), eleventh (6), 13th (7).

Here’s a code snippet that efficiently creates a chord of “notes” degree from an incoming MIDI Note. Code to do something with that array would obviously have to be added.

@OnMIDINote
  //set “notes” to the number of notes wanted in the chord before this event triggers!
  chordNotes[0] = ScaleQuantize MIDINote
  for i = 1 to (notes - 1)
    chordNotes[i] = ScaleQuantize chordNotes[i-1] + 3
  endfor
@End

On PatchStorage you can find several 'Include Snippets' that cover specifc problems and that are intended to be appended your own scipt code.

I tried to make them as 'developer-friendly' as possible and also did extensive testing on each of these includes. The documentation wiki pages show the snippets source which should be easier to read than inside Mozaic.

PatchStorage	Wiki	Level	Info
Pad & Shift Manager	not yet	Easy	Add multi-pad or SHIFT single-tab/double-tab/hold interaction to your scripts
Migration Manager	Dokumentation	Complex	Migrate script parameters between different script versions

Mozaic: Scripting Tips & Tricks

Two dimensional Arrays

Multi dimensional Arrays

Store two positive Values into a single Variable

Store three unsigned Bytes into a single Variable

Some Best Practice Tips

Multi-Line Pad Labels

Use the SHIFT Button to toggle to HELP View

Use a Knob to toggle 16 Pads View to HELP View

Knob double-tap Support

Using Logic Operators in Expressions instead of IF cases

Using Inc and Dec in Expressions

Calculate Standard Chords from a Root Note

Include Snippets