IAcpHal::SubmitCommand Method

Submits a command to the ACP.

Syntax

public:
HRESULT SubmitCommand(
         ACP_COMMAND_TYPE command,
         UINT64 commandId,
         UINT32 audioFrame,
         const void *data,
         APU_ADDRESS notification
)  

Parameters

command
Type: 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 is a UINT64 to support pointers being passed 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 that audio frame has passed in which case the processing will start at the next audio frame. There are also two special values for this parameter:

• ACP_SUBMIT_PROCESS_COMMAND_ASAP Instructs the ACP to process the command as soon as possible (on the current audio frame if possible).
• ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAME Instructs 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 high voice count graphs to drop voices.

*data
Type: void 

[in, optional] Optional data associated with the command. Most commands require a data structure.

notification
Type: APU_ADDRESS 

[in, optional] 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 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 see if the command completed.

Return value

Type: HRESULT 

If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values shown in the following table.

Return codes

Remarks

This is the only API that allows a title to communicate with the ACP, SHAPE and XMA.

The lifetime for data submitted using this SubmitCommand method is variable. The pointer to the structure passed as input is only referenced during the API call, which 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 that needs to be copied internally. If the lifetime management of the additional command data is a concern an application can register for command completed messages, so receiving a message exactly when the additional data in the command is no longer being referenced.

If a title submits one or more commands with either the ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAME flag set, or with a specific audio frame number, then all of these commands will be processed at the beginning of the specified audio frame before any other processing is performed.

Note that all ACP commands are asynchronous on the main CPU, a call to IAcpHal::SubmitCommand will not block processing.

If a title wants to use notifications, the most efficient method is:

1. Create an APU heap (using ApuCreateHeap) where the non-cached size is large enough to hold all of the contexts the title needs as well as all of the notifications the title will use. This must be called before any other ACP or APU methods, otherwise a default heap will be allocated.
2. Allocate a non-cached array of UINT32s equal in size to the number of notifications that are needed (that is, the total number of context updates that will be issued per audio frame). Note that it is very inefficient to allocate the notifications one at a time.

Requirements

Header: Declared in acphal.h.

Library: Use acphal.lib.