> ## 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.

# XDspActivate

> XDspActivate

# XDspActivate

通过从池中获取空闲的处理资源来激活 XDSP 流。每个 XDSP 客户端最多允许激活 256 个流。

## 语法

```cpp theme={null}
HRESULT XDspActivate(  
         XDspClientHandle clientHandle,  
         XDspActivationParameters* params,  
         XDspStatus** status,  
         XDspStreamHandle* streamHandle  
)  
```

### 参数

*clientHandle*   \_In\_\
类型：[XDspClientHandle](/reference/audio/xdspaudio/handles/xdspclienthandle)

通过调用 XDspConnect 获取的有效 XDSP 客户端句柄。

*params*   \_In\_\
类型：[XDspActivationParameters\*](/reference/audio/xdspaudio/structs/xdspactivationparameters)

指向 [XDspActivationParameters](/reference/audio/xdspaudio/structs/xdspactivationparameters) 结构的指针。

*status*   \_Outptr\_\
类型：[XDspStatus\*\*](/reference/audio/xdspaudio/structs/xdspstatus)

指向 [XDspStatus](/reference/audio/xdspaudio/structs/xdspstatus) 结构的指针。有关其他详细信息，请参阅**备注**部分。

*streamHandle*   \_Outptr\_\
类型：[XDspStreamHandle\*](/reference/audio/xdspaudio/handles/xdspstreamhandle)

如果调用成功，则返回有效的 [XDspStreamHandle](/reference/audio/xdspaudio/handles/xdspstreamhandle)。有关其他详细信息，请参阅**备注**部分。

### 返回值

类型：HRESULT

如果方法成功，则返回 S\_OK。如果方法失败，则返回下列代码之一（部分列表）：

| 返回代码                                        | 说明                                                                                                                                                                         |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| E\_POINTER                                  | 无效指针。                                                                                                                                                                      |
| E\_INVALIDARG                               | 一个或多个参数无效。                                                                                                                                                                 |
| XDSP\_E\_NO\_DEVICE\_RESOURCES              | 没有可用的 XDSP 设备资源来处理你的请求。                                                                                                                                                    |
| XDSP\_E\_INVALID\_IMPULSE\_RESPONSE\_LENGTH | 提供的脉冲响应长度无效。如果 [impulseResponseLengthInFloats](/reference/audio/xdspaudio/structs/xdspactivationparameters) 小于 (`9 * blockSize * 2`) 或大于 16 秒 (`16 * 48000 * 2`)，则可能发生此错误。 |

## 备注

此调用速度较快，因为它从池中获取资源而不是重新分配资源。

调用方必须为要执行的 XDSP 流指定 [XDspProcessType](/reference/audio/xdspaudio/enums/xdspprocesstype)。XDSP 流的实例在其生命周期内只能处理一种类型的操作。若要执行两种或更多不同的处理类型，则必须实例化两个或多个 XDSP 流实例。

在 [XDspActivationParameters](/reference/audio/xdspaudio/structs/xdspactivationparameters) 结构中，调用方必须指定以下内容：

* 激活选项。
* 每条命令将处理的帧数，即输入和输出帧数。
* 流的通道数。仅支持单声道和立体声输入流。
* 对于 [XDspProcessType::Convolution](/reference/audio/xdspaudio/enums/xdspprocesstype) 处理类型，指定脉冲响应长度（以 float 为单位）。
* 对于 [XDspProcessType::Convolution](/reference/audio/xdspaudio/enums/xdspprocesstype) 处理类型，指定作为频域值的脉冲响应。

如果调用成功，将返回一个有效的 [XDspStreamHandle](/reference/audio/xdspaudio/handles/xdspstreamhandle)，用于该流的其他调用（[XDspSubmitCommand](/reference/audio/xdspaudio/functions/xdspsubmitcommand)、[XDspSubmitCommandWithEnvelope](/reference/audio/xdspaudio/functions/xdspsubmitcommandwithenvelope)、[XDspDeactivate](/reference/audio/xdspaudio/functions/xdspdeactivate)）。此外，如果此调用成功，还将返回一个指向 [XDspStatus](/reference/audio/xdspaudio/structs/xdspstatus) 的指针，可用于检查已提交命令的状态。

它可用于确定最近已处理的命令，以及已提交命令的结果是否可以被使用。
[XDspStatus](/reference/audio/xdspaudio/structs/xdspstatus) 还包含它所代表的 XDSP 流最近提交到硬件的命令的序号，以及第一个失败命令的序号。若为卷积处理，调用方可在此调用返回后释放脉冲响应内存。

## 要求

**头文件：** XDspAudio.h

**库：** Chad.lib

**支持的平台：** XBOX Series X|S

## 概念文档

* [使用 XDSP API 进行带包络的单流卷积概述](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope)
* [使用 XDSP API 进行单流卷积概述](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution)
* [XDSP 概述](/build/console-features/audio/overviews/xdsp-overview)

## 另请参阅

[XDSP](/reference/audio/xdspaudio/xdspaudio_members)\
[XDSP Errors](/reference/audio/xdspaudio/enums/xdsperrors)\
[使用 XDSP API 进行单流卷积概述](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution)\
[使用 XDSP API 进行单流 FFT/IFFT 概述](/build/console-features/audio/overviews/xdsp-overview-single-stream-fft-ifft)\
[使用 XDSP API 进行带包络的单流卷积概述](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope)


## Related topics

- [XDspDeactivate](/zh-CN/reference/audio/xdspaudio/functions/xdspdeactivate.md)
- [XDSP 概述](/zh-CN/build/console-features/audio/overviews/xdsp-overview.md)
- [使用 XDSP API 进行单流卷积概述](/zh-CN/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution.md)
- [使用 XDSP API 进行带包络的单流卷积](/zh-CN/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope.md)
- [XDSP audio](/zh-CN/reference/audio/xdspaudio/xdspaudio_members.md)