Suporte a usos em descritores de relatório do digitalizador

Um Uso é o nome de um valor, botão ou coleção em um relatório HID. O host usa os seguintes usos ao extrair dados de uma caneta ou dispositivo sensível ao toque.

Membro	Descrição	?	ID	Dispositivo
X	Coordenada X da posição do contato.	Área de Trabalho	0x30	Caneta, Toque
Y	Coordenada Y da posição do contato.	Área de Trabalho	0x31	Caneta, Toque
Dica	Defina se o dedo ou a caneta estiver na superfície do digitalizador.	Digitalizador	0x42	Caneta, Toque
No intervalo	Defina quando o dedo ou a caneta é detectado ao passar o mouse sobre o digitalizador ou em contato com a superfície do digitalizador.	Digitalizador	0x32	Caneta, Toque
Confiança	Defina quando o contato é um dedo (não uma palma ou qualquer outra parte da mão que não deva disparar a entrada do dedo).	Digitalizador	0x47	Touch
Largura	Largura do contato.	Digitalizador	0x48	Touch
Altura	Altura do contato.	Digitalizador	0x49	Touch
Hora da verificação	Tempo de verificação relativo.	Digitalizador	0x56	Touch
Pressão	Quantidade de pressão que o usuário está aplicando ao ponto de contato.	Digitalizador	0x30	Caneta, Toque
Barrel	Definir se o botão no barril de uma caneta for pressionado	Digitalizador	0x44	Caneta
Azimuth	A rotação no sentido anti-horário do cursor sobre o eixo Z.	Digitalizador	0x3f	Caneta, Toque
Invert	Definido quando a extremidade oposta da caneta está passando o mouse sobre o digitalizador.	Digitalizador	0x3c	Caneta
Borracha	Definido quando a extremidade oposta da caneta estiver na superfície do digitalizador.	Digitalizador	0x45	Caneta
Inclinação X	O ângulo entre o plano Y-Z e o plano que contém o eixo do dispositivo de ponteiro e o eixo Y.	Digitalizador	0x3d	Caneta
Inclinação Y	O ângulo entre o plano X-Z e o plano do dispositivo de ponteiro; uma inclinação Y positiva é em direção ao usuário.	Digitalizador	0x3e	Caneta
Torção	Rotação no sentido horário do cursor sobre seu próprio eixo.	Digitalizador	0x41	Caneta

Nota Os usos listados na tabela acima são conhecidos pelo Windows e são entregues a aplicativos usando a mensagem WM_POINTER.

Nota Os dispositivos de ponteiro são gratuitos para dar suporte a usos adicionais (incluindo usos específicos do fornecedor). Usos adicionais não são entregues a aplicativos em mensagens WM_POINTER. O valor desses usos pode ser recuperado usando a função GetRawPointerDeviceData . Para tornar os usos acessíveis da função GetRawPointerDeviceData , os usos devem estar localizados no mesmo relatório que os usos de X e Y.

Descritor HID para digitalizadores

Começando com Windows 8, um digitalizador de toque deve aparecer como uma tela sensível ao toque (página = 0x0D, uso = 0x04). Um digitalizador de caneta deve aparecer como uma caneta integrada (página = 0x0D, uso = 0x02) ou uma caneta externa (página = 0x0D, uso = 0x01). Os dispositivos de toque e caneta integrados são mapeados para a tela à qual estão fisicamente conectados. Os dispositivos de caneta externa são mapeados para a área de trabalho virtual.

Usos de HID necessários para digitalizadores

Os usos a seguir são necessários para todos os digitalizadores. Os dispositivos que não dão suporte a todos os usos necessários não funcionarão em Windows 8:

X e Y
X e Y relatam as coordenadas de contato. Em Windows 8, um dispositivo pode relatar dois pontos para cada contato. O primeiro ponto (conhecido como T) é considerado o ponto que o usuário pretendia tocar enquanto o segundo ponto (conhecido como C) é considerado o centro do contato. Os dispositivos capazes de relatar T e C devem ter uma matriz de uso de dois valores X e dois valores Y. Os valores na primeira posição nas matrizes são interpretados como as coordenadas de T e os valores na segunda posição são interpretados como as coordenadas de C. (a contagem de relatórios para ambos os usos é 2 para indicar a presença de uma matriz de uso). Os dispositivos que relatam C também devem relatar os usos de Largura e Altura . O host usa C para criar o retângulo delimitador em torno do contato. Se o dispositivo relatar apenas um par X e Y, o host usará esse par para T e C. O descritor de toque de exemplo inclui matrizes de uso para X e Y. Os extratos a seguir do descritor de exemplo ilustram a diferença entre um dispositivo que dá suporte apenas a T e um dispositivo que dá suporte a T e C.

Um dispositivo que relata apenas T não deve ter uma matriz de uso para as propriedades X e Y (ou seja, a contagem de relatórios para cada uso é 1, conforme indicado no seguinte.)

0x05, 0x01,                         //       USAGE_PAGE (Generic Desk..
    0x26, 0xff, 0x0f,                   //       LOGICAL_MAXIMUM (4095)         
    0x75, 0x10,                         //       REPORT_SIZE (16)             
    0x55, 0x0e,                         //       UNIT_EXPONENT (-2)           
    0x65, 0x13,                         //       UNIT(Inch,EngLinear)                  
    0x09, 0x30,                         //       USAGE (X)                    
    0x35, 0x00,                         //       PHYSICAL_MINIMUM (0)         
    0x46, 0xb5, 0x04,                   //       PHYSICAL_MAXIMUM (1205)
    0x95, 0x01,                         //       REPORT_COUNT (1)         
    0x81, 0x02,                         //       INPUT (Data,Var,Abs)         
    0x46, 0x8a, 0x03,                   //       PHYSICAL_MAXIMUM (906)
    0x09, 0x31,                         //       USAGE (Y)                    
    0x81, 0x02,                         //       INPUT (Data,Var,Abs)

Um dispositivo que dá suporte a T e C usa matrizes de uso para relatar os valores X e Y. A contagem de relatórios para X e Y é 2.

0x05, 0x01,                         //       USAGE_PAGE (Generic Desk..
    0x26, 0xff, 0x0f,                   //       LOGICAL_MAXIMUM (4095)         
    0x75, 0x10,                         //       REPORT_SIZE (16)             
    0x55, 0x0e,                         //       UNIT_EXPONENT (-2)           
    0x65, 0x13,                         //       UNIT(Inch,EngLinear)                  
    0x09, 0x30,                         //       USAGE (X)                    
    0x35, 0x00,                         //       PHYSICAL_MINIMUM (0)         
    0x46, 0xb5, 0x04,                   //       PHYSICAL_MAXIMUM (1205)
    0x95, 0x02,                         //       REPORT_COUNT (2)         
    0x81, 0x02,                         //       INPUT (Data,Var,Abs)         
    0x46, 0x8a, 0x03,                   //       PHYSICAL_MAXIMUM (906)
    0x09, 0x31,                         //       USAGE (Y)                    
    0x81, 0x02,                         //       INPUT (Data,Var,Abs)

Nota Esses exemplos aproveitam a regra HID de que os itens globais permanecem os mesmos para cada item main até serem alterados. Isso permite que os usos X e Y compartilhem apenas uma entrada para a contagem de relatórios.

Os dispositivos de caneta devem usar o primeiro exemplo para seus descritores, pois C não é relevante para esses dispositivos.

Os seguintes itens globais devem ser especificados para os usos X e Y :

• Mínimo lógico
• Máximo lógico
• Mínimo físico
• Máximo físico
• Unidade
• Expoente de unidade

O alcance físico do dispositivo e das unidades precisa ser relatado com precisão. Se as informações forem imprecisas, o dispositivo não funcionará corretamente. Os dispositivos também precisam relatar dados dentro do alcance lógico especificado no descritor de relatório. Qualquer valor relatado fora desse alcance será considerado como dados inválidos e o valor será alterado para o valor de limite mais próximo (mínimo lógico ou máximo lógico).

Ponta
Use a opção Dica para indicar o contato de dedo ou caneta e a decolagem da superfície do digitalizador. Deve haver um item main com um tamanho de relatório igual a 1. Ao fornecer relatórios, a posição do bit deve ser definida quando o dedo ou a caneta estiver em contato com a superfície do digitalizador. Caso contrário, o bit deverá ser limpo.

Tempo de Verificação
O Tempo de Verificação relata o tempo relativo em unidades de 100 microssegundos. Ele representa o delta em relação ao primeiro quadro relatado quando um dispositivo começa a relatar dados após um período de inatividade. O primeiro tempo de digitalização recebido é tratado como o tempo base dos próximos tempos relatados. Os deltas entre os tempos de verificação relatados devem refletir a frequência de verificação do digitalizador. É importante observar que, ao contrário de outros usos, o host não permite nenhuma flexibilidade na unidade do uso do tempo de varredura. Espera-se que o valor seja revertido, pois apenas 1 byte é alocado para o contador. O valor de tempo de varredura deve ser o mesmo para todos os contatos dentro de um quadro. Esse requisito também se aplica a dispositivos que relatam dados usando o modo híbrido

Nota Esse uso só é necessário para dispositivos touch.

No intervalo
Se o dispositivo der suporte à detecção do eixo Z, o digitalizador deverá definir o uso no intervalo no relatório de entrada quando o transdutor estiver dentro da região em que a digitalização for possível. Se o dispositivo não der suporte à detecção do eixo Z, o driver não deverá incluir o uso no intervalo em seu descritor de relatório.

Versões anteriores do Windows têm diretrizes diferentes sobre como os drivers de digitalizador de toque devem lidar com relatórios no intervalo.

Os dispositivos que dão suporte a caneta e toque devem dar suporte a estados NULL para os usos X e Y na coleção de nível superior da caneta. Quando a caneta é detectada em uma altura em que os valores X e Y não podem ser detectados com precisão, o dispositivo deve relatar valores NULL para X e Y e definir o uso no intervalo . Valores NULL simplesmente significam valores fora do intervalo lógico especificado para esses usos, desde que o dispositivo tenha indicado que dá suporte a NULL para o uso relevante. Em seguida, o dispositivo pode relatar valores X e Y precisos depois que a caneta estiver próxima o suficiente da superfície para tornar isso possível. Esse protocolo permite que o host implemente a rejeição da palma da mão quando a caneta estiver no intervalo.

Deve-se observar que o host reconhecerá os valores fora do intervalo lógico como significando a implementação desse protocolo somente se o descritor de relatório incluir especificamente o bit que significa o fato de que X e Y dão suporte a estados NULL . Caso contrário, os valores fora do intervalo lógico são simplesmente movidos para o valor de limite mais próximo. Os extratos a seguir de descritores de relatório ilustram a diferença entre um dispositivo que dá suporte a NULL para X e Y e um que não dá. Deve-se observar que o suporte NULL só é necessário na coleção de nível superior da caneta. Coleções de nível superior de toque não precisam dar suporte a NULL para X e Y para essa finalidade.

Extração de relatório com suporte NULL para X e Y:

0x05, 0x01,                         //     USAGE_PAGE (Generic Desktop) 42
    0x09, 0x30,                         //     USAGE (X)                    44
    0x75, 0x10,                         //     REPORT_SIZE (16)             46
    0x95, 0x01,                         //     REPORT_COUNT (1)             48
    0xa4,                               //     PUSH                         50
    0x55, 0x0d,                         //     UNIT_EXPONENT (-3)           51
    0x65, 0x13,                         //     UNIT (Inch,EngLinear)        53
    0x35, 0x00,                         //     PHYSICAL_MINIMUM (0)         55
    0x46, 0x3a, 0x20,                   //     PHYSICAL_MAXIMUM (8250)      57
    0x26, 0xf8, 0x52,                   //     LOGICAL_MAXIMUM (21240)      60
    0x81, 0x42,                         //     INPUT (Data,Var,Abs)         63
    0x09, 0x31,                         //     USAGE (Y)                    65
    0x46, 0x2c, 0x18,                   //     PHYSICAL_MAXIMUM (6188)      67
    0x26, 0x6c, 0x3e,                   //     LOGICAL_MAXIMUM (15980)      70
    0x81, 0x42,                         //     INPUT (Data,Var,Abs)         73

Extração de relatório sem suporte NULL para X e Y:

0x05, 0x01,                         //       USAGE_PAGE (Generic Desk..
    0x26, 0xff, 0x0f,                   //       LOGICAL_MAXIMUM (4095)         
    0x75, 0x10,                         //       REPORT_SIZE (16)             
    0x55, 0x0e,                         //       UNIT_EXPONENT (-2)           
    0x65, 0x13,                         //       UNIT(Inch,EngLinear)                  
    0x09, 0x30,                         //       USAGE (X)                    
    0x35, 0x00,                         //       PHYSICAL_MINIMUM (0)         
    0x46, 0xb5, 0x04,                   //       PHYSICAL_MAXIMUM (1205)
    0x95, 0x01,                         //       REPORT_COUNT (1)         
    0x81, 0x02,                         //       INPUT (Data,Var,Abs)         
    0x46, 0x8a, 0x03,                   //       PHYSICAL_MAXIMUM (906)
    0x09, 0x31,                         //       USAGE (Y)                    
    0x81, 0x02,                         //       INPUT (Data,Var,Abs)

Consulte a seção Suporte a Toque e Caneta para obter um descritor completo de um dispositivo de caneta que dá suporte a valores NULL para X e Y.

Nota Esse uso é necessário para todos os dispositivos de caneta, mas é opcional para dispositivos touch.

Usos opcionais de HID

Os usos a seguir são opcionais, mas você deve implementá-los se o hardware do digitalizador der suporte a eles. Os digitalizadores que não dão suporte a esses usos não devem incluí-los no descritor de relatório.

Largura e Altura
Os usos de Largura e Altura representam a largura e a altura da caixa delimitadora ao redor do contato por toque. Os valores relatados nunca devem ser 0, exceto quando um evento "UP" está sendo relatado, nesse caso eles devem ser 0.

Width e Height também são expostos aos desenvolvedores de aplicativos por meio da mensagem WM_POINTER.

Confiança
Confiança é uma sugestão do dispositivo sobre se o contato de toque foi um toque pretendido ou acidental. Se você estiver confiante de que o toque se destina, defina o uso de confiança como 1 (true). O dispositivo deve rejeitar toques acidentais ao máximo possível enquanto a latência permanece no intervalo necessário. Se você não tiver certeza de que o toque se destina e seu dispositivo não rejeitou o toque como acidental, defina o uso de confiança como 0 (falso). Se o dispositivo sempre rejeitar toques acidentais, você não precisará incluir o uso de confiança.

Pressão
A pressão é uma medida da força que o dedo ou a caneta exerce contra a superfície do digitalizador. Não há restrições de intervalo permitido para pressão. No entanto, o intervalo especificado por um dispositivo será normalizado para um intervalo de 0 a 1024 ao fornecer dados para aplicativos cliente.

Barril
O barril deve ser definido quando o botão de barril da caneta é pressionado. Caso contrário, ele deverá ser redefinido. Barrel é usado pelo Windows para modificar a função da dica para uma ação primária (toque, arrastar) ou uma ação secundária (toque direito, arrastar para a direita).

Embora Pressure e Barrel sejam usos opcionais, é recomendável implementá-los para digitalizadores de caneta. Valor adicional é adicionado para esses usos: a pressão define a largura do traço da caneta, tornando-a mais realista e a opção de barril permite a funcionalidade do botão direito do mouse ao usar a caneta.

Inclinação X
X Tilt representa o ângulo do plano entre o plano Y-Z e o plano que contém o eixo do transdutor e o eixo Y.

O alcance físico e o alcance lógico precisam ser especificados. O intervalo físico deve ser -90 a 90. O alcance lógico precisa ser grande o suficiente para fornecer dados com a precisão de pelo menos duas casas decimais. Radianos também podem ser usados para o intervalo físico. A lista a seguir mostra uma combinação lógica e física típica.

• Mínimo lógico: -9000
• Máximo lógico: 9000
• Unidade: Graus
• Expoente de Unidade: -2
• Mínimo físico: -9000
• Máximo físico: 9000

Inclinação Y
Y Tilt representa o ângulo do plano entre o plano X-Z e o plano que contém os planos X transdutor.

O alcance físico e o alcance lógico precisam ser especificados. O intervalo físico deve estar entre –90 e 90. O alcance lógico precisa ser grande o suficiente para fornecer dados com a precisão de pelo menos duas casas decimais. Radianos também podem ser usados para o intervalo físico. A lista a seguir mostra uma combinação lógica e física típica.

• Mínimo lógico: 0
• Máximo lógico: 18000
• Unidade: Graus
• Expoente de Unidade: -2
• Mínimo físico: -9000
• Máximo físico: 9000

Torção
Twist especifica a rotação no sentido horário do cursor em torno de seu próprio eixo principal.

O alcance físico e o alcance lógico precisam ser especificados. O intervalo físico deve ser de 0 a 360. O alcance lógico precisa ser grande o suficiente para fornecer dados com a precisão de pelo menos duas casas decimais. Radianos também podem ser usados para o intervalo físico. Nesse caso, o intervalo lógico deve ser grande o suficiente para relatar valores precisos para pelo menos quatro casas decimais. A lista a seguir mostra uma combinação lógica e física típica.

• Mínimo lógico: 0
• Máximo lógico: 62831
• Unidade: Radianos
• Expoente de unidade: -4
• Mínimo físico: 0
• Máximo físico: 62831

Azimute
Azimuth especifica a rotação no sentido anti-horário do cursor ao redor do eixo Z por meio de um intervalo circular completo. O alcance físico e o alcance lógico precisam ser especificados. O intervalo físico deve ser de 0 a 360, no entanto, o dispositivo pode relatar o intervalo completo ou metade do intervalo supondo que as reticências de toque sejam simétricas com base nos recursos de hardware. O alcance lógico precisa ser grande o suficiente para fornecer dados com a precisão de pelo menos duas casas decimais. Radianos também podem ser usados para o intervalo físico. Nesse caso, o intervalo lógico deve ser grande o suficiente para relatar valores precisos para pelo menos 4 casas decimais. A lista a seguir mostra uma combinação lógica e física típica.

• Mínimo lógico: 0
• Máximo lógico: 36000
• Unidade: Graus
• Expoente de Unidade: -2
• Mínimo físico: 0
• Máximo físico: 36000

Nota O Expoente de Unidade deve ser -2 quando Unit for Degrees e -4 quando Unit for Radians.