juce_ARAAudioReaders.h

/*
  ==============================================================================
 
   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.
 
  ==============================================================================
*/
 
#pragma once
 
namespace juce
{
 
class AudioProcessor;
 
/* All these readers follow a common pattern of "invalidation":
 
   Whenever the samples they are reading are altered, the readers become invalid and will stop
   accessing the model graph. These alterations are model edits such as property changes, content
   changes (if affecting sample scope), or the deletion of some model object involved in the read
   process. Since these edits are performed on the document controller thread, reader validity can
   immediately be checked after the edit has been concluded, and any reader that has become invalid
   can be recreated.
 
   Note that encountering a failure in any individual read call does not invalidate the reader, so
   that the entity using the reader can decide whether to retry or to back out. This includes trying
   to read an audio source for which the host has currently disabled access: the failure will be
   immediately visible, but the reader will remain valid. This ensures that for example a realtime
   renderer can just keep reading and will be seeing proper samples again once sample access is
   re-enabled.
 
   If desired, the code calling readSamples() can also implement proper signaling of any read error
   to the document controller thread to trigger rebuilding the reader as needed. This will typically
   be done when implementing audio source analysis: if there is an error upon reading the samples
   that cannot be resolved within a reasonable timeout, then the analysis would be aborted. The
   document controller code that monitors the analysis tasks can evaluate this and re-launch a new
   analysis when appropriate (e.g. when access is re-enabled).
 
   When reading playback regions (directly or through a region sequence reader), the reader will
   represent the regions as a single source object that covers the union of all affected regions.
   The first sample produced by the reader thus will be the first sample of the earliest region.
   This means that the location of this region has to be taken into account by the calling code if
   it wants to relate the samples to the model or any other reader output.
*/
 
//==============================================================================
class JUCE_API  ARAAudioSourceReader  : public AudioFormatReader,
                                        private ARAAudioSource::Listener
{
public:
    explicit ARAAudioSourceReader (ARAAudioSource* audioSource);
 
    ~ARAAudioSourceReader() override;
 
    bool readSamples (int* const* destSamples,
                      int numDestChannels,
                      int startOffsetInDestBuffer,
                      int64 startSampleInFile,
                      int numSamples) override;

    bool isValid() const { return audioSourceBeingRead != nullptr; }

    void invalidate();
 
    void willUpdateAudioSourceProperties (ARAAudioSource* audioSource,
                                          ARAAudioSource::PropertiesPtr newProperties) override;
    void doUpdateAudioSourceContent (ARAAudioSource* audioSource,
                                     ARAContentUpdateScopes scopeFlags) override;
    void willEnableAudioSourceSamplesAccess (ARAAudioSource* audioSource, bool enable) override;
    void didEnableAudioSourceSamplesAccess (ARAAudioSource* audioSource, bool enable) override;
    void willDestroyAudioSource (ARAAudioSource* audioSource) override;
 
private:
    ARAAudioSource* audioSourceBeingRead;
    std::unique_ptr<ARA::PlugIn::HostAudioReader> hostReader;
    ReadWriteLock lock;
    std::vector<void*> tmpPtrs;
 
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ARAAudioSourceReader)
};
 
//==============================================================================
class JUCE_API  ARAPlaybackRegionReader   : public AudioFormatReader,
                                            private ARAPlaybackRegion::Listener
{
public:
    explicit ARAPlaybackRegionReader (ARAPlaybackRegion* playbackRegion);

    ARAPlaybackRegionReader (double sampleRate, int numChannels,
                             const std::vector<ARAPlaybackRegion*>& playbackRegions);
 
    ~ARAPlaybackRegionReader() override;

    bool isValid() const { return (playbackRenderer != nullptr); }

    void invalidate();
 
    bool readSamples (int* const* destSamples,
                      int numDestChannels,
                      int startOffsetInDestBuffer,
                      int64 startSampleInFile,
                      int numSamples) override;
 
    void willUpdatePlaybackRegionProperties (ARAPlaybackRegion* playbackRegion,
                                             ARAPlaybackRegion::PropertiesPtr newProperties) override;
    void didUpdatePlaybackRegionContent (ARAPlaybackRegion* playbackRegion,
                                         ARAContentUpdateScopes scopeFlags) override;
    void willDestroyPlaybackRegion (ARAPlaybackRegion* playbackRegion) override;

    int64 startInSamples = 0;
 
private:
    std::unique_ptr<ARAPlaybackRenderer> playbackRenderer;
    AudioPlayHead::PositionInfo positionInfo;
    ReadWriteLock lock;
 
    static constexpr int maximumBlockSize = 4 * 1024;
 
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ARAPlaybackRegionReader)
};
 
} // namespace juce