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

# XGameStreamingGetDisplayDetails

> XGameStreamingGetDisplayDetails

# XGameStreamingGetDisplayDetails

此 API 返回指定客户端的显示详细信息。可用于做出明智的决策，例如以什么自定义纵横比呈现或使用什么分辨率来启用 DirectCapture。

## 语法

```cpp theme={null}
HRESULT XGameStreamingGetDisplayDetails(
        XGameStreamingClientId client,
        uint32_t maxSupportedPixels,
        float widestSupportedAspectRatio,
        float tallestSupportedAspectRatio,
        XGameStreamingDisplayDetails* displayDetails
)
```

### 参数

*client*   \_In\_\
类型：XGameStreamingClientId

正在查询的流式处理客户端。

*maxSupportedPixels*   \_In\_\
类型：uint32\_t

游戏支持的最大像素数。

*widestSupportedAspectRatio*   \_In\_\
类型：float

游戏支持的最宽纵横比。这是使用支持的最宽分辨率通过 width / height 计算得出的。

*tallestSupportedAspectRatio*   \_In\_\
类型：float

游戏支持的最高纵横比。这是使用支持的最高分辨率通过 width / height 计算得出的。

*displayDetails*   \_Out\_\
类型：[XGameStreamingDisplayDetails\*](/reference/system/xgamestreaming/structs/xgamestreamingdisplaydetails)

流式处理客户端的显示详细信息。

### 返回值

类型：HRESULT

如果成功，则返回 **S\_OK**；否则返回错误代码。

#### 潜在错误

| 错误代码                                     | 错误值        | 错误原因                                                                                                                                          |
| ---------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| E\_GAMESTREAMING\_NOT\_INITIALIZED       | 0x89245400 | XGameStreaming 运行时尚未初始化。在调用其他 API 之前，请先调用 XGameStreamingInitialize。                                                                           |
| E\_GAMESTREAMING\_CLIENT\_NOT\_CONNECTED | 0x89245401 | 指定的客户端未连接。                                                                                                                                    |
| E\_GAMESTREAMING\_NO\_DATA               | 0x89245402 | 请求的数据不可用。数据可能稍后可用。                                                                                                                            |
| E\_INVALIDARG                            | 0x80070057 | 一个或多个参数无效。`maxSupportedPixels` 必须大于 0。`widestSupportedAspectRatio` 必须大于或等于 16/9 并且不能为无穷大。`tallestSupportedAspectRatio` 必须小于或等于 16/9 并且必须大于 0。 |

有关错误代码列表，请参阅[错误代码](/reference/errorcodes)。

## 备注

`displayDetails` 中的数据可用于驱动游戏的各个方面，例如渲染游戏的分辨率，以及告知关键信息或 UI 的放置位置，以确保它们可交互且不被遮挡。

`displayDetails` 结构中的 `preferredWidth` 和 `preferredHeight` 基于流式处理客户端上的实际显示、基于流式处理系统的限制以及游戏提供的参数（`maxSupportedPixels`、`widestSupportedAspectRatio`、`tallestSupportedAspectRatio`）。

请记住，数据可能在游戏启动时不可用，也可能在客户端连接事件时不一定可用，因此游戏应使用事件或轮询。

## 示例

```C++ theme={null}

#define DEFAULT_GAME_WIDTH 1920
#define DEFAULT_GAME_HEIGHT 1080

#define GAME_WIDEST_SUPPORTED_ASPECT_RATIO 21.5f / 9.0f
#define GAME_TALLEST_SUPPORTED_ASPECT_RATIO 16.0f / 10.0f

static uint32_t s_currentStreamWidth = DEFAULT_GAME_WIDTH;
static uint32_t s_currentStreamHeight = DEFAULT_GAME_HEIGHT;

// Option 1: Event driven. Note: be aware of potential threading issues when using the task queue.
void GameStreamingClientManager::OnConnectionStateChanged(XGameStreamingClientId client, XGameStreamingConnectionState connected)
{
    // Other connection work like registering or unregistering for the client properties change events.
    ...

    UpdateResolutionIfNeeded();
}

void GameStreamingClientManager::OnClientPropertiesChanged(
    XGameStreamingClientId client,
    uint32_t updatedPropertiesCount,
    XGameStreamingClientProperty* updatedProperties)
{
    for (uint32_t i = 0; i < updatedPropertiesCount; ++i)
    {
        switch (updatedProperties[i])
        {
        case XGameStreamingClientProperty::DisplayDetails:
        {
            UpdateResolutionIfNeeded();
            break;
        }

        default:
            // A characteristic we are not tracking - do nothing
            break;
        }
    }
}

// Option 2: Polling.

void Game::Update(DX::StepTimer const& timer)
{
    ...

    gameStreamingClientManager->UpdateResolutionIfNeeded();

    ...
}

void GameStreamingClientManager::UpdateResolutionIfNeeded()
{
    bool changeResolution = false;
    bool useDefaultResolution = true;

    // Only use custom resolution when there is only one streaming client connected.
    if (XGameStreamingGetClientCount() == 1)
    {
        XGameStreamingClientId client;
        uint32_t clientsUsed = 0;
        HRESULT hr = XGameStreamingGetClients(1, &client, &clientsUsed);
        if (SUCCEEDED(hr) && clientsUsed == 1)
        {
            XGameStreamingDisplayDetails displayDetails = {};
            hr = XGameStreamingGetDisplayDetails(client, DEFAULT_GAME_WIDTH * DEFAULT_GAME_HEIGHT, GAME_WIDEST_SUPPORTED_ASPECT_RATIO, GAME_TALLEST_SUPPORTED_ASPECT_RATIO, &displayDetails);

            if (SUCCEEDED(hr))
            {
                useDefaultResolution = false;

                // Assuming the game supports all resolutions, use the stream resolution to the preferred dimensions as provided.
                if (s_currentStreamWidth != displayDetails.preferredWidth || s_currentStreamHeight != displayDetails.preferredHeight)
                {
                    changeResolution = true;
                    s_currentStreamWidth = displayDetails.preferredWidth;
                    s_currentStreamHeight = displayDetails.preferredHeight;
                }
            }
            else
            {
                LogFormat(L"XGameStreamingGetDisplayDetails failed %x", hr);
            }
        }
        else
        {
            LogFormat(L"XGameStreamingGetClients failed hr=%x clientsUsed=%d", hr, clientsUsed);
        }
    }

    if (useDefaultResolution)
    {
        if (s_currentStreamWidth != DEFAULT_GAME_WIDTH || s_currentStreamHeight != DEFAULT_GAME_HEIGHT)
        {
            changeResolution = true;
            s_currentStreamWidth = DEFAULT_GAME_WIDTH;
            s_currentStreamHeight = DEFAULT_GAME_HEIGHT;
        }
    }

    if (changeResolution)
    {
        // Update the stream to the new resolution.
        HRESULT hr = XGameStreamingSetResolution(s_currentStreamWidth, s_currentStreamHeight);
        if (SUCCEEDED(hr))
        {
            // Update the game to render at the new resolution.
        }
        else
        {
            LogFormat(L"XGameStreamingSetResolution failed %x", hr);
        }
    }
}

```

## 要求

**标头：** xgamestreaming.h\
**库：** xgameruntime.lib\
**支持的平台：** Windows、XBOX One 系列主机和 XBOX Series 主机

## 另请参阅

[XGameStreaming](/reference/system/xgamestreaming/xgamestreaming_members)

[XGameStreamingDisplayDetails](/reference/system/xgamestreaming/structs/xgamestreamingdisplaydetails)

[XGameStreamingRegisterClientPropertiesChanged](/reference/system/xgamestreaming/functions/xgamestreamingregisterclientpropertieschanged)

[XGameStreamingSetResolution](/reference/system/xgamestreaming/functions/xgamestreamingsetresolution)

[自定义分辨率概述](/build/core-features/common/game-streaming/game-streaming-custom-resolution-overview)


## Related topics

- [XGameStreamingDisplayDetails](/zh-CN/reference/system/xgamestreaming/structs/xgamestreamingdisplaydetails.md)
- [XGameStreamingVideoFlags](/zh-CN/reference/system/xgamestreaming/enums/xgamestreamingvideoflags.md)
- [XGameStreamingSetResolution](/zh-CN/reference/system/xgamestreaming/functions/xgamestreamingsetresolution.md)
- [XGameStreamingClientProperty](/zh-CN/reference/system/xgamestreaming/enums/xgamestreamingclientproperty.md)
- [游戏串流自定义分辨率最佳实践](/zh-CN/build/core-features/common/game-streaming/game-streaming-custom-resolution-best-practices.md)