/[svn]/doc/docbase/instrument_scripts/nksp/01_nksp.html
ViewVC logotype

Annotation of /doc/docbase/instrument_scripts/nksp/01_nksp.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3191 - (hide annotations) (download) (as text)
Fri May 19 15:19:37 2017 UTC (6 years, 10 months ago) by schoenebeck
File MIME type: text/html
File size: 56804 byte(s)
* NKSP language tour: minor correction about the form
  of variable names.

1 schoenebeck 2732 <html>
2     <head>
3     <meta name="author" content="Christian Schoenebeck">
4     <title>NKSP Language</title>
5     <meta name="description" content="Introduction to the NKSP real-time instrument script language.">
6     </head>
7     <body>
8     <p>
9     This document intends to give you a compact introduction and overview to
10     the NKSP real-time instrument script language, so you can start writing
11     your own instrument scripts in short time. It concentrates on describing
12     the script language. If you rather want to learn how to modify and
13     attach scripts to your sounds, then please refer to the gigedit manual for
14 schoenebeck 3111 <a href="gigedit_scripts.html">how to manage instrument scripts with gigedit</a>
15     for Gigasampler/GigaStudio format sounds, or refer to the SFZ opcode
16     <code lang="sfz">script</code> for attaching NKSP scripts with
17     SFZ format sounds.
18 schoenebeck 2732 </p>
19    
20     <h3>At a Glance</h3>
21     <p>
22     <img src="nksp_file.png" style="height:111px; margin-right:12px;">
23     NKSP stands for "is <b>N</b>ot <b>KSP</b>", which denotes its distinction
24 schoenebeck 2995 to an existing proprietary language called <i>KSP</i>.
25 schoenebeck 2732 NSKP is a script language specifically designed to write real-time capable
26     software extensions to LinuxSampler's sampler engines that can be bundled
27     individually with sounds by sound designers themselves.
28    
29     Instead of defining a completely new script language, NKSP is leaned on
30     that mentioned properiatary script language. The biggest advantage is that
31     sound designers and musicians can leverage the huge amount of existing KSP
32     scripts which are already available for various purposes on the Internet,
33     instead of being forced to write all scripts from scratch in a completely
34     different language.
35     </p>
36     <p>
37     That also means however that there are some differences between those two
38     languages. Some extensions have been added to the NKSP core language to
39     make it a bit more convenient and less error prone to write scripts, and
40     various new functions had to be added due to the large difference of the
41     sampler engines and their underlying sampler format. Efforts have been
42     made though to make NKSP as much compatible to KSP as possible.
43     The NKSP documentation will emphasize individual differences in
44     the two languages and function implementations wherever they may occur, to
45     give you immediate hints where you need to take care of regarding
46     compatibility issues when writing scripts that should be spawned on both
47     platforms.
48     </p>
49     <p>
50     Please note that the current focus of NKSP is the sound controlling aspect
51     of sounds. At this point there is no support for the graphical user
52     interface function set of KSP in NKSP.
53     </p>
54    
55     <h2>Event Handlers</h2>
56     <p>
57     NKSP is an event-driven language. That means you are writing so called
58     <i>event handlers</i> which define what the sampler shall do on individual
59     events that occur, while using the sound the script was bundled with.
60     An event handler in general looks like this:
61     </p>
62     <code lang="nksp">
63     on ??event-name??
64    
65     ??statements??
66    
67     end on
68     </code>
69     <p>
70     There are currently four events available:
71     </p>
72     <table>
73     <tr>
74     <th>Event Type</th> <th>Description</th>
75     </tr>
76     <tr>
77     <td><code>on note</code></td> <td>This event handler is executed when a new note was triggered, i.e. when hitting a key on a MIDI keyboard.</td>
78     </tr>
79     <tr>
80     <td><code>on release</code></td> <td>This event handler is executed when a new note was released, i.e. when releasing a key on a MIDI keyboard.</td>
81     </tr>
82     <tr>
83     <td><code>on controller</code></td> <td>This event handler is executed when a MIDI control change event occurred. For instance when turning the modulation wheel at a MIDI keyboard.</td>
84     </tr>
85     <tr>
86     <td><code>on init</code></td> <td>Executed only once, as very first event handler, right after the script had been loaded. This code block is usually used to initialize variables in your script with some initial, useful data.</td>
87     </tr>
88     </table>
89     <p>
90     You are free to decide for which ones of those event types you are going to
91     write an event handler for. You can write an event handler for only one
92     event type or write event handlers for all of those event types. Also
93     dependent on the respective event type, there are certain things you can
94     do and things which you can't do. But more on that later.
95     </p>
96    
97     <h3>Note Events</h3>
98     <p>
99     As a first example, the following tiny script will print a message to your
100     terminal whenever you trigger a new note with your MIDI keyboard.
101     </p>
102     <code>
103     on note
104     message("A new note was triggered!")
105     end on
106     </code>
107     <p>
108     Probably you are also interested to see which note you triggered exactly.
109     The sampler provides you a so called
110     <i title="A script variable which is provided by the sampler and which has a very specific purpose which you cannot override for other purposes.">
111     built-in variable
112     </i>
113     called <code>$EVENT_NOTE</code> which reflects the note number
114     (as value between 0 and 127) of the note that has just been triggered. Additionally
115     the built-in variable <code>$EVENT_VELOCITY</code> provides you the
116     velocity value (also between 0 and 127) of the note event.
117     </p>
118     <code>
119     on note
120     message("Note " & $EVENT_NOTE & " was triggered with velocity " & $EVENT_VELOCITY)
121     end on
122     </code>
123     <p>
124     The <code>&</code> character concatenates text strings with each other.
125     In this case it is also automatically converting the note number into a
126     text string.
127     </p>
128     <note class="important">
129     The message() function is not appropriate for being used with your final
130     production sounds, since it can lead to audio dropouts.
131     You should only use the message() function to try out things, and to spot
132     and debug problems with your scripts.
133     </note>
134    
135     <h3>Release Events</h3>
136     <p>
137     As counter part to the <code>note</code> event handler, there is also the
138     <code>release</code> event handler, which is executed when a note was
139     released. This event handler can be used similarly:
140     </p>
141     <code>
142     on release
143     message("Note " & $EVENT_NOTE & " was released with release velocity " & $EVENT_VELOCITY)
144     end on
145     </code>
146     <p>
147     Please note that you can hardly find MIDI keyboards which support release
148     velocity. So with most keyboards this value will be 127.
149     </p>
150    
151     <h3>Controller Events</h3>
152     <p>
153     Now let's extend the first script to not only show note-on and note-off
154     events, but also to show a message whenever
155     you use a MIDI controller (i.e. modulation wheel, sustain pedal, etc.).
156     </p>
157     <code>
158     on note
159     message("Note " & $EVENT_NOTE & " was triggered with velocity " & $EVENT_VELOCITY)
160     end on
161    
162     on release
163     message("Note " & $EVENT_NOTE & " was released with release velocity " & $EVENT_VELOCITY)
164     end on
165    
166     on controller
167     message("MIDI Controller " & $CC_NUM " changed its value to " & %CC[$CC_NUM])
168     end on
169     </code>
170     <p>
171     It looks very similar to the note event handlers. <code>$CC_NUM</code>
172     reflects the MIDI controller number of the MIDI controller that had been
173     changed and <code>%CC</code> is a so called <i>array variable</i>, which not only
174     contains a single number value, but instead it contains several values at
175     the same time. The built-in <code>%CC</code> array variable contains the current
176     controller values of all 127 MIDI controllers. So <code>%CC[1]</code> for
177     example would give you the current controller value of the modulation
178     wheel, and therefore <code>%CC[$CC_NUM]</code> reflects the new controller
179     value of the controller that just had been changed.
180     </p>
181     <p>
182     There is some special aspect you need to be aware about: in contrast to the MIDI standard,
183     monophonic aftertouch (a.k.a. channel pressure) and pitch beend wheel are
184     handled by NKSP as if they were regular MIDI controllers. So a value change
185     of one of those two triggers a regular <code>controller</code> event handler
186     to be executed. To obtain the current aftertouch value you can use
187     <code>%CC[$VCC_MONO_AT]</code>, and to get the current pitch bend wheel
188     value use <code>%CC[$VCC_PITCH_BEND]</code>.
189     </p>
190    
191     <h3>Script Load Event</h3>
192     <p>
193     As the last one of the four event types available with NKSP, the following
194     is an example of an <code>init</code> event handler.
195     </p>
196     <code>
197     on init
198     message("This script has been loaded and is ready now!")
199     end on
200     </code>
201     <p>
202     You might think, that this is probably a very exotic event. Because in
203     fact, this "event" is only executed once for your script: exactly when
204     the script was loaded by the sampler. This is not an unimportant event
205     handler though. Because it is used to prepare your script for various
206     purposes. We will get more about that later.
207     </p>
208    
209     <h2>Comments</h2>
210     <p>
211     Let's face it: software code is sometimes hard to read, especially when you
212     are not a professional software developer who deals with such kinds of
213     things every day. To make it more easy for you to understand, what you
214     had in mind when you wrote a certain script three years ago, and also if
215     some other developer might need to continue working on your scripts one
216     day, you should place as many comments into your scripts as possible. A
217     comment in NKSP is everything that is nested into a an opening and closing
218     pair of curly braces.
219     </p>
220     <code>{ This is a comment. }</code>
221     <p>
222     You cannot only use this to leave some human readable explanations here
223     and there, you might also use such curly braces to quickly disable parts
224     of your scripts for a moment, i.e. when debugging certain things.
225     </p>
226     <code>
227     on init
228     { The following will be prompted to the terminal when the sampler loaded this script. }
229     message("My script loaded.")
230    
231     { This code block is commented out, so these two messages will not be displayed }
232     {
233     message("Another text")
234     message("And another one")
235     }
236     end on
237     </code>
238    
239     <h2>Variables</h2>
240     <p>
241     In order to be able to write more complex and more useful scripts, you
242     also need to remember some data somewhere for being able to use that
243     data at a later point. This can be done by using
244     <i title="A variable is a storage location paired with an associated symbolic name.">
245     variables
246     </i>.
247     We already came across some <i>built-in variables</i>, which are already
248     defined by the sampler for you. To store your own data you need to declare
249     your own <i>user variables</i>, which has the following form:
250     </p>
251     <p>
252     <code>declare $??variable-name?? := ??initial-value??
253     </p>
254     <p>
255     The left hand side's <code>??variable-name??</code> is an arbitrary name
256     you can chose for your variable. That name might consist of English
257 schoenebeck 3191 letters A to Z (lower and upper case), digits (<code>0</code> to <code>9</code>),
258     and the underscore character "<code>_</code>".
259 schoenebeck 2732 Variable names must be unique. So you can neither declare several variables
260     with the same name, nor can you use a name for your variable that is
261     already been reserved by <i>built-in variables</i>.
262     The right hand side's <code>??initial-value??</code> is simply the first
263     value the variable should store right after it was created. You can also
264     omit that.
265     </p>
266     <p>
267     <code>declare $??variable-name??
268     </p>
269     <p>
270     In that case the sampler will automatically assign <code>0</code> for you
271     as the variable's initial value. This way we could for example count the
272     total amount of notes triggered.
273     </p>
274     <code>
275     on init
276     declare $numberOfNotes := 0
277     end on
278    
279     on note
280     $numberOfNotes := $numberOfNotes + 1
281    
282     message("This is the " & $numberOfNotes & "th note triggered so far.")
283     end on
284     </code>
285     <p>
286     In the <code>init</code> event handler we create our own variable
287     <code>$numberOfNotes</code> and assign <code>0</code> to it as its
288     initial value. Like mentioned before, that initial assignment is optional.
289     In the <code>note</code> event handler we then increase the
290     <code>$numberOfNotes</code> variable by one, each time a new note was
291     triggered and then print a message to the terminal with the current total
292     amount of notes that have been triggered so far.
293     </p>
294     <note>
295     NKSP allows you to declare variables in all event handlers, however if
296     you want to keep compatibility with KSP, then you should only
297     declare variables in <code>init</code> event handlers.
298     </note>
299    
300     <h3>Variable Types</h3>
301     <p>
302     There are currently three different variable types, which you can easily
303     recognize upon their first character.
304     </p>
305     <table>
306     <tr>
307     <th>Variable Form</th> <th>Data Type</th> <th>Description</th>
308     </tr>
309     <tr>
310     <td><code>$??variable-name??</code></td> <td>Integer Scalar</td> <td>Stores one single integer number value.</td>
311     </tr>
312     <tr>
313     <td><code>%??variable-name??</code></td> <td>Integer Array</td> <td>Stores a certain amount of integer number values.</td>
314     </tr>
315     <tr>
316     <td><code>@??variable-name??</code></td> <td>String</td> <td>Stores one text string.</td>
317     </tr>
318     </table>
319     <p>
320     So the first character just before the actual variable name, always
321     denotes the data type of the variable. Also note that all variable types
322     share the same variable name space. That means you cannot declare a
323     variable with a name that has already been used to declare a variable of
324     another variable type.
325     </p>
326    
327     <h3>Array Variables</h3>
328     <p>
329     We already used the first two variable types. However we have not seen yet
330     how to declare such array variables. This is the common declaration form
331     for creating your own array variables.
332     </p>
333     <code>
334     on init
335     declare %??variable-name??[??array-size??] := ( ??list-of-values?? )
336     end on
337     </code>
338     <p>
339     So let's say you wanted to create an array variable with the first 12
340     prime numbers, then it might look like this.
341     </p>
342     <code>
343     on init
344     declare %primes[12] := ( 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37 )
345     end on
346     </code>
347     <p>
348     Like with integer variables, assigning some initial values with
349     <code>??list-of-values??</code> is optional. The array
350     declaration form without initial value assignment looks like this.
351     </p>
352     <code>
353     on init
354     declare %??variable-name??[??array-size??]
355     end on
356     </code>
357     <p>
358     When you omit that initial assignment, then all numbers of that array will
359     automatically be initialized with <code>0</code> each. With array
360     variables however, it is always mandatory to provide
361     <code>??array-size??</code> with an array
362     variable declaration, so the sampler can create that array with the
363     requested amount of values when the script is loaded. In contrast to many
364     other programming languages, changing that amount of values of an array
365     variable is not possible after the variable had been declared. That's due
366     to the fact that this language is dedicated to real-time applications, and
367     changing the size of an array variable at runtime would harm real-time
368     stability of the sampler and thus could lead to audio dropouts. So NKSP
369     does not allow you to do that.
370     </p>
371    
372    
373     <h3>String Variables</h3>
374     <p>
375     You might also store text with variables. These are called <i>text string
376     variables</i>, or short: <i>string variables</i>. Let's skip the common declaration
377     form of string variables and let us modify a prior example to just use
378     such kind of variable.
379     </p>
380     <code>
381     on init
382     declare $numberOfNotes
383     declare @firstText := "This is the "
384     declare @secondText
385     end on
386    
387     on note
388     $numberOfNotes := $numberOfNotes + 1
389     @secondText := "th note triggered so far."
390     message(@firstText & $numberOfNotes & @secondText)
391     end on
392     </code>
393     <p>
394     It behaves exactly like the prior example and shall just give you a
395     first idea how to declare and use string variables.
396     </p>
397     <note class="important">
398     Like with the message() function, you should not use string variables
399     with your final production sounds, since it can lead to audio dropouts.
400     You should only use string variables to try out things, and to spot
401     and debug problems with your scripts.
402     </note>
403    
404     <h3>Variable Scope</h3>
405     <p>
406     By default, all variables you declare with NKSP are
407     <i title="A variable that is accessible throughout an entire script.">
408     global variables
409     </i>. That means every event handler can access the data of such a global
410     variable. Furthermore, each instance of an event handler accesses the same
411     data when it is referencing that variable. And the latter fact can be a
412     problem sometimes, which we will outline next.
413     </p>
414     <p>
415     Let's assume you wanted to write an instrument script that shall resemble
416     a simple delay effect. You could do that by writing an note event handler
417     that automatically triggers several new notes for each note being
418     triggered on a MIDI keyboard. The following example demonstrates how that
419     could be achieved.
420     </p>
421 schoenebeck 2872 <note>
422     You need at least LinuxSampler 2.0.0.svn2 or higher for the following
423     example to work as described and as expected. Refer to the notes of the
424     <code>wait()</code> function reference documentation for more
425     informations about this issue.
426 schoenebeck 2732 </note>
427     <code>
428     on init
429     { The amount of notes to play }
430     declare const $delayNotes := 4
431     { Tempo with which the new notes will follow the orignal note }
432     declare const $bpm := 90
433     { Convert BPM to microseconds (duration between the notes) }
434     declare const $delayMicroSeconds := 60 * 1000000 / $bpm
435     { Just a working variable for being used with the while loop below }
436     declare $i
437     { For each successive note we trigger, we will reduce the velocity a bit}
438     declare $velocity
439     end on
440    
441     on note
442     { First initialize the variable $i with 4 each time we enter this event
443     handler, because each time we executed this handler, the variable will be 0 }
444     $i := $delayNotes
445    
446     { Loop which will be executed 4 times in a row }
447     while ($i)
448     { Calculate the velocity for the next note being triggered }
449     $velocity := 127 * $i / ($delayNotes + 1)
450     { Suspend this script for a short moment ... }
451     wait($delayMicroSeconds)
452     { ... and after that short break, trigger a new note. }
453     play_note($EVENT_NOTE, $velocity)
454     { Decrement loop counter $i by one }
455     $i := $i - 1
456     end while
457     end on
458     </code>
459     <p>
460     In this example we used a new keyword <code>const</code>. This additional
461     variable qualifier defines that we don't intend to change this variable
462     after declaration. So if you know beforehand, that a certain variable should
463     remain with a certain value, then you might use the <code>const</code>
464     qualifier to avoid that you i.e. change the value accidently when you
465     modify the script somewhere in future.
466     </p>
467     <p>
468     Now when you trigger one single note on your keyboard with that script,
469     you will hear the additional notes being triggered. And also when you
470     hit another note after a while, everything seems to be fine. However if
471     you start playing quick successive notes, you will notice something goes
472     wrong. The amount of notes being triggered by the script is now incorrect
473     and also the volume of the individual notes triggered by the script is wrong.
474     What's going on?
475     </p>
476     <p>
477     To understand the problem in the last example, let's consider what is
478     happening when executing that script exactly: Each time you play a note
479     on your keyboard, a new instance of the <code>note</code> event handler
480     will be spawned and executed by the sampler. In all our examples so far
481     our scripts were so simple, that in practice only one handler instance
482     was executed at a time. This is different in this case though. Because
483     by calling the <code>wait()</code> function, the respective handler
484     execution instance is paused for a while and in total each handler
485     instance will be executed for more than 2 seconds in this particular
486     example. As a consequence, when
487     you play multiple, successive notes on your keyboard in short time, you
488     will have several instances of the <code>note</code> event handler running
489     simultaniously. And that's where the problem starts. Because by default,
490     as said, all variables are global variables. So the handler instances
491     which are now running in parallel, are all reading and modifying the same
492     data. Thus the individual handler instances will modify the
493     <code>$i</code> and <code>$velocity</code> variables of each other, causing
494     an undesired misbehavior.
495     </p>
496     <note>
497     NKSP's built-in function <code>play_note()</code> allows you to pass
498     between one and four function arguments. For the function arguments you
499     don't provide to a <code>play_note()</code> call, NKSP will automatically
500     use default values. If you want your script to be compatible with KSP,
501     then you should always pass four arguments to that function though.
502     </note>
503    
504     <h3>Polyphonic Variables</h3>
505     <p>
506     As a logical consequence of the previously described data concurrency
507     problem, it would be desirable to have each event handler instance use
508     its own variable instance, so that the individual handler instances stop
509     interfering with each other. For this purpose the so called
510     <i title="A variable which is effectively a separate variable for each event handler instance.">
511     polyphonic variable
512     </i>
513     qualifier exists with NKSP. Declaring such a variable is identical to
514     declaring a regular variable, just that you add the keyword <code>polyphonic</code>.
515     </p>
516     <code>
517     declare polyphonic $??variable-name??
518     </code>
519     <p>
520     So to fix the bug in our previous example, we simply make the variables
521     <code>$i</code> and <code>$velocity</code> polyphonic variables.
522     </p>
523     <code>
524     on init
525     { The amount of notes to play }
526     declare const $delayNotes := 4
527     { Tempo with which the new notes will follow the orignal note }
528     declare const $bpm := 90
529     { Convert BPM to microseconds (duration between the notes) }
530     declare const $delayMicroSeconds := 60 * 1000000 / $bpm
531     { Just a working variable for being used with the while loop below }
532     declare polyphonic $i { < --- NOW POLYPHONIC !!! }
533     { For each successive note we trigger, we will reduce the velocity a bit}
534     declare polyphonic $velocity { < --- NOW POLYPHONIC !!! }
535     end on
536    
537     on note
538     { First initialize the variable $i with 4 each time we enter this event
539     handler, because each time we executed this handler, the variable will be 0 }
540     $i := $delayNotes
541    
542     { Loop which will be executed 4 times in a row }
543     while ($i)
544     { Calculate the velocity for the next note being triggered }
545     $velocity := 127 * $i / ($delayNotes + 1)
546     { Suspend this script for a short moment ... }
547     wait($delayMicroSeconds)
548     { ... and after that short break, trigger a new note. }
549     play_note($EVENT_NOTE, $velocity)
550     { Decrement loop counter $i by one }
551     $i := $i - 1
552     end while
553     end on
554     </code>
555     <p>
556     And that's it! The script works now as intended. Now you might wonder, why
557     are variables not <i>polyphonic</i> by default? Isn't that more common and
558     wouldn't that be more safer than using global variables by default? The reason is that
559     a polyphonic variable consumes a lot more memory than a regular (global) variable.
560     That's because for each polyphonic variable, the sampler has to allocate
561     in advance (when the script is loaded) as many instances of that
562     polyphonic variable as there are maximum events
563     allowed with the sampler. So that's a lot! Considering that today's
564     computers have plenty of RAM this might be a theoretical aspect, but in the
565     end: this default scope of variables was already like this with <i>KSP</i>
566     so we are also doing it like this with NKSP for compatibility reasons.
567     </p>
568     <p>
569     Please note that the <i>polyphonic</i> qualifier only exists for integer
570     variables. So you cannot declare polyphonic string variables, nor can you
571     declare polyphonic array variables. Like in the previous explanation,
572     this is due to the fact that it would consume a huge amount of memory
573     for such variables. And with string variables and array variables, the
574     required amount of memory would be much higher than with simple integer
575     variables.
576     </p>
577     <p>
578     As summary, the following are guideline rules describing when you should
579     use the polyphonic qualifier for a certain variable. You should declare
580     a particular variable polyphonic if one (or even both) of the following two
581     conditions apply to that variable.
582     </p>
583     <ol>
584     <li>
585     If you call the <code>wait()</code> function within your event
586     handlers and the respective variable is modified and read before
587     and after at least one of the individual <code>wait()</code> calls.
588     </li>
589     <li>
590     If you have loops that might run for a very long time, while accessing
591     the respective variable in between. That's because if your script is
592     running consecutively for too long, the sampler will automatically suspend your
593     script for a while to avoid your script becoming a real-time stability
594     hazard for the sampler. Your script will then automatically be resumed
595     after a short moment by the sampler, so effectively this is similar to
596     something like an "automated" <code>wait()</code> function call by
597     the sampler.
598     </li>
599     </ol>
600     <p>
601     In all other cases you should rather use regular (global) variables instead.
602     But keep in mind that you might need to re-assign a certain value for
603     some global variables when you enter the respective event handler, just
604     like we did with <code>$i := $delayNotes</code> right from the start
605     during discussion of the previous example script.
606     </p>
607 schoenebeck 2763 <p>
608     There is another special aspect regarding the variable scope of polyphonic
609     variables: <code>note</code> handlers and <code>release</code> handlers of
610     the same script share the same polyphonic variable scope, that means you
611     may pass data from a particular note's <code>note</code> handler to its
612     <code>release</code> handler by using the same polyphonic variable name.
613     </p>
614 schoenebeck 2732
615     <h2>Control Structures</h2>
616     <p>
617     A computer is more than a calculator that adds numbers and stores them
618     somewhere. One of the biggest strength of a computer, which makes it
619     such powerful, is the ability to do different things depending on various
620     conditions. For example your computer might clean up your hard drive
621     while you are not sitting in front of it, and it might immediately stop
622     doing so when you need all its resources to cut your latest video which
623     you just shot.
624     </p>
625     <p>
626     In order to do that for you, a computer program allows you to define
627     conditions and a list of instructions the computer shall
628     perform for you under those individual conditions. These kinds of
629     software mechanisms are called <i>Control Structures</i>.
630     </p>
631    
632     <h3>if Branches</h3>
633     <p>
634     The most fundamental control structure are <i>if branches</i>, which has
635     the following general form.
636     </p>
637     <code>
638     if (??condition??)
639    
640     ??statements??
641    
642     end if
643     </code>
644     <p>
645     The specified <code>??condition??</code> is evaluated each time script
646     execution reaches this control block. The condition can for example be
647     the value of a variable, some arithmetic expression, a function call or
648     a combination of them. In all cases the sampler expects the
649     <code>??condition??</code> expression to evaluate to some numeric
650     (or boolean) value. If the evaluated number is exactly <code>0</code> then
651     the condition is interpreted to be <i>false</i> and thus the list of
652     <code>??statements??</code> is not executed. If the evaluated value is any
653     other value than <code>0</code> then the condition is interpreted to be
654     <i>true</i> and accordingly the list of <code>??statements??</code> will be
655     executed.
656     </p>
657     <p>
658     Alternatively you might also specify a list of instructions which shall be
659     executed when the condition is <i>false</i>.
660     </p>
661     <code>
662     if (??condition??)
663    
664     ??statements-when-true??
665    
666     else
667    
668     ??statements-when-false??
669    
670     end if
671     </code>
672     <p>
673     In this case the first list of statements is executed when the
674     <code>??condition??</code> evaluated to <i>true</i>, otherwise the second
675     list of statements is executed instead.
676     </p>
677     <p>
678     Once again, let's get back to the example of counting triggered notes.
679     You might have noticed that it did not output correct English for the
680     first three notes. Let's correct this now.
681     </p>
682     <code>
683     on init
684     declare $numberOfNotes
685     declare @postfix
686     end on
687    
688     on note
689     $numberOfNotes := $numberOfNotes + 1
690    
691     if ($numberOfNotes == 1)
692     @postfix := "st"
693     else
694     if ($numberOfNotes == 2)
695     @postfix := "nd"
696     else
697     if ($numberOfNotes == 3)
698     @postfix := "rd"
699     else
700     @postfix := "th"
701     end if
702     end if
703     end if
704    
705     message("This is the " & $numberOfNotes & @postfix & " note triggered so far.")
706     end on
707     </code>
708     <p>
709     We are now checking the value of <code>$numberOfNotes</code> before we
710     print out a message. If <code>$numberOfNotes</code> equals one, then we
711     assign the string <code>"st"</code> to the variable <code>@postfix</code>,
712     if <code>$numberOfNotes</code> equals 2 instead we assign the string
713     <code>"nd"</code> instead, if it equals 3 instead we assign
714     <code>"rd"</code>, in all other cases we assign the string
715     <code>"th"</code>. And finally we assemble the text message to be
716     printed out to the terminal on line 23.
717     </p>
718    
719     <h3>Select Case Branches</h3>
720     <p>
721     The previous example now outputs the numbers in correct English. But the
722     script code looks a bit bloated, right? That's why there is a short hand
723     form.
724     </p>
725     <code>
726     select ??expression??
727    
728     case ??integer-1??
729    
730     ??statements-1??
731    
732    
733     case ??integer-2??
734    
735     ??statements-2??
736    
737     .
738     .
739     .
740     end select
741     </code>
742     <p>
743     The provided <code>??expression??</code> is first evaluated to an integer
744     value. Then this value is compared to the integer values of the nested
745     <code>case</code> lines. So it first compares the evaluated value of
746     <code>??expression??</code> with <code>??integer-1??</code>, then it
747     compares it with <code>??integer-2??</code>, and so on. The first integer
748     number that matches with the evaluated value of <code>??expression??</code>,
749     will be interpreted as being the current valid condition. So if
750     <code>??expression??</code> equals <code>??integer-1??</code>,
751     then <code>??statements-1??</code> will be executed, otherwise if
752     <code>??expression??</code> equals <code>??integer-2??</code>,
753     then <code>??statements-2??</code> will be executed, and so on.
754     </p>
755     <p>
756     Using a select-case construct, our previous example would look like follows.
757     </p>
758     <code>
759     on init
760     declare $numberOfNotes
761     declare @postfix
762     end on
763    
764     on note
765     $numberOfNotes := $numberOfNotes + 1
766     @postfix := "th"
767    
768     select $numberOfNotes
769     case 1
770     @postfix := "st"
771     case 2
772     @postfix := "nd"
773     case 3
774     @postfix := "rd"
775 schoenebeck 3119 end select
776 schoenebeck 2732
777     message("This is the " & $numberOfNotes & @postfix & " note triggered so far.")
778     end on
779     </code>
780     <note>
781     If you like, you can also put parentheses around the select expression,
782     like <code>select (??expression??)</code>. Some developers familiar with
783     other programming languages might prefer this style. However if you want
784     to keep compatibility with KSP, you should not use parentheses for
785     select expressions.
786     </note>
787     <p>
788     The amount
789     of case conditions you add to such select-case blocks is completely up
790     to you. Just remember that the case conditions will be compared one by one,
791     from top to down. The latter can be important when you define a case line
792     that defines a value range. So for instance the following example will
793     not do what was probably intended.
794     </p>
795     <code>
796     on init
797     declare $numberOfNotes
798     end on
799    
800     on note
801     $numberOfNotes := $numberOfNotes + 1
802    
803     select $numberOfNotes
804     case 1 to 99
805     message("Less than 100 notes triggered so far")
806     exit
807     case 1
808     message("First note was triggered!") { Will never be printed ! }
809     exit
810     case 2
811     message("Second note was triggered!") { Will never be printed ! }
812     exit
813     case 3
814     message("Third note was triggered!") { Will never be printed ! }
815     exit
816 schoenebeck 3119 end select
817 schoenebeck 2732
818     message("Wow, already the " & $numberOfNotes & "th note triggered.")
819     end on
820     </code>
821     <p>
822     You probably get the idea what this script "should" do. For the 1st note
823     it should print <code>"First note was triggered!"</code>, for the 2nd
824     note it should print <code>"Second note was triggered!"</code>, for the 3rd
825     note it should print <code>"Third note was triggered!"</code>, for the 4th
826     up to 99th note it should print <code>"Less than 100 notes triggered so far"</code>,
827     and starting from the 100th note and all following ones, it should print
828     the precise note number according to line 23. However, it doesn't!
829     </p>
830     <p>
831     To correct this problem, you need to move the first case block to the end,
832     like follows.
833     </p>
834     <code>
835     on init
836     declare $numberOfNotes
837     end on
838    
839     on note
840     $numberOfNotes := $numberOfNotes + 1
841    
842     select $numberOfNotes
843     case 1
844     message("First note was triggered!")
845     exit
846     case 2
847     message("Second note was triggered!")
848     exit
849     case 3
850     message("Third note was triggered!")
851     exit
852     case 1 to 99
853     message("Less than 100 notes triggered so far")
854     exit
855 schoenebeck 3119 end select
856 schoenebeck 2732
857     message("Wow, already the " & $numberOfNotes & "th note triggered.")
858     end on
859     </code>
860     <p>
861     Or you could of course fix the questioned case range from <code>case 1 to 99</code>
862     to <code>case 4 to 99</code>. Both solutions will do.
863     </p>
864     <p>
865     We also used the <i>built-in function</i> <code>exit()</code> in the
866     previous example. You can use it to stop execution at that point of your
867     script. In the previous example it prevents multiple messages to be
868     printed to the terminal.
869     </p>
870     <note class="important">
871     The <code>exit()</code> function only stops execution of the <b>current</b>
872     event handler instance! It does <b>not</b> stop execution of other
873     instances of the same event handler, nor does it stop execution of other
874     handlers of other event types, and especially it does <b>not</b> stop or
875     prevent further or future execution of your entire script! In other words,
876     you should rather see this function as a return statement, in case you are
877     familiar with other programming languages already.
878     </note>
879    
880     <h3>while Loops</h3>
881     <p>
882     Another fundamental control construct of program flow are loops.
883     You can use so called
884     <i title="Repeats a given list of instructions until the defined condition turns false.">
885     while loops
886     </i>
887     with NKSP.
888     </p>
889     <code>
890     while (??condition??)
891    
892     ??statements??
893    
894     end while
895     </code>
896     <p>
897     A while loop is entered if the provided <code>??condition??</code>
898     expression evaluates to <i>true</i> and will then continue to execute
899     the given list of <code>??statements??</code> down to the end of the statements
900     list. The <code>??condition??</code> is re-evaluated each time execution
901     reached the end of the <code>??statements??</code> list and according to
902     that latest evaluated <code>??condition??</code> value at that point, it
903     will or will not repeat executing the statements again. If the condition
904     turned <i>false</i> instead, it will leave the loop and continue executing
905     statements that follow after the while loop block.
906     </p>
907     <p>
908     The next example will print the same message three times in a row to the
909     terminal, right after the script had been loaded by the sampler.
910     </p>
911     <code>
912     on init
913     declare $i := 3
914    
915     while ($i)
916     message("Print this three times.")
917     $i := $i - 1
918     end while
919     end on
920     </code>
921     <p>
922     When the while loop is reached for the first time in this example, the
923     condition value is <code>3</code>. And as we learned before, all integer
924     values that are not <code>0</code> are interpreted as being a <i>true</i> condition.
925     Accordingly the while loop is entered, the message is printed to the
926     terminal and the variable <code>$i</code> is reduced by one. We reached
927     the end of the loop's statements list, so it is now re-evaluating the
928     condition, which is now the value <code>2</code> and thus the loop
929     instructions are executed again. That is repeated until the loop was
930     executed for the third time. The variable <code>$i</code> is now
931     <code>0</code>, so the loop condition turned finally to <i>false</i> and the
932     loop is thus left at that point and the text message was printed
933     three times in total.
934     </p>
935 schoenebeck 3061
936     <h3>User Functions</h3>
937     <p>
938     We already came across various built-in functions, which you may call
939     by your scripts to perform certain tasks or behavior which is already
940 schoenebeck 3062 provided for you by the sampler. NKSP also allows you to write your
941     own functions, which you then may call from various places of your
942     script.
943     <p>
944     </p>
945     When working on larger scripts, you
946 schoenebeck 3061 may notice that you easily get to the point where you may have to
947     duplicate portions of your script code, since there are certain things
948     that you may have to do again and again in different parts of your script.
949     Software developers usually try to avoid such code duplications to
950 schoenebeck 3062 keep the overall amount of code as small as possible, since the
951     overall amount of code would bloat quickly and would
952 schoenebeck 3061 make the software very hard to maintain. One way for you to avoid such
953     script code duplications with NKSP is to write so called <i>User Functions</s>.
954     </p>
955     <p>
956     Let's assume you wanted to create a simple stuttering effect. You may do so
957     like in the following example.
958     </p>
959     <code>
960     on note
961     while (1)
962     wait(200000)
963     if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
964     exit()
965     end if
966     change_vol($EVENT_ID, -20000) { Reduce volume by 20 dB. }
967     wait(200000)
968     if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
969     exit()
970     end if
971     change_vol($EVENT_ID, 0) { Increase volume to 0 dB. }
972     end while
973     end on
974     </code>
975     <p>
976     This script will run an endless loop for each note being triggered.
977 schoenebeck 3064 Every <code lang="none">200ms</code> it will turn the volume alternatingly down and
978 schoenebeck 3063 up to create the audible stuttering effect. After each <code lang="nksp">wait()</code>
979 schoenebeck 3061 call it calls <code>event_status($EVENT_ID)</code> to check whether
980     this note is still alive, and as soon as the note died, it will stop
981     execution of the script instance by calling <code>exit()</code>. The latter
982 schoenebeck 3064 is important in this example, because otherwise the script execution instances would
983 schoenebeck 3061 continue to run in this endless loop forever, even after the respectives
984 schoenebeck 3064 notes are gone. Which would let your CPU usage to increase with every new note
985     and would never decrease again.
986 schoenebeck 3061 This behavior of the sampler is not a bug, it is intended, since there may
987     also be cases where you want to do certain things by script even after the
988     respective notes are dead and gone. However as you can see, that script is
989     using the same portions of script code twice. To avoid that, you could also
990     write the same script with a user function like this:
991     </p>
992     <code>
993     function pauseMyScript
994     wait(200000)
995     if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
996     exit()
997     end if
998     end function
999 schoenebeck 2732
1000 schoenebeck 3061 on note
1001     while (1)
1002     call pauseMyScript
1003     change_vol($EVENT_ID, -20000) { Reduce volume by 20 dB. }
1004     call pauseMyScript
1005     change_vol($EVENT_ID, 0) { Increase volume back to 0 dB. }
1006     end while
1007     end on
1008     </code>
1009     <p>
1010     The script became in this simple example only slightly smaller, but it also
1011 schoenebeck 3062 became easier to read and behaves identically to the previous solution.
1012     And in practice, with a more complex script, you can
1013 schoenebeck 3061 reduce the overall amount of script code a lot this way. You can choose any
1014     name for your own user functions, as long as the name is not already
1015     reserved by a built-in function. Note that for calling a user function,
1016     you must always precede the actual user function name with the
1017     <code>call</code> keyword. Likewise you may however not use the
1018     <code>call</code> keyword for calling any built-in function. So that
1019     substantially differs calling built-in functions from calling user functions.
1020     </p>
1021    
1022 schoenebeck 2732 <h2>Operators</h2>
1023     <p>
1024     A programming language provides so called <i>operators</i> to perform
1025     certain kinds of transformations of data placed next to the operators.
1026     These are the operators available with NKSP.
1027     </p>
1028    
1029     <h3>Arithmetic Operators</h3>
1030     <p>
1031     These are the most basic mathematical operators, which allow to add,
1032     subtract, multiply and divide integer values with each other.
1033     </p>
1034     <code>
1035     on init
1036     message("4 + 3 is " & 4 + 3) { Add }
1037     message("4 - 3 is " & 4 - 3) { Subtract }
1038     message("4 * 3 is " & 4 * 3) { Multiply }
1039     message("35 / 5 is " & 35 / 5) { Divide }
1040     message("35 mod 5 is " & 35 mod 5) { Remainder of Division ("modulo") }
1041     end on
1042     </code>
1043     <p>
1044     You may either use direct integer literal numbers like used in the upper
1045     example, or you can use integer number variables or integer array variables.
1046     </p>
1047    
1048     <h3>Boolean Operators</h3>
1049     <p>
1050     To perform logical transformations of <i>boolean</i> data, you may use the
1051 schoenebeck 2936 following logical operators:
1052 schoenebeck 2732 </p>
1053     <code>
1054     on init
1055     message("1 and 1 is " & 1 and 1) { logical "and" }
1056     message("1 and 0 is " & 1 and 0) { logical "and" }
1057     message("1 or 1 is " & 1 or 1) { logical "or" }
1058     message("1 or 0 is " & 1 or 0) { logical "or" }
1059     message("not 1 is " & not 1) { logical "not" }
1060     message("not 0 is " & not 0) { logical "not" }
1061     end on
1062     </code>
1063     <p>
1064 schoenebeck 2936 Keep in mind that with logical operators shown above,
1065     all integer values other than <code>0</code>
1066 schoenebeck 2732 are interpreted as boolean <i>true</i> while an integer value of
1067     precisely <code>0</code> is interpreted of being boolean <i>false</i>.
1068     </p>
1069 schoenebeck 2936 <p>
1070     So the logical operators shown above always look at numbers at a whole.
1071     Sometimes however you might rather need to process numbers bit by bit. For
1072     that purpose the following bitwise operators exist.
1073     </p>
1074     <code>
1075     on init
1076     message("1 .and. 1 is " & 1 .and. 1) { bitwise "and" }
1077     message("1 .and. 0 is " & 1 .and. 0) { bitwise "and" }
1078     message("1 .or. 1 is " & 1 .or. 1) { bitwise "or" }
1079     message("1 .or. 0 is " & 1 .or. 0) { bitwise "or" }
1080     message(".not. 1 is " & .not. 1) { bitwise "not" }
1081     message(".not. 0 is " & .not. 0) { bitwise "not" }
1082     end on
1083     </code>
1084     <p>
1085     Bitwise operators work essentially like logical operators, with the
1086     difference that bitwise operators compare each bit independently.
1087     So a bitwise <code>.and.</code> operator for instance takes the 1st bit
1088     of the left hand's side value, the 1st bit of the right hand's side value,
1089     compares the two bits logically and then stores that result as 1st bit of
1090     the final result value, then it takes the 2nd bit of the left hand's side value
1091     and the 2nd bit of the right hand's side value, compares those two bits logically
1092     and then stores that result as 2nd bit of the final result value, and so on.
1093     </p>
1094    
1095 schoenebeck 2732
1096     <h3>Comparison Operators</h3>
1097     <p>
1098     For branches in your program flow, it is often required to compare data
1099     with each other. This is done by using comparison operators, enumerated
1100     below.
1101     </p>
1102     <code>
1103     on init
1104     message("Relation 3 < 4 -> " & 3 < 4) { "smaller than" comparison }
1105     message("Relation 3 > 4 -> " & 3 > 4) { "greater than" comparison }
1106     message("Relation 3 <= 4 -> " & 3 <= 4) { "smaller or equal than" comparison}
1107     message("Relation 3 >= 4 -> " & 3 >= 4) { "greater or equal than" comparison}
1108     message("Relation 3 # 4 -> " & 3 # 4) { "not equal to" comparison}
1109     message("Relation 3 = 4 -> " & 3 = 4) { "is equal to" comparison}
1110     end on
1111     </code>
1112     <p>
1113     All these operations yield in a <i>boolean</i> result which could then
1114     by used i.e. with <code>if</code> or <code>while</code> loop statements.
1115     </p>
1116    
1117     <h3>String Operators</h3>
1118     <p>
1119     Last but not least, there is exactly one operator for text string data;
1120     the string concatenation operator <code>&</code>, which
1121     combines two text strings with each other.
1122     </p>
1123     <code>
1124     on init
1125     declare @s := "foo" & " bar"
1126     message(@s)
1127     end on
1128     </code>
1129     <p>
1130     We have used it now frequently in various examples before.
1131     </p>
1132    
1133     <h2>Preprocessor Statements</h2>
1134     <p>
1135     Similar to low-level programming languages like C, C++, Objective C
1136     and the like, NKSP supports a set of so called preprocessor statements.
1137     These are essentially "instructions" which are "executed" or rather
1138     processed, before (and only before) the script is executed by the sampler,
1139     and even before the script is parsed by the actual NKSP language parser.
1140     You can think of a preprocessor as a very primitive parser, which is the
1141     first one getting in touch with your script, it modifies the script code
1142     if requested by your preprocessor statements in the script, and then
1143     passes the (probably) modified script to the actual NKSP language parser.
1144     </p>
1145     <p>
1146     When we discussed <a href="#comments">comments</a> in NKSP scripts before,
1147     it was suggested that you might comment out certain code parts to disable
1148     them for a while during development of scripts. It was also suggested
1149     during this language tour that you should not use string variables or use
1150     the <code>message()</code> function with your final production sounds.
1151     However those are very handy things during development of your instrument
1152     scripts. You might even have a bunch of additional code in your scripts
1153     which only satisfies the purpose to make debugging of your scripts more easy,
1154     which however wastes on the other hand precious CPU time. So what do you
1155     do? Like suggested, you could comment out the respective code sections as
1156     soon as development of your script is completed. But then one day you
1157     might continue to improve your scripts, and the debugging code would be
1158     handy, so you would uncomment all the relevant code sections to get them
1159     back. When you think about this, that might be quite some work each time.
1160     Fortunately there is an alternative by using preprocessor statements.
1161     </p>
1162    
1163     <h3>Set a Condition</h3>
1164     <p>
1165     First you need to set a preprocessor condition in your script. You can do
1166     that like this:
1167     </p>
1168     <code>
1169     SET_CONDITION(??condition-name??)
1170     </code>
1171     <p>
1172     This preprocessor "condition" is just like some kind of
1173     <i title="A variable which can only have two states: i.e. true or false.">
1174     boolean variable
1175     </i>
1176     which is only available to the preprocessor and by using
1177     <code>SET_CONDITION(??condition-name??)</code>, this is like setting this
1178     preprocessor condition to <i>true</i>. Like with regular script
1179     variables, a preprocessor condition name can be chosen quite arbitrarily
1180     by you. But again, there are some pre-defined preprocessor conditions
1181     defined by the sampler for you. So you can only set a condition name here
1182     which is not already reserved by a built-in preprocessor condition. Also
1183     you shall not set a condition in your script again if you have already set it
1184     before somewhere in your script. The NKSP preprocessor will ignore setting
1185     a condition a 2nd time and will just print a warning when the script is
1186     loaded, but you should take care of it, because it might be a cause for
1187     some bug.
1188     </p>
1189    
1190     <h3>Reset a Condition</h3>
1191     <p>
1192     To clear a condition in your script, you might reset the condition like so:
1193     </p>
1194     <code>
1195     RESET_CONDITION(??condition-name??)
1196     </code>
1197     <p>
1198     This is like setting that preprocessor condition back to <i>false</i> again.
1199     You should only reset a preprocessor condition that way if you did set it
1200     with <code>SET_CONDITION(??condition-name??)</code> before. Trying to
1201     reset a condition that has not been set before, or trying to reset a
1202     condition that has already been reset, will both be ignored by the samlper,
1203     but again you will get a warning, and you should take care about it.
1204     </p>
1205    
1206     <h3>Conditionally Using Code</h3>
1207     <p>
1208     Now what do you actually do with such preprocessor conditions? You can use
1209     them for the NKSP language parser to either
1210     </p>
1211     <ul>
1212     <li>use certain parts of your code</i>
1213     <li><b>and</b> / <b>or</b> to ignore certain parts of your code</i>
1214     </ul>
1215     <p>
1216     You can achieve that by wrapping NKSP code parts into a pair of either
1217     </p>
1218     <code>
1219     USE_CODE_IF(??condition-name??)
1220    
1221     ??some-NKSP-code-goes-here??
1222    
1223     END_USE_CODE
1224     </code>
1225     <p>
1226     preprocessor statements, or between
1227     </p>
1228     <code>
1229     USE_CODE_IF_NOT(??condition-name??)
1230    
1231     ??some-NKSP-code-goes-here??
1232    
1233     END_USE_CODE
1234     </code>
1235     <p>
1236     statements. In the first case, the NKSP code portion is used by the NKSP
1237     language parser if the given preprocessor <code>??condition-name??</code> is set
1238     (that is if condition is <i>true</i>).
1239     If the condition is not set, the NKSP code portion in between is
1240     completely ignored by the NKSP language parser.
1241     </p>
1242     <p>
1243     In the second case, the NKSP code portion is used by the NKSP
1244     language parser if the given preprocessor <code>??condition-name??</code> is <b>not</b> set
1245     (or was reset)
1246     (that is if condition is <i>false</i>).
1247     If the condition is set, the NKSP code portion in between is
1248     completely ignored by the NKSP language parser.
1249     </p>
1250     <p>
1251     Let's look at an example how to use that to define conditional debugging
1252     code.
1253     </p>
1254     <code>
1255     SET_CONDITION(DEBUG_MODE)
1256    
1257     on init
1258     declare const %primes[12] := ( 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37 )
1259     declare $i
1260    
1261     USE_CODE_IF(DEBUG_MODE)
1262     message("This script has just been loaded.")
1263    
1264     $i := 0
1265     while ($i < num_elements(%primes))
1266     message("Prime " & $i & " is " & %primes[$i])
1267     $i := $i + 1
1268     end while
1269     END_USE_CODE
1270     end on
1271    
1272     on note
1273     USE_CODE_IF(DEBUG_MODE)
1274     message("Note " & $EVENT_NOTE & " was triggered with velocity " & $EVENT_VELOCITY)
1275     END_USE_CODE
1276     end on
1277    
1278     on release
1279     USE_CODE_IF(DEBUG_MODE)
1280     message("Note " & $EVENT_NOTE & " was released with release velocity " & $EVENT_VELOCITY)
1281     END_USE_CODE
1282     end on
1283    
1284     on controller
1285     USE_CODE_IF(DEBUG_MODE)
1286     message("MIDI Controller " & $CC_NUM " changed its value to " & %CC[$CC_NUM])
1287     END_USE_CODE
1288     end on
1289     </code>
1290     <p>
1291     The <i>built-in function</i> <code>num_elements()</code> used above, can
1292     be called to obtain the size of an array variable at runtime.
1293     As this script looks now, the debug messages will be printed out. However
1294     it requires you to just remove the first line, or to comment out the first
1295     line, in order to disable all debug code portions in just a second:
1296     </p>
1297     <code>
1298     { Setting the condition is commented out, so our DEBUG_MODE is disabled now. }
1299     { SET_CONDITION(DEBUG_MODE) }
1300    
1301     on init
1302     declare const %primes[12] := ( 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37 )
1303     declare $i
1304    
1305     USE_CODE_IF(DEBUG_MODE) { Condition is not set, so this entire block will be ignored now. }
1306     message("This script has just been loaded.")
1307    
1308     $i := 0
1309     while ($i < num_elements(%primes))
1310     message("Prime " & $i & " is " & %primes[$i])
1311     $i := $i + 1
1312     end while
1313     END_USE_CODE
1314     end on
1315    
1316     on note
1317     USE_CODE_IF(DEBUG_MODE) { Condition is not set, no message will be printed. }
1318     message("Note " & $EVENT_NOTE & " was triggered with velocity " & $EVENT_VELOCITY)
1319     END_USE_CODE
1320     end on
1321    
1322     on release
1323     USE_CODE_IF(DEBUG_MODE) { Condition is not set, no message will be printed. }
1324     message("Note " & $EVENT_NOTE & " was released with release velocity " & $EVENT_VELOCITY)
1325     END_USE_CODE
1326     end on
1327    
1328     on controller
1329     USE_CODE_IF(DEBUG_MODE) { Condition is not set, no message will be printed. }
1330     message("MIDI Controller " & $CC_NUM " changed its value to " & %CC[$CC_NUM])
1331     END_USE_CODE
1332     end on
1333     </code>
1334     <p>
1335     Now you might say, you could also achieve that by declaring and using
1336     a regular NKSP variable. That's correct, but there are two major
1337     advantages by using preprocessor statements.
1338     </p>
1339     <ol>
1340     <li>
1341     <b>Saving Resources</b> -
1342     The preprocessor conditions are only processed before the script is
1343     loaded into the NKSP parser. So in contrast to using NKSP variables,
1344     the preprocessor solution does not waste any CPU time or memory
1345     resources while executing the script. That also means that variable
1346     declarations can be disabled with the preprocessor this way
1347     and thus will also safe resources.
1348     </li>
1349     <li>
1350     <b>Cross Platform Support</b> -
1351     Since the code portions filtered out by the preprocessor never make it
1352     into the NKSP language parser, those filtered code portions might also
1353     contain code which would have lead to parser errors. For example you
1354     could use a built-in preprocessor condition to check whether your script
1355     was loaded into LinuxSampler or rather into another sampler. That way
1356     you could maintain one script for both platforms: NKSP and KSP.
1357     Accordingly you could
1358     also check a built-in variable to obtain the version of the sampler in
1359     order to enable or disable code portions of your script that might
1360     use some newer script features of the sampler which don't exist in older
1361     version of the sampler.
1362     </li>
1363     </ol>
1364     <p>
1365     As a rule of thumb: if there are things that you could move from your
1366     NKSP executed programming code out to the preprocessor, then you should
1367     use the preprocessor instead for such things. And like stated above,
1368     there are certain things which you can only achieve with the preprocessor.
1369     </p>
1370    
1371     <h2>What Next?</h2>
1372     <p>
1373     You have completed the introduction of the NKSP real-time instrument
1374     script language at this point. You can now dive into the details of the
1375     NKSP language by moving on to the
1376     <a href="nksp_reference.html">NKSP reference documentation</a>.
1377     Which provides you an overview and quick access to the details of all
1378     built-in functions, built-in variables and more.
1379     </p>
1380    
1381     </body>
1382     </html>

  ViewVC Help
Powered by ViewVC