Difference between revisions of "Touchscreen Calibration"
(→Retrieving calibration data) |
|||
| Line 43: | Line 43: | ||
It is possible to retrieve calibration data manually in order to hard-code them into a program. This is especially useful during the development phase. | It is possible to retrieve calibration data manually in order to hard-code them into a program. This is especially useful during the development phase. | ||
| − | The calibration data is just a struct containing six float values. In order to hard-code them the struct must be populated with the appropriate values and then be passed to the GINPUT module through the [Touchscreen_Calibration#Storing calibration data|Storing calibration data]] interface. | + | The calibration data is just a struct containing six float values. In order to hard-code them the struct must be populated with the appropriate values and then be passed to the GINPUT module through the [[Touchscreen_Calibration#Storing calibration data|Storing calibration data]] interface. |
Revision as of 23:29, 19 June 2015
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 Retrieving calibration data to learn how to hard-code calibration data.
Contents
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.
Retrieving calibration data
It is possible to retrieve calibration data manually in order to hard-code them into a program. This is especially useful during the development phase.
The calibration data is just a struct containing six float values. In order to hard-code them the struct must be populated with the appropriate values and then be passed to the GINPUT module through the Storing calibration data interface.
