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

# 自訂解析度概觀

> 使用 XGameStreamingSetResolution 讓 XBOX Game Streaming 輸出符合手機、平板電腦和其他用戶端的長寬比，而非 16:9。

XBOX Game Streaming 可讓您根據電視以外裝置 (例如手機、平板電腦和其他裝置) 的輸出解析度，自訂遊戲的解析度。這有助於在各種裝置上提供更豐富的體驗。我們推出了 [XGameStreamingGetDisplayDetails](/zh-TW/reference/system/xgamestreaming/functions/xgamestreaminggetdisplaydetails) 和 [XGameStreamingSetResolution](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingsetresolution)，讓您可以將串流從 XBOX 的 16:9 長寬比切換為符合手機、平板電腦等許多不同裝置的長寬比。

例如，下圖說明在串流環境中未做任何變更時，XBOX 遊戲在一般 16:9 電視螢幕上與在直向模式的平板電腦或手機上的轉譯方式。

<img src="https://mintcdn.com/microsoft-4404708b/sIrPFR_ir_sNKVEv/images/gdk/features/common/Letterbox_4_3Tablet.jpg?fit=max&auto=format&n=sIrPFR_ir_sNKVEv&q=85&s=00e601ab2323aec3acd775323b1620eb" alt="橫向平板電腦上的 XBOX 標誌，上下有黑邊" width="1130" height="850" data-path="images/gdk/features/common/Letterbox_4_3Tablet.jpg" />

<img src="https://mintcdn.com/microsoft-4404708b/sIrPFR_ir_sNKVEv/images/gdk/features/common/Letterbox_4_3Tablet_portrait.jpg?fit=max&auto=format&n=sIrPFR_ir_sNKVEv&q=85&s=a84b5ea56442935ce6af972ee9b6bcab" alt="直向平板電腦上的 XBOX 標誌，上下有黑邊" width="712" height="940" data-path="images/gdk/features/common/Letterbox_4_3Tablet_portrait.jpg" />

**圖 1. 未使用 `XGameStreamingGetDisplayDetails` 和 `XGameStreamingSetResolution` 時，遊戲在不同裝置上的轉譯**

另一方面，下一張圖說明使用上述 API 將長寬比設定為 4:3 時，相同遊戲在不同裝置上的轉譯方式。請注意，在平板電腦上轉譯時空白區域已消失。

<img src="https://mintcdn.com/microsoft-4404708b/sIrPFR_ir_sNKVEv/images/gdk/features/common/4_3Tablet_withCustomRes.jpg?fit=max&auto=format&n=sIrPFR_ir_sNKVEv&q=85&s=a98a6638a2d9649d82f2eb9a02e561c4" alt="填滿橫向平板電腦螢幕的 XBOX 標誌" width="1317" height="1000" data-path="images/gdk/features/common/4_3Tablet_withCustomRes.jpg" />

<img src="https://mintcdn.com/microsoft-4404708b/sIrPFR_ir_sNKVEv/images/gdk/features/common/16_9TV.jpg?fit=max&auto=format&n=sIrPFR_ir_sNKVEv&q=85&s=9cf9ad60e2e168f8f2864afe8f7f0b30" alt="填滿 16:9 電視螢幕的 XBOX 標誌" width="1590" height="931" data-path="images/gdk/features/common/16_9TV.jpg" />

**圖 2. 使用 `XGameStreamingGetDisplayDetails` 和 `XGameStreamingSetResolution` 時，遊戲在不同裝置上的轉譯**

`XGameStreamingGetDisplayDetails` 會傳回指定用戶端的顯示詳細資料。這可用來做出明智的決策，例如要以哪些自訂長寬比轉譯，或要使用哪個解析度來啟用 [DirectCapture](/zh-TW/build/core-features/common/game-streaming/game-streaming-directcapture-overview)。DirectCapture 的設計目的是在作品呈現相容畫面時將伺服器延遲降至最低，可消除大約 16 到 72 毫秒的延遲。每款遊戲的延遲降低幅度各不相同，因為這取決於遊戲的轉譯輸出。

作品決定解析度之後，就應使用 `XGameStreamingSetResolution`。此 API 會設定串流的解析度。

這些 API 會公開 DirectCapture 的需求和用戶端的慣用解析度，讓不同的作品都能採用。
<Note>必須遵循最小值/最大值需求以及其他 DirectCapture 規則。</Note>

請注意，雖然這些 API 也存在於家用主機上，但為了維持電視相容性，它們只允許使用標準解析度 (實際上等同於不執行任何作業)。

## 如何正確使用這些 API

1. **連線串流**

如果您先前未曾串流過遊戲，請依照此處的指示操作：[遊戲串流測試必要條件](/zh-TW/build/core-features/common/game-streaming/game-streaming-stream-your-game)

1. **取得顯示器的詳細資料**

   若要取得顯示器的詳細資料，遊戲可以呼叫 `XGameStreamingGetDisplayDetails`，這會傳回指定用戶端的顯示詳細資料。

2. **挑選解析度**

   這取決於遊戲。有數個選項，例如

   a. 使用 `preferredWidth`/`preferredHeight` 作為最佳相符項目。

   b. 使用 `XGameStreamingDisplayDetails`，在預先設定的一組已測試解析度中尋找最接近的解析度。

   c. 為遊戲的 PC 版本開啟解析度選擇器，讓玩家選擇解析度。請考慮將解析度限制在 `maxWidth`、`maxHeight` 和 `maxPixels` 的範圍內。

3. **設定串流解析度**

   呼叫 `XGameStreamingSetResolution`，將串流解析度變更為新的轉譯解析度。最好是在回應使用者動作時呼叫，例如串流開始、調整大小、旋轉裝置動作等。

   請注意，此解析度不需要符合 preferredWidth/preferredHeight。如果不相符，串流可能會縮放以符合螢幕大小，並加入上下或左右黑邊以填滿剩餘空間。

   > \[!NOTE]
   > 請務必注意，設定串流解析度需要時間、會使用有限的資源，而且會產生玩家可見的效果，因此應該很少呼叫此 API；例如，在新用戶端連線或變更其慣用解析度時。

   每 200 毫秒呼叫 `XGameStreamingSetResolution` 超過一次會造成短暫的拉伸。此 API 並非即時安全。

4. **開始轉譯**

   轉譯自訂解析度應與轉譯其他解析度相同：設定您的視窗大小，並以新的解析度設定您的背景緩衝區。

如果您想要試試看，請參考我們的範例 [這裡](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/xCloud/CustomResolution)。

## 另請參閱

[自訂解析度最佳做法](/zh-TW/build/core-features/common/game-streaming/game-streaming-custom-resolution-best-practices)

[使用自訂解析度進行測試 (NDA 主題)](/zh-TW/build/core-features/common/game-streaming/game-streaming-testing-custom-resolution)


## Related topics

- [XR-003 提交的遊戲品質](/zh-TW/publishing/certification/xr/xr-003.md)
- [XBOX 主機遊戲的認證測試 XBOX 需求](/zh-TW/publishing/certification/console-cert-tested-requirements.md)
- [NDA 主題目錄 - Microsoft Learn 線上連結](/zh-TW/nda/nda-topic-directory.md)
- [服務 C API 概觀 - PFLocalization.h](/zh-TW/services/playfab/api-references/c/pflocalization/pflocalization_members.md)
- [服務 C API 概觀 - PFStatistics.h](/zh-TW/services/playfab/api-references/c/pfstatistics/pfstatistics_members.md)