--- doc/docbase/instrument_scripts/nksp/real_unit_final/01_nksp_real_unit_final.html 2019/09/17 17:37:51 3604 +++ doc/docbase/instrument_scripts/nksp/real_unit_final/01_nksp_real_unit_final.html 2019/09/17 19:44:02 3605 @@ -3,7 +3,7 @@ Real Numbers, Units and Finalness Real_Numbers_Units_and_Finalness - + @@ -105,7 +105,8 @@ initialized with zero value(s) (that is 0.0 actually).

- I actually already had plans for implementing floating point support in NKSP + I actually already had plans for implementing floating point support in + NKSP much earlier, but I somehow had the feeling that KSP would add it as well. And I though before "inventing" again some kind of new syntax set for this feature and then having to somehow merge and maintain cross-compatibility between KSP syntax @@ -184,7 +185,7 @@ if you pass integers instead then you'll get an integer as result instead.

- Then there are functions, like e.g. the new functions sin(), cos(), + Then there are functions, like e.g. the new math functions sin(), cos(), tan(), sqrt(), which only accept real numbers as arguments (and always return a real number as result). Trying to pass integers will cause a parser error, because those particular functions are not really useful on integers at all. @@ -310,7 +311,7 @@

What about the other comparison operators like <, >, <=, >=? Well, - those other comparison operators all behave as with system level + those other comparison operators all behave like with system level programming languages. So these comparison operators currently do not take the mentioned floating point tolerances into account and hence they behave differently than the = @@ -430,7 +431,7 @@

Calculating with Units

- 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. Of course you can do much more with this feature than just passing them literally to some built-in function call as we did above so far. You can assign them to variables, too, like: @@ -523,6 +524,8 @@ $foo := 8ms, but you must not change the variable ever to a different unit type later on like $foo := 8Hz. Trying to switch the variable to a different unit type that way will cause a parser error. + Changing the fundamental unit type of a variable is not allowed, because it + would change the semantical meaning of the variable.

What may look like a lousy limitation of the technical implementation @@ -543,7 +546,7 @@ your script code. So you neither have to load the script into the sampler, nor do you have to run and test the code just to spot such kind of mistakes. You will always see them instantly - in the code editor. + in the code editor while you are typing your code.

So getting back and proceed with an early example, this code would be fine: @@ -557,6 +560,8 @@

+ That's Ok because the built-in function change_vol() + optionally accepts the unit B for its 2nd argument. Whereas the following would immediately raise a parser error:

@@ -611,7 +616,8 @@ B short for "Bel" - May be used for volume changes. + May be used for volume changes and other kinds of relative changes + (e.g. depth of envelope generators). @@ -802,11 +808,11 @@ in your script to change the volume of voices of a note, then the actual, final volume value being applied to the voices is not just the value that you passed to change_vol(), but rather a combination of that value and values of other modulation sources of volume - 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 changing value coming from an amplitude LFO that you might be using in your instrument patch, and you might most certainly also use an amplitude envelope generator which will also have its impact on the final volume of course. - 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 to eventually calculate the actual, final volume to be applied to the voices, like illustrated in the following schematic figure.

@@ -865,7 +871,7 @@ whereas in use cases where you would always apply the $volume "finally" and probably need to pass it to several change_vol() function calls at several places in your script, - then you might store the "finalness" directly to the variable instead. + then you might store the "finalness" information directly to the variable instead.

KSP is also using the exclamation mark in front of variable names of string arrays. @@ -941,7 +947,7 @@

- + @@ -988,7 +994,7 @@

The reason is also exactly the same, because finalness is a parse-time required information - and an array access by using yet another variable like e.g. might + and an array access by using yet another variable like e.g. %foo[$someVar] might break that parse-time awareness of "finalness" for the compiler.

@@ -998,7 +1004,7 @@

Backward Compatibility

- 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, do they break your old scripts?

@@ -1007,27 +1013,28 @@

Our goal was always to preserve constant behaviour for existing sounds, so that even ancient sound files in GigaSampler v1 format still would sound - 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 + (probably with GigaSampler at that time). And that means the same policy applies to instrument scripts as well of course.

You can also arbitrarily mix your existing instrument scripts by just partly using the new features described in this article at some sections of your scripts, while - 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 are designed that they won't break anything existing, and that they always - collaborate correctly in a mixed way with old NKSP code. + collaborate correctly in an arbitrary, mixed way with old NKSP code.

Status Quo

- That's it! For now ... + That's it!  For now ...

This is the current development state regarding these new NKSP core language features. It might not be the final word though. I am aware certain aspects that I decided can be argued about (or maybe even entire features). And that's actually one of the reasons why I decided to write this (even for my habits) - 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 decisions that I took.

Unit Type Relative Final ReasonUnit Type Relative Final Reason
None