> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IAcpHal::SubmitCommand

> IAcpHal::SubmitCommand

# IAcpHal::SubmitCommand

ACP에 명령을 제출합니다.

## 구문

```cpp theme={null}
HRESULT SubmitCommand(  
         ACP_COMMAND_TYPE command,  
         UINT64 commandId,  
         UINT32 audioFrame,  
         const void* data= nullptr,  
         APU_ADDRESS notification= 0  
)  
```

### 매개 변수

*command*   \
형식: [ACP\_COMMAND\_TYPE](/reference/audio/acphal/enums/acp_command_type)

명령입니다. [ACP\_COMMAND\_TYPE](/reference/audio/acphal/enums/acp_command_type) 열거형을 참조하세요.

*commandId*   \
형식: UINT64

명령에 대한 선택적, 임의의 식별자입니다. 이 ID는 특정 메시지와 함께 반환됩니다. 포인터를 명령 ID로 전달하는 것을 지원하기 위한 UINT64입니다.

*audioFrame*   \
형식: UINT32

오디오 프레임 번호가 지정되면, 이미 지나가지 않은 경우 해당 오디오 프레임 시작 시 명령이 처리됩니다. 지나간 경우에는 다음 오디오 프레임에서 처리가 시작됩니다. 이 매개 변수에는 두 가지 특수 값도 있습니다.

* `ACP_SUBMIT_PROCESS_COMMAND_ASAP`는 ACP에 명령을 가능한 한 빨리—가능하다면 현재 오디오 프레임에—처리하도록 지시합니다.
* `ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAME`은 ACP에 다음 오디오 프레임 시작 시 명령을 처리하도록 지시합니다. 명령이 컨텍스트를 업데이트하는 것이라면, 이 컨텍스트는 플로우그래프 처리가 시작되기 전에 업데이트됩니다. 이는 플로우그래프 처리의 시작을 지연시키며, 이는 음성 수가 많은 그래프가 음성을 삭제하게 될 수 있습니다.

*data*   \_In\_opt\_\
형식: void\*

명령과 관련된 선택적 데이터입니다. 대부분의 명령은 데이터 구조가 필요합니다.

*notification*   \_In\_opt\_\
형식: APU\_ADDRESS

명령이 완료될 때 0이 아닌 값으로 설정되는 UINT32 요소의 선택적 물리적 주소입니다. 가상 주소에 대한 해당 포인터는 **volatile**로 선언되어야 합니다. 이는 command-completed 메시지와 유사하지만, 명령의 완료를 알리기 위해 메시지가 필요하지 않다는 점이 다릅니다. XAudio2가 ACP에 명령을 제출할 때, 명령이 완료되었는지 확인할 때 이 알림 포인터를 사용합니다.

### 반환 값

형식: HRESULT

메서드가 성공하면 S\_OK를 반환합니다. 메서드가 실패하면 다음 코드 중 하나를 반환합니다(부분 목록):

| 반환 코드               | 설명                    |
| ------------------- | --------------------- |
| E\_INVALIDARG       | 하나 이상의 인수가 유효하지 않습니다. |
| ACP\_E\_QUEUE\_FULL | 명령 큐가 가득 찼습니다.        |

## 설명

이는 타이틀이 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`에 대한 호출은 처리를 차단하지 않습니다.

다음은 타이틀이 알림을 사용하기 위한 가장 효율적인 방법입니다.

1. [ApuCreateHeap](/reference/audio/apu/functions/apucreateheap)을 사용하여 타이틀이 필요로 하는 모든 컨텍스트와 사용할 모든 알림을 담을 수 있을 만큼 큰 비 캐시 크기의 APU 힙을 만듭니다. 다른 ACP 또는 메서드 이전에 이 메서드가 호출되지 않으면 기본 힙이 할당됩니다.

2. 필요한 알림 수와 크기가 같은 UINT32의 비 캐시 배열을 할당합니다: 즉, 오디오 프레임당 발행될 총 컨텍스트 업데이트 수. 한 번에 하나의 알림을 할당하는 것은 매우 비효율적이라는 점을 유의하세요.

## 요구 사항

**헤더:** acphal.h

**지원 플랫폼:** XBOX One 제품군 콘솔 및 XBOX Series 콘솔

## 관련 항목

[ACP\_COMMAND\_TYPE](/reference/audio/acphal/enums/acp_command_type)
[AcpHal](/reference/audio/acphal/acphal_members)


## Related topics

- [IAcpHal](/ko/reference/audio/acphal/interfaces/IAcpHal/iacphal.md)
- [SHAPE 오디오 플로우그래프 구성 모범 사례](/ko/build/console-features/audio/overviews/best-practices-audio-flowgraph-construction.md)
- [IAcpHal::Connect](/ko/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_connect.md)
- [ACP_COMMAND_TYPE](/ko/reference/audio/acphal/enums/acp_command_type.md)
- [ACP_COMMAND_UPDATE_CONTEXTS](/ko/reference/audio/acphal/structs/acp_command_update_contexts.md)