How to Create and Run a Basic WorldToolKit Application at CAEN

Introduction

WorldToolKit is a library of C language functions developed by the Sense8 Division of Engineering Animations Inc. for the development of virtual reality programs. This document describes how to create and run a basic WTK application using the resources of the Computer Aided Engineering Network at the University of Michigan. For more complete information, see also:

WorldToolKit Reference Manual
WorldToolKit Quick Reference Guide
WorldToolKit Installation and Hardware Guide

All three of these manuals are available on-line in PDF format ( see below. ) The first two are also available in paper form at the Media Union reserve desk. The third guide is platform dependant, and is available for each of the hardware platforms supported at the University of Michigan ( Windows NT/95/98, SGI, Sun )

Directory Structure

On Windows NT computers, the WTK files are located under S:\BIN\WTK
On the Media Union VR Lab SGI computers, the WTK files are located under /disk1/wtk
The following sub-directories are most important:
- lib: This directory holds the library files to be linked.
- include: This directory holds the header files to be #included.
- models: This directory ( and subdirectories thereof ) hold the 3-D models used by the sample and demo programs.
- images: Similar to "models", holding the relevent texture map files.
- doc: Holds PDF format versions of all documentation.
- demo: Holds demo programs, in both executable and source formats.
- examples: More example files, in source version only.

Environment Variables

WTKCODES: In order for any WTK program to run, this environment variable must point to the main WTK directory. e.g. "set WTKCODES=S:\BIN\WTK".
WTMODELS: This variable, in the form of a PATH type variable, lists directories in which to look for 3-D model files. It typically includes the models subdirectory, e.g. S:\BIN\WTK\MODELS.
WTIMAGES: Similar to WTMODELS, this variable lists directories in which to look for texture maps. It typically includes the images subdirectory, e.g. S:\BIN\WTK\IMAGES.
Additional environment variables are described in the Reference Manual.

How to Create a Basic Application under Windows NT

Launch the Microsoft Visual Studio C++ Development System.
From the File menu, select New, and then pick a Win32 Console Application.
( Other types are possible, but are beyond the scope of this section. )
1. Under "Location", type in the parent directory of the directory you wish to work in. ( Microsoft will automatically create a subdirectory in the next step. ) e.g. H:\eng591
2. Under "Project Name", type in a name for this project, with no extension, e.g. "bareVR".
3. Select radio buttons for "Create new workspace" and "Empty Project".
From the Project menu, select "Add to Project" and "Files". Then specify the names of the source filse that are needed for your program.
1. If the files already exist in the correct directory, they can be selected from a list.
2. Otherwise they can be typed in. In the latter case the computer will ask whether you wish to add the files to the project even though they don't exist.
3. Files used in this step can either be demo or example files that you have copied into your own directory, or your original source code.
From the Project menu, select Settings:
1. On the C/C++ Tab:
  1. In the Preprocessor Section, for All Configurations, under "Additional Include Directories", type in "S:\BIN\WTK\INCLUDE".
  2. In the Code Generation Section:
    1. For the "Release" configuration, select "Multithreaded DLL"
    2. For the "Debug" configuration, select "Debug Multithreaded DLL"
2. On the Link Tab, under the "Input" section:
  1. For all configurations, under "Additional Library Path", type in "S:\BIN\WTK\LIB".
  2. For all configurations, under "Object Library Modules" add the following AFTER the modules that are already listed ( i.e. do not delete any of the listed modules ) : "opengl32.lib wsock32.lib, winmm.lib, wtk.lib".
  3. Under "Ignore Modules":
    1. For the "Release" configuration, type in "libc.lib, libcmt.lib"
    2. For the "Debug" configuration, type in "libc.lib, libcmt.lib, msvcrt.lib"
From the Build menu, select "Rebuild All". Further development may implement "Build" or "Run", as appropriate. You may also want to choose "Select Active Configuration" from the Build menu.
The resulting application can be run either from within the development studio, or using any of the normal methods for running programs under Windows.

How to Create a Basic Application under UNIX
( In the Media Union VR Lab )

The linked makefile will make an executable WTK application from a source file ending in ".c". For example, to create the executable "bareVR" from a source file "bareVR.c", type

make bareVR

It is also necessary to set three environment variables, WTKCODES, WTMODELS, and WTIMAGES. For example:

setenv WTKCODES /disk1/wtk
setenv WTMODELS /disk1/wtk/models
setenv WTIMAGES /disk1/wtk/images

Note, that the first of these variables begins with "WTK", and the other two with "WT" ( no K ).

The PATH environment variable on these machines does not normally include the current directory, so in order to run the resulting executable, it is necessary to preface the program name with "./", i.e. "./bareVR".

You may wish to edit your ".login" or ".cshrc" files to set the WT environment variables, and possibly also the PATH variable.

Note: As of 28 September 1999, WTK is only loaded on Indigos 1, 2, 4, and 5, and on Aegaeon. WTK eventually should be on all the SGIs in the VR Lab.

How to Navigate in a WTK Application

Navigation in virtual worlds is a basic skill that seems to cause many people difficulty. Many people would like to simply point to where they want to go and have the computer move them there. Unfortunately there are several reasons why the default WTK navigation does not work that way.

Instead, all motion is done with the mouse, based upon the position of the mouse cursor relative to the center of the screen. The amount of movement is related to the distance from the center - there is no motion when the mouse is in the center, and increasing amounts as the mouse is moved away from center. The results of pressing different mouse buttons in different parts of the screen are shown in the following diagram and table:

With the mouse
cursor located:
and holding down:

the left mouse button

the right mouse button

both mouse buttons

in the center.

does nothing

does nothing

does nothing

at the top.

moves forward

slides up ( towards ceiling. )

tilts view up.

at the bottom.

moves backwards

slides down ( towards floor. )

tilts view down.

to the left.

turns to the left

slides to the left

tilts clockwise

to the right.

turns to the right

slides to the right

tilts counterclockwise

How to Create More Advanced Applications

The WorldToolKit Installation and Hardware Guide provides information on the libraries and options required for more advanced programs, such as those involving MFC or GUI interfaces.

With the mouse cursor located:	and holding down:
With the mouse cursor located:	the left mouse button	the right mouse button	both mouse buttons
in the center.	does nothing	does nothing	does nothing
at the top.	moves forward	slides up ( towards ceiling. )	tilts view up.
at the bottom.	moves backwards	slides down ( towards floor. )	tilts view down.
to the left.	turns to the left	slides to the left	tilts clockwise
to the right.	turns to the right	slides to the right	tilts counterclockwise