버전
menu_open
알림: 고객님의 주요 출시 버전( 2019.1.11.7296 )에 해당하는 최신 설명서로 이동했습니다. 특정 버전의 설명서를 보시려면 Audiokinetic 런처에서 오프라인 설명서를 다운로드하고 Wwise Authoring의 Offline Documentation을 확인하세요.
Wwise SDK 2019.1.11
스피커 매트릭스 콜백을 이용한 고급 믹스 커스텀화

일부 게임은 라우팅 및 패닝과 관련해 매우 특정한 요구사항이 있는데, Wwise에서 준비된 기능이 없는 경우가 있습니다. 이를 위한 해결책으로 'speaker matrix callback'에 등록하는 방법이 있습니다. 보이스나 버스가 다른 버스로 믹싱되려고 할 때 이 콜백이 호출됩니다. 이 콜백에서 전역적 또는 특정 채널에 국한된 보이스나 버스 레벨을 변경할 수 있어, 믹스나 패닝을 수정할 수 있습니다.

다음 예제는 한 보이스에 대해 콜백을 등록하는 방법을 보여줍니다. 해당 보이스를 재생하는 이벤트를 발송할 때 이런 작업이 발생합니다.

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

VoiceCallback 콜백은, 출력 버스를 구별해내는 방법, 보이스가 출력 버스에 믹싱돼 들어갈 때 기본 볼륨을 변경하는 방법, 그리고 패닝 볼륨을 변경해 다양한 입사각을 시뮬레이션하는 방법을 보여줍니다. AkSpeakerVolumeMatrixCallbackInfo::pContext 는 보이스와 관련 있는 정보를 나타내며, AkSpeakerVolumeMatrixCallbackInfo::pMixerContext 는 믹싱되는 버스와 관련된 정보를 나타냅니다 (dry 출력 버스, 또는 보조 센드).

static void VoiceCallback(
AkCallbackType in_eType, // Callback 타입.
AkCallbackInfo* in_pCallbackInfo // 필요한 정보가 담긴 구조체. 콜백 타입에 따라 올바른 하위 타입으로 캐스팅할 수 있습니다.
)
{
// 이것이 스피커 볼륨 매트릭스 콜백이라는 것을 알고 있습니다. 올바른 하위 타입으로 캐스팅합니다.
AKASSERT( in_eType == AK_SpeakerVolumeMatrix );
AkSpeakerVolumeMatrixCallbackInfo* pVolumeCallbackInfo = (AkSpeakerVolumeMatrixCallbackInfo*)in_pCallbackInfo;
// PostEvent()로 전달되거나 반환된 ID에 해당하는 이벤트 및 게임 오브젝트, 재생 ID.
AkUniqueID eventID = pVolumeCallbackInfo->eventID;
AkGameObjectID objID = pVolumeCallbackInfo->gameObjID;
AkPlayingID playingID = pVolumeCallbackInfo->playingID;
AKASSERT( eventID == AK::EVENTS::PLAY_HELLO );
// 이 콜백은 보이스가 라우팅되는 각 버스에 대해 호출됩니다. 이 예제에서는 믹스를 "My_Dry_Bus" 버스로만 커스텀하고자 합니다.
if ( pVolumeCallbackInfo->pMixerContext->GetBusID() != AK::SoundEngine::GetIDFromString( "My_Dry_Bus" ) )
return;
// "base" 볼륨에 임의로 변경사항을 적용합니다 (예: 모든 채널에 적용).
// ---------------------------------------------------------------------------------
// "My_Dry_Bus"에 보이스 볼륨을 두 배로 증가시킵니다 (+6dB).
*pVolumeCallbackInfo->pfBaseVolume *= 2.f;
// "My_Dry_Bus"에 대해 보이스의 거리 감쇠(distance attenuation)의 실행을 취소합니다 (단일 위치일 경우).
*pVolumeCallbackInfo->pfEmitterListenerVolume = 1.f;
// "My_Dry_Bus"에 대해 보이스 패닝을 변경합니다. 해당 사운드가 3D 위치 지정을 사용할 경우를 가정해봅시다.
// ---------------------------------------------------------------------------------
AkUInt32 uNumPosition = pVolumeCallbackInfo->pContext->GetNum3DPositions();
// 하나의 3D 사운드에는 여러 개의 위치가 있을 수 있습니다 (AK::SoundEngine::SetMultiplePositions() 참고). 이번 예제에서는 첫 번째 위치만 고려합니다.
if ( uNumPosition > 0 )
{
// 리스너 위치를 쿼리합니다. 일반적으로, 보이스가 믹싱되는 버스는 리스너에 따라 좌우됩니다. 따라서 게임 오브젝트를 믹서에 연결하세요.
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);
// 이미터 게임 오브젝트 위치를 구합니다.
AkTransform posEmitter;
pVolumeCallbackInfo->pContext->GetVoiceInfo()->GetGameObjectPosition(0, posEmitter);
// 버스나 믹서의 믹싱을 이용해 새로운 패닝 볼륨을 계산하세요.
pVolumeCallbackInfo->pMixerContext->Compute3DPositioning(
posEmitter, // 이미터 트랜스폼.
posListener, // 리스너 트랜스폼.
pVolumeCallbackInfo->pContext->GetCenterPerc(), // 중앙 비율. 중앙이 있는 출력의 모노 입력에만 적용합니다.
pVolumeCallbackInfo->pContext->GetSpread(0), // 확산.
pVolumeCallbackInfo->pContext->GetFocus(0), // 포커스.
pVolumeCallbackInfo->inputConfig, // 입력의 채널 구성.
pVolumeCallbackInfo->inputConfig.uChannelMask, // 패닝에 선택된 채널의 마스크 (제외된 입력 채널은 해당 출력에 영향을 주지 않습니다).
pVolumeCallbackInfo->outputConfig, // 원하는 출력 구성.
pVolumeCallbackInfo->pVolumes // 반환된 볼륨 매트릭스. AK::SpeakerVolumes::Matrix::GetRequiredSize() 를 이용해 사전 할당되어야 합니다 ( AK::SpeakerVolumes::Matrix services 참고).
);
}
}
}

다음 예제는 버스 콜백을 등록하는 방법입니다. 여기서는 AkSpeakerVolumeMatrixCallbackInfo::pContext 가 ("My_Bus")로 등록한 버스와 관련된 정보를 나타내며, AkSpeakerVolumeMatrixCallbackInfo::pMixerContext 는 믹싱되는 버스, 상위 버스와 관련된 정보를 나타냅니다 (또는 시그널 체인에서 다음 믹싱 버스 관련 정보를 나타냅니다).

AK::SoundEngine::RegisterBusVolumeCallback( AK::SoundEngine::GetIDFromString( "My_Bus" ), BusCallback );
static void BusCallback(
AkSpeakerVolumeMatrixCallbackInfo* in_pCallbackInfo // 필요한 버스 정보가 들어있는 구조체.
)
{
// 버스로부터 호출됨: 재생 ID와 연결 불가능.
AKASSERT( in_pCallbackInfo->playingID == AK_INVALID_PLAYING_ID );
// 상위 버스로 믹싱되기 전에 해당 버스의 출력 지점에서 믹스다운 신호의 패닝 볼륨을 변경합니다.
// 믹싱 서비스를 이용하여 입력을 3-스테레오 구성으로 Transmix하고, 상위 버스의 다른 모든 채널에 끼치는 영향을 없앱니다.
// Transmix 게인을 얻기 위해 볼륨 매트릭스를 할당합니다 (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, // 입력의 채널 구성.
cfgThreeStereo, // 믹성 출력의 채널 구성.
in_pCallbackInfo->pContext->GetCenterPerc(),// Center%: Wwise가 계산한 center% 값을 사용.
mxTransmix );
// 가능하면 결과를 실제 믹싱 매트릭스로 복사하고 후방 채널과 LFE를 정리.
// 주의: 믹싱 버스에 중앙 채널이 있는지 알 수 없으므로 확인이 필요함.
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++ )
{
// 각각의 입력 채널에 대해 출력 볼륨 벡터를 구함.
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 );
// 앞 채널로 패닝 복사.
AkUInt32 uChanOut = 0;
while ( uChanOut < uNumOutputChannelsToCopy )
{
vMixOut[uChanOut] = vTransmixOut[uChanOut];
++uChanOut;
}
// 다른 채널 정리.
while ( uChanOut < in_pCallbackInfo->outputConfig.uNumChannels )
{
vMixOut[uChanOut] = 0;
++uChanOut;
}
}
}

다음 예제는 버스에 등록해 미터링 데이터를 쿼리하는 방법을 보여줍니다.

// 버스 미터링에 등록. 참고: 미터링에 등록하는 방법은 비용이 매우 높은 편이며, 특히 True Peak와 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 인터페이스.
AkChannelConfig in_channelConfig, // 버스의 채널 구성.
AkMeteringFlags in_eMeteringFlags // RegisterBusMeteringCallback() 에서 요청된 미터링 플래그. in_pMeteringInfo 로 해당하는 미터 값에만 접근할 수 있습니다. 다른 접근은 실패합니다.
)
{
// 콜백을 등록했기 때문에 최소한 True Peak와 K-Weighted Power 미터링이 활성화돼있어야 합니다.
AKASSERT( ( in_eMeteringFlags & AK_EnableBusMeter_TruePeak ) && ( in_eMeteringFlags & AK_EnableBusMeter_KPower ) );
// K-Weighted Power를 구해 작업을 수행합니다.
AkReal32 fPower = in_pMetering->GetKWeightedPower();
// True Peak를 구해 작업을 수행합니다.
// 채널당 하나의 값이 있습니다.
AK::SpeakerVolumes::ConstVectorPtr vTruePeak = in_pMetering->GetTruePeak();
for ( AkUInt32 uChannel = 0; uChannel < in_channelConfig.uNumChannels; uChannel++ )
{
AkReal32 fChannelPeak = vTruePeak[uChannel];
...
}
...
}
AkSpeakerVolumeMatrixCallbackInfo::pContext
AK::IAkMixerInputContext * pContext
Context of the current voice/bus about to be mixed into the output bus with specified base volume and...
Definition: AkCallback.h:170
AK::IAkMetering
Interface to retrieve metering information about a buffer.
Definition: AkCommonDefs.h:206
AkCallbackInfo::gameObjID
AkGameObjectID gameObjID
Game object ID
Definition: AkCallback.h:88
AK::IAkMixerInputContext::GetSpread
virtual AkReal32 GetSpread(AkUInt32 in_uIndex)=0
AkSpeakerVolumeMatrixCallbackInfo::pfBaseVolume
AkReal32 * pfBaseVolume
Base volume, common to all channels.
Definition: AkCallback.h:168
AkSpeakerVolumeMatrixCallbackInfo::outputConfig
AkChannelConfig outputConfig
Channel configuration of the output bus.
Definition: AkCallback.h:167
AkChannelConfig::uNumChannels
AkUInt32 uNumChannels
Number of channels.
Definition: AkSpeakerConfig.h:510
AkSpeakerVolumeMatrixCallbackInfo::inputConfig
AkChannelConfig inputConfig
Channel configuration of the voice/bus.
Definition: AkCallback.h:166
AK::IAkMetering::GetKWeightedPower
virtual AkReal32 GetKWeightedPower()=0
AkTransform::OrientationFront
const AkVector & OrientationFront() const
Get orientation front vector.
Definition: AkTypes.h:319
AkTransform::OrientationTop
const AkVector & OrientationTop() const
Get orientation top vector.
Definition: AkTypes.h:325
AkChannelConfig::uChannelMask
AkUInt32 uChannelMask
Channel mask (configuration).
Definition: AkSpeakerConfig.h:512
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
AkSpeakerVolumeMatrixCallbackInfo::pMixerContext
AK::IAkMixerPluginContext * pMixerContext
Output mixing bus context. Use it to access a few useful panning and mixing services,...
Definition: AkCallback.h:171
AK::IAkGameObjectPluginInfo::GetGameObjectPosition
virtual AKRESULT GetGameObjectPosition(AkUInt32 in_uIndex, AkSoundPosition &out_position) const =0
AK::SoundEngine::RegisterBusMeteringCallback
AKSOUNDENGINE_API AKRESULT RegisterBusMeteringCallback(AkUniqueID in_busID, AkBusMeteringCallbackFunc in_pfnCallback, AkMeteringFlags in_eMeteringFlags)
AkEventCallbackInfo::eventID
AkUniqueID eventID
Unique ID of Event, passed to PostEvent()
Definition: AkCallback.h:98
AK::IAkMixerInputContext::GetVoiceInfo
virtual IAkVoicePluginInfo * GetVoiceInfo()=0
AK::SpeakerVolumes::VectorPtr
AkReal32 * VectorPtr
Volume vector. Access each element with the standard bracket [] operator.
Definition: AkSpeakerVolumes.h:49
AkVector::Y
AkReal32 Y
Y Position
Definition: AkTypes.h:300
AK::IAkMetering::GetTruePeak
virtual AK::SpeakerVolumes::ConstVectorPtr GetTruePeak()=0
AK::IAkMixerInputContext::GetFocus
virtual AkReal32 GetFocus(AkUInt32 in_uIndex)=0
AkVector::X
AkReal32 X
X Position
Definition: AkTypes.h:299
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
AK::IAkMixerInputContext::GetNum3DPositions
virtual AkUInt32 GetNum3DPositions()=0
AkVector::Z
AkReal32 Z
Z Position
Definition: AkTypes.h:301
AkTransform::SetOrientation
void SetOrientation(const AkVector &in_orientationFront, const AkVector &in_orientationTop)
Set orientation. Orientation front and top should be orthogonal and normalized.
Definition: AkTypes.h:391
AkSpeakerVolumeMatrixCallbackInfo::pfEmitterListenerVolume
AkReal32 * pfEmitterListenerVolume
Emitter-listener pair-specific gain. When there are multiple emitter-listener pairs,...
Definition: AkCallback.h:169
AK::IAkMixerPluginContext::Compute3DPositioning
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
AK::IAkMixerPluginContext::GetBusID
virtual AkUniqueID GetBusID()=0
AK::IAkMixerPluginContext::ComputeSpeakerVolumesDirect
virtual AKRESULT ComputeSpeakerVolumesDirect(AkChannelConfig in_inputConfig, AkChannelConfig in_outputConfig, AkReal32 in_fCenterPerc, AK::SpeakerVolumes::MatrixPtr out_mxVolumes)=0
Compute a direct speaker assignment volume matrix with proper downmixing rules between two channel co...
AK::SoundEngine::GetIDFromString
AKSOUNDENGINE_API AkUInt32 GetIDFromString(const char *in_pszString)
AK::IAkPluginContextBase::GetGameObjectInfo
virtual IAkGameObjectPluginInfo * GetGameObjectInfo()=0
AkChannelConfig::SetStandard
AkForceInline void SetStandard(AkUInt32 in_uChannelMask)
Set channel config as a standard configuration specified with given channel mask.
Definition: AkSpeakerConfig.h:544
AK::SpeakerVolumes::MatrixPtr
AkReal32 * MatrixPtr
Volume matrix. Access each input channel vector with AK::SpeakerVolumes::Matrix::GetChannel().
Definition: AkSpeakerVolumes.h:50
AK::IAkMixerInputContext::GetCenterPerc
virtual AkReal32 GetCenterPerc()=0
AK::IAkGameObjectPluginInfo
Game object information available to plugins.
Definition: IAkPlugin.h:92
AkVector
3D vector.
Definition: AkTypes.h:282
AK::SoundEngine::PostEvent
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)
AkSpeakerVolumeMatrixCallbackInfo::pVolumes
AK::SpeakerVolumes::MatrixPtr pVolumes
Pointer to volume matrix describing the contribution of each source channel to destination channels....
Definition: AkCallback.h:165
AkTransform
Position and orientation of game objects.
Definition: AkTypes.h:306
AkEventCallbackInfo::playingID
AkPlayingID playingID
Playing ID of Event, returned by PostEvent()
Definition: AkCallback.h:97
AK::SpeakerVolumes::ConstVectorPtr
const AkReal32 * ConstVectorPtr
Constant volume vector. Access each element with the standard bracket [] operator.
Definition: AkSpeakerVolumes.h:51
AK::SoundEngine::RegisterBusVolumeCallback
AKSOUNDENGINE_API AKRESULT RegisterBusVolumeCallback(AkUniqueID in_busID, AkBusCallbackFunc in_pfnCallback)

이 페이지가 도움이 되었나요?

지원이 필요하신가요?

질문이 있으신가요? 문제를 겪고 계신가요? 더 많은 정보가 필요하신가요? 저희에게 문의해주시면 도와드리겠습니다!

지원 페이지를 방문해 주세요

작업하는 프로젝트에 대해 알려주세요. 언제든지 도와드릴 준비가 되어 있습니다.

프로젝트를 등록하세요. 아무런 조건이나 의무 사항 없이 빠른 시작을 도와드리겠습니다.

Wwise를 시작해 보세요