> ## 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. # XDspSubmitCommandWithEnvelope > XDspSubmitCommandWithEnvelope # 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 ```cpp theme={null} HRESULT XDspSubmitCommandWithEnvelope( XDspStreamHandle handle, XDspCommand* command, float* envelopeBuffer, uint32_t* commandSequence ) ``` ### Parameters *handle*   \_In\_\ Type: [XDspStreamHandle](/reference/audio/xdspaudio/handles/xdspstreamhandle) A valid XDSP stream handle. *command*   \_In\_\ Type: [XDspCommand\*](/reference/audio/xdspaudio/structs/xdspcommand) Pointer to a [XDspCommand](/reference/audio/xdspaudio/structs/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](/reference/audio/xdspaudio/functions/xdspconnect) or [XDspConnectWithMaximumStreamLimit](/reference/audio/xdspaudio/functions/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): | Return code | Description | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | E\_INVALIDARG | One or more of the arguments are invalid. | | XDSP\_E\_QUEUE\_FULL | This call will return XDSP\_E\_QUEUE\_FULL if the stream and hardware server reached max processing capacity. Wait for the hardware to process the commands before submitting more commands. | | XDSP\_E\_DEVICE\_FATAL\_ERROR | If the hardware server is in a bad state, **XDspSubmitCommandWithEnvelope** will return XDSP\_E\_DEVICE\_FATAL\_ERROR error code. | ## 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 to `uint32_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](/reference/audio/xdspaudio/functions/xdspactivate) was called. This number will be one for the first command and is incremented by one for each successful **XDspSubmitCommandWithEnvelope** or [XDspSubmitCommand](/reference/audio/xdspaudio/functions/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](/reference/audio/xdspaudio/structs/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](/reference/audio/xdspaudio/structs/xdspstatus) and it should be deactivated using [XDspDeactivate](/reference/audio/xdspaudio/functions/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|S ## Conceptual documentation * [Overview of XDSP Enveloping](/build/console-features/audio/overviews/xdsp-overview-enveloping) * [Overview of a single stream Convolution with Envelope using the XDSP API](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope) * [XDSP overview](/build/console-features/audio/overviews/xdsp-overview) ## See also [XDSP](/reference/audio/xdspaudio/xdspaudio_members)\ [XdspSubmitCommand](/reference/audio/xdspaudio/functions/xdspsubmitcommand)\ [XDSP Errors](/reference/audio/xdspaudio/enums/xdsperrors)\ [Overview of a single stream Convolution using the XDSP API](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution)\ [Overview of a single stream Convolution with Envelope using the XDSP API](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope) [Overview of a single stream FFT/IFFT using the XDSP API](/build/console-features/audio/overviews/xdsp-overview-single-stream-fft-ifft) ## Related topics - [XDspSubmitCommand](/reference/audio/xdspaudio/functions/xdspsubmitcommand.md) - [Single-stream convolution with envelope using the XDSP API](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope.md) - [XDSP overview](/build/console-features/audio/overviews/xdsp-overview.md) - [XDSP Enveloping Overview](/build/console-features/audio/overviews/xdsp-overview-enveloping.md) - [XDSP audio](/reference/audio/xdspaudio/xdspaudio_members.md)