GroovX readme file

See also the TUTORIAL file for more getting-started help.

Table of contents:

1. Overview

This is a C++ toolkit for writing visual psychophysics experiments. Various abstractions relating to experiments (visual objects, trials, observer responses, etc.) are implemented in C++, and are exposed through a Tcl interface as scriptable objects.

Note that sitting beside this README file is a TUTORIAL file which should contain some useful examples of how to get started actually using the program.

2. Organization of the files

The src/ directory contains subdirectories for each of the various components of the system. Packages that are configured to be loadable at run-time are found in src/pkgs/.

When the system is built, the object files go into a hierarchy within build/obj/ that parallels src/. That is, a source file src/foo/ will be compiled to build/obj/foo/bar.o.

3. Dependencies

This software requires these development packages:

The following additional packages are optional. The configure script should generally be able to detect whether you have them installed or not and set up the Makefile appropriately.

The following packages are optional, but are used in some of the scripts that use the groovx software.

4. Configuration

Configuration of GroovX is done with a standard autoconf-generated configure script. To run the script with the default options, just do:


To see a description of available configuration options, do:

       ./configure --help

Some important configuration options:

--enable-debug={no|yes} [default is yes]
determines whether to include runtime debuggability into the executable. If 'yes' (the default), then certain commands will be available in the shell to control debug verbosity and stack tracing.

--enable-aqua={no|yes} [default is no]
determines whether to use Aqua windows or X11 windows on a Mac OS X build; default is X11

--enable-readline={no|yes} [default is yes]
whether to enable readline support, which allows for command-line editing and a command history

--enable-rgba={no|yes} [default is yes]
whether to run OpenGL graphics in rgba true-color mode (instead of color-index mode)

--enable-double-buffer={no|yes} [default is yes]
whether to run OpenGL graphics in double-buffered mode (instead of single-buffer mode); double-buffering allows for smoother screen redraws with less flicker and "tearing"

--enable-direct-render={no|yes} [default is yes]
whether to run OpenGL graphics in a direct-rendering context; this means that 3-D graphics calls will use the hardware acceleration of the grapics card, if possible

--enable-werror={no|yes} [default is yes]
whether to force all compiler warnings to be errors

--with-matlab=/path/to/matlab [default is /usr/local/matlab]
give the location of a matlab installation against which some matlab interfaces can be built; if no matlab directory is given, then only stub matlab interfaces will be set up... the code will compile, but attempts to use a matlab interface will trigger a run-time error

--with-html=/path/to/html [default is ~/www/groovx/]
specifies where HTML documentation should be installed during a "make docs" invocation

5. Building

Once you have all package dependencies installed, and run the configure script, just type "make" and everything should build and install. A short test suite (takes ~10 seconds on a 1GHz Pentium III Linux machine) is run at the end of every "make" invocation.

6. Portability

This software has been built and run successfully under:

Note that for Mac OS X, you can build either for X11 (if you are running an X server such as OroborosX on your OSX box) or for Aqua (OSX's native windowing system). By default the configure script will setup for X11, but you can pass the --enable-aqua option to tell it to set up for Aqua instead.

Earlier versions of the software have been built successfully under SGI's IRIX6 and HP's HPUX 10.x, but these configurations have not been tested recently.

The software requires a reasonably C++ std-compliant compiler. Compilers that have worked successfully in the past include:

but note that the older compilers (especially g++ 2.95.x, HP aCC, and SGI MIPSpro) haven't been tested lately so it's likely that a few things will not work out-of-the-box with those compilers.

7. Contact information

Any questions about the software should be directed to its author:

     Rob Peters
     rjpeters at usc dot edu

The software described here is Copyright (c) 1998-2005, Rob Peters.
This page was generated Wed Dec 3 06:53:56 2008 by Doxygen version 1.5.5.