EngSetPointerShape function (winddi.h)

  • Article

The EngSetPointerShape function sets the pointer shape for the calling driver.

Syntax

ENGAPI ULONG EngSetPointerShape(
  [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
);

Parameters

[in] pso

Pointer to a SURFOBJ structure that describes the surface on which to draw.

[in] psoMask

Pointer to a SURFOBJ structure that defines the AND-XOR mask to apply to the pointer bitmap. The top half of the bitmap specifies the monochrome AND mask and the bottom half specifies the monochrome XOR mask. The pointer is the same width and half the height of the mask to which psoMask points. There are no implicit constraints on pointer sizes, but optimal pointer sizes are 32 x 32, 48 x 48, and 64 x 64 pixels. If this parameter is NULL, the pointer is transparent.

[in] psoColor

Pointer to a SURFOBJ structure that defines the colors for a color pointer. This bitmap is the same width and half the height of the bitmap to which psoMask points, and is in the same color format as the surface to which pso points. If this parameter is NULL, the pointer is monochrome.

[in] pxlo

Pointer to a XLATEOBJ structure that defines the colors in psoColor.

[in] xHot

Specifies the x coordinate of the pointer's hot spot relative to its upper-left pixel. The pixel indicated by the hot spot should be positioned at the new pointer position.

[in] yHot

Specifies the y coordinate of the pointer's hot spot relative to its upper-left pixel. The pixel indicated by the hot spot should be positioned at the new pointer position.

[in] x

Specifies the x coordinates of the new pointer position.

[in] y

Specifies the y coordinates of the new pointer position.

[in] prcl

Pointer to a RECTL structure. If non-NULL, the driver has provided a rectangle that bounds all pixels affected by the pointer on the display. GDI avoids drawing on this rectangle without first moving the pointer out of the way.

[in] fl

Specifies a set of flags that GDI should use to process this call. This parameter can be one or more of the following predefined values:

Flag Meaning
SPS_ANIMATESTART GDI should be prepared to receive a series of similarly-sized pointer shapes that will comprise an animated pointer effect.
SPS_ANIMATEUPDATE GDI should draw the next pointer shape in the animated series.
SPS_CHANGE GDI is requested to change the pointer shape.

Return value

EngSetPointerShape returns one of the following values:

Return code Description
SPS_ACCEPT_EXCLUDE
 GDI accepts the shape. GDI does not read from or write to the rectangle written at prcl without first moving the pointer out of the way.
SPS_ERROR
 GDI normally supports this shape, but failed for unusual reasons.

Remarks

The driver can call EngSetPointerShape to have GDI manage a software cursor.

There are two parts to the monochrome bitmap to which psoMask points. The first part defines the AND mask for the pointer while the second part defines the XOR mask. Taken together, these masks provide two bits of information for each pixel of the pointer image. The following truth table determines what GDI draws on the display for different values in the AND and XOR masks:

AND value XOR value Resultant Pixel
0 0 White
0 1 Black
1 0 No change in pixel
1 1 Pixel color is inverted
 

This mechanism supplies a black and white image while allowing for transparency and inversion of the pixels that make up the pointer.

Requirements

Requirement Value
Minimum supported client Available in Windows 2000 and later versions of the Windows operating systems.
Target Platform Universal
Header winddi.h (include Winddi.h)
Library Win32k.lib
DLL Win32k.sys

See also

DrvSetPointerShape

EngMovePointer

SURFOBJ

XLATEOBJ