Tutorial
DSP
KUIML
How-to
Scripts
DSPinitialize
August 04, 2020

Initialize

The initialize function is called before all other functions on script start. So here you can check your variables, set or update input and output parameters, and if you encounter any errors while initializing, you can return false to prevent the script from running.

There are two variants of this function in AngelScript version of PnS API:

  1. void initialize() { }
  2. bool initialize() { return true; }

The second version (which returns bool) exists in both AngelScript and C++ APIs, is more powerful, so I suggest you use that.

For example, while initializing you can check the sampleRate, and if your script doesn't support it, you can return false to prevent script from running. If everything is fine return true.

Initialize function is a place where you can update attributes of input and output parameters (and strings), so you can make a very cozy function for adding parameters, like explained in the article "How to add parameters conveniently".

ALERT

In some cases (I've seen it on Mac C++ API for example) the initialize function can be called twice. So if you are doing something that relies on previous state of variables, like adding value to the end of array, be aware, cause it can be added twice. To not get in trouble, set a flag to check if initialize was already executed.

Important for native API

Initialize is particularly important for C++ API, because it's the place where your sampleRate, audioInputsCount and other variables are initialized and set. In comparison, in AngelScript API you can use sampleRate and other variables while constructing global variables, like that:

  1. // in AngelScript you can already use variables like sampleRate etc.
  2. string name = "My script";
  3. uint halfASecondInSamples = uint(sampleRate / 10.0);
  4. uint totalInputChannels = audioInputsCount + audioInputsAuxCount;
  5.  
  6. bool initialize(){
  7. // ...
  8. return true;
  9. }

In C++ API you have to do it in initialize, like this.

  1. // in C++ you only declare them here
  2. DSP_EXPORT string name = "My script";
  3. DSP_EXPORT uint audioInputsCount=0;
  4. DSP_EXPORT uint audioInputsAuxCount=0;
  5. DSP_EXPORT double sampleRate=0;
  6.  
  7. uint halfASecondInSamples;
  8. uint totalInputChannels;
  9.  
  10. // and their values are accessible not earlier than initialize call
  11. DSP_EXPORT bool initialize() {
  12. // here global API vars like sampleRate, audioInputsCount etc are already set.
  13. halfASecondInSamples; = sampleRate / 10.0;
  14. totalInputChannels = audioInputsCount + audioInputsAuxCount;
  15. return true;
  16. }

In my experience, initialize function can be also called when user is changing sampleRate, buffer size, etc. So from script point of view it's much like restarting a script.

Initialize and shutdown

Initialize seems a proper place to open files, load libraries (for C++ API), initialize objects, etc.

To close files, free resources, there a complementary shutdown function. It is mostly useful for C++ PnS API (here you can delete what was created with new, close file handles, etc).