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> |
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 |
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. |
311 |
<p> |
<p> |
312 |
What about the other comparison operators like <code><</code>, |
What about the other comparison operators like <code><</code>, |
313 |
<code>></code>, <code><=</code>, <code>>=</code>? Well, |
<code>></code>, <code><=</code>, <code>>=</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> |
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: |
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 |
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: |
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> |
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 |
|
|
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> |
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. |
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 Type</th> <th>Relative</th> <th>Final</th> <th>Reason</th> |
951 |
</tr> |
</tr> |
952 |
<tr> |
<tr> |
953 |
<td>None</td> |
<td>None</td> |
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"> |
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> |
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! 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> |