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

# PresentX (XBOX One 系列)

> 呈現一組資源以供顯示。

呈現一組資源以供顯示。

## 語法

```cpp theme={null}
HRESULT PresentX(
        UINT PlaneCount,
        const D3D12XBOX_PRESENT_PLANE_PARAMETERS* pPlaneParameters,
        const D3D12XBOX_PRESENT_PARAMETERS* pPresentParameters)
```

### 參數

*PlaneCount*   \_In\_range\_(1, D3D12XBOX\_PRESENT\_PLANES\_MAX)
類型：UINT

要呈現的平面數目。多個平面可以由一個背景平面加上重疊層，以及/或者成對的畫面標準與高動態範圍 (HDR) 合成所組成。使用平面數目 0 可將顯示切換為 null，這會將顯示色彩設定為黑色。XBOX Series X|S 允許混合大於 1920 x 1080 的平面，而且兩者都可以是高動態範圍。

*pPlaneParameters*   \_In\_reads\_(PlaneCount)
類型：const [D3D12XBOX\_PRESENT\_PLANE\_PARAMETERS](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_present_plane_parameters)\*

指向參數陣列第一個元素的指標，這些參數用於控制每個所提供平面的呈現方式。請依 Z 順序 (由後至前) 排列陣列。先依最接近程度設定元素，再依色彩空間 (HDR-SDR) 配對設定。

*pPresentParameters*   \_In\_opt\_
類型：const [D3D12XBOX\_PRESENT\_PARAMETERS](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_present_parameters)\*

選擇性。指向一組用於控制呈現之參數的指標。

### 傳回值

類型：HRESULT

HRESULT 成功或錯誤碼。

如果指定的交換資源已成功排入佇列等待呈現，則傳回 S\_OK。

如果指定了 [D3D12XBOX\_PRESENT\_FLAG\_DO\_NOT\_WAIT](/zh-TW/reference/graphics/d3d12_x/enums/d3d12xbox_present_flags)，且 *pPlaneParameters* 中一或多個指定的 *ppResources* 目前正在顯示或已排入佇列等待呈現，則傳回 ERROR\_WAS\_STILL\_DRAWING。

如果參數無效或呈現的合成無效，則傳回 E\_INVALIDARG。

如果 GPU 在呼叫 **PresentX** 之前沒有回應，則傳回 D3DERR\_DEVICEREMOVED

## 備註

*pPlaneParameters* 內所含 *ppResources* 陣列中的資源，可作為舊版交換鏈結的替代品，且建立時必須支援翻轉至顯示器。若要啟用翻轉支援，請呼叫 [CreateCommittedResource](https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-id3d12device-createcommittedresource)，並在 *pDesc* 參數中設定 **D3D12\_HEAP\_FLAG\_ALLOW\_DISPLAY** 旗標 ([D3D12\_HEAP\_FLAGS](/zh-TW/reference/graphics/d3d12_x/enums/d3d12_heap_flags))。目前尚不允許使用沒有基礎堆積所建立的資源。

交換鏈結已演變成由使用者管理的可顯示資源集合；不過，由於 TLB 的限制，同一時間只能具現化有限數量的此類資源。如果可顯示資源目前正由顯示器掃描輸出或已排入佇列等待呈現，就無法將其釋放到解除配置的程度。您必須先將顯示翻轉至另一組資源或 null (如果應用程式已關閉)。若要執行 null 呈現，請呼叫 **PresentX(0, nullptr, nullptr);**。

由於 *ppResources* 取代了交換鏈結，交換資源的色彩空間現在會宣告為 *pPlaneParameters* 中所含平面參數的一部分，而 GameDVR 的自動色調對應則是透過 [D3D12XBOX\_RESOURCE\_FLAG\_ALLOW\_AUTOMATIC\_GAMEDVR\_TONE\_MAP](/zh-TW/reference/graphics/d3d12_x/enums/d3d12_resource_flags) 資源建立旗標為資源選取，但會產生額外的堆積儲存空間及每次 Present 的 GPU 成本。XBOX Series X|S 新增了兩種交換資源格式：**DXGI\_FORMAT\_R9G9B9E5\_SHAREDEXP** 與 **DXGI\_FORMAT\_A8\_UNORM**。**DXGI\_FORMAT\_A8\_UNORM** 交換資源應一律與 **DXGI\_FORMAT\_R9G9B9E5\_SHAREDEXP** 交換資源配對。當需要 Alpha 通道時 (例如混合多個平面時)，它會作為 RGBE 資源的 Alpha 通道。XBOX Series X|S 也允許透過 [D3D12XBOX\_RESOURCE\_FLAG\_ALLOW\_DCC](/zh-TW/reference/graphics/d3d12_x/enums/d3d12_resource_flags) 資源建立旗標，對交換資源進行差異色彩壓縮 (Delta Color Compression)。

如果未提供用於產生資源 (或至少用於開始建構資源) 之畫面的識別資訊，資源可能不會被呈現。這是將呈現統計資料與個別畫面建立關聯、從起點測量完整畫面管線延遲，以及對顯示進行輸入取樣所必需的。識別是透過 *pPlaneParameters* 參數的 *Token* 成員來執行，由於各平面的呈現頻率可能不同而具有不同的基礎畫面，因此可以為每個合成平面 (背景與重疊) 指定不同的 [D3D12XBOX\_FRAME\_PIPELINE\_TOKEN](/zh-TW/reference/graphics/d3d12_x/enums/d3d12xbox_frame_pipeline_token) 值。對於全部來自同一畫面的平面，應重複包含管線權杖。

畫面及其相關聯的交換資源必須依產生的順序呈現。源自 [WaitFrameEventX](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12device/methods/id3d12device_waitframeeventx) 的畫面管線權杖串流會透過 *PresentX* 終止，不允許捨棄畫面或重新排序。在更新一或多個其他平面時，可以讓某個合成平面的內容持續保留在顯示器上；若要這麼做，請傳遞與上一次呼叫 *PresentX* 時為該平面提供的相同資源與畫面權杖。

若要移除在一連串 *PresentX* 呼叫期間建立的合成平面，請在後續呼叫 *PresentX* 時，從 *pPlaneParameters* 所指向的陣列中省略該平面的資源與權杖。

已呈現的交換資源會在其排定的 VBlank 時翻轉至顯示器；這是假設 *PresentX* 呼叫是在 *pPresentParameters* 的 *ImmediateThresholdPercent* 中所宣告的目標臨界值內發出並處理。如果 **PresentX** 錯過了 VBlank 但在臨界值內抵達，則會立即翻轉至顯示器。此臨界值是根據顯示掃描輸出時間 (VBlank 到 VBlank) 的百分比，而不是所定義畫面間隔的百分比。此外，與透過在 *pPresentParameters* 中使用 [D3D12XBOX\_PRESENT\_FLAG\_IMMEDIATE](/zh-TW/reference/graphics/d3d12_x/enums/d3d12xbox_present_flags) 旗標所安排的立即呈現 (會立即觸發下一個畫面的起點) 不同，根據臨界值進行的立即翻轉只有在後續畫面起點的時間已經過去時，才會發出該起點的訊號。

## 需求

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

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

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

## 另請參閱

[ID3D12CommandQueue](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/id3d12commandqueue)


## Related topics

- [XFrontPanelPresentBuffer](/zh-CN/reference/devkit/xfrontpaneldisplay/functions/xfrontpanelpresentbuffer.md)
- [NDA 主題目錄 - Microsoft Learn 線上連結](/zh-TW/nda/nda-topic-directory.md)
- [Game streaming latency compensation deep dive](/build/core-features/common/game-streaming/game-streaming-latency-compensation-deep-dive.md)
- [XGameStreamingGetAssociatedFrame](/reference/system/xgamestreaming/functions/xgamestreaminggetassociatedframe.md)
- [Análisis en profundidad de la compensación de latencia en game streaming](/es/build/core-features/common/game-streaming/game-streaming-latency-compensation-deep-dive.md)