Función DrvSetPointerShape (winddi.h)

Artículo
08/27/2023

La función DrvSetPointerShape se usa para solicitar al controlador que saque el puntero de la pantalla, si el controlador lo ha dibujado allí; para intentar establecer una nueva forma de puntero; y para colocar el nuevo puntero en la pantalla en una posición especificada.

Sintaxis

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

Puntero a una estructura SURFOBJ que describe la superficie en la que se va a dibujar.

[in] psoMask

Puntero a la estructura SURFOBJ que define la máscara AND-XOR. (La máscara AND-XOR se describe en Dibujo de punteros monocromáticos). Las dimensiones de este mapa de bits determinan el tamaño del puntero. No hay restricciones implícitas en los tamaños de puntero, pero los tamaños de puntero óptimos son 32 x 32, 48 x 48 y 64 x 64 píxeles. Si este parámetro es NULL, el puntero es transparente.

[in] psoColor

Puntero a la estructura SURFOBJ que define los colores de un puntero de color. Si este parámetro es NULL, el puntero es monocromo. El mapa de bits del puntero tiene el mismo ancho que la máscara de relleno y la mitad del alto.

[in] pxlo

Puntero a una estructura XLATEOBJ que define los colores en el colorcolor.

[in] xHot

Especifique la posición x de la zona activa del puntero en relación con su píxel superior izquierdo. El píxel indicado por la zona activa debe colocarse en la nueva posición del puntero.

[in] yHot

Especifique la posición y del punto activo del puntero en relación con su píxel superior izquierdo. El píxel indicado por la zona activa debe colocarse en la nueva posición del puntero.

[in] x

Especifique la coordenada x de la nueva posición del puntero.

[in] y

Especifique la coordenada y de la nueva posición del puntero.

[in] prcl

Especifica la estructura RECTL que indica la ubicación en la que el controlador debe escribir un rectángulo que especifique un límite ajustado para la parte visible del puntero.

[in] fl

Especifica un conjunto extensible de marcas. El controlador debe rechazar la llamada si se establecen marcas que no entiende. Este parámetro puede ser uno o varios de los siguientes valores predefinidos y uno o varios valores definidos por el controlador:

Marca	Significado
SPS_ALPHA	El puntero tiene valores alfa por píxel.
SPS_ANIMATESTART	El controlador debe estar preparado para recibir una serie de formas de puntero de tamaño similar que incluirán un efecto de puntero animado.
SPS_ANIMATEUPDATE	El controlador debe dibujar la siguiente forma de puntero en la serie animada.
SPS_ASYNCCHANGE	Este marcador está obsoleto. En el caso de los controladores heredados, el controlador debe aceptar el cambio solo si es capaz de cambiar la forma del puntero en el hardware, mientras que otro dibujo está en curso en el dispositivo. GDI usa esta opción solo si la marca de GCAPS_ASYNCCHANGE obsoleta ahora está establecida en el miembro flGraphicsCaps de la estructura DEVINFO .
SPS_CHANGE	Se solicita al controlador que cambie la forma del puntero.
SPS_FREQMASK	Se solicita al controlador que represente una pista del mouse, actualizando la imagen tantas veces por milisegundo como se indica en la expresión fl & SPS_FREQMASK. Un controlador que sea capaz de representar las rutas del mouse debe tener la marca GCAPS2_MOUSETRAILS establecida en el miembro flGraphicsCaps2 de su estructura DEVINFO .
SPS_LENGTHMASK	Se solicita al controlador que represente un final del mouse de longitud indicado por la expresión fl & SPS_LENGTHMASK. (Un final del mouse de longitud N se compone de N + 1 imágenes de cursor). Un controlador que sea capaz de representar las rutas del mouse debe tener la marca GCAPS2_MOUSETRAILS establecida en el miembro flGraphicsCaps2 de su estructura DEVINFO .

Valor devuelto

El valor devuelto puede ser uno de los siguientes valores:

Código devuelto	Descripción
SPS_ACCEPT_EXCLUDE	Está obsoleto. GDI deshabilitará el puntero del controlador y volverá a la simulación de software si el controlador devuelve este valor.
SPS_ACCEPT_NOEXCLUDE	El controlador acepta la forma. La forma se admite en hardware y GDI no se preocupa por otros dibujos sobrescribir el puntero.
SPS_DECLINE	El controlador no admite la forma, por lo que GDI debe simularla.
SPS_ERROR	Normalmente, el controlador admite esta forma, pero no se pudo realizar por motivos inusuales.

Comentarios

DrvSetPointerShape es opcional para los controladores de pantalla. Sin embargo, si se implementa esta función, también se debe implementar DrvMovePointer .

Los miembros de iUniq de las estructuras SURFOBJ a las que los puntos ppMask y dbColor son únicos para punteros únicos. El controlador puede usar esta información junto con los identificadores dhsurf únicos de estas estructuras como claves de caché para el almacenamiento en caché de cursores.

Cuando SPS_ALPHA se establece en el parámetro fl , el valor de graphMask es NULL y el colorcolor apunta a una superficie BGRA de 32bpp. El valor alfa por píxel indica la opacidad del píxel de puntero correspondiente con el píxel de escritorio debajo. El formato alfa de origen está premultiplicado; es decir, cada uno de los canales de color de la superficie de origen ya se ha multiplicado previamente con el valor alfa correspondiente, lo que elimina una operación de multiplicación en el momento de la mezcla.

Los cursores alfa predeterminados son en gran medida negro y blanco con un amplio rango de valores alfa; sin embargo, no hay ninguna restricción de color, ya que las aplicaciones pueden especificar cursores arbitrarios por sí mismos. Los tamaños de puntero alfa típicos son aproximadamente 8 píxeles más grandes en dimensión que los punteros típicos sin alfa. Esto admite el efecto de sombra, que se logra mediante un filtro de desenfoque que expande la forma de mapa de bits del puntero resultante. La gran mayoría de punteros serán mapas de bits de 64 x 64 píxeles o más pequeños.

El controlador indica su capacidad de controlar punteros con valores alfa por píxel estableciendo la marca GCAPS2_ALPHACURSOR en el miembro flGraphicsCaps2 de la estructura DEVINFO devuelta por DrvEnablePDEV.