Subversion Repositories svn.mios

Rev

Rev 1105 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
1095 tk 1
HEADER 3 MIDIbox NG User Manual --- .NGL Configuration File
2
 
3
<P CLASS=INFO><B><A HREF="midibox_ng_manual.html">Back to main page...</A></B></P>
4
 
5
<H1>MIDIbox NG</H1>
6
<H1>User Manual --- .NGL Configuration File</H1>
7
 
8
<P CLASS=INFO>This chapter lists the configuration commands of a .NGL file. If this format is new to you, please read the <A HREF="midibox_ng_manual_fs.html">First Steps chapter</A> first to get a basic understanding.</P>
9
 
10
<H2> <IMG SRC="images/bullet.gif" ALT=""> LABEL </H2>
11
 
12
<P CLASS=DESC>The <I>LABEL</I> command specifies global label definitions which can be referenced by using the Caret (^) specifier in label or LCD output definitions of the <A HREF="midibox_ng_manual_ngc.html">.NGC file</A>.
13
 
14
<P CLASS=DESC>A basic usage example can already be found in the DEFAULT.NGL file which has been generated whenever a "virgin" SD Card has been connected to the core module:
1113 tk 15
<TT><PRE style="margin-left:50px; font-size:8pt">
1095 tk 16
# Standard label for buttons:
17
LABEL std_btn  "Button #%3i %3d%b"
18
 
19
# Standard label for LEDs:
20
LABEL std_led  "LED #%3i       %b"
21
 
22
# Standard label for rotary encoders:
23
LABEL std_enc  "ENC #%3i    %3d%B"
24
 
25
# Standard label for pots connected to AIN pins:
26
LABEL std_ain  "AIN #%3i    %3d%B"
27
 
28
# Standard label for pots connected to AINSER module:
29
LABEL std_aser "AINSER #%3i %3d%B"
30
 
31
# Standard label for motorfaders:
32
LABEL std_mf   "MF #%3i     %3d%B"
33
</PRE></TT>
34
 
35
These standard labels are displayed whenever an EVENT_* in the .NGC file refers to the appr. label, such as:
1113 tk 36
<TT><PRE style="margin-left:50px; font-size:8pt">
1095 tk 37
# this command is part of a .NGC file:
38
EVENT_BUTTON id=1  type=NoteOn key=36  lcd_pos=1:1:1 label="^std_btn"
39
</PRE></TT>
40
 
1113 tk 41
<P CLASS=DESC>It's allowed that one label follows another in the same string:
42
<TT><PRE style="margin-left:50px; font-size:8pt">
43
# this command is part of a .NGC file:
44
EVENT_BUTTON id=1  type=NoteOn key=36  lcd_pos=1:1:1 label="^clr^btn^value"
45
</PRE></TT>
46
will print the ^clr, the ^btn and the ^value label (which have been defined by yourself).</P>
47
 
48
<P CLASS=DESC>And for the case, that text follows a label, terminate it with ^#
49
<TT><PRE style="margin-left:50px; font-size:8pt">
50
# this command is part of a .NGC file:
51
EVENT_BUTTON id=1  type=NoteOn key=36  lcd_pos=1:1:1 label="^clr^#MyText"
52
</PRE></TT>
53
will print the ^clr label (which has been defined by yourself), followed by "MyText".</P>
54
 
1095 tk 55
<P CLASS=DESC>The size of a label is limited to 8 characters to avoid unnecessary compute overhead while searching for matching strings.
56
 
57
 
58
<H2> <IMG SRC="images/bullet.gif" ALT=""> COND </H2>
59
 
60
<P CLASS=DESC>CONDitional labels are the most powerful purpose of global label definitions - they allow to output different strings based on the EVENT value!</P>
61
 
62
<P CLASS=DESC>Following example demonstrates the purpose pretty nicely:
1113 tk 63
<TT><PRE style="margin-left:50px; font-size:8pt">
1095 tk 64
COND_LABEL fil_type
65
COND =0    "Bypass   "
66
COND =1    "LP 24dB  "
67
COND =2    "LP 12dB  "
68
COND =3    "BP 24dB  "
69
COND =4    "BP 12dB  "
70
COND =5    "HP 24dB  "
71
COND =6    "HP 12dB  "
72
COND =7    "Notch24dB"
73
COND =8    "Notch12dB"
74
COND =9    "Comb+    "
75
COND =10   "Comb-    "
76
COND =11   "PPG LP   "
77
COND_ELSE  "Type %3d "
78
</PRE></TT>
79
 
80
<P CLASS=DESC>An EVENT_* command can use it this way:
81
 
1113 tk 82
<TT><PRE style="margin-left:50px; font-size:8pt">
1095 tk 83
# this command is part of a .NGC file:
84
EVENT_ENC id=1  type=CC cc=16  lcd_pos=1:1:1 label="Filter Type: ^fil_type"
85
</PRE></TT>
86
 
87
<P CLASS=DESC>So: each value can be named, but it's also possible to define value ranges at which a string should be taken, such as:
1113 tk 88
<TT><PRE style="margin-left:50px; font-size:8pt">
1095 tk 89
COND_LABEL test1
90
COND =0   "Val is 000   %3d"
91
COND =1   "Val is 001   %3d"
92
COND =2   "Val is 002   %3d"
93
COND =3   "Val is 003   %3d"
94
COND <20  "Val is <20   %3d"
95
COND <=40 "Val is <=40  %3d"
96
COND_ELSE "else cond.   %3d"
97
</PRE></TT>
98
 
99
<P CLASS=DESC>Here a list of supported commands:
100
 
101
 
102
<TABLE WIDTH="100%" BORDER=0 CELLSPACING=5 CELLPADDING=0>
103
  <TR>
104
    <TH WIDTH=150>COND Statement</TD>
105
    <TH>Description</TD>
106
  </TR>
107
  <TR>
108
    <TD CLASS=TABCOLOR2 WIDTH=150><I>COND_LABEL "&lt;name&gt;"</I></TD>
109
    <TD CLASS=TABCOLOR2>Starts a conditional label. The size of a label name is limited to 8 characters!
110
  </TR>
111
  <TR>
112
    <TD CLASS=TABCOLOR2 WIDTH=150><I>COND = or ==</I></TD>
113
    <TD CLASS=TABCOLOR2>String will be taken if the EVENT value is equal to the specified constant
114
  </TR>
115
  <TR>
116
    <TD CLASS=TABCOLOR2 WIDTH=150><I>COND &lt;</I></TD>
117
    <TD CLASS=TABCOLOR2>String will be taken if the EVENT value is less than the specified constant
118
  </TR>
119
  <TR>
120
    <TD CLASS=TABCOLOR2 WIDTH=150><I>COND &lt;=</I></TD>
121
    <TD CLASS=TABCOLOR2>String will be taken if the EVENT value is less or equal the specified constant
122
  </TR>
123
  <TR>
124
    <TD CLASS=TABCOLOR2 WIDTH=150><I>COND &gt;</I></TD>
125
    <TD CLASS=TABCOLOR2>String will be taken if the EVENT value is greater than the specified constant
126
  </TR>
127
  <TR>
128
    <TD CLASS=TABCOLOR2 WIDTH=150><I>COND &gt;=</I></TD>
129
    <TD CLASS=TABCOLOR2>String will be taken if the EVENT value is greater or equal the specified constant
130
  </TR>
131
  <TR>
132
    <TD CLASS=TABCOLOR2 WIDTH=150><I>COND_ELSE</I></TD>
133
    <TD CLASS=TABCOLOR2>This finishes a conditional label and returns a string if the previous statements haven't hit.<BR>
134
      It's strongly recommended to use this condition regardless if your definitions cover all possible values or not - it's at least a debugging help:
1113 tk 135
<TT><PRE style="margin-left:50px; font-size:8pt">
1095 tk 136
COND_ELSE "I made an error!"
137
</PRE></TT>
138
  </TR>
139
</TABLE>
140
 
1096 tk 141
<P CLASS=DESC>Note that <I>&gt;</I> and <I>&gt;=</I> actually don't make much sense, since the conditions are processed top-down. Once the EVENT value is greater(-equal) the constant, the matching label will be taken, and the remaining conditions won't be processed anymore. These statements are only provided for completeness purposes... ;-) (and sometimes it's useful to express conditions this way)
1095 tk 142
 
1101 tk 143
<H2> <IMG SRC="images/bullet.gif" ALT=""> Format Specifiers </H2>
1095 tk 144
 
1101 tk 145
<P CLASS=DESC>Following format specifiers are available:
146
 
147
<UL CLASS=CL>
148
  <LI><I>%d</I>: will output the value (minus specified <I>offset</I>) in decimal format
149
  <LI><I>%u</I>: same like %d, but value always in unsigned format
150
  <LI><I>%x</I>: will output the value (minus specified <I>offset</I>) in hexadecimal format
151
  <LI><I>%X</I>: same like %x, but with capital letters
152
  <LI><I>%c</I>: will output the value as character
153
  <LI><I>%s</I>: will output an empty string. In conjunction with padding values it could save some memory, e.g. "%20s" will output 20 spaces
154
  <LI><I>%i</I>: the ID of the EVENT
155
  <LI><I>%p</I>: for EVENT_BUTTON_MATRIX only: the pin number of the matrix
156
  <LI><I>%e</I>: the MIDI event of the EVENT (up to 3 hexadecimal values, always 6 characters)
157
  <LI><I>%m</I>: the minimum value of the EVENT which has been specified with <I>range</I>
158
  <LI><I>%M</I>: the maximum value of the EVENT which has been specified with <I>range</I>
159
  <LI><I>%b</I>: a binary digit: * if value >= (range/2), o if value < (range/2)
160
  <LI><I>%B</I>: a vertical bar which works like a meter.<BR>In conjunction with various fonts (selected with <I>&amp;&lt;font&gt;</I>) alternative icons will be output instead.
161
  <LI><I>%q</I>: current selected bank (q is a rotated b - do you see it? ;-)
162
  <LI><I>%C</I>: clear all LCDs
163
  <LI><I>%%</I>: outputs the % character
164
</UL>
165
 
166
<P CLASS=DESC>It's possible to format the output by adding following specifiers after the percent (%) character. In following example the %d (decimal value) is used, but this works with any format type:
167
<UL CLASS=CL>
168
  <LI><I>%3d</I>: the value will be padded with spaces to 3 characters, and it will be output right-aligned, e.g. "  1", " 10", "100"
169
  <LI><I>%-3d</I>: the value will be padded with spaces to 3 characters, and it will be output left-aligned, e.g. "1  ", "10 ", "100"
170
  <LI><I>%03d</I>: the value will be padded with zeroes to 3 characters, and it will be output right-aligned, e.g. "001", "010", "100"
171
</UL>
172
 
1095 tk 173
<H2> <IMG SRC="images/bullet.gif" ALT=""> Technical Background </H2>
174
 
175
<P CLASS=DESC>Actually the RAM memory size of a MBHP_CORE_STM32 or MBHP_CORE_LPC17 core is too low to provide instant access to huge conditional string lists. Therefore the definitions of a .NGL file will be automatically compiled into a .BIN file whenever the .NGL file has been modified. The .BIN file is structured in a way so that MIDIbox NG can quickly access the strings directly from SD Card. By using a clever registration mechanism this mostly allows access within less than 1 mS, which is totally acceptable for a thread which is running in background, and which doesn't delay the MIDI processing.
176
 
177
<P CLASS=DESC>Therefore you are welcome to use conditional labels as often as you like - they won't affect the performance, and they are a very useful extension to improve the readability of parameter value selections! :-)</P>
178
 
179
FOOTER