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

# WaitFrameEventX (XBOX One 系列)

> 等候已排程的畫面格事件收到訊號。

等候已排程的畫面格事件收到訊號。

## 語法

```cpp theme={null}
HRESULT WaitFrameEventX(
        D3D12XBOX_FRAME_EVENT_TYPE Type,
        UINT TimeOutInMs,
        D3D12XBOX_WAIT_FRAME_OBJECT_LIST* pAncillaryWaitList,
        D3D12XBOX_WAIT_FRAME_EVENT_FLAGS Flags,
        D3D12XBOX_FRAME_PIPELINE_TOKEN* pToken)
```

### 參數

*Type*   \_In\_\
類型：[D3D12XBOX\_FRAME\_EVENT\_TYPE](/zh-TW/reference/graphics/d3d12_x/enums/d3d12xbox_frame_event_type)

要等候的事件類型。

*TimeOutInMs*   \_In\_\
類型：UINT

在傳回之前等候事件收到訊號的時間量 (以毫秒為單位)。可以使用 *D3D12XBOX\_WAIT\_FRAME\_EVENT\_INFINITE* 值來等候而不會逾時。

*pAncillaryWaitList*   \_In\_opt\_\
類型：[D3D12XBOX\_WAIT\_FRAME\_OBJECT\_LIST](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_wait_frame_object_list)\*

選擇性清單，最多包含 63 個輔助事件，作為等候的條件。

*Flags*   \_In\_\
類型：[D3D12XBOX\_WAIT\_FRAME\_EVENT\_FLAGS](/zh-TW/reference/graphics/d3d12_x/enums/d3d12xbox_wait_frame_event_flags)

用來對等候提供額外控制的旗標。如需詳細資訊，請參閱＜備註＞。

*pToken*   \_Inout\_\
類型：[D3D12XBOX\_FRAME\_PIPELINE\_TOKEN](/zh-TW/reference/graphics/d3d12_x/enums/d3d12xbox_frame_pipeline_token)\*

觸發事件之畫面格的識別碼。

### 傳回值

類型：HRESULT

HRESULT 成功或錯誤碼。

如果其中一個或所有指定的事件已收到訊號，因而滿足等候，則傳回 S\_OK。

如果 *TimeOutInMs* 已經過，但事件未依等候條件收到訊號，則傳回 S\_FALSE。

如果使用有限逾時且 GPU 停止回應，導致無法處理新畫面格滿足 [D3D12XBOX\_FRAME\_EVENT\_ORIGIN](/zh-TW/reference/graphics/d3d12_x/enums/d3d12xbox_frame_event_type) 等候所依賴的先前 [PresentX](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/methods/id3d12commandqueue_presentx)，則傳回 D3DERR\_DEVICEREMOVED。如果另一個執行緒在等候期間呼叫 [SuspendX](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/methods/id3d12commandqueue_suspendx) 來暫停應用程式，也會傳回 D3DERR\_DEVICEREMOVED。

若事件類型、等候清單和旗標值無效，或尚未排程指定類型的畫面格事件，則傳回 E\_INVALIDARG。

## 備註

* 必須使用 [ScheduleFrameEventX](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12device/methods/id3d12device_scheduleframeeventx) 方法來排程要等候的事件。

* *WaitFrameEventX* 會等候，直到指定類型的事件 (或選擇性地，其中一個或所有指定的輔助事件) 收到訊號，或直到經過 *TimeOutInMs* 的持續時間為止。這就是 *WaitFrameEventX* 可用來封鎖或輪詢畫面格事件訊號的方式。

* 如果提供輔助等候事件，則根據預設，當主要畫面格事件或任何輔助事件收到訊號時，等候即會滿足。傳回時，*pAncillaryWaitList* 的 *pSignaledObjectIndex* 成員所參考的記憶體，在等候逾時時會設定為 *D3D12XBOX\_SIGNALED\_OBJECT\_INDEX\_NONE*，在畫面格事件本身收到訊號時會設定為 *D3D12XBOX\_SIGNALED\_OBJECT\_INDEX\_PRIMARY*，否則會設定為清單中第一個收到訊號之輔助事件的索引值。

  應使用手動重設的輔助事件來判斷在滿足等候時是否有多個事件收到訊號；傳回時，可以對每個輔助事件呼叫 WaitForSingleObject (逾時為 0) 來測試是否處於已發出訊號狀態。如有需要，可以加入 [D3D12XBOX\_WAIT\_FRAME\_EVENT\_FLAG\_WAIT\_ALL](/zh-TW/reference/graphics/d3d12_x/enums/d3d12xbox_wait_frame_event_flags) 旗標，將方法的等候條件變更為只有在所有物件都收到訊號時才滿足。

* [D3D12XBOX\_FRAME\_PIPELINE\_TOKEN](/zh-TW/reference/graphics/d3d12_x/enums/d3d12xbox_frame_pipeline_token) 用來在系統中識別畫面格。當起點事件收到訊號且對其進行的等候未逾時就傳回時，將會產生新的畫面格管線權杖值。

  以 [D3D12XBOX\_FRAME\_EVENT\_ORIGIN](/zh-TW/reference/graphics/d3d12_x/enums/d3d12xbox_frame_event_type) 呼叫 *WaitFrameEventX* 時，指標應設定為 *D3D12XBOX\_FRAME\_PIPELINE\_TOKEN\_NULL*，傳回時它將包含產生的權杖。接著，此權杖可用來將畫面格與相關的管線事件和資料 (例如輸入樣本、轉譯標記和統計資料) 建立關聯。[PresentX](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/methods/id3d12commandqueue_presentx) 甚至需要使用它，以便將提供顯示的資源與產生這些資源的畫面格相互識別。對於起點以外的事件類型，呼叫者必須提供先前產生的畫面格權杖，以便將所執行的等候與執行它的畫面格建立關聯。

* 起點事件等候是主要的節流機制，可防止 CPU 命令清單的錄製過度領先 GPU 清單的執行，並最終領先畫面格顯示。一般而言，只有在過去的畫面格已完成並抵達顯示器，或其期限 (由 [SetFrameIntervalX](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12device/methods/id3d12device_setframeintervalx) 建立) 尚未到達時，畫面格起點才會收到訊號 (並在等候傳回時產生新的畫面格權杖)。

  提供了一項例外，允許應用程式在畫面格的起點訊號發出之前，提早開始處理畫面格，並在等候逾時時產生並傳回其管線權杖。這可以透過加入 [D3D12XBOX\_WAIT\_FRAME\_EVENT\_FLAG\_PROCESS\_TOKEN\_ON\_TIMEOUT](/zh-TW/reference/graphics/d3d12_x/enums/d3d12xbox_wait_frame_event_flags) 旗標來達成，但可能會產生額外的管線延遲，其長度等於等候傳回與後續起點訊號之間的差距 (如果在等候之後查詢輸入)。不過，即使畫面格可以在到達其起點時間之前開始，它也可能不會被處理以進行呈現。嘗試在提早呼叫 [PresentX](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/methods/id3d12commandqueue_presentx) 時使用過早產生的管線權杖，將導致該方法封鎖，直到發出該畫面格的起點訊號為止。

## 需求

**標頭:** d3d12\_x.h

**程式庫:** d3d12\_x.lib

**支援的平台:** XBOX One 系列


## Related topics

- [Wait](/zh-CN/reference/graphics/d3d12/interfaces/id3d12commandqueue/methods/id3d12commandqueue_wait_public.md)
- [Game streaming latency compensation deep dive](/build/core-features/common/game-streaming/game-streaming-latency-compensation-deep-dive.md)
- [D3D12_MULTIPLE_FENCE_WAIT_FLAGS](/zh-CN/reference/graphics/d3d12/enums/d3d12_multiple_fence_wait_flags_public.md)
- [IGameInputDispatcher::OpenWaitHandle](/zh-CN/reference/input/gameinput/interfaces/IGameInputDispatcher/methods/igameinputdispatcher_openwaithandle.md)
- [NDA 主題目錄 - Microsoft Learn 線上連結](/zh-TW/nda/nda-topic-directory.md)