Week 2: Introducing Plugin GUI Magic (PGM)

Understanding JUCE Plugin Parameters

PGM, following JUCE-recommended best practice, requires us to create a juce::AudioProcessorValueTreeState (APVTS) in our processor to hold all of our plugin parameter info in a hierarchically grouped ParameterLayout:

1. We create our parameters before our processor is fully created, and add them to our ParameterLayout that we pass to the APVTS constructor.
2. We create the APVTS ourselves (in our derived class of foleys::MagicProcessor which is a derived class of juce::AudioProcessor).
3. During the APVTS construction, which happens during our processor initialization, we bind ourselves (the processor - "this") permanently and uniquely to the APVTS as the processorToConnectTo.
4. Summary of the above three points:

   AudioProcessor()
       APVTS()
          createParameterLayout()
          create and return the parameters in a juce::AudioProcessorParameterGroup
          MOVE the parameters into the parameters array OWNED BY THE APVTS
       Later you can access the parameters via APVTS methods such as:
          std::atomic* getRawParameterValue (StringRef parameterID)
          RangedAudioParameter* getParameter (StringRef parameterID)

5. From then on, the PGM GUI Editor (including any MIDI controllers driving the PGM parameters, etc.) will directly write the plugin parameters in memory, and the AudioProcessor will read them from the same memory.
   
6. Notes:
   • Since writing and reading of the same parameter memory may occur on two different CPU threads (we discussed the Message Thread and Audio Thread in the last lecture), std::atomic parameter pointers are used to prevent a so-called "torn" read or write due to a collision of two or more threads.
   • On most CPUs, a single-word parameter (such as a float) is thread-safe for reading and writing thanks to a built-in memory barrier for this purpose, and the Faust compiler assumes this.
   • When the C++ compiler knows a read/write is thread-safe, using std::atomic should do nothing and cost nothing at run time. It is therefore best practice to declare audio processor parameters using std::atomic and let the C++ compiler decide what is needed for thread safety, if anything.
7. Recommended Reading
   • Read carefully the documentation for the first APVTS constructor.
     Note that "controlling the processor" in this context means manipulating its parameter values.
     You can probably get by simply following parameter handling in the PGM examples (if followed precisely),
     but a better plan is to study the PGM examples after digesting the following:
   • Read the reference doc for AudioProcessorValueTreeState (APVTS).
   • Read the reference doc for the APVTS contained-class ParameterLayout, which we must create and pass to the APVTS constructor.
   • Read the reference doc for the two types of classes that can be added to a ParameterLayout:
     • RangedAudioParameter
     • AudioProcessorParameterGroup
   • In class we discussed virtual function definition and when to have them in header files versus .cpp files.
     Since this discussion was quite incomplete, I recorded an interesting chat with GPT-4 on these topics.

This is the most advanced C++ we will have to deal with in Music 320c, involving unique smart pointers and a rigid construction/initialization process.

Be aware that this APVTS-based method of handling plugin parameters is relatively recent, so you'll find older JUCE code, even in official JUCE tutorials, that uses the older (deprecated) processor-based management of the plugin parameters. In particular, createAndAddParameter() is deprecated, so avoid examples using that.