> ## 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](/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** 按钮关联的*跳跃*操作。它提供了一种触摸布局，*jump* 图标配置为在虚拟控制器上按下 **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](/zh-CN/reference/system/xgamestreaming/enums/xgamestreaminggamepadphysicality.md)
- [XGameStreaming](/zh-CN/reference/system/xgamestreaming/xgamestreaming_members.md)
- [构建触控的设计师指南](/zh-CN/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-tak-designers-guide.md)
- [XGameStreamingGetAssociatedFrame](/zh-CN/reference/system/xgamestreaming/functions/xgamestreaminggetassociatedframe.md)
- [GAMEPAD_VIBRATION](/zh-CN/reference/tools/xtf/xtfinput/structures/gamepad_vibration.md)