List of source code files for NEWTRACK - Eric Auer, version 11/2004.
See the .h files for additional information!



usevbios.asm: NASM source code for usevbios.com ... To create the
  .com from the .asm, use "nasm -o usevbios.com usevbios.asm". You
  can use the DOS or the Linux version of NASM: http://nasm.sf.net/

oszi.asm: A small test program for the printer port A/D converter.
  Shows "oscilloscope" graphs for both A/D channels on a 320x200
  screen (in MCGA mode, make sure to use only on the primary VGA).
  The scope always uses printer port 0x378 (LPT1), no extra checks.



arch.h: Defines port I/O commands, DOS memory access macros, DOS
  interrupt call method, variable types for 8/16/32 bit signed and
  unsigned integers. If you want to port NEWTRACK to another OS,
  you will probably have to replace all code which refers to DOS
  memory or interrupts by something which accesses the driver layer
  of your OS. The port I/O can still be done directly (but e.g. in
  Linux you would have to be root for that) but - at least for
  multitasking OSes - you should use the OS drivers here as well.

tracker.h: The main header file for NEWTRACK. Contains #define
  lines for button assignments and other hardware driver parameters.
  Has all global function declarations for the .c files of the
  driver / lowlevel functions.

script.h: Defines trial processing parameters like thresholds,
  margins, trial type definition data type defLine, the wordArea
  data type and the LOG_STRING macro. Has the function declarations
  for the trial / script / layout related .c files. Trial types and
  word areas are stored in global arrays.



newtrack.c: Contains the main() function, which processes the
  command line arguments and/or prompts the operator for some
  configuration settings like the script file name. Initializes
  the rest of the system. Then, calibrate() and then do_script()
  are called. In the end, even if you abort the experiment, the log
  file buffer contents are written into the log file and the program
  ends. Do not reboot before this point or nothing will be logged.
  In FLIP mode, most driver initialization steps are skipped, active
  screen is toggled to the screen which was not active when NEWTRACK
  started, and NEWTRACK returns to the DOS prompt. This is useful for
  the VGA + VGA dual head hardware, but not for VGA + monochrome
  where you should use the DOS MODE command instead. To compile
  NEWTRACK, use the DJGPP (gcc/g++) compiler for DOS:
  [rerror error.log] gcc -Wall -O3 -s -o newtrack.exe *.c

calibr8.c: get_pixel_xy() and get_xy() functions return calibrated
  eye coordinates (calling get_raw_xy() internally) in virtual pixel
  or character coordinate units respectively. You have to call the
  calibrate() function first, which shows fixation marks interactively
  and calculates the calibration parameters from the measured raw mark
  positions. When calibrate() is called later, an eye cursor based on
  the previous calibration is displayed and the mark display is done
  in randomized order. The coordinates are adjusted by a quadratic
  factor, a normal factor and a linear offset. Normally, the quadratic
  factor should be small compared to the normal factor. The X and Y
  coordinates are kept strictly separate.



timer.c: get_ytime() function, returns a timestamp with microsecond
  precision. Uses either the CPU TimeStampCounter or the DJGPP
  uclock() function which uses the normal PC timer chip. Contains
  inline assembly code. Initializes itself on first call. The
  initialization takes up to two seconds. Pre-initialize cpu_mhz to
  bypass this, e.g. if you need no accurate timestamps or know your
  exact CPU speed already.

acquire.c: get_raw_xy() function, to read raw (0..4095 range)
  coordinates (from mouse, printer port module or DAS16 board).
  get_buttons() function, returns a bitmask of pressed buttons in
  the low byte of the returned int. The high bytes are used to
  return information about keyboard button events. Button input is
  detected on printer port device, CIO-CTR and keyboard.
  debounce() simply waits until the selected buttons have been in
  un-pressed state for a given time. get_tracking() tests the
  track loss / blink status, read through printer port module or
  DAS16 board. Functions initialize themselves on first call if
  needed. get_tracking() just returns the stored status from the
  last get_raw_xy() call. You can change some local #define lines
  to disable some of the input modes / drivers. The mouse driver
  uses mickey coordinates, not screen coordinates, so you can
  calibrate them to a resolution / sensitivity of your choice in
  the calibrate() function like all the other drivers.

dualhead.c: select_screen() function to select either of the two
  connected screens as target for subsequent screen output. Can also
  be used to blank / unblank the screens. get_resolution() function
  returns the number of lines and columns on the screens (minimum of
  both screens if different). select_screen() initializes the dual
  head output system on first call: Either VGA + monochrome or two
  (PCI/newer) VGA boards can be used. If neither is found, only one
  screen is used and dual head output is simulated by using every
  other line for the stimulus and the others for the operator display.
  The VGA / VGA mode scans the PCI (and AGP) bus to find VGA devices.
  It toggles the configuration settings to switch between two VGA
  devices later: Only one device at a time is connected to the CPU,
  and for that device, you can access the video memory. Now also
  supports running the subject screen in VESA graphics mode, while
  the operator screen is still only used in text mode. If less chars
  fit on the graphics screen than on the text screen, the right and
  bottom parts of the latter will be blanked when you switch screens.

screen.c: the generic put_string() function to draw a string on one of
  the screens, possibly highlighting the word in focus, possibly with
  an eye cursor displayed. Coordinate units are characters. This uses
  a global ScreenSeg variable which can be modified by select_screen()
  of dualhead.c for the VGA + monochrome output mode. put_string() now
  supports output in VESA graphics mode, with 8x16 font zoomed to
  16x32, or if only one screen present, 16x16. A text buffer in RAM
  allows this to happen quite fast, as only those characters where
  changes occur are redrawn. The provided clear_screen() function does
  clear the text itself, fills "what to redraw" buffers with spaces,
  and clears the VESA canvas (if applicable) to a selectable color.
  In VESA, clear_screen() also updates put_char()'s idea of "black".


chunker.c: The get_word() function is the core of the stimulus script
  parsing process. It copies the first word from the input string and
  returns a pointer to the next word. Can skip over comments and over
  protected line breaks, depending on the skipcomments boolean
  argument. At the end of a line, an empty word is returned. Comment
  lines are returned as empty word as well.

script.c: From the main program, only do_script() is called. All other
  trial processing is controlled by do_script(), which only takes a
  script input string and a pointer to an output log buffer as
  arguments.



script_d.c: Reads the stimulus definition script and extracts all
  define (trial type definition) lines. The results are stored in
  a global array errors are logged and syntactically incorrect
  define lines are not stored as trial type definitions.

trials.c: do_script_trials() loops over all trials in the stimulus
  definition script and takes care of all user interaction. Stimuli
  and gaze activation marks are displayed and the gaze analysis
  results and button presses are logged. The operator can interrupt
  trials to recalibrate the system, skip a trial or abort the whole
  experiment. Errors (e.g. in trial definitions) and timeouts are
  logged. A long file, although much of the work is done in helper
  functions e.g. in calibr8.c, analyze.c and layout.c! Image / text
  mixed trials are handled as a superset of plain text presentation
  functionality. The operator display never uses graphics mode, but
  an "ASCII arts" representation of run-time image analysis (done
  by functions in pcxshow.c) is shown for images.

layout.c: layout() selects a suitable screen layout for a given
  text string. If the text would need more lines otherwise, smaller
  side margins and spacing are used. The result of the calculations
  can be read through get_line() and get_line_ypos() which return
  a line and a suggested screen position for it, respectively. The
  line spacing depends on the total number of lines, which is returned
  by the initial layout() call. You can tell layout() to reserve space
  at the top or at the bottom of the screen. This is used during
  combined image / text presentation.

analyze.c: describe_stimulus() logs one area description line for
  each word of the current stimulus (read from the layout() results)
  to the global log buffer. It initializes the global "areas" array
  as well, storing the screen position of each word. This is called
  at the beginning of each trial, after calling layout(), from the
  main do_script_trials() loop. analyze_focus() takes eye coordinates
  (in virtual pixels) as input and returns an index into the "areas"
  array or -1, depending on which of the array elements fits the given
  eye coordinates. word_for_area() simply returns the word string
  which corresponds to a given "areas" array index. If the stimulus
  has image components, a bitmap array with image analysis results is
  consulted before checking for text hits. For coordinates inside an
  image object, a special array index depending on the object number
  is returned. Corresponding "words" are of "PCX/42" form.

fixation.c: check_fixations() logs fixations when it finds some. Call
  it at least once per millisecond. You have to use get_xy() between
  calls, to update the coordinate buffers. To initialize, pass a zero
  timestamp argument. Quite configurable. Short fixations are not
  logged, and saccades are only logged as "end of a fixation".


fileread.c: fileread() general purpose "read file to buffer" function
  with error checking. Able to prompt the user for a file name if
  none given. The buffer is allocated by fileread itself.


vesadata.h: data structures which are used to get information about
  VESA compatible VGA cards and their graphics and text modes.

vesa.h: VESA graphics putpixel16() macro and macros for other color
  depths, global VESA related variables like the palette (used for
  displaying 8 bit pixelspace data on high color screens), the
  (optionally allocated) pixelspace itself, the definition of the
  current vesa mode (a structure), a selector to access the linear
  frame buffer (lfbSel: this software needs VESA VBE 2.0 or better),
  the RGB2c macro to convert RGB colors to high color frame buffer
  pixel values. Also needed for using vesainit.

vesainit.c: The vesainit() function which does everything to enter
  a VESA graphics mode of the selected resolution, refresh rate
  (see vbe3refresh!) and depth (use "0x0" to return to text mode).
  Initializes the global vesamode structure (defined in vesa.h) and
  the lfbSel (same).

vbe3ref.c: The vbe3refresh() function modifies a VESA graphics mode
  as described by the vesamode structure to use a given horizontal
  refresh rate (must be in range 30 .. 180, unit is kHz). Rate is
  reduced if needed to get below 140 frames per second. You have
  to provide the mode number and your VGA BIOS must support VBE 3.0
  (common only for some nVidia and 3dfx based VGAs, but you can use
  SciTech Display Doctor or similar drivers for other 1990s VGAs).
  vesainit calls vbe3refresh, you shouldn't call vbe3refresh yourself.

pcxshow.c: pcxshow() displays a PCX image (which you have to load
  into RAM beforehand) on VESA graphics screen. Can also copy raw
  (1 byte per pixel) color data and a color histogram into a buffer.
  The palette data is stored globally. The user can specify the X and
  Y coordinates for the image on screen (raw pixel data corresponds
  to screen coordinates, not image coordinates!). The PCX image must
  have between 17 and 256 (max. 191 recommended colors).
  findmax() finds the biggest value in an array of uint32 numbers.
  showpalette() draws a sample of the global palette on a selectable
  position. doFill() is a recursive fill function which operates on
  the VESA pixelspace array (if one is allocated). It is used by
  imagechunker(), which takes the pixelspace color of the background
  as input and scans the pixelspace for objects, painting each object
  in another color, and returning the Y coordinate range where
  objects were found and the number of found objects (max. 250
  recommended).

