> ## 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 Envia um comando para a fila de hardware de um determinado fluxo XDSP. Essa API é semelhante a XDspSubmitCommand, que envia um comando ao hardware, exceto que recebe um parâmetro adicional, envelopeBuffer, que contém um valor de ganho para cada bloco do filtro de resposta ao impulso. Esses valores de ganho são aplicados à resposta ao impulso durante a convolução.\ Quando o uso de um envelope for desejado, essa API deverá ser chamada com um ponteiro válido para o buffer de envelope. É responsabilidade do chamador garantir que o buffer de envelope permaneça válido até que não seja mais necessário. Para parar de usar o envelope, deve-se usar XDspSubmitCommand ou XDspSubmitCommandWithEnvelope com nullptr para envelopeBuffer. Essa API só deve ser usada para um fluxo ativado para XDspProcessType::Convolution. ## Sintaxe ```cpp theme={null} HRESULT XDspSubmitCommandWithEnvelope( XDspStreamHandle handle, XDspCommand* command, float* envelopeBuffer, uint32_t* commandSequence ) ``` ### Parâmetros *handle*   \_In\_\ Tipo: [XDspStreamHandle](/pt-BR/reference/audio/xdspaudio/handles/xdspstreamhandle) Um identificador de fluxo XDSP válido. *command*   \_In\_\ Tipo: [XDspCommand\*](/pt-BR/reference/audio/xdspaudio/structs/xdspcommand) Ponteiro para uma estrutura [XDspCommand](/pt-BR/reference/audio/xdspaudio/structs/xdspcommand). *envelopeBuffer*   \_In\_\ Tipo: float\* Ponteiro para os valores de ganho de cada bloco do filtro de resposta ao impulso a serem aplicados durante a convolução.\ Esse buffer deve fazer parte da memória registrada por [XDspConnect](/pt-BR/reference/audio/xdspaudio/functions/xdspconnect) ou [XDspConnectWithMaximumStreamLimit](/pt-BR/reference/audio/xdspaudio/functions/xdspconnectwithmaximumstreamlimit) e deve estar alinhado em 16 bytes. Esse buffer é usado pelo hardware e não pode ser modificado nem liberado até que todos os comandos que o utilizam sejam concluídos e as respostas tenham sido coletadas. A contagem de valores de ganho no buffer de envelope deve ser pelo menos o número de blocos no filtro de resposta ao impulso e é calculada da seguinte forma.\ *uint32\_t IRLengthInComplexValues = XDspActivationParameters::impulseResponseLengthInFloats/2;*\ *uint32\_t IRLengthInBlocks = IRLengthInComplexValues/ XDspActivationParameters::blockFrameCount;*\ *uint32\_t envelopeSize = ((IRLengthInBlocks \* sizeof(float) + 15) & \~(0xF)) / sizeof(float);* Esse buffer segue o tamanho da resposta ao impulso. Para uma resposta ao impulso estéreo, os valores de ganho de todo o canal esquerdo são seguidos pelos valores de ganho de todo o canal direito, da mesma forma que a resposta ao impulso do canal esquerdo é seguida pela resposta ao impulso do canal direito. Para uma resposta ao impulso mono, os mesmos valores de ganho são aplicados aos canais esquerdo e direito de um sinal de entrada estéreo. O tamanho mínimo desse buffer deve ser de 8 valores float no caso de um filtro de resposta ao impulso mono e de 16 valores float no caso de um filtro de resposta ao impulso estéreo. *commandSequence*   \_Out\_\ Tipo: uint32\_t\* Ponteiro para `uint32_t` para retornar um valor de sequência de comando. Confira a seção **Comentários** para obter detalhes adicionais. ### Valor retornado Tipo: HRESULT Se o método for bem-sucedido, ele retornará S\_OK. Se o método falhar, ele retornará o seguinte código (lista parcial): | Código de retorno | Descrição | | - | - | | E\_INVALIDARG | Um ou mais argumentos são inválidos. | | XDSP\_E\_QUEUE\_FULL | Essa chamada retornará XDSP\_E\_QUEUE\_FULL se o fluxo e o servidor de hardware atingirem a capacidade máxima de processamento. Aguarde o hardware processar os comandos antes de enviar mais comandos. | | XDSP\_E\_DEVICE\_FATAL\_ERROR | Se o servidor de hardware estiver em um estado inválido, **XDspSubmitCommandWithEnvelope** retornará o código de erro XDSP\_E\_DEVICE\_FATAL\_ERROR. | ## Comentários Essa chamada será rápida, pois não alocará recursos nem processará dados; ela apenas envia o comando ao servidor de hardware. O processo de convolução tem *'n'* estágios, e o envelopamento pode ser alternado, ativado/desativado somente no primeiro estágio. Isso significa que o efeito de envelopamento pode não ser imediato e pode ser atrasado por alguns envios. Para desabilitar os parâmetros de envelope, deve-se chamar **XDspSubmitCommand** ou **XDspSubmitCommandWithEnvelope** com um envelopeBuffer nulo. Essa chamada também recebe um ponteiro para `uint32_t` para retornar um valor de sequência de comando, *commandSequence*, para rastrear quando o resultado do comando estará pronto posteriormente. Esse número representa o total de comandos que foram enviados com êxito desde que a sessão foi iniciada e depois que [XDspActivate](/pt-BR/reference/audio/xdspaudio/functions/xdspactivate) foi chamado. Esse número será um para o primeiro comando e é incrementado em um para cada chamada bem-sucedida de **XDspSubmitCommandWithEnvelope** ou [XDspSubmitCommand](/pt-BR/reference/audio/xdspaudio/functions/xdspsubmitcommand) depois disso. Se o servidor de hardware estiver em um estado inválido, **XDspSubmitCommandWithEnvelope** retornará o código de erro XDSP\_E\_DEVICE\_FATAL\_ERROR. Nesse ponto, nenhum outro comando poderá ser enviado para o fluxo XDSP que está em estado de falha. O [XDspStatus](/pt-BR/reference/audio/xdspaudio/structs/xdspstatus) do fluxo também indicará o mesmo erro. O fluxo XDSP afetado deve aguardar até que todos os comandos enviados sejam processados pelo hardware, verificando o [XDspStatus](/pt-BR/reference/audio/xdspaudio/structs/xdspstatus), e deve ser desativado usando [XDspDeactivate](/pt-BR/reference/audio/xdspaudio/functions/xdspdeactivate) quando todos os comandos forem processados. Outros fluxos XDSP não serão afetados, e o hardware continuará a processar os comandos deles. ## Requisitos **Cabeçalho:** XDspAudio.h **Biblioteca:** Chad.lib **Plataformas compatíveis:** XBOX Series X|S ## Documentação conceitual * [Visão geral do envelopamento do XDSP](/pt-BR/build/console-features/audio/overviews/xdsp-overview-enveloping) * [Visão geral de uma convolução de fluxo único com envelope usando a API do XDSP](/pt-BR/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope) * [Visão geral do XDSP](/pt-BR/build/console-features/audio/overviews/xdsp-overview) ## Confira também [XDSP](/pt-BR/reference/audio/xdspaudio/xdspaudio_members)\ [XdspSubmitCommand](/pt-BR/reference/audio/xdspaudio/functions/xdspsubmitcommand)\ [Erros do XDSP](/pt-BR/reference/audio/xdspaudio/enums/xdsperrors)\ [Visão geral de uma convolução de fluxo único usando a API do XDSP](/pt-BR/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution)\ [Visão geral de uma convolução de fluxo único com envelope usando a API do XDSP](/pt-BR/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope) [Visão geral de uma FFT/IFFT de fluxo único usando a API do XDSP](/pt-BR/build/console-features/audio/overviews/xdsp-overview-single-stream-fft-ifft) ## Related topics - [XDspSubmitCommandWithEnvelope](/reference/audio/xdspaudio/functions/xdspsubmitcommandwithenvelope.md) - [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)