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

# IGameInputDevice::GetTouchSurfaceInfo

> 取得輸入裝置上觸控表面的相關資訊。

取得輸入裝置上觸控表面的相關資訊。

## 語法

```cpp theme={null}
HRESULT GetTouchSurfaceInfo(
    uint32_t surfaceIndex,
    GameInputTouchSurfaceInfo* info
);
```

### 參數

*surfaceIndex*\
類型：uint32\_t

觸控表面之從零開始的索引。此值必須小於 [IGameInputDevice::GetTouchSurfaceCount](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_gettouchsurfacecount.md) 傳回的值。

*info*   \_Out\_\
類型：[GameInputTouchSurfaceInfo](https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/input/gameinput/structs/gameinputtouchsurfaceinfo)\*

接收觸控表面的相關資訊。

### 傳回值

類型：HRESULT

成功時傳回 `S_OK`。如果 *surfaceIndex* 大於或等於裝置上的觸控表面數目，則傳回 `E_BOUNDS`；在此情況下，*info* 會設定為零。

## 備註

傳回的資訊描述表面可同時回報的最大接觸點數目、表面的尺寸 (以裝置單位表示)，以及表面的類型 (例如觸控板或觸控螢幕)。[IGameInputReading::GetTouchSurfaceState](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_gettouchsurfacestate.md) 所回報的接觸點位置是相對於這些尺寸，因此您可以使用這些尺寸將接觸點位置正規化。

此資訊在裝置物件的存留期間內不會變更。

下列範例會將裝置每個觸控表面上第一個接觸點的位置正規化至 \[0, 1) 範圍。

```cpp theme={null}
void ProcessTouch(IGameInputDevice* device, IGameInputReading* reading) noexcept
{
    const uint32_t surfaceCount = device->GetTouchSurfaceCount();
    for (uint32_t surfaceIndex = 0; surfaceIndex < surfaceCount; ++surfaceIndex)
    {
        GameInputTouchSurfaceInfo info = {};
        if (FAILED(device->GetTouchSurfaceInfo(surfaceIndex, &info)) ||
            info.padWidth == 0 || info.padHeight == 0)
        {
            continue;
        }

        GameInputTouchContact contact = {};
        if (reading->GetTouchSurfaceState(surfaceIndex, 1, &contact) == 1)
        {
            const float x = static_cast<float>(contact.padX) / info.padWidth;
            const float y = static_cast<float>(contact.padY) / info.padHeight;
            // Use the normalized position (x, y) of the contact.
        }
    }
}
```

> [!NOTE]
>
> 觸控支援取決於裝置和平台。

## 需求

**標頭：** GameInput.h

**程式庫：** gameinput.lib

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

## 另請參閱

[GameInput 概觀](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-overview.md)\
[IGameInputDevice](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/igameinputdevice.md)\
[GameInputTouchSurfaceInfo](https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/input/gameinput/structs/gameinputtouchsurfaceinfo)\
[IGameInputDevice::GetTouchSurfaceCount](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_gettouchsurfacecount.md)\
[IGameInputReading::GetTouchSurfaceState](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_gettouchsurfacestate.md)

## 版本歷程記錄

| 版本 | 變更 |
| - | - |
| **v4** | 已推出。 |


## Related topics

- [IGameInputDevice::GetTouchSurfaceCount](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_gettouchsurfacecount.md)
- [IGameInputReading::GetTouchSurfaceState](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_gettouchsurfacestate.md)
- [IGameInputReading::GetTouchContactCount](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_gettouchcontactcount.md)
- [IGameInputDevice::GetSupportedInput](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getsupportedinput.md)
- [IGameInputDevice::GetInputReportInfo](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getinputreportinfo.md)