IAcpHal::SubmitCommand
Submits a command to the ACP.Syntax
Parameters
commandType: ACP_COMMAND_TYPE The command. Refer to the ACP_COMMAND_TYPE enumeration. commandId
Type: UINT64 Optional, arbitrary identifier for the command. This ID will be returned with specific messages. It’s a UINT64 to support passing a pointer as the command ID. audioFrame
Type: UINT32 If an audio frame number is specified, the command will be processed at the beginning of that audio frame unless it has passed, in which case processing will start at the next audio frame. There are also two special values for this parameter:
ACP_SUBMIT_PROCESS_COMMAND_ASAPinstructs the ACP to process the command as soon as possible—on the current audio frame, if possible.ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAMEinstructs the ACP to process the command at the beginning of the next audio frame. If the command is to update a context, this context will be updated before the flowgraph processing starts. This does delay the start of flowgraph processing, which could cause graphs that have high voice counts to drop voices.
Type: void* Optional data associated with the command. Most commands require a data structure. notification _In_opt_
Type: APU_ADDRESS Optional physical address of a UINT32 element that will be set to a non-zero value when the command completes. The corresponding pointer to the virtual address should be declared as volatile. This is similar to a command-completed message, except that a message is not required to signal the completion of a command. When XAudio2 submits a command to the ACP, it uses this notification pointer when checking to determine whether the command completed.
Return value
Type: HRESULT If the method succeeds, it returns S_OK. If the method fails, it returns one of the following codes (a partial list):Remarks
This is the only API that allows a title to communicate with the Audio Control Processor (ACP), the Scalable Hardware Audio Processing Engine (SHAPE), and XMA. The lifetime for data submitted using thisSubmitCommand method is variable. The pointer to the structure passed as input is referenced only during the API call; this means a developer can use local variables safely. If the command contains a pointer to another block of data, that data is not copied and must remain present until the ACP has processed the command. This is done to minimize the amount of data to be copied internally. If the lifetime management of the additional command data is a concern, an application can register for command completed messages, to receive a message exactly when the additional data in the command is no longer being referenced.
If a title submits one or more commands with the ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAME flag set or with a specific audio frame number, then all these commands are processed at the beginning of the specified audio frame and before any other processing is performed.
Note that because all ACP commands are asynchronous on the main CPU, a call to IAcpHal::SubmitCommand won’t block processing.
The following is the most efficient method for a title to use notifications:
- Using ApuCreateHeap, create an APU heap where the non-cached size is large enough to hold all contexts the title needs and all notifications it will use. If this method is not called before any other ACP or method, then a default heap will be allocated.
- Allocate a non-cached array of UINT32s that is equal in size to the number of notifications needed: that is, the total number of context updates that will be issued per audio frame. Note that it’s very inefficient to allocate one notification at a time.