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

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

Parent Directory | Revision Log | View Patch Patch

-revision 2872 by schoenebeck,
Sun Apr 10 18:42:55 2016 UTC
+revision 3191 by schoenebeck,
Fri May 19 15:19:37 2017 UTC
 Line 11
        your own instrument scripts in short time. It concentrates on describing
        the script language. If you rather want to learn how to modify and
        attach scripts to your sounds, then please refer to the gigedit manual for
-       <a href="gigedit_scripts.html">how to manage instrument scripts with gigedit</a>.
+       <a href="gigedit_scripts.html">how to manage instrument scripts with gigedit</a>
+       for Gigasampler/GigaStudio format sounds, or refer to the SFZ opcode
+       <code lang="sfz">script</code> for attaching NKSP scripts with
+       SFZ format sounds.
      </p>
      <h3>At a Glance</h3>
      <p>
        <img src="nksp_file.png" style="height:111px; margin-right:12px;">
        NKSP stands for "is <b>N</b>ot <b>KSP</b>", which denotes its distinction
-       to an existing proprieatary language called <i>KSP</i>.
+       to an existing proprietary language called <i>KSP</i>.
        NSKP is a script language specifically designed to write real-time capable
        software extensions to LinuxSampler's sampler engines that can be bundled
        individually with sounds by sound designers themselves.
-Line 251 
 end on
+Line 254 
 end on
      <p>
        The left hand side's <code>??variable-name??</code> is an arbitrary name
        you can chose for your variable. That name might consist of English
-       letters A to Z (lower and upper case) and the underscore character "<code>_</code>".
+       letters A to Z (lower and upper case), digits (<code>0</code> to <code>9</code>),
+       and the underscore character "<code>_</code>".
        Variable names must be unique. So you can neither declare several variables
        with the same name, nor can you use a name for your variable that is
        already been reserved by <i>built-in variables</i>.
-Line 768 
 on note
+Line 772 
 on note
        @postfix := "nd"
      case 3
        @postfix := "rd"
-   end if
+   end select
    message("This is the " & $numberOfNotes & @postfix & " note triggered so far.")
  end on
-Line 809 
 on note
+Line 813 
 on note
      case 3
        message("Third note was triggered!") { Will never be printed ! }
        exit
-   end if
+   end select
    message("Wow, already the " & $numberOfNotes & "th note triggered.")
  end on
-Line 848 
 on note
+Line 852 
 on note
      case 1 to 99
        message("Less than 100 notes triggered so far")
        exit
-   end if
+   end select
    message("Wow, already the " & $numberOfNotes & "th note triggered.")
  end on
-Line 928 
 end on
+Line 932 
 end on
        loop is thus left at that point and the text message was printed
        three times in total.
      </p>
+     <h3>User Functions</h3>
+     <p>
+       We already came across various built-in functions, which you may call
+       by your scripts to perform certain tasks or behavior which is already
+       provided for you by the sampler. NKSP also allows you to write your
+       own functions, which you then may call from various places of your
+       script.
+     <p>
+     </p>
+       When working on larger scripts, you
+       may notice that you easily get to the point where you may have to
+       duplicate portions of your script code, since there are certain things
+       that you may have to do again and again in different parts of your script.
+       Software developers usually try to avoid such code duplications to
+       keep the overall amount of code as small as possible, since the
+       overall amount of code would bloat quickly and would
+       make the software very hard to maintain. One way for you to avoid such
+       script code duplications with NKSP is to write so called <i>User Functions</s>.
+     </p>
+     <p>
+       Let's assume you wanted to create a simple stuttering effect. You may do so
+       like in the following example.
+     </p>
+     <code>
+ on note
+   while (1)
+     wait(200000)
+     if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
+       exit()
+     end if
+     change_vol($EVENT_ID, -20000)  { Reduce volume by 20 dB. }
+     wait(200000)
+     if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
+       exit()
+     end if
+     change_vol($EVENT_ID, 0)  { Increase volume to 0 dB. }
+   end while
+ end on
+     </code>
+     <p>
+       This script will run an endless loop for each note being triggered.
+       Every <code lang="none">200ms</code> it will turn the volume alternatingly down and
+       up to create the audible stuttering effect. After each <code lang="nksp">wait()</code>
+       call it calls <code>event_status($EVENT_ID)</code> to check whether
+       this note is still alive, and as soon as the note died, it will stop
+       execution of the script instance by calling <code>exit()</code>. The latter
+       is important in this example, because otherwise the script execution instances would
+       continue to run in this endless loop forever, even after the respectives
+       notes are gone. Which would let your CPU usage to increase with every new note
+       and would never decrease again.
+       This behavior of the sampler is not a bug, it is intended, since there may
+       also be cases where you want to do certain things by script even after the
+       respective notes are dead and gone. However as you can see, that script is
+       using the same portions of script code twice. To avoid that, you could also
+       write the same script with a user function like this:
+     </p>
+     <code>
+ function pauseMyScript
+   wait(200000)
+   if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
+     exit()
+   end if
+ end function
+ on note
+   while (1)
+     call pauseMyScript
+     change_vol($EVENT_ID, -20000)  { Reduce volume by 20 dB. }
+     call pauseMyScript
+     change_vol($EVENT_ID, 0)  { Increase volume back to 0 dB. }
+   end while
+ end on
+     </code>
+     <p>
+       The script became in this simple example only slightly smaller, but it also
+       became easier to read and behaves identically to the previous solution.
+       And in practice, with a more complex script, you can
+       reduce the overall amount of script code a lot this way. You can choose any
+       name for your own user functions, as long as the name is not already
+       reserved by a built-in function. Note that for calling a user function,
+       you must always precede the actual user function name with the
+       <code>call</code> keyword. Likewise you may however not use the
+       <code>call</code> keyword for calling any built-in function. So that
+       substantially differs calling built-in functions from calling user functions.
+     </p>
      <h2>Operators</h2>
      <p>
        A programming language provides so called <i>operators</i> to perform
-Line 958 
 end on
+Line 1048 
 end on
      <h3>Boolean Operators</h3>
      <p>
        To perform logical transformations of <i>boolean</i> data, you may use the
-       following boolean operators:
+       following logical operators:
      </p>
      <code>
  on init
-Line 971 
 on init
+Line 1061 
 on init
  end on
      </code>
      <p>
-       Remember that with boolean operations, all integer values other than <code>0</code>
+       Keep in mind that with logical operators shown above,
+       all integer values other than <code>0</code>
        are interpreted as boolean <i>true</i> while an integer value of
        precisely <code>0</code> is interpreted of being boolean <i>false</i>.
      </p>
+     <p>
+       So the logical operators shown above always look at numbers at a whole.
+       Sometimes however you might rather need to process numbers bit by bit. For
+       that purpose the following bitwise operators exist.
+     </p>
+     <code>
+ on init
+   message("1 .and. 1 is " & 1 .and. 1)  { bitwise "and" }
+   message("1 .and. 0 is " & 1 .and. 0)  { bitwise "and" }
+   message("1 .or. 1 is " & 1 .or. 1)    { bitwise "or" }
+   message("1 .or. 0 is " & 1 .or. 0)    { bitwise "or" }
+   message(".not. 1 is " & .not. 1)      { bitwise "not" }
+   message(".not. 0 is " & .not. 0)      { bitwise "not" }
+ end on
+     </code>
+     <p>
+       Bitwise operators work essentially like logical operators, with the
+       difference that bitwise operators compare each bit independently.
+       So a bitwise <code>.and.</code> operator for instance takes the 1st bit
+       of the left hand's side value, the 1st bit of the right hand's side value,
+       compares the two bits logically and then stores that result as 1st bit of
+       the final result value, then it takes the 2nd bit of the left hand's side value
+       and the 2nd bit of the right hand's side value, compares those two bits logically
+       and then stores that result as 2nd bit of the final result value, and so on.
+     </p>
      <h3>Comparison Operators</h3>
      <p>

 Legend:



Removed from v.2872
 


changed lines


 
Added in v.3191
 Legend:



Removed from v.2872
 


changed lines


 
Added in v.3191
-Removed from v.2872
+Added in v.3191

	ViewVC Help
Powered by ViewVC