juce_AudioChannelSet.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.
 
   The code included in this file is provided under the terms of the ISC license
   http://www.isc.org/downloads/software-support-policy/isc-license. Permission
   To use, copy, modify, and/or distribute this software for any purpose with or
   without fee is hereby granted provided that the above copyright notice and
   this permission notice appear in all copies.
 
   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  AudioChannelSet
{
public:
    AudioChannelSet() = default;

    static AudioChannelSet JUCE_CALLTYPE disabled();
 
    //==============================================================================
    static AudioChannelSet JUCE_CALLTYPE mono();
 

    static AudioChannelSet JUCE_CALLTYPE stereo();
 
 
    //==============================================================================
    static AudioChannelSet JUCE_CALLTYPE createLCR();
 

    static AudioChannelSet JUCE_CALLTYPE createLRS();
 

    static AudioChannelSet JUCE_CALLTYPE createLCRS();
 
 
    //==============================================================================
    static AudioChannelSet JUCE_CALLTYPE create5point0();
 

    static AudioChannelSet JUCE_CALLTYPE create5point1();
 

    static AudioChannelSet JUCE_CALLTYPE create6point0();
 

    static AudioChannelSet JUCE_CALLTYPE create6point1();
 

    static AudioChannelSet JUCE_CALLTYPE create6point0Music();
 

    static AudioChannelSet JUCE_CALLTYPE create6point1Music();
 

    static AudioChannelSet JUCE_CALLTYPE create7point0();
 

    static AudioChannelSet JUCE_CALLTYPE create7point0SDDS();
 

    static AudioChannelSet JUCE_CALLTYPE create7point1();
 

    static AudioChannelSet JUCE_CALLTYPE create7point1SDDS();

    static AudioChannelSet JUCE_CALLTYPE create5point0point2();

    static AudioChannelSet JUCE_CALLTYPE create5point1point2();

    static AudioChannelSet JUCE_CALLTYPE create5point0point4();

    static AudioChannelSet JUCE_CALLTYPE create5point1point4();

    static AudioChannelSet JUCE_CALLTYPE create7point0point2();

    static AudioChannelSet JUCE_CALLTYPE create7point1point2();

    static AudioChannelSet JUCE_CALLTYPE create7point0point4();

    static AudioChannelSet JUCE_CALLTYPE create7point1point4();

    static AudioChannelSet JUCE_CALLTYPE create7point0point6();

    static AudioChannelSet JUCE_CALLTYPE create7point1point6();

    static AudioChannelSet JUCE_CALLTYPE create9point0point4();

    static AudioChannelSet JUCE_CALLTYPE create9point1point4();

    static AudioChannelSet JUCE_CALLTYPE create9point0point6();

    static AudioChannelSet JUCE_CALLTYPE create9point1point6();
 
    //==============================================================================
    static AudioChannelSet JUCE_CALLTYPE quadraphonic();
 

    static AudioChannelSet JUCE_CALLTYPE pentagonal();
 

    static AudioChannelSet JUCE_CALLTYPE hexagonal();
 

    static AudioChannelSet JUCE_CALLTYPE octagonal();
 
    //==============================================================================
    static AudioChannelSet JUCE_CALLTYPE ambisonic (int order = 1);

    int getAmbisonicOrder() const;
 
    //==============================================================================
    static AudioChannelSet JUCE_CALLTYPE discreteChannels (int numChannels);

    static AudioChannelSet JUCE_CALLTYPE canonicalChannelSet (int numChannels);

    static AudioChannelSet JUCE_CALLTYPE namedChannelSet (int numChannels);

    static Array<AudioChannelSet> JUCE_CALLTYPE channelSetsWithNumberOfChannels (int numChannels);
 
    //==============================================================================
    enum ChannelType
    {
        unknown             = 0, 
 
        //==============================================================================
        left                = 1, 
        right               = 2, 
        centre              = 3, 
 
        //==============================================================================
        LFE                 = 4,              
        leftSurround        = 5,              
        rightSurround       = 6,              
        leftCentre          = 7,              
        rightCentre         = 8,              
        centreSurround      = 9,              
        surround            = centreSurround, 
        leftSurroundSide    = 10,             
        rightSurroundSide   = 11,             
        topMiddle           = 12,             
        topFrontLeft        = 13,             
        topFrontCentre      = 14,             
        topFrontRight       = 15,             
        topRearLeft         = 16,             
        topRearCentre       = 17,             
        topRearRight        = 18,             
        LFE2                = 19,             
        leftSurroundRear    = 20,             
        rightSurroundRear   = 21,             
        wideLeft            = 22,             
        wideRight           = 23,             
 
        //==============================================================================
        // Used by Dolby Atmos 7.0.2 and 7.1.2
        topSideLeft         = 28, 
        topSideRight        = 29, 
 
        //==============================================================================
        // Ambisonic ACN formats - all channels are SN3D normalised
 
        // zero-th and first-order ambisonic ACN
        ambisonicACN0       = 24, 
        ambisonicACN1       = 25, 
        ambisonicACN2       = 26, 
        ambisonicACN3       = 27, 
 
        // second-order ambisonic
        ambisonicACN4       = 30, 
        ambisonicACN5       = 31, 
        ambisonicACN6       = 32, 
        ambisonicACN7       = 33, 
        ambisonicACN8       = 34, 
 
        // third-order ambisonic
        ambisonicACN9       = 35, 
        ambisonicACN10      = 36, 
        ambisonicACN11      = 37, 
        ambisonicACN12      = 38, 
        ambisonicACN13      = 39, 
        ambisonicACN14      = 40, 
        ambisonicACN15      = 41, 
 
        // fourth-order ambisonic
        ambisonicACN16      = 42, 
        ambisonicACN17      = 43, 
        ambisonicACN18      = 44, 
        ambisonicACN19      = 45, 
        ambisonicACN20      = 46, 
        ambisonicACN21      = 47, 
        ambisonicACN22      = 48, 
        ambisonicACN23      = 49, 
        ambisonicACN24      = 50, 
 
        // fifth-order ambisonic
        ambisonicACN25      = 51, 
        ambisonicACN26      = 52, 
        ambisonicACN27      = 53, 
        ambisonicACN28      = 54, 
        ambisonicACN29      = 55, 
        ambisonicACN30      = 56, 
        ambisonicACN31      = 57, 
        ambisonicACN32      = 58, 
        ambisonicACN33      = 59, 
        ambisonicACN34      = 60, 
        ambisonicACN35      = 61, 
 
        //==============================================================================
        ambisonicW          = ambisonicACN0, 
        ambisonicX          = ambisonicACN3, 
        ambisonicY          = ambisonicACN1, 
        ambisonicZ          = ambisonicACN2, 
 
        //==============================================================================
        bottomFrontLeft     = 62, 
        bottomFrontCentre   = 63, 
        bottomFrontRight    = 64, 
 
        proximityLeft       = 65, 
        proximityRight      = 66, 
 
        bottomSideLeft      = 67, 
        bottomSideRight     = 68, 
        bottomRearLeft      = 69, 
        bottomRearCentre    = 70, 
        bottomRearRight     = 71, 
 
        //==============================================================================
 
        // sixth-order ambisonic
        ambisonicACN36      = 72, 
        ambisonicACN37      = 73, 
        ambisonicACN38      = 74, 
        ambisonicACN39      = 75, 
        ambisonicACN40      = 76, 
        ambisonicACN41      = 77, 
        ambisonicACN42      = 78, 
        ambisonicACN43      = 79, 
        ambisonicACN44      = 80, 
        ambisonicACN45      = 81, 
        ambisonicACN46      = 82, 
        ambisonicACN47      = 83, 
        ambisonicACN48      = 84, 
 
        // seventh-order ambisonic
        ambisonicACN49      = 85, 
        ambisonicACN50      = 86, 
        ambisonicACN51      = 87, 
        ambisonicACN52      = 88, 
        ambisonicACN53      = 89, 
        ambisonicACN54      = 90, 
        ambisonicACN55      = 91, 
        ambisonicACN56      = 92, 
        ambisonicACN57      = 93, 
        ambisonicACN58      = 94, 
        ambisonicACN59      = 95, 
        ambisonicACN60      = 96, 
        ambisonicACN61      = 97, 
        ambisonicACN62      = 98, 
        ambisonicACN63      = 99, 
 
        //==============================================================================
        discreteChannel0    = 128  
    };

    static String JUCE_CALLTYPE getChannelTypeName (ChannelType);

    static String JUCE_CALLTYPE getAbbreviatedChannelTypeName (ChannelType);

    static ChannelType JUCE_CALLTYPE getChannelTypeFromAbbreviation (const String& abbreviation);
 
    //==============================================================================
    enum
    {
        maxChannelsOfNamedLayout = 64
    };

    void addChannel (ChannelType newChannelType);

    void removeChannel (ChannelType newChannelType);

    int size() const noexcept;

    bool isDisabled() const noexcept                    { return size() == 0; }

    Array<ChannelType> getChannelTypes() const;

    ChannelType getTypeOfChannel (int channelIndex) const noexcept;

    int getChannelIndexForType (ChannelType type) const noexcept;

    String getSpeakerArrangementAsString() const;

    static AudioChannelSet fromAbbreviatedString (const String& set);

    String getDescription() const;

    bool isDiscreteLayout() const noexcept;

    void intersect (const AudioChannelSet& other)      { channels &= other.channels; }

    static AudioChannelSet JUCE_CALLTYPE channelSetWithChannels (const Array<ChannelType>&);
 
    //==============================================================================
    // Conversion between wave and juce channel layout identifiers

    static AudioChannelSet JUCE_CALLTYPE fromWaveChannelMask (int32 dwChannelMask);

    int32 getWaveChannelMask() const noexcept;
 
    //==============================================================================
    static int getAmbisonicOrderForNumChannels (int numChannels, int maxOrderToCheck = 7);
 
    //==============================================================================
    bool operator== (const AudioChannelSet&) const noexcept;
    bool operator!= (const AudioChannelSet&) const noexcept;
    bool operator<  (const AudioChannelSet&) const noexcept;
 
private:
    //==============================================================================
    BigInteger channels;
 
    //==============================================================================
    explicit AudioChannelSet (uint32);
    explicit AudioChannelSet (const std::initializer_list<ChannelType>&);
 
};
 
} // namespace juce