$Id: README,v 1.3 2002/06/19 18:55:08 dlowder Exp $

General
=======

The idea of tslib is to have a core library that provides standardised
services, and a set of plugins to manage the conversion and filtering as
needed.

The plugins for a particular touchscreen are loaded automatically by the
library under the control of a static configuration file, ts.conf.
ts.conf gives the library basic configuration information.  Each line
specifies one module, and the parameters for that module.  The modules
are loaded in order, with the first one processing the touchscreen data
first.  For example:

  module variance xlimit=50 ylimit=50 pthreshold=100
  module dejitter xdelta=3 ydelta=2 pthreshold=100
  module linear

These parameters are described below.

With this configuration file, we end up with the following data flow
through the library:

  raw device --> variance --> dejitter --> linear --> application
                 module       module       module

You can re-order these modules as you wish, add more modules, or remove them
all together.  When you call ts_read(), the values you read are values that
have passed through the chain of filters and scaling conversions.  Another
call is provided, ts_read_raw() which bypasses all the modules and reads the
raw data directly from the device.

There are a couple of programs in the tslib/test directory which give example
usages.  They are by no means exhaustive, nor probably even good examples.
They are basically the programs I used to test this library.


Module Parameters
=================

module:	variance
----------------

Description:
  Variance filter.  Calculates the variance on the last 4 X and Y axis values
  independently, and averages the two samples with the smallest variance.

Parameters:
  xlimit
	Sets the X axis variance limit on the last 4 touch screen samples,
	in touch screen coordinates.  Variances outside this limit will
	cause 4 extra samples to be collected.

  ylimit
	Sets the Y axis variance limit on the last 4 touch screen samples,
	in touch screen coordinates.  Variances outside this limit will
	cause 4 extra samples to be collected.

  pthreshold
	Sets the pressure threshold, above which we believe the pen
	to be down.

module: dejitter
----------------

Description:
  Removes jitter on the X and Y co-ordinates.  Samples whos X and Y
  differentials are within these limits will be treated as an identical
  value, and gobbled up.

Parameters:
  xdelta
  ydelta
	Sets the minimum differential between the current and the previous
	X or Y sample.

  pthreshold

module: linear
--------------

Description:
  Linear scaling module, primerily used for conversion of touch screen
  co-ordinates to screen co-ordinates.

Parameters:
  xyswap
	interchange the X and Y co-ordinates -- no longer used or needed
	if the new linear calibration utility ts_calibrate is used.