XDspSubmitCommandWithEnvelope
Submit one command to the hardware queue for a given XDSP stream. This API is similar to the XDspSubmitCommand where it submits one command to the hardware, except that it takes an additional parameter envelopeBuffer that contains a gain value for each block of the impulse response filter. These gain values are applied to the impulse response during convolution.When the use of an envelope is desired, this API should be called with a valid pointer to the envelope buffer. It is the caller’s responsibility to ensure that the envelope buffer remains valid until it is no longer needed. To stop using the envelope, either XDspSubmitCommand or XDspSubmitCommandWithEnvelope with a nullptr for the envelopeBuffer should be used. This API should only be used for a stream activated for XDspProcessType::Convolution.
Syntax
Parameters
handle _In_Type: XDspStreamHandle A valid XDSP stream handle. command _In_
Type: XDspCommand* Pointer to a XDspCommand structure. envelopeBuffer _In_
Type: float* Pointer to the gain values for each block of impulse response filter to be applied during the convolution.
This buffer must be part of the memory registered by XDspConnect or XDspConnectWithMaximumStreamLimit and should be 16 byte aligned. This buffer is used by the hardware and cannot be modified or freed until all the commands using this buffer are complete and responses have been picked up. The count of gain values in envelope buffer should be at least the number of blocks in the impulse response filter and is calculated as follows.
uint32_t IRLengthInComplexValues = XDspActivationParameters::impulseResponseLengthInFloats/2;
uint32_t IRLengthInBlocks = IRLengthInComplexValues/ XDspActivationParameters::blockFrameCount;
uint32_t envelopeSize = ((IRLengthInBlocks * sizeof(float) + 15) & ~(0xF)) / sizeof(float); This buffer follows the size of the impulse response. For stereo impulse response, the gain values for the entire left channel are followed by the gain values for the entire right channel in the same way as the left channel impulse response is followed by the right channel impulse response. For a mono impulse response, the same gain values are applied to both the left and right channels of a stereo input signal. The minimum size of this buffer should be 8 float values in case of a mono impulse response filter and 16 float values in case of a stereo impulse response filter. commandSequence _Out_
Type: uint32_t* Pointer to
uint32_t to return a command sequence value. See the Remarks section for additional details.
Return value
Type: HRESULT If the method succeeds, it returns S_OK. If the method fails, it returns the following code (partial list):Remarks
This call will be fast as it will not allocate resources or process data and just sends the command to the hardware server. The convolution process has ‘n’ stages and enveloping can be switched, turned on/off only in the first stage. This means that the enveloping effect may not be immediate and may be delayed by a few submissions. To disable the envelope parameters, XDspSubmitCommand or XDspSubmitCommandWithEnvelope with a null envelopeBuffer should be called. This call will also take a pointer touint32_t to return a command sequence value, commandSequence, to track when the command result is ready later. This number represents the total number of commands that have been submitted successfully since the session started and after XDspActivate was called. This number will be one for the first command and is incremented by one for each successful XDspSubmitCommandWithEnvelope or XDspSubmitCommand call after that.
If the hardware server is in a bad state, XDspSubmitCommandWithEnvelope will return XDSP_E_DEVICE_FATAL_ERROR error code. At this point, no more commands can be submitted for the XDSP stream that is in a failed state. XDspStatus for the stream will also indicate the same error. The affected XDSP stream should wait for all submitted commands to be processed by the hardware by checking the XDspStatus and it should be deactivated using XDspDeactivate once all the commands are processed. Other XDSP streams will not be affected and hardware will continue to process their commands.
Requirements
Header: XDspAudio.h Library: Chad.lib Supported platforms: XBOX Series X|SConceptual documentation
- Overview of XDSP Enveloping
- Overview of a single stream Convolution with Envelope using the XDSP API
- XDSP overview
See also
XDSPXdspSubmitCommand
XDSP Errors
Overview of a single stream Convolution using the XDSP API
Overview of a single stream Convolution with Envelope using the XDSP API Overview of a single stream FFT/IFFT using the XDSP API