> ## 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 런타임이 초기화되지 않았습니다. 다른 API를 호출하기 전에 XGameStreamingInitialize를 호출하세요. |
| E\_INVALIDARG                      | 0x80070057 | *width* 및/또는 *height* 매개 변수나 하드웨어가 요구 사항을 충족하지 않습니다.                              |

오류 코드 목록은 [오류 코드](/reference/errorcodes)를 참조하세요.

## 설명

비표준 해상도를 사용하는 이 API는 XBOX Game Streaming 서버, XBOX Series X 개발 키트 및 XBOX Series S 테스트 키트에서만 성공합니다. 720p와 1080p 같은 표준 해상도는 하드웨어에 관계없이 성공합니다. 그 이유는 소매용 XBOX는 Remote Play를 통해서만 스트리밍할 수 있으며 TV로 여전히 비디오를 출력하고 있을 수 있어서 비표준 해상도를 사용하면 왜곡된 이미지가 생성될 수 있기 때문입니다.

너비와 높이의 최솟값은 640x360이어야 하며, 최댓값은 [XGameStreamingGetDisplayDetails](/reference/system/xgamestreaming/functions/xgamestreaminggetdisplaydetails)에서 검색할 수 있는 [XGameStreamingDisplayDetails](/reference/system/xgamestreaming/structs/xgamestreamingdisplaydetails)의 `maxWidth` 및 `maxHeight` 필드에서 확인할 수 있습니다.

`width` \* `height`로 계산되는 최대 픽셀 수는 인코더의 최댓값보다 작거나 같아야 합니다. 최댓값은 [XGameStreamingGetDisplayDetails](/reference/system/xgamestreaming/functions/xgamestreaminggetdisplaydetails) API를 사용하여 확인할 수 있습니다. 이 값은 향후 늘어날 수 있습니다.

`width`와 `height`는 8로 나누어져야 합니다.

이 API는 원하는 만큼 자주 호출할 수 있지만 스트림 해상도는 200ms마다 한 번만 변경할 수 있습니다. 해당 200ms 창 내에 발생한 호출 중 마지막 해상도가 창이 지난 후 적용됩니다.

이 API는 연결된 모든 클라이언트에 대해 스트림의 해상도를 설정한다는 점에 유의하세요. 즉, 여러 클라이언트가 연결되어 있을 때 게임에 가장 적합한 옵션이 무엇인지 결정하기 위해 특별히 고려해야 합니다. 표준 16:9 해상도를 사용하는 것을 의미할 수도 있고, 모든 클라이언트에 가장 잘 맞는 해상도를 찾는 것을 의미할 수도 있습니다.

<Note>스트림 해상도를 변경하면 ID3D12CommandQueue::PresentX에서 뷰 사각형 크기 조정이 수정됩니다. D3D12XBOX\_PRESENT\_PLANE\_PARAMETERS.pDestPlacementBase의 0.0\~1.0 크기 조정 계수는 표준 1920x1080이나 3840x2160 해상도가 아닌, XGameStreamingSetResolution에 전달된 너비와 높이를 참조합니다.</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](/reference/system/xgamestreaming/xgamestreaming_members)\
[XGameStreamingDisplayDetails](/reference/system/xgamestreaming/structs/xgamestreamingdisplaydetails)\
[XGameStreamingGetDisplayDetails](/reference/system/xgamestreaming/functions/xgamestreaminggetdisplaydetails)\
[사용자 지정 해상도 개요](/build/core-features/common/game-streaming/game-streaming-custom-resolution-overview)


## Related topics

- [XGameStreaming](/ko/reference/system/xgamestreaming/xgamestreaming_members.md)
- [XGameStreamingGetDisplayDetails](/ko/reference/system/xgamestreaming/functions/xgamestreaminggetdisplaydetails.md)
- [게임 스트리밍 사용자 지정 해상도 모범 사례](/ko/build/core-features/common/game-streaming/game-streaming-custom-resolution-best-practices.md)
- [사용자 지정 해상도 개요](/ko/build/core-features/common/game-streaming/game-streaming-custom-resolution-overview.md)
- [XGameStreamingVideoFlags](/ko/reference/system/xgamestreaming/enums/xgamestreamingvideoflags.md)