XGameStreamingGetDisplayDetails

아티클
05/10/2023

이 API는 지정된 클라이언트의 디스플레이 세부 정보를 반환합니다. 이를 통해 렌더링할 사용자 지정 가로 세로 비율 또는 DirectCapture를 활성화하는 데 사용할 해상도 등을 결정할 때 정보에 입각한 결정을 내릴 수 있습니다.

구문

HRESULT XGameStreamingGetDisplayDetails(
        XGameStreamingClientId client,
        uint32_t maxSupportedPixels,
        float widestSupportedAspectRatio,
        float tallestSupportedAspectRatio,
        XGameStreamingDisplayDetails* displayDetails
)

매개 변수

client _In_
형식: XGameStreamingClientId

쿼리 중인 스트리밍 클라이언트입니다.

maxSupportedPixels _In_
형식: uint32_t

게임에서 지원하는 최대 픽셀 수입니다.

widestSupportedAspectRatio _In_
형식: float

게임에서 지원하는 가장 넓은 가로 세로 비율입니다. 이 비율은 지원되는 가장 넓은 해상도를 사용하여 너비/높이로 계산됩니다.

tallestSupportedAspectRatio _In_
형식: float

게임에서 지원하는 가장 높이가 긴 가로 세로 비율입니다. 이 비율은 지원되는 가장 높이가 긴 해상도를 사용하여 너비/높이로 계산됩니다.

displayDetails _Out_
형식: 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보다 커야 합니다.

오류 코드 목록은 오류 코드를 참조하세요.

비고

displayDetails 내의 데이터는 게임을 렌더링할 해상도와 같은 게임의 측면을 구동하고 중요한 정보 또는 UI가 상호 작용 가능하고 가려지지 않도록 배치할 위치를 알리는 데 사용할 수 있습니다.

displayDetails 구조체 내 preferredWidth 및 preferredHeight은(는) 스트리밍 클라이언트의 실제 디스플레이, 스트리밍 시스템에 따른 제한 사항, 게임에서 제공하는 매개 변수(maxSupportedPixels, widestSupportedAspectRatio, tallestSupportedAspectRatio)를 기반으로 합니다.

데이터는 게임 시작 시 사용이 불가할 수 있으며 클라이언트 연결 이벤트 시점에 반드시 사용 가능한 것은 아닙니다. 따라서 게임은 이벤트 또는 폴링을 사용해야 합니다.

예


#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);
        }
    }
}