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

從特定遊戲台讀數取得輸入實體性對應。

<a id="syntaxSection" />

## 語法

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

<a id="parametersSection" />

### 參數

*gamepadReading*   \_In\_\
類型：IGameInputReading\*

要查詢的遊戲台讀數。

*gamepadPhysicality*   \_Out\_\
類型：[XGameStreamingGamepadPhysicality](/zh-TW/reference/system/xgamestreaming/enums/xgamestreaminggamepadphysicality)\*

輸入讀數的實體性。

<a id="retvalSection" />

### 傳回值

類型：HRESULT

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

**可能的錯誤**

| 錯誤碼 | 錯誤值 | 錯誤原因 |
| - | - | - |
| E\_GAMESTREAMING\_NOT\_INITIALIZED | 0x89245400 | XGameStreaming 執行階段尚未初始化。請先呼叫 [XGameStreamingInitialize](/zh-TW/reference/system/xgamestreaming/functions/xgamestreaminginitialize)，再呼叫其他 API。 |
| 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](/zh-TW/reference/system/xgamestreaming/xgamestreaming_members)\
[XGameStreamingGamepadPhysicality](/zh-TW/reference/system/xgamestreaming/enums/xgamestreaminggamepadphysicality)\
[XGameStreaming 觸控調整](/zh-TW/reference/system/xgamestreaming/xgamestreaming_members#TouchAdaptation)


## Related topics

- [XGameStreamingGetGamepadPhysicality](/reference/system/xgamestreaming/functions/xgamestreaminggetgamepadphysicality.md)
- [XGameStreamingGamepadPhysicality](/reference/system/xgamestreaming/enums/xgamestreaminggamepadphysicality.md)