Função DrvSetPointerShape (winddi.h)

Artigo
08/27/2023

A função DrvSetPointerShape é usada para solicitar que o driver tire o ponteiro da exibição, se o driver a tiver desenhado lá; para tentar definir uma nova forma de ponteiro; e para colocar o novo ponteiro na exibição em uma posição especificada.

Sintaxe

ULONG DrvSetPointerShape(
  [in] SURFOBJ  *pso,
  [in] SURFOBJ  *psoMask,
  [in] SURFOBJ  *psoColor,
  [in] XLATEOBJ *pxlo,
  [in] LONG     xHot,
  [in] LONG     yHot,
  [in] LONG     x,
  [in] LONG     y,
  [in] RECTL    *prcl,
  [in] FLONG    fl
);

Parâmetros

[in] pso

Ponteiro para uma estrutura SURFOBJ que descreve a superfície na qual desenhar.

[in] psoMask

Ponteiro para a estrutura SURFOBJ que define a máscara AND-XOR. (A máscara AND-XOR é descrita em Desenhando Ponteiros Monocromáticos.) As dimensões desse bitmap determinam o tamanho do ponteiro. Não há restrições implícitas em tamanhos de ponteiro, mas os tamanhos de ponteiro ideais são 32 x 32, 48 x 48 e 64 x 64 pixels. Se esse parâmetro for NULL, o ponteiro será transparente.

[in] psoColor

Ponteiro para a estrutura SURFOBJ que define as cores de um ponteiro de cor. Se esse parâmetro for NULL, o ponteiro será monocromático. O bitmap do ponteiro tem a mesma largura que psoMask e metade da altura.

[in] pxlo

Ponteiro para uma estrutura XLATEOBJ que define as cores em psoColor.

[in] xHot

Especifique a posição x do ponto de acesso do ponteiro em relação ao pixel superior esquerdo. O pixel indicado pelo ponto de acesso deve ser posicionado na nova posição do ponteiro.

[in] yHot

Especifique a posição y do ponto de acesso do ponteiro em relação ao pixel superior esquerdo. O pixel indicado pelo ponto de acesso deve ser posicionado na nova posição do ponteiro.

[in] x

Especifique a coordenada x da nova posição do ponteiro.

[in] y

Especifique a coordenada y da nova posição do ponteiro.

[in] prcl

Especifica a estrutura RECTL que indica o local em que o driver deve gravar um retângulo que especifica um limite apertado para a parte visível do ponteiro.

[in] fl

Especifica um conjunto extensível de sinalizadores. O driver deve recusar a chamada se algum sinalizador estiver definido que ele não entenda. Esse parâmetro pode ser um ou mais dos seguintes valores predefinidos e um ou mais valores definidos pelo driver:

Sinalizador	Significado
SPS_ALPHA	O ponteiro tem valores alfa por pixel.
SPS_ANIMATESTART	O driver deve estar preparado para receber uma série de formas de ponteiro de tamanho semelhante que serão compostas por um efeito de ponteiro animado.
SPS_ANIMATEUPDATE	O driver deve desenhar a próxima forma de ponteiro na série animada.
SPS_ASYNCCHANGE	Esse sinalizador é obsoleto. Para drivers herdados, o driver só deverá aceitar a alteração se for capaz de alterar a forma do ponteiro no hardware enquanto outro desenho estiver em andamento no dispositivo. O GDI usará essa opção somente se o sinalizador GCAPS_ASYNCCHANGE agora obsoleto estiver definido no membro flGraphicsCaps da estrutura DEVINFO .
SPS_CHANGE	O driver é solicitado a alterar a forma do ponteiro.
SPS_FREQMASK	O driver é solicitado a renderizar uma trilha do mouse, atualizando a imagem quantas vezes por milissegundos conforme indicado na expressão fl & SPS_FREQMASK. Um driver capaz de renderizar trilhas de mouse deve ter o sinalizador GCAPS2_MOUSETRAILS definido no membro flGraphicsCaps2 de sua estrutura DEVINFO .
SPS_LENGTHMASK	O driver é solicitado a renderizar uma trilha de comprimento do mouse indicada pela expressão fl & SPS_LENGTHMASK. (Uma trilha de comprimento N do mouse é composta por N + 1 imagens de cursor.) Um driver capaz de renderizar trilhas de mouse deve ter o sinalizador GCAPS2_MOUSETRAILS definido no membro flGraphicsCaps2 de sua estrutura DEVINFO .

Retornar valor

O valor retornado pode ser um dos seguintes valores:

Código de retorno	Descrição
SPS_ACCEPT_EXCLUDE	Está obsoleto. A GDI desabilitará o ponteiro do driver e reverter para a simulação de software se o driver retornar esse valor.
SPS_ACCEPT_NOEXCLUDE	O driver aceita a forma. A forma tem suporte no hardware e a GDI não está preocupada com outros desenhos substituindo o ponteiro.
SPS_DECLINE	O driver não dá suporte à forma, portanto, a GDI deve simpá-la.
SPS_ERROR	O driver normalmente dá suporte a essa forma, mas falhou por motivos incomuns.

Comentários

DrvSetPointerShape é opcional para drivers de exibição. No entanto, se essa função for implementada, o DrvMovePointer também deverá ser implementado.

Os membros iUniq das estruturas SURFOBJ às quais psoMask e psoColor apontam são exclusivos para ponteiros exclusivos. O driver pode usar essas informações em conjunto com os identificadores dhsurf exclusivos dessas estruturas como chaves de cache para cache de cursor.

Quando SPS_ALPHA é definido no parâmetro fl , psoMask é NULL e psoColor aponta para uma superfície BGRA de 32bpp. O valor alfa por pixel indica a opacidade do pixel de ponteiro correspondente com o pixel da área de trabalho abaixo. O formato alfa de origem é pré-multiplicado; ou seja, cada um dos canais de cor da superfície de origem já foi pré-multiplicado com o valor alfa correspondente, eliminando assim uma operação de multiplicação no momento da mistura.

Os cursores alfa padrão são em grande parte pretos e brancos com uma grande variedade de valores alfa; no entanto, não há restrição de cor, pois os aplicativos podem especificar cursores arbitrários por conta própria. Os tamanhos típicos do ponteiro alfa são aproximadamente 8 pixels maiores na dimensão do que os ponteiros típicos sem alfa. Isso acomoda o efeito de sombra, que é realizado por um filtro de desfoque que expande a forma de bitmap do ponteiro resultante. A grande maioria dos ponteiros será de bitmaps de 64 x 64 pixels ou menor.

O driver indica sua capacidade de manipular ponteiros com valores alfa por pixel definindo o sinalizador GCAPS2_ALPHACURSOR no membro flGraphicsCaps2 da estrutura DEVINFO retornada por DrvEnablePDEV.