trunk/Doc/development/socketinput.txt

   1 Control of Dasher from a network socket
   2 = = = = = = = = = = = = = = = = = = = =
   3  - Seb Wills <saw27@mrao.cam.ac.uk>
   4    28 September 2005
   5
   6
   7 Introduction
   8 ============
   9
  10 The Dasher 'cursor', which determines the direction of zooming, and is
  11 indicated by a black square, is usually controlled by the mouse pointer,
  12 either through direct manipulation of the mouse or through other software
  13 (such as a gaze tracker) which controls the position of the pointer on the
  14 screen.
  15
  16 From version 4, Dasher also allows its cursor to be controlled via
  17 messages received from another program via a UDP socket. The other
  18 program may be running on a different computer to Dasher, with cursor
  19 position information sent over a network.
  20
  21 Socket configuration
  22 ====================
  23
  24 The UDP port number on which Dasher listens is configured in the
  25 Socket page of Dasher's preferences dialog. The preferences also
  26 contain a check-box to enable socket input. When selected, the cursor
  27 position is updated only by UDP packets (as specified below), and not
  28 by the mouse.
  29
  30 To assist with diagnosing any problems you experience when using an
  31 external application to drive Dasher, there is an option in the
  32 preferences to display debugging messages. When this option is enabled,
  33 Dasher will display messages showing the contents of all messages
  34 received through the UDP port and information about how it is processing
  35 them. Under Linux, these debug messages are printed to the console
  36 (stderr); in Windows a console window is opened when you enable this
  37 option and the messages are displayed in it.
  38
  39 Message format
  40 ==============
  41
  42 Packets sent to Dasher's UDP port should consist of one or more lines,
  43 each terminated by a newline (0x0a) character. Each line should
  44 consist of a text label, followed by other data. Dasher ignores lines
  45 which do not start with one of two particular labels which are
  46 specified in Dasher's preferences and correspond to the X and Y
  47 coordinates. (In one-dimensional mode, only the Y coordinate is used.)
  48
  49 If a line is read which begins with one of these labels, the text
  50 after the label (after skipping whitespace) is interpreted as an ASCII
  51 representation of a floating-point number, and is used to update the
  52 corresponding coordinate of the cursor position.
  53
  54 An example packet might therefore look like this:
  55
  56 XCoordinate 15.2
  57 YCoordinate -21.2
  58 OtherData 12s
  59
  60 In this example, Dasher would probably be configured with
  61 "XCoordinate" as its label for the X coordinate, and "YCoordinate" for
  62 the Y Coordinate. Individual packets do not need to contain both (or
  63 either of) an X and Y coordinate value. In this example, the "OtherData"
  64 line would be ignored by Dasher.
  65
  66 Packets may be sent as frequently as it is required to update the cursor.
  67 Since UDP does not guarantee delivery of packets, it is recommended to
  68 periodically send packets regardless of whether the values contained therein
  69 have changed. TCP support may be added in future.
  70
  71 Coordinate transformation
  72 =========================
  73
  74 In Dasher's socket input preferences, you should specify the range of
  75 values that Dasher should expect to receive for each coordinate. These
  76 are used to linearly transform values received into Dasher's internal
  77 coordinate system.
  78
  79 Assuming that you are using left-to-right writing orientation, then
  80 for the X coordinate, a value equal to the 'min' value specified in
  81 the preferences corresponds to the left-hand edge of the Dasher
  82 landscape. Ideally, 'max' corresponds to the right-hand edge, and
  83 values in-between are mapped linearly between these extremes in the
  84 obvious manner, however this is not currently (2005-11-29) the case;
  85 somebody needs to look into the various non-linearities applied to the
  86 coordinates and make socket input be treated more similarly to mouse
  87 input. For the Y coordinate, 'min' and 'max' correspond to the top and
  88 bottom of the Dasher landscape, respectively.
  89
  90 Note that you can invert the sense of an input by swapping the values
  91 for 'min' and 'max' so that 'max' is numerically smaller than 'min'. The
  92 socket input code already inverts the sense of the X coordinate, to
  93 compensate for the fact that in Dasher's internal coordinate system, the X
  94 coordinate increases to the left, whereas most people would expect it to
  95 increase to the right.
  96
  97 Values received which lie outside of the range between 'min' and 'max' are
  98 clipped to those values.
  99