_ak_speaker_volumes_8h

Wwise SDK 2024.1.4

 /*******************************************************************************
 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
 released in source code form as part of the SDK installer package.
  
 Commercial License Usage
  
 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
 may use this file in accordance with the end user license agreement provided 
 with the software or, alternatively, in accordance with the terms contained in a
 written agreement between you and Audiokinetic Inc.
  
 Apache License Usage
  
 Alternatively, this file may be used under the Apache License, Version 2.0 (the 
 "Apache License"); you may not use this file except in compliance with the 
 Apache License. You may obtain a copy of the Apache License at 
 http://www.apache.org/licenses/LICENSE-2.0.
  
 Unless required by applicable law or agreed to in writing, software distributed
 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
 the specific language governing permissions and limitations under the License.
  
   Copyright (c) 2025 Audiokinetic Inc.
 *******************************************************************************/
  
 // AkSpeakerVolumes.h
  
 /// \file 
 /// Multi-channel volume definitions and services.
 /// Always associated with an AkChannelConfig. In the case of standard configurations, the volume items ordering
 /// match the bit ordering in the channel mask, except for the LFE which is skipped and placed at the end of the
 /// volume array.
 /// Refer to \ref goingfurther_speakermatrixcallback for an example of how to manipulate speaker volume vectors/matrices.
  
 #ifndef _AK_SPEAKER_VOLUMES_H_
 #define _AK_SPEAKER_VOLUMES_H_
  
 #include <AK/SoundEngine/Common/AkTypes.h>
 #include <AK/SoundEngine/Platforms/Generic/AkSpeakerVolumes.h>
 #include <AK/Tools/Common/AkAssert.h>
 #include <AK/Tools/Common/AkPlatformFuncs.h>
  
 namespace AK
 {
 /// Multi-channel volume definitions and services.
 namespace SpeakerVolumes
 {
     typedef AkReal32 * VectorPtr;               ///< Volume vector. Access each element with the standard bracket [] operator.
     typedef AkReal32 * MatrixPtr;               ///< Volume matrix. Access each input channel vector with AK::SpeakerVolumes::Matrix::GetChannel().
     typedef const AkReal32 * ConstVectorPtr;    ///< Constant volume vector. Access each element with the standard bracket [] operator.
     typedef const AkReal32 * ConstMatrixPtr;    ///< Constant volume matrix. Access each input channel vector with AK::SpeakerVolumes::Matrix::GetChannel().
  
     /// Volume vector services.
     namespace Vector
     {
         /// Copy volumes.
         AkForceInline void Copy( VectorPtr in_pVolumesDst, ConstVectorPtr in_pVolumesSrc, AkUInt32 in_uNumChannels )
         {
             AKASSERT( ( in_pVolumesDst && in_pVolumesSrc ) || in_uNumChannels == 0 );
             if ( in_uNumChannels )
                 memcpy( in_pVolumesDst, in_pVolumesSrc, in_uNumChannels * sizeof( AkReal32 ) );
         }
  
         /// Copy volumes with gain.
         AkForceInline void Copy( VectorPtr in_pVolumesDst, ConstVectorPtr in_pVolumesSrc, AkUInt32 in_uNumChannels, AkReal32 in_fGain )
         {
             AKASSERT( ( in_pVolumesDst && in_pVolumesSrc ) || in_uNumChannels == 0 );
             for ( AkUInt32 uChan = 0; uChan < in_uNumChannels; uChan++ )
             {
                 in_pVolumesDst[uChan] = in_pVolumesSrc[uChan] * in_fGain;
             }
         }
  
         /// Clear volumes.
         AkForceInline void Zero( VectorPtr in_pVolumes, AkUInt32 in_uNumChannels )
         {
             AKASSERT( in_pVolumes || in_uNumChannels == 0 );
             if ( in_uNumChannels )
                 memset( in_pVolumes, 0, in_uNumChannels * sizeof( AkReal32 ) );
         }
  
         /// Accumulate two volume vectors.
         AkForceInline void Add( VectorPtr in_pVolumesDst, ConstVectorPtr in_pVolumesSrc, AkUInt32 in_uNumChannels )
         {
             AKASSERT( ( in_pVolumesDst && in_pVolumesSrc ) || in_uNumChannels == 0 );
             for ( AkUInt32 uChan = 0; uChan < in_uNumChannels; uChan++ )
             {
                 in_pVolumesDst[uChan] += in_pVolumesSrc[uChan];
             }
         }
  
         /// Compute the sum of all components of a volume vector.
         AkForceInline AkReal32 L1Norm(ConstVectorPtr io_pVolumes, AkUInt32 in_uNumChannels)
         {
             AkReal32 total = 0;
             AKASSERT((io_pVolumes) || in_uNumChannels == 0);
             for (AkUInt32 uChan = 0; uChan < in_uNumChannels; uChan++)
             {
                 total += io_pVolumes[uChan];
             }
  
             return total;
         }
  
         /// Multiply volume vector with a scalar.
         AkForceInline void Mul( VectorPtr in_pVolumesDst, const AkReal32 in_fVol, AkUInt32 in_uNumChannels )
         {
             AKASSERT( in_pVolumesDst || in_uNumChannels == 0 );
             for ( AkUInt32 uChan = 0; uChan < in_uNumChannels; uChan++ )
             {
                 in_pVolumesDst[uChan] *= in_fVol;
             }
         }
  
         /// Multiply two volume vectors.
         AkForceInline void Mul( VectorPtr in_pVolumesDst, ConstVectorPtr in_pVolumesSrc, AkUInt32 in_uNumChannels )
         {
             AKASSERT( ( in_pVolumesDst && in_pVolumesSrc ) || in_uNumChannels == 0 );
             for ( AkUInt32 uChan = 0; uChan < in_uNumChannels; uChan++ )
             {
                 in_pVolumesDst[uChan] *= in_pVolumesSrc[uChan];
             }
         }
  
         /// Get max for all elements of two volume vectors, independently.
         AkForceInline void Max( AkReal32 * in_pVolumesDst, const AkReal32 * in_pVolumesSrc, AkUInt32 in_uNumChannels )
         {
             AKASSERT( ( in_pVolumesDst && in_pVolumesSrc ) || in_uNumChannels == 0 );
             for ( AkUInt32 uChan = 0; uChan < in_uNumChannels; uChan++ )
             {
                 in_pVolumesDst[uChan] = AkMax( in_pVolumesDst[uChan], in_pVolumesSrc[uChan] );
             }
         }
         
         /// Get min for all elements of two volume vectors, independently.
         AkForceInline void Min( AkReal32 * in_pVolumesDst, const AkReal32 * in_pVolumesSrc, AkUInt32 in_uNumChannels )
         {
             AKASSERT( ( in_pVolumesDst && in_pVolumesSrc ) || in_uNumChannels == 0 );
             for ( AkUInt32 uChan = 0; uChan < in_uNumChannels; uChan++ )
             {
                 in_pVolumesDst[uChan] = AkMin( in_pVolumesDst[uChan], in_pVolumesSrc[uChan] );
             }
         }
     }
  
     /// Volume matrix (multi-in/multi-out channel configurations) services.
     namespace Matrix
     {
         /// Compute size (in bytes) required for given channel configurations.
         AkForceInline AkUInt32 GetRequiredSize( AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut ) 
         {
             return in_uNumChannelsIn * Vector::GetRequiredSize( in_uNumChannelsOut );
         }
  
         /// Compute size (in number of elements) required for given channel configurations.
         AkForceInline AkUInt32 GetNumElements( AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut ) 
         {
             return in_uNumChannelsIn * Vector::GetNumElements( in_uNumChannelsOut );
         }
         
         /// Get pointer to volume distribution for input channel in_uIdxChannelIn.
         AkForceInline VectorPtr GetChannel( MatrixPtr in_pVolumeMx, AkUInt32 in_uIdxChannelIn, AkUInt32 in_uNumChannelsOut ) 
         {
             AKASSERT( in_pVolumeMx );
             return in_pVolumeMx + in_uIdxChannelIn * Vector::GetNumElements( in_uNumChannelsOut );
         }
  
         /// Get pointer to volume distribution for input channel in_uIdxChannelIn.
         AkForceInline ConstVectorPtr GetChannel( ConstMatrixPtr in_pVolumeMx, AkUInt32 in_uIdxChannelIn, AkUInt32 in_uNumChannelsOut ) 
         {
             AKASSERT( in_pVolumeMx );
             return in_pVolumeMx + in_uIdxChannelIn * Vector::GetNumElements( in_uNumChannelsOut );
         }
  
         /// Copy matrix.
         AkForceInline void Copy( MatrixPtr in_pVolumesDst, ConstMatrixPtr in_pVolumesSrc, AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut )
         {
             AkUInt32 uNumElements = Matrix::GetNumElements( in_uNumChannelsIn, in_uNumChannelsOut );
             AKASSERT( ( in_pVolumesDst && in_pVolumesSrc ) || uNumElements == 0 );
             if ( uNumElements )
                 memcpy( in_pVolumesDst, in_pVolumesSrc, uNumElements * sizeof( AkReal32 ) );
         }
  
         /// Copy matrix with gain.
         AkForceInline void Copy( MatrixPtr in_pVolumesDst, ConstMatrixPtr in_pVolumesSrc, AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut, AkReal32 in_fGain )
         {
             AkUInt32 uNumElements = Matrix::GetNumElements( in_uNumChannelsIn, in_uNumChannelsOut );
             AKASSERT( ( in_pVolumesDst && in_pVolumesSrc ) || uNumElements == 0 );
             for ( AkUInt32 uChan = 0; uChan < uNumElements; uChan++ )
             {
                 in_pVolumesDst[uChan] = in_pVolumesSrc[uChan] * in_fGain;
             }
         }
  
         /// Clear matrix.
         AkForceInline void Zero( MatrixPtr in_pVolumes, AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut )
         {
             AkUInt32 uNumElements = Matrix::GetNumElements( in_uNumChannelsIn, in_uNumChannelsOut );
             AKASSERT( in_pVolumes || uNumElements == 0 );
             if ( uNumElements )
                 memset( in_pVolumes, 0, uNumElements * sizeof( AkReal32 ) );
         }
  
         /// Multiply a matrix with a scalar.
         AkForceInline void Mul( MatrixPtr in_pVolumesDst, const AkReal32 in_fVol, AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut )
         {
             AkUInt32 uNumElements = Matrix::GetNumElements( in_uNumChannelsIn, in_uNumChannelsOut );
             AKASSERT( in_pVolumesDst || uNumElements == 0 );
             for ( AkUInt32 uChan = 0; uChan < uNumElements; uChan++ )
             {
                 in_pVolumesDst[uChan] *= in_fVol;
             }
         }
  
         /// Add all elements of two volume matrices, independently.
         AkForceInline void Add(MatrixPtr in_pVolumesDst, ConstMatrixPtr in_pVolumesSrc, AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut)
         {
             AkUInt32 uNumElements = Matrix::GetNumElements(in_uNumChannelsIn, in_uNumChannelsOut);
             AKASSERT((in_pVolumesDst && in_pVolumesSrc) || uNumElements == 0);
             for (AkUInt32 uChan = 0; uChan < uNumElements; uChan++)
             {
                 in_pVolumesDst[uChan] += in_pVolumesSrc[uChan];
             }
         }
  
         /// Pointwise Multiply-Add of all elements of two volume matrices.
         AkForceInline void MAdd(MatrixPtr in_pVolumesDst, ConstMatrixPtr in_pVolumesSrc, AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut, AkReal32 in_fGain)
         {
             AkUInt32 uNumElements = Matrix::GetNumElements(in_uNumChannelsIn, in_uNumChannelsOut);
             AKASSERT((in_pVolumesDst && in_pVolumesSrc) || uNumElements == 0);
             for (AkUInt32 uChan = 0; uChan < uNumElements; uChan++)
             {
                 in_pVolumesDst[uChan] += in_pVolumesSrc[uChan] * in_fGain;
             }
         }
         
         /// Get absolute max for all elements of two volume matrices, independently.
         AkForceInline void AbsMax(MatrixPtr in_pVolumesDst, ConstMatrixPtr in_pVolumesSrc, AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut)
         {
             AkUInt32 uNumElements = Matrix::GetNumElements( in_uNumChannelsIn, in_uNumChannelsOut );
             AKASSERT( ( in_pVolumesDst && in_pVolumesSrc ) || uNumElements == 0 );
             for ( AkUInt32 uChan = 0; uChan < uNumElements; uChan++ )
             {
                 in_pVolumesDst[uChan] = ((in_pVolumesDst[uChan] * in_pVolumesDst[uChan]) > (in_pVolumesSrc[uChan] * in_pVolumesSrc[uChan])) ? in_pVolumesDst[uChan] : in_pVolumesSrc[uChan];
             }
         }
  
         /// Get max for all elements of two volume matrices, independently.
         AkForceInline void Max(MatrixPtr in_pVolumesDst, ConstMatrixPtr in_pVolumesSrc, AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut)
         {
             AkUInt32 uNumElements = Matrix::GetNumElements(in_uNumChannelsIn, in_uNumChannelsOut);
             AKASSERT((in_pVolumesDst && in_pVolumesSrc) || uNumElements == 0);
             for (AkUInt32 uChan = 0; uChan < uNumElements; uChan++)
             {
                 in_pVolumesDst[uChan] = (in_pVolumesDst[uChan] > in_pVolumesSrc[uChan]) ? in_pVolumesDst[uChan] : in_pVolumesSrc[uChan];
             }
         }
     }
 }
 }
  
 #endif  //_AK_SPEAKER_VOLUMES_H_

AkMin

#define AkMin(x1, x2)

Definition: AkPlatformFuncs.h:90

AK::SpeakerVolumes::Vector::Copy

AkForceInline void Copy(VectorPtr in_pVolumesDst, ConstVectorPtr in_pVolumesSrc, AkUInt32 in_uNumChannels)

Copy volumes.

Definition: AkSpeakerVolumes.h:58

Definition of data structures for AkAudioObject.

Definition: AkWwiseSDKVersion.cs:31

AkMax

#define AkMax(x1, x2)

Definition: AkPlatformFuncs.h:89

AK::SpeakerVolumes::Vector::L1Norm

AkForceInline AkReal32 L1Norm(ConstVectorPtr io_pVolumes, AkUInt32 in_uNumChannels)

Compute the sum of all components of a volume vector.

Definition: AkSpeakerVolumes.h:94

AK::SpeakerVolumes::Vector::Max

AkForceInline void Max(AkReal32 *in_pVolumesDst, const AkReal32 *in_pVolumesSrc, AkUInt32 in_uNumChannels)

Get max for all elements of two volume vectors, independently.

Definition: AkSpeakerVolumes.h:127

AK::SpeakerVolumes::Matrix::GetRequiredSize

AkForceInline AkUInt32 GetRequiredSize(AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut)

Compute size (in bytes) required for given channel configurations.

Definition: AkSpeakerVolumes.h:151

AK::SpeakerVolumes::Matrix::Zero

AkForceInline void Zero(MatrixPtr in_pVolumes, AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut)

Clear matrix.

Definition: AkSpeakerVolumes.h:197

AK::SpeakerVolumes::Matrix::GetNumElements

AkForceInline AkUInt32 GetNumElements(AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut)

Compute size (in number of elements) required for given channel configurations.

Definition: AkSpeakerVolumes.h:157

AkReal32

float AkReal32

32-bit floating point

Definition: AkNumeralTypes.h:46

AK::SpeakerVolumes::Matrix::AbsMax

AkForceInline void AbsMax(MatrixPtr in_pVolumesDst, ConstMatrixPtr in_pVolumesSrc, AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut)

Get absolute max for all elements of two volume matrices, independently.

Definition: AkSpeakerVolumes.h:239

AK::SpeakerVolumes::VectorPtr

AkReal32 * VectorPtr

Volume vector. Access each element with the standard bracket [] operator.

Definition: AkSpeakerVolumes.h:49

AK::SpeakerVolumes::Matrix::GetChannel

AkForceInline VectorPtr GetChannel(MatrixPtr in_pVolumeMx, AkUInt32 in_uIdxChannelIn, AkUInt32 in_uNumChannelsOut)

Get pointer to volume distribution for input channel in_uIdxChannelIn.

Definition: AkSpeakerVolumes.h:163

AKASSERT

#define AKASSERT(Condition)

Definition: AkAssert.h:67

AK::SpeakerVolumes::Matrix::Add

AkForceInline void Add(MatrixPtr in_pVolumesDst, ConstMatrixPtr in_pVolumesSrc, AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut)

Add all elements of two volume matrices, independently.

Definition: AkSpeakerVolumes.h:217

AK::SpeakerVolumes::ConstMatrixPtr

const AkReal32 * ConstMatrixPtr

Constant volume matrix. Access each input channel vector with AK::SpeakerVolumes::Matrix::GetChannel(...

Definition: AkSpeakerVolumes.h:52

AK::SpeakerVolumes::Vector::Zero

AkForceInline void Zero(VectorPtr in_pVolumes, AkUInt32 in_uNumChannels)

Clear volumes.

Definition: AkSpeakerVolumes.h:76

AK::SpeakerVolumes::Matrix::MAdd

AkForceInline void MAdd(MatrixPtr in_pVolumesDst, ConstMatrixPtr in_pVolumesSrc, AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut, AkReal32 in_fGain)

Pointwise Multiply-Add of all elements of two volume matrices.

Definition: AkSpeakerVolumes.h:228

AkPlatformFuncs.h

AK::SpeakerVolumes::Vector::Add

AkForceInline void Add(VectorPtr in_pVolumesDst, ConstVectorPtr in_pVolumesSrc, AkUInt32 in_uNumChannels)

Accumulate two volume vectors.

Definition: AkSpeakerVolumes.h:84

AK::SpeakerVolumes::MatrixPtr

AkReal32 * MatrixPtr

Volume matrix. Access each input channel vector with AK::SpeakerVolumes::Matrix::GetChannel().

Definition: AkSpeakerVolumes.h:50

AkTypes.h