XGameStreamingSetResolution

设置流的分辨率。

语法

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 运行时尚未初始化。 在调用其他 API 之前，先调用 XGameStreamingInitialize。
E_INVALIDARG	0x80070057	width 和/或 height 参数或硬件不符合要求。

有关错误代码的列表，请参阅错误代码。

备注

这种采用非标准分辨率的 API 只能在 Xbox 游戏流式处理服务器、Xbox Series X 开发工具包和 Xbox Series S 测试工具包上成功。 无论硬件如何，720p 和 1080p 等标准分辨率都将成功。 原因是，零售版 Xbox 只能通过 Remote Play 进行流式传输，并且可能仍在将视频输出到电视，因此使用非标准分辨率会产生失真图像。

宽度和高度必须至少为 640x360，最大值可以在 XGameStreamingDisplayDetails 的 maxWidth 和 maxHeight 字段中找到，这些字段可以从 XGageStreamingGetDisplaydetails 中检索。

从 width * height 计算的最大像素必须等于或小于编码器的最大值。 可以使用 XGameStreamingGetDisplayDetails API 找到最大值。 此值将来可能会增加。

width 和 height 必须可以被 8 整除。

可以根据需要频繁调用 API，但流分辨率每 200 毫秒只能更改一次。 在该 200 毫秒时间段内发生的任何调用的最后一个分辨率将在该时间段结束后应用。

请注意，此 API 将为所有连接的客户端设置流分辨率。 这意味着在连接多个客户端时，必须特别注意，确定什么是游戏的最佳选项。 这可能意味着使用标准 16:9 分辨率，也可能意味着尝试查找最适合所有客户端的分辨率。

注意

更改流分辨率会修改 ID3D12CommandQueue::PresentX 中的视图矩形缩放。 D3D12XBOX_PRESENT_PLANE_PARAMETERS.pDestPlacementBase 缩放因子 0.0-1.0 是指传递给 XGameStreamingSetResolution 的高度和宽度，而不是它们本来所指的标准 1920x1080 或 3840x2160 分辨率。

示例

#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
XGameStreamingDisplayDetails
XGameStreamingGetDisplayDetails
自定义分辨率概述