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

Initialize

The initialize function is called before all other functions when the script starts. Here, you can check your variables, set or update input and output parameters, and if you encounter any errors during initialization, you can return false to prevent the script from running.

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

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

The second version (which returns bool) exists in both AngelScript and C++ APIs and is more powerful, so it is recommended to use that one.

For example, during initialization, you can check the sampleRate value, and if your script doesn't support it, you can return false to prevent the 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), allowing you to create a convenient function for adding parameters, as explained in the article "How to add parameters conveniently".

ALERT

In some cases (as seen in the Mac C++ API, for example), the initialize function can be called several times. If you are performing actions that rely on the previous state of variables, such as adding a value to the end of an array, be cautious, as it may be added twice. To avoid issues, set a flag to check if initialization has already been executed.

Important for native API

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

  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 the C++ API, you have to do it in the initialize function, 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, the initialize function can also be called when the user changes the sampleRate, buffer size, etc. So from the script's point of view, it's much like restarting a script.

Initialize and shutdown

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

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

Comments

Please, authorize to view and post comments.