DrvSetPointerShape

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,

OUT RECTL *prcl,

IN FLONG fl

);

DrvSetPointerShape is used to request the driver to:

Take the pointer off the display, if the driver has drawn it there.
Attempt to set a new pointer shape.
Put the new pointer on the display at a specified position.

Parameters

pso

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

psoMask

Points to a SURFOBJ structure that defines the AND-XOR mask. (The AND-XOR mask is described in Drawing Monochrome Pointers.) The dimensions of this bitmap determine the size of the pointer. 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.

psoColor

Points to a SURFOBJ structure that defines the colors for a color pointer. If this parameter is null, the pointer is monochrome. The pointer bitmap has the same width as psoMask and half the height.

pxlo

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

xHot, yHot

Specify the x and y positions 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.

x, y

Specify the new pointer position.

prcl

If nonnull, the driver should write 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.

fl

Specifies an extensible set of flags. The driver should decline the call if any flags are set that it does not understand. This parameter can be one or more of the following predefined values, and one or more driver-defined values:

Flag	Meaning
SPS_CHANGE	The driver is requested to change the pointer shape.
SPS_ASYNCCHANGE	The driver should accept the change only if it is capable of changing the pointer shape in the hardware while other drawing is underway on the device. GDI uses this option only if the GCAPS_ASYNCCHANGE flag is set in the flGraphicsCaps member of the DEVINFO structure.
SPS_ANIMATESTART	The driver should be prepared to receive a series of similarly-sized pointer shapes that will comprise an animated pointer effect.
SPS_ANIMATEUPDATE	The driver should draw the next pointer shape in the animated series.

Return Value

The return value can be one of the following values:

Value

Meaning

SPS_ERROR

The driver normally supports this shape, but failed for unusual reasons.

SPS_DECLINE

The driver does not support the shape, so GDI must simulate it.

SPS_ACCEPT_NOEXCLUDE

The driver accepts the shape. The shape is supported in hardware and GDI is not concerned about other drawings overwriting the pointer.

SPS_ACCEPT_EXCLUDE

The driver 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.

Comments

DrvSetPointerShape is optional for display drivers.

IN SURFOBJ *pso,
IN SURFOBJ *psoMask,
IN SURFOBJ *psoColor,
IN XLATEOBJ *pxlo,
IN LONG xHot,
IN LONG yHot,
IN LONG x,
IN LONG y,
OUT RECTL *prcl,
IN FLONG fl
);

Value	Meaning
SPS_ERROR	The driver normally supports this shape, but failed for unusual reasons.
SPS_DECLINE	The driver does not support the shape, so GDI must simulate it.
SPS_ACCEPT_NOEXCLUDE	The driver accepts the shape. The shape is supported in hardware and GDI is not concerned about other drawings overwriting the pointer.
SPS_ACCEPT_EXCLUDE	The driver 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.