> ## 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 游戏串流输出匹配手机、平板电脑及其他客户端的宽高比，而不再局限于 16:9。

XBOX 游戏串流让您能够根据除电视之外的设备（例如手机、平板电脑和其他设备）的输出分辨率自定义游戏的分辨率。这有助于跨设备提供更丰富的体验。为此引入了 [XGameStreamingGetDisplayDetails](/reference/system/xgamestreaming/functions/xgamestreaminggetdisplaydetails) 和 [XGameStreamingSetResolution](/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](/build/core-features/common/game-streaming/game-streaming-directcapture-overview)。DirectCapture 旨在在游戏呈现兼容帧时最大限度地减少服务器延迟，消除大约 16 到 72 毫秒的延迟。由于取决于游戏的渲染输出，这种延迟减少因游戏而异。

一旦游戏确定了分辨率，就应使用 `XGameStreamingSetResolution`。此 API 将设置串流的分辨率。

这些 API 公开了 DirectCapture 的要求和客户端的首选分辨率，以便不同的游戏都能采用。
<Note>必须遵循最小/最大要求以及其他 DirectCapture 规则。</Note>

请注意，虽然这些 API 会在家用主机上存在，但它们只允许使用标准分辨率以保持电视兼容性（实际上使它们成为无操作）。

## 如何正确使用这些 API

1. **连接串流**

如果您之前没有串流过您的游戏，请按照此处的说明操作：[游戏串流测试先决条件](/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)的示例。

## 另请参阅

[自定义分辨率最佳实践](/build/core-features/common/game-streaming/game-streaming-custom-resolution-best-practices)

[使用自定义分辨率进行测试（NDA 主题）](/build/core-features/common/game-streaming/game-streaming-testing-custom-resolution)


## Related topics

- [游戏串流自定义分辨率最佳实践](/zh-CN/build/core-features/common/game-streaming/game-streaming-custom-resolution-best-practices.md)
- [使用自定义分辨率进行测试](/zh-CN/build/core-features/common/game-streaming/game-streaming-testing-custom-resolution.md)
- [DirectCapture 概述](/zh-CN/build/core-features/common/game-streaming/game-streaming-directcapture-overview.md)
- [XGameStreamingDisplayDetails](/zh-CN/reference/system/xgamestreaming/structs/xgamestreamingdisplaydetails.md)
- [XGameStreamingSetResolution](/zh-CN/reference/system/xgamestreaming/functions/xgamestreamingsetresolution.md)