GetPointerInputTransform function

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

Syntax


BOOL WINAPI GetPointerInputTransform(
  _In_   UINT32 pointerId,
  _In_   UINT32 historyCount,
  _Out_  UINT32 *inputTransform
);

Parameters

pointerId [in]

An identifier of the pointer for which to retrieve information.

historyCount [in]

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.

inputTransform [out]

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

Minimum supported client

Windows 8 [desktop apps only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Header

Winuser.h (include Windows.h)

Library

User32.lib

DLL

User32.dll

See also

Functions
INPUT_TRANSFORM

 

 

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.