/[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 3262 by schoenebeck,
Wed May 31 23:19:39 2017 UTC
+revision 3717 by schoenebeck,
Mon Jan 13 13:29:05 2020 UTC
 Line 67 
 on ??event-name??
  end on
      </code>
      <p>
-       There are currently four events available:
+       There are currently six events available:
      </p>
        <table>
          <tr>
 Line 77 
 end on
            <td><code>on note</code></td> <td>This event handler is executed when a new note was triggered, i.e. when hitting a key on a MIDI keyboard.</td>
          </tr>
          <tr>
-           <td><code>on release</code></td> <td>This event handler is executed when a new note was released, i.e. when releasing a key on a MIDI keyboard.</td>
+           <td><code>on release</code></td> <td>This event handler is executed when a note was released, i.e. when releasing a key on a MIDI keyboard.</td>
          </tr>
          <tr>
            <td><code>on controller</code></td> <td>This event handler is executed when a MIDI control change event occurred. For instance when turning the modulation wheel at a MIDI keyboard.</td>
          </tr>
          <tr>
+           <td><code>on rpn</code></td> <td>This event handler is executed when a MIDI <i>RPN</i> event occurred.</td>
+         </tr>
+         <tr>
+           <td><code>on nrpn</code></td> <td>This event handler is executed when a MIDI <i>NRPN</i> event occurred.</td>
+         </tr>
+         <tr>
            <td><code>on init</code></td> <td>Executed only once, as very first event handler, right after the script had been loaded. This code block is usually used to initialize variables in your script with some initial, useful data.</td>
          </tr>
        </table>
-Line 147 
 end on
+Line 153 
 end on
        Please note that you can hardly find MIDI keyboards which support release
        velocity. So with most keyboards this value will be 127.
      </p>
      <h3>Controller Events</h3>
      <p>
        Now let's extend the first script to not only show note-on and note-off
-Line 180 
 end on
+Line 186 
 end on
      </p>
      <p>
        There is some special aspect you need to be aware about: in contrast to the MIDI standard,
-       monophonic aftertouch (a.k.a. channel pressure) and pitch beend wheel are
+       monophonic aftertouch (a.k.a. channel pressure) and pitch bend wheel are
        handled by NKSP as if they were regular MIDI controllers. So a value change
        of one of those two triggers a regular <code>controller</code> event handler
        to be executed. To obtain the current aftertouch value you can use
        <code>%CC[$VCC_MONO_AT]</code>, and to get the current pitch bend wheel
        value use <code>%CC[$VCC_PITCH_BEND]</code>.
      </p>
+     <h3>RPN / NRPN Events</h3>
+     <p>
+       There are also dedicated event handlers for
+       MIDI <i title="Registered Parameter Number">RPN</i> and
+       <i title="Non-Registered Parameter Number">NRPN</i>
+       events:
+     </p>
+     <code>
+ on rpn
+   message("RPN address msb=" & msb($RPN_ADDRESS) & ",lsb=" & lsb($RPN_ADDRESS) &
+           "-> value msb=" & msb($RPN_VALUE) & ",lsb="  & lsb($RPN_VALUE))
+   if ($RPN_ADDRESS = 2)
+     message("Standard Coarse Tuning RPN received")
+   end if
+ end on
+ on nrpn
+   message("NRPN address msb=" & msb($RPN_ADDRESS) & ",lsb=" & lsb($RPN_ADDRESS) &
+           "-> value msb=" & msb($RPN_VALUE) & ",lsb="  & lsb($RPN_VALUE))
+ end on
+     </code>
+     <p>
+       Since MIDI RPN and NRPN events are actually MIDI controller events,
+       you might as well handle these with the previous
+       <code>controller</code> event handler. But since RPN and NRPN messages
+       are not just one MIDI message, but rather always handled by a set of
+       individual MIDI messages, and since the
+       precise set and sequence of actual MIDI commands sent varies between
+       vendors and even among individual of their products, it highly makes sense to
+       use these two specialized event handlers for these instead, because the
+       sampler will already relief you from that burden to deal with all those
+       low-level MIDI event processing issues and all their wrinkles involved
+       when handling RPNs and NRPNs.
+     </p>
+     <note>
+       Even though there are two separate, dedicated event handlers for RPN and NRPN events,
+       they both share the same built-in variable names as you can see in the
+       example above.
+     </note>
+     <p>
+       So by reading <code>$RPN_ADDRESS</code> you get the RPN / NRPN parameter
+       number that had been changed, and <code>$RPN_VALUE</code> represents the
+       new value of that RPN / NRPN parameter. Note that these two built-in
+       variables are a 14-bit representation of the parameter number and new
+       value. So their possible value range is <code>0 .. 16383</code>. If you
+       rather want to use their (in MIDI world) more common separated two 7 bit
+       values instead, then you can easily do that by wrapping them into either
+       <code>msb()</code> or <code>lsb()</code> calls like also demonstrated above.
+     </p>
      <h3>Script Load Event</h3>
      <p>
-       As the last one of the four event types available with NKSP, the following
+       As the last one of the six event types available with NKSP, the following
        is an example of an <code>init</code> event handler.
      </p>
      <code>
-Line 214 
 end on
+Line 270 
 end on
        had in mind when you wrote a certain script three years ago, and also if
        some other developer might need to continue working on your scripts one
        day, you should place as many comments into your scripts as possible. A
-       comment in NKSP is everything that is nested into a an opening and closing
+       comment in NKSP is everything that is nested into an opening and closing
        pair of curly braces.
      </p>
      <code>{ This is a comment. }</code>
-Line 299 
 end on
+Line 355 
 end on
      <h3>Variable Types</h3>
      <p>
-       There are currently three different variable types, which you can easily
+       There are currently five different variable types, which you can easily
        recognize upon their first character.
      </p>
      <table>
-Line 313 
 end on
+Line 369 
 end on
          <td><code>%??variable-name??</code></td> <td>Integer Array</td> <td>Stores a certain amount of integer number values.</td>
        </tr>
        <tr>
+         <td><code>~??variable-name??</code></td> <td>Real Number Scalar</td> <td>Stores one single real (floating point) number value.</td>
+       </tr>
+       <tr>
+         <td><code>???variable-name??</code></td> <td>Real Number Array</td> <td>Stores a certain amount of real (floating point) number values.</td>
+       </tr>
+       <tr>
          <td><code>@??variable-name??</code></td> <td>String</td> <td>Stores one text string.</td>
        </tr>
      </table>
-Line 413 
 end on
+Line 475 
 end on
      </p>
      <p>
        Let's assume you wanted to write an instrument script that shall resemble
-       a simple delay effect. You could do that by writing an note event handler
+       a simple delay effect. You could do that by writing a note event handler
        that automatically triggers several new notes for each note being
        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 478 
 end on
+Line 534 
 end on
        happening when executing that script exactly: Each time you play a note
        on your keyboard, a new instance of the <code>note</code> event handler
        will be spawned and executed by the sampler. In all our examples so far
-       our scripts were so simple, that in practice only one handler instance
+       our scripts were so simple, that in practice only one event handler instance
        was executed at a time. This is different in this case though. Because
        by calling the <code>wait()</code> function, the respective handler
        execution instance is paused for a while and in total each handler
-Line 487 
 end on
+Line 543 
 end on
        you play multiple, successive notes on your keyboard in short time, you
        will have several instances of the <code>note</code> event handler running
        simultaniously. And that's where the problem starts. Because by default,
-       as said, all variables are global variables. So the handler instances
+       as said, all variables are global variables. So the event handler instances
        which are now running in parallel, are all reading and modifying the same
-       data. Thus the individual handler instances will modify the
+       data. Thus the individual event handler instances will modify the
        <code>$i</code> and <code>$velocity</code> variables of each other, causing
        an undesired misbehavior.
      </p>
-Line 981 
 end on
+Line 1037 
 end on
        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
+       notes are gone. Which would let your CPU usage 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
-Line 1021 
 end on
+Line 1077 
 end on
      <h3>Synchronized Blocks</h3>
      <p>
-       When we introduced the <a href="polyphonic_variables">polyphonic keyword</a>
+       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
-Line 1104 
 end synchronized
+Line 1160 
 end synchronized
      </p>
      <note>
        Such <code>synchronized</code> blocks are a language extension which
-       is only available with NKSP and requires at least LinuxSampler 2.0.0.svn60
+       is only available with NKSP. KSP does not support <code>synchronized</code> blocks.
-       or higher. KSP does not support <code>synchronized</code> blocks.
      </note>
      <p>
        So to make our previous example concurrency safe, we would
-Line 1141 
 end on
+Line 1196 
 end on
      <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
+       in languages like e.g. Java. This technique really provides an easy way
        to protect certain sections of your script against concurrency issues.
      </p>
      <note class="important">
-Line 1197 
 end on
+Line 1252 
 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 1244 
 end on
+Line 1299 
 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 e.g. with <code>if</code> or <code>while</code> loop statements.
      </p>
      <h3>String Operators</h3>
-Line 1332 
 RESET_CONDITION(??condition-name??)
+Line 1387 
 RESET_CONDITION(??condition-name??)
        You should only reset a preprocessor condition that way if you did set it
        with <code>SET_CONDITION(??condition-name??)</code> before. Trying to
        reset a condition that has not been set before, or trying to reset a
-       condition that has already been reset, will both be ignored by the samlper,
+       condition that has already been reset, will both be ignored by the sampler,
        but again you will get a warning, and you should take care about it.
      </p>
-Line 1500 
 end on
+Line 1555 
 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>
+       e.g. at the very beginning of your script.
+       So the previous example can be simplified to 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 1510 
 end on
+Line 1622 
 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.3262
 


changed lines


 
Added in v.3717
 Legend:



Removed from v.3262
 


changed lines


 
Added in v.3717
-Removed from v.3262
+Added in v.3717

	ViewVC Help
Powered by ViewVC