버전
menu_open
Wwise SDK 2024.1.0
통합 세부사항 - MIDI

소개

SDK API는 MIDI 이벤트를 사운드 엔진에 전달하도록 함수를 제공합니다. 발송 가능한 MIDI 이벤트의 타입:

  • 노트-온(note-on) 이벤트
  • 노트-오프(note-off) 이벤트
  • 그리고 연속 제어기(CC) 이벤트

사운드를 생성하기 위한 MIDI 이벤트에 대해서 반드시 대상 신시사이저를 가져야 합니다. 신시사이저는 프로젝트의 액터-믹서 계층 구조에서 Wwise 사용자에 의해 생성된 Wwise 오브젝트의 모음입니다. 노트-온 이벤트는 일반적으로 대상 액터-믹서 오브젝트나 이를 통해 파생된 오브젝트를 재생하게 됩니다. 재생된 액터-믹서 오브젝트는 다음과 같은 상황에서 재생을 중지합니다.

  • 반복 재생이 설정되지 않았으며 음원의 끝까지 도달했을 때
  • 또는, 해당 노트-오프 이벤트가(같은 노트와 채널) 같은 대상으로 전송될 때

게임에 MIDI 이벤트의 통합

AK::SoundEngine::PostMIDIOnEvent "PostMIDIOnEvent" 함수는 사운드 엔진에서 MIDI 이벤트를 큐에 넣습니다. 이 함수는 다음 인자를 받습니다.

  • MIDI 이벤트
  • Event ID
  • Game Object ID
  • Playing ID

사운드 엔진은 발송된 MIDI 이벤트를 시퀀스에 그룹화합니다. 각각의 시퀀스는 다음과 같이 식별됩니다.

  • Game Object ID; 함수 매개 변수
  • Playing ID; 함수 매개 변수
  • Wwise Object ID; 이벤트 ID에 부합하는 이벤트에서 각 재생 동작의 대상 오브젝트로부터 가져옴. 이벤트와 관련해서 더 자세한 내용은 Event 통합하기 를 참고합니다.

이렇게 해서 같은 MIDI 이벤트를 여러 대상에 동시에 전달하는 게 가능합니다. 예를 들어, 다음과 같이 가정해보겠습니다.

  • 이벤트 EV1, 이는 Wwise Object W0과 W1에 대한 재생 액션을 갖습니다.
  • 이벤트 EV2, 이는 Wwise 오브젝트 W0에 대한 재생 액션을 갖습니다.

만약 Game Object GO와 함께 MIDI 이벤트 ME1을 EV1으로 전달하면, 사운드 엔진이 MIDI 시퀀스 W0-GO-PID1과 W1-GO-PID1에 MIDI 이벤트 ME1을 추가하며, 이 때 PID1은 PostMIDIOnEven에 의해 반환된 Playing ID입니다. 그러고 나서 MIDI 이벤트 ME2를 이벤트 EV2에 전달하면, 사운드 엔진이 MIDI 이벤트 ME2를 MIDI 시퀀스 W0-GO-PID2에 추가하게 됩니다.

AK::SoundEngine::PostMIDIOnEvent를 호출하면 MIDI 이벤트가 MIDI 시퀀스에 추가됩니다. 그러나 AK::SoundEngine::RenderAudio 함수가 호출되기 전까지는 어떠한 처리도 완료되지 않습니다. 각각의 AK::SoundEngine::RenderAudio 호출로 메시지 큐를 처리하며, 얼마든지 오디오 프레임을 생산해낼 수 있습니다. 이는 이전 RenderAudio 호출 이후 얼마나 많은 시간이 소요되었는지에 따라 달라집니다. RenderAudio에 의해 처리되는 각 프레임에 대해 사운드 엔진은 한 프레임에서 모든 MIDI 시퀀스의 처리를 진행합니다.

MIDI 이벤트 타이밍

MIDI 이벤트가 언제 실행될지는 다음 요소에 의해 결정됩니다.

  • 큐에 담기는 시점 (PostMIDIOnEvent를 통해)
  • 이벤트의 멤버 AkMIDIPost::uOffset
  • PostMIDIOnEvent를 호출할 때 제공되는 전달인자 in_bAbsoluteOffsets

in_bAbsoluteOffsets가 false이면, MIDI 이벤트는 사운드 엔진의 메시지 큐에서 PostMIDIOnEvent 메시지를 읽은 시간부터 uOffset 샘플을 실행합니다. ( MIDI 시퀀스 갱신 참고). 만약 in_bAbsoluteOffsets가 true이면, MIDI 이벤트가 절대 시간 기준으로 uOffset 샘플을 실행합니다. 현재 절대 시간은 AK::SoundEngine::GetSampleTick 호출로 가져옵니다.

참고: 샘플의 지속 시간은 사운드 엔진의 오디오 세팅, 즉 AK::SoundEngine::GetAudioSettings 호출에 의해 정할 수 있습니다.

MIDI 이벤트 시퀀스 - Playing ID

PostMIDIOnEvent 호출은 MIDI 시퀀스로 전달된 모든 MIDI 이벤트를 합칩니다. 앞서 설명한 것과 같이, MIDI 시퀀스는 다음 내용으로 정의됩니다.

  • Playing ID
  • Game Object ID
  • Event ID 시퀀스의 Playing ID는 AK_INVALID_PLAYING_ID 로 설정된 in_playingID로 PostMIDIOnEvent 호출을 이용해 생성됩니다. 다음 호출인 PostMIDIOnEvent에 이 Playing ID를 이용해 시퀀스에 MIDI 이벤트를 추가합니다. 이 시퀀스는 다음과 같습니다.
  • PostMIDIOnEvent 첫번째 호출이 MIDI 시퀀스를 생성합니다. 함수 인자 in_playingID가 AK_INVALID_PLAYING_ID 에 설정됩니다. 이 함수가 Playing ID PID를 반환합니다.
  • 시퀀스에 이벤트를 추가하기 위해 그 다음 호출 PostMIDIOnEvent를 만듭니다. 함수 인자 in_playingID가 PID로 설정됩니다.

PostMIDIOnEvent가 반환한 Playing ID가 이벤트가 원하는 시퀀스에 전달됐는지를 확인합니다. 만약 반환된 Playing ID가

  • in_playingID와 일치하는 경우, 이벤트가 의도한 시퀀스에 추가된 것입니다.
  • in_playingID와 일치하지 않는 경우, 이벤트는 새로 생성된 시퀀스에 추가된 것입니다.
  • AK_INVALID_PLAYING_ID 인 경우, 오류가 발생하고 이벤트는 아무 시퀀스에도 추가되지 않은 것입니다.

지정된 시퀀스와는 별개로 다음과 같은 상황에서 새로운 시퀀스가 생성될 수 있습니다.

  • 시퀀스(Playing ID)가 존재하지 않는 경우
  • 시퀀스가 다른 Game Object나 Event를 이용해 생성된 경우
  • 모든 MIDI 이벤트가 실행되었고 모든 재생 사운드가 종료됐기 때문에 시퀀스가 더 이상 존재하지 않는 경우

MIDI 시퀀스 갱신

여기서 중요한 점은, 각각의 MIDI 시퀀스가 애플리케이션에 의해 의도된 정확한 시간으로 사운드 엔진에 의해서 재생된다는 점입니다. MIDI 시퀀스가 사운드 엔진에 전달되는 방법에는 두 가지가 있습니다.

전체 MIDI 시퀀스에 대해 알고 있으며 MIDI 시퀀스의 타이밍이 변경되지 않는다면, 전체 MIDI 시퀀스는 한 번의 AK::SoundEngine::PostMIDIOnEvent 호출로 전달될 수 있습니다.

그러나 이러한 경우가 아니라면, MIDI 시퀀스는 매프레임마다 갱신되어야 합니다. AK::SoundEngine::PostMIDIOnEvent 함수는 애플리케이션에서 언제 어디서나 호출될 수 있습니다. 그러나 메인 오디오 스레드 외에 다른 스레드에서 이 함수를 호출하면 동기화 이슈가 발생할 수 있습니다. AK::SoundEngine::PostMIDIOnEvent 호출은 사운드 엔진의 메시지 큐에 이벤트만 전달하게 됩니다. 메시지 큐는 AK::SoundEngine::RenderAudio 호출로 처리되며, 이러한 호출은 많은 오디오 프레임 처리를 초래할 수 있습니다. 적절한 동기화를 보장하도록 다음과 같이 애플리케이션이 전역 콜백 함수를 등록할 것을 권장합니다.

  • AK::SoundEngine::RegisterGlobalCallback( &MyCallbackFunction, AkGlobalCallbackLocation_PreProcessMessageQueueForRender );

등록된 함수는 각 오디오 프레임에서 사운드 엔진에 의해 호출됩니다. 애플리케이션은 오디오 프레임의 트랙을 유지하도록 콜백 함수를 사용할 수 있습니다. 이렇게 콜백 함수에서 MIDI 이벤트를 발송하면 적절한 동기화를 보장하게 됩니다.

MIDI 시퀀스의 중지

MIDI 시퀀스의 재생을 중지하기 위해서 AK::SoundEngine::StopMIDIOnEvent "StopMIDIOnEvent" 함수를 호출합니다. 이 함수는 매개 변수로 Playing ID와 Event ID, Game Object ID를 받습니다. 이러한 매개 변수는 와일드카드로 동작하도록 유효하지 않은 값이 설정될 수 있습니다. 이렇게 모든 전달인자가 유효하지 않은 값으로 설정되면 모든 MIDI 시퀀스가 중지됩니다.

이 함수를 호출하면 MIDI 시퀀스를 삭제하고 사운드 재생을 중지하게 됩니다.

MIDI의 통합 예제와 관련한 내용은 예제 통합으로 빠르게 시작하기 - MIDI 를 참고하세요.

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

지원이 필요하신가요?

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

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

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

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

Wwise를 시작해 보세요