Library reference


The following is an alphabetical list of all the VRUT functions. To access a function, the VRUT library must first be loaded with "import vrut". Some functions need you to pass predefined constants which are always fully capitalized. Both functions and constants must be prefixed with "vrut.". Remember, python is case-sensitive.
 
addchild Import a 3D model(VRML file)
addsensor Connect toa sensor device (eg. tracker)
addtexture Load a textureimage into memory
appearance Change theappearance of a child object
callback Register a callbackfunction for handling user interaction
clamp Constrain or or bodyposition/orientation
clearall Completely clear the VRUT internal environment
clearcolor Change the background clear color
cursor Set the visibilityof the system mouse cursor
curtain Set the visibilityof the the screen or objects
disable Turn off a GLstate variable
enable Turn on a GL statevariable
endlayer Stop buildingon-the-fly geometry
execute Run a Python statementwith the internal interpreter
framerate Show the frame-rate
fog Activate and change fogging
get Return values of variousstate variables
go Start VRUT
linewidth Change theline width of on-the-fly geometry
messagecolor Changecolor of 3D message
mouse Set the state of mouseprocessing
movie Start an animatedtexture movie
playback Play back aviewpoint recording file
playsound Play a soundfile over the speakers
pointsize Change thepoint size of on-the-fly geometry
pushscroll Start a3D scroll menu
override Turn off DECALmode and remove standard lighting
quit Exit VRUT as gracefullyas possible
reset Reset the target object
rotate Rotate an objector the viewpoint
savecsb Export entire scene as optimized Cosmo binary file
scale Scale an object
setaspect Configurethe screen horz.-to-vert. aspect ratio
setclip Set the near andfar clipping planes
setfov Set the perspectivefield-of-view
setipd Set the simulatedinterpupilary distance for stereo
setscene Set which scene gets rendered
showmessage Show 3Dtext string
starthotspot Begin monitoring a hotspot
startlayer Start building on-the-fly geometry
starttimer Turn onan expiration timer
tracker Attach to connectedtracker to the viewpoint
translate Translatean object or the viewpoint
version Print versionsof VRUT and all linked modules
vertex Define a 3D coordinatefor on-the-fly geometry
vertexcolor Specifythe color of on-the-fly geometry



 
addchild(fileName, [anchor], [scene])
Add a VRML file to the render environment.  Anchor is not supported at this time. Also, a child can only be added at the global level of a script and not inside of a function (doing so will cause winvrut to hang) unless the code to add the child is wrapped inside a call to vrut.execute.  Supported anchors are vrut.WORLD and vrut.HEAD (default is WORLD).  In addition to the anchor, you can also specify the scene number into which the child is to be added (default is scene#1).  Currently, only scene numbers 1 and 2 are supported.
Supported methods:

    addchild(fileName)
    alpha([alphaValue]) - set alpha level for transparency, or no arg. for blending
    appearance(flags)
    center(x, y, z)
    copy() - create an independent copy of child (an efficient mechanism for avoiding texture reloads)
    clone() - create an dependent copy of child (certain appearance properties are shared across all clones)
    curtain(state)
    getchild(objectName)
    movie(texture, objectName, [rate], [duration], [loopMode], [transparency])
    rotate(x, y, z, deg)
    scale(x, y, z)
    stats() - print out polygon statistics
    sensor(sensorObject) - attach specified to sensor
    texture(textureObject, objectName) - apply specified texture
    translate(x, y, z)
 

Use getchild() to gain access to a sub-child that is contained within the "parent" child object.  Often 3D modeling software will allow you to name objects that you build as part of your scene.  If you want to have independent control over the separate objects in the scene, you can choose to either save each of these objects as separate VRML files, or by using this command you can save everything as a single VRML file and later during VRUT runtime extract the sub-child nodes and then use commands such as "curtain", "rotate", and "translate" on them.
 

addmail([privateAddress] | [mailCode])
Start the mail handling utilities.  Doing this will allow you to send a message over the local network to another computer that is also running VRUT.  This command will also activate the local receiving of mail from other computers, and if you register a MAIL_EVENT callback function, you can capture these messages and use them for controlling your local process.

Supported methods:
 

send(message, [mailCode]) - send a text string of no more the 100 characters.


UNDER DEVELOPMENT:

def mymail(message): - can I figure out who it was from within a process?

mymail = myself.addmail([mailboxNum])
 - assign given mailbox number

mymail.send(message, mailboxNum)
 

 
addsensor(type)
This is the new technique for adding sensors to the virtual environment, and will ultimately be the way trackers can be attached to object and not just the observer's eyepoint.  In version 2.1, addsensor is used to activate a sensor device (eg., headtracker) but vrut.tracker is still used to "attach" it to the head (it will attach the first available 3DOF or 6DOF sensor that has been added to the environment to the head and engage headtracking).  The type parameter allows you to specifiy what type of tracker you want.  Currently, you must specify the tracker by its plug-in name (eg., "shootingstar").  In the next version, you'll be able to just ask for sensors by their type (eg, 3DOF, 6DOF, JOYSTICK, etc.), and the system will grab the best one for that purpose.

Supported methods:

center(x,y,z) - defines the center of the sensor tranform (only applicable when attached to object)
command() - send a floating point value to the sensor object (only some sensors support signals)
get() - without a parameter, returns all raw sensor data
reset() - performs sensor's reset function
rotate(x,y,z,q) - applies rotation to sensor transform (only applicable when attached to object)
scale(x,y,z) - scales the sensor transform (only applicable when attached to object)
starthotspot() - begin monitoring a hotspot based directly on raw sensor data
addtexture(textureName)
Use this command to load a texture image into VRUT's texture cache.  Once loaded, you can apply this texture object to 3D geometry and override the object's original texture.  To do this, you'll need to refer to the name of the sub-object within the geometry file on which to apply the texture (your modeler should let you specifiy such names).  There are two ways to apply textures.  First, you can use the 3D object's method command "texture()", passing it the name of the sub-object on which to apply the texture.  Or, you can use the texture's own method "texture()" and pass it the name of the sub-object on which to globally apply this texture change.

Supported methods:

texture(objectName) - swap this texture onto all objects name "objectName" throught scene


appearance(flags)
The child method allows on-the-fly control of appearance properties.  Currently, the only properties that can be modified are texture filtering (vrut.TEXMIPMAP) and texture transparency (vrut.TRANSPARENCY).  Filtering allows the activation of linear and mipmap filtering for texture magnification and minification.  Transparency makes it possible to use texture formats that support alpha-layer transparency (TIFF, PNG, and RGBA) to create the effect of transparent surfaces. To specifiy more than one flag at a time, 'or' the flags together.  If you pass no arguments, VRUT will try to reset the object to its original settings.

callback(event, function)
Use this to register a python function that you want executed when a certain event happens. The functions must be loaded as a module with the execute command so that the functions are available callable by VRE. Note: callback function names must be less than 50 characters long.

Available events:

  1. BUTTON_EVENT - occurs when the belt control button is pressed. The called function is passed the current setting of the belt control knob.
  2. KEYBOARD_EVENT - returns a character typed into the VRE graphics window. Only printable charcters are considered events (ASCII 32-126).
  3. TIMER_EVENT - returns the timer number that expired. When a timer is started with starttimer it can be given any integer number ID that is desired. See starttimer
  4. PLAYBACK_EVENT - returns nothing, but is triggered when a playback file has completed. See playback.
  5. RECORD_EVENT - returns nothing, but istriggered when a recording session has reach the maximum duration. See record.
  6. HOTSPOT_EVENT - occurs when the user enters a defined hotspot. The hotspot ID is returned to the called function.
  7. MENU_EVENT - occurs when the user selects from a menu generated by the pushscroll command. The called function is passed the text of the menu item selected.
  8. MOUSEBUTTON_EVENT - occurs when one of the buttons on the mouse is pressed.  Values returned are vrut.MOUSEBUTTON_LEFT and vrut.MOUSEBUTTON_RIGHT.
  9. MOUSEMOVE_EVENT - occurs when the mouse is moved.  This could put a load on the processor, so data is not actually transmitted unless a function is used to activate the callback:  use vrut.mouseScroll() to begin reading integer values that specify whether mouse was moved up or down after a trial is finished and you are ready to record a subject's response.  Use vrut.mouseMotionOff() to turn off data transmission before you begin the next trial.  The callback is only registered once, and one can turn mouse input on and off repeatedly.  (See mouse()).
  10. MAIL_EVENT - occurs when a mailbox handling has been activated and a message has been received from another computer.
Example of setting up a callback routine to echo the keyboard:
# Must always include the VRUT library at the beginning of a file
import vrut

def myKeyboard(key):

print key
vrut.callback(vrut.KEYBOARD_EVENT, __name__'.myKeyboard')


clamp(what, p1, p2, p3)
Forces either HEAD_POS,HEAD_ORI, or BODY_ORI to take on the values passed in p1, p2, and p3. For position, specify the X, Y, and Z coordinates. For orientation, specify yaw, pitch, and roll. The clamp will remain in effect until the clamp is reset (see reset command).

clearall()
Clear all layers, states, etc.

clearcolor(r,g,b)
Sets the a new clear color. This is the color get the whole screen get erased to before a new scene is drawn. Clear the screen takes time, so if you're rendering a scene that entirely fills the screen (e.g., the inside of a room), then you should disable the screen clears and get faster rendering.

cursor([mode])
Changes the visibility of the mouse.  Without an argument, the mouse cursor visibility will switch between on and off.  To explicitly change the visibility, send vrut.START or vrut.STOP.

curtain(state)
curtain(state, anchor, layer)
Used to "open" or "close" the curtain over the graphics screen. This allows the images to be temporarily blacked out without having to pop all the models off the layer stacks. The state can be either vrut.OPEN or vrut.CLOSE. The addition form of the command are for turning off a single eye (vrut.LEFT_EYE or vrut.RIGHT_EYE).

disable(mode)
Disables the selected mode. This is equivalent to the OpenGL glDisable function and supports most of the GL_ modes: ALPHA_TEST,BLEND, COLOR_MATERIAL, CULL_FACE, DEPTH_TEST, FOG, LIGHT0, LIGHT1,LIGHT2, LIGHT3, LIGHT4, LIGHT5, LIGHT6, LIGHT7, LIGHTING, NORMALIZE, POLYGON_SMOOTH, POLYGON_STIPPLE, SCISSOR_TEST, STENCIL_TEST, TEXTURE_2D. See the OpenGL Blue Book under glEnable for information about each option.

Example:
vrut.disable(vrut.FOG) - turns off fog

enable(mode)
Enables the selected mode. This is equivalent to the OpenGL glDisable function and supports most of the GL_ modes (see disable above)

Example:
vrut.enable(vrut.LIGHT0)

endlayer()
Used to close a custom geometry layer begun with the startlayer command.

execute(command-expression)
This send the string command-expression to the VRE python interpreter. This is used in conjuction with registering callback procedures. Use this function first to load a module containing the scripts you want executed when certain events happen, such as type a key on the keyboard. See also callback.

Example:
vrut.execute('import mymodule')

framerate([status])
Framerate sends statistics to the console window.  To see of graphical plot of the statistics in the viewport, set status equal to vrut.NICE.  A call to this function with no arguments turns on the frame-rate counter in the console window.  To deactivate the output, pass vrut.OFF.

fog(start, end) or
fog(density)
Turns on the fogger. The fog equations used depend on the parameters supplied. If a start and end values are given, then linear fogging is enabled in which no fog appears before start distance from the observerand 100% density is reached at end distance from the observer. If only a density is given, then an exponential dropoff function is used (OpenGL's GL_EXP) that's continuous from 0 to infinity. In both cases, the fog color is set to the current clear color.

vrut.fog(1, 10) - enables fog from 1 to 10 meters

get(what)
Use this to retrieve information about the observer's position or orientation, or to get information about the belt knob, or to read the peripheral data channels. You specify what kind of information you want returned, and depending on what it is you'll be returned a single value or a vector of values. Some of these values are meaningless unless the network has been established with a call to vrut.inittracker(). The following table lists the options and what is returned:

HEAD_POS           x, y, z
HEAD_ORI           yaw, pitch
BODY_ORI           yaw
INITHMD            Initial state
INITSTEREO         Initial state
INITTRACKER        Initial state
INITOPTION1        Initial state
INITOPTION2        Initial state
INITMESG           Initial state
For instance, vrut.get(vrut.HEAD_POS) returns a Python vector with 3 numbers: x, y, and z. For example, just typing:
print vrut.get(vrut.HEAD_POS)
will return the following:
(0.0, 1.82, 0.0)

You can set the get result to a variable, and then access just one of the values if you like. The following example will just print out the Y value of the head position (this is the second member in the list but indexed with a '1' because Python indices always start with 0):

foo = vrut.get(vrut.HEAD_POS)
print foo[1]
and would return:
1.82


go([mode])
Use to begin the main graphics window, VRE. Without arguments, the following is assumed: vrut.CONSOLE | vrut.MONO | vrut.PERSPECTIVE. Below are the modes that are available. Only one from each group should be or'd in the mode argument to go. The first member of each group is the default. When debugging from a remote terminal, you can pass the NICE flag so that the VRE window is smaller than normal and apppears in the upper-righthand corner (in other words, you're being nice to the person who's trying to work on the console).

CONSOLE - small window on consolve montior
FULLSCREEN - take over the entire monitor with no window borders
HMD - render appropriately for use with the local helmet mounted display

MONO
STEREO

PERSPECTIVE
ORTHOGRAPHIC

PROMPT - prompt user for initial start states using a standard dialog box
NICE - place a small window in the upper-righthand corner

DEBUG - set up winvrut shared memory so that the program can be run from the debugger


linewidth([with])
Use this to change the width of line elements when creating geometries on the fly using the startlayer command.

messagecolor(messageNum, red, blue, green)
Use this command to change the color of a message that is currently visible.

mouse(mode)
Turns on/off internal mouse handling by passing vrut.START or vrut.STOP, respectively.  This function is used in either in conjunction with mouse callback events, or simply to turn off mouse processing so that the user doesn't accidentally change the viewpoint (using the default mouse navigation mode).  When mouse handling is turned on, it will trigger vrut.MOUSE_EVENTS that will return positive integer values when the mouse is moved up, and negative values when the mouse is moved down.  Values correspond to increments from the last mouse position, so absolute position is not available.   However, it does allow the user to scroll indefinitely.  By default, the cursor is turned of when mouse handling is activated (you can turn it on again with cursor()).

This function requires that a callback of type MOUSEMOVE_EVENT be registered.  Stop listening to mouse movements by calling mouse(vrut.STOP).  Suggested use: (a) register the callback;  (b) at the beginning of each experimental trial, call mouse(vrut.STOP) so the callback is not triggered while time-critical graphics are running;  (c) call mouse(vrut.START) after the stimulus presentation, when you are ready to record input, then call mouse(vrut.STOP) again..

movie(texture, objectName, [rate], [duration], [loopMode], [transparency])
Display simple movies on Cosmo3d objects in your virtual world.  Movies consist of a set of texture files (sorry, no quicktime support in the WIN32 IFL lib yet) that are numbered sequentially starting at one, e.g., 'foo1.tif', 'foo2.tif', 'foo3.tif'....

Parameters:

When creating the geometry objects for your VE, which is usually done in 3dStudioMax, assign a unique name to the object on which you want to show a movie (e.g., 'screen1').

When calling the movie() function, you designate the name of the texture files to use for the movies as, for example, 'foo.tif', leaving out the numbers, and supply the name of the object on which to show the movie.  The program then searches for the object and loads all the numbered texture files.  Note you do not designate how many texture files there are--the program starts with the first texture and loads files sequentially until it fails to find one.

You can choose to allow transparency:  the alpha plane of the texture file, which designates opacity of an object, can be used to determine if a particular pixel is to be drawn or not.  This does not permit partial transparency--the alpha plane in this application acts as a stencil, so you can cut out objects.  A value of 1.0 (or 256) means the pixel is rendered, while anything less than 1.0 is considered invisible (this will probably change in the future to support that same transparency modulation support by the child.appearance method).

Aside from setting the frame rate and duration, you can set the loopMode:  the movie either plays forward and resets to the beginning when it reaches the end, or it starts playing forward, and switches direction when it reaches the end, thus oscillating back and forth.  This is useful to cut down on the amount of used texture memory when you are showing something (quasi) cyclical.  For example, a film clip of a ball bouncing up and down can be cut in half.

All file formats are supported. To take advantage of transparency, you must use the TIF, PNG, and RGBA formats.

If you are satisfied with the default values, you can call the function simply as movie(texture, objectName). If you want to start a movie at a rate other than the default, you can call the function as movie(texture, objectName, yourFrameRate), and leave out the other values.  However, if you want to change only the duration, you have to specify all the parameters before it, i.e., you would have to call movie(texture, objectName, yourFrameRate, yourDuration).  In this case, default values would be used for loopMode and transparency.  In general, parameters are specified from left to right, and the ones to the right of the last specified one are filled in with default values.  It is not possible to skip a parameter in the list.

It is possible to play several movies simultaneously:  just call the movie() function for each one.  When displaying the same movie on different objects, the program uses the set of textures that is already loaded.  Aside from sharing a set of textures, the different instances of the same movie are independent in their parameter settings, i.e., they can run at different rates, durations, and loopModes, and their transparency settings are independent.

It is important to assign texture coordinates to the object vertices when creating the geometry.  These need to be stored in the vrml file, and they are loaded with addchild().  Assigning a temporary texture in 3dStudioMax helps to set that up. The temporary texture is discarded when the movie textures are painted onto the object.

Additional Programming Notes

override()
By default, VRUT starts in texture DECAL mode and has a start directional light pointed straight down the positive Z axis.  This enables models without any light sources to still be viewable.  If you're interested in getting maximum performance or maximum control over the appearance of your scene (i.e., you want to see proper lighting effects), you'll definitely want to turn off these standard defaults by issuing override().

playback(filename, filter, [callback])
This function is used to playback a previously recorded tracking file. The tracking file can contain information about the observer's head position, head orientation, and body orientation. Any of the three can be selected by or'ing together the filter flags described below. The data file should be tab-delimited rows with three columns for each of the selected options. For position include x, y, and z (in meters). For orientation include yaw, pitch, and roll (in degrees). The columns in the data file must always be ordered as follows: head position, head orientation, and body orientation, regardless of the order the filter flags are or'd. The optional callback function, if provided, will be called when the end of the playback data file has been reached. Note that this playback function returns control back to python immediately and will process in the background.

The data read from the file will be used as offsets to whatever the current position and orientations are as given by the tracking system. If you want the data file to specify absolute position and orientation, then simply turn off that particular component of the tracking system, or don't initialize the tracking at all.

Filter flags:

Example:
vrut.playback('data.rec', vrut.HEAD_POS | vrut.BODY_ORI)
In this example, the data file will have six columns in this following order:

head_x head_y head_z body_yaw body_pitch body_roll

playsound([wavefile],[option])
Play a standard wavefile asynchronously through the system speakers.  The 'wavefile' must be found either in the current working directory or along the standard windows search path.  Option can take the value LOOP to cause it to play over and over.  Passing no arguments whatsoever will force a looping sound to quit.

pointsize(size)
When dynamically building a geometry layer using the startlayer command, this command is used to specify point size (in pixels) of point primitives. See startlayer.

pushscroll(anchor, menuList)
This creates a new layer on the specfied anchor (WORLD, BODY, or HEAD) that's a menu build from the menuList given. If the belt knob is working, then the user can select menu items by rotating the knob and pressing the button to select. When an item is selected, a MENU_EVENT is generated, so if MENU_EVENT has been registered as a callback your python script can know which menu item was selected. Note: the menu is generated as a black rectange with white lettering (the selected line will be red lettering). The menu is intially placed at (0,0,0), so it may be necessary to use the translate command to move it. If you want the menu to appear in front of whereever the user, push it onto the BODY anchor and move it one or two meters forward in Z.

Example:
myList = "Go to next trial", "Redo last trial"
vrut.pushlayer(vrut.WORLD, myList)

quit()
Exit VRUT by closing down all windows and releasing system resources where necessary.  This can also be used to reset the IPC.

reset(what,[layerNum])
Use this to reset various VRUT states. For model layer offsets, specify the anchor as 'what' and give the layer number. For view offsets, just specify HEAD_POS, HEAD_ORI, or BODY_ORI; this will reset any offsets and any clamps that have been applied.  NOTE: resetting HEAD_POS will set the eyeheight to zero.

rotate(x, y, z, degrees)
rotate(anchor, layerNum, axis, degrees)
rotate(view, deltaYaw, deltaPitch, deltaRoll)
rotate(child, axis, degrees)
The first and second form of "rotate" are used to operate on VRUT child objects (eg., VRML files).  The first form is a method function of the child object and will apply an absolute rotation parallel to the vector described by (x, y, z) and through the chlid object's center.  The second form accepts the child object as a parameter and will apply an incremental rotation to the object along the selected cardinal axis (rotation is relative, and multiple calls of the same angle will be additive).  The possible values of axis are XAXIS, YAXIS, and ZAXIS  The third form of "rotation" is used to rotate geometry generated on the fly using VRUT "startlayer"; this will incrementally rotate an entire layer along the indicated axis by the number of degrees specified. The angular rotation is also relative.  The fourth form of "rotate" is used to offset the viewing direction by rotating the entire body about the specified Euler angles.  This too is a relative offset.

savecsb(fileName)
This function will export the entire contents of scene 1 (the default VRUT scene) as a Cosmo binary file.  This file format is optimized for speed and can be used later to reload your scene.  Everything in the current scene will be stored into a single file, including all loaded VRML objects, all transformations applied after-the-fact, appearance qualities (eg., TRANSPARENCY).  Textures are optimized but the original texture image files will still need to exist along the original paths in order for the CSB file to work.  When saving a .CSB file be sure to append your filename with the .CSB suffix.  When loading a .CSB file you simply use the "addchild" command as for VRML files.  If your scene contained multiple objects that you later want to manipulate separately, you can gain access to these individual objects by using the child method "getchild" and passing the name of the original VRML file as the object name to get.

scale(x, y, z)
scale(anchor, layerNum, scaleX, scaleY, scaleZ)
The first form applies to VRUT child objects (eg., VRML files); the second form applies to geometry created on the fly.  The scales modifies an entire layer by the scale factors given for each dimension. For the first form of scale, the factors are absolute; for the second they are relative (multiplicative).

self()
Use this to obtain a copy of the child object from within a child script.

setaspect(ratio)
Set the horizontal-to-vertical aspect ratio for ORTHOGRAPHIC display mode.

setclip(near, far)
Set the inter-pupilary distance to be used for rendering calculations. The passed value should be in meters, and the default value used is 0.06.

setfov(verticalFOV, horz2vertRatio)
Set the perspective rendering for the specified vertical field-of-view in degrees as the first parameter, and the specified ratio of horizontal to vertical dimensions of the viewport (i.e., the width to height of the monitor). The SONY monitor measures 37.4 cm x 28.8 cm. Click here more a detailed explanation of use.

setipd(distance)
Set the inter-pupilary distance to be used for rendering calculations. The passed value should be in meters, and the default value used is 0.06.

setscene(sceneNumber, [eye])
Set the scene that is currently being rendered.  This version of VRUT maintains two scene graphs that can be loaded with different objects.  By default, VRUT command operate on scene #1 which is also the default display scene.  You can use the second scene to build up another world and then call setscene() to switch back and forth.  Another use with stereo systems is to present one scene to one eye and the other scene to the other eye.  To set a scene so that it renders only to one eye, pass vrut.LEFT_EYE or vrut.RIGHT_EYE in the eye argument.

shadow(anchor, layerNum, [status])
Shadows can be cast from any layer on any anchor. The shadowing engine is fairly limited so beware of bizarre looking results. The shadows are alway cast from a parallel light rays directly overhead upon the ground surface. No actual ground surface needs to present because black shadows will appear at the ground even if there's no ground geometry loaded (but unless you change the clearcolor from black you won't notice them). Also, beware that the shadows vary in height around zero by a few centimeters, which means that if you load a floor layer exactly at height zero it may occlude some of your shadow (fix this problem by translating the floor layer down about 5 cm). By default this command activates shadowing; pass vrut.FALSE as the status to turn off shadowing.

showmessage(message, [x, y, z], [scale], [clump])
Use this to show a simple string message in 3D.  By default, the message will appear at (0, 0, 0), in black lettering, about 1 m per letter, and attached to the world anchor.  You can override these defaults by passing the appropriate arguments.  You can add up to 10 message at a single time at different locations.  To get rid of one or all messages, send showmessage('off').

starthotspot(hotspotID, type, centerX, centerZ, p1, [p2])
Establish a hotspot at the specified location with the given integer hotspotID. Hotspots come in four types: CIRCLE_HOTSPOT_IN, CIRCLE_HOTSPOT_OUT, RECTANGLE_HOTSPOT_IN, and RECTANGLE_HOTSPOT_OUT. A circle hotspot is defined by a center and a radius. When starting a circle hotspot, give the radius as argument p1 (p2 is not used). A rectangle hotspot is defined by a center and a width around that center in the X and Z dimensions (thus the dimensions of the rectangle hotspot are 2*X by 2*Z), given as arguments p1 and p2, respectively. CIRCLE and RECTANGLE hotspots are either IN (triggered upon entering the hotspot) or OUT (triggered when exiting the hotspot). When a hotspot event is triggered, the callback function is passed the ID of the triggered hotspot, and the (x,y,z) coordinates of the observer head position (so that's one integer and three floating points). After a hotspot has been triggered once, the hotspot is de-activated. This is necessary so that the hotspot does not continue to create events. If desired, you can re-establish the hotspot later (try using a timer event). You can re-use hotspot ID's as often as you like.

startlayer(mode)
This command provides access to OpenGL commands for building geometry. You might want to use this to dynamically build a model. The vrut command vertex allows you to specify the 3D coordinates of geomtetric primitives such as points, lines, quads, etc. Any geometry you create this way is pushed automatically onto the WORLD anchor as a new layer. Before using this commands, you ought to become familiar with the OpenGL commands glBeginList(), glVertex3, and glEndList() (see OpenGL redbook pages 33-37). The vrut command startlayer acts like glBeginList. You can begin a quads list, and then switch to triangles list by just re-issueing startlayer (no analogue to glEndList() is necessary). A call to endlayer must be made when all geometry is completed before the display list is actually created. It is up to you to verify that the appropriate multiples of the vertex commands are issued appropriated for the selected mode. The follow OpenGL geometry modes can be selected:


starttimer(timerID, [timerSeconds])
Start a timer giving it an integer ID timerNum. It is initially set for timerSeconds duration (this can be a floating point number to take advantage of up to millisecond resolution, though keep in mind the display is quantized into 1/60 second intervals).  If no time is specified, then VRUT assumes you want a timer to expire as fast as possible.

tracker([command])
Used to quckly attach a sensor that has already been added to the virtual environment to the eyepoint.  At least one 3DOF or 6DOF sensor must already have been added (vrut.addsensor) before this command will work.  If more than one sensor has been added that fits that description, then the first one added will be the one used.  With no arguments, START is assumed and tracking is started. The other options are END and RESET.

translate(x, y, z)
translate(child, deltaX, deltaY, deltaZ)
translate(anchor, layerNum, deltaX, deltaY, deltaZ)
translate(view, deltaX, deltaY, deltaZ)
The first form of this function applies to VRUT child objects (eg., VRML files) and translations are absolute.  In the second form of the "translate" function you pass the child objects as an argument and the translations will be applied incrementally.  In the third  form, you can translate a geometry layer created on the fly using "startlayer"; you must specify the anchor (HEAD, BODY, or WORLD), the layer number, and the offsets in X, Y, and Z. The fourth form lets you offset the viewing position, specify HEAD_POS and just give the X, Y, and Z offsets (the offsets must be specified in WORLD axes not BODY axes, which means the positive X and Z will not alway move the observer to his/her right/forward unless he/she happens to be facing North). To reset either model or view offsets to zero, see the reset command.

version()
Print a list of all version numbers of VRUT and all its linked modules, including IPC, VRUT library, and all sensors.

vertex(x, y, z)
When dynamically building a geometry layer using the startlayer command, this command is used to specify the 3D coordinates of each vertex of each primitive. See startlayer.

vertexcolor(r, g, b)
When dynamically building a geometry layer using the startlayer command, this command is used to specify the color of each vertex of each primitive. See startlayer.