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

> XGameStreamingSetResolution

# XGameStreamingSetResolution

設定串流的解析度。

## 語法

```cpp theme={null}
HRESULT XGameStreamingSetResolution(
        uint32_t width,
        uint32_t height
)
```

### 參數

*width*   \_In\_\
類型：uint32\_t

要設定的串流解析度寬度。

*height*   \_In\_\
類型：uint32\_t

要設定的串流解析度高度。

### 傳回值

類型：HRESULT

如果成功，則傳回 **S\_OK**；否則傳回錯誤碼。

#### 可能的錯誤

| 錯誤碼 | 錯誤值 | 錯誤原因 |
| - | - | - |
| E\_GAMESTREAMING\_NOT\_INITIALIZED | 0x89245400 | XGameStreaming 執行階段尚未初始化。請先呼叫 XGameStreamingInitialize，再呼叫其他 API。 |
| E\_INVALIDARG | 0x80070057 | *width* 及/或 *height* 參數或硬體不符合需求。 |

如需錯誤碼清單，請參閱[錯誤碼](/zh-TW/reference/errorcodes)。

## 備註

以非標準解析度呼叫此 API 時，只有在 XBOX Game Streaming 伺服器、XBOX Series X Dev Kit 和 XBOX Series S Test Kit 上才會成功。720p 和 1080p 等標準解析度則不論硬體為何都會成功。原因是零售版 XBOX 只能透過遠端遊玩進行串流，而且可能仍在將視訊輸出到電視，因此使用非標準解析度會產生失真的影像。

寬度和高度最小必須為 640x360，最大值可在 [XGameStreamingDisplayDetails](/zh-TW/reference/system/xgamestreaming/structs/xgamestreamingdisplaydetails) 的 `maxWidth` 和 `maxHeight` 欄位中找到，而該結構可從 [XGameStreamingGetDisplayDetails](/zh-TW/reference/system/xgamestreaming/functions/xgamestreaminggetdisplaydetails) 擷取。

以 `width` \* `height` 計算出的最大像素數，必須等於或小於編碼器的上限。您可以使用 [XGameStreamingGetDisplayDetails](/zh-TW/reference/system/xgamestreaming/functions/xgamestreaminggetdisplaydetails) API 找到此上限。此值未來可能會提高。

`width` 和 `height` 必須可被 8 整除。

此 API 可以視需要頻繁呼叫，但串流解析度每 200 毫秒只能變更一次。在該 200 毫秒時間範圍內發生的所有呼叫中，最後一個解析度會在該時間範圍結束後套用。

請注意，此 API 會為所有已連線用戶端設定串流的解析度。這表示當有多個用戶端連線時，必須特別考量以判斷對遊戲而言最佳的選項。這可能表示要使用標準 16:9 解析度，也可能表示要嘗試找出最適合所有用戶端的解析度。

<Note>變更串流解析度會修改 `ID3D12CommandQueue::PresentX` 中的檢視矩形縮放。`D3D12XBOX_PRESENT_PLANE_PARAMETERS.pDestPlacementBase` 的 0.0-1.0 縮放比例是指傳遞給 `XGameStreamingSetResolution` 的高度和寬度，而不是原本所指的標準 1920x1080 或 3840x2160 解析度。  </Note>

## 範例

```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](/zh-TW/reference/system/xgamestreaming/xgamestreaming_members)\
[XGameStreamingDisplayDetails](/zh-TW/reference/system/xgamestreaming/structs/xgamestreamingdisplaydetails)\
[XGameStreamingGetDisplayDetails](/zh-TW/reference/system/xgamestreaming/functions/xgamestreaminggetdisplaydetails)\
[自訂解析度概觀](/zh-TW/build/core-features/common/game-streaming/game-streaming-custom-resolution-overview)


## Related topics

- [XGameStreamingSetResolution](/reference/system/xgamestreaming/functions/xgamestreamingsetresolution.md)
- [Best Practices for Game Streaming Custom Resolution](/build/core-features/common/game-streaming/game-streaming-custom-resolution-best-practices.md)
- [Custom Resolution Overview](/build/core-features/common/game-streaming/game-streaming-custom-resolution-overview.md)
- [XGameStreaming](/reference/system/xgamestreaming/xgamestreaming_members.md)
- [Testing With Custom Resolution](/build/core-features/common/game-streaming/game-streaming-testing-custom-resolution.md)