18 |
<p> |
<p> |
19 |
<img src="nksp_file.png" style="height:111px; margin-right:12px;"> |
<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 |
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>. |
to an existing proprietary language called <i>KSP</i>. |
22 |
NSKP is a script language specifically designed to write real-time capable |
NSKP is a script language specifically designed to write real-time capable |
23 |
software extensions to LinuxSampler's sampler engines that can be bundled |
software extensions to LinuxSampler's sampler engines that can be bundled |
24 |
individually with sounds by sound designers themselves. |
individually with sounds by sound designers themselves. |
414 |
triggered on a MIDI keyboard. The following example demonstrates how that |
triggered on a MIDI keyboard. The following example demonstrates how that |
415 |
could be achieved. |
could be achieved. |
416 |
</p> |
</p> |
417 |
<note class="important"> |
<note> |
418 |
The following example does not fully work with LinuxSampler yet. That's |
You need at least LinuxSampler 2.0.0.svn2 or higher for the following |
419 |
because the used <code>wait()</code> function is not fully implemented |
example to work as described and as expected. Refer to the notes of the |
420 |
yet. Currently a <code>wait()</code> function call suspends execution, |
<code>wait()</code> function reference documentation for more |
421 |
but since the respective scheduler code is yet missing, the script |
informations about this issue. |
|
will automatically be resumed with the next audio fragment cycle. So |
|
|
effectively a <code>wait()</code> call will pause your script for a few |
|
|
miliseconds with LinuxSampler right now, no matter which function argument |
|
|
you provided. Hopefully this will be implemented soon though. |
|
422 |
</note> |
</note> |
423 |
<code> |
<code> |
424 |
on init |
on init |
600 |
like we did with <code>$i := $delayNotes</code> right from the start |
like we did with <code>$i := $delayNotes</code> right from the start |
601 |
during discussion of the previous example script. |
during discussion of the previous example script. |
602 |
</p> |
</p> |
603 |
|
<p> |
604 |
|
There is another special aspect regarding the variable scope of polyphonic |
605 |
|
variables: <code>note</code> handlers and <code>release</code> handlers of |
606 |
|
the same script share the same polyphonic variable scope, that means you |
607 |
|
may pass data from a particular note's <code>note</code> handler to its |
608 |
|
<code>release</code> handler by using the same polyphonic variable name. |
609 |
|
</p> |
610 |
|
|
611 |
<h2>Control Structures</h2> |
<h2>Control Structures</h2> |
612 |
<p> |
<p> |
928 |
loop is thus left at that point and the text message was printed |
loop is thus left at that point and the text message was printed |
929 |
three times in total. |
three times in total. |
930 |
</p> |
</p> |
931 |
|
|
932 |
|
<h3>User Functions</h3> |
933 |
|
<p> |
934 |
|
We already came across various built-in functions, which you may call |
935 |
|
by your scripts to perform certain tasks or behavior which is already |
936 |
|
provided for you by the sampler. NKSP also allows you to write your |
937 |
|
own functions, which you then may call from various places of your |
938 |
|
script. |
939 |
|
<p> |
940 |
|
</p> |
941 |
|
When working on larger scripts, you |
942 |
|
may notice that you easily get to the point where you may have to |
943 |
|
duplicate portions of your script code, since there are certain things |
944 |
|
that you may have to do again and again in different parts of your script. |
945 |
|
Software developers usually try to avoid such code duplications to |
946 |
|
keep the overall amount of code as small as possible, since the |
947 |
|
overall amount of code would bloat quickly and would |
948 |
|
make the software very hard to maintain. One way for you to avoid such |
949 |
|
script code duplications with NKSP is to write so called <i>User Functions</s>. |
950 |
|
</p> |
951 |
|
<p> |
952 |
|
Let's assume you wanted to create a simple stuttering effect. You may do so |
953 |
|
like in the following example. |
954 |
|
</p> |
955 |
|
<code> |
956 |
|
on note |
957 |
|
while (1) |
958 |
|
wait(200000) |
959 |
|
if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE)) |
960 |
|
exit() |
961 |
|
end if |
962 |
|
change_vol($EVENT_ID, -20000) { Reduce volume by 20 dB. } |
963 |
|
wait(200000) |
964 |
|
if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE)) |
965 |
|
exit() |
966 |
|
end if |
967 |
|
change_vol($EVENT_ID, 0) { Increase volume to 0 dB. } |
968 |
|
end while |
969 |
|
end on |
970 |
|
</code> |
971 |
|
<p> |
972 |
|
This script will run an endless loop for each note being triggered. |
973 |
|
Every <code lang="none">200ms</code>. It will turn the volume alternatingly down and |
974 |
|
up to create the audible stuttering effect. After each <code lang="nksp">wait()</code> |
975 |
|
call it calls <code>event_status($EVENT_ID)</code> to check whether |
976 |
|
this note is still alive, and as soon as the note died, it will stop |
977 |
|
execution of the script instance by calling <code>exit()</code>. The latter |
978 |
|
is important in this example, because otherwise the script instances would |
979 |
|
continue to run in this endless loop forever, even after the respectives |
980 |
|
notes are gone. Which would let your CPU usage to increase with every new note. |
981 |
|
This behavior of the sampler is not a bug, it is intended, since there may |
982 |
|
also be cases where you want to do certain things by script even after the |
983 |
|
respective notes are dead and gone. However as you can see, that script is |
984 |
|
using the same portions of script code twice. To avoid that, you could also |
985 |
|
write the same script with a user function like this: |
986 |
|
</p> |
987 |
|
<code> |
988 |
|
function pauseMyScript |
989 |
|
wait(200000) |
990 |
|
if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE)) |
991 |
|
exit() |
992 |
|
end if |
993 |
|
end function |
994 |
|
|
995 |
|
on note |
996 |
|
while (1) |
997 |
|
call pauseMyScript |
998 |
|
change_vol($EVENT_ID, -20000) { Reduce volume by 20 dB. } |
999 |
|
call pauseMyScript |
1000 |
|
change_vol($EVENT_ID, 0) { Increase volume back to 0 dB. } |
1001 |
|
end while |
1002 |
|
end on |
1003 |
|
</code> |
1004 |
|
<p> |
1005 |
|
The script became in this simple example only slightly smaller, but it also |
1006 |
|
became easier to read and behaves identically to the previous solution. |
1007 |
|
And in practice, with a more complex script, you can |
1008 |
|
reduce the overall amount of script code a lot this way. You can choose any |
1009 |
|
name for your own user functions, as long as the name is not already |
1010 |
|
reserved by a built-in function. Note that for calling a user function, |
1011 |
|
you must always precede the actual user function name with the |
1012 |
|
<code>call</code> keyword. Likewise you may however not use the |
1013 |
|
<code>call</code> keyword for calling any built-in function. So that |
1014 |
|
substantially differs calling built-in functions from calling user functions. |
1015 |
|
</p> |
1016 |
|
|
1017 |
<h2>Operators</h2> |
<h2>Operators</h2> |
1018 |
<p> |
<p> |
1019 |
A programming language provides so called <i>operators</i> to perform |
A programming language provides so called <i>operators</i> to perform |
1043 |
<h3>Boolean Operators</h3> |
<h3>Boolean Operators</h3> |
1044 |
<p> |
<p> |
1045 |
To perform logical transformations of <i>boolean</i> data, you may use the |
To perform logical transformations of <i>boolean</i> data, you may use the |
1046 |
following boolean operators: |
following logical operators: |
1047 |
</p> |
</p> |
1048 |
<code> |
<code> |
1049 |
on init |
on init |
1056 |
end on |
end on |
1057 |
</code> |
</code> |
1058 |
<p> |
<p> |
1059 |
Remember that with boolean operations, all integer values other than <code>0</code> |
Keep in mind that with logical operators shown above, |
1060 |
|
all integer values other than <code>0</code> |
1061 |
are interpreted as boolean <i>true</i> while an integer value of |
are interpreted as boolean <i>true</i> while an integer value of |
1062 |
precisely <code>0</code> is interpreted of being boolean <i>false</i>. |
precisely <code>0</code> is interpreted of being boolean <i>false</i>. |
1063 |
</p> |
</p> |
1064 |
|
<p> |
1065 |
|
So the logical operators shown above always look at numbers at a whole. |
1066 |
|
Sometimes however you might rather need to process numbers bit by bit. For |
1067 |
|
that purpose the following bitwise operators exist. |
1068 |
|
</p> |
1069 |
|
<code> |
1070 |
|
on init |
1071 |
|
message("1 .and. 1 is " & 1 .and. 1) { bitwise "and" } |
1072 |
|
message("1 .and. 0 is " & 1 .and. 0) { bitwise "and" } |
1073 |
|
message("1 .or. 1 is " & 1 .or. 1) { bitwise "or" } |
1074 |
|
message("1 .or. 0 is " & 1 .or. 0) { bitwise "or" } |
1075 |
|
message(".not. 1 is " & .not. 1) { bitwise "not" } |
1076 |
|
message(".not. 0 is " & .not. 0) { bitwise "not" } |
1077 |
|
end on |
1078 |
|
</code> |
1079 |
|
<p> |
1080 |
|
Bitwise operators work essentially like logical operators, with the |
1081 |
|
difference that bitwise operators compare each bit independently. |
1082 |
|
So a bitwise <code>.and.</code> operator for instance takes the 1st bit |
1083 |
|
of the left hand's side value, the 1st bit of the right hand's side value, |
1084 |
|
compares the two bits logically and then stores that result as 1st bit of |
1085 |
|
the final result value, then it takes the 2nd bit of the left hand's side value |
1086 |
|
and the 2nd bit of the right hand's side value, compares those two bits logically |
1087 |
|
and then stores that result as 2nd bit of the final result value, and so on. |
1088 |
|
</p> |
1089 |
|
|
1090 |
|
|
1091 |
<h3>Comparison Operators</h3> |
<h3>Comparison Operators</h3> |
1092 |
<p> |
<p> |