EngSetPointerTag function (winddi.h)

Article
10/13/2021

The EngSetPointerTag function is obsolete for Windows 2000 and later operating system versions. This function is still supported, but always returns FALSE.

EngSetPointerTag creates a shape that is unioned with the application's pointer shape on DrvSetPointerShape calls to other associated drivers in a mirrored system.

Syntax

ENGAPI BOOL EngSetPointerTag(
  [in] HDEV     hdev,
  [in] SURFOBJ  *psoMask,
  [in] SURFOBJ  *psoColor,
  [in] XLATEOBJ *pxlo,
  [in] FLONG    fl
);

Parameters

[in] hdev

Handle to the device. This handle is the GDI handle received by the driver as the hdev parameter for DrvCompletePDEV.

[in] psoMask

Pointer to a 1bpp SURFOBJ structure that describes the monochrome components of the tag. The dimensions of this bitmap determine the size of the tag. There are no implicit constraints on tag sizes, but optimal tag sizes are 32 x 32, 48 x 48, and 64 x 64 pixels. GDI removes the current tag when this value is NULL.

[in] psoColor

Pointer to a SURFOBJ structure in the same color format as the calling driver. This value can be NULL if the tag contains no color components. The color bitmap has the same width as psoInputMask and half the height.

[in] pxlo

Reserved for system use; must be set to NULL.

[in] fl

Reserved for system use; must be set to zero.

Return value

EngSetPointerTag returns TRUE when it successfully applies the tag. Otherwise, it returns FALSE. For Windows 2000 and later, this function always returns FALSE.

Remarks

A remote-control driver can call EngSetPointerTag to tag a pointer shape to denote control of the system. Once the remote-control driver sets a tag, GDI will automatically composite it with all pointer shapes generated by the system, until the driver removes or changes the tag.

The driver that calls EngSetPointerShape never gets its own tag applied to its own DrvSetPointerShape calls by GDI; only other drivers in the mirrored system get the tag applied.

If psoColor is NULL, psoMask points to a monochrome surface that is twice as high as it is wide. The top half contains the monochrome AND mask, and the bottom half contains the monochrome XOR mask.

If psoColor is not NULL, psoMask contains only the monochrome AND mask and psoColor contains the color XOR surface. This color surface must be in the same color format as the driver. GDI joins the shapes by anchoring the upper-left corners of each bitmap.

GDI makes copies of psoMask and psoColor, so the surfaces passed in by the driver can be deleted immediately after calling EngSetPointerTag.

The results of EngSetPointerTag take effect on the next pointer shape call generated by the system.

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