juce_AudioProcessor.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2022 - Raw Material Software Limited
 
   JUCE is an open source library subject to commercial or open-source
   licensing.
 
   By using JUCE, you agree to the terms of both the JUCE 7 End-User License
   Agreement and JUCE Privacy Policy.
 
   End User License Agreement: www.juce.com/juce-7-licence
   Privacy Policy: www.juce.com/juce-privacy-policy
 
   Or: You may also use this code under the terms of the GPL v3 (see
   www.gnu.org/licenses).
 
   JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
   EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
   DISCLAIMED.
 
  ==============================================================================
*/
 
namespace juce
{
 
//==============================================================================
class JUCE_API  AudioProcessor
{
protected:
    struct BusesProperties;
 
    //==============================================================================
    AudioProcessor();

    AudioProcessor (const BusesProperties& ioLayouts);

    AudioProcessor (const std::initializer_list<const short[2]>& channelLayoutList)
        : AudioProcessor (busesPropertiesFromLayoutArray (layoutListToArray (channelLayoutList)))
    {
    }
 
public:
    //==============================================================================
    enum ProcessingPrecision
    {
        singlePrecision,
        doublePrecision
    };
 
    enum class Realtime
    {
        no,
        yes
    };
 
    using ChangeDetails = AudioProcessorListener::ChangeDetails;
 
    //==============================================================================
    virtual ~AudioProcessor();
 
    //==============================================================================
    virtual const String getName() const = 0;

    virtual StringArray getAlternateDisplayNames() const;
 
    //==============================================================================
    virtual void prepareToPlay (double sampleRate,
                                int maximumExpectedSamplesPerBlock) = 0;

    virtual void releaseResources() = 0;

    virtual void memoryWarningReceived()     { jassertfalse; }

    virtual void processBlock (AudioBuffer<float>& buffer,
                               MidiBuffer& midiMessages) = 0;

    virtual void processBlock (AudioBuffer<double>& buffer,
                               MidiBuffer& midiMessages);

    virtual void processBlockBypassed (AudioBuffer<float>& buffer,
                                       MidiBuffer& midiMessages);

    virtual void processBlockBypassed (AudioBuffer<double>& buffer,
                                       MidiBuffer& midiMessages);
 
 
    //==============================================================================
    struct BusesLayout
    {
        Array<AudioChannelSet> inputBuses;

        Array<AudioChannelSet> outputBuses;

        int getNumChannels (bool isInput, int busIndex) const noexcept
        {
            auto& bus = (isInput ? inputBuses : outputBuses);
            return isPositiveAndBelow (busIndex, bus.size()) ? bus.getReference (busIndex).size() : 0;
        }

        AudioChannelSet& getChannelSet (bool isInput, int busIndex) noexcept
        {
            return (isInput ? inputBuses : outputBuses).getReference (busIndex);
        }

        AudioChannelSet getChannelSet (bool isInput, int busIndex) const noexcept
        {
            return (isInput ? inputBuses : outputBuses)[busIndex];
        }

        AudioChannelSet getMainInputChannelSet()  const noexcept    { return getChannelSet (true,  0); }

        AudioChannelSet getMainOutputChannelSet() const noexcept    { return getChannelSet (false, 0); }

        int getMainInputChannels()  const noexcept                  { return getNumChannels (true, 0); }

        int getMainOutputChannels() const noexcept                  { return getNumChannels (false, 0); }
 
        bool operator== (const BusesLayout& other) const noexcept   { return inputBuses == other.inputBuses && outputBuses == other.outputBuses; }
        bool operator!= (const BusesLayout& other) const noexcept   { return inputBuses != other.inputBuses || outputBuses != other.outputBuses; }
    };
 
    //==============================================================================
    class Bus
    {
    public:
        bool isInput() const noexcept;

        int getBusIndex() const noexcept;

        bool isMain() const noexcept                                    { return getBusIndex() == 0; }
 
        //==============================================================================
        const String& getName() const noexcept                          { return name; }

        const AudioChannelSet& getDefaultLayout() const noexcept        { return dfltLayout; }
 
        //==============================================================================
        const AudioChannelSet& getCurrentLayout() const noexcept        { return layout; }

        const AudioChannelSet& getLastEnabledLayout() const noexcept    { return lastLayout; }

        bool setCurrentLayout (const AudioChannelSet& layout);

        bool setCurrentLayoutWithoutEnabling (const AudioChannelSet& layout);

        inline int getNumberOfChannels() const noexcept                 { return cachedChannelCount; }

        bool setNumberOfChannels (int channels);
 
        //==============================================================================
        bool isLayoutSupported (const AudioChannelSet& set, BusesLayout* currentLayout = nullptr) const;

        bool isNumberOfChannelsSupported (int channels) const;

        AudioChannelSet supportedLayoutWithChannels (int channels) const;

        int getMaxSupportedChannels (int limit = AudioChannelSet::maxChannelsOfNamedLayout) const;

        BusesLayout getBusesLayoutForLayoutChangeOfBus (const AudioChannelSet& set) const;
 
        //==============================================================================
        bool isEnabled() const noexcept                             { return ! layout.isDisabled(); }

        bool enable (bool shouldEnable = true);

        bool isEnabledByDefault() const noexcept                    { return enabledByDefault; }
 
        //==============================================================================
        int getChannelIndexInProcessBlockBuffer (int channelIndex) const noexcept;
 

        template <typename FloatType>
        AudioBuffer<FloatType> getBusBuffer (AudioBuffer<FloatType>& processBlockBuffer) const
        {
            auto di = getDirectionAndIndex();
            return owner.getBusBuffer (processBlockBuffer, di.isInput, di.index);
        }
 
    private:
        friend class AudioProcessor;
        Bus (AudioProcessor&, const String&, const AudioChannelSet&, bool);
 
        struct BusDirectionAndIndex
        {
            bool isInput;
            int index;
        };
 
        BusDirectionAndIndex getDirectionAndIndex() const noexcept;
        void updateChannelCount() noexcept;
 
        AudioProcessor& owner;
        String name;
        AudioChannelSet layout, dfltLayout, lastLayout;
        bool enabledByDefault;
        int cachedChannelCount;
 
        JUCE_DECLARE_NON_COPYABLE (Bus)
    };
 
    //==============================================================================
    int getBusCount (bool isInput) const noexcept                   { return (isInput ? inputBuses : outputBuses).size(); }

    Bus* getBus (bool isInput, int busIndex) noexcept               { return getBusImpl (*this, isInput, busIndex); }

    const Bus* getBus (bool isInput, int busIndex) const noexcept   { return getBusImpl (*this, isInput, busIndex); }
 
    //==============================================================================
    virtual bool canAddBus (bool isInput) const                     { ignoreUnused (isInput); return false; }

    virtual bool canRemoveBus (bool isInput) const                  { ignoreUnused (isInput); return false; }

    bool addBus (bool isInput);

    bool removeBus (bool isInput);
 
    //==============================================================================
    bool setBusesLayout (const BusesLayout&);

    bool setBusesLayoutWithoutEnabling (const BusesLayout&);

    BusesLayout getBusesLayout() const;

    AudioChannelSet getChannelLayoutOfBus (bool isInput, int busIndex) const noexcept;

    bool setChannelLayoutOfBus (bool isInput, int busIndex, const AudioChannelSet& layout);

    inline int getChannelCountOfBus (bool isInput, int busIndex) const noexcept
    {
        if (auto* bus = getBus (isInput, busIndex))
            return bus->getNumberOfChannels();
 
        return 0;
    }

    bool enableAllBuses();

    bool disableNonMainBuses();
 
    //==============================================================================
    int getChannelIndexInProcessBlockBuffer (bool isInput, int busIndex, int channelIndex) const noexcept;

    int getOffsetInBusBufferForAbsoluteChannelIndex (bool isInput, int absoluteChannelIndex, int& busIndex) const noexcept;

    template <typename FloatType>
    AudioBuffer<FloatType> getBusBuffer (AudioBuffer<FloatType>& processBlockBuffer, bool isInput, int busIndex) const
    {
        auto busNumChannels = getChannelCountOfBus (isInput, busIndex);
        auto channelOffset = getChannelIndexInProcessBlockBuffer (isInput, busIndex, 0);
 
        return AudioBuffer<FloatType> (processBlockBuffer.getArrayOfWritePointers() + channelOffset,
                                       busNumChannels, processBlockBuffer.getNumSamples());
    }
 
    //==============================================================================
    bool checkBusesLayoutSupported (const BusesLayout&) const;
 
    //==============================================================================
    virtual bool supportsDoublePrecisionProcessing() const;

    ProcessingPrecision getProcessingPrecision() const noexcept         { return processingPrecision; }

    bool isUsingDoublePrecision() const noexcept                        { return processingPrecision == doublePrecision; }

    void setProcessingPrecision (ProcessingPrecision newPrecision) noexcept;
 
    //==============================================================================
    AudioPlayHead* getPlayHead() const noexcept                 { return playHead; }
 
    //==============================================================================
    int getTotalNumInputChannels()  const noexcept              { return cachedTotalIns; }

    int getTotalNumOutputChannels() const noexcept              { return cachedTotalOuts; }

    inline int getMainBusNumInputChannels()   const noexcept    { return getChannelCountOfBus (true,  0); }

    inline int getMainBusNumOutputChannels()  const noexcept    { return getChannelCountOfBus (false, 0); }
 
    //==============================================================================
    static bool containsLayout (const BusesLayout& layouts, const std::initializer_list<const short[2]>& channelLayoutList)
    {
        return containsLayout (layouts, layoutListToArray (channelLayoutList));
    }
 
    template <size_t numLayouts>
    static bool containsLayout (const BusesLayout& layouts, const short (&channelLayoutList) [numLayouts][2])
    {
        return containsLayout (layouts, layoutListToArray (channelLayoutList));
    }

    template <size_t numLayouts>
    BusesLayout getNextBestLayoutInLayoutList (const BusesLayout& layouts,
                                               const short (&channelLayoutList) [numLayouts][2])
    {
        return getNextBestLayoutInList (layouts, layoutListToArray (channelLayoutList));
    }
 
    //==============================================================================
    double getSampleRate() const noexcept                       { return currentSampleRate; }

    int getBlockSize() const noexcept                           { return blockSize; }
 
    //==============================================================================

    int getLatencySamples() const noexcept                      { return latencySamples; }

    void setLatencySamples (int newLatency);

    virtual double getTailLengthSeconds() const = 0;

    virtual bool acceptsMidi() const = 0;

    virtual bool producesMidi() const = 0;

    virtual bool supportsMPE() const                            { return false; }

    virtual bool isMidiEffect() const                           { return false; }
 
    //==============================================================================
    const CriticalSection& getCallbackLock() const noexcept     { return callbackLock; }

    void suspendProcessing (bool shouldBeSuspended);

    bool isSuspended() const noexcept                                   { return suspended; }

    virtual void reset();
 
    //==============================================================================
    virtual AudioProcessorParameter* getBypassParameter() const        { return nullptr; }
 
    //==============================================================================
    bool isNonRealtime() const noexcept                                 { return nonRealtime; }

    Realtime isRealtime() const noexcept
    {
        return isNonRealtime() ? Realtime::no : Realtime::yes;
    }

    virtual void setNonRealtime (bool isNonRealtime) noexcept;
 
   #if ! JUCE_AUDIOPROCESSOR_NO_GUI
    //==============================================================================
    virtual AudioProcessorEditor* createEditor() = 0;

    virtual bool hasEditor() const = 0;
 
    //==============================================================================
    AudioProcessorEditor* getActiveEditor() const noexcept;

    AudioProcessorEditor* createEditorIfNeeded();
   #endif
 
    //==============================================================================
    static int getDefaultNumParameterSteps() noexcept;

    void updateHostDisplay (const ChangeDetails& details = ChangeDetails::getDefaultFlags());
 
    //==============================================================================
    void addParameter (AudioProcessorParameter*);

    void addParameterGroup (std::unique_ptr<AudioProcessorParameterGroup>);

    const AudioProcessorParameterGroup& getParameterTree() const;

    void setParameterTree (AudioProcessorParameterGroup&& newTree);

    virtual void refreshParameterList();

    const Array<AudioProcessorParameter*>& getParameters() const;
 
    //==============================================================================
    virtual int getNumPrograms() = 0;

    virtual int getCurrentProgram() = 0;

    virtual void setCurrentProgram (int index) = 0;

    virtual const String getProgramName (int index) = 0;

    virtual void changeProgramName (int index, const String& newName) = 0;
 
    //==============================================================================
    virtual void getStateInformation (juce::MemoryBlock& destData) = 0;

    virtual void getCurrentProgramStateInformation (juce::MemoryBlock& destData);

    virtual void setStateInformation (const void* data, int sizeInBytes) = 0;

    virtual void setCurrentProgramStateInformation (const void* data, int sizeInBytes);

    virtual void numChannelsChanged();

    virtual void numBusesChanged();

    virtual void processorLayoutsChanged();
 
    //==============================================================================
    virtual void addListener (AudioProcessorListener* newListener);

    virtual void removeListener (AudioProcessorListener* listenerToRemove);
 
    //==============================================================================
    virtual void setPlayHead (AudioPlayHead* newPlayHead);
 
    //==============================================================================
    void setPlayConfigDetails (int numIns, int numOuts, double sampleRate, int blockSize);

    void setRateAndBufferSizeDetails (double sampleRate, int blockSize) noexcept;
 
    //==============================================================================
    virtual int32 getAAXPluginIDForMainBusConfig (const AudioChannelSet& mainInputLayout,
                                                  const AudioChannelSet& mainOutputLayout,
                                                  bool idForAudioSuite) const;
 
    //==============================================================================
    struct CurveData
    {
        enum class Type  : int
        {
            EQ,             // an EQ curve - input is in Hz, output is in dB
            Dynamics,       // a dynamics curve - input and output is in dB
            GainReduction,  // a gain reduction curve - input and output is in dB
 
            Unknown = -1
        };
 
        std::function<float (float)> curve;   // a function which represents your curve (such as an eq)
        Range<float> xRange, yRange;          // the data range of your curve
 
        // For some curve types, your plug-in may already measure the current input and output values.
        // An host can use to indicate where on the curve the current signal is (for example
        // by putting a dot on the curve). Simply leave these strings empty if you do not want to
        // support this.
        String xMeterID, yMeterID;
    };
 
    virtual CurveData getResponseCurve (CurveData::Type /*curveType*/) const      { return {}; }
 
   #if ! JUCE_AUDIOPROCESSOR_NO_GUI
    //==============================================================================
    void editorBeingDeleted (AudioProcessorEditor*) noexcept;
   #endif

    enum WrapperType
    {
        wrapperType_Undefined = 0,
        wrapperType_VST,
        wrapperType_VST3,
        wrapperType_AudioUnit,
        wrapperType_AudioUnitv3,
        wrapperType_AAX,
        wrapperType_Standalone,
        wrapperType_Unity,
        wrapperType_LV2
    };

    const WrapperType wrapperType;

    static const char* getWrapperTypeDescription (AudioProcessor::WrapperType) noexcept;
 

    struct TrackProperties
    {
        String name;    // The name of the track - this will be empty if the track name is not known
       #if ! JUCE_AUDIOPROCESSOR_NO_GUI
        Colour colour;  // The colour of the track - this will be transparentBlack if the colour is not known
       #endif
 
        // other properties may be added in the future
    };

    virtual void updateTrackProperties (const TrackProperties& properties);
 
    //==============================================================================
    static void copyXmlToBinary (const XmlElement& xml,
                                 juce::MemoryBlock& destData);

    static std::unique_ptr<XmlElement> getXmlFromBinary (const void* data, int sizeInBytes);

    static void JUCE_CALLTYPE setTypeOfNextNewPlugin (WrapperType);
 
protected:
    virtual bool isBusesLayoutSupported (const BusesLayout&) const          { return true; }

    virtual bool canApplyBusesLayout (const BusesLayout& layouts) const     { return isBusesLayoutSupported (layouts); }

    virtual bool applyBusLayouts (const BusesLayout& layouts);
 
    //==============================================================================
    struct BusProperties
    {
        String busName;

        AudioChannelSet defaultLayout;

        bool isActivatedByDefault;
    };

    struct BusesProperties
    {
        Array<BusProperties> inputLayouts;

        Array<BusProperties> outputLayouts;
 
        void addBus (bool isInput, const String& name, const AudioChannelSet& defaultLayout, bool isActivatedByDefault = true);
 
        JUCE_NODISCARD BusesProperties withInput  (const String& name, const AudioChannelSet& defaultLayout, bool isActivatedByDefault = true) const;
        JUCE_NODISCARD BusesProperties withOutput (const String& name, const AudioChannelSet& defaultLayout, bool isActivatedByDefault = true) const;
    };

    virtual bool canApplyBusCountChange (bool isInput, bool isAddingBuses,
                                         BusProperties& outNewBusProperties);
 
    //==============================================================================
    std::atomic<AudioPlayHead*> playHead { nullptr };

    void sendParamChangeMessageToListeners (int parameterIndex, float newValue);
 
public:
   #ifndef DOXYGEN
    // These methods are all deprecated in favour of using AudioProcessorParameter
    // and AudioProcessorParameterGroup
    [[deprecated]] virtual int getNumParameters();
    [[deprecated]] virtual const String getParameterName (int parameterIndex);
    [[deprecated]] virtual String getParameterID (int index);
    [[deprecated]] virtual float getParameter (int parameterIndex);
    [[deprecated]] virtual String getParameterName (int parameterIndex, int maximumStringLength);
    [[deprecated]] virtual const String getParameterText (int parameterIndex);
    [[deprecated]] virtual String getParameterText (int parameterIndex, int maximumStringLength);
    [[deprecated]] virtual int getParameterNumSteps (int parameterIndex);
    [[deprecated]] virtual bool isParameterDiscrete (int parameterIndex) const;
    [[deprecated]] virtual float getParameterDefaultValue (int parameterIndex);
    [[deprecated]] virtual String getParameterLabel (int index) const;
    [[deprecated]] virtual bool isParameterOrientationInverted (int index) const;
    [[deprecated]] virtual void setParameter (int parameterIndex, float newValue);
    [[deprecated]] virtual bool isParameterAutomatable (int parameterIndex) const;
    [[deprecated]] virtual bool isMetaParameter (int parameterIndex) const;
    [[deprecated]] virtual AudioProcessorParameter::Category getParameterCategory (int parameterIndex) const;
    [[deprecated]] void beginParameterChangeGesture (int parameterIndex);
    [[deprecated]] void endParameterChangeGesture (int parameterIndex);
    [[deprecated]] void setParameterNotifyingHost (int parameterIndex, float newValue);
 
    // These functions are deprecated: your audio processor can inform the host
    // on its bus and channel layouts and names using the AudioChannelSet and various bus classes.
    [[deprecated]] int getNumInputChannels() const noexcept                   { return getTotalNumInputChannels(); }
    [[deprecated]] int getNumOutputChannels() const noexcept                  { return getTotalNumOutputChannels(); }
    [[deprecated]] const String getInputSpeakerArrangement() const noexcept   { return cachedInputSpeakerArrString; }
    [[deprecated]] const String getOutputSpeakerArrangement() const noexcept  { return cachedOutputSpeakerArrString; }
    [[deprecated]] virtual const String getInputChannelName  (int channelIndex) const;
    [[deprecated]] virtual const String getOutputChannelName (int channelIndex) const;
    [[deprecated]] virtual bool isInputChannelStereoPair  (int index) const;
    [[deprecated]] virtual bool isOutputChannelStereoPair (int index) const;
   #endif
 
private:
    //==============================================================================
    struct InOutChannelPair
    {
        InOutChannelPair() = default;
 
        InOutChannelPair (int16 inCh, int16 outCh) noexcept    : inChannels (inCh), outChannels (outCh) {}
        InOutChannelPair (const int16 (&config)[2]) noexcept   : inChannels (config[0]), outChannels (config[1]) {}
 
        bool operator== (const InOutChannelPair& other) const noexcept
        {
            return other.inChannels == inChannels && other.outChannels == outChannels;
        }
 
        int16 inChannels = 0, outChannels = 0;
    };
 
    template <size_t numLayouts>
    static Array<InOutChannelPair> layoutListToArray (const short (&configuration) [numLayouts][2])
    {
        Array<InOutChannelPair> layouts;
 
        for (size_t i = 0; i < numLayouts; ++i)
            layouts.add (InOutChannelPair (configuration[(int) i]));
 
        return layouts;
    }
 
    static Array<InOutChannelPair> layoutListToArray (const std::initializer_list<const short[2]>& configuration)
    {
        Array<InOutChannelPair> layouts;
 
        for (auto&& i : configuration)
            layouts.add (InOutChannelPair (i));
 
        return layouts;
    }
 
    template <typename This>
    static auto getBusImpl (This& t, bool isInput, int busIndex) -> decltype (t.getBus (isInput, busIndex))
    {
        return (isInput ? t.inputBuses : t.outputBuses)[busIndex];
    }
 
    //==============================================================================
    static BusesProperties busesPropertiesFromLayoutArray (const Array<InOutChannelPair>&);
 
    BusesLayout getNextBestLayoutInList (const BusesLayout&, const Array<InOutChannelPair>&) const;
    static bool containsLayout (const BusesLayout&, const Array<InOutChannelPair>&);
 
    //==============================================================================
    void createBus (bool isInput, const BusProperties&);
 
    //==============================================================================
    Array<AudioProcessorListener*> listeners;
   #if ! JUCE_AUDIOPROCESSOR_NO_GUI
    Component::SafePointer<AudioProcessorEditor> activeEditor;
   #endif
    double currentSampleRate = 0;
    int blockSize = 0, latencySamples = 0;
    bool suspended = false;
    std::atomic<bool> nonRealtime { false };
    ProcessingPrecision processingPrecision = singlePrecision;
    CriticalSection callbackLock, listenerLock, activeEditorLock;
 
    friend class Bus;
    mutable OwnedArray<Bus> inputBuses, outputBuses;
 
    String cachedInputSpeakerArrString, cachedOutputSpeakerArrString;
    int cachedTotalIns = 0, cachedTotalOuts = 0;
 
    AudioProcessorParameterGroup parameterTree;
    Array<AudioProcessorParameter*> flatParameterList;
 
    AudioProcessorParameter* getParamChecked (int) const;
 
  #if JUCE_DEBUG
   #if ! JUCE_DISABLE_AUDIOPROCESSOR_BEGIN_END_GESTURE_CHECKING
    BigInteger changingParams;
   #endif
 
    bool textRecursionCheck = false;
    std::unordered_set<String> paramIDs, groupIDs;
   #if ! JUCE_DISABLE_CAUTIOUS_PARAMETER_ID_CHECKING
    std::unordered_set<String> trimmedParamIDs;
   #endif
  #endif
 
    void checkForDuplicateTrimmedParamID (AudioProcessorParameter*);
    void validateParameter (AudioProcessorParameter*);
    void checkForDuplicateParamID (AudioProcessorParameter*);
    void checkForDuplicateGroupIDs (const AudioProcessorParameterGroup&);
 
    AudioProcessorListener* getListenerLocked (int) const noexcept;
    void updateSpeakerFormatStrings();
    void audioIOChanged (bool busNumberChanged, bool channelNumChanged);
    void getNextBestLayout (const BusesLayout&, BusesLayout&) const;
 
    template <typename floatType>
    void processBypassed (AudioBuffer<floatType>&, MidiBuffer&);
 
    friend class AudioProcessorParameter;
    friend class LADSPAPluginInstance;
 
    [[deprecated ("This method is no longer used - you can delete it from your AudioProcessor classes.")]]
    virtual bool silenceInProducesSilenceOut() const  { return false; }
 
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (AudioProcessor)
};
 
} // namespace juce