/[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 2732 - (hide annotations) (download) (as text)
Sun Apr 26 20:54:00 2015 UTC (8 years, 11 months ago) by schoenebeck
File MIME type: text/html
File size: 51342 byte(s)
* Initial import of doc.linuxsampler.org.

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     <a href="gigedit_scripts.html">how to manage instrument scripts with gigedit</a>.
15     </p>
16    
17     <h3>At a Glance</h3>
18     <p>
19     <img src="nksp_file.png" style="height:111px; margin-right:12px;">
20     NKSP stands for "is <b>N</b>ot <b>KSP</b>", which denotes its distinction
21     to an existing proprieatary language called <i>KSP</i>.
22     NSKP is a script language specifically designed to write real-time capable
23     software extensions to LinuxSampler's sampler engines that can be bundled
24     individually with sounds by sound designers themselves.
25    
26     Instead of defining a completely new script language, NKSP is leaned on
27     that mentioned properiatary script language. The biggest advantage is that
28     sound designers and musicians can leverage the huge amount of existing KSP
29     scripts which are already available for various purposes on the Internet,
30     instead of being forced to write all scripts from scratch in a completely
31     different language.
32     </p>
33     <p>
34     That also means however that there are some differences between those two
35     languages. Some extensions have been added to the NKSP core language to
36     make it a bit more convenient and less error prone to write scripts, and
37     various new functions had to be added due to the large difference of the
38     sampler engines and their underlying sampler format. Efforts have been
39     made though to make NKSP as much compatible to KSP as possible.
40     The NKSP documentation will emphasize individual differences in
41     the two languages and function implementations wherever they may occur, to
42     give you immediate hints where you need to take care of regarding
43     compatibility issues when writing scripts that should be spawned on both
44     platforms.
45     </p>
46     <p>
47     Please note that the current focus of NKSP is the sound controlling aspect
48     of sounds. At this point there is no support for the graphical user
49     interface function set of KSP in NKSP.
50     </p>
51    
52     <h2>Event Handlers</h2>
53     <p>
54     NKSP is an event-driven language. That means you are writing so called
55     <i>event handlers</i> which define what the sampler shall do on individual
56     events that occur, while using the sound the script was bundled with.
57     An event handler in general looks like this:
58     </p>
59     <code lang="nksp">
60     on ??event-name??
61    
62     ??statements??
63    
64     end on
65     </code>
66     <p>
67     There are currently four events available:
68     </p>
69     <table>
70     <tr>
71     <th>Event Type</th> <th>Description</th>
72     </tr>
73     <tr>
74     <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>
75     </tr>
76     <tr>
77     <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>
78     </tr>
79     <tr>
80     <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>
81     </tr>
82     <tr>
83     <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>
84     </tr>
85     </table>
86     <p>
87     You are free to decide for which ones of those event types you are going to
88     write an event handler for. You can write an event handler for only one
89     event type or write event handlers for all of those event types. Also
90     dependent on the respective event type, there are certain things you can
91     do and things which you can't do. But more on that later.
92     </p>
93    
94     <h3>Note Events</h3>
95     <p>
96     As a first example, the following tiny script will print a message to your
97     terminal whenever you trigger a new note with your MIDI keyboard.
98     </p>
99     <code>
100     on note
101     message("A new note was triggered!")
102     end on
103     </code>
104     <p>
105     Probably you are also interested to see which note you triggered exactly.
106     The sampler provides you a so called
107     <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.">
108     built-in variable
109     </i>
110     called <code>$EVENT_NOTE</code> which reflects the note number
111     (as value between 0 and 127) of the note that has just been triggered. Additionally
112     the built-in variable <code>$EVENT_VELOCITY</code> provides you the
113     velocity value (also between 0 and 127) of the note event.
114     </p>
115     <code>
116     on note
117     message("Note " & $EVENT_NOTE & " was triggered with velocity " & $EVENT_VELOCITY)
118     end on
119     </code>
120     <p>
121     The <code>&</code> character concatenates text strings with each other.
122     In this case it is also automatically converting the note number into a
123     text string.
124     </p>
125     <note class="important">
126     The message() function is not appropriate for being used with your final
127     production sounds, since it can lead to audio dropouts.
128     You should only use the message() function to try out things, and to spot
129     and debug problems with your scripts.
130     </note>
131    
132     <h3>Release Events</h3>
133     <p>
134     As counter part to the <code>note</code> event handler, there is also the
135     <code>release</code> event handler, which is executed when a note was
136     released. This event handler can be used similarly:
137     </p>
138     <code>
139     on release
140     message("Note " & $EVENT_NOTE & " was released with release velocity " & $EVENT_VELOCITY)
141     end on
142     </code>
143     <p>
144     Please note that you can hardly find MIDI keyboards which support release
145     velocity. So with most keyboards this value will be 127.
146     </p>
147    
148     <h3>Controller Events</h3>
149     <p>
150     Now let's extend the first script to not only show note-on and note-off
151     events, but also to show a message whenever
152     you use a MIDI controller (i.e. modulation wheel, sustain pedal, etc.).
153     </p>
154     <code>
155     on note
156     message("Note " & $EVENT_NOTE & " was triggered with velocity " & $EVENT_VELOCITY)
157     end on
158    
159     on release
160     message("Note " & $EVENT_NOTE & " was released with release velocity " & $EVENT_VELOCITY)
161     end on
162    
163     on controller
164     message("MIDI Controller " & $CC_NUM " changed its value to " & %CC[$CC_NUM])
165     end on
166     </code>
167     <p>
168     It looks very similar to the note event handlers. <code>$CC_NUM</code>
169     reflects the MIDI controller number of the MIDI controller that had been
170     changed and <code>%CC</code> is a so called <i>array variable</i>, which not only
171     contains a single number value, but instead it contains several values at
172     the same time. The built-in <code>%CC</code> array variable contains the current
173     controller values of all 127 MIDI controllers. So <code>%CC[1]</code> for
174     example would give you the current controller value of the modulation
175     wheel, and therefore <code>%CC[$CC_NUM]</code> reflects the new controller
176     value of the controller that just had been changed.
177     </p>
178     <p>
179     There is some special aspect you need to be aware about: in contrast to the MIDI standard,
180     monophonic aftertouch (a.k.a. channel pressure) and pitch beend wheel are
181     handled by NKSP as if they were regular MIDI controllers. So a value change
182     of one of those two triggers a regular <code>controller</code> event handler
183     to be executed. To obtain the current aftertouch value you can use
184     <code>%CC[$VCC_MONO_AT]</code>, and to get the current pitch bend wheel
185     value use <code>%CC[$VCC_PITCH_BEND]</code>.
186     </p>
187    
188     <h3>Script Load Event</h3>
189     <p>
190     As the last one of the four event types available with NKSP, the following
191     is an example of an <code>init</code> event handler.
192     </p>
193     <code>
194     on init
195     message("This script has been loaded and is ready now!")
196     end on
197     </code>
198     <p>
199     You might think, that this is probably a very exotic event. Because in
200     fact, this "event" is only executed once for your script: exactly when
201     the script was loaded by the sampler. This is not an unimportant event
202     handler though. Because it is used to prepare your script for various
203     purposes. We will get more about that later.
204     </p>
205    
206     <h2>Comments</h2>
207     <p>
208     Let's face it: software code is sometimes hard to read, especially when you
209     are not a professional software developer who deals with such kinds of
210     things every day. To make it more easy for you to understand, what you
211     had in mind when you wrote a certain script three years ago, and also if
212     some other developer might need to continue working on your scripts one
213     day, you should place as many comments into your scripts as possible. A
214     comment in NKSP is everything that is nested into a an opening and closing
215     pair of curly braces.
216     </p>
217     <code>{ This is a comment. }</code>
218     <p>
219     You cannot only use this to leave some human readable explanations here
220     and there, you might also use such curly braces to quickly disable parts
221     of your scripts for a moment, i.e. when debugging certain things.
222     </p>
223     <code>
224     on init
225     { The following will be prompted to the terminal when the sampler loaded this script. }
226     message("My script loaded.")
227    
228     { This code block is commented out, so these two messages will not be displayed }
229     {
230     message("Another text")
231     message("And another one")
232     }
233     end on
234     </code>
235    
236     <h2>Variables</h2>
237     <p>
238     In order to be able to write more complex and more useful scripts, you
239     also need to remember some data somewhere for being able to use that
240     data at a later point. This can be done by using
241     <i title="A variable is a storage location paired with an associated symbolic name.">
242     variables
243     </i>.
244     We already came across some <i>built-in variables</i>, which are already
245     defined by the sampler for you. To store your own data you need to declare
246     your own <i>user variables</i>, which has the following form:
247     </p>
248     <p>
249     <code>declare $??variable-name?? := ??initial-value??
250     </p>
251     <p>
252     The left hand side's <code>??variable-name??</code> is an arbitrary name
253     you can chose for your variable. That name might consist of English
254     letters A to Z (lower and upper case) and the underscore character "<code>_</code>".
255     Variable names must be unique. So you can neither declare several variables
256     with the same name, nor can you use a name for your variable that is
257     already been reserved by <i>built-in variables</i>.
258     The right hand side's <code>??initial-value??</code> is simply the first
259     value the variable should store right after it was created. You can also
260     omit that.
261     </p>
262     <p>
263     <code>declare $??variable-name??
264     </p>
265     <p>
266     In that case the sampler will automatically assign <code>0</code> for you
267     as the variable's initial value. This way we could for example count the
268     total amount of notes triggered.
269     </p>
270     <code>
271     on init
272     declare $numberOfNotes := 0
273     end on
274    
275     on note
276     $numberOfNotes := $numberOfNotes + 1
277    
278     message("This is the " & $numberOfNotes & "th note triggered so far.")
279     end on
280     </code>
281     <p>
282     In the <code>init</code> event handler we create our own variable
283     <code>$numberOfNotes</code> and assign <code>0</code> to it as its
284     initial value. Like mentioned before, that initial assignment is optional.
285     In the <code>note</code> event handler we then increase the
286     <code>$numberOfNotes</code> variable by one, each time a new note was
287     triggered and then print a message to the terminal with the current total
288     amount of notes that have been triggered so far.
289     </p>
290     <note>
291     NKSP allows you to declare variables in all event handlers, however if
292     you want to keep compatibility with KSP, then you should only
293     declare variables in <code>init</code> event handlers.
294     </note>
295    
296     <h3>Variable Types</h3>
297     <p>
298     There are currently three different variable types, which you can easily
299     recognize upon their first character.
300     </p>
301     <table>
302     <tr>
303     <th>Variable Form</th> <th>Data Type</th> <th>Description</th>
304     </tr>
305     <tr>
306     <td><code>$??variable-name??</code></td> <td>Integer Scalar</td> <td>Stores one single integer number value.</td>
307     </tr>
308     <tr>
309     <td><code>%??variable-name??</code></td> <td>Integer Array</td> <td>Stores a certain amount of integer number values.</td>
310     </tr>
311     <tr>
312     <td><code>@??variable-name??</code></td> <td>String</td> <td>Stores one text string.</td>
313     </tr>
314     </table>
315     <p>
316     So the first character just before the actual variable name, always
317     denotes the data type of the variable. Also note that all variable types
318     share the same variable name space. That means you cannot declare a
319     variable with a name that has already been used to declare a variable of
320     another variable type.
321     </p>
322    
323     <h3>Array Variables</h3>
324     <p>
325     We already used the first two variable types. However we have not seen yet
326     how to declare such array variables. This is the common declaration form
327     for creating your own array variables.
328     </p>
329     <code>
330     on init
331     declare %??variable-name??[??array-size??] := ( ??list-of-values?? )
332     end on
333     </code>
334     <p>
335     So let's say you wanted to create an array variable with the first 12
336     prime numbers, then it might look like this.
337     </p>
338     <code>
339     on init
340     declare %primes[12] := ( 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37 )
341     end on
342     </code>
343     <p>
344     Like with integer variables, assigning some initial values with
345     <code>??list-of-values??</code> is optional. The array
346     declaration form without initial value assignment looks like this.
347     </p>
348     <code>
349     on init
350     declare %??variable-name??[??array-size??]
351     end on
352     </code>
353     <p>
354     When you omit that initial assignment, then all numbers of that array will
355     automatically be initialized with <code>0</code> each. With array
356     variables however, it is always mandatory to provide
357     <code>??array-size??</code> with an array
358     variable declaration, so the sampler can create that array with the
359     requested amount of values when the script is loaded. In contrast to many
360     other programming languages, changing that amount of values of an array
361     variable is not possible after the variable had been declared. That's due
362     to the fact that this language is dedicated to real-time applications, and
363     changing the size of an array variable at runtime would harm real-time
364     stability of the sampler and thus could lead to audio dropouts. So NKSP
365     does not allow you to do that.
366     </p>
367    
368    
369     <h3>String Variables</h3>
370     <p>
371     You might also store text with variables. These are called <i>text string
372     variables</i>, or short: <i>string variables</i>. Let's skip the common declaration
373     form of string variables and let us modify a prior example to just use
374     such kind of variable.
375     </p>
376     <code>
377     on init
378     declare $numberOfNotes
379     declare @firstText := "This is the "
380     declare @secondText
381     end on
382    
383     on note
384     $numberOfNotes := $numberOfNotes + 1
385     @secondText := "th note triggered so far."
386     message(@firstText & $numberOfNotes & @secondText)
387     end on
388     </code>
389     <p>
390     It behaves exactly like the prior example and shall just give you a
391     first idea how to declare and use string variables.
392     </p>
393     <note class="important">
394     Like with the message() function, you should not use string variables
395     with your final production sounds, since it can lead to audio dropouts.
396     You should only use string variables to try out things, and to spot
397     and debug problems with your scripts.
398     </note>
399    
400     <h3>Variable Scope</h3>
401     <p>
402     By default, all variables you declare with NKSP are
403     <i title="A variable that is accessible throughout an entire script.">
404     global variables
405     </i>. That means every event handler can access the data of such a global
406     variable. Furthermore, each instance of an event handler accesses the same
407     data when it is referencing that variable. And the latter fact can be a
408     problem sometimes, which we will outline next.
409     </p>
410     <p>
411     Let's assume you wanted to write an instrument script that shall resemble
412     a simple delay effect. You could do that by writing an note event handler
413     that automatically triggers several new notes for each note being
414     triggered on a MIDI keyboard. The following example demonstrates how that
415     could be achieved.
416     </p>
417     <note class="important">
418     The following example does not fully work with LinuxSampler yet. That's
419     because the used <code>wait()</code> function is not fully implemented
420     yet. Currently a <code>wait()</code> function call suspends execution,
421     but since the respective scheduler code is yet missing, the script
422     will automatically be resumed with the next audio fragment cycle. So
423     effectively a <code>wait()</code> call will pause your script for a few
424     miliseconds with LinuxSampler right now, no matter which function argument
425     you provided. Hopefully this will be implemented soon though.
426     </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    
608     <h2>Control Structures</h2>
609     <p>
610     A computer is more than a calculator that adds numbers and stores them
611     somewhere. One of the biggest strength of a computer, which makes it
612     such powerful, is the ability to do different things depending on various
613     conditions. For example your computer might clean up your hard drive
614     while you are not sitting in front of it, and it might immediately stop
615     doing so when you need all its resources to cut your latest video which
616     you just shot.
617     </p>
618     <p>
619     In order to do that for you, a computer program allows you to define
620     conditions and a list of instructions the computer shall
621     perform for you under those individual conditions. These kinds of
622     software mechanisms are called <i>Control Structures</i>.
623     </p>
624    
625     <h3>if Branches</h3>
626     <p>
627     The most fundamental control structure are <i>if branches</i>, which has
628     the following general form.
629     </p>
630     <code>
631     if (??condition??)
632    
633     ??statements??
634    
635     end if
636     </code>
637     <p>
638     The specified <code>??condition??</code> is evaluated each time script
639     execution reaches this control block. The condition can for example be
640     the value of a variable, some arithmetic expression, a function call or
641     a combination of them. In all cases the sampler expects the
642     <code>??condition??</code> expression to evaluate to some numeric
643     (or boolean) value. If the evaluated number is exactly <code>0</code> then
644     the condition is interpreted to be <i>false</i> and thus the list of
645     <code>??statements??</code> is not executed. If the evaluated value is any
646     other value than <code>0</code> then the condition is interpreted to be
647     <i>true</i> and accordingly the list of <code>??statements??</code> will be
648     executed.
649     </p>
650     <p>
651     Alternatively you might also specify a list of instructions which shall be
652     executed when the condition is <i>false</i>.
653     </p>
654     <code>
655     if (??condition??)
656    
657     ??statements-when-true??
658    
659     else
660    
661     ??statements-when-false??
662    
663     end if
664     </code>
665     <p>
666     In this case the first list of statements is executed when the
667     <code>??condition??</code> evaluated to <i>true</i>, otherwise the second
668     list of statements is executed instead.
669     </p>
670     <p>
671     Once again, let's get back to the example of counting triggered notes.
672     You might have noticed that it did not output correct English for the
673     first three notes. Let's correct this now.
674     </p>
675     <code>
676     on init
677     declare $numberOfNotes
678     declare @postfix
679     end on
680    
681     on note
682     $numberOfNotes := $numberOfNotes + 1
683    
684     if ($numberOfNotes == 1)
685     @postfix := "st"
686     else
687     if ($numberOfNotes == 2)
688     @postfix := "nd"
689     else
690     if ($numberOfNotes == 3)
691     @postfix := "rd"
692     else
693     @postfix := "th"
694     end if
695     end if
696     end if
697    
698     message("This is the " & $numberOfNotes & @postfix & " note triggered so far.")
699     end on
700     </code>
701     <p>
702     We are now checking the value of <code>$numberOfNotes</code> before we
703     print out a message. If <code>$numberOfNotes</code> equals one, then we
704     assign the string <code>"st"</code> to the variable <code>@postfix</code>,
705     if <code>$numberOfNotes</code> equals 2 instead we assign the string
706     <code>"nd"</code> instead, if it equals 3 instead we assign
707     <code>"rd"</code>, in all other cases we assign the string
708     <code>"th"</code>. And finally we assemble the text message to be
709     printed out to the terminal on line 23.
710     </p>
711    
712     <h3>Select Case Branches</h3>
713     <p>
714     The previous example now outputs the numbers in correct English. But the
715     script code looks a bit bloated, right? That's why there is a short hand
716     form.
717     </p>
718     <code>
719     select ??expression??
720    
721     case ??integer-1??
722    
723     ??statements-1??
724    
725    
726     case ??integer-2??
727    
728     ??statements-2??
729    
730     .
731     .
732     .
733     end select
734     </code>
735     <p>
736     The provided <code>??expression??</code> is first evaluated to an integer
737     value. Then this value is compared to the integer values of the nested
738     <code>case</code> lines. So it first compares the evaluated value of
739     <code>??expression??</code> with <code>??integer-1??</code>, then it
740     compares it with <code>??integer-2??</code>, and so on. The first integer
741     number that matches with the evaluated value of <code>??expression??</code>,
742     will be interpreted as being the current valid condition. So if
743     <code>??expression??</code> equals <code>??integer-1??</code>,
744     then <code>??statements-1??</code> will be executed, otherwise if
745     <code>??expression??</code> equals <code>??integer-2??</code>,
746     then <code>??statements-2??</code> will be executed, and so on.
747     </p>
748     <p>
749     Using a select-case construct, our previous example would look like follows.
750     </p>
751     <code>
752     on init
753     declare $numberOfNotes
754     declare @postfix
755     end on
756    
757     on note
758     $numberOfNotes := $numberOfNotes + 1
759     @postfix := "th"
760    
761     select $numberOfNotes
762     case 1
763     @postfix := "st"
764     case 2
765     @postfix := "nd"
766     case 3
767     @postfix := "rd"
768     end if
769    
770     message("This is the " & $numberOfNotes & @postfix & " note triggered so far.")
771     end on
772     </code>
773     <note>
774     If you like, you can also put parentheses around the select expression,
775     like <code>select (??expression??)</code>. Some developers familiar with
776     other programming languages might prefer this style. However if you want
777     to keep compatibility with KSP, you should not use parentheses for
778     select expressions.
779     </note>
780     <p>
781     The amount
782     of case conditions you add to such select-case blocks is completely up
783     to you. Just remember that the case conditions will be compared one by one,
784     from top to down. The latter can be important when you define a case line
785     that defines a value range. So for instance the following example will
786     not do what was probably intended.
787     </p>
788     <code>
789     on init
790     declare $numberOfNotes
791     end on
792    
793     on note
794     $numberOfNotes := $numberOfNotes + 1
795    
796     select $numberOfNotes
797     case 1 to 99
798     message("Less than 100 notes triggered so far")
799     exit
800     case 1
801     message("First note was triggered!") { Will never be printed ! }
802     exit
803     case 2
804     message("Second note was triggered!") { Will never be printed ! }
805     exit
806     case 3
807     message("Third note was triggered!") { Will never be printed ! }
808     exit
809     end if
810    
811     message("Wow, already the " & $numberOfNotes & "th note triggered.")
812     end on
813     </code>
814     <p>
815     You probably get the idea what this script "should" do. For the 1st note
816     it should print <code>"First note was triggered!"</code>, for the 2nd
817     note it should print <code>"Second note was triggered!"</code>, for the 3rd
818     note it should print <code>"Third note was triggered!"</code>, for the 4th
819     up to 99th note it should print <code>"Less than 100 notes triggered so far"</code>,
820     and starting from the 100th note and all following ones, it should print
821     the precise note number according to line 23. However, it doesn't!
822     </p>
823     <p>
824     To correct this problem, you need to move the first case block to the end,
825     like follows.
826     </p>
827     <code>
828     on init
829     declare $numberOfNotes
830     end on
831    
832     on note
833     $numberOfNotes := $numberOfNotes + 1
834    
835     select $numberOfNotes
836     case 1
837     message("First note was triggered!")
838     exit
839     case 2
840     message("Second note was triggered!")
841     exit
842     case 3
843     message("Third note was triggered!")
844     exit
845     case 1 to 99
846     message("Less than 100 notes triggered so far")
847     exit
848     end if
849    
850     message("Wow, already the " & $numberOfNotes & "th note triggered.")
851     end on
852     </code>
853     <p>
854     Or you could of course fix the questioned case range from <code>case 1 to 99</code>
855     to <code>case 4 to 99</code>. Both solutions will do.
856     </p>
857     <p>
858     We also used the <i>built-in function</i> <code>exit()</code> in the
859     previous example. You can use it to stop execution at that point of your
860     script. In the previous example it prevents multiple messages to be
861     printed to the terminal.
862     </p>
863     <note class="important">
864     The <code>exit()</code> function only stops execution of the <b>current</b>
865     event handler instance! It does <b>not</b> stop execution of other
866     instances of the same event handler, nor does it stop execution of other
867     handlers of other event types, and especially it does <b>not</b> stop or
868     prevent further or future execution of your entire script! In other words,
869     you should rather see this function as a return statement, in case you are
870     familiar with other programming languages already.
871     </note>
872    
873     <h3>while Loops</h3>
874     <p>
875     Another fundamental control construct of program flow are loops.
876     You can use so called
877     <i title="Repeats a given list of instructions until the defined condition turns false.">
878     while loops
879     </i>
880     with NKSP.
881     </p>
882     <code>
883     while (??condition??)
884    
885     ??statements??
886    
887     end while
888     </code>
889     <p>
890     A while loop is entered if the provided <code>??condition??</code>
891     expression evaluates to <i>true</i> and will then continue to execute
892     the given list of <code>??statements??</code> down to the end of the statements
893     list. The <code>??condition??</code> is re-evaluated each time execution
894     reached the end of the <code>??statements??</code> list and according to
895     that latest evaluated <code>??condition??</code> value at that point, it
896     will or will not repeat executing the statements again. If the condition
897     turned <i>false</i> instead, it will leave the loop and continue executing
898     statements that follow after the while loop block.
899     </p>
900     <p>
901     The next example will print the same message three times in a row to the
902     terminal, right after the script had been loaded by the sampler.
903     </p>
904     <code>
905     on init
906     declare $i := 3
907    
908     while ($i)
909     message("Print this three times.")
910     $i := $i - 1
911     end while
912     end on
913     </code>
914     <p>
915     When the while loop is reached for the first time in this example, the
916     condition value is <code>3</code>. And as we learned before, all integer
917     values that are not <code>0</code> are interpreted as being a <i>true</i> condition.
918     Accordingly the while loop is entered, the message is printed to the
919     terminal and the variable <code>$i</code> is reduced by one. We reached
920     the end of the loop's statements list, so it is now re-evaluating the
921     condition, which is now the value <code>2</code> and thus the loop
922     instructions are executed again. That is repeated until the loop was
923     executed for the third time. The variable <code>$i</code> is now
924     <code>0</code>, so the loop condition turned finally to <i>false</i> and the
925     loop is thus left at that point and the text message was printed
926     three times in total.
927     </p>
928    
929     <h2>Operators</h2>
930     <p>
931     A programming language provides so called <i>operators</i> to perform
932     certain kinds of transformations of data placed next to the operators.
933     These are the operators available with NKSP.
934     </p>
935    
936     <h3>Arithmetic Operators</h3>
937     <p>
938     These are the most basic mathematical operators, which allow to add,
939     subtract, multiply and divide integer values with each other.
940     </p>
941     <code>
942     on init
943     message("4 + 3 is " & 4 + 3) { Add }
944     message("4 - 3 is " & 4 - 3) { Subtract }
945     message("4 * 3 is " & 4 * 3) { Multiply }
946     message("35 / 5 is " & 35 / 5) { Divide }
947     message("35 mod 5 is " & 35 mod 5) { Remainder of Division ("modulo") }
948     end on
949     </code>
950     <p>
951     You may either use direct integer literal numbers like used in the upper
952     example, or you can use integer number variables or integer array variables.
953     </p>
954    
955     <h3>Boolean Operators</h3>
956     <p>
957     To perform logical transformations of <i>boolean</i> data, you may use the
958     following boolean operators:
959     </p>
960     <code>
961     on init
962     message("1 and 1 is " & 1 and 1) { logical "and" }
963     message("1 and 0 is " & 1 and 0) { logical "and" }
964     message("1 or 1 is " & 1 or 1) { logical "or" }
965     message("1 or 0 is " & 1 or 0) { logical "or" }
966     message("not 1 is " & not 1) { logical "not" }
967     message("not 0 is " & not 0) { logical "not" }
968     end on
969     </code>
970     <p>
971     Remember that with boolean operations, all integer values other than <code>0</code>
972     are interpreted as boolean <i>true</i> while an integer value of
973     precisely <code>0</code> is interpreted of being boolean <i>false</i>.
974     </p>
975    
976     <h3>Comparison Operators</h3>
977     <p>
978     For branches in your program flow, it is often required to compare data
979     with each other. This is done by using comparison operators, enumerated
980     below.
981     </p>
982     <code>
983     on init
984     message("Relation 3 < 4 -> " & 3 < 4) { "smaller than" comparison }
985     message("Relation 3 > 4 -> " & 3 > 4) { "greater than" comparison }
986     message("Relation 3 <= 4 -> " & 3 <= 4) { "smaller or equal than" comparison}
987     message("Relation 3 >= 4 -> " & 3 >= 4) { "greater or equal than" comparison}
988     message("Relation 3 # 4 -> " & 3 # 4) { "not equal to" comparison}
989     message("Relation 3 = 4 -> " & 3 = 4) { "is equal to" comparison}
990     end on
991     </code>
992     <p>
993     All these operations yield in a <i>boolean</i> result which could then
994     by used i.e. with <code>if</code> or <code>while</code> loop statements.
995     </p>
996    
997     <h3>String Operators</h3>
998     <p>
999     Last but not least, there is exactly one operator for text string data;
1000     the string concatenation operator <code>&</code>, which
1001     combines two text strings with each other.
1002     </p>
1003     <code>
1004     on init
1005     declare @s := "foo" & " bar"
1006     message(@s)
1007     end on
1008     </code>
1009     <p>
1010     We have used it now frequently in various examples before.
1011     </p>
1012    
1013     <h2>Preprocessor Statements</h2>
1014     <p>
1015     Similar to low-level programming languages like C, C++, Objective C
1016     and the like, NKSP supports a set of so called preprocessor statements.
1017     These are essentially "instructions" which are "executed" or rather
1018     processed, before (and only before) the script is executed by the sampler,
1019     and even before the script is parsed by the actual NKSP language parser.
1020     You can think of a preprocessor as a very primitive parser, which is the
1021     first one getting in touch with your script, it modifies the script code
1022     if requested by your preprocessor statements in the script, and then
1023     passes the (probably) modified script to the actual NKSP language parser.
1024     </p>
1025     <p>
1026     When we discussed <a href="#comments">comments</a> in NKSP scripts before,
1027     it was suggested that you might comment out certain code parts to disable
1028     them for a while during development of scripts. It was also suggested
1029     during this language tour that you should not use string variables or use
1030     the <code>message()</code> function with your final production sounds.
1031     However those are very handy things during development of your instrument
1032     scripts. You might even have a bunch of additional code in your scripts
1033     which only satisfies the purpose to make debugging of your scripts more easy,
1034     which however wastes on the other hand precious CPU time. So what do you
1035     do? Like suggested, you could comment out the respective code sections as
1036     soon as development of your script is completed. But then one day you
1037     might continue to improve your scripts, and the debugging code would be
1038     handy, so you would uncomment all the relevant code sections to get them
1039     back. When you think about this, that might be quite some work each time.
1040     Fortunately there is an alternative by using preprocessor statements.
1041     </p>
1042    
1043     <h3>Set a Condition</h3>
1044     <p>
1045     First you need to set a preprocessor condition in your script. You can do
1046     that like this:
1047     </p>
1048     <code>
1049     SET_CONDITION(??condition-name??)
1050     </code>
1051     <p>
1052     This preprocessor "condition" is just like some kind of
1053     <i title="A variable which can only have two states: i.e. true or false.">
1054     boolean variable
1055     </i>
1056     which is only available to the preprocessor and by using
1057     <code>SET_CONDITION(??condition-name??)</code>, this is like setting this
1058     preprocessor condition to <i>true</i>. Like with regular script
1059     variables, a preprocessor condition name can be chosen quite arbitrarily
1060     by you. But again, there are some pre-defined preprocessor conditions
1061     defined by the sampler for you. So you can only set a condition name here
1062     which is not already reserved by a built-in preprocessor condition. Also
1063     you shall not set a condition in your script again if you have already set it
1064     before somewhere in your script. The NKSP preprocessor will ignore setting
1065     a condition a 2nd time and will just print a warning when the script is
1066     loaded, but you should take care of it, because it might be a cause for
1067     some bug.
1068     </p>
1069    
1070     <h3>Reset a Condition</h3>
1071     <p>
1072     To clear a condition in your script, you might reset the condition like so:
1073     </p>
1074     <code>
1075     RESET_CONDITION(??condition-name??)
1076     </code>
1077     <p>
1078     This is like setting that preprocessor condition back to <i>false</i> again.
1079     You should only reset a preprocessor condition that way if you did set it
1080     with <code>SET_CONDITION(??condition-name??)</code> before. Trying to
1081     reset a condition that has not been set before, or trying to reset a
1082     condition that has already been reset, will both be ignored by the samlper,
1083     but again you will get a warning, and you should take care about it.
1084     </p>
1085    
1086     <h3>Conditionally Using Code</h3>
1087     <p>
1088     Now what do you actually do with such preprocessor conditions? You can use
1089     them for the NKSP language parser to either
1090     </p>
1091     <ul>
1092     <li>use certain parts of your code</i>
1093     <li><b>and</b> / <b>or</b> to ignore certain parts of your code</i>
1094     </ul>
1095     <p>
1096     You can achieve that by wrapping NKSP code parts into a pair of either
1097     </p>
1098     <code>
1099     USE_CODE_IF(??condition-name??)
1100    
1101     ??some-NKSP-code-goes-here??
1102    
1103     END_USE_CODE
1104     </code>
1105     <p>
1106     preprocessor statements, or between
1107     </p>
1108     <code>
1109     USE_CODE_IF_NOT(??condition-name??)
1110    
1111     ??some-NKSP-code-goes-here??
1112    
1113     END_USE_CODE
1114     </code>
1115     <p>
1116     statements. In the first case, the NKSP code portion is used by the NKSP
1117     language parser if the given preprocessor <code>??condition-name??</code> is set
1118     (that is if condition is <i>true</i>).
1119     If the condition is not set, the NKSP code portion in between is
1120     completely ignored by the NKSP language parser.
1121     </p>
1122     <p>
1123     In the second case, the NKSP code portion is used by the NKSP
1124     language parser if the given preprocessor <code>??condition-name??</code> is <b>not</b> set
1125     (or was reset)
1126     (that is if condition is <i>false</i>).
1127     If the condition is set, the NKSP code portion in between is
1128     completely ignored by the NKSP language parser.
1129     </p>
1130     <p>
1131     Let's look at an example how to use that to define conditional debugging
1132     code.
1133     </p>
1134     <code>
1135     SET_CONDITION(DEBUG_MODE)
1136    
1137     on init
1138     declare const %primes[12] := ( 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37 )
1139     declare $i
1140    
1141     USE_CODE_IF(DEBUG_MODE)
1142     message("This script has just been loaded.")
1143    
1144     $i := 0
1145     while ($i < num_elements(%primes))
1146     message("Prime " & $i & " is " & %primes[$i])
1147     $i := $i + 1
1148     end while
1149     END_USE_CODE
1150     end on
1151    
1152     on note
1153     USE_CODE_IF(DEBUG_MODE)
1154     message("Note " & $EVENT_NOTE & " was triggered with velocity " & $EVENT_VELOCITY)
1155     END_USE_CODE
1156     end on
1157    
1158     on release
1159     USE_CODE_IF(DEBUG_MODE)
1160     message("Note " & $EVENT_NOTE & " was released with release velocity " & $EVENT_VELOCITY)
1161     END_USE_CODE
1162     end on
1163    
1164     on controller
1165     USE_CODE_IF(DEBUG_MODE)
1166     message("MIDI Controller " & $CC_NUM " changed its value to " & %CC[$CC_NUM])
1167     END_USE_CODE
1168     end on
1169     </code>
1170     <p>
1171     The <i>built-in function</i> <code>num_elements()</code> used above, can
1172     be called to obtain the size of an array variable at runtime.
1173     As this script looks now, the debug messages will be printed out. However
1174     it requires you to just remove the first line, or to comment out the first
1175     line, in order to disable all debug code portions in just a second:
1176     </p>
1177     <code>
1178     { Setting the condition is commented out, so our DEBUG_MODE is disabled now. }
1179     { SET_CONDITION(DEBUG_MODE) }
1180    
1181     on init
1182     declare const %primes[12] := ( 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37 )
1183     declare $i
1184    
1185     USE_CODE_IF(DEBUG_MODE) { Condition is not set, so this entire block will be ignored now. }
1186     message("This script has just been loaded.")
1187    
1188     $i := 0
1189     while ($i < num_elements(%primes))
1190     message("Prime " & $i & " is " & %primes[$i])
1191     $i := $i + 1
1192     end while
1193     END_USE_CODE
1194     end on
1195    
1196     on note
1197     USE_CODE_IF(DEBUG_MODE) { Condition is not set, no message will be printed. }
1198     message("Note " & $EVENT_NOTE & " was triggered with velocity " & $EVENT_VELOCITY)
1199     END_USE_CODE
1200     end on
1201    
1202     on release
1203     USE_CODE_IF(DEBUG_MODE) { Condition is not set, no message will be printed. }
1204     message("Note " & $EVENT_NOTE & " was released with release velocity " & $EVENT_VELOCITY)
1205     END_USE_CODE
1206     end on
1207    
1208     on controller
1209     USE_CODE_IF(DEBUG_MODE) { Condition is not set, no message will be printed. }
1210     message("MIDI Controller " & $CC_NUM " changed its value to " & %CC[$CC_NUM])
1211     END_USE_CODE
1212     end on
1213     </code>
1214     <p>
1215     Now you might say, you could also achieve that by declaring and using
1216     a regular NKSP variable. That's correct, but there are two major
1217     advantages by using preprocessor statements.
1218     </p>
1219     <ol>
1220     <li>
1221     <b>Saving Resources</b> -
1222     The preprocessor conditions are only processed before the script is
1223     loaded into the NKSP parser. So in contrast to using NKSP variables,
1224     the preprocessor solution does not waste any CPU time or memory
1225     resources while executing the script. That also means that variable
1226     declarations can be disabled with the preprocessor this way
1227     and thus will also safe resources.
1228     </li>
1229     <li>
1230     <b>Cross Platform Support</b> -
1231     Since the code portions filtered out by the preprocessor never make it
1232     into the NKSP language parser, those filtered code portions might also
1233     contain code which would have lead to parser errors. For example you
1234     could use a built-in preprocessor condition to check whether your script
1235     was loaded into LinuxSampler or rather into another sampler. That way
1236     you could maintain one script for both platforms: NKSP and KSP.
1237     Accordingly you could
1238     also check a built-in variable to obtain the version of the sampler in
1239     order to enable or disable code portions of your script that might
1240     use some newer script features of the sampler which don't exist in older
1241     version of the sampler.
1242     </li>
1243     </ol>
1244     <p>
1245     As a rule of thumb: if there are things that you could move from your
1246     NKSP executed programming code out to the preprocessor, then you should
1247     use the preprocessor instead for such things. And like stated above,
1248     there are certain things which you can only achieve with the preprocessor.
1249     </p>
1250    
1251     <h2>What Next?</h2>
1252     <p>
1253     You have completed the introduction of the NKSP real-time instrument
1254     script language at this point. You can now dive into the details of the
1255     NKSP language by moving on to the
1256     <a href="nksp_reference.html">NKSP reference documentation</a>.
1257     Which provides you an overview and quick access to the details of all
1258     built-in functions, built-in variables and more.
1259     </p>
1260    
1261     </body>
1262     </html>

  ViewVC Help
Powered by ViewVC