ACP 개요
이 섹션에서는 ACP의 프로그래밍 인터페이스를 설명합니다.acphal 라이브러리(acphal.lib)는 Scalable Hardware Audio Processing Engine(SHAPE)의 API 세트를 정의합니다. Microsoft Game Development Kit(GDK)에는 SHAPE와 함께 사용할 오디오 데이터를 준비하는 데 도움이 되는 오디오 유틸리티 및 소스 코드 모음도 포함되어 있습니다. 유틸리티 헤더는 다음을 정의합니다:
- 지원되는 각 데이터 형식에 대한 컨텍스트 구조
- 이러한 컨텍스트에 대해 읽고 쓸 수 있는 함수의 전체 세트
- 플로우그래프
- DMA 유틸리티
- EQ 컴프레서 유틸리티
- 필터 볼륨 유틸리티
- PCM 유틸리티
- SRC 유틸리티
- XMA 유틸리티
- 타깃 값
- 스레드 안전성
- PCM 및 XMA 데이터에 SRC를 사용하기 위한 지침
- 타이틀 일시 중지 및 재개
플로우그래프
SHAPE를 사용하기 위해 타이틀은 일반적으로 SHAPE 플로우그래프를 생성합니다. 다른 대안에 대한 설명은 XMA 유틸리티 섹션을 참고하십시오. SHAPE 플로우그래프는 명령 배열(SHAPE 블록당 하나)과 함께 개별 블록의 동작 순서와 처리할 데이터를 설명하는 컨텍스트 데이터로 이루어집니다. ACP는 플로우그래프의 데이터를 사용하여 SHAPE 블록 내 동작을 올바르게 스케줄링합니다. 타이틀은 플로우그래프를 구성하고 ACP에 제출할 책임이 있습니다. 플로우그래프를 구성하려면 ShapeFlowGraph (flowgraph utility methods)를 사용하십시오. 다음 그림에서 녹색 블록은 SHAPE 구성요소를, 시안 블록은 소스 자료를, 라벨이 붙은 노란색 원은 하드웨어 믹스 버퍼를 나타냅니다.3D 사운드
그림 1. 두 출력 간에 패닝되는 두 개의 보이스, 공통 출력으로의 send 포함. 코드로 표현하면 이 플로우그래프는 다음과 같이 나타낼 수 있습니다.소프트웨어 오디오 엔진의 프론트엔드
그림 2. 소프트웨어 엔진에 대한 기본 프론트엔드. 잠재적으로 이 모델을 사용하는 모든 보이스는 동일한 구조를 사용할 수 있습니다. 코드로 표현하면 이 플로우그래프는 다음과 같이 나타낼 수 있습니다.오디오 렌더링
오디오를 렌더링하려면- 이전 예제에서 보여준 것과 같이 처리할 오디오 그래프를 정의하는 플로우그래프를 생성합니다.
- 플로우그래프가 어떻게 무엇을 처리할지 정의하는 컨텍스트 구조를 생성합니다.
-
SubmitCommand 메서드를 사용하여 ACP에 플로우그래프를 제출합니다.
SubmitCommand의 매개변수에 따라 플로우그래프는 한 번 처리된 후 삭제되거나 매 오디오 프레임마다 처리됩니다. -
타이틀은
ACP_COMMAND_UPDATE_*_CONTEXT명령을 사용하거나, 플로우그래프 처리와 업데이트를 올바르게 동기화하고 컨텍스트를 수동으로 업데이트하여 각 오디오 프레임마다 컨텍스트 데이터를 업데이트할 책임이 있습니다.- ACP_COMMAND_UPDATE_DMA_CONTEXT
- ACP_COMMAND_UPDATE_EQCOMP_CONTEXT
- ACP_COMMAND_UPDATE_FILTVOL_CONTEXT
- ACP_COMMAND_UPDATE_PCM_CONTEXT
- ACP_COMMAND_UPDATE_SRC_CONTEXT
- ACP_COMMAND_UPDATE_XMA_CONTEXT
ACP_COMMAND_TYPE_UPDATE_*_CONTEXT 명령은 오디오 프레임당 소수의 컨텍스트를 업데이트할 때 사용하십시오. 이 명령으로 다수의 컨텍스트를 업데이트하는 것은 효율적이지 않은데, 명령 처리 외에도 많은 양의 컨텍스트 데이터를 복사하여 ACP로 전송해야 하기 때문입니다. 다수의 컨텍스트를 업데이트하려면 타이틀은 컨텍스트 데이터를 수정한 후 비영구적 플로우그래프를 ACP에 제출하거나, ACP_COMMAND_TYPE_START_FLOWGRAPH 명령과 ACP_COMMAND_LOAD_SHAPE_FLOWGRAPH 명령의 waitForStart 매개변수를 잘 활용하여 컨텍스트가 업데이트될 때까지 처리를 대기시켜야 합니다. 플로우그래프가 처리를 완료하면 컨텍스트는 다시 업데이트할 수 있게 됩니다.
컨텍스트를 업데이트하는 세 번째 대안은 더블 버퍼링 프로세스를 사용하는 것입니다. 타이틀은 플로우그래프가 처리되는 동안 컨텍스트의 두 번째 복사본을 업데이트하고 오디오 프레임 시작 시 컨텍스트를 교체할 수 있습니다.
플로우그래프 파싱
ACP는 오디오 프레임(2.667ms 제한이 있는 ACP 오디오 프레임)의 끝에서 영구적 플로우그래프의 파싱을 종료합니다. 타이틀이 오디오 프레임의 75%를 처리하는 데 필요한 플로우그래프를 가지고 있지만, 오디오 프레임의 30%가 지난 시점에서야 처리를 시작하도록 허용한다면, 파싱되지 못한 플로우그래프 부분은 폐기됩니다. 플로우그래프 자체는 변경되지 않습니다. 이런 일이 발생하면, 타이틀이 메시지를 수신하도록 등록되어 있는 경우 ACP는ACP_MESSAGE_TYPE_FLOWGRAPH_TERMINATED 메시지를 보냅니다. 어떤 명령이 내부 SHAPE 큐에 삽입되지 않았는지 확인하려면 타이틀이 플로우그래프 명령의 queued 플래그를 검사하면 됩니다.
비영구적 플로우그래프는 제출 시간과 상관없이 일반적으로 완료될 때까지 처리됩니다. 예외 중 하나는 소스 데이터의 부재나 disabled 플래그의 잘못된 사용으로 인해 하나 이상의 명령이 차단되는 경우입니다. 타이틀은 ACP 오디오 프레임 중 어느 시점에서든 비영구적 플로우그래프를 제출할 수 있으며, (몇 가지 경계 사례를 제외하고) 완료될 것을 확신할 수 있습니다. 이점은 2.667ms의 ACP 오디오 프레임 간격 내에서 플로우그래프를 계속 처리하는 한 타이틀이 오디오 클록과 완벽하게 동기화될 필요가 없다는 것입니다. 위험은 타이틀이 플로우그래프를 일관되게 제출하지 않거나 플로우그래프가 2.667ms를 초과하는 경우 오디오 드롭아웃이 발생할 수 있다는 것입니다.
다음은 플로우그래프의 수명에 대한 요약입니다.
- 영구적 플로우그래프는 새 플로우그래프나 사실상 제거되는 null 플로우그래프가 제출되어 교체될 때까지 ACP에서 활성 상태로 유지됩니다.
- ACP는 클라이언트가 시작 명령을 기다리도록 지시하지 않는 한 오디오 프레임 시작 시 영구적 플로우그래프 처리를 시작합니다.
- ACP는 영구적 플로우그래프가 완전히 처리되지 않았더라도 오디오 프레임 종료 직전에 처리를 중단합니다.
- 비영구적 플로우그래프는 완료될 때까지만 활성 상태이며 이후 제거됩니다.
- 비영구적 플로우그래프는 오디오 프레임 사이에도 활성 상태로 유지됩니다. 완료된 후에만 제거됩니다.
명령 처리는 플로우그래프 파싱과 연결되어 있지 않습니다. ACP는 지속적으로 새 명령을 스캔하며 플로우그래프 파싱이나 다른 작업을 수행하면서 최대한 빨리 처리합니다.
플로우그래프 업데이트
플로우그래프를 업데이트하는 옵션은 앞서 설명한 컨텍스트 업데이트 옵션과 유사합니다. 기본 규칙은 동일합니다: 처리 중인 플로우그래프는 업데이트하지 마십시오. 플로우그래프를 업데이트하는 세 가지 전략을 사용할 수 있습니다.- 비영구적 플로우그래프를 사용하고 필요할 때 재구성한 후 오디오 프레임 시작 시 제출합니다. 타이틀은 필요한 만큼 같은 플로우그래프를 재사용할 수 있습니다. 플로우그래프가 변경되지 않으면 재구성할 필요가 없습니다. 이전 것이 처리되는 동안 새 플로우그래프를 구성하는 방식으로 이 접근 방식을 더블 버퍼링할 수도 있습니다. 재구성할 때, 플로우그래프는 처음부터 구성할 수 있을 뿐만 아니라, 믹스 버퍼 ID를 적절히 설정하여 섹션을 저장하고 필요에 따라 연결할 수도 있습니다.
-
영구적 플로우그래프를 사용하고 변경이 필요할 때만 재구성하여 교체합니다. 여기서도 더블 버퍼링이 유효합니다. ACP_COMMAND_LOAD_SHAPE_FLOWGRAPH의
waitForStart매개변수를 사용하지 않음으로써 ACP가 자유롭게 실행되도록 할 수 있습니다. ACP는 오디오 프레임이 시작되자마자, 그리고 해당 오디오 프레임을 위한 명령이 처리된 직후 플로우그래프 처리를 시작합니다. 또는waitForStart매개변수를 설정하여ACP_COMMAND_TYPE_START_FLOWGRAPH명령이 전송될 때까지 플로우그래프가 처리되지 않도록 할 수 있습니다. 이는 플로우그래프 업데이트에 직접적으로 영향을 미치지는 않지만 동기화가 약간 개선됩니다. -
플로우그래프의 일부를 비활성화하려면 플로우그래프 명령의
disabled플래그를 사용합니다. 예를 들어, 마스터 플로우그래프를 구축하되 각 실행에서 필요한 섹션만 활성화할 수 있습니다. 새 플로우그래프를 ACP에 전달하려면 이 방법은 옵션 1 또는 2와 함께 사용해야 합니다. ACP는 현재 고립된 블록을 찾기 위해 플로우그래프를 순회하지 않는다는 점에 유의하십시오. 타이틀은 플로우그래프를 통한 전체 경로를 비활성화해야 합니다(첫 번째 노드만이 아님). 이를 수행하지 않으면 SHAPE 명령이 하드웨어를 일시적으로 정체시킵니다. 이러한 정체는 처리할 수 없는 단일 블록이 작은 비용으로 제거되는 것처럼 단순할 수도 있고, 전체 보이스를 정체시킬 만큼 심각할 수도 있습니다.
ACP_MESSAGE_TYPE_FLOWGRAPH_COMPLETED를 사용하여 업데이트를 관리하는 경우, ACP가 메시지를 메시지 큐에 추가한 후 타이틀이 PopMessage를 호출하기까지 ACP가 오랫동안 유휴 상태로 남을 수 있습니다. 업데이트를 관리하는 데 이 방식을 사용하지 마십시오 - ACP가 계속 활성 상태를 유지하도록 하십시오.
다중 플로우그래프
타이틀은 여러 플로우그래프의 결합된 요구사항이 하드웨어 성능을 초과하지 않는 한 오디오 프레임당 여러 플로우그래프를 처리할 수 있습니다. 이점은 타이틀이 미들웨어 및 커스텀 오디오 엔진을 여러 개 실행하거나 파싱을 더 관리하기 쉬운 청크로 나눌 수 있다는 것입니다. 단점은 이 모드에서 SHAPE 하드웨어가 그다지 효율적으로 실행되지 않는다는 것입니다. SHAPE의 최대 처리량에 도달하려면 각 SHAPE 블록이 100% 바쁘게 유지되어야 하는데, 여러 플로우그래프가 처리될 때는 이것이 불가능합니다. ACP 클라이언트당 하나의 플로우그래프만 로드할 수 있습니다. 클라이언트가 새 플로우그래프를 제출하면 기존 플로우그래프를 대체합니다. 다중 플로우그래프 지원이 필요한 타이틀은 각 플로우그래프 유형에 대해 별도의 클라이언트(각 클라이언트는 자체 명령 및 메시지 큐를 가짐)를 두거나, 새 플로우그래프를 제출하기 전에 플로우그래프가 완료될 때까지 기다려야 합니다. 다중 플로우그래프 지원은 단일 클라이언트가 아니라 여러 클라이언트에서 사용되도록 설계되었습니다. 이를 통해 미들웨어 엔진은 자체 플로우그래프를 제출하고, 타이틀은 추가 커스텀 처리를 위한 별도의 플로우그래프를 제출할 수 있습니다. 타이틀에서 필요한 각 ACP 클라이언트에 대해IACPHAL 인터페이스의 인스턴스를 생성하십시오.
모든 ACP 및 SHAPE 리소스(특히 컨텍스트 배열)는 모든 클라이언트 간에 공유되므로, 클라이언트는 해당 리소스의 할당 및 공유를 조율해야 합니다.
DMA 유틸리티
Direct Memory Access(DMA) 유틸리티는 ShapeDMAContext.h 파일에 포함되어 있습니다. 다음 유틸리티는 SHAPE_DMA_CONTEXT 구조에 대해 동작합니다. 자세한 내용은 ShapeDmaContext (DMA utility methods)를 참고하십시오.EQ 컴프레서 유틸리티
EQCOMP 유틸리티는 ShapeEqCompContext.h 파일에 포함되어 있습니다. 이 유틸리티는 SHAPE_EQCOMP_CONTEXT 구조에 대해 동작합니다. 자세한 내용은 ShapeEqCompContext (EQCOMP utility methods)를 참고하십시오.필터 볼륨 유틸리티
필터 볼륨 유틸리티는 ShapeFiltVolContext.h 파일에 포함되어 있습니다. 이 유틸리티는 SHAPE_FILTVOL_CONTEXT 구조에 대해 동작합니다. 자세한 내용은 ShapeFiltVolContext (FLTVOL utility methods)를 참고하십시오.PCM 유틸리티
Pulse Code Modulation(PCM) 유틸리티는 ShapePCMContext.h 파일에 포함되어 있습니다. 이 유틸리티는 SHAPE_PCM_CONTEXT 구조에 대해 동작합니다. 자세한 내용은 ShapePcmContext (PCM utility methods)를 참고하십시오.SRC 유틸리티
Sample Rate Convertor(SRC) 유틸리티는 ShapeSRCContext.h 파일에 포함되어 있습니다. 이 유틸리티는 SHAPE_SRC_CONTEXT 구조에 대해 동작합니다. 자세한 내용은 ShapeSrcContext (SRC utility methods)를 참고하십시오.XMA 유틸리티
XMA 유틸리티는 ShapeXMAContext.h 파일에 포함되어 있습니다. 이 유틸리티는 SHAPE_XMA_CONTEXT 구조에 대해 동작합니다. 자세한 내용은 ShapeXmaContext (XMA utility methods)를 참고하십시오. 하드웨어 에뮬레이션의 XMA 디코드 기능은 제한적입니다. 자세한 내용은 SHAPE_XMA_CONTEXT 구조 항목을 참고하십시오. 타이틀은 플로우그래프 없이 XMA 데이터를 사용할 수 있지만, 데이터는 여전히 다음 표에 나온 ACP_COMMAND_TYPE 명령을 사용하여 ACP를 통과해야 합니다.
이러한 명령을 사용하면 타이틀은 다음 순서로 동작을 진행하여 XBOX 360 XMA HAL을 사용하는 것과 거의 동일하게 XBOX One ACP HAL을 사용할 수 있습니다.
- 관련 데이터로 컨텍스트를 채웁니다: 버퍼, 오프셋 등.
- 컨텍스트를 활성화합니다.
-
컨텍스트를 업데이트합니다. 컨텍스트가 비활성화되어 있으면 타이틀은 자유롭게 내용을 직접 수정할 수 있습니다. 컨텍스트가 활성화되어 있으면 타이틀은 먼저 비활성화하거나, ACP가 비활성화, 대기, 업데이트를 처리하기 때문에 더 효율적일 수 있는
ACP_COMMAND_TYPE_UPDATE_XMA_CONTEXT명령을 사용할 수 있습니다.
타깃 값
유틸리티 함수에서 설정할 수 있는 타깃 값은 오디오 프레임 종료 시 매개변수의 최종 값을 나타냅니다. 예를 들어 SHAPE_FILTVOL_CONTEXT 구조에는gain 및 gainTarget 값이 포함되어 있습니다. 프레임이 처리되는 동안 gain은 선형 보간과 다음 방정식을 사용하여 계산됩니다.
gain은 gainTarget과 같아집니다.
ACP에 설정할 수 있는 타깃 매개변수는 다음 표와 같습니다.
스레드 안전성
IACPHAL 인터페이스 메서드 및 ACPHAL 메서드는 스레드에 안전합니다. ApuCreateHeap 호출이 수행되면 힙이 모든 스레드에서 사용됩니다. 다음 유틸리티 함수는 스레드에 안전하지 않습니다. 하지만 이에 대한 소스 코드가 제공됩니다. 필요한 경우 스레드 안전하게 만들 수 있습니다. 일반적인 방법은 Critical Section Objects를 사용하는 것입니다.- ShapeFlowGraph (flowgraph)
- ShapeDmaContext (DMA)
- ShapeEqCompContext (EQCOMP)
- ShapeFiltVolContext (FLTVOL)
- ShapePcmContext (PCM)
- ShapeSrcContext (SRC)
- ShapeXmaContext (XMA)
PCM 및 XMA 데이터에 SRC를 사용하기 위한 지침
다음 표는 PCM 및 XMA 데이터에 SRC 블록을 사용하기 위한 지침입니다.이러한 시나리오 중 하나가 완료되면 SRC 명령은
SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE입니다.타이틀 일시 중지 및 재개
예를 들어 사용자가 Constrained 모드로 전환할 때, 타이틀은 일시 중지하고 재개할 수 있어야 합니다.IAcpHal을 사용하여 SHAPE 하드웨어에 직접 코딩할 때 일시 중지하고 재개하려면 타이틀이 단순히 명령 제출을 중지하도록 하십시오. 이미 제출된 명령은 정상적으로 완료되며 메시지 큐를 채울 수 있습니다.
타이틀이 영구적 플로우그래프를 사용하는 경우 처리를 중지하기 위해 null 플로우그래프를 로드해야 합니다. 이것은 XAudio2를 사용하여 코딩할 때의 일시 중지 및 재개 프로세스와 다릅니다. 자세한 내용은 XAudio2 개요를 참고하십시오.
참조 API 문서
- Acphal (API contents)
- Shapedmacontext (API contents)
- Structures
- Shapeeqcompcontext (API contents)
- Structures
- Shapefiltvolcontext (API contents)
- Structures
- Shapeflowgraph (API contents)
- Shapepcmcontext (API contents)
- Structures
- Shapesrccontext (API contents)
- Structures
- Shapexmacontext (API contents)
- Structures
- apu (API contents)
- Functions
