GetPointerInputTransform function (winuser.h)

Gets one or more transforms for the pointer information coordinates associated with the current message.

Syntax

BOOL GetPointerInputTransform(
  [in]  UINT32          pointerId,
  [in]  UINT32          historyCount,
  [out] INPUT_TRANSFORM *inputTransform
);

Parameters

[in] pointerId

An identifier of the pointer for which to retrieve information.

[in] historyCount

The number of INPUT_TRANSFORM structures that inputTransform can point to.

This value must be no less than 1 and no greater than the value specified in historyCount of the POINTER_INFO structure returned by GetPointerInfo, GetPointerTouchInfo, or GetPointerPenInfo (for a single input transform) or GetPointerInfoHistory, GetPointerTouchInfoHistory, or GetPointerPenInfoHistory (for an array of input transforms).

If GetPointerInputTransform succeeds, inputTransform is updated with the total count of structures available. The total count of structures available is the same as the historyCount field of the POINTER_INFO structure.

[out] inputTransform

Address of an array of INPUT_TRANSFORM structures to receive the transform information. This parameter cannot be NULL.

Return value

If the function succeeds, the return value is non-zero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

A consumer of pointer input messages typically uses ScreenToClient or MapWindowPoints to convert screen coordinates to client coordinates.

If a transform is applied on the message consumer, use GetPointerInputTransform to retrieve the transform on the message consumer at the time the input occurred. The inverse of this transform can then be used to convert pointer input coordinates from screen coordinates to the client coordinates of the message consumer.

If an input transform is not associated with the input, the GetPointerInputTransform function fails with the last error set to ERROR_NO_DATA. Use ScreenToClient or MapWindowPoints instead.

The input transform does not respect any right-to-left layout setting on the input target. An application that requires adjusted coordinates for right-to-left layout must perform the right-to-left mirroring or combine an appropriate mirroring transform with the input transform.

The information returned by GetPointerInputTransform is associated with the most recent pointer message retrieved by the calling thread. When the next message is retrieved by the calling thread, the information associated with the previous message might no longer be available.

If an application calls GetPointerInfo, it can call GetPointerInputTransform with the same pointer Id and a single INPUT_TRANSFORM output buffer to get the input transform associated with the data.

If an application calls GetPointerFrameInfo, it can call GetPointerInputTransform with the same pointer Id and a single INPUT_TRANSFORM output buffer to get the input transform associated with the data. The same input transform applies to the entire frame.

If an application calls GetPointerInfoHistory, it can call GetPointerInputTransform with the same pointer Id and an output buffer to hold the entries retrieved using GetPointerInfoHistory. Each input transform in the returned array can be used with the corresponding entry in the array returned by GetPointerInfoHistory.

If an application calls GetPointerFrameInfoHistory, it can call GetPointerInputTransform with the same pointer Id and an output buffer to hold the entries retrieved using GetPointerInfoHistory. Each input transform in the returned array can be used with the corresponding frame in the array returned by GetPointerFrameInfoHistory, with the same input transform being applied to the entire frame.

If the information associated with the message is no longer available, this function fails with the last error set to ERROR_INVALID_PARAMETER.

If historyCount contains a value larger than the historyCount field of the POINTER_INFO structure returned by GetPointerInfo (or the first POINTER_INFO structure in the array returned by GetPointerInfoHistory), the function fails with the last error set to ERROR_INVALID_PARAMETER.

Requirements

See also

Functions

INPUT_TRANSFORM