/[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 3063 by schoenebeck,
Fri Dec 16 18:26:26 2016 UTC
+revision 3608 by schoenebeck,
Wed Sep 18 13:24:28 2019 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>
-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 414 
 end on
+Line 418 
 end on
        triggered on a MIDI keyboard. The following example demonstrates how that
        could be achieved.
      </p>
-     <note>
-       You need at least LinuxSampler 2.0.0.svn2 or higher for the following
-       example to work as described and as expected. Refer to the notes of the
-       <code>wait()</code> function reference documentation for more
-       informations about this issue.
-     </note>
      <code>
  on init
    { The amount of notes to play }
-Line 768 
 on note
+Line 766 
 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 807 
 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 846 
 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 970 
 end on
+Line 968 
 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
+       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 instances would
+       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.
+       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
-Line 1014 
 end on
+Line 1013 
 end on
        substantially differs calling built-in functions from calling user functions.
      </p>
+     <h3>Synchronized Blocks</h3>
+     <p>
+       When we introduced the <a href="#polyphonic_variables">polyphonic keyword</a>
+       previously, we learned that a script may automatically be suspended by
+       the sampler at any time and then your script is thus sleeping for an
+       arbitrary while. The sampler must do such auto suspensions under certain
+       situations in cases where an instrument script may become a hazard for the
+       sampler's overall real-time stability. If the sampler would not do so, then
+       instrument scripts might easily cause audio dropouts, or at worst, buggy
+       instrument scripts might even lock up the entire sampler in an endless
+       loop. So auto suspension is an essential feature of the sampler's real-time
+       instrument script engine.
+     </p>
+     <p>
+       Now the problem as a script author is that you don't really know beforehand
+       why and when your script might get auto suspended by the sampler. And when
+       you are working on more complex, sophisticated scripts, you will notice
+       that this might indeed be a big problem in certain sections of your scripts.
+       Because in practice, a sophisticated script often has at least one certain
+       consecutive portion of statements which must be executed in strict consecutive order
+       by the sampler, which might otherwise cause concurrency issues and thus
+       misbehavior of your script if that sensible code section was auto suspended
+       in between. A typical example of such concurrency sensible code sections are
+       statements which are reading and conditionally modifying global variables.
+       If your script gets auto suspended in such a code section, another
+       script handler instance might then interfere and change those global
+       variables in between.
+     </p>
+     <p>
+       To avoid that, you can place such a sensible code section at the very beginning
+       of your event handler. For example consider you might be writing a custom
+       <i title="A consecutive pitch glide from one note to another note.">glissando</i>
+       script starting like this:
+     </p>
+     <code>
+ on init
+   declare $keysDown
+   declare $firstNoteID
+   declare $firstNoteNr
+   declare $firstVelocity
+ end on
+ on note
+   { The concurrency sensible code section for the "first active" note. }
+   inc($keysDown)
+   if ($keysDown = 1 or event_status($firstNoteID) = $EVENT_STATUS_INACTIVE)
+     $firstNoteID = $EVENT_ID
+     $firstNoteNr = $EVENT_NOTE
+     $firstVelocity = $EVENT_VELOCITY
+     exit { return from event handler here }
+   end if
+   { The non-sensible code for all other subsequent notes would go here. }
+ end on
+ on release
+   dec($keysDown)
+ end on
+     </code>
+     <p>
+       Because the earlier statements are executed in an event handler, the higher
+       the chance that they will never get auto suspended. And with those couple of
+       lines in the latter example you might even be lucky that it won't ever get
+       suspended in that sensible code section at least. However when it comes to live
+       concerts you don't really want to depend on luck, and in practice such a
+       sensible code section might be bigger than this one.
+     </p>
+     <p>
+       That's why we introduced <code>synchronized</code> code blocks for the
+       NKSP language, which have the following form:
+     </p>
+     <code>
+ synchronized
+   ??statements??
+ end synchronized
+     </code>
+     <p>
+       All <code>??statements??</code> which you put into such a synchronized
+       code block are guaranteed that they will never get auto suspended by
+       the sampler.
+     </p>
+     <note>
+       Such <code>synchronized</code> blocks are a language extension which
+       is only available with NKSP. KSP does not support <code>synchronized</code> blocks.
+     </note>
+     <p>
+       So to make our previous example concurrency safe, we would
+       change it like this:
+     </p>
+     <code>
+ on init
+   declare $keysDown
+   declare $firstNoteID
+   declare $firstNoteNr
+   declare $firstVelocity
+ end on
+ on note
+   { The concurrency sensible code section for the "first active" note. }
+   synchronized
+     inc($keysDown)
+     if ($keysDown = 1 or event_status($firstNoteID) = $EVENT_STATUS_INACTIVE)
+       $firstNoteID = $EVENT_ID
+       $firstNoteNr = $EVENT_NOTE
+       $firstVelocity = $EVENT_VELOCITY
+       exit { return from event handler here }
+     end if
+   end synchronized
+   { The non-sensible code for all other subsequent notes would go here. }
+ end on
+ on release
+   dec($keysDown)
+ end on
+     </code>
+     <p>
+       If you are already familiar with some programming languages, then you
+       might already have seen such synchronized code block concepts
+       in languages like i.e. Java. This technique really provides an easy way
+       to protect certain sections of your script against concurrency issues.
+     </p>
+     <note class="important">
+       You <b>must</b> use such <code>synchronized</code> code blocks only with great
+       care! If the amount of statements being executed in your synchronized block
+       is too large, then you will get audio dropouts. If you even use loops in
+       synchronized code blocks, then the entire sampler might even become
+       unresponsive in case your script is buggy!
+     </note>
      <h2>Operators</h2>
      <p>
        A programming language provides so called <i>operators</i> to perform
-Line 1059 
 end on
+Line 1190 
 end on
        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>.
+       precisely <code>0</code> is interpreted as being boolean <i>false</i>.
      </p>
      <p>
        So the logical operators shown above always look at numbers at a whole.
-Line 1106 
 end on
+Line 1237 
 end on
      </code>
      <p>
        All these operations yield in a <i>boolean</i> result which could then
-       by used i.e. with <code>if</code> or <code>while</code> loop statements.
+       be used i.e. with <code>if</code> or <code>while</code> loop statements.
      </p>
      <h3>String Operators</h3>
-Line 1362 
 end on
+Line 1493 
 end on
        use the preprocessor instead for such things. And like stated above,
        there are certain things which you can only achieve with the preprocessor.
      </p>
+     <h3>Disable Messages</h3>
+     <p>
+       Since it is quite common to switch a script between a development version
+       and a production version, you actually don't need to wrap all your
+       <code>message()</code> calls into preprocessor statements like in the
+       previous example just to disable messages. There is actually a built-in
+       preprocessor condition dedicated to perform that task much more conveniently for you.
+       To disable all messages in your script, simply add <code>SET_CONDITION(NKSP_NO_MESSAGE)</code>
+       i.e. at the very beginning of your script.
+       So the previous example can be simplified like this:
+     </p>
+     <code>
+ { Enable debug mode, so show all debug messages. }
+ SET_CONDITION(DEBUG_MODE)
+ { If our user declared condition "DEBUG_MODE" is not set ... }
+ USE_CODE_IF_NOT(DEBUG_MODE)
+   { ... then enable this built-in condition to disable all message() calls. }
+   SET_CONDITION(NKSP_NO_MESSAGE)
+ END_USE_CODE
+ on init
+   declare const %primes[12] :=  ( 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37 )
+   declare $i
+   message("This script has just been loaded.")
+   USE_CODE_IF(DEBUG_MODE)
+   $i := 0
+   while ($i < num_elements(%primes))
+     message("Prime " & $i & " is " & %primes[$i])
+     $i := $i + 1
+   end while
+   END_USE_CODE
+ end on
+ on note
+   message("Note " & $EVENT_NOTE & " was triggered with velocity " & $EVENT_VELOCITY)
+ end on
+ on release
+   message("Note " & $EVENT_NOTE & " was released with release velocity " & $EVENT_VELOCITY)
+ end on
+ on controller
+   message("MIDI Controller " & $CC_NUM " changed its value to " & %CC[$CC_NUM])
+ end on
+     </code>
+     <p>
+       You can then actually also add <code>RESET_CONDITION(NKSP_NO_MESSAGE)</code>
+       at another section of your script, which will cause all subsequent
+       <code>message()</code> calls to be processed again. So that way you can
+       easily enable and disable <code>message()</code> calls of entire individual
+       sections of your script, without having to wrap all <code>message()</code>
+       calls into preprocessor statements.
+     </p>
      <h2>What Next?</h2>
      <p>
        You have completed the introduction of the NKSP real-time instrument
-Line 1372 
 end on
+Line 1560 
 end on
        Which provides you an overview and quick access to the details of all
        built-in functions, built-in variables and more.
      </p>
+     <p>
+       You might also be interested to look at new <i>NKSP</i> core language
+       features being added to the latest development version of the sampler:
+       <a href="real_unit_final/01_nksp_real_unit_final.html">
+         Real Numbers, Units and Finalness ...
+       </a>
+     </p>
    </body>
  </html>

 Legend:



Removed from v.3063
 


changed lines


 
Added in v.3608
 Legend:



Removed from v.3063
 


changed lines


 
Added in v.3608
-Removed from v.3063
+Added in v.3608

	ViewVC Help
Powered by ViewVC