interactive VRS

A Tcl/Tk binding of the Virtual Rendering System

Homepage of VRS: www.vrs3d.org

Contact: iVRS project group


News

07.07.2003

    iVRS 1.09 has been released. 
      - This release corresponds to the VRS-3.3 alpha from 04.07.2004

12.01.2004

Added some dlls for the binary version of iVRS that appeared to be missing under circumstances. Just copy them into the bin-directory of your tcl/tk installation. These files will be included in the next release of iVRS.

28.11.2003

    iVRS 1.08 has been released. 
      - in sync with VRS-3.2 final from 27.11.2003

23.06.2003

    iVRS 1.07 has been released. 
      - in sync with VRS-3.2alpha from 18.06.2003

31.01.2003

    iVRS 1.06 has been released. 
      - added binary support for Tcl 8.4
      - fixed shadow bugs

15.01.2003

    iVRS 1.05 has been released. 
      - added support for ID class
      - added wrapper method '?' to query concrete method
      - added version number

07.07.2002

    iVRS 1.04 has been released. 
      - now using Tcl/Tk stubs for Win32 binaries
      - simplified iterator usage
      - fixed 3DS reader

05.04.2002

    iVRS 1.03 has been released. 
      - Unix support

11.12.2001

    iVRS 1.02 has been released. 
      - optimization
      - bug fixes

27.11.2001

    iVRS 1.01 has been released. 
      - calling mechanism has been improved
      - more templates are supported (Iterator, Array, List, Array2D, Iterator2D)
      - IDE prototype added

29.10.2001     iVRS 1.0 has been released
      - Tcl/Tk extension of VRS

 

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:

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

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: 

iVRS 1.09 Windows binary iVRS 1.09 for Windows.zip (3.7 MB)
iVRS 1.09 source iVRS 1.09.zip (0.4 MB. Additionally you also must download VRS-3.3alpha. Beware that iVRS does not automatically create all wrapper classes correctly; for compilation some minor tweaks are required.)
iVRS 1.08 Windows binary iVRS 1.08 for Windows.zip (2.9 MB)
Additional dlls for iVRS 1.08 binary Additional dlls which are required for iVRS under some configurations. Just copy them into the bin-directory of your tcl/tk installiation. (0.4 MB)
iVRS 1.08 Windows source iVRS 1.08.zip (0.4 MB. Additionally you also must download VRS-3.2)
iVRS 1.07 Windows binary iVRS 1.07 for Windows.zip (2.5 MB)
iVRS 1.06 Windows binary iVRS 1.06 for Windows.zip (2.5 MB)
iVRS 1.06 + VRS 3.0 source iVRS 1.06 source.zip (3.2 MB)
iVRS 1.05 Windows binary iVRS 1.05 for Windows.zip (1.5 MB)
iVRS 1.04 Windows binary iVRS 1.04 for Windows.zip (1.5 MB)
iVRS 1.03 Windows binary iVRS 1.03 for Windows.zip (1.4 MB)
iVRS 1.03 + VRS 3.0 Unix source  iVRS 1.03 for Unix source.tar.gz (1.6 MB)
iVRS 1.02 Window binary iVRS 1.02 for Windows.zip (1.4 MB)
iVRS 1.01 Window binary iVRS 1.01 for Windows.zip (1.3 MB)
iVRS 1.0 Window binary iVRS 1.0 for Windows.zip (1.7 MB)

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:

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:

% new Sphere
-> objSphere1
% set mySphere [new Sphere] 
-> objSphere2

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. 

<object-name> <method-name> <arg1 arg2 ... argN>

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

% objSphere1 setCenter {1 0 1} or
% $mySphere setRadius 15.2

 


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. 

<class-name> <method-name> <arg1 arg2 ... argN>

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

% set myImage [ObjectLoader readFile picture.ppm]

 


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.

// c++
class A {
   enum Mode {ON, OFF};
   void setMode(A::Mode mode) ;
};

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

% $a setMode A::ON
% $a getMode
-> A::ON

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!

% $a setMode A::ON|A::OFF

 


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: 

class

syntax

description

Vector

x y z

XYZ coordinates

Color

r g b a

red, green, blue, alpha values

Bounds

lx ly lz    ux uy uz

LLF, URB

Ray

ox oy oz    dx dy dz

origin, direction

Matrix

  a11 a12 a13 a14  
  a21 a22 a23 a24
 
  a31 a32 a33 a34
 
  a41 a42 a43 a44 

Coordinates of a 4x4 matrix

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:

$polygonset setVertexIterator [VectorItr {1 3 2} {1 9 1} {2 4 8}]


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.

$texturegl setInternalFormat GL_RGB

 


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::

VRS info classes  all classes available in the iVRS
VRS info objects  all objects currently available in iVRS
VRS info version  current iVRS version number (>= 1.05)
VRS info methodnames [classname|objectname] all names of all object and class methods of class classname or object objectname
VRS info methods [classname|objectname] detailed information (returntype, name, arguments) on all object methods of class classname or object objectname
VRS info statics [classname|objectname] detailed information (returntype, name, arguments) on all class methods of class classname or object objectname
VRS info ctors [classname|objectname] detailed information (arguments) on all constructors of class classname or object objectname
VRS info enums [classname|objectname] all enumelements of class classname or object objectname
VRS info classname objectname the class name of object classname
VRS info childclasses classname the all child classes of class classname
VRS info parentclass classname the parent of class classname
[classname|objectname] ? methodname detailed information on the concrete method named methodname (>= 1.05)

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.