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

# XDspConnect

> XDspConnect

# XDspConnect

与硬件服务器建立连接，创建 XDSP 客户端实例，并分配处理所需的资源。同时活动的 XDSP 客户端全局上限为 8 个。

## 语法

```cpp theme={null}
HRESULT XDspConnect(  
         float* baseBuffer,  
         uint32_t baseBufferLength,  
         uint32_t aggregateImpulseResponseInSeconds,  
         XDspClientHandle* handle  
)  
```

### 参数

*baseBuffer*   \_In\_\
类型：float\*

由 XDSP 调用方分配的连续缓冲区，用于传递输入数据和获取输出数据。有关其他详细信息，请参阅下文的**备注**部分。

*baseBufferLength*   \_In\_\
类型：uint32\_t

*baseBuffer* 的长度（以字节为单位）。该长度至少为 64 KB，最多不能超过 500 MB。

*aggregateImpulseResponseInSeconds*   \_In\_\
类型：uint32\_t

表示将同时在此客户端上激活的所有单个脉冲响应的总时长。对于 [XDspProcessType::Convolution](/reference/audio/xdspaudio/enums/xdspprocesstype)，*aggregateImpulseResponseInSeconds* 必须设置为大于零的值；否则必须为零。所有 XDSP 客户端的总脉冲响应时长全局上限为 128 秒。

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

XDSP 客户端的句柄，用于通过 [XDspActivate](/reference/audio/xdspaudio/functions/xdspactivate) 激活流，以及通过 [XDspDisconnect](/reference/audio/xdspaudio/functions/xdspdisconnect) 将客户端从硬件服务器断开连接。所有 XDSPClientHandle 在任何给定时刻最多可有 256 个流处于活动状态。

### 返回值

类型：HRESULT

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

| 返回代码                                                 | 说明                                                                                                    |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| E\_INVALIDARG                                        | 一个或多个参数无效。                                                                                            |
| E\_OUTOFMEMORY                                       | 内存分配失败。                                                                                               |
| XDSP\_E\_MAX\_CLIENTS\_EXCEEDED                      | 已创建的 XDspClient 数量达到最大值。                                                                              |
| XDSP\_E\_MAX\_AGGREGATE\_IMPULSE\_RESPONSE\_EXCEEDED | 当前的 [XDspConnect](/reference/audio/xdspaudio/functions/xdspconnect) 调用将导致 XDSP 超出所支持的聚合脉冲响应长度上限，因此无效。 |

## 备注

如果调用成功，调用方可以通过 [XDspCommand](/reference/audio/xdspaudio/structs/xdspcommand) 参数使用 *baseBuffer* 传递流的输入数据和获取输出数据。如果使用包络，此缓冲区还应包含用于存储包络参数的空间。有关包络的详细信息，请参阅[使用 XDSP API 进行包络处理概述](/build/console-features/audio/overviews/xdsp-overview-enveloping)。

在激活 XDSP 流之前，必须调用此函数以注册一大块内存，该内存足够容纳：作为输入的多个完整音频流、通过 [XDspActivate](/reference/audio/xdspaudio/functions/xdspactivate) 激活的所有 XDSP 流的多个输出缓冲区，以及在 [XDspProcessType::ForwardFourierTransform](/reference/audio/xdspaudio/enums/xdspprocesstype) 处理类型的 [XDspCommand](/reference/audio/xdspaudio/structs/xdspcommand) 中可能使用的多个块乘数缓冲区。请注意上文所述的此缓冲区的大小上下限要求。如果此调用成功，所有 XDSP 流都可以访问此内存块的任何部分。

此内存应通过 XMemAlloc() 分配，属性为：**XALLOC\_MEMTYPE\_PHYSICAL\_CACHEABLE**、**XALLOC\_PAGESIZE\_64KB**、**XALLOC\_ALIGNMENT\_64K**

这些属性应使用 **MAKE\_XALLOC\_ATTRIBUTES()** 进行设置。

示例如下：

```cpp theme={null}
static const ULONGLONG XMemAllocAttributes = MAKE_XALLOC_ATTRIBUTES(allocatorId,
   0,
   XALLOC_MEMTYPE_PHYSICAL_CACHEABLE,
   XALLOC_PAGESIZE_64KB,
   XALLOC_ALIGNMENT_64K,
   FALSE);
```

上述示例中的 *allocatorId* 应替换为标题使用的正确分配器 ID。

调用方需要自行分区并复用 *baseBuffer*，以容纳不同的输入流和多个流的输出缓冲区。*impulseResponse* 不必来自 *baseBuffer*，也可以来自调用方分配的任何内存。

在调用 [XDspConnect](/reference/audio/xdspaudio/functions/xdspconnect) 之前，不应释放 *baseBuffer* 所指向的内存。

传递给 [XDSP API](/reference/audio/xdspaudio/xdspaudio_members) 的所有内存指针都必须为 16 字节对齐。

如果调用成功，将返回一个有效的 [XDspClientHandle](/reference/audio/xdspaudio/handles/xdspclienthandle)，用于 [XDspActivate](/reference/audio/xdspaudio/functions/xdspactivate) 和 [XDspDisconnect](/reference/audio/xdspaudio/functions/xdspdisconnect) 调用。

## 要求

**头文件：** XDspAudio.h

**库：** Chad.lib

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

## 概念文档

* [XDSP 包络处理概述](/build/console-features/audio/overviews/xdsp-overview-enveloping)
* [使用 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)\
[XDspConnectWithMaximumStreamLimit](/reference/audio/xdspaudio/functions/xdspconnectwithmaximumstreamlimit)\
[XDspDisconnect](/reference/audio/xdspaudio/functions/xdspdisconnect)\
[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

- [XDspConnectWithMaximumStreamLimit](/zh-CN/reference/audio/xdspaudio/functions/xdspconnectwithmaximumstreamlimit.md)
- [XDspDisconnect](/zh-CN/reference/audio/xdspaudio/functions/xdspdisconnect.md)
- [XDspCommand](/zh-CN/reference/audio/xdspaudio/structs/xdspcommand.md)
- [XDspActivationParameters](/zh-CN/reference/audio/xdspaudio/structs/xdspactivationparameters.md)
- [XDSP 包络概述](/zh-CN/build/console-features/audio/overviews/xdsp-overview-enveloping.md)