> ## 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/ko/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*의 요소는 0으로 설정됩니다. [GameInputTouchContact](https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/input/gameinput/structs/gameinputtouchcontact)의 `contactId` 멤버는 접촉이 표면에 남아 있는 동안 동일하게 유지되므로, 이를 사용하여 여러 판독값에 걸쳐 접촉을 추적할 수 있습니다.

*contactArray*의 크기를 지정하려면 [IGameInputReading::GetTouchContactCount](https://docs.xbox.com/ko/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/ko/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_gettouchsurfaceinfo.md)를 호출하세요.

터치 데이터가 포함된 판독값은 [IGameInputReading::GetInputKind](https://docs.xbox.com/ko/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/ko/build/core-features/common/input/overviews/input-overview.md)\
[IGameInputReading](https://docs.xbox.com/ko/reference/input/gameinput/interfaces/igameinputreading/igameinputreading.md)\
[IGameInputReading::GetTouchContactCount](https://docs.xbox.com/ko/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_gettouchcontactcount.md)\
[IGameInputDevice::GetTouchSurfaceInfo](https://docs.xbox.com/ko/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/ko/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_gettouchcontactcount.md)
- [IGameInputDevice::GetTouchSurfaceInfo](https://docs.xbox.com/ko/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_gettouchsurfaceinfo.md)
- [IGameInputDevice::GetTouchSurfaceCount](https://docs.xbox.com/ko/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_gettouchsurfacecount.md)
- [GameInputKind](https://docs.xbox.com/ko/reference/input/gameinput/enums/gameinputkind.md)
- [GameInput API 버전 관리](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-versioning.md)