/[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 2995 by schoenebeck, Sat Sep 24 23:53:21 2016 UTC revision 3061 by schoenebeck, Fri Dec 16 17:20:55 2016 UTC
# Line 928  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

Legend:
Removed from v.2995  
changed lines
  Added in v.3061

  ViewVC Help
Powered by ViewVC