バージョン
menu_open
Wwise SDK 2023.1.2
Speaker Matrix Callbackを使用した高度なミックスカスタマイズ

ゲームの中には、Wwiseですぐに利用できない非常に特定のルーティングやパニングがあるものがあります。この限界を回避する一つの方法は、"speaker matrix callback" (スピーカー マトリックス コールバック) への登録です。このコールバックは、ボイスやバスが他のバスにミックスされる際に呼び出します。このコールバックから、ボイスやバスのグローバルならびにチャンネルに特化したレベルを変更できるので、ミックスやパニングの修正ができます。

以下の例では、ボイスのコールバックを登録する方法を示しています。これはこのボイスを再生するイベントをポストした際に発生します。

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

VoiceCallback コールバックは、そのように出力バスの特定、ボイスを出力バスにミックスする際のベースボリュームの変更、そして異なる発生角度をシミュレートするためのパニングボリュームの変更ができるかを示しています。AkSpeakerVolumeMatrixCallbackInfo::pContext は、ボイスに関連する情報を、そして AkSpeakerVolumeMatrixCallbackInfo::pMixerContext はそのボイスがミックスされるバスに関連する情報を示します (ドライ出力バスまたはAUXセンド)。

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.
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()). この例では、最初のみを考慮します。
if ( uNumPosition > 0 )
{
// Query the listener position. 通常、ボイスをミックスする先のバスは、リスナーに紐づいています。このため、ゲームオブジェクトをミキサーに関連づけてください。
AkTransform posListener;
AK::IAkGameObjectPluginInfo * pBusObject = pVolumeCallbackInfo->pMixerContext->GetGameObjectInfo();
if (pBusObject)
{
pBusObject->GetGameObjectPosition(0, posListener);
// リスナーを上下逆にして、遊んでみます。
AkVector listenerTop = posListener.OrientationTop();
listenerTop.X = -listenerTop.X;
listenerTop.Y = -listenerTop.Y;
listenerTop.Z = -listenerTop.Z;
posListener.SetOrientation(posListener.OrientationFront(), listenerTop);
// Get the emitter game object position.
AkTransform posEmitter;
pVolumeCallbackInfo->pContext->GetVoiceInfo()->GetGameObjectPosition(0, posEmitter);
// Use mixing services of the bus/mixer to compute new panning volumes.
pVolumeCallbackInfo->pMixerContext->Compute3DPositioning(
posEmitter, // Emitter transform.
posListener, // Listener transform.
pVolumeCallbackInfo->pContext->GetCenterPerc(), // Center percentage. モノ入力から、センターのある出力に入力した場合に限定して、適用できます。
pVolumeCallbackInfo->pContext->GetSpread(0), // Spread.
pVolumeCallbackInfo->pContext->GetFocus(0), // Focus.
pVolumeCallbackInfo->inputConfig, // Channel configuration of the input.
pVolumeCallbackInfo->inputConfig.uChannelMask, // Mask of input channels selected for panning (excluded input channels don't contribute to the output).
pVolumeCallbackInfo->outputConfig, // Desired output configuration.
pVolumeCallbackInfo->pVolumes // Returned volumes matrix. AK::SpeakerVolumes::Matrix::GetRequiredSize()を使って、事前にアロケーションします(AK::SpeakerVolumes::Matrixサービスを参照)
);
}
}
}

次の例は、バスコールバックにどの様に登録するかを示しています。この場合では、AkSpeakerVolumeMatrixCallbackInfo::pContext が登録をしたバス (「My_Bus」) に関連する情報を、AkSpeakerVolumeMatrixCallbackInfo::pMixerContext が、ミックスされたその親バス (またはシグナルチェーンの次のミキシングバス) に関連する情報を示します。

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;
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 );
// 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;
}
}
}

次の例は、そのメータリングデータを問い合わせるための、バスへの登録方法を示しています。

// Register to bus metering. Note: there is a significant cost to registering to metering, especially True Peak and K-Weighted Power.
static void MeterCallback(
AK::AkMetering * in_pMetering, // AK::AkMetering struct containing 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];
...
}
...
}
AkGameObjectID gameObjID
Game object ID
Definition: AkCallback.h:87
AkReal32 * pfBaseVolume
Base volume, common to all channels.
Definition: AkCallback.h:168
@ AK_EnableBusMeter_KPower
Enable computation of K-weighted power metering (used as a basis for computing loudness,...
Definition: AkTypes.h:1241
AkChannelConfig outputConfig
Channel configuration of the output bus.
Definition: AkCallback.h:167
AKSOUNDENGINE_API AKRESULT RegisterBusVolumeCallback(AkUniqueID in_busID, AkBusCallbackFunc in_pfnCallback, void *in_pCookie=NULL)
AkUInt32 uNumChannels
Number of channels.
AkChannelConfig inputConfig
Channel configuration of the voice/bus.
Definition: AkCallback.h:166
AkUInt64 AkGameObjectID
Game object ID
Definition: AkTypes.h:142
const AkVector & OrientationFront() const
Get orientation front vector.
Definition: AkTypes.h:626
const AkVector & OrientationTop() const
Get orientation top vector.
Definition: AkTypes.h:632
AkUInt32 uChannelMask
Channel mask (configuration).
AkMeteringFlags
Metering flags. Used for specifying bus metering, through AK::SoundEngine::RegisterBusVolumeCallback(...
Definition: AkTypes.h:1235
AkForceInline AkUInt32 GetRequiredSize(AkUInt32 in_uNumChannelsIn, AkUInt32 in_uNumChannelsOut)
Compute size (in bytes) required for given channel configurations.
AK::IAkMixerPluginContext * pMixerContext
Output mixing bus context. Use it to access a few useful panning and mixing services,...
Definition: AkCallback.h:170
AkCallbackType
Type of callback. Used as a bitfield in methods AK::SoundEngine::PostEvent() and AK::SoundEngine::Dyn...
Definition: AkCallback.h:48
float AkReal32
32-bit floating point
virtual AKRESULT GetGameObjectPosition(AkUInt32 in_uIndex, AkSoundPosition &out_position) const =0
AkUniqueID eventID
Unique ID of Event, passed to PostEvent()
Definition: AkCallback.h:97
AkReal32 * VectorPtr
Volume vector. Access each element with the standard bracket [] operator.
AkReal32 Y
Y Position
Definition: AkTypes.h:487
AkUInt32 AkUniqueID
Unique 32-bit ID
Definition: AkTypes.h:134
AkReal32 X
X Position
Definition: AkTypes.h:486
AkForceInline VectorPtr GetChannel(MatrixPtr in_pVolumeMx, AkUInt32 in_uIdxChannelIn, AkUInt32 in_uNumChannelsOut)
Get pointer to volume distribution for input channel in_uIdxChannelIn.
@ AK_EnableBusMeter_TruePeak
Enable computation of true peak metering (most CPU and memory intensive).
Definition: AkTypes.h:1238
#define AK_SPEAKER_SETUP_3STEREO
3.0 setup channel mask
#define AKASSERT(Condition)
Definition: AkAssert.h:67
#define AkAlloca(_size_)
Stack allocations.
AkReal32 Z
Z Position
Definition: AkTypes.h:488
void SetOrientation(const AkVector &in_orientationFront, const AkVector &in_orientationTop)
Set orientation. Orientation front and top should be orthogonal and normalized.
Definition: AkTypes.h:698
AKSOUNDENGINE_API AKRESULT RegisterBusMeteringCallback(AkUniqueID in_busID, AkBusMeteringCallbackFunc in_pfnCallback, AkMeteringFlags in_eMeteringFlags, void *in_pCookie=NULL)
AkReal32 * pfEmitterListenerVolume
Emitter-listener pair-specific gain. When there are multiple emitter-listener pairs,...
Definition: AkCallback.h:169
virtual AKRESULT Compute3DPositioning(AkReal32 in_fAngle, AkReal32 in_fElevation, AkReal32 in_fSpread, AkReal32 in_fFocus, AkChannelConfig in_inputConfig, AkChannelMask in_uInputChanSel, AkChannelConfig in_outputConfig, AkReal32 in_fCenterPerc, AK::SpeakerVolumes::MatrixPtr out_mxVolumes)=0
Struct containing metering information about a buffer. Depending on when this struct is generated,...
Definition: AkCommonDefs.h:204
static const AkPlayingID AK_INVALID_PLAYING_ID
Invalid playing ID
Definition: AkTypes.h:179
virtual AKRESULT ComputeSpeakerVolumesDirect(AkChannelConfig in_inputConfig, AkChannelConfig in_outputConfig, AkReal32 in_fCenterPerc, AK::SpeakerVolumes::MatrixPtr out_mxVolumes)=0
AKSOUNDENGINE_API AkUInt32 GetIDFromString(const char *in_pszString)
virtual IAkGameObjectPluginInfo * GetGameObjectInfo()=0
AkForceInline void SetStandard(AkUInt32 in_uChannelMask)
Set channel config as a standard configuration specified with given channel mask.
AkReal32 * MatrixPtr
Volume matrix. Access each input channel vector with AK::SpeakerVolumes::Matrix::GetChannel().
uint32_t AkUInt32
Unsigned 32-bit integer
Game object information available to plugins.
Definition: IAkPlugin.h:102
3D vector for some operations in 3D space. Typically intended only for localized calculations due to ...
Definition: AkTypes.h:444
AKSOUNDENGINE_API AkPlayingID PostEvent(AkUniqueID in_eventID, AkGameObjectID in_gameObjectID, AkUInt32 in_uFlags=0, AkCallbackFunc in_pfnCallback=NULL, void *in_pCookie=NULL, AkUInt32 in_cExternals=0, AkExternalSourceInfo *in_pExternalSources=NULL, AkPlayingID in_PlayingID=AK_INVALID_PLAYING_ID)
@ AK_SpeakerVolumeMatrix
Callback triggered at each frame, letting the client modify the speaker volume matrix....
Definition: AkCallback.h:54
AK::SpeakerVolumes::MatrixPtr pVolumes
Pointer to volume matrix describing the contribution of each source channel to destination channels....
Definition: AkCallback.h:165
Position and orientation of objects in a "local" space
Definition: AkTypes.h:613
AkUInt32 AkPlayingID
Playing ID
Definition: AkTypes.h:137
AkPlayingID playingID
Playing ID of Event, returned by PostEvent()
Definition: AkCallback.h:96
const AkReal32 * ConstVectorPtr
Constant volume vector. Access each element with the standard bracket [] operator.

このページはお役に立ちましたか?

サポートは必要ですか?

ご質問や問題、ご不明点はございますか?お気軽にお問い合わせください。

サポートページをご確認ください

あなたのプロジェクトについて教えてください。ご不明な点はありませんか。

プロジェクトを登録していただくことで、ご利用開始のサポートをいたします。

Wwiseからはじめよう