> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XGameStreamingShowTouchControlLayoutOnClient

> XGameStreamingShowTouchControlLayoutOnClient

# XGameStreamingShowTouchControlLayoutOnClient

在单个客户端上显示所请求的触摸控件集。

## 语法

```cpp theme={null}
void XGameStreamingShowTouchControlLayoutOnClient(  
         XGameStreamingClientId client,  
         const char* layout  
)  
```

### 参数

*client*   \_In\_\
类型：XGameStreamingClientId

要在其上显示触摸控件的流式处理客户端设备。

*layout*   \_In\_opt\_z\_\
类型：char\*

要显示的触摸控件布局的名称，或 nullptr 以显示默认布局。

要在流式处理客户端设备上显示的触摸控件布局的 ID。布局 ID 是特定于游戏的，与作为[Touch Adaptation Kit](https://docs.xbox.com/zh-CN/build/core-features/common/game-streaming/game-streaming-touch-touch-adaptation-kit-overview.md)的一部分提供给 XBOX Game Streaming 的布局的 ID 对应。此字符串应采用 UTF-8 编码。

如果提供 `nullptr`，将显示默认的触摸控件集。

任何不与游戏的触摸控件布局 ID 对应的字符串都不会更改客户端设备上触摸控件的状态，使其保持不变。在这些情况下，内容测试应用程序可能会提供诊断信息。

## 返回值

类型：void

## 备注

此 API 请求指定的游戏流式处理客户端在玩家的客户端设备上显示特定的触摸控件布局。如果玩家未在对游戏进行流式处理，或者流式处理客户端未启用触摸，则此函数不执行任何操作。

如果玩家使用的是物理控制器而不是触摸控件，则此函数不会强制在其设备上显示触摸控件。相反，客户端将在下次玩家开始使用触摸控件时使用上次请求的布局。

你可以将此函数视为对客户端设备的提示，告诉它如果玩家正在使用触摸控件，哪种触摸控件布局最适合当前游戏状态。然后客户端设备将管理何时最适合将这些控件放在玩家的屏幕上。

每次调用 `XGameStreamingShowTouchControlLayoutOnClient` 都会导致通过网络发送一条消息，因此不应该每帧调用它。相反，只有在游戏需要在不同的触摸控件布局之间切换时才调用此 API。

如果你的游戏想要在**所有**已连接的流式处理客户端设备上显示触摸控件布局，请考虑改用 [XGameStreamingShowTouchControlLayout](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrollayout.md)。

## 示例

```C++ theme={null}
void OnGameStateChanged(GameState newState, XGameStreamingClientId client)
{
    // Toggle to the set of touch overlay controls which best match the new state of the game
    switch (newState)
    {
    case GameState::FirstPersonAction:
        XGameStreamingShowTouchControlLayoutOnClient(client, "FirstPersonAction");
        break;
    case GameState::Driving:
        XGameStreamingShowTouchControlLayoutOnClient(client, "Driving");
        break;
    case GameState::CutScene:
        // Don't show any touch overlay controls while the cut scene is rendering
        XGameStreamingHideTouchControlsOnClient(client);
        break;
    }
}
```

## 要求

**标头：** xgamestreaming.h

**库：** xgameruntime.lib

**支持的平台：** Windows、XBOX One 系列主机和 XBOX Series 主机

## 另请参阅

[XGameStreamingHideTouchControlsOnClient](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/functions/xgamestreaminghidetouchcontrols.md)\
[XGameStreamingShowTouchControlLayout](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrollayout.md)\
[XGameStreaming](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/xgamestreaming_members.md#TouchAdaptation)


## Related topics

- [XGameStreamingShowTouchControlLayout](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrollayout.md)
- [XGameStreamingHideTouchControlsOnClient](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/functions/xgamestreaminghidetouchcontrolsonclient.md)
- [XGameStreamingShowTouchControlsWithStateUpdateOnClient](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrolswithstateupdateonclient.md)
- [XGameStreaming（API 内容）](https://docs.xbox.com/zh-CN/reference/system/xgamestreaming/xgamestreaming_members.md)
- [在 Unity 项目中使用 GDK API 的 C# 包装器](https://docs.xbox.com/zh-CN/build/gdk-and-engines/unity/unity-api-wrappers.md)