버전
menu_open
Wwise SDK 2019.1.11
통합 상세 내용 - 음악 콜백

소개

게임에 상호작용 음악을 만들 때, 그 음악의 박자와 관련한 정보가 필요할 수 있습니다. 음악 알림을 이용해 사운드 엔진으로부터 이 정보를 요청할 수 있습니다. 박자는 현재 재생 중인 주요 음악 세그먼트에 의해 결정됩니다. 세그먼트에는 다양한 박자표가 있을 수 있어, 현재 재생 중인 음악에 따라 박자가 바뀌게 됩니다. 재생 중인 음악이 없는 경우, 아무런 알림도 없습니다.

음악 콜백에는 다음과 같이 두 가지 타입이 있습니다.

  • Music Notiifcations (음악 알림): 현재 음악 재생 속성의 피호출자에게 알림을 보냅니다.
  • Music Playlist Selection (음악 재생 선택): 피호출자가 음악 재생 목록의 다음 요소 선택을 강제할 수 있도록 합니다.

음악 알림 사용 방법

음악에 대한 마커 알림을 받고자 할 경우, 애플리케이션을 설계할 때 고려해야 할 특정한 요소들이 있습니다.

  • 원하는 박자의 음악이 있는 이벤트 재생을 게시할 때 다음 중 하나 또는 여러 개의 플래그를 추가할 수 있습니다.
AK_MusicSyncBeat = 0x0100, // Music Beat(음악 박자) 알림 활성화.
AK_MusicSyncBar = 0x0200, // Music Bar(음악 마디) 알림 활성화.
AK_MusicSyncEntry = 0x0400, // Music Entry Point(음악 도입 지점) 알림 활성화.
AK_MusicSyncExit = 0x0800, // Music Exit Point(음악 종료 지점) 알림 활성화.
AK_MusicSyncGrid = 0x1000, // Music Grid(음악 그리드) 알림 활성화.
AK_MusicSyncUserCue = 0x2000, // Music User Cue(음악 사용자 큐) 알림 활성화.
AK_MusicSyncPoint = 0x4000, // 음악 싱크 지점 알림 활성화.
AK_MusicSyncAll = 0xff00, // AK_MusicSync 등록과 관련된 모든 알림을 받을 때 이 플래그를 사용.

이벤트 종료 알림을 받고자 하는 경우에는 AK_EndOfEvent | AK_MusicSyncBeat 를 사용해야 합니다. 플래그가 비트별로 배타적이기 때문입니다.

AkPlayingID AK::SoundEngine::PostEvent(
AkUniqueID in_eventID, // 이벤트의 고유 ID
AkGameObjectID in_gameObjectID, // 연관된 게임 오브젝트 ID
AkUInt32 in_uFlags = 0, // Bitmask: AkCallbackType 참조
AkCallbackFunc in_pfnCallback = NULL, // Callback function
void * in_pCookie = NULL // 콜백 함수로 보낼 콜백 쿠키
// 및 이와 함께할 추가적 정보
);
  • 자신의 콜백 함수는 반드시 다음의 포맷이어야 합니다.
static void MusicCallback(
AkCallbackType in_eType, // 콜백 이유 타입. 여기서는 AK_MusicSyncBeat
AkCallbackInfo* in_pCallbackInfo // 콜백 정보 구조체를 가리키는 포인터. 여기서는
// AkMusicSyncCallbackInfo*.
)
  • 콜백 함수가 호출되면 어떤 타입의 알림을 보낼 지 먼저 확인해야 합니다. 예를 들어 AK_MusicSyncBar 알림만 처리하는 경우, 다른 이벤트 타입을 받으면 반환해야합니다.
  • 알림 타입에 따라 in_pCallbackInfo 를 적절한 정보의 구조체 타입으로 형변환해야 합니다. 음악 알림의 경우, AkMusicSyncCallbackInfo 가 됩니다.
/// Ak_MusicSync 에 해당하는 콜백 정보 구조체
struct AkMusicSyncCallbackInfo : public AkCallbackInfo
{
AkPlayingID playingID; ///< Event의 Playing ID, PostEvent()에 의해 반환됨
AkCallbackType musicSyncType; ///< AK_MusicSyncEntry, AK_MusicSyncBeat, AK_MusicSyncBar, AK_MusicSyncExit, AK_MusicSyncGrid, AK_MusicSyncPoint 또는 AK_MusicSyncUserCue 중 하나.
AkReal32 fBeatDuration; ///< 초 단위 Beat(박자) 길이.
AkReal32 fBarDuration; ///< 초 단위 Bar(마디) 길이.
AkReal32 fGridDuration; ///< 초 단위 Grid(격자선) 길이.
AkReal32 fGridOffset; ///< 초 단위 Grid 오프셋.
};
주의
여러 음악 알림을 요청할 경우, 이 알림들이 추가적으로 전송됩니다. 즉, 4분의 4박자표에 AK_MusicSyncBeat 와 AK_MusicSyncBar 를 둘 다 등록하면 마디당 네 개의 박자 알림과 그 마디 자체에 대한 알림 하나를 받게 됩니다. 시간 '0' 또한 대부분의 경우 한 박자와 한 마디로 계산되며, AK_MusicSyncEntry 도 마찬가지입니다. 즉, 마디, 박자, 도입 지점을 등록하면 음악이 시작될 때 세 개의 콜백을 연달아 받게 됩니다.
템포는 다음 공식을 이용해 계산합니다: 템포 (단위: BPM) = 60.0 / fBeatDuration.
박자표의 분자는 다음 공식을 이용해 계산합니다: 분자값 = fBarDuration / fBeatDuration. 이를 통해 마디당 몇 박자가 있는 지 알 수 있습니다.
AK_MusicSyncExit 알림은 현재 세그먼트의 맨 끝에 다다랐을 때에만 전송됩니다. 만약 음악이 현재 세그먼트가 끝나기 전에 다른 세그먼트로 전환되면 AK_MusicSyncExit 알림을 보내지 않습니다.
참고
예제 통합으로 빠르게 시작하기 - 이벤트

음악 재생목록 콜백 사용 방법

위에서 언급한 콜백 함수를 이용해 음악 재생목록의 다음 요소 선택을 수작업으로 직접 관리할 수 있습니다. 그러기 위해 다음 플래그를 추가합니다.

AK_MusicPlaylistSelect = 0x0040 // 음악 재생목록 컨테이너가 다음 재생 요소를 선택해야 할 때 콜백이 트리거됩니다.

이 이벤트 타입을 받으면 콜백 함수가 in_pCallbackInfo 매개 변수를 AkMusicPlaylistCallbackInfo 타입으로 형변환해야 합니다.

/// Ak_MusicPlaylistSelect에 해당하는 콜백 함수 구조체
struct AkMusicPlaylistCallbackInfo : public AkEventCallbackInfo
{
AkPlayingID playlistID; ///< 음악 재생목록 컨테이너 내 활성화 노드의 ID
AkUInt32 uNumPlaylistItems; ///< 재생목록 노드 내 요소의 개수 (세그먼트나 다른 재생목록일 수 있음)
AkUInt32 uPlaylistSelection; ///< 선택: 사운드 엔진에 의해 설정되고, 콜백 함수에 의해 변경됨 (0 <= uPlaylistSelection < uNumPlaylistItems 범위 안에 있지 않을 경우 무시됨)
AkUInt32 uPlaylistItemDone; ///< 재생목록 노드 완료: 사운드 엔진에 의해 설정되고, 콜백 함수에 의해 변경됨 (0을 제외한 값으로 설정되면 현재 재생목록 요소가 완료되고 uPlaylistSelection가 무시됨)
};

playlistID 멤버가 활성화된 재생목록 노드를 표시합니다. 사운드 엔진은 재생목록 노드에서 다음 요소를 선택해 콜백 함수가 호출되기 전에 재생합니다. 이 선택은 uPlaylistSelection 와 uPlaylistItemDone 멤버에 포함돼있습니다. uPlaylistItemDone 을 0으로 설정하면 uPlaylistSelection 가 재생목록 노드에서 다음으로 재생할 요소를 결정합니다. uPlaylistItemDone 가 0으로 설정돼있지 않으면 현재 재생목록 노드가 종료됩니다 (이 경우 그 상위 노드가 활성화 노드로 됨). uPlaylistSelection 와 uPlaylistItemDone 멤버 모두 콜백 함수에 의해 변경할 수 있습니다.

알림 레이턴시

현재는, 버퍼가 하드웨어로 전달될 때 알림을 보냅니다. 즉, 알림을 보낼 때와 실제 재생될 때 사이에 일정한 상수 지연이 있다는 것을 의미합니다. 이는, 애플리케이션이 마커와 관련된 정보를 모으고, 해당 마커에 연결된 사운드가 실제 재생되기 전에 이를 처리할 수 있는 충분한 시간이 됩니다.

이 지연 시간은 플랫폼별로 다르다는 점에 유의하세요.

콜백 스레드

마커의 콜백은 사운드 엔진의 주요 스레드에서 처리됩니다. 즉, 애플리케이션이 알림으로부터 필요한 모든 정보를 모은 후 즉각 반환해야한다는 뜻입니다. 만약 특정 처리가 필요한 경우, 알림으로부터 관련 정보를 복사해온 후 별도의 스레드에서 실행해야 합니다.

애플리케이션이 스레드를 너무 오래 붙잡고 있으면 사운드 엔진이 언더런(underrun) 상태로 들어가고 출력 재생이 중단될 수 있습니다.

참고
통합 세부 사항 - Event
AkMusicPlaylistCallbackInfo::uPlaylistSelection
AkUInt32 uPlaylistSelection
Selection: set by sound engine, modified by callback function (if not in range 0 <= uPlaylistSelectio...
Definition: AkCallback.h:188
AkMusicSyncCallbackInfo::musicSyncType
AkCallbackType musicSyncType
Would be either AK_MusicSyncEntry, AK_MusicSyncBeat, AK_MusicSyncBar, AK_MusicSyncExit,...
Definition: AkCallback.h:217
AkMusicSyncCallbackInfo::playingID
AkPlayingID playingID
Playing ID of Event, returned by PostEvent()
Definition: AkCallback.h:215
AkMusicPlaylistCallbackInfo::uPlaylistItemDone
AkUInt32 uPlaylistItemDone
Playlist node done: set by sound engine, modified by callback function (if set to anything but 0 then...
Definition: AkCallback.h:189
AkMusicPlaylistCallbackInfo::playlistID
AkUniqueID playlistID
ID of playlist node
Definition: AkCallback.h:186
AkMusicPlaylistCallbackInfo::uNumPlaylistItems
AkUInt32 uNumPlaylistItems
Number of items in playlist node (may be segments or other playlists)
Definition: AkCallback.h:187
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)

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

지원이 필요하신가요?

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

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

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

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

Wwise를 시작해 보세요