Version
menu_open

Advanced Mix Customization Using the Speaker Matrix Callback

Some games have very specific needs in terms of routing and panning, which may not be readily available in Wwise. One way to work around this limitation is to register to the "speaker matrix callback". This callback is called when a voice or a bus is about to be mixed into another bus. From this callback, you can change the global and channel specific level of the voice or bus, thus modifying the mix or panning.

The following example shows how you can register to this callback for a voice. This happens when you post the event that will play this voice.

AK::SoundEngine::PostEvent( AK::EVENTS::PLAY_HELLO, GAME_OBJECT_HUMAN, AK_SpeakerVolumeMatrix, VoiceCallback );

The callback VoiceCallback illustrates how you can identify the output bus, change the base volume of the voice as it gets mixed into the output bus, and change the panning volumes to simulate a different angle of incidence. AkSpeakerVolumeMatrixCallbackInfo::pContext exposes information relative to the voice, and AkSpeakerVolumeMatrixCallbackInfo::pMixerContext exposes information relative to the bus into which it is mixed (the dry output bus, or an auxiliary send).

static void VoiceCallback( 
    AkCallbackType in_eType,                            // Callback type.
    AkCallbackInfo* in_pCallbackInfo                    // Structure containing desired information. You can cast it to the proper sub-type, depending on the callback type.
    )
{
    // We know this is a speaker volume matrix callback. Cast to proper subtype.
    AKASSERT( in_eType == AK_SpeakerVolumeMatrix );
    AkSpeakerVolumeMatrixCallbackInfo* pVolumeCallbackInfo = (AkSpeakerVolumeMatrixCallbackInfo*)in_pCallbackInfo;

    // Event, game object and playing ID correspond to the IDs passed to / returned from PostEvent().
    AkUniqueID eventID = pVolumeCallbackInfo->eventID;
    AkGameObjectID objID = pVolumeCallbackInfo->gameObjID;
    AkPlayingID playingID = pVolumeCallbackInfo->playingID;
    
    AKASSERT( eventID == AK::EVENTS::PLAY_HELLO );
    
    // This callback gets called for each bus into which the voice is routed. In this example, we want to customize mix into the "My_Dry_Bus" bus only.
    if ( pVolumeCallbackInfo->pMixerContext->GetBusID() != AK::SoundEngine::GetIDFromString( "My_Dry_Bus" ) )
        return;

        
    // Apply arbitrary changes to "base" volumes (i.e. common to all channels).
    // ---------------------------------------------------------------------------------
    
    // Double the volume (+6dB) of the voice into "My_Dry_Bus".
    *pVolumeCallbackInfo->pfBaseVolume *= 2.f;
    
    // Undo distance attenuation of the voice into "My_Dry_Bus" (in the single position case).
    *pVolumeCallbackInfo->pfEmitterListenerVolume = 1.f;
    
    
    // Change panning of the voice into "My_Dry_Bus". Say the sound uses 3D positioning.
    // ---------------------------------------------------------------------------------
    AkUInt32 uNumPosition = pVolumeCallbackInfo->pContext->GetNum3DPositions();

    // A 3D sound may have multiple positions (see AK::SoundEngine::SetMultiplePositions()). In this example, consider first one only.
    if ( uNumPosition > 0 )
    {
        // Get angle of incidence using the input (voice) context.
        AkEmitterListenerPair ray;
        pVolumeCallbackInfo->pContext->Get3DPosition( 0, ray );

        // Use mixing services of the bus/mixer to compute new panning volumes, by shifting the azimuth by 90 degrees (PI/2) to the right (positive angle).
        pVolumeCallbackInfo->pMixerContext->Compute3DPositioning( 
            ray.Azimuth() + 1.57079f,                       // Azimuth: Shift azimuth angle.
            pVolumeCallbackInfo->pContext->GetSpread( 0 ),  // Spread: Use spread value computed by Wwise.
            pVolumeCallbackInfo->pContext->GetFocus( 0 ),   // Focus: Use focus value computed by Wwise.
            pVolumeCallbackInfo->inputConfig,               // Input (voice) channel config.
            pVolumeCallbackInfo->outputConfig,              // Output (bus) channel config.
            pVolumeCallbackInfo->pContext->GetCenterPerc(), // Center%: Use center% value computed by Wwise.
            pVolumeCallbackInfo->pVolumes );                // Pass in the mixing matrix; its values will be overriden by Compute3DPositioning(), thus changing the resulting panning.
    }
}

The following example shows how you can register to a bus callback. In this case, AkSpeakerVolumeMatrixCallbackInfo::pContext exposes information relative to the bus to which we registered ("My_Bus"), and AkSpeakerVolumeMatrixCallbackInfo::pMixerContext exposes information relative to the bus into which it is mixed, its parent bus (or the next mixing bus in the signal chain).

AK::SoundEngine::RegisterBusVolumeCallback( AK::SoundEngine::GetIDFromString( "My_Bus" ), BusCallback );

static void BusCallback( 
    AkSpeakerVolumeMatrixCallbackInfo* in_pCallbackInfo // Structure containing desired bus information. 
    )
{
    // Called from a bus: cannot be associated to a playing ID.
    AKASSERT( in_pCallbackInfo->playingID == AK_INVALID_PLAYING_ID );
    
    // Change panning volumes of the mixdown signal at the output of this bus before it gets mixed into its parent;
    // Using mixing services, transmix input into a 3-stereo configuration, and silence out contribution to all other channels of the parent bus.

    // Allocate a volume matrix to obtain transmix gains (input_config -> 3-stereo).
    AkChannelConfig cfgThreeStereo;
    cfgThreeStereo.SetStandard( AK_SPEAKER_SETUP_3STEREO );
    AkUInt32 uSize = AK::SpeakerVolumes::Matrix::GetRequiredSize( in_pCallbackInfo->inputConfig.uNumChannels, cfgThreeStereo.uNumChannels );
    AK::SpeakerVolumes::MatrixPtr mxTransmix = (AK::SpeakerVolumes::MatrixPtr)AkAlloca( uSize );

    in_pCallbackInfo->pMixerContext->ComputeSpeakerVolumesDirect(
        in_pCallbackInfo->inputConfig,  // Channel configuration of the input.
        cfgThreeStereo,                 // Channel configuration of the mixer output.
        in_pCallbackInfo->pContext->GetCenterPerc(),// Center%: Use center% value computed by Wwise.
        mxTransmix );

    // Copy result into real mixing matrix and clear out the back channels and LFE (if applicable).
    // Warning: we cannot assume that the mixing bus has a center channel, so we need to verify it.
    AkChannelConfig cfgThreeStereoANDBus;
    cfgThreeStereoANDBus.SetStandard( AK_SPEAKER_SETUP_3STEREO & in_pCallbackInfo->outputConfig.uChannelMask );
    AkUInt32 uNumOutputChannelsToCopy = cfgThreeStereoANDBus.uNumChannels;

    for ( AkUInt32 uChanIn = 0; uChanIn < in_pCallbackInfo->inputConfig.uNumChannels; uChanIn++ )
    {
        // Get output volume vector for each input channel.
        AK::SpeakerVolumes::VectorPtr vTransmixOut = AK::SpeakerVolumes::Matrix::GetChannel( mxTransmix, uChanIn, cfgThreeStereo.uNumChannels );
        AK::SpeakerVolumes::VectorPtr vMixOut = AK::SpeakerVolumes::Matrix::GetChannel( in_pCallbackInfo->pVolumes, uChanIn, in_pCallbackInfo->outputConfig.uNumChannels );

        // Copy panning to front channels.
        AkUInt32 uChanOut = 0;
        while ( uChanOut < uNumOutputChannelsToCopy )
        {
            vMixOut[uChanOut] = vTransmixOut[uChanOut];
            ++uChanOut;
        }

        // Clear out other channels.
        while ( uChanOut < in_pCallbackInfo->outputConfig.uNumChannels )
        {
            vMixOut[uChanOut] = 0;
            ++uChanOut;
        }
    }
}

The next example shows how you can register to a bus to query its metering data.

// Register to bus metering. Note: there is a significant cost to registering to metering, especially True Peak and K-Weighted Power.
AK::SoundEngine::RegisterBusMeteringCallback( AK::SoundEngine::GetIDFromString( "My_Bus" ), MeterCallback, (AkMeteringFlags)( AK_EnableBusMeter_TruePeak | AK_EnableBusMeter_KPower ) );

static void MeterCallback(
    AK::IAkMetering * in_pMetering,                     // AK::IAkMetering interface for retrieving metering information.
    AkChannelConfig in_channelConfig,                   // Channel configuration of the bus.
    AkMeteringFlags in_eMeteringFlags                   // Metering flags that were asked for in RegisterBusMeteringCallback(). You may only access corresponding meter values from in_pMeteringInfo. Others will fail.
    )
{
    // At least true peak and K-weighted power metering must be enabled since we registered for this callback.
    AKASSERT( ( in_eMeteringFlags & AK_EnableBusMeter_TruePeak ) && ( in_eMeteringFlags & AK_EnableBusMeter_KPower ) );
    
    // Get K-weighted power and do something with it.
    AkReal32 fPower = in_pMetering->GetKWeightedPower();

    // Get true peak and do something with it.
    // There is one value per channel.
    AK::SpeakerVolumes::ConstVectorPtr vTruePeak = in_pMetering->GetTruePeak();
    for ( AkUInt32 uChannel = 0; uChannel < in_channelConfig.uNumChannels; uChannel++ )
    {
        AkReal32 fChannelPeak = vTruePeak[uChannel];

        ...
    }

    ...
}

Cette page a-t-elle été utile ?

Besoin d'aide ?

Des questions ? Des problèmes ? Besoin de plus d'informations ? Contactez-nous, nous pouvons vous aider !

Visitez notre page d'Aide

Décrivez-nous de votre projet. Nous sommes là pour vous aider.

Enregistrez votre projet et nous vous aiderons à démarrer sans aucune obligation !

Partir du bon pied avec Wwise