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

# GetFrameStatisticsX (XBOX One 系列)

> 擷取畫面的一組統計資料。

擷取畫面的一組統計資料。

## 語法

```cpp theme={null}
HRESULT GetFrameStatisticsX(
        D3D12XBOX_FRAME_PIPELINE_TOKEN Token,
        D3D12XBOX_FRAME_STATISTICS_TYPE TypeSet,
        UINT* pCount,
        D3D12XBOX_FRAME_STATISTICS* pStatistics)
```

### 參數

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

識別目標畫面的管線權杖。

*TypeSet*   \_In\_
類型：[D3D12XBOX\_FRAME\_STATISTICS\_TYPE](/zh-TW/reference/graphics/d3d12_x/enums/d3d12xbox_frame_statistics_type)

識別要擷取之統計資料的類型旗標組合。

*pCount*   \_Inout\_
類型：UINT\*

指向某個值的指標，該值指定 *pStatistics* 清單的大小 (以項目為單位)。傳回時，此值會更新為包含寫入清單的項目數目。

*pStatistics*   \_Out\_\
類型：[D3D12XBOX\_FRAME\_STATISTICS](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_frame_statistics)\*

指向畫面統計資料陣列中第一個元素的指標。傳回時，所查詢之指定類型的統計資料會寫入此陣列。

### 傳回值

類型：HRESULT

HRESULT 成功或錯誤碼。

如果有一或多組所要求類型的統計資料可用 (並在清單空間允許的情況下傳回)，則傳回 S\_OK。

如果所要求的統計資料都尚未可用，則傳回 S\_FALSE。

如果是未知的畫面管線權杖、無效的類型集合和無效的清單配置，則傳回 E\_INVALIDARG。

## 備註

雖然可以針對任何有效的畫面管線權杖查詢統計資料，但執行階段目前會保留最近 17 個畫面的歷程記錄限制。任何源自超過 17 個間隔之前的畫面都沒有可提供的統計資料，對其查詢統計資料會傳回 S\_FALSE。如果所要求類型的相關聯畫面事件尚未發生，因而無法取得統計資料，這些類型也不會傳回任何統計資料。(相關聯畫面事件的範例之一，是在畫面實際翻轉至顯示器之前，就指定 [D3D12XBOX\_FRAME\_STATISTICS\_TYPE\_DISPLAY](/zh-TW/reference/graphics/d3d12_x/enums/d3d12xbox_frame_statistics_type) 的查詢。)

統計資料查詢可能會針對所要求集合中包含的每個類型傳回多個項目。多個統計資料的範例包括：

* 當畫面出現在多個顯示平面上時的 [PRESENT](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_present_statistics)、[RENDER](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_render_statistics) 和 [DISPLAY](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_display_statistics)
* 當畫面期間發生多個 VBlank 事件時的 [FRAME\_EVENT](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_frame_event_statistics) [DISPLAY\_VBLANK](/zh-TW/reference/graphics/d3d12_x/enums/d3d12xbox_frame_event_type)
* 當代表畫面進行多次輸入查詢時的 [INPUT](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_input_statistics)

提供給 **GetFrameStatisticsX** 的統計資料陣列應據此調整大小。雖然可以使用此方法查詢可用的統計資料數目，但隨著畫面事件完成並產生其他統計資料，在後續呼叫時大小可能會改變。

所有參考時間的畫面統計資料都會以 CPU 時間戳記 (也就是 *QueryPerformanceCounter*) 的形式提供，即使是 GPU 執行的動作也一樣。這樣做是為了在統計資料中保持一致的時間表示方式，而且由於多種佇列類型可能各自維護獨立的時鐘，因此也能與命令佇列執行保持無關。您可以使用 [GetClockCalibration](https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-id3d12commandqueue-getclockcalibration)，以佇列為基礎將回報的 CPU 時間戳記轉換為對等的 GPU 時間戳記。

若要追蹤從畫面起點到顯示的管線延遲，應用程式會持續查詢統計資料。結果可作為意見反應機制，讓遊戲得知透過呼叫 [ScheduleFrameEventX](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12device/methods/id3d12device_scheduleframeeventx) 對排程的畫面開始時間所做的更新。目標是以適當方式排程起點時間，讓畫面完成轉譯並在時間上盡可能接近其顯示翻轉時呈現。理想情況下，畫面之間不應浪費任何時間。

1. 畫面的起點與遊戲台輸入查詢：[FRAME\_EVENT\_STATISTICS](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_frame_event_statistics)::SignalTime 和 [INPUT\_STATISTICS](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_input_statistics)::QueryTime
2. 對畫面交換資源的最後一次寫入，以及呈現這些資源的呼叫：[RENDER\_STATISTICS](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_render_statistics)::FrameCompleteTime 和 [PRESENT\_STATISTICS](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_present_statistics)::PresentCallTime
3. PresentX 呼叫以及將資源翻轉至顯示器：[PRESENT\_STATISTICS](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_present_statistics)::PresentCallTime 和 [DISPLAY\_STATISTICS](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_display_statistics)::FlipTime

唯一的管線延遲應該是應用程式在 [PresentX](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/methods/id3d12commandqueue_presentx) 呼叫與翻轉之間制定的邊界，以防範畫面持續時間突增，進而降低錯過目標 VBlank 的風險。

## 需求

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

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

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


## Related topics

- [Dynamic Power States (DPS)](/build/game-principles/sustainability/dynamic-power-states.md)
- [Estados de energía dinámicos (DPS)](/es/build/game-principles/sustainability/dynamic-power-states.md)
- [动态电源状态(DPS)](/zh-CN/build/game-principles/sustainability/dynamic-power-states.md)
- [GetShapeDmaNumFrames](/zh-CN/reference/audio/shapedmacontext/functions/getshapedmanumframes.md)
- [GetShapeDmaFramesAvailable](/zh-CN/reference/audio/shapedmacontext/functions/getshapedmaframesavailable.md)