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

# XGameStreamingGetGamepadPhysicality

> XGameStreamingGetGamepadPhysicality

# XGameStreamingGetGamepadPhysicality

특정 게임패드 판독값에서 입력 물리성(physicality) 매핑을 가져옵니다.

<a id="syntaxSection" />

## 구문

```cpp theme={null}
HRESULT XGameStreamingGetGamepadPhysicality(
         IGameInputReading* gamepadReading,
         XGameStreamingGamepadPhysicality* gamepadPhysicality
)
```

<a id="parametersSection" />

### 매개 변수

*gamepadReading*   \_In\_\
형식: IGameInputReading\*

쿼리 대상 게임패드 판독값입니다.

*gamepadPhysicality*   \_Out\_\
형식: [XGameStreamingGamepadPhysicality](/reference/system/xgamestreaming/enums/xgamestreaminggamepadphysicality)\*

입력 판독값의 물리성입니다.

<a id="retvalSection" />

### 반환 값

형식: HRESULT

성공하면 **S\_OK**를 반환하고, 그렇지 않으면 오류 코드를 반환합니다.

**잠재적 오류**

| 오류 코드                                        | 오류 값       | 오류 원인                                                                                                                                                    |
| -------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| E\_GAMESTREAMING\_NOT\_INITIALIZED           | 0x89245400 | XGameStreaming 런타임이 초기화되지 않았습니다. 다른 API를 호출하기 전에 [XGameStreamingInitialize](/reference/system/xgamestreaming/functions/xgamestreaminginitialize)를 호출하세요. |
| E\_GAMESTREAMING\_NOT\_STREAMING\_CONTROLLER | 0x89245404 | 현재 판독값이 스트리밍 컨트롤러에서 온 것이 아닙니다.                                                                                                                           |

<a id="remarksSection" />

## 설명

게임은 물리적으로 연결된 컨트롤러에서 입력이 왔는지, 아니면 가상 컨트롤러 입력으로 변환된 터치 레이아웃에서 왔는지에 따라 컨트롤러 입력을 구분해야 할 수 있습니다.

**예제 시나리오**

게임에서 *점프* 동작이 **A** 버튼에 연결되어 있습니다. 이 게임은 가상 컨트롤러의 **A** 버튼 누름으로 구성된 *점프* 아이콘이 포함된 터치 레이아웃을 제공합니다. 또한 이 게임은 플레이어가 물리적 컨트롤러를 다시 매핑하여 **A**가 더 이상 *점프*와 연결되지 않도록 할 수 있는 기능도 제공합니다.

게임은 요소와 상호 작용하기 위한 시각적 힌트를 표시할 수 있습니다(예: *점프*하려면 **A**를 누르세요). 플레이어가 터치 레이아웃을 사용하는 경우, 시각적 힌트에는 해당 터치 레이아웃 버튼의 아이콘이 표시되어야 합니다.

<a id="exampleSection" />

## 예제

다음 코드 예제에서 게임은 기본적으로 컨트롤러의 **A** 버튼에 *점프* 동작을 연결해 두었습니다. 이 설정은 플레이어가 사용자 지정할 수 있지만, 화면의 터치 레이아웃은 고정되어 있으므로 터치 레이아웃의 **A** 버튼 누름은 항상 *점프*로 처리되어야 하며, 물리적 컨트롤러의 **A**는 플레이어가 컨트롤러 매핑을 사용자 지정한 대로 처리되어야 합니다.

```cpp theme={null}
void Game::Update(DX::StepTimer const& timer)
{
    g_gameInput->GetCurrentReading(GameInputKind::GameInputKindController, g_gamepad, &reading);
    
    GameInputGamepadState state;
    reading->GetGamepadState(&state);

    XGameStreamingGamepadPhysicality physicality = XGameStreamingGamepadPhysicality::None;
    
    HRESULT hr = XGameStreamingGetGamepadPhysicality(reading, &physicality);

    if ((state.buttons & GameInputGamepadA) != GameInputGamepadNone)
    {
        if (SUCCEEDED(hr))
        {
            if ((physicality & XGameStreamingGamepadPhysicality::AVirtual) == 
                XGameStreamingGamepadPhysicality::AVirtual)
            {
                // 'A' Input came from touch layout
                // Perform 'jump' action, if applicable
            }
            else if ((physicality & XGameStreamingGamepadPhysicality::APhysical) == 
                 XGameStreamingGamepadPhysicality::APhysical)
            {
                // 'A' Input came from the physical controller.
                // Lookup 'A' from the user's customized controller mapping.
                // Perform whatever action A is mapped to, if applicable.
            }
        }
        else
        {
            // Physicality not present on this gamepad.
            // Perform input 'A' action as if there were no stream.
        }
    }

    // UI icon updates.
    // If the player is using the touch layouts, then show touch iconography, 
    // otherwise switch to the physical controller iconography.
    if (SUCCEEDED(hr))
    {
        if ((physicality & XGameStreamingGamepadPhysicality::AllVirtual) != 
            XGameStreamingGamepadPhysicality::None)
        {
            // At least one input is coming from virtual touch layout.
            // Update UI icons to match the touch layouts.
        } 
        else 
        {
            if ((physicality & XGameStreamingGamepadPhysicality::AllPhysical) != 
                XGameStreamingGamepadPhysicality::None)
            {
                // At least one input is coming from a physical controller.
                // Update UI icons to match a physical controller inputs (for example, LT/LB/RT/RB icon).
            }
        }
    }
    else
    {
        // Use the default non-streaming behavior for UI icons 
    }
}
```

<a id="requirementsSection" />

## 요구 사항

**헤더:** xgamestreaming.h

**라이브러리:** xgameruntime.lib

**지원 플랫폼:** Windows, XBOX One 계열 콘솔 및 XBOX Series 콘솔

<a id="seealsoSection" />

## 함께 보기

[XGameStreaming](/reference/system/xgamestreaming/xgamestreaming_members)\
[XGameStreamingGamepadPhysicality](/reference/system/xgamestreaming/enums/xgamestreaminggamepadphysicality)\
[XGameStreaming 터치 적응](/reference/system/xgamestreaming/xgamestreaming_members#TouchAdaptation)


## Related topics

- [XGameStreamingGamepadPhysicality](/ko/reference/system/xgamestreaming/enums/xgamestreaminggamepadphysicality.md)
- [XGameStreaming](/ko/reference/system/xgamestreaming/xgamestreaming_members.md)
- [터치 컨트롤을 구축하기 위한 디자이너 가이드](/ko/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-tak-designers-guide.md)
- [XGameStreamingGetAssociatedFrame](/ko/reference/system/xgamestreaming/functions/xgamestreaminggetassociatedframe.md)
- [GAMEPAD_VIBRATION](/ko/reference/tools/xtf/xtfinput/structures/gamepad_vibration.md)