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

> Recupera os contatos em uma superfície de toque de uma leitura de entrada.

Recupera os contatos em uma superfície de toque de uma leitura de entrada.

## Sintaxe

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

### Parâmetros

*surfaceIndex*   \_In\_\
Tipo: uint32\_t

Índice da superfície de toque. Deve ser menor que o valor retornado por [IGameInputDevice::GetTouchSurfaceCount](https://docs.xbox.com/pt-BR/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_gettouchsurfacecount.md).

*contactArrayCount*   \_In\_\
Tipo: uint32\_t

Número de elementos em *contactArray*.

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

Matriz que recebe os contatos na superfície de toque. Pode ser nula.

### Valor retornado

Tipo: uint32\_t

Se *contactArray* for nulo, retorna o número de contatos na superfície de toque. Caso contrário, retorna o número de contatos gravados em *contactArray*, que é o menor valor entre o número de contatos e *contactArrayCount*. Retorna 0 se a leitura não contiver dados de toque ou se *surfaceIndex* não for um índice de superfície válido.

## Comentários

Cada elemento de *contactArray* descreve um contato na superfície, como um dedo. Os elementos de *contactArray* que não são gravados com um contato são definidos como zero. O membro `contactId` de [GameInputTouchContact](https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/input/gameinput/structs/gameinputtouchcontact) permanece o mesmo enquanto o contato permanecer na superfície, portanto você pode usá-lo para acompanhar um contato entre leituras.

Para dimensionar *contactArray*, chame [IGameInputReading::GetTouchContactCount](https://docs.xbox.com/pt-BR/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_gettouchcontactcount.md) ou use o membro `maxContactCount` de [GameInputTouchSurfaceInfo](https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/input/gameinput/structs/gameinputtouchsurfaceinfo) para alocar uma matriz grande o suficiente para qualquer leitura. Para interpretar as coordenadas do contato, chame [IGameInputDevice::GetTouchSurfaceInfo](https://docs.xbox.com/pt-BR/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_gettouchsurfaceinfo.md) com o mesmo índice de superfície.

As leituras que contêm dados de toque incluem `GameInputKindTouch` em [IGameInputReading::GetInputKind](https://docs.xbox.com/pt-BR/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getinputkind.md).

> [!NOTE]
>
> O suporte ao toque depende do dispositivo e da plataforma.

O exemplo a seguir lê os contatos em todas as superfícies de toque de um dispositivo.

```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)
        }
    }
}
```

## Requisitos

**Cabeçalho:** GameInput.h

**Biblioteca:** gameinput.lib

**Plataformas com suporte:** Windows, consoles da família XBOX One e consoles XBOX Series

## Confira também

[Visão geral do GameInput](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-overview.md)\
[IGameInputReading](https://docs.xbox.com/pt-BR/reference/input/gameinput/interfaces/igameinputreading/igameinputreading.md)\
[IGameInputReading::GetTouchContactCount](https://docs.xbox.com/pt-BR/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_gettouchcontactcount.md)\
[IGameInputDevice::GetTouchSurfaceInfo](https://docs.xbox.com/pt-BR/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)

## Histórico de versões

| Versão | Alterações |
| - | - |
| **v4** | Introduzido. |


## Related topics

- [IGameInputReading::GetTouchContactCount](https://docs.xbox.com/pt-BR/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_gettouchcontactcount.md)
- [IGameInputDevice::GetTouchSurfaceInfo](https://docs.xbox.com/pt-BR/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_gettouchsurfaceinfo.md)
- [IGameInputDevice::GetTouchSurfaceCount](https://docs.xbox.com/pt-BR/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_gettouchsurfacecount.md)
- [GameInputKind](https://docs.xbox.com/pt-BR/reference/input/gameinput/enums/gameinputkind.md)
- [Controle de versão da API do GameInput](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-versioning.md)