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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 2763 by schoenebeck, Wed May 6 21:14:19 2015 UTC revision 3061 by schoenebeck, Fri Dec 16 17:20:55 2016 UTC
# Line 18  Line 18 
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.
# Line 414  end on Line 414  end on
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
# Line 932  end on Line 928  end on
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. When working on larger scripts, you
937          may notice that you easily get to the point where you may have to
938          duplicate portions of your script code, since there are certain things
939          that you may have to do again and again in different parts of your script.
940          Software developers usually try to avoid such code duplications to
941          keep the overall amount of code as small as possible, since it would
942          make the software very hard to maintain. One way for you to avoid such
943          script code duplications with NKSP is to write so called <i>User Functions</s>.
944        </p>
945        <p>
946          Let's assume you wanted to create a simple stuttering effect. You may do so
947          like in the following example.
948        </p>
949        <code>
950    on note
951      while (1)
952        wait(200000)
953        if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
954          exit()
955        end if
956        change_vol($EVENT_ID, -20000)  { Reduce volume by 20 dB. }
957        wait(200000)
958        if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
959          exit()
960        end if
961        change_vol($EVENT_ID, 0)  { Increase volume to 0 dB. }
962      end while
963    end on
964        </code>
965        <p>
966          This script will run an endless loop for each note being triggered.
967          Every <code>200ms</code> it will turn the volume alternatingly down and
968          up to create the audible stuttering effect. After each <code>wait()</code>
969          call it calls <code>event_status($EVENT_ID)</code> to check whether
970          this note is still alive, and as soon as the note died, it will stop
971          execution of the script instance by calling <code>exit()</code>. The latter
972          is important in this case, because otherwise the script instances would
973          continue to run in this endless loop forever, even after the respectives
974          notes are gone. Which would let your CPU usage to increase with every note.
975          This behavior of the sampler is not a bug, it is intended, since there may
976          also be cases where you want to do certain things by script even after the
977          respective notes are dead and gone. However as you can see, that script is
978          using the same portions of script code twice. To avoid that, you could also
979          write the same script with a user function like this:
980        </p>
981        <code>
982    function pauseMyScript
983      wait(200000)
984      if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
985        exit()
986      end if
987    end function
988            
989    on note
990      while (1)
991        call pauseMyScript
992        change_vol($EVENT_ID, -20000)  { Reduce volume by 20 dB. }
993        call pauseMyScript
994        change_vol($EVENT_ID, 0)  { Increase volume back to 0 dB. }
995      end while
996    end on
997        </code>
998        <p>
999          The script became in this simple example only slightly smaller, but it also
1000          became easier to read. And in practice, with a more complex script, you can
1001          reduce the overall amount of script code a lot this way. You can choose any
1002          name for your own user functions, as long as the name is not already
1003          reserved by a built-in function. Note that for calling a user function,
1004          you must always precede the actual user function name with the
1005          <code>call</code> keyword. Likewise you may however not use the
1006          <code>call</code> keyword for calling any built-in function. So that
1007          substantially differs calling built-in functions from calling user functions.
1008        </p>
1009    
1010      <h2>Operators</h2>      <h2>Operators</h2>
1011      <p>      <p>
1012        A programming language provides so called <i>operators</i> to perform        A programming language provides so called <i>operators</i> to perform
# Line 962  end on Line 1036  end on
1036      <h3>Boolean Operators</h3>      <h3>Boolean Operators</h3>
1037      <p>      <p>
1038        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
1039        following boolean operators:        following logical operators:
1040      </p>      </p>
1041      <code>      <code>
1042  on init  on init
# Line 975  on init Line 1049  on init
1049  end on  end on
1050      </code>      </code>
1051      <p>      <p>
1052        Remember that with boolean operations, all integer values other than <code>0</code>        Keep in mind that with logical operators shown above,
1053          all integer values other than <code>0</code>
1054        are interpreted as boolean <i>true</i> while an integer value of        are interpreted as boolean <i>true</i> while an integer value of
1055        precisely <code>0</code> is interpreted of being boolean <i>false</i>.        precisely <code>0</code> is interpreted of being boolean <i>false</i>.
1056      </p>      </p>
1057        <p>
1058          So the logical operators shown above always look at numbers at a whole.
1059          Sometimes however you might rather need to process numbers bit by bit. For
1060          that purpose the following bitwise operators exist.
1061        </p>
1062        <code>
1063    on init
1064      message("1 .and. 1 is " & 1 .and. 1)  { bitwise "and" }
1065      message("1 .and. 0 is " & 1 .and. 0)  { bitwise "and" }
1066      message("1 .or. 1 is " & 1 .or. 1)    { bitwise "or" }
1067      message("1 .or. 0 is " & 1 .or. 0)    { bitwise "or" }
1068      message(".not. 1 is " & .not. 1)      { bitwise "not" }
1069      message(".not. 0 is " & .not. 0)      { bitwise "not" }
1070    end on
1071        </code>
1072        <p>
1073          Bitwise operators work essentially like logical operators, with the
1074          difference that bitwise operators compare each bit independently.
1075          So a bitwise <code>.and.</code> operator for instance takes the 1st bit
1076          of the left hand's side value, the 1st bit of the right hand's side value,
1077          compares the two bits logically and then stores that result as 1st bit of
1078          the final result value, then it takes the 2nd bit of the left hand's side value
1079          and the 2nd bit of the right hand's side value, compares those two bits logically
1080          and then stores that result as 2nd bit of the final result value, and so on.
1081        </p>
1082    
1083            
1084      <h3>Comparison Operators</h3>      <h3>Comparison Operators</h3>
1085      <p>      <p>
Legend:
Removed from v.2763  
changed lines
  Added in v.3061
  ViewVC Help
Powered by ViewVC