Touchscreen Calibration

Certain user input devices such as touchscreens needs to be calibrated. For this, the GINPUT module provides a calibration dialog. The calibration uses a tree-point algorithm. Three calibration points (cross hairs) will show up, one after another. Each of the crosses needs to be pressed as precisely as possible. At the end a fourth calibration cross will appear in the center of the screen. This last calibration point is used to test whether the calibration was successful. If the difference between the internal read-out of the touch coordinate and the expected result is too big the process will be restarted automatically. See Tolerance for more information.

By default the calibration dialog will pop-up on every power-up unless the GINPUT module could load valid calibration data. See Storing calibration data for more information.

See Touchscreen_Calibration#Retrieving calibration data to learn how to hard-code calibration data.

Forcing calibration

It is possible to show up the calibration dialog during runtime by calling ginputCalibrateMouse().

Tolerance

The calibration dialog will perform a check to verify that the calibration process was successful by presenting a fourth calibration point at the center of the screen. When the tolerance between the expected coordinates and the actual read-outs is too big the calibration dialog will restart itself. It's the responsibility of the touchscreen driver to specify how big the tolerance may be. Hence this value can be modified in the board file. Note that there are two tolerance settings: One for the pen mode and one for the finger mode. The values specified are pixels.

#define GMOUSE_ADS7843_PEN_CALIBRATE_ERROR		8
#define GMOUSE_ADS7843_FINGER_CALIBRATE_ERROR	       14

Extreme coordinates

By default the cross-hairs of the calibration dialog will show with about 25% distance to the display border. However, for some touchscreen types it is better to place the calibration cross-hairs directly at the corners of the display. To enable this feature GINPUT_MOUSE_MAX_CALIBRATION_ERROR may be set to TRUE in the touchscreen drivers board file.

Storing calibration data

It is possible to save calibration data. This allows to calibrate a device once and load the corresponding calibration data on each startup to avoid calibrating the touchscreen on each power-up. The calibration storage interface is highly flexible and it's possible to store calibration data on any location that provides sufficient memory to save and load 24 bytes of data.

To enable the calibration data (re)storing feature GINPUT_TOUCH_USER_CALIBRATION_LOAD must be set to TRUE in the configuration configuration file.

The following function is called by the GINPUT module on initialization (when gfxInit() is being called):

LoadMouseCalibration(unsigned instance, void* data, size_t sz)

You can implement this function in your own application code to provide the GINPUT module with existing calibration data.

Note that the calibration dialog will automatically pop-up when this function returns FALSE.

The same thing applies to storing calibration data during runtime: The GINPUT module will call the following function when the calibration dialog was passed successfully:

SaveMouseCalibration (unsigned instance, const void* data, size_t sz)

You can implement this function in your own application code to save the calibration data during runtime. This function must return TRUE if the calibration data could successfully be stored and FALSE otherwise.

Note: The instance parameters it the driver instance. This is only useful when more than one touchscreen is connected to the system. This parameter can be used to save the calibration data of each individual touchscreen.