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

# IGameInputReading::GetTouchSurfaceState

> 從輸入讀數擷取觸控表面上的接觸點。

從輸入讀數擷取觸控表面上的接觸點。

## 語法

```cpp theme={null}
uint32_t GetTouchSurfaceState(
    uint32_t surfaceIndex,
    uint32_t contactArrayCount,
    GameInputTouchContact* contactArray
);
```

### 參數

*surfaceIndex*   \_In\_\
類型：uint32\_t

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

*contactArrayCount*   \_In\_\
類型：uint32\_t

*contactArray* 中的元素數目。

*contactArray*   \_Out\_writes\_to\_opt\_(contactArrayCount, return)\
類型：[GameInputTouchContact](https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/input/gameinput/structs/gameinputtouchcontact)\*

接收觸控表面上接觸點的陣列。可以是 Null。

### 傳回值

類型：uint32\_t

如果 *contactArray* 為 Null，則傳回觸控表面上的接觸點數目。否則，傳回寫入 *contactArray* 的接觸點數目，此值為接觸點數目與 *contactArrayCount* 兩者中的較小值。如果讀數不包含觸控資料，或 *surfaceIndex* 不是有效的表面索引，則傳回 0。

## 備註

*contactArray* 的每個元素描述表面上的一個接觸點，例如一根手指。*contactArray* 中未寫入接觸點的元素會設定為零。只要接觸點仍停留在表面上，[GameInputTouchContact](https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/input/gameinput/structs/gameinputtouchcontact) 的 `contactId` 成員就會保持不變，因此您可以使用它在多個讀數之間追蹤接觸點。

若要決定 *contactArray* 的大小，請呼叫 [IGameInputReading::GetTouchContactCount](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_gettouchcontactcount.md)，或使用 [GameInputTouchSurfaceInfo](https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/input/gameinput/structs/gameinputtouchsurfaceinfo) 的 `maxContactCount` 成員來配置足以容納任何讀數的陣列。若要解譯接觸點座標，請以相同的表面索引呼叫 [IGameInputDevice::GetTouchSurfaceInfo](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_gettouchsurfaceinfo.md)。

包含觸控資料的讀數會在 [IGameInputReading::GetInputKind](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getinputkind.md) 中包含 `GameInputKindTouch`。

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

下列範例會讀取裝置每個觸控表面上的接觸點。

```cpp theme={null}
void ReadTouchContacts(
    _In_ IGameInputDevice* device,
    _In_ IGameInputReading* reading) noexcept
{
    const uint32_t surfaceCount = device->GetTouchSurfaceCount();
    for (uint32_t surfaceIndex = 0; surfaceIndex < surfaceCount; ++surfaceIndex)
    {
        GameInputTouchSurfaceInfo surfaceInfo = {};
        if (FAILED(device->GetTouchSurfaceInfo(surfaceIndex, &surfaceInfo)))
        {
            continue;
        }

        std::vector<GameInputTouchContact> contacts(surfaceInfo.maxContactCount);
        const uint32_t contactCount = reading->GetTouchSurfaceState(
            surfaceIndex,
            static_cast<uint32_t>(contacts.size()),
            contacts.data());

        for (uint32_t i = 0; i < contactCount; ++i)
        {
            const GameInputTouchContact& contact = contacts[i];

            // Normalize the position to the range [0, 1].
            const float x = static_cast<float>(contact.padX) / static_cast<float>(surfaceInfo.padWidth);
            const float y = static_cast<float>(contact.padY) / static_cast<float>(surfaceInfo.padHeight);

            // Application-specific code to handle contact.contactId at (x, y)
        }
    }
}
```

## 需求

**標頭：** 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)\
[IGameInputReading](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputreading/igameinputreading.md)\
[IGameInputReading::GetTouchContactCount](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_gettouchcontactcount.md)\
[IGameInputDevice::GetTouchSurfaceInfo](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_gettouchsurfaceinfo.md)\
[GameInputTouchContact](https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/input/gameinput/structs/gameinputtouchcontact)\
[GameInputTouchSurfaceInfo](https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/input/gameinput/structs/gameinputtouchsurfaceinfo)

## 版本歷程記錄

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


## Related topics

- [IGameInputReading::GetTouchContactCount](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_gettouchcontactcount.md)
- [IGameInputDevice::GetTouchSurfaceCount](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_gettouchsurfacecount.md)
- [IGameInputDevice::GetTouchSurfaceInfo](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_gettouchsurfaceinfo.md)
- [GameInputKind](https://docs.xbox.com/zh-TW/reference/input/gameinput/enums/gameinputkind.md)
- [GameInput API 版本控制](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-versioning.md)