interactive VRS

A Tcl/Tk binding of the Virtual Rendering System

Homepage of VRS: www.vrs3d.org

Contact: iVRS project group

News

1. What is iVRS?

iVRS stands for interactive VRS and  is a Tcl/Tk package that provides full access to 3D features of the Virtual Rendering System VRS. Using iVRS, Tcl/Tk applications do have access to the powerful scene graph and behavior graph of VRS and, in this way, can construct complex, interactive 3D scenes. With iVRS, most of VRS' functionality gets accessible within the scripting language Tcl. Using Tcl commands, you can instantiate VRS objects and call their respective methods. This has been achieved building wrapper classes, which convert method arguments between Tcl strings and C++ data types. The wrapper mechanism used to build iVRS includes:

• Creating and deleting VRS objects
• Calling public methods
• Calling static methods
• Handling of overloaded methods
• Handling of polymorphic methods
• Handling of operator methods
• Handling of default parameters.

The parameter conversion between C++ and Tcl handles the following types:

• built-in data types (e.g. int, char, float, double, unsigned int, char* ...),
• enumerations ( e.g. Light::ON),
• OpenGL defines (e.g. GL_DST_COLOR),
• Pointer to VRS classes,
• Untyped pointers.

Note: The iVRS wrappers rely exclusively on standard Tcl, that is, iVRS does not require object-oriented extensions for Tcl such as [incr Tcl], although this might be important for your Tcl code in general. 

2. Background

Scripting languages are excellent gluing languages helping to integrate components and libraries and facilitating application development. Why? A remarkable share of time creating C++-based applications is owed to the compilation of the used application components. Every change made to the source code of the components (changing interface parameters, modification of GUI callbacs, etc.) implicates a compilation process, transforming the respective programming language commands into assembler code.

Interpreted languages such as Tcl enable „interactive“ programming of applications: Commands are passed as plain text to the interpreter which interprets the source and translates it into appropriate function calls. As this process takes places at run-time, the processing speed of an interpreted program is slower, compared to a compiled program version, of course. In iVRS, there are only a few stages considered to be time-critical: it is important to efficiently traverse a geometry graph and to efficiently map geometry objects to primitives of the underlying 3D rendering system. Construction and modifying scene graphs, however, is generally not time-critical. Both tasks are completely wrapped, that is, no performance is lost since graph traversal and mapping are performed exclusively and automatically by C++ methods. Tcl is mainly used to construct scene graphs and to modify objects, both are in general non-time critical aspects in an interactive, real-time application.

3. Download iVRS

A precompiled Win32 version of iVRS can be downloaded here: 

To run iVRS, you need Tcl/Tk. A self-installing executable of Tcl/Tk 8.3 can be found at activeState.com: Tcl/Tk 8.3.4.1 for Windows (7.3 MB)

4. Installing iVRS

After installing Tcl/Tk 8.3, decompress the dowloaded "ivrs1XX_binary.zip" file into your Tcl home directory. 
If "C:\Tcl\"  is  your Tcl installation directory, the following files should be present:

• C:\Tcl\bin\iVRS.dll

• C:\Tcl\bin\VRS_VC60.dll (or simply VRS.dll for iVRS 1.07 and older)

• C:\Tcl\bin\VRS_tcl.dll

• C:\Tcl\lib\VRS3.2\pkgIndex.tcl

• C:\Tcl\lib\VRS3.2\demos

Just write "package require VRS" in the first line of your Tcl scripts in order to import iVRS.

5. Working with iVRS

5.1 Creating and deleting objects

The command new creates VRS objects in the iVRS console. The return value of new is the name (reference), by which the C++-object can be handled in the console.

In addition, the name of the object can be saved in Tcl variables for later usage:

If a method expects a pointer to an instance the return value of new can be used: The symbol is transformed into a correct type internally.

The delete command frees the memory associated with an object. If an object 'a' is an instance of a derived class from SharedObj it is freed if and only if no other object holds a references on 'a' (according to the SharedObj mechanism of VRS):. The number of references to an SharedObj object can be retrieved using the method references. 

% delete $mySphere
% delete objSphere1

A group of objects can be deleted in one statement, for example: 
% delete $mySphere objSphere1

5.2 Calling object methods

To invoke a method available for a given object, the object name is followed by the method name and, optionally, arguments. 

Arguments are separated by whitespaces. Arguments containing spaces must be grouped by {} or “ ” :

5.3 Calling static methods

To invoke a static method available for a given class, the class name is followed by the method name and, optionally, arguments. 

Arguments are separated by whitespaces. Arguments containing spaces must be grouped by {} or “” :

5.4 Handling of overloaded methods

The following example shows a class A with two equally named methods with different signature:

// c++
class A {
    void setValue (int i);
    void setValue (SharedObj* o);
};

When calling one of these methods in C++, the compiler can decide  by means of the argument type which method to choose. As Tcl is an interpreter language the decision must be done at runtime. iVRS iterates over all equally named methods and tries to convert the argument string to the necessary type. If no type fits no method is called and an error message is generated.

% set s [new Sphere]
% set a [new A]
% $a setValue 15   OK: first method fits.
% $a setValue $s   OK: first method does not fit, second method does fit
% $a setValue foo    ERROR: "foo" could not be converted to int respective SharedObj*

Note: Distinguishable types in C++ need not be distinguishable in iVRS, e.g., char and long. The first method that can convert all arguments is choosen! 

5.5 Supported Datatypes

iVRS supports most built-in datatypes as well as objects of wrapped classes. This way, values of built-in datatypes and object references can be passed to methods, and can be returned by methods. iVRS represents values of built-in datatypes (respectively object references) by strings.  Supported built-in datatypes include int, char, float, double, unsigned int, long, unsigned long, char*, and void*. Type conversion is strictly enforced, e.g.,  1.1 will not be accepted as int value. Derived built-in datatypes as float* or char*** are not supported.

5.6 Enumerations

Enumerations can be passed as strings to the interpreter, the numeric value of an enumeration element does not need to be known! This approach depends on a stringent typing of enumerations on C++ side.

The enumeration declared in the class above can be used in iVRS as follows:

iVRS recognizes that an enumeration of class A is expected, and the string „A::ON“ is converted into the value of the enumeration element as specified in C++.

In some cases it makes sense to work without this strong typing, for example, if values are processed bit-wise: This requires arguments of type int and support of iVRS for the bit-wise OR-operator (‚|’). When using the OR-operator, one must take care on putting the single enumeration elements together without separating them through whitespaces!

5.7 Elementary VRS Datatypes

Most elementary VRS classes are not derived from SharedObj (e.g., Vector, Color, Ray, Bounds) for sake of speed. These types are used for call-by-value and not by-reference (or pointer): Instances are defined by their values,  they do not have an identity! Elementary classes are support by direct conversion in iVRS. The following table explains the syntax: 

The following example show how to use the direct conversion:

% set s [new Sphere]
% $s setCenter {1 2 3}
% $s getCenter
1 2 3

Note: You can use the new and delete command for this types as well. 

% set v [new Vector 1 2 3]
% $s setCenter $v
% $s getCenter
1 2 3

5.8 Iterators

Data exchange between VRS objects is normally handled independently from the underlying containers using iterators. Whenever an iterator is expected it can be generated implicitly by putting data values together.

Examples:

The C++ Iterator<int>  is generate by writing  [intItr 1 44 6 99 123 2 88] or

Iterator<Vector> is generate by writing  [VectorItr {1 3 2} {1 9 1} {2 4 8} ]. 

Example for setting a vertex iterator in a polygon set:

5.9 OpenGL defines

OpenGL has a large number of predefined values specified by preprocessor defines. For the sake of easiness, these defines were included into VRS class interfaces. All OpenGL defines possibly expected at VRS interfaces can be used in iVRS as well, assuming the respective class interface uses the OpenGL data types Glenum, Glint, or  Gluint.

5.10 The „NULL“ object

The object named NULL represents the well-known null pointer, and may be used where object references are expected:

% $polygonset setTextureIterator NULL or

% $polygonset getTextureIterator
-> NULL

5.11 Retrieving the VRS status

The VRS command allows Tcl applications to get information on the VRS status. The  VRS cleanup command deletes  iVRS objects are destroyed. The VRS info command queries information on a specific class or an object::

Query all method names of the Sphere class:

% VRS info methodnames Sphere
boundingBox getCenter getClientData getObjectName getRadius getTheta getYMax getYMin modified references setCenter setClientData setObjectName setRadius setTheta setYMinMax 

Query all non-static methods for a sphere object:

% VRS info methods objSphere64778431
Bounds boundingBox {}
Vector getCenter {}
void* getClientData {}
char* getObjectName {}
double getRadius {}
double getTheta {}
...

Query all enumeration elements of class InputEvent:

% VRS info enums InputEvent
AllChanges AllKeys AllMouseButtons Ctrl Lock Mod1 Mod2 Mod3 Mod4 Mod5 MouseButton1 MouseButton2 MouseButton3 MouseButton4 MouseButton5 NoModifier NoMouseButton Pressed Released Shift:

© 2001 by the VRS Group.