IAcpHal::SubmitCommand
ACP에 명령을 제출합니다.구문
매개 변수
command형식: ACP_COMMAND_TYPE 명령입니다. ACP_COMMAND_TYPE 열거형을 참조하세요. commandId
형식: UINT64 명령에 대한 선택적, 임의의 식별자입니다. 이 ID는 특정 메시지와 함께 반환됩니다. 포인터를 명령 ID로 전달하는 것을 지원하기 위한 UINT64입니다. audioFrame
형식: UINT32 오디오 프레임 번호가 지정되면, 이미 지나가지 않은 경우 해당 오디오 프레임 시작 시 명령이 처리됩니다. 지나간 경우에는 다음 오디오 프레임에서 처리가 시작됩니다. 이 매개 변수에는 두 가지 특수 값도 있습니다.
ACP_SUBMIT_PROCESS_COMMAND_ASAP는 ACP에 명령을 가능한 한 빨리—가능하다면 현재 오디오 프레임에—처리하도록 지시합니다.ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAME은 ACP에 다음 오디오 프레임 시작 시 명령을 처리하도록 지시합니다. 명령이 컨텍스트를 업데이트하는 것이라면, 이 컨텍스트는 플로우그래프 처리가 시작되기 전에 업데이트됩니다. 이는 플로우그래프 처리의 시작을 지연시키며, 이는 음성 수가 많은 그래프가 음성을 삭제하게 될 수 있습니다.
형식: void* 명령과 관련된 선택적 데이터입니다. 대부분의 명령은 데이터 구조가 필요합니다. notification _In_opt_
형식: APU_ADDRESS 명령이 완료될 때 0이 아닌 값으로 설정되는 UINT32 요소의 선택적 물리적 주소입니다. 가상 주소에 대한 해당 포인터는 volatile로 선언되어야 합니다. 이는 command-completed 메시지와 유사하지만, 명령의 완료를 알리기 위해 메시지가 필요하지 않다는 점이 다릅니다. XAudio2가 ACP에 명령을 제출할 때, 명령이 완료되었는지 확인할 때 이 알림 포인터를 사용합니다.
반환 값
형식: HRESULT 메서드가 성공하면 S_OK를 반환합니다. 메서드가 실패하면 다음 코드 중 하나를 반환합니다(부분 목록):설명
이는 타이틀이 Audio Control Processor(ACP), Scalable Hardware Audio Processing Engine(SHAPE) 및 XMA와 통신할 수 있게 하는 유일한 API입니다. 이SubmitCommand 메서드를 사용하여 제출된 데이터의 수명은 가변적입니다. 입력으로 전달된 구조체에 대한 포인터는 API 호출 중에만 참조됩니다. 이는 개발자가 로컬 변수를 안전하게 사용할 수 있음을 의미합니다. 명령이 다른 데이터 블록에 대한 포인터를 포함하는 경우, 그 데이터는 복사되지 않으며 ACP가 명령을 처리할 때까지 존재해야 합니다. 이는 내부적으로 복사되는 데이터의 양을 최소화하기 위해 수행됩니다. 추가 명령 데이터의 수명 관리가 문제인 경우, 애플리케이션은 command completed 메시지에 등록하여 명령의 추가 데이터가 더 이상 참조되지 않는 정확한 시점에 메시지를 수신할 수 있습니다.
타이틀이 ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAME 플래그가 설정되거나 특정 오디오 프레임 번호가 있는 하나 이상의 명령을 제출한 경우, 이러한 모든 명령은 지정된 오디오 프레임 시작 시 다른 처리가 수행되기 전에 처리됩니다.
모든 ACP 명령은 메인 CPU에서 비동기적이므로 IAcpHal::SubmitCommand에 대한 호출은 처리를 차단하지 않습니다.
다음은 타이틀이 알림을 사용하기 위한 가장 효율적인 방법입니다.
- ApuCreateHeap을 사용하여 타이틀이 필요로 하는 모든 컨텍스트와 사용할 모든 알림을 담을 수 있을 만큼 큰 비 캐시 크기의 APU 힙을 만듭니다. 다른 ACP 또는 메서드 이전에 이 메서드가 호출되지 않으면 기본 힙이 할당됩니다.
- 필요한 알림 수와 크기가 같은 UINT32의 비 캐시 배열을 할당합니다: 즉, 오디오 프레임당 발행될 총 컨텍스트 업데이트 수. 한 번에 하나의 알림을 할당하는 것은 매우 비효율적이라는 점을 유의하세요.