GetTouchValuators - aleslab/Psychtoolbox-3-aleslab-fork GitHub Wiki

event = GetTouchValuators(event, deviceInfo)

Return 'event', an augmented version of the input 'event', ie. event extended
with info about additional semantic meaning of the specified touch input event,
using device specific semantic mapping info provided in 'deviceInfo'.

1. Get 'deviceInfo' at script startup:
   deviceInfo = GetTouchDeviceInfo(deviceIndex);

2. For each retrieved touch event evt = TouchEventGet(...):
   evt = GetTouchValuators(evt, deviceInfo)

Which information is available on a given operating system/display system and
device combo is variable, but the returned event struct potentially has the
following additional fields:

.RawX = Raw device x position of touch.

.RawY = Raw device y position of touch.

.ToolX = Raw device x position of approaching tool, if detectable.

.ToolY = Raw device y position of approaching tool, if detectable.

.ToolType = Type of tool used on the surface. There are numbers for finger,
palm, and different type of styluses.

.Pressure = Pressure which the touch applies to the touch device surface,
normalized to 0.0 - 1.0 range.

.Distance = Distance from the touch surface, normalized to 0.0 - 1.0 range,
with 0.0 = contact, 1.0 = Maximally far away while still being
detectable, iow. hovering over the surface.

.TouchMajor = Length of major axis of an ellipse which approximates the shape
of the touch area, in device units.

.TouchMinor = Length of minor axis of an ellipse which approximates the shape
of the touch area, in device units.

.WidthMajor and .WidthMinor are major/minor width of an ellipse approximating
the complete object approaching the screen. The ratio TouchMajor / WidthMajor
and TouchMinor / WidthMinor can be used to approximate how close/strong a touch
is, in the absence of .Pressure or .Distance information.

.Orientation = If the touch contact area isn't circular and the hardware can
detect the orientation of a touch area, then this stores orientation
in degrees. 0 degrees = Upward pointing - aligned with positive
y-axis of the touch surface. > 0 degress = clock-wise turn, < 0
degrees = counter clock-wise turn. Many devices can not find out
orientation at all, or only if a contact is more vertical (0 deg.)
rather more horizontal (90 deg.).