> ## 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 用戶端執行個體,並配置處理所需的資源。全域限制為同時最多 8 個作用中的 XDSP 用戶端。

## 語法

```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](/zh-TW/reference/audio/xdspaudio/enums/xdspprocesstype),*aggregateImpulseResponseInSeconds* 必須設定為大於零的值,否則必須為零。所有 XDSP 用戶端的彙總脈衝回應全域限制為 128 秒。

*handle*   \_Outptr\_\
類型:[XDspClientHandle\*](/zh-TW/reference/audio/xdspaudio/handles/xdspclienthandle)

XDSP 用戶端的控制代碼,應用來透過 [XDspActivate](/zh-TW/reference/audio/xdspaudio/functions/xdspactivate) 啟用串流,以及透過 [XDspDisconnect](/zh-TW/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](/zh-TW/reference/audio/xdspaudio/functions/xdspconnect) 呼叫會導致 XDSP 超過支援的最大彙總脈衝回應長度,因此無效。 |

## 備註

如果呼叫成功,呼叫端可以使用 *baseBuffer* 透過 [XDspCommand](/zh-TW/reference/audio/xdspaudio/structs/xdspcommand) 參數來傳遞輸入資料及擷取串流的輸出資料。如果使用 Envelope,此緩衝區也應該納入用於儲存 Envelope 參數的緩衝區。如需 Envelope 的詳細資訊,請參閱[使用 XDSP API 的 Envelope 概觀](/zh-TW/build/console-features/audio/overviews/xdsp-overview-enveloping)。

必須先呼叫此函式,才能啟用 XDSP 串流,以註冊一個足以容納下列項目的大型記憶體區塊:做為輸入的多個完整音訊串流、將透過 [XDspActivate](/zh-TW/reference/audio/xdspaudio/functions/xdspactivate) 啟用之所有 XDSP 串流的多個輸出緩衝區,以及可能用於 [XDspProcessType::ForwardFourierTransform](/zh-TW/reference/audio/xdspaudio/enums/xdspprocesstype) 處理類型之 [XDspCommand](/zh-TW/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* 應取代為遊戲所使用的正確配置器識別碼。

由呼叫端負責分割及回收 *baseBuffer*,以容納多個串流的不同輸入串流和輸出緩衝區。*impulseResponse* 不需要來自此 *baseBuffer*,它可以來自呼叫端所配置的任何記憶體。

在呼叫 [XDspConnect](/zh-TW/reference/audio/xdspaudio/functions/xdspconnect) 之前,不應釋放 *baseBuffer* 所指向的記憶體。

傳遞給 [XDSP API](/zh-TW/reference/audio/xdspaudio/xdspaudio_members) 的所有記憶體指標都必須以 16 位元組對齊。

如果呼叫成功,將會傳回有效的 [XDspClientHandle](/zh-TW/reference/audio/xdspaudio/handles/xdspclienthandle),以便搭配 [XDspActivate](/zh-TW/reference/audio/xdspaudio/functions/xdspactivate) 和 [XDspDisconnect](/zh-TW/reference/audio/xdspaudio/functions/xdspdisconnect) 呼叫使用。

## 需求

**標頭:** XDspAudio.h

**程式庫:** Chad.lib

**支援的平台:** XBOX Series X|S

## 概念文件

* [XDSP Envelope 概觀](/zh-TW/build/console-features/audio/overviews/xdsp-overview-enveloping)
* [使用 XDSP API 進行含 Envelope 的單一串流 Convolution 的概觀](/zh-TW/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope)
* [使用 XDSP API 進行單一串流 Convolution 的概觀](/zh-TW/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution)
* [XDSP 概觀](/zh-TW/build/console-features/audio/overviews/xdsp-overview)

## 另請參閱

[XDSP](/zh-TW/reference/audio/xdspaudio/xdspaudio_members)\
[XDspConnectWithMaximumStreamLimit](/zh-TW/reference/audio/xdspaudio/functions/xdspconnectwithmaximumstreamlimit)\
[XDspDisconnect](/zh-TW/reference/audio/xdspaudio/functions/xdspdisconnect)\
[XDSP 錯誤](/zh-TW/reference/audio/xdspaudio/enums/xdsperrors)\
[使用 XDSP API 進行單一串流 Convolution 的概觀](/zh-TW/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution)\
[使用 XDSP API 進行單一串流 FFT/IFFT 的概觀](/zh-TW/build/console-features/audio/overviews/xdsp-overview-single-stream-fft-ifft)\
[使用 XDSP API 進行含 Envelope 的單一串流 Convolution 的概觀](/zh-TW/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope)


## Related topics

- [XDspConnect](/reference/audio/xdspaudio/functions/xdspconnect.md)
- [XDspConnectWithMaximumStreamLimit](/reference/audio/xdspaudio/functions/xdspconnectwithmaximumstreamlimit.md)
- [XDspDisconnect](/reference/audio/xdspaudio/functions/xdspdisconnect.md)
- [XDspCommand](/reference/audio/xdspaudio/structs/xdspcommand.md)
- [XDSP overview](/build/console-features/audio/overviews/xdsp-overview.md)