/[svn]/doc/docbase/instrument_scripts/nksp/real_unit_final/01_nksp_real_unit_final.html
ViewVC logotype

Diff of /doc/docbase/instrument_scripts/nksp/real_unit_final/01_nksp_real_unit_final.html

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 3603 by schoenebeck, Tue Sep 17 17:21:13 2019 UTC revision 3605 by schoenebeck, Tue Sep 17 19:44:02 2019 UTC
# Line 3  Line 3 
3      <meta name="author" content="Christian Schoenebeck">      <meta name="author" content="Christian Schoenebeck">
4      <title>Real Numbers, Units and Finalness</title>      <title>Real Numbers, Units and Finalness</title>
5      <urlpath>Real_Numbers_Units_and_Finalness</urlpath>      <urlpath>Real_Numbers_Units_and_Finalness</urlpath>
6      <meta name="description" content="NKSP Development News: Support for real numbers, standard measuring units and finalness.">      <meta name="description" content="New NKSP Core Language Features: Support for real numbers, standard measuring units and finalness.">
7      <link rel="stylesheet" href="http://doc.linuxsampler.org/css/preview.css">      <link rel="stylesheet" href="http://doc.linuxsampler.org/css/preview.css">
8      <script type="text/javascript" src="http://doc.linuxsampler.org/js/preview.js"></script>      <script type="text/javascript" src="http://doc.linuxsampler.org/js/preview.js"></script>
9    </head>    </head>
# Line 105  declare ?foo[4] := ( 0.1, 2.0, 46.238, 1 Line 105  declare ?foo[4] := ( 0.1, 2.0, 46.238, 1
105        initialized with zero value(s) (that is <code>0.0</code> actually).        initialized with zero value(s) (that is <code>0.0</code> actually).
106      </p>      </p>
107      <note class="remark">      <note class="remark">
108        I actually already had plans for implementing floating point support in <i>NKSP</i>        I actually already had plans for implementing floating point support in
109          <i title="NKSP stands for 'is <b>N</b>ot <b>KSP</b>', which denotes its distinction 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.">NKSP</i>
110        much earlier, but I somehow had the feeling that <i>KSP</i> would add it as well.        much earlier, but I somehow had the feeling that <i>KSP</i> would add it as well.
111        And I though before "inventing" again some kind of new syntax set for this feature        And I though before "inventing" again some kind of new syntax set for this feature
112        and then having to somehow merge and maintain cross-compatibility between <i>KSP</i> syntax        and then having to somehow merge and maintain cross-compatibility between <i>KSP</i> syntax
# Line 184  declare ?foo[4] := ( 0.1, 2.0, 46.238, 1 Line 185  declare ?foo[4] := ( 0.1, 2.0, 46.238, 1
185        if you pass integers instead then you'll get an integer as result instead.        if you pass integers instead then you'll get an integer as result instead.
186      </p>      </p>
187      <p>      <p>
188        Then there are functions, like e.g. the new functions <code>sin()</code>, <code>cos()</code>,        Then there are functions, like e.g. the new math functions <code>sin()</code>, <code>cos()</code>,
189        <code>tan()</code>, <code>sqrt()</code>, which only accept real numbers as arguments (and        <code>tan()</code>, <code>sqrt()</code>, which only accept real numbers as arguments (and
190        always return a real number as result). Trying to pass integers will cause a parser error,        always return a real number as result). Trying to pass integers will cause a parser error,
191        because those particular functions are not really useful on integers at all.        because those particular functions are not really useful on integers at all.
# Line 310  end on Line 311  end on
311      <p>      <p>
312        What about the other comparison operators like <code>&lt;</code>,        What about the other comparison operators like <code>&lt;</code>,
313        <code>&gt;</code>, <code>&lt;=</code>, <code>&gt;=</code>? Well,        <code>&gt;</code>, <code>&lt;=</code>, <code>&gt;=</code>? Well,
314        those other comparison operators all behave as with system level        those other comparison operators all behave like with system level
315        programming languages. So these comparison operators currently        programming languages. So these comparison operators currently
316        do <b>not</b> take the mentioned floating point tolerances into        do <b>not</b> take the mentioned floating point tolerances into
317        account and hence they behave differently than the <code>=</code>        account and hence they behave differently than the <code>=</code>
# Line 430  change_tune($EVENT_ID, -24c) Line 431  change_tune($EVENT_ID, -24c)
431    
432      <h3>Calculating with Units</h3>      <h3>Calculating with Units</h3>
433      <p>      <p>
434        Having said that, these examples above were just meant as warm up scenarios.        Having said that, these examples above were just meant as warm up appetizer.
435        Of course you can do much more with this feature than just passing them        Of course you can do much more with this feature than just passing them
436        literally to some built-in function call as we did above so far.        literally to some built-in function call as we did above so far.
437        You can assign them to variables, too, like:        You can assign them to variables, too, like:
# Line 523  end on Line 524  end on
524        <code>$foo := 8ms</code>, but you must not change the variable ever to a different        <code>$foo := 8ms</code>, but you must not change the variable ever to a different
525        unit type later on like <code>$foo := 8Hz</code>. Trying to switch        unit type later on like <code>$foo := 8Hz</code>. Trying to switch
526        the variable to a different unit type that way will cause a parser error.        the variable to a different unit type that way will cause a parser error.
527          Changing the fundamental unit type of a variable is not allowed, because it
528          would change the semantical meaning of the variable.
529      </p>      </p>
530      <note class="remark">      <note class="remark">
531        What may look like a lousy limitation of the technical implementation        What may look like a lousy limitation of the technical implementation
# Line 543  end on Line 546  end on
546        your script code. So you neither        your script code. So you neither
547        have to load the script into the sampler, nor do you have to run and test the        have to load the script into the sampler, nor do you have to run and test the
548        code just to spot such kind of mistakes. You will always see them instantly        code just to spot such kind of mistakes. You will always see them instantly
549        in the code editor.        in the code editor while you are typing your code.
550      </note>      </note>
551      <p>      <p>
552        So getting back and proceed with an early example, this code would be fine:        So getting back and proceed with an early example, this code would be fine:
# Line 557  end note Line 560  end note
560        </code>        </code>
561      </p>      </p>
562      <p>      <p>
563          That's Ok because the built-in function <code>change_vol()</code>
564          optionally accepts the unit <code>B</code> for its 2nd argument.
565        Whereas the following would immediately raise a parser error:        Whereas the following would immediately raise a parser error:
566      </p>      </p>
567      <p>      <p>
# Line 611  end note Line 616  end note
616          <tr>          <tr>
617            <td><code>B</code></td>            <td><code>B</code></td>
618            <td>short for "Bel"</td>            <td>short for "Bel"</td>
619            <td>May be used for volume changes.</td>            <td>May be used for volume changes and other kinds of relative changes
620                  (e.g. depth of envelope generators).</td>
621          </tr>          </tr>
622        </table>        </table>
623    
# Line 802  declare %bar[4] := ( 800s, 1ms, 14kHz, 4 Line 808  declare %bar[4] := ( 800s, 1ms, 14kHz, 4
808        in your script to change the volume of voices of a note, then the actual, final volume        in your script to change the volume of voices of a note, then the actual, final volume
809        value being applied to the voices is not just the value that you passed to <code>change_vol()</code>,        value being applied to the voices is not just the value that you passed to <code>change_vol()</code>,
810        but rather a combination of that value and values of other modulation sources of volume        but rather a combination of that value and values of other modulation sources of volume
811        like a constant volume factor stored with the instrument patch, as well as a continuously        like a constant gain setting stored with the instrument patch, as well as a continuously
812        changing value coming from an amplitude LFO        changing value coming from an amplitude LFO
813        that you might be using in your instrument patch, and you might most certainly also use        that you might be using in your instrument patch, and you might most certainly also use
814        an amplitude envelope generator which will also have its impact on the final volume of course.        an amplitude envelope generator which will also have its impact on the final volume of course.
815        All these individual values are multiplied with each other in real-time by the sampler's engine core        All these individual volume values are multiplied with each other in real-time by the sampler's engine core
816        to eventually calculate the actual, final volume to be applied to the voices, like illustrated in the following        to eventually calculate the actual, final volume to be applied to the voices, like illustrated in the following
817        schematic figure.        schematic figure.
818      </p>      </p>
# Line 865  end note Line 871  end note
871        whereas in use cases where you would always apply the        whereas in use cases where you would always apply the
872        <code>$volume</code> "finally" and probably need to pass it to several        <code>$volume</code> "finally" and probably need to pass it to several
873        <code>change_vol()</code> function calls at several places in your script,        <code>change_vol()</code> function calls at several places in your script,
874        then you might store the "finalness" directly to the variable instead.        then you might store the "finalness" information directly to the variable instead.
875      </p>      </p>
876      <note class="remark">      <note class="remark">
877        <i>KSP</i> is also using the exclamation mark in front of variable names of string arrays.        <i>KSP</i> is also using the exclamation mark in front of variable names of string arrays.
# Line 941  end note Line 947  end note
947      <p>      <p>
948        <table>        <table>
949          <tr>          <tr>
950            <th>Unit Type</th>  <th>Relative</th>  <th>Final</th>  <th>Reason</th>            <th>Unit&nbsp;Type</th>  <th>Relative</th>  <th>Final</th>  <th>Reason</th>
951          </tr>          </tr>
952          <tr>          <tr>
953            <td>None</td>            <td>None</td>
# Line 988  declare %foo[3] := ( !-6dB, -8dB, !2dB ) Line 994  declare %foo[3] := ( !-6dB, -8dB, !2dB )
994      </p>      </p>
995      <p>      <p>
996        The reason is also exactly the same, because <i>finalness</i> is a parse-time required information        The reason is also exactly the same, because <i>finalness</i> is a parse-time required information
997        and an array access by using yet another variable like e.g. <script>%foo[%someVar]</script> might        and an array access by using yet another variable like e.g. <code>%foo[$someVar]</code> might
998        break that parse-time awareness of "finalness" for the compiler.        break that parse-time awareness of "finalness" for the compiler.
999      </p>      </p>
1000      <note class="remark">      <note class="remark">
# Line 998  declare %foo[3] := ( !-6dB, -8dB, !2dB ) Line 1004  declare %foo[3] := ( !-6dB, -8dB, !2dB )
1004    
1005      <h2>Backward Compatibility</h2>      <h2>Backward Compatibility</h2>
1006      <p>      <p>
1007        You might be asking, what do those new features mean to your existing instrument scripts,        You might be asking, what do all those new features mean to your existing instrument scripts,
1008        do they break your old scripts?        do they break your old scripts?
1009      </p>      </p>
1010      <p>      <p>
# Line 1007  declare %foo[3] := ( !-6dB, -8dB, !2dB ) Line 1013  declare %foo[3] := ( !-6dB, -8dB, !2dB )
1013      <p>      <p>
1014        Our goal was always to preserve constant behaviour for existing sounds,        Our goal was always to preserve constant behaviour for existing sounds,
1015        so that even ancient sound files in GigaSampler v1 format still would sound        so that even ancient sound files in GigaSampler v1 format still would sound
1016        exactly as you heard them originally for the 1st time many years ago (probably with GigaSampler at that time).        exactly as you heard them originally for the 1st time many, many years ago
1017          (probably with GigaSampler at that time).
1018        And that means the same policy applies to instrument scripts as well of course.        And that means the same policy applies to instrument scripts as well of course.
1019      </p>      </p>
1020      <p>      <p>
1021        You can also arbitrarily mix your existing instrument scripts by just partly using the new        You can also arbitrarily mix your existing instrument scripts by just partly using the new
1022        features described in this article at some sections of your scripts, while        features described in this article at some sections of your scripts, while
1023        at the same time preserving your old code at other sections. So these features        at the same time preserving your old code at other code sections. So these features
1024        are designed that they won't break anything existing, and that they always        are designed that they won't break anything existing, and that they always
1025        collaborate correctly in a mixed way with old <i>NKSP</i> code.        collaborate correctly in an arbitrary, mixed way with old <i>NKSP</i> code.
1026      </p>      </p>
1027    
1028      <h2>Status Quo</h2>      <h2>Status Quo</h2>
1029      <p>      <p>
1030        That's it! For now ...        That's it!&nbsp;&nbsp;For now ...
1031      </p>      </p>
1032      <p>      <p>
1033        This is the current development state regarding these new <a href="01_nksp.html">NKSP</a>        This is the current development state regarding these new <a href="01_nksp.html">NKSP</a>
1034        core language features. It might not be the final word though. I am aware certain        core language features. It might not be the final word though. I am aware certain
1035        aspects that I decided can be argued about (or maybe even entire features).        aspects that I decided can be argued about (or maybe even entire features).
1036        And that's actually one of the reasons why I decided to write this (even for my habits)        And that's actually one of the reasons why I decided to write this (even for my habits)
1037        quite long and detailed article, describing also the reasons for individual language design        quite long and detailed article, which also explained the reasons for individual language design
1038        decisions that I took.        decisions that I took.
1039      </p>      </p>
1040      <p>      <p>

Legend:
Removed from v.3603  
changed lines
  Added in v.3605

  ViewVC Help
Powered by ViewVC