Wwise SDK 2023.1.3

오디오 장치 플러그인 인터페이스 구현

오디오 장치 플러그인은 오디오 처리 과정에서 가장 엔드포인트라고 할 수 있습니다. 일반적인 오디오 장치는 OS 사운드 시스템이겠지만, 추가적인 하드웨어나 드라이버를 통해 더 다양한 출력을 사용할 수도 있습니다. 싱크 플러그인의 역할은, 최종 믹스된 오디오 샘플을 받아 장치가 이해할 수 있는 형태로 전송하는 일입니다.

사운드 엔진 컴포넌트

사운드 엔진 단에서 오디오 장치 플러그인을 작성할 때 AK::IAkSinkPlugin interface 를 구현하는 과정이 포함됩니다. 여기서는 이 인터페이스에 국한된 함수들만 다루도록 하겠습니다. 다른 플러그인 타입에서도 사용되는 인터페이스 컴포넌트와 관련한 더 많은 정보는 사운드 엔진 플러그인 만들기 를 참고하세요 ( AK::IAkPlugin interface ). 또한 예제 코드의 AkSink 플러그인도 제공하고 있으니 참고해보세요 ( 예제 ).

오디오 장치는 항상 사용하는 플러그인(Audio Device ShareSet)과 특정 장치 ID를 통해 지정됩니다. 이 장치 ID는 Wwise 사운드 엔진과는 아무 관련이 없으며, 다만 플러그인을 구현하는 사람이 같은 타입이 여럿 존재하는 장치들을 쉽게 구분할 수 있도록 하기 위한 목적입니다. 장치 ID는 AK::SoundEngine::Init 과 AK::SoundEngine::AddOutput 에서 사용되는 AkOutputSettings::idDevice 매개 변수를 통해 게임으로 전송됩니다. 예를 들어 한 오디오 장치 플러그인이 특정 컴퓨터에서 Windows의 오디오 장치에 접근하려고 할 때 여러 개의 Windows 장치를 발견할 경우가 있습니다.

만약 자신의 장치가 다른 장치들과 구분되지 않아도 무방하다면, 이 매개 변수를 무시해도 됩니다. 그러나 이러한 구현을 위해서는 idDevice 매개 변수가 0 일 때 선택되는 "기본 장치"를 반드시 지원해야 한다는 개념을 인지하고 있어야 합니다. 처음 사용 가능한 장치로 할 지 아니면 0 를 받았을 때 선택되는 특정 장치로 할 지는 플러그인 프로그래머의 선택에 달렸습니다.

싱크 플러그인은 사용 가능한 오디오 장치의 열거를 지원하기 위해 추가 정적 함수를 등록할 수 있습니다. 이 함수의 목적은 저작 툴에서 사용자가 선택 가능한 장치를 채워넣거나 AK::SoundEngine::GetDeviceList 호출을 통해 런타임에서 장치 열거를 할 수 있도록 하기 위해서입니다. 이 함수는 선택 사항입니다. 이 함수를 적용하지 않으면 플러그인은 필요시 'default' 출력으로 초기화합니다. 필요한 경우, 플러그인 매개 변수 생성 함수 후 추가 정적 함수를 제공해야 합니다. 플러그인 생성에 사용되는 다른 정적 함수에 대한 더 자세한 정보는 사운드 엔진 플러그인 만들기 를 참고하세요.

아래는 실제 존재하지는 않는 MyPlugin이라는 싱크 플러그인의 장치 열거를 구현하는 한 예제입니다. MyPlugin 네임스페이스의 함수들과 클래스들은 실제 플러그인 구현의 플레이스홀더입니다.

플러그인 장치 열거는 채울 장치의 최대 개수와 AkDeviceDescription 의 선할당된 배열로 Wwise에 의해 호출됩니다. 장치 이름의 최대 길이는 AK_MAX_PATH (256 자)입니다. 올바르게 채워진 장치 디스크립션의 개수를 반영하도록 값(io_maxNumDevices)을 수정해야 합니다. 제시된 장치 디스크립션 배열 포인터가 null이면 채워 넣을 장치 설명의 숫자를 반영하도록 개수를 수정해야 호출자가 out_deviceDescriptions에 대해 적절한 메모리 양을 할당할 수 있습니다.

// ...
 
AKRESULT GetMyPluginDeviceList(AkUInt32& io_maxNumDevices, AkDeviceDescription* out_deviceDescriptions)
{
    // 예를 들어, 사용 가능한 장치를 가져옴
    const AkUInt32 deviceCount = MyPlugin::GetNumberOfDevices();
    const MyPlugin::Device* devices = MyPlugin::GetDevices();
 
    // 장치 개수 요청을 처리함:
    // 만약 out_deviceDescriptions 가 NULL이면, io_maxNumDevices 가 장치 개수로 설정되어
    // 호출자가 메모리를 얼만큼 확보해놓을 지를 결정함
    if (out_deviceDescriptions == NULL)
    {
        io_maxNumDevices = deviceCount;
        return AK_Success;
    }
 
    // 또는, out_deviceDescriptions 를 채워 넣음
    // 사용 가능한 모든 장치가 채워질 때까지 (i == deviceCount)
    // 또는 배열의 끝에 다다를 때까지 (i == io_maxNumDevices)
    int i = 0;
    for (; i < deviceCount && i < io_maxNumDevices; ++i)
    {
        AKPLATFORM::SafeStrCpy(out_deviceDescriptions[i].deviceName, device[i]->deviceName, AK_MAX_PATH);
        out_deviceDescriptions[i].idDevice = devices[i].idDevice;
        out_deviceDescriptions[i].deviceStateMask = devices[i].deviceStateMask;
        out_deviceDescriptions[i].isDefaultDevice = devices[i].isDefaultDevice;
    }
 
    // 배열에 입력된 장치의 개수를 설정
    io_maxNumDevices = i;
 
    return AK_Success;
}
 
// 정적 이니셜라이저 오브젝트가 자동으로 플러그인을 사운드 엔진에 등록함
AK::PluginRegistration MyPluginRegistration(AkPluginTypeEffect, AKCOMPANYID_MYCOMPANY, EFFECTID_MYPLUGIN, CreateMyPlugin, CreateMyPluginParams, GetMyPluginDeviceList);

참고: 이 사운드 엔진 구현은 이전의 저작 전용 플러그인과 동등한 AkGetSinkPluginDevices 를 대체하여 모든 지원 플랫폼에 대해 장치 열거를 구현할 수 있으며 AK::SoundEngine::GetDeviceList 로 런타임에 호출할 수 있습니다.

참고: 이 함수는 모든 플랫폼에서 컴파일됩니다. 플랫폼에 특화된 장치 열거를 다루기 위해서는 적절한 매크로를 사용해야 하며 (예: AK_WIN, AK_LINUX, 등), 아무 구현도 정의돼있지 않은 플랫폼에서 AK_NotImplemented 를 반환해야 합니다.

Audio Device 플러그인의 저작 DLL

다른 플러그인과 마찬가지로, 싱크 플러그인 또한 해당하는 저작 DLL이 필요합니다. 모든 플러그인에 대해 공통으로 적용되는 Wwise 저작 컴포넌트 기본 설정에 대한 정보는 플러그인 라이브러리 형식 저작하기 을(를) 참고하세요.

참고: AkGetSinkPluginDevices 는 현재 사용 중단되었습니다. 장치 열거를 구현하려면 위의 사운드 엔진 컴포넌트 섹션을 참고하세요.

자신의 Audio Device 플러그인 시험해보기

플러그인의 Wwise 부분을 구현하고 ( 오디오 플러그인의 Authoring(저작) 부분 작성하기 ) 사운드 엔진 부분을 구현한 다음, 다음과 같이 단계별로 자신의 플러그인을 시험해볼 수 있습니다.

자신의 Wwise Project에서 자신의 새 플러그인을 사용하는 Audio Device ShareSet를 생성하세요. 이 ShareSet에 고유한 이름을 부여합니다.
뱅크를 생성합니다.
반드시 자신의 플러그인이 게임 코드에 등록돼있어야 합니다. 사운드 엔진 플러그인 개요 를 참고하세요.
사운드 엔진의 초기화 매개 변수에 자신의 오디오 장치 ID가 사용되도록 지정합니다. AkOutputSettings 의 ID는 프로젝트 내 Audio Device ShareSet의 이름 해시이며, AK::SoundEngine::GetIDFromString 에 의해 부여됩니다.

예시:

AkInitSettings initSettings;
AkPlatformInitSettings platformInitSettings;
AK::SoundEngine::GetDefaultInitSettings( initSettings );
AK::SoundEngine::GetDefaultPlatformInitSettings( platformInitSettings );
 
initSettings.settingsMainOutput.audioDeviceShareset = AK::SoundEngine::GetIDFromString("YourNewAudioDeviceSharesetNameHere");
 
AK::SoundEngine::Init( &initSettings, &platformInitSettings );

또 다른 방법으로, AK::SoundEngine::AddOutput 로 자신의 Audio Device 플러그인을 사용해도 됩니다.

AkOutputSettings outputSettings("YourNewAudioDeviceSharesetNameHere", 0 /*Default device*/)'

AK::SoundEngine::AddOutput(outputSettings);

AK::SoungEngine::GetDeviceList 를 이용하여 자신의 플러그인에 대해 장치 열거를 검사해볼 수 있습니다.

const int maxNbDevices = 20;
AkDeviceDescription devices[maxNbDevices];
 
AkUInt32 deviceCount = maxNbDevices;
AKRESULT res = AK::SoundEngine::GetDeviceList(
    AK::SoundEngine::GetIDFromString("YourNewAudioDeviceSharesetNameHere"),
    deviceCount,
    devices
);

더 자세한 정보는 다음 섹션을 참조하세요.

AkInitSettings::settingsMainOutput

AkOutputSettings settingsMainOutput

Main output device settings.

Definition: AkSoundEngine.h:229

AkDeviceDescription::deviceStateMask

AkAudioDeviceState deviceStateMask

Bitmask used to filter the device based on their state.

Definition: AkTypes.h:323

AK::SoundEngine::Init

AKSOUNDENGINE_API AKRESULT Init(AkInitSettings *in_pSettings, AkPlatformInitSettings *in_pPlatformSettings)

AK_MAX_PATH

#define AK_MAX_PATH

Maximum path length.

Definition: AkTypes.h:82

AkPlatformInitSettings

Definition: AkAndroidSoundEngine.h:55

AkDeviceDescription::isDefaultDevice

bool isDefaultDevice

Identify default device. Always false when not supported.

Definition: AkTypes.h:324

AKRESULT

Standard function call result.

Definition: AkTypes.h:213

AkPluginTypeEffect

@ AkPluginTypeEffect

Effect plug-in: applies processing to audio data.

Definition: AkTypes.h:1253

AkOutputSettings

Platform-independent initialization settings of output devices.

Definition: AkSoundEngine.h:116

NULL

#define NULL

Definition: AkTypes.h:46

AK_Success

@ AK_Success

The operation was successful.

Definition: AkTypes.h:215

AK::SoundEngine::GetDefaultInitSettings

AKSOUNDENGINE_API void GetDefaultInitSettings(AkInitSettings &out_settings)

AK::PluginRegistration

Definition: IAkPlugin.h:1762

AK::SoundEngine::GetDefaultPlatformInitSettings

AKSOUNDENGINE_API void GetDefaultPlatformInitSettings(AkPlatformInitSettings &out_platformSettings)

AKPLATFORM::SafeStrCpy

AkForceInline void SafeStrCpy(wchar_t *in_pDest, const wchar_t *in_pSrc, size_t in_uDestMaxNumChars)

Safe unicode string copy.

Definition: AkPlatformFuncs.h:449

AK::SoundEngine::GetIDFromString

AKSOUNDENGINE_API AkUInt32 GetIDFromString(const char *in_pszString)

AkDeviceDescription

Definition: AkTypes.h:320

AkOutputSettings::audioDeviceShareset

AkUniqueID audioDeviceShareset

Definition: AkSoundEngine.h:129

AkUInt32

uint32_t AkUInt32

Unsigned 32-bit integer

Definition: AkNumeralTypes.h:38

AkInitSettings

Definition: AkSoundEngine.h:215

AK::SoundEngine::GetDeviceList

AKSOUNDENGINE_API AKRESULT GetDeviceList(AkUInt32 in_ulCompanyID, AkUInt32 in_ulPluginID, AkUInt32 &io_maxNumDevices, AkDeviceDescription *out_deviceDescriptions)

AkDeviceDescription::idDevice

AkUInt32 idDevice

Device ID for Wwise. This is the same as what is returned from AK::GetDeviceID and AK::GetDeviceIDFro...

Definition: AkTypes.h:321

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

지원이 필요하신가요?

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

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

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

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

Wwise를 시작해 보세요

Wwise SDK

Audio Device (Sink) 플러그인 만들기