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 values for more information.
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 values
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.
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.
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.
