/[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 3063 by schoenebeck, Fri Dec 16 18:26:26 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. 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
# Line 962  end on Line 1043  end on
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
# Line 975  on init Line 1056  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>
Legend:
Removed from v.2763  
changed lines
  Added in v.3063
  ViewVC Help
Powered by ViewVC