Tcl3D: Doing 3D with Tcl

Tcl3D: Doing 3D with Tcl


image


  1. INTRODUCTION 2

    1. Architecture overview 2

    2. Modules overview 3

    3. Library versions 6

    4. Supported platforms 6

    5. Getting started 7

  2. INSTALLATION 10

    1. Installation of a binary distribution 11

    2. Installation of a source distribution 12

    3. Extending Tcl3D 18

  3. WRAPPING IN DETAIL 19

    1. Wrapping description 19

    2. Wrapping reference card 25

  4. MODULES IN DETAIL 26

    1. tcl3dOgl->Togl: Enhanced Togl widget 26

    2. tcl3dOgl->OpenGL: Wrapper for OpenGL functionality 29

    3. tcl3dOgl->Util: Tcl3D utility library 33

    4. tcl3dCg: Wrapper for NVidia’s Cg shading language 50

    5. tcl3dSDL: Wrapper for the Simple DirectMedia Library 50

    6. tcl3dFTGL: Wrapper for the OpenGL Font Rendering Library 51

    7. tcl3dGl2ps: Wrapper for the OpenGL To Postscript Library 52

    8. tcl3dOde: Wrapper for the Open Dynamics Engine 52

    9. tcl3dOsg: Wrapper for the OpenSceneGraph library 53

    10. tcl3dGauges: Tcl3D package for displaying gauges 54

  5. MISCELLANEOUS TCL3D INFORMATION 55

    1. License information 55

    2. Programming hints 56

    3. Open issues 57

    4. Known bugs 58

    5. Starpack internals 58

    6. OpenGL deprecation mode 59

  6. DEMO APPLICATIONS 63

  7. RELEASE NOTES 64

    1. Release history 64

    2. Release details 66

    3. Obsolete functions 71

  8. REFERENCES 73

1 Introduction

1 Introduction


Tcl3D enables the 3D functionality of OpenGL and various other portable 3D libraries at the Tcl scripting level.


It’s main design requirement is to wrap existing 3D libraries without modification of their header files and with minimal manual code writing. The Tcl API shall be a direct wrapping of the C/C++ based library API’s, with a “natural” mapping of C types to according Tcl types.


This is accomplished mostly with the help of SWIG [24], the Simplified Wrapper and Interface Generator.


Tcl3D is based on ideas of Roger E. Critchlow, who formerly created an OpenGL Tcl binding called Frustum [30].


N o t e :

Text in this manual with a light blue background color indicate changes since the last release of this manual.


1.1 Architecture overview

1.1 Architecture overview


The Tcl3D package currently consists of the following building blocks, also called modules throughout the manual:


Tcl3D core module

tcl3dOgl

Togl: Enhanced Togl widget, a Tk widget for displaying OpenGL content.

OpenGL: Wrapper for core OpenGL functionality (GL Version 4.1, GLU Version 1.2) and OpenGL extensions.

Util: Tcl3D utility library: Math functions, standard shapes, stop watch, demo support.

Tcl3D optional modules

tcl3dCg

Wrapper for NVidia’s Cg shading language.

tcl3dSDL

Wrapper for the Simple DirectMedia Library.

tcl3dFTGL

Wrapper for the OpenGL Font Rendering library.

tcl3dGl2ps

Wrapper for the OpenGL To Postscript library.

tcl3dOde

Wrapper for the Open Dynamics Engine.

tcl3dOsg

Wrapper for the OpenSceneGraph library.

tcl3dGauges

Tcl3D package for displaying gauges.

Table 1.1: Overview of Tcl3D modules


Each module is implemented as a separate Tcl package and can be loaded explicitely with the Tcl package command, ex. package require tcl3dsdl. All available Tcl3D modules can be loaded with a single command: package require tcl3d.


N o t e

image


Figure 1.1: Tcl3D package layout


The next figure shows the currently available modules of Tcl3D. Modules with blue text color have been updated since the last release.


The Tcl3D Modules


image


image

Tcl-Level

Tcl3D Demos and Applications

Tcl3D Demos and Applications


tcl3dOgl

Tcl-based Utilities

tcl3dGauges

Tcl Extension Package



SWIG generated Tcl interfaces Tcl-Interface


tcl3dOgl

C-based Utilities

tcl3dOgl

OpenGL 4.1 and extensions

tcl3dOgl

Togl Widget

tcl3dOgl

C-based Utilities

tcl3dOgl

OpenGL 4.1 and extensions

tcl3dOgl

Togl Widget


tcl3dCg

Cg Shading

tcl3dSDL

Joystick and CD

tcl3dFTGL

Font Rendering

tcl3dGl2ps

OpenGL to PS/PDF

tcl3dOde

Physics Engine

tcl3dOsg

OpenSceneGraph

C/C++-Level


Figure 1.2: Overview of Tcl3D modules



1.2 Modules overview

1.2 Modules overview


This chapter gives a short overview of the modules available in Tcl3D.

      1. Tcl3D core module

        The Tcl3D core module tcl3dOgl consists of the following 3 sub-modules:

      2. Tcl3D optional modules

        The following Tcl3D optional modules are currently available:


A detailed description of this module can be found in chapter 4.8.


tcl3dOsg: Wrapper for the OpenSceneGraph library

This module wraps the OpenSceneGraph library (OSG) [13] and adds some OSG related utility procedures.


A detailed description of this module can be found in chapter 4.9.


tcl3dGauges: Tcl3D package for displaying gauges

This package implements the following gauges as a pure Tcl package: airspeed, altimeter, compass, tilt-meter.

A detailed description of this module can be found in chapter 4.10.


1.3 Library versions

1.3 Library versions


The following table shows a list of the library versions used in the Tcl3D infrastructure.


Lib

Version

Comment

URL

Libraries used for the Tcl3D core module

GLEW

1.5.7

Included in Tcl3D source tree.

http://glew.sourceforge.net/

Togl

2.0

Modified version included in Tcl3D source tree.

http://sourceforge.net/projects/togl

Libraries used for the Tcl3D optional modules

Cg

2.2.0017

February 2010 release.

http://developer.nvidia.com/object/cg_toolkit.html

FTGL

2.1.3

Release Candiate 5

http://sourceforge.net/projects/ftgl/

GL2PS

1.3.5

Included in Tcl3D source tree.

http://www.geuz.org/gl2ps/

ODE

0.7.0

http://sourceforge.net/projects/opende/

OSG

2.8.2

http://www.openscenegraph.org

SDL

1.2.9

http://www.libsdl.org/index.php

Libraries used for the Tcl3D starpack

Tcl/Tk

8.5.8

Tcl/Tk starpack

http://www.kroc.tk/tclkit-darwin.html http://www.patthoyts.tk/tclkit/

TkImg

1.4

SVN Revision 315

http://sourceforge.net/projects/tkimg/

Snack

2.2

http://www.speech.kth.se/snack/

Tablelist

4.12

http://www.nemethi.de

Twapi

2.2.3

Windows only.

http://twapi.magicsplat.com/


1.4 Supported platforms

1.4 Supported platforms

The following table gives an overview on the availability of the different Tcl3D modules on the supported operating systems. It also tries to give an indication on the quality of the module.


Windows

32-bit

Linux

32-bit

Linux

64-bit

Mac OS X

32-bit (Intel)

IRIX 6.5

n32

Module

Wrap

Test

Wrap

Test

Wrap

Test

Wrap

Test

Wrap

Test

tcl3dOgl

++

++

++

++

++

++

++

+

++

+

tcl3dCg

++

++

++

++

++

++

++

+

-

-

tcl3dSDL

+

++

+

++

+

++

+

0

+

+

tcl3dFTGL

++

+

++

+

++

+

++

0

++

+

tcl3dGl2ps

++

+

++

+

++

+

++

+

++

+

tcl3dOde

+

0

+

0

+

0

+

0

+

0

tcl3dOsg

+

+

+

+

+

+

+

+

0

0

tcl3dGauges

++

+

++

+

++

+

++

+

++

+

Table 1.2: Availability of Tcl3D modules


Legend for Table 1.2:


image

Column Wrap Column Test

image

++ Interface of module fully wrapped. ++ Module extensively tested. No errors known.

+ Interface of module partially wrapped. + Module tested. Minor errors known.

0 Module not yet wrapped. 0 Module in work.

- Module not available for the platform. - Module not available for the platform.


Short summary:

The Windows and Linux ports are supported best and are regularly tested on different graphics card and OpenGL driver combinations.

On IRIX every module (except OSG and Cg - which is not available for SGI) has been wrapped and seems to be running fine, but no extensive tests have been done.

The OS X port is tested on a MacBook only with limited graphics capabilities.


1.5 Getting started

1.5 Getting started


The easiest way to get started, is using a Tcl3D starpack. Starpacks for Windows, Linux, IRIX and Mac OS X (Intel based) can be downloaded from http://www.tcl3d.org/. See chapter 2 for a detailed information about all available Tcl3D distribution packages.


The only prerequisite needed for using the Tcl3D starpack distribution is an installed OpenGL driver. Everything else - even the Tcl interpreter - is contained in the starpack.


The starpacks are distributed as a ZIP-compressed file. Unzipping this file creates a directory containing the starpack tcl3dsh-OS-VERSION. Distributions for Unix systems contain an additional shell script tcl3dsh-OS-VERSION.sh, which should be used for starting the Tcl3D starpack.

After starting the starpack, a toplevel Tk window labeled Tcl3D as well as a console window labeled Tcl3D Console should appear, similar to starting a wish shell.

The console window should contain the following usage message as well as a tcl3d prompt:


Type "pres" to start Tcl3D presentation.

Type "inst" to write the Tcl3D installation packages to disk.


Note:

Temporary and output files are written to C:/tmp/tcl3dData.tmp.

The OpenSceneGraph library and demos are not included in this presentation.


tcl3d>


Typing pres in the console window, starts the Tcl3D presentation showing an introductionary animation as shown in the screenshot below. The available key and mouse bindings are shown in the console window.

image

Figure 1.3: Tcl3D presentation intro


Binding

Action

Key-Escape

Exit the program

Key-Left

Move text to the left

Key-Right

Move text to the right

Key-i

Increase distance from viewer

Key-d

Decrease distance from viewer

Key-Up

Increase speed

Key-Down

Decrease speed

Key-plus

Rotate text

Key-minus

Rotate text (other direction)

Key-space

Set speed of text to zero

Key-r

Reset speed and position of text

Mouse-1

Start animation

Mouse-2

Stop animation

Table 1.3: Tcl3D presentation shortcuts


The presentation can also be started directly by using -pres as a command line parameter to the Tcl3D starpack.


Description of the Tcl3D starpack


The starpack tcl3dsh can be used as


Some notes about the demos contained in the starpack: OpenSceneGraph related demos are not included in the starpack.

Depending on your operating system, graphics card and driver, some of the programs may raise an error message or will not work properly.

As the demos contained within the starpack were written to be standalone programs, no error recovery was implemented. The programs typically just quit. This is, why you may get a confirmation window from time to time, asking you, if you want to quit the presentation.

In most cases, you may proceed with other demos, but be warned, that strange effects may occur.

2 Installation

2 Installation


Precompiled packages for Windows, Linux, IRIX and Intel based Mac OS X, the source code of the Tcl3D package as well as test and demonstration programs can be downloaded from the Tcl3D home page at http://www.tcl3d.org.


The precompiled packages have been generated on the following operating system / compiler combinations:


Operating system

Compiler

Tck/Tk

Swig

Windows 7 64-bit

VS Express 2008 (32-bit)

8.5.8

1.3.40

SuSE Linux 11.2 32-bit (2.6.31)

gcc 4.4.1

8.5.7

1.3.36

SuSE Linux 11.2 64-bit (2.6.31)

gcc 4.4.1

8.5.7

1.3.36

Mac OSX 10.5.0

(SnowLeopard)

gcc 4.2.1 (32-bit)

8.5.8

1.3.40

SGI IRIX 6.5.22

gcc 3.4.6 (Nekoware)


Please report problems or errors to info@tcl3d.org.


image

Use the following script when sending bug reports or questions to supply me with information about your environment.


catch { console show }


package require tcl3d togl .t


# Print information about the OS. parray tcl_platform


# Print information about the Tcl3D modules. puts [tcl3dGetPackageInfo]


# Print information about the OpenGL driver. puts [tcl3dOglGetVersions]


# If it's a problem with an OpenGL extension, you should also

# include the output of the following statement: puts [tcl3dOglGetExtensions]


# If Tcl3D procedures are not found

# (ex. invalid command name "tcl3dShowPackageInfo")

# print out some low-level information. parray tcl3dPkgInfo


image

The following distribution packages are currently available. Which packages are needed, depends on the proposed usage. See the next chapters for detailed information.

Documents

Tcl3D-Manual-VERSION.odt

Tcl3D user manual (this document). OpenOffice format.

Tcl3D-Manual-VERSION.pdf

Tcl3D user manual (this document). PDF format.

Tcl3D-RefManual-VERSION.pdf

Tcl3D reference manual.

Tcl3D-DemoRef-VERSION.pdf

Tcl3D demo programs reference.

Demos

tcl3d-demos-VERSION.zip

Tcl3D demo sources.

tcl3d-demoimgs-VERSION.zip

Screenshots of all Tcl3D demo programs.

Starpacks

tcl3dsh-win32-VERSION.zip

Tcl3D starpack for Windows.

tcl3dsh-Linux-VERSION.zip

Tcl3D starpack for 32-bit Linux.

tcl3dsh-Linux64-VERSION.zip

Tcl3D starpack for 64-bit Linux.

tcl3dsh-Darwin-VERSION.zip

Tcl3D starpack for Mac OS X (Intel based).

tcl3dsh-IRIX64-VERSION.zip

Tcl3D starpack for SGI IRIX (MIPS based).

Binary packages

tcl3d-win32-VERSION.zip

External libraries (DLL's) and Tcl3D package for Windows.

tcl3d-Linux-VERSION.zip

External libraries (DSO's) and Tcl3D package for 32-bit Linux.

tcl3d-Linux64-VERSION.zip

External libraries (DSO's) and Tcl3D package for 64-bit Linux.

tcl3d-Darwin-VERSION.zip

External libraries (DSO's) and Tcl3D package for Mac OS X.

tcl3d-IRIX64-VERSION.zip

External libraries (DSO's) and Tcl3D package for SGI IRIX.

Sources

tcl3d-src-VERSION.zip

Tcl3D source distribution.

tcl3d-starpack-VERSION.zip

Tcl3D sources for creating starpacks.

Table 2.1: Tcl3D distribution packages


The term VERSION is a template for the Tcl3D version number, i.e. for the currently available version it must be replaced with 0.5.0.


2.1 Installation of a binary distribution

2.1 Installation of a binary distribution


There are two possibilities to install a Tcl3D binary distribution onto your computer.


      1. Installation from a Tcl3D starpack

        The following prerequisites are needed when installing from a Tcl3D starpack:

        • An OpenGL driver suitable for your graphics card. It is recommend to download and install an up-to-date OpenGL driver from the manufacturer of your graphics card, especially if intending to write shader programs in GLSL or Cg.


          Download, unzip and start a Tcl3D starpack presentation as described in chapter 1.5.


          In the right menu pane, you will see 3 buttons in the Installation and Information menu (see Figure 1.3 on page 8).

          These allow you to extract the Tcl3D packages (tcl3d0.5.0), the external libraries (extlibs) and the demo programs (demos) onto the file system, so you can use Tcl3D from tclsh or wish.


        • The Tcl3D package folder (tcl3d0.5.0) should be copied into the library section of your Tcl installation (ex. C:\Tcl\lib). If write access to this Tcl directory is not permitted, you can copy the tcl3d0.5.0 directory somewhere else, eg. C:\mytcl3d or /home/user/mytcl3d. To have Tcl look for packages in this location, you must set the TCLLIBPATH environment variable with the above specified directory name as value. Note, that on Windows the path must be written with slashes (not backslashes): set TCLLIBPATH = C:/mytcl3d

        • The files contained in the external libraries folder (extlibs) should be copied into a directory, which is listed in your PATH environment variable (Windows) or your LD_LIBRARY_PATH environment variable (Unix).

        • The demonstration programs folder (demos) can be copied to any convenient place of your file system.


          N o t e

          The starpack does not contain the tcl3dOsg library files and demo applications due to space limitations.


          Now you are ready for using Tcl3D from a standard Tcl interpreter by starting a tclsh or wish

          program and issuing the following command: package require tcl3d.


          Alternatively you can extract the 3 installation folders with one of the following methods:

        • Start the Tcl3D starpack and issue the command inst in the console.

        • Start the Tcl3D starpack with command line parameter -inst.

          Both steps will copy the 3 above described package folders into the directory containing the starpack.


      2. Installation from a binary package

        The following prerequisites are needed when using a Tcl3D binary package:

        • An OpenGL driver suitable for your graphics card. It is recommend to download and install an up-to-date OpenGL driver from the manufacturer of your graphics card, especially if intending to write shader programs in GLSL or Cg.

        • A Tcl/Tk version greater or equal to 8.5.

        • The Img extension is needed to have access to various image formats, which are used as OpenGL textures.

        • For some demos the snack extension is used.

        • To generate screenshots from the Tcl3D presentation, the Twapi extension is needed on Windows.

          It is therefore recommended to use an ActiveTcl distribution [25], which contains all of the above listed Tcl extensions.


          Download and unzip the following distribution packages suitable for your operating system:

        • tcl3d-OS-0.5.0.zip

        • tcl3d-demos-0.5.0.zip


Then copy the resulting folders into the appropriate directories as described in the previous chapter.


2.2 Installation of a source distribution

2.2 Installation of a source distribution


This chapter outlines the general process of compiling, customising and installing the Tcl3D package. See the file Readme.txt in the source code distribution for additional up-to-date information.


      1. Step 1: Prerequisites

        The following prerequisites are needed when using a Tcl3D source package:

        • An OpenGL driver suitable for your graphics card. It is recommend to download and install an up-to-date OpenGL driver from the manufacturer of your graphics card, especially if intending to write shader programs in GLSL or Cg.

        • A Tcl/Tk version greater or equal to 8.5.

        • The Img extension is needed to have access to various image formats, which are used as OpenGL textures.

        • For some demos the snack extension is used.

        • To generate screenshots from the Tcl3D presentation, the Twapi extension is needed on Windows.

          It is therefore recommended to use an ActiveTcl distribution [25], which contains all of the above listed Tcl extensions.


          To build the Tcl3D modules from source, the following additional tools need to be installed and accessable from the command line:


          Tool

          Version

          URL

          GNU make

          >= 3.79

          http://www.gnu.org/

          SWIG

          >= 1.3.36

          http://www.swig.org/

          Table 2.2: Tools for building Tcl3D


          N o t e

        • A binary version of SWIG for IRIX is available from my private home page http://www.posoft.de/.

        • Tcl3D prior to version 0.4.1 has been successfully generated and tested with SWIG versions 1.3.24, 1.3.29 and 1.3.36.

        • For wrapping the OpenSceneGraph library, SWIG version 1.3.36 is needed. Older versions of SWIG (as stated above) are not supported anymore with Tcl3D versions 0.4.1 and newer.

        • See chapter 5.4 for known bugs with other SWIG versions.


          Download and unzip the following distribution packages suitable for your operating system:

        • tcl3d-src-0.5.0.zip

        • tcl3d-OS-0.5.0.zip

        • tcl3d-demos-0.5.0.zip

        • tcl3d-starpack-0.5.0.zip


          Example installation procedures


          Version 1: Tcl3D-Basic: OpenGL support, no external libraries

          Needed: tcl3d-src-0.5.0.zip

          Recommended: tcl3d-demos.0.5.0.zip


          Unzip tcl3d-src-0.5.0.zip in a folder of your choice. This creates a new folder tcl3d

          containing the sources. Unzip tcl3d-demos.0.5.0.zip into the new folder tcl3d. You should end up with a directory and file structure as shown in the next figure.

          image

          Figure 2.1: Tcl3D-Basic directory structure


          If only basic OGL support is needed, disable the optional modules by commenting all WRAP_* macro lines in file make.wrap.

          The presentation framework presentation.tcl works, but the texts are displayed as 2D bitmaps only. Most OpenGL only demos should work.


          Version 2: Tcl3D-Complete: OpenGL support plus optional modules

          Needed: tcl3d-src-0.5.0.zip

          Needed: tcl3d-OS-0.5.0.zip

          Recommended: tcl3d-demos.0.5.0.zip


          Unzip tcl3d-src-0.5.0.zip in a folder of your choice. This creates a new folder tcl3d

          containing the sources. Unzip tcl3d-demos.0.5.0.zip into the new folder tcl3d.

          Unzip tcl3d-OS-0.5.0.zip into a temporary folder. Then copy the dynamic libraries contained in subfolder extlibs/OS into a directory, which is listed in your PATH environment variable (Windows) or your LD_LIBRARY_PATH environment variable (Unix).


          You should end up with a directory and file structure as shown in figure 2.1.


          If you want to build the tcl3dCg module, you have to download and install the Cg toolkit version 2.2.0017 from [7]. After installation, copy all the Cg header files into the tcl3dCg/Twapi directory. These files are not included in the Tcl3D distribution because of license issues. The dynamic libraries of Cg are included in the Tcl3D distribution package tcl3d-OS-0.5.0.zip.

          If you want to wrap only a sub-set of the supported optional modules, edit the make.wrap file appropriately. See chapter 2.2.3 Step 3: Customization for details.


          Version 3: Tcl3D-Star: Tcl3D-Basic or Tcl3D-Complete with starpack support

          Needed: Installation of Version 1 or 2

          Needed: tcl3d-starpack-0.5.0.zip


          Perform the steps as described for Version 1 or 2. Additionally copy the folder extlibs contained in distribution package tcl3d-OS-0.5.0.zip into the source code folder tcl3d. Then unzip tcl3d-starpack-0.5.0.zip into the source code folder tcl3d.


          You should end up with a directory and file structure as shown in the next figure.

          image

          Figure 2.2: Tcl3D-Complete starpack directory structure


          N o t e

        • The starpack distribution package contains Tclkits for all supported operating systems, as well as supporting Tcl packages (tkImg, snack, ...) needed for the Tcl3D demonstration programs.


      2. Step 2: Configuration

        Before compiling, edit the appropriate config_* file to fit your platform/compiler combination:


        Operating system

        Compiler

        Configuration file

        Windows

        Visual C++ 7.1, 8.0, 9.0, 10.0

        config_win32

        Windows

        CygWin (gcc)

        config_cygwin

        Windows

        MinGW (gcc)

        config_msys

        Linux (32-bit)

        gcc

        config_Linux

        Linux (64-bit)

        gcc

        config_Linux64

        Mac OS X

        gcc

        config_Darwin

        SGI IRIX 6.5

        gcc, MIPS Pro 7.3

        config_IRIX64

        Table 2.3: Tcl3D configuration files


        N o t e

        • Visual C++ 6.0 and CygWin support have been deprecated.

        • MinGW is supported for the C modules only. The C++ modules tcl3dFTGL and tcl3dOsg

          can not be used with the supplied binaries of the libraries.

        • Visual Studio .NET 2003 corresponds to compiler version 7.1.

        • Visual Studio 2005 corresponds to compiler version 8.0.

        • Visual Studio 2008 corresponds to compiler version 9.0.

        • Visual Studio 2010 corresponds to compiler version 10.0.

        • To detect, if using a DOS console for compilation, the existence of environment variable VSINSTALLDIR is checked. This variable is also used to detect a .NET compiler (i.e. VS2005, VS2008 or VS2010, which need manifests).

        • For Unix systems, the name after the underscore is derived from the Unix commands uname -s and uname -m. See the file make.oscheck for details on the mapping of the command output.


          The following lines in the config_* files may be edited:

          WITH_DEBUG

          If you don't want debug information, remove ALL characters after the equal sign.

          INSTDIR

          Set to your preferred installation directory.

          TCLDIR

          Set to where your Tcl installation is located on disk.

          TKDIR

          Set to where your Tk installation is located on disk.

          TCLMINOR

          Set to your installed Tcl minor version.

          Table 2.4: Tcl3D configuration variables


          Examples:


          Compile with debugging information. The Tcl/Tk installation is located in /usr/local. We install the Tcl3D package into the same location as the Tcl distribution. The installed Tcl version is 8.5.


          WITH_DEBUG = 1

          INSTDIR = /usr/local TCLDIR = /usr/local TKDIR = /usr/local TCLMINOR = 5


          Compile without debugging information. The Tcl/Tk installation is located in C:\Programme\Tcl. We install the Tcl3D package into a separate directory. The installed Tcl version is 8.6.


          WITH_DEBUG =

          INSTDIR = C:\Programme\Tcl TCLDIR = C:\Programme\poSoft TKDIR = C:\Programme\poSoft TCLMINOR = 6


          Instead of editing the configuration file, you may alternatively create a file called make.private

          in the top level directory of Tcl3D and add lines according to your needs.


          ifeq ($(KERNEL),win32) INSTDIR = F:\Programme\poSoft TCLDIR = F:\Programme\Tcl TKDIR = F:\Programme\Tcl endif

          ifeq ($(KERNEL),mingw) INSTDIR = F:/Programme/poSoft TCLDIR = F:/Programme/Tcl TKDIR = F:/Programme/Tk endif


      3. Step 3: Customization

        The optional modules can be included or excluded from the compilation step by setting the following macros in file make.wrap in the top level directory of the Tcl3D source tree.


        Macro name

        Description

        Additional check file

        WRAP_CG

        Customize support for tcl3dCg

        Cg/cg.h

        WRAP_SDL

        Customize support for tcl3dSDL

        include/SDL.h

        WRAP_FTGL

        Customize support for tcl3dFTGL

        include/FTGL.h

        WRAP_GL2PS

        Customize support for tcl3dGl2ps

        gl2ps.h

        WRAP_ODE

        Customize support for tcl3dOde

        ode/ode.h

        Macro name

        Description

        Additional check file

        WRAP_OSG

        Customize support for tcl3dOsg

        include/osg/Object

        Table 2.5: Customization settings


        N o t e

        • Do not set a macro to 0, but comment the corresponding line (i.e. undefine), as shown in the following example:

          WRAP_FEATURE = 1 enables the feature

          # WRAP_FEATURE = 1 disables the feature


          Each Makefile of an optional module additionally checks for the existence of an important include file (as listed in column "Additional check file") to enable extension support for Tcl3D.


      4. Step 4: Compilation and installation

        The following commands should compile and install the Tcl3D package:


        > gmake

        > gmake install


        The make process prints out lines about the success of wrapping optional modules:

        Tcl3D built with Cg support Tcl3D built without ODE support

        ...


        The starpack is not generated by default. If you installed the starpack distribution package, you have to go into the directory starpack and call make there.


        N o t e

        • To test the generated starpack, copy it into a temporary directory and start it from there, as the starpack will copy external libraries into the current directory.


First installation tests


Start a tclsh or wish shell and type the following two commands:

> package require tcl3d

> togl .t

Now use either the command tcl3dShowPackageInfo for graphical package information or

tcl3dGetPackageInfo for textual package information.

If these procedures fail, you may try the low level information supplied in the Tcl array

tcl3dPkgInfo:


> parray tcl3dPkgInfo

tcl3dPkgInfo(tcl3dcg,avail) = 0

tcl3dPkgInfo(tcl3dcg,version) = Cg library not wrapped

tcl3dPkgInfo(tcl3dftgl,avail) = 1

tcl3dPkgInfo(tcl3dftgl,version) = 0.5.0


Version Tcl3D-Basic should print out information similar to the lines listed below, when calling

tcl3dGetPackageInfo:


{tcl3dcg 0 {Cg library not wrapped} {}}

{tcl3dftgl 0 {FTGL library not wrapped} {}}

{tcl3dgauges 1 0.5.0 {}}

{tcl3dgl2ps 0 {GL2PS library not wrapped} {}}

{tcl3dode 0 {ODE library not wrapped} {}}

{tcl3dogl 1 0.5.0 {1.4 APPLE-1.6.16}}

{tcl3dosg 0 {OSG library not wrapped} {}}

{tcl3dsdl 0 {SDL library not wrapped} {}}


Version Tcl3D-Complete should print out information similar to the lines listed below, when calling tcl3dGetPackageInfo:


{tcl3dcg 1 0.5.0 2.2.0017}

{tcl3dftgl 1 0.5.0 2.1.3-rc5}

{tcl3dgauges 1 0.5.0 {}}

{tcl3dgl2ps 1 0.5.0 1.3.5}

{tcl3dode 1 0.5.0 0.7.0}

{tcl3dogl 1 0.5.0 {1.4 APPLE-1.6.16}}

{tcl3dosg 1 0.5.0 2.8.2}

{tcl3dsdl 1 0.5.0 1.2.9}


2.3 Extending Tcl3D

2.3 Extending Tcl3D


TODO: This chapter will be filled in a future release.

TODO: This chapter will be filled in a future release.


      1. General information

        Each optional module wrapping a library (eg. SDL) has to have at least 2 files in folder tclfiles: pkgIndex.tcl and tcl3dPKGQuery.tcl.

        The latter file contains procedures to query functionality related to package PKG. All procedures contained in this file must be able to work, even if the corresponding dynamic library does not exist or is just a dummy.

        This file must be loaded in pkgIndex.tcl before the dynamic library. All other package related Tcl files should be loaded after the dynamic library.


      2. Extending with a Tcl utility


      3. Extending with a C/C++ utility


      4. Extending with a newer version of an external library


      5. Extending with a new external library

        3 Wrapping in detail

        3 Wrapping in detail


        This chapter explains, how parameters and return values of the C and C++-based library functions are mapped to Tcl command parameters and return values. The intention of the wrapping mechanism was to be as close to the C interface and use Tcl standard types wherever possible:

        • C functions are mapped to Tcl commands.

        • C constants are mapped to Tcl global variables.

        • Some C enumerations are mapped to Tcl global variables and are inserted into a Tcl hash table for lookup by name.


          The mapping described in this chapter is consistently applied to all libraries wrapped with Tcl3D. It is optimized to work best with the OpenGL interface.


          3.1 Wrapping description

          3.1 Wrapping description


          Conventions used in this chapter:


        • Every type of parameter is explained with a typical example from the OpenGL wrapping.

        • The notation TYPE stands for any scalar value (char, int, float, enum etc. as well as inherited scalar types like GLboolean, GLint, GLfloat, etc.). It is not used for type void or GLvoid.

        • The notation STRUCT stands for any C struct.

        • The decision how to map C to Tcl types was mainly inspired to fit the needs of the OpenGL library best. The same conventions are used for the optional modules, too.

        • Function parameters declared as const pointers are interpreted as input parameters. Parameters declared as pointer are interpreted output parameters.


      1. Scalar input parameters

        The mapping of most scalar types is handled by SWIG standard typemaps. Scalar types as function input parameter must be supplied as numerical value.

        Input parameter

        TYPE

        C declaration

        void glTranslatef (GLfloat x, GLfloat y, GLfloat z);

        C example

        glTranslatef (1.0, 2.0, 3.0); glTranslatef (x, y, z);

        Tcl example

        glTranslatef 1.0 2.0 3.0 glTranslatef $x $y $z

        Table 3.1: Wrapping of a scalar input parameter


        The mapping of the following enumerations is handled differently (see file tcl3dConstHash.i). They can be specified either as numerical value like the other scalar types, or additionally as a name identical to the enumeration name.

        • GLboolean

        • GLenum

        • GLbitfield

        • CGenum

        • CGGLenum

        • CGprofile

        • CGtype

        • CGresource

        • CGerror

          The mapping is explained using the 3 OpenGL enumeration types. The Cg types are handled accordingly.


          GLenum as function input parameter can be supplied as numerical value or as name.


          Input parameter

          GLenum

          C declaration

          void glEnable (GLenum cap);

          C example

          glEnable (GL_BLEND);

          Tcl example

          glEnable GL_BLEND glEnable $::GL_BLEND

          Table 3.2: Wrapping of a GLenum input parameter


          GLbitfield as function input parameter can be supplied as numerical value or as name.


          N o t e

        • A combination of bit masks has to be specified as a numerical value like this:

          glClear [expr $::GL_COLOR_BUFFER_BIT | $::GL_DEPTH_BUFFER_BIT]


          Input parameter

          GLbitfield

          C declaration

          void glClear (GLbitfield mask);

          C example

          glClear (GL_COLOR_BUFFER_BIT);

          Tcl example

          glClear GL_COLOR_BUFFER_BIT glClear $::GL_COLOR_BUFFER_BIT

          Table 3.3: Wrapping of a GLbitfield input parameter


          GLboolean as function input parameter can be supplied as numerical value or as name.


          Input parameter

          GLboolean

          C declaration

          void glEdgeFlag (GLboolean flag);

          C example

          glEdgeFlag (GL_TRUE);

          Tcl example

          glEdgeFlag GL_TRUE glEdgeFlag $::GL_TRUE

          Table 3.4: Wrapping of a GLboolean input parameter


      2. Pointer input parameters

        The mapping of const TYPE pointers is handled in file tcl3dPointer.i. Constant pointers as function input parameter must be supplied as a Tcl list.

        Input parameter

        const TYPE[SIZE], const TYPE *

        C declaration

        void glMaterialfv (GLenum face, GLenum pname,

        const GLfloat *params);

        C example

        GLfloat mat_diffuse = { 0.7, 0.7, 0.7, 1.0 }; glMaterialfv (GL_FRONT, GL_DIFFUSE, mat_diffuse);

        Tcl example

        set mat_diffuse { 0.7 0.7 0.7 1.0 } glMaterialfv GL_FRONT GL_DIFFUSE $mat_diffuse

        Table 3.5: Wrapping of a pointer input parameter


        N o t e

        • This type of parameter is typically used to specify small vectors (2D, 3D and 4D) as well as control points for NURBS.

        • Unlike in the C version, specifying data with the scalar version of a function (ex.

          glVertex3f) is faster than the vector version (ex. glVertex3fv) in Tcl.

        • Tcl lists given as parameters to a Tcl3D function have to be flat, i.e. they are not allowed to contain sublists. When working with lists of lists, you have to flatten the list, before supplying it as an input parameter to a Tcl3D function. One way to do this is shown in the example below.


          set ctrlpoints {

          {-4.0 -4.0 0.0} {-2.0 4.0 0.0}

          { 2.0 -4.0 0.0} { 4.0 4.0 0.0}

          }

          glMap1f GL_MAP1_VERTEX_3 0.0 1.0 3 4 [join $ctrlpoints]


          The mapping of const void pointers is handled by SWIG standard typemaps.


          Constant void pointers as function input parameter must be given as a pointer to a contiguous piece of memory of appropriate size.


          Input parameter

          const void[SIZE], const void *

          C declaration

          void glVertexPointer (GLint size, GLenum type,

          GLsizei stride, const GLvoid *ptr);


          C example

          static GLint vertices[] =

          { 25, 25, 100, 325, 175, 25,

          175, 325, 250, 25, 325, 325};

          glVertexPointer (2, GL_INT, 0, vertices);


          Tcl example

          set vertices [tcl3dVectorFromArgs GLint \ 25 25 100 325 175 25 \

          175 325 250 25 325 325]

          glVertexPointer 2 GL_INT 0 $::vertices

          Table 3.6: Wrapping of a void pointer input parameter


          N o t e

        • The allocation of usable memory can be accomplished with the use of the tcl3dVector

          commands, which are described in chapter 4.3.5.

        • This type of parameter is typically used to supply image data or vertex arrays. See also the description of the image utility module in chapter 4.3.6.


      3. Output parameters

        The mapping of non-constant pointers is handled by the SWIG standard typemaps.


        Non-constant pointers as function output parameter must be given as a pointer to a contiguous piece of memory of appropriate size (tcl3dVector). See note above.

        Output parameter

        TYPE[SIZE], void[SIZE], TYPE *, void *


        C declaration

        void glGetFloatv (GLenum pname, GLfloat *params);


        void glReadPixels (GLint x, GLint y, GLsizei width,

        GLsizei height, GLenum format, GLenum type, GLvoid *pixels);


        C example

        GLfloat values[2];

        glGetFloatv (GL_LINE_WIDTH_GRANULARITY, values);


        GLubyte *vec = malloc (w * h * 3);

        glReadPixels (0, 0, w, h, GL_RGB, GL_UNSIGNED_BYTE, vec);


        Tcl example

        set values [tcl3dVector GLfloat 2] glGetFloatv GL_LINE_WIDTH_GRANULARITY $values


        set vec [tcl3dVector GLubyte [expr $w * $h * 3]] glReadPixels 0 0 $w $h GL_RGB GL_UNSIGNED_BYTE $vec

        Table 3.7: Wrapping of a pointer output parameter


      4. Function return values

        The mapping of return values is handled by the SWIG standard typemaps. Scalar return values are returned as the numerical value.

        Pointer to structs are returned with the standard SWIG mechanism of encoding the pointer in an

        ASCII string.


        Function return

        TYPE, STRUCT *

        C declaration

        GLuint glGenLists (GLsizei range);


        GLUnurbs* gluNewNurbsRenderer (void);


        C example

        GLuint sphereList = glGenLists(1);


        GLUnurbsObj *theNurb = gluNewNurbsRenderer(); gluNurbsProperty (theNurb, GLU_SAMPLING_TOLERANCE, 25.0);


        Tcl example

        set sphereList [glGenLists 1]


        set theNurb [gluNewNurbsRenderer]

        gluNurbsProperty $theNurb GLU_SAMPLING_TOLERANCE 25.0

        Table 3.8: Wrapping of a function return value


        The next lines show an example of SWIG’s pointer encoding:


        % set theNurb [gluNewNurbsRenderer]

        % puts $theNurb

        _10fa1500_p_GLUnurbs


        The returned name can only be used in functions expecting a pointer to the appropriate struct.


      5. Exceptions from the standard rules

        The GLU library as specified in header file glu.h does not provide an API, that is using the const specifier as consistent as the GL core library. So one class of function parameters (TYPE*) is handled differently with GLU functions. Arguments of type TYPE* are used both as input and output parameters in the C version. In GLU 1.2 most functions use this type as input parameter. Only two functions use this type as an output parameter.

        So for GLU functions there is the exception, that TYPE* is considered an input parameter and therefore is wrapped as a Tcl list.


        Input parameter

        TYPE * (GLU only)


        C declaration

        void gluNurbsCurve (GLUnurbs *nobj, GLint nknots,

        GLfloat *knot, GLint stride, GLfloat *ctlarray, GLint order, GLenum type);


        C example

        GLfloat curvePt[4][2] = {{0.25, 0.5}, {0.25, 0.75},

        {0.75, 0.75}, {0.75, 0.5}};

        GLfloat curveKnots[8] = {0.0, 0.0, 0.0, 0.0,

        1.0, 1.0, 1.0, 1.0};

        gluNurbsCurve (theNurb, 8, curveKnots, 2,

        &curvePt[0][0], 4, GLU_MAP1_TRIM_2);


        Tcl example

        set curvePt {0.25 0.5 0.25 0.75 0.75 0.75 0.75 0.5}

        set curveKnots {0.0 0.0 0.0 0.0 1.0 1.0 1.0 1.0}

        gluNurbsCurve $theNurb 8 $curveKnots 2 $curvePt 4 GLU_MAP1_TRIM_2

        Table 3.9: Wrapping of GLU functions


        The two aforementioned functions, which provide output parameters with TYPE* are gluProject and gluUnProject. These are handled as a special case in the SWIG interface file glu.i. The 3 output parameters are given the keyword OUTPUT, so SWIG handles them in a special way: SWIG builds a list consisting of the normal function return value, and all parameters marked with that keyword. This list will be the return value of the corresponding Tcl command.


        Definition in glu.h

        Redefinition in SWIG interface file glu.i

        extern GLint gluUnProject (

        GLint gluUnProject (

        GLdouble winX, GLdouble winY,

        GLdouble winX, GLdouble winY,

        GLdouble winZ,

        GLdouble winZ,

        const GLdouble *model,

        const GLdouble *model,

        const GLdouble *proj,

        const GLdouble *proj,

        const GLint *view,

        const GLint *view,

        GLdouble* objX,

        GLdouble* OUTPUT,

        GLdouble* objY,

        GLdouble* OUTPUT,

        GLdouble* objZ);

        GLdouble* OUTPUT);

        Table 3.10: Wrapping exceptions for GLU


        Example usage (see Redbook example unproject.tcl for complete code):


        glGetIntegerv GL_VIEWPORT $viewport glGetDoublev GL_MODELVIEW_MATRIX $mvmatrix glGetDoublev GL_PROJECTION_MATRIX $projmatrix set viewList [tcl3dVectorToList $viewport 4] set mvList [tcl3dVectorToList $mvmatrix 16] set projList [tcl3dVectorToList $projmatrix 16]


        set realy [expr [$viewport get 3] - $y - 1]

        set winList [gluUnProject $x $realy 0.0 $mvList $projList $viewList]

        puts "gluUnProject return value: [lindex $winList 0]" puts [format "World coords at z=0.0 are (%f, %f, %f)" \

        [lindex $winList 1] [lindex $winList 2] [lindex $winList 3]]


        N o t e

        • The above listed exceptions are only valid for the GLU library. The optional modules have not been analysed in-depth regarding the constness of parameters.


4.1 tcl3dOgl->Togl: Enhanced Togl widget

4.1 tcl3dOgl->Togl: Enhanced Togl widget


Togl [6] is a Tk widget with support to display graphics in an OpenGL context. The original version only supported issuing drawing commands in C. To be usable from the Tcl level, it has been extended with configuration options for specifying Tcl callback commands.


Requirements for this module: None, all files are contained in the Tcl3D distribution.


      1. Togl commands

        The following is a list of currently available Togl commands. The commands changed or new in Tcl3D are marked bold and explained in detail below. For a description of the other commands see the original Togl documentation.


        configure render swapbuffers makecurrent postredisplay loadbitmapfont

        unloadbitmapfont

        width height


        Bitmap fonts


        Specifying bitmap fonts can be accomplished with the loadbitmapfont command. The font can either be specified in XLFD format or Tk-like with the following options:


        –family courier|times|...

        -weight medium|bold

        -slant regular|italic

        –size PixelSize


        Examples:


        $toglwin loadbitmapfont -*-courier-bold-r-*-*-10-*-*-*-*-*-*-*

        $toglwin loadbitmapfont -family fixed -size 12 -weight medium -slant regular


        See the tcl3dToglFonts.tcl and tcl3dFont.tcl demos for more examples, on how to use fonts with Togl.


      2. Togl options

        The following is a list of currently available Togl options. The options changed or new in Tcl3D are marked bold and explained in detail below. For a description of the other options see the original Togl documentation.


        -height -width -setgrid

        -rgba -redsize -greensize -bluesize

        -double -depth -depthsize -accum

        -accumredsize -accumgreensize -accumbluesize -accumalphasize

        -alpha -alphasize -stencil -stencilsize

        -auxbuffers -privatecmap -overlay -stereo

        -cursor -time -sharelist -sharecontext

        -ident -indirect -pixelformat

        -swapinterval -multisamplebuffers -multisamplesamples

        -createproc -displayproc -reshapeproc

        image

        -coreprofile -major -minor


        These configuration options behave like standard Tcl options and can be queried as such:


        % package require tcl3d ; # or just package require tcl3dogl 0.5.0

        % togl .t

        % .t configure

        {-height height Height 400 400} …

        {-displayproc displayproc Displayproc {} {}} …

        % .t configure -displayproc DisplayCallback

        % .t configure -displayproc

        -displayproc displayproc Displayproc {} DisplayCallback


        Callback procedures


        To be usable from the Tcl level, the Togl widget has been extended to support 3 new configuration options for specifying Tcl callback procedures:


        -createproc ProcName Procedure is called when a new widget is created.

        -reshapeproc ProcName Procedure is called when the widget's size is changed.

        -displayproc ProcName Procedure is called when the widget's content needs to be redrawn. Default settings are:

        {-createproc createproc Createproc {} {}}

        {-displayproc displayproc Displayproc {} {}}

        {-reshapeproc reshapeproc Reshapeproc {} {}}


        The callback procedures must have the following signatures:


        proc

        CreateProc

        {

        toglwin

        }

        {

        ...

        }

        proc

        ReshapeProc

        {

        toglwin

        }

        {

        ...

        }

        proc

        DisplayProc

        {

        toglwin

        }

        {

        ...

        }

        N o t e :

        Starting with Tcl3D version 0.5.0 the Togl version used in Tcl3D is based on version 2.0. The advantages are Tcl_Obj based callback functions and a cleaner code base. All callbacks now have the same signature, i.e. only the Togl widget identifier. This introduces an incompatibilty with previous Tcl3D versions, where the Reshape callback function had additional parameters for the new width and height of the Togl window. See the Tcl3D demos or the example below for backward compatible changes to the Reshape callback.

        Starting with Tcl3D version 0.5.0 the Togl version used in Tcl3D is based on version 2.0. The advantages are Tcl_Obj based callback functions and a cleaner code base. All callbacks now have the same signature, i.e. only the Togl widget identifier. This introduces an incompatibilty with previous Tcl3D versions, where the Reshape callback function had additional parameters for the new width and height of the Togl window. See the Tcl3D demos or the example below for backward compatible changes to the Reshape callback.


        Display options


        -swapinterval Enable/disable synchronisation to vertical blank signal

        -multisamplebuffers Enable/disable the multisample buffer

        -multisamplesamples Set the number of multisamples Default settings are:

        {-swapinterval swapInterval SwapInterval 0 0}

        {-multisamplebuffers multisampleBuffers MultisampleBuffers 0 0}

        {-multisamplesamples multisampleSamples MultisampleSamples 2 2}


        N o t e

        • Multisampling was implemented for the Togl widget in Tcl3D version 0.3.2. If working with older versions of Tcl3D, you may enable multisampling outside of Tcl3D as follows:

          With NVidia cards, you can enable multisampling under Windows via the NVidia driver GUI. Under Linux you can set the environment variable GL_FSAA_MODE to 1.

        • The default value for -swapinterval has been changed in version 0.4.0 from 1 to 0, i.e. if this option is not specified, a Tcl3D program does not wait for the vertical blank signal, but runs at maximum speed.


          image

          Profile options


          -coreprofile Enable/disable the OpenGL core profile.

          -major Set the OpenGL major number for the core profile.

          -minor Set the OpenGL minor number for the core profile.


          Default settings are:


          {-coreprofile coreProfile CoreProfile false 0}

          {-major major Major 1 1}

          {-minor minor Minor 0 0}


      3. A simple Tcl3D template

        A template for a Tcl3D application looks like follows:


        package require tcl3d


        proc CreateCallback { toglwin } {

        glShadeModel GL_SMOOTH ; # Enable smooth shading glClearColor 0.0 0.0 0.0 0.5 ; # Black background glClearDepth 1.0 ; # Depth buffer setup glEnable GL_DEPTH_TEST ; # Enable depth testing

        }

        proc ReshapeCallback { toglwin { w -1 } { h -1 } } {

        set w [$toglwin width] ; # Get Togl window width set h [$toglwin height] ; # Get Togl window height

        glViewport 0 0 $w $h ; # Reset the current viewport glMatrixMode GL_PROJECTION ; # Select the projection matrix glLoadIdentity ; # Reset the projection matrix


        # Calculate the aspect ratio of the window

        gluPerspective 45.0 [expr double($w)/double($h)] 0.1 100.0


        glMatrixMode GL_MODELVIEW ; # Select the modelview matrix glLoadIdentity ; # Reset the modelview matrix

        }


        proc DisplayCallback { toglwin } {

        # Clear color and depth buffer

        glClear [expr $::GL_COLOR_BUFFER_BIT | $::GL_DEPTH_BUFFER_BIT]

        glLoadIdentity ; # Reset the current modelview matrix glTranslatef 0.0 0.0 -5.0 ; # Transformations

        glRotatef $::xrot 1.0 0.0 0.0

        glRotatef $::yrot 0.0 1.0 0.0

        glRotatef $::zrot 0.0 0.0 1.0


        drawGeometry ; # Draw the actual geometry


        $toglwin swapbuffers ; # Swap front and back buffer

        }


        frame .fr

        pack .fr -expand 1 -fill both

        # Create a Togl widget with a depth buffer and doublebuffering enabled. togl .fr.toglwin -width 250 -height 250 \

        -double true -depth true \

        -createproc CreateCallback \

        -reshapeproc ReshapeCallback \

        -displayproc DisplayCallback grid .fr.toglwin -row 0 -column 0 -sticky news


        N o t e

        • Option –createproc is not effective, when specified in the configure subcommand. It has to be specified at widget creation time.


          4.2 tcl3dOgl->OpenGL: Wrapper for OpenGL functionality

          4.2 tcl3dOgl->OpenGL: Wrapper for OpenGL functionality


          This module wraps OpenGL functionality up to OpenGL Version 4.1, GLU library functions based on Version 1.2 and several OpenGL extensions.

          It is implemented with the help of the GLEW [14] library.

          Standard shapes (box, sphere, cylinder, teapot, …) with a GLUT compatible syntax are supplied in this module, too.


          Requirements for this module: An OpenGL driver suitable for your graphics card. It is recommend to download and install an up-to-date OpenGL driver from the manufacturer of your graphics card, especially if intending to write shader programs in GLSL or Cg.


          The master SWIG file for wrapping the OpenGL library is tcl3dOgl.i.


          OpenGL library

          Implementation files: tcl3dOglQuery.tcl, tcl3dOglUtil.tcl, tcl3dOglHelp.txt

          Header files: glew.h, glu.h

          Wrapper files: glew.i, glewautogen.i, glu.i

          Implementation files: tcl3dOglQuery.tcl, tcl3dOglUtil.tcl, tcl3dOglHelp.txt

          Header files: glew.h, glu.h

          Wrapper files: glew.i, glewautogen.i, glu.i


          image

          The wrapping for this module is based on the header files glew.h and glu.h.


          N o t e

        • The original GLEW header file is not usable for direct wrapping with Swig, so it's infor- mation is used for generating the wrapper files glewdefs.i and glewfuncs.i during the build process with Tcl script createSwigAndHelpFile.tcl.

        • File tcl3dOglHelp.tcl is automatically generated by script createSwigAndHelpFile.tcl too.

        • See the ReadmeGlew.txt file in subdirectory GLSpec for more detailled information about the GLEW wrapping and update process.


          The next figure shows the dependencies of the build process.


          image

          www.opengl.org


          glExtUrlList.html

          glExtUrlList.html

          OpenGL

          Reference Manuals


          tcl3dOglHelp.txt

          tcl3dOglHelp.txt

          createFuncUrlList.tcl createExtUrlList.tcl


          glFuncUrlList.txt

          glExtUrlList.txt

          glew.h glu.h gl.spec


          createSwigAndHelpFile.tcl


          glewdefs.i

          glewfuncs.i

          tcl3dOglHelp.tcl


          Figure 4.1: Build dependencies of the tcl3dOgl module

          The following Tcl3D specific commands are implemented in this module:


          Tcl3D command

          Description

          tcl3dOglGetVersion

          Get the OpenGL version string.

          tcl3dOglGetVersionNumber

          Get the OpenGL version number as a dictionary.

          tcl3dOglGetGlewVersion

          Get the version of the used GLEW library.

          tcl3dOglGetProfile

          Get OpenGL profile settings.

          tcl3dOglHaveFunc

          Check availability of an OpenGL function in the OpenGL driver.

          tcl3dOglHaveExtension

          Check, if a given OpenGL extension is provided by the OpenGL implementation.

          tcl3dOglHaveVersion

          Check, if a specific OpenGL version is available.

          tcl3dOglGetVersions

          Query the OpenGL library with the keys GL_VENDOR, GL_RENDERER, GL_VERSION, GLU_VERSION and return

          the results as a list of key-value pairs.

          tcl3dOglGetExtensions

          Query the OpenGL library with the keys GL_EXTENSIONS and GLU_EXTENSIONS and return the results as a list of key-value pairs.

          tcl3dOglGetStates

          Query all state variables of the OpenGL library and return the results as a list of sub-lists. Each sublist contains a

          Tcl3D command

          Description

          flag indicating the sucess of the query, the querying command used, the key and the value(s). Deprecated.

          tcl3dOglGetIntState

          Get OpenGL integer state variable.

          tcl3dOglGetFloatState

          Get OpenGL float state variable.

          tcl3dOglGetDoubleState

          Get OpenGL double state variable.

          tcl3dOglGetMaxTextureSize

          Get maximum texture size.

          tcl3dOglGetMaxTextureUnits

          Get maximum number of texture units.

          tcl3dOglGetViewport

          Get current viewport as a 4-element Tcl list.

          tcl3dOglGetShaderState

          Utility function for easier use of OpenGL function

          glGetShaderiv.

          tcl3dOglGetProgramState

          Utility function for easier use of OpenGL function

          glGetProgramiv.

          tcl3dOglGetShaderInfoLog

          Utility function for easier use of OpenGL function

          glGetShaderInfoLog.

          tcl3dOglGetProgramInfoLog

          Utility function for easier use of OpenGL function

          glGetProgramInfoLog.

          tcl3dOglGetShaderSource

          Utility function for easier use of OpenGL function

          glGetShaderSource.

          tcl3dOglGetInfoLogARB

          Utility function for easier use of OpenGL function

          glGetInfoLogARB.

          tcl3dOglShaderSource

          Utility function for easier use of OpenGL function

          glShaderSource.

          tcl3dOglReadShaderFile

          Read a shader file.

          tcl3dOglCompileProgram

          Compile a shader program.

          tcl3dOglLinkProgram

          Link a shader program.

          tcl3dOglBuildProgram

          Build a shader program.

          tcl3dOglDestroyProgram

          Destroy a shader program.

          glMultiDrawElements

          Procedure to implement the OpenGL function

          glMultiDrawElements.

          tcl3dOglGetGlError

          Check, if an OpenGL related error has been occurred.

          tcl3dOglGetFuncList

          Return a list of the names of all wrapped OpenGL functions.

          tcl3dOglGetFuncSignatureList

          Return a list of the C-signatures of all wrapped OpenGL functions.

          Deprecated. Use tclOglGetFuncSignature instead.

          tcl3dOglGetFuncVersionList

          Return a list of the OpenGL versions or extensions of all wrapped OpenGL functions.

          Deprecated. Use tclOglGetFuncVersion instead.

          tcl3dOglGetVersionList

          Get list of wrapped OpenGL versions and extensions.

          tcl3dOglGetExtensionList

          Get list of all OpenGL extensions.

          tcl3dOglIsFuncWrapped

          Check if OpenGL or GLU function is wrapped.

          tcl3dOglGetFuncSignature

          Get the signature of an OpenGL or GLU function.

          tcl3dOglGetFuncVersion

          Get the version or extension name of an OpenGL function.

          tcl3dOglGetEnumVersion

          Get the version or extension name of an OpenGL enumeration.

          tcl3dOglGetFuncDeprecated

          Get the OpenGL version, an OpenGL function has been declared deprecated.

          tcl3dOglGetUrl

          Get the URL of the official documentation of an OpenGL item.

          tcl3dOglGetVersionFuncs

          Get the function names of an OpenGL version or

          Tcl3D command

          Description

          extension.

          tcl3dOglGetVersionEnums

          Get the enumeration names of an OpenGL version or extension.

          tcl3dOglGetExtSuffixes

          Get list of allowed OpenGL extension suffixes.

          tcl3dOglFindFunc

          Find an OpenGL core or extension function.

          tcl3dOglSetNormalMode

          Set the execution mode of OpenGL functions to normal.

          tcl3dOglSetSafeMode

          Set the execution mode of OpenGL functions to safe.

          tcl3dOglSetDebugMode tcl3dOglSetMode

          Set the execution mode of OpenGL functions to debug. Set the execution mode of OpenGL functions.

          Table 4.1: tcl3dOgl helper commands

          N o t e

        • The functions glGetString and gluGetString as well as the corresponding high-level functions tcl3dOglGetVersions and tcl3dOglGetExtensions only return correct values, if a Togl window has been created, i.e. a rendering context has been established. This holds true for function tcl3dOglHaveFunc, too.

        • See Hint 6 in chapter 5.2 for the differences between the GLEW extension library and the previously used OglExt extension library.


          image

          GLUT shapes library


          Implementation files: tcl3dShapesGlut.c, tcl3dShapesTeapot.c, tcl3dShapesGlut.tcl

          Header files: tcl3dShapesGlut.h

          Wrapper files: tcl3dOgl.i

          Implementation files: tcl3dShapesGlut.c, tcl3dShapesTeapot.c, tcl3dShapesGlut.tcl

          Header files: tcl3dShapesGlut.h

          Wrapper files: tcl3dOgl.i


          The shapes library consists of C files (tcl3dShapesTeapot.c for the teapot, tcl3dShapesGlut.c for all other GLUT shapes and the common header file tcl3dShapesGlut.h) and the Tcl file tcl3dShapesGlut.tcl.


          The GLUT shape objects are available under identical names for porting test and demonstration programs to Tcl3D. These shapes are used extensively in the examples of the OpenGL redbook [27]. See there for a description of the functions and its parameters.


          Solid shapes

          Wire shapes

          glutSolidCone

          glutWireCone

          glutSolidCube

          glutWireCube

          glutSolidDodecahedron

          glutWireDodecahedron

          glutSolidIcosahedron

          glutWireIcosahedron

          glutSolidOctahedron

          glutWireOctahedron

          glutSolidSphere

          glutWireSphere

          glutSolidTeapot

          glutWireTeapot

          glutSolidTetrahedron

          glutWireTetrahedron

          glutSolidTorus

          glutWireTorus

          Table 4.2: tcl3dOgl GLUT shape commands


          N o t e

        • The teapot implementation differs in the original GLUT and the freeglut implementation. If using the teapot in a benchmark application, note that:

          Freeglut uses 7 for the grid parameter.

          Original GLUT and Tcl3D use 14 as grid parameter.


          image

          All supported GLUT compatible shapes (Demo glutShapes.tcl)


          Examples


          The following code snippet shows how to call tcl3dOglGetVersions.


          foreach glInfo [tcl3dOglGetVersions] {

          puts "[lindex $glInfo 0]: [lindex $glInfo 1]"

          }


          GL_VENDOR: ATI Technologies Inc. GL_RENDERER: ATI Radeon HD 5800 Series

          GL_VERSION: 3.2.9704 Compatibility Profile Context GLU_VERSION: 1.2.2.0 Microsoft Corporation GL_SHADING_LANGUAGE_VERSION: 1.50

          GLEW_VERSION: 1.5.4


          image

          The following code snippet shows how to call tcl3dOglGetExtensions.


          foreach glInfo [tcl3dOglGetExtensions] { puts "[lindex $glInfo 0]:"

          foreach ext [lsort [lindex $glInfo 1]] { puts "\t$ext"

          }

          }


          GL_EXTENSIONS:

          GL_ARB_depth_texture GL_ARB_fragment_program GL_ARB_imaging

          … GLU_EXTENSIONS:

          GL_EXT_bgra


          N o t e :

          tcl3dOglGetExtensions lists the extensions supported by the running OpenGL driver. Use

          tcl3dOglGetExtensionList to get a list of all specified OpenGL extensions.


          See the demo program tcl3dInfo.tcl for other examples on how to use these procedures.


          4.3 tcl3dOgl->Util: Tcl3D utility library

          4.3 tcl3dOgl->Util: Tcl3D utility library


          This module implements several utilities in C and Tcl offering functionality needed for 3D programs. It currently contains the following components:

        • 3D vector and transformation matrix component

        • Information component

        • File utility component

        • Color names component

        • Large data component (tcl3dVector)

        • Image utility component

        • Screen capture component

        • Timing component

        • Random number component

        • 3D-model and shapes component

        • Virtual trackball and arcball component

        • C/C++ based utilities for demo applications


Requirements for this module: None, all files are contained in the Tcl3D distribution. The master SWIG file for wrapping the utility library is util.i.

      1. 3D vector and transformation matrix module

        This module provides miscellaneous 3D vector and 4x4 transformation matrix functions.


        Overview


        The following tables list the available functions of this module. For a detailed description of the functions see the Tcl3D Reference Manual [5] or the source code files as listed in section Implementation details at the end of this chapter.


        Tcl3D command

        Description

        tcl3dVec3Print

        Print the contents of a 3D vector onto standard output.

        tcl3dVec3fCompare

        Compare two 3D vectors.

        tcl3dVec3fIdentity

        Fill a 3D vector with (0.0, 0.0, 0.0).

        tcl3dVec3fCopy

        Copy a 3D vector.

        tcl3dVec3fLength

        Calculate the length of a 3D vector.

        tcl3dVec3fNormalize

        Normalise a 3D vector.

        tcl3dVec3fDistance

        Calculate the distance between two 3D vectors.

        tcl3dVec3fDotProduct

        Calculate the dot product of two 3D vectors.

        tcl3dVec3fCrossProduct

        Calculate the cross product of two 3D vectors.

        tcl3dVec3fAdd

        Add two 3D vectors.

        tcl3dVec3fSubtract

        Subtract two 3D vectors.

        tcl3dVec3fScale

        Scale a 3D vector by a scalar value.

        tcl3dVec3fPlaneNormal

        Create a plane normal defined by three points.

        Table 4.3: tcl3dUtil: 3D vector commands

        N o t e

        • All above listed 3D vector commands are available for single-precision (prefix tcl3dVec3f) and double-precision (prefix tcl3dVec3d) floating point numbers.


          Tcl3D command

          Description

          tcl3dMatPrint

          Print the contents of a matrix onto standard output.

          tcl3dMatfCompare

          Compare two transformation matrices.

          tcl3dMatfIdentity

          Build the identity transformation matrix.

          tcl3dMatfCopy

          Copy a transformation matrix.

          tcl3dMatfTranslatev

          Build a translation matrix based on a 3D vector.

          tcl3dMatfTranslate

          Build a translation matrix based on 3 scalar values.

          tcl3dMatfRotate

          Build a rotation matrix based on angle (°) and axis.

          tcl3dMatfRotateX

          Build a rotation matrix based on angle (°) around x axis.

          Tcl3D command

          Description

          tcl3dMatfRotateY

          Build a rotation matrix based on angle (°) around y axis.

          tcl3dMatfRotateZ

          Build a rotation matrix based on angle (°) around z axis.

          tcl3dMatfScalev

          Build a scale matrix based on a 3D vector.

          tcl3dMatfScale

          Build a scale matrix based on 3 scalar values.

          tcl3dMatfTransformPoint

          Transform a point by a given matrix.

          tcl3dMatfTransformVector

          Transform a 3D vector by a given matrix.

          tcl3dMatfMult

          Multiply two transformation matrices.

          tcl3dMatfInvert

          Invert a transformation matrix.

          tcl3dMatfTranspose

          Transpose a transformation matrix.

          tcl3dMultMatrixf

          Replacement function for glMultMatf.

          tcl3dRotatef

          Replacement function for glRotatef.

          tcl3dScalef

          Replacement function for glScalef.

          tc3dTranslatef

          Replacement function for glTranslatef.

          Table 4.4: tcl3dUtil: Matrix commands

          N o t e

        • All above listed 4x4 matrix commands are available for single-precision (prefix tcl3dMatf) and double-precision (prefix tcl3dMatd) floating point numbers.


          Tcl3D command

          Description

          tcl3dOrtho

          Replacement function for glOrtho.

          tcl3dFrustum

          Replacement function for glFrustum.

          tcl3dPerspective

          Replacement function for gluPerspective.

          tcl3dLookAt

          Replacement function for gluLookAt.

          Table 4.5: tcl3dUtil: View commands

          Examples


          See the test programs matmathtest.tcl and vecmathtest.tcl for examples, on how to use these procedures. Also take a look at the demo program ogl_fps_controls.tcl for a real-world example.


          Implementation details


          image

          The functionality of this module is implemented in the following files:


          Implementation files: tcl3dVecMath.c, tcl3dViewMath.c, tcl3dVecMath.tcl

          Header files: tcl3dVecMath.h, tcl3dViewMath.h

          Wrapper files: util.i

          Implementation files: tcl3dVecMath.c, tcl3dViewMath.c, tcl3dVecMath.tcl

          Header files: tcl3dVecMath.h, tcl3dViewMath.h

          Wrapper files: util.i


      2. Information module

        This module provides convenience functions for querying Tcl3D package related information.


        Overview


        The following table lists the available functions of this module. For a detailed description of the functions see the Tcl3D Reference Manual [5] or the source code files as listed in section Implementation details at the end of this chapter.

        Tcl3D command

        Description

        tcl3dHavePackage

        Check, if a Tcl package is available in a given version.

        tcl3dGetLibraryInfo

        Return the library version corresponding to supplied Tcl3D package name.

        tcl3dGetPackageInfo

        Return a list of sub-lists containing Tcl3D package information. Each sub-list contains the name of the Tcl3D sub-package, the availability flag (0 or 1), the sub-package version as well as the version of the wrapped library.

        tcl3dShowPackageInfo

        Display the version info returned by tcl3dGetPackageInfo in a toplevel window.

        tcl3dHaveCg

        Check, if the Cg library has been loaded successfully.

        tcl3dHaveSDL

        Check, if the SDL library has been loaded successfully.

        tcl3dHave

        Check, if the FTGL library has been loaded successfully.

        tcl3dHaveGl2ps

        Check, if the GL2PS library has been loaded successfully.

        tcl3dHaveOde

        Check, if the ODE library has been loaded successfully.

        tcl3dHaveOsg

        Check, if the OSG library has been loaded successfully.

        Table 4.6: tcl3dUtil: Information commands


        Examples


        The following code snippet shows how to call tcl3dGetPackageInfo.


        foreach pkgInfo [tcl3dGetPackageInfo] {

        puts "[lindex $pkgInfo 0]: [lindex $pkgInfo 1]"

        }


        {tcl3dcg 1 0.5.0 2.2.0017}

        {tcl3dftgl 1 0.5.0 2.1.3-rc5}

        {tcl3dgauges 1 0.5.0 {}}

        {tcl3dgl2ps 1 0.5.0 1.3.5}

        {tcl3dode 1 0.5.0 0.7.0}

        {tcl3dogl 1 0.5.0 {1.4 APPLE-1.6.16}}

        {tcl3dosg 1 0.5.0 2.8.2}

        {tcl3dsdl 1 0.5.0 1.2.9}


        Implementation details


        image

        The functionality of this module is implemented in the following files:


        Implementation files: tcl3dUtilInfo.tcl

        Header files: None

        Wrapper files: None

        Implementation files: tcl3dUtilInfo.tcl

        Header files: None

        Wrapper files: None


      3. File utility module

        This module provides miscellaneous functions for file related tasks: Handling of temporary directories and file access from a starpack.


        Overview


        The following table lists the available functions of this module. For a detailed description of the functions see the Tcl3D Reference Manual [5] or the source code files as listed in section Implementation details at the end of this chapter.

        Tcl3D command

        Description

        tcl3dGetTmpDir

        Get the name of a temporary directory.

        tcl3dCreateTmpDir

        Create a unique temporary directory.

        tcl3dGenExtName

        Create a name on the file system. Use this function, if writing to a file from a script, which may be running from within a starpack.

        tcl3dGetExtFile

        Get a name on the file system. Use this function, if a file is needed for reading from an external Tcl3D library, like font files used by FTGL, or shader files, and the script may be executed from within a starpack.

        Table 4.7: tcl3dUtil: File utility commands


        Examples


        See the demo program Lesson02.tcl for an example usage of tcl3dGenExtName, and demo

        ftglTest.tcl for an example usage of tcl3dGetExtFile .


        Implementation details


        image

        The functionality of this module is implemented in the following files:


        Implementation files: tcl3dUtilFile.tcl

        Header files: None

        Wrapper files: None

        Implementation files: tcl3dUtilFile.tcl

        Header files: None

        Wrapper files: None


      4. Color names module

        This module provides miscellaneous functions for handling color specifications in Tcl and OpenGL style.


        Overview


        The following table lists the available functions of this module. For a detailed description of the functions see the Tcl3D Reference Manual [5] or the source code files as listed in section Implementation details at the end of this chapter.


        Tcl3D command

        Description

        tcl3dGetColorNames

        Return a list of all supported Tcl color names.

        tcl3dFindColorName

        Check, if supplied color name is a valid Tcl color name.

        tcl3dName2Hex

        Convert a Tcl color name into the corresponding hexadecimal representation: #RRGGBB

        tcl3dName2Hexa

        Convert a Tcl color name into the corresponding hexadecimal representation: #RRGGBBAA

        tcl3dName2rgb

        Convert a Tcl color specification into the corresponding OpenGL representation. OpenGL colors are returned as a list of 3 unsigned bytes: r g b

        tcl3dName2rgbf

        Convert a color specification into the corresponding OpenGL representation. OpenGL colors are returned as a list of 3 floats in the range [0..1]: r g b

        tcl3dName2rgba

        Convert a color specification into the corresponding OpenGL representation. OpenGL colors are returned as a list of 4 unsigned bytes: r g b a

        Tcl3D command

        Description

        tcl3dName2rgbaf

        Convert a color specification into the corresponding OpenGL representation. OpenGL colors are returned as a list of 4 floats in the range [0..1]: r g b a

        tcl3dRgb2Name

        Convert an OpenGL RGB color representation into a hexadecimal Tcl color name string. OpenGL colors are specified as unsigned bytes in the range [0..255].

        tcl3dRgba2Name

        Convert an OpenGL RGBA color representation into a hexadecimal Tcl color name string. OpenGL colors are specified as unsigned bytes in the range [0..255].

        tcl3dRgbf2Name

        Convert an OpenGL RGB color representation into a hexadecimal Tcl color name string. OpenGL colors are specified as floats in the range [0..1].

        tcl3dRgbaf2Name

        Convert an OpenGL RGBA color representation into a hexadecimal Tcl color name string. OpenGL colors are specified as floats in the range [0..1].

        Table 4.8: tcl3dUtil: Color utility commands


        Examples


        image

        See the test program colorNames.tcl for examples, on how to use these procedures.


        [tcl3dName2Hex white] returns "#FFFFFF" [tcl3dName2Hexa white] returns "#FFFFFFFF"


        [tcl3dName2rgb white] returns {255 255 255}

        [tcl3dRgb2Name 255 255 255] returns "#FFFFFF"


        [tcl3dName2rgba white] returns {255 255 255 255}

        [tcl3dRgba2Name 255 255 255 255] returns "#FFFFFFFF"


        [tcl3dName2rgbf white] returns {1.0 1.0 1.0}

        [tcl3dRgbf2Name 1.0 1.0 1.0] returns "#FFFFFF"


        [tcl3dName2rgbaf white] returns {1.0 1.0 1.0 1.0}

        [tcl3dRgbaf2Name 1.0 1.0 1.0 1.0] returns "#FFFFFFFF"


        [tcl3dName2rgb "#0a0c0e"] returns {10 12 14}


        Implementation details


        image

        The functionality of this module is implemented in the following files:


        Implementation files: tcl3dUtilColors.tcl

        Header files: None

        Wrapper files: None

        Implementation files: tcl3dUtilColors.tcl

        Header files: None

        Wrapper files: None


      5. Large data module

        This module provides miscellaneous functions for handling large data like textures and vertex arrays.


        Overview

        The following table lists the available functions of this module. For a detailed description of the functions see the Tcl3D Reference Manual [5] or the source code files as listed in section Implementation details at the end of this chapter.


        Tcl3D command

        Description

        tcl3dVector

        Create a new Tcl3D Vector by calling the low-level memory allocation routine new_TYPE and create a new Tcl procedure. (See example below).

        tcl3dVectorInd

        Get index of a Tcl3D Vector.

        tcl3dVectorPrint

        Print the contents of a Tcl3D Vector onto standard output.

        tcl3dVectorFromArgs

        Create a new Tcl3D Vector from a variable argument list.

        tcl3dVectorFromList

        Create a new Tcl3D Vector from a Tcl list.

        tcl3dVectorFromString

        Create a new Tcl3D Vector from a Tcl string. Very slow.

        tcl3dVectorFromByteArray

        Create a new Tcl3D Vector from a Tcl binary string.

        tcl3dVectorFromPhoto

        Create a new Tcl3D Vector containing the data of a Tk photo image. See next chapter for detailed description.

        tcl3dVectorFromLinspace

        Create a new linearly spaced Tcl3D Vector.

        tcl3dVectorToList

        Copy the contents of a Tcl3D Vector into a Tcl list. Very slow.

        tcl3dVectorToString

        Copy the contents of a Tcl3D Vector into a string. Very slow.

        tcl3dVectorToByteArray

        Copy the contents of a Tcl3D Vector into a Tcl binary string.

        Table 4.9: tcl3dUtil: tcl3dVector utility commands


        N o t e

        • The tcl3dFromString and tcl3dVectorToString commands can be replaced with the corresponding ByteArray commands, which are much faster.

        • For functions converting photos into vectors and vice versa, see the next chapter about image manipulation.


          The tcl3dVector command creates a new Tcl procedure with the following subcommands, which wrap the low-level vector access functions described above:


          Subcommand

          Description

          get

          Get vector element at a given index. (TYPE_getitem)

          set

          Set vector element at a given index to supplied value. (TYPE_setitem)

          setrgb

          Set 3 vector elements starting at given index. (TYPE_setrgb)

          setrgba

          Set 4 vector elements starting at given index. (TYPE_setrgba)

          setvec

          Set range of vector elements to supplied value. (TYPE_setarray)

          addvec

          Add supplied value to a range of vector elements. (TYPE_addarray)

          mulvec

          Muliply supplied value to a range of vector elements. (TYPE_mularray)

          delete

          Delete a tcl3dVector. (delete_TYPE)

          elemsize

          Determine the size of an element in bytes. (TYPE_elemsize)

          Table 4.10: tcl3dUtil: tcl3dVector subcommands


          Examples


          The following example shows the usage of the tcl3dVector command.


          set ind 23

          set vec [tcl3dVector GLfloat 123] ; # Create Vector of 123 GLfloats

          $vec set $ind 1017.0 ; # Set element at index 23 to 1017.0 set x [$vec get $ind] ; # Get element at index 23

          puts [$vec elemsize] ; # Prints out 4

          $vec addvec 33 2 10 ; # Add 33 to ten elements starting at index 2

          $vec delete ; # Free the allocated memory


          N o t e

        • Indices start at zero.


          The following example shows the usage of the tcl3dVectorFromLinspace command.


          # Create a GLdouble vector of length 5 with values from 0 to 0.1


          > set v [tcl3dVectorFromLinspace GLdouble 0 0.1 5]

          > tcl3dVectorPrint $v 5


          0: 0.000

          1: 0.025

          2: 0.050

          3: 0.075

          4: 0.100


          See also the test program vectorlinspace.tcl for more examples.


          See the demo program bytearray.tcl and vecmanip.tcl for examples, on how to use the

          ByteArray procedures for generating textures in Tcl.


          Implementation details


          image

          The functionality of this module is implemented in the following files:


          Implementation files: tcl3dVector.tcl

          Header files: None

          Wrapper files: vector.i, bytearray.i

          Implementation files: tcl3dVector.tcl

          Header files: None

          Wrapper files: vector.i, bytearray.i


          As stated in chapter 3.1.2, some of the OpenGL functions need a pointer to a contiguous block of allocated memory. SWIG already provides a feature to automatically generate wrapper functions for allocating and freeing memory of any type. This SWIG feature

          %array_functions has been extended and replaced with 2 new SWIG commands:

          %baseTypeVector for scalar types and %complexTypeVector for complex types like structs. It not only creates setter and getter functions for accessing single elements of the allocated memory, but also adds functions to set ranges of the allocated memory.


          Wrapper functions for the following scalar types are defined in file tcl3dVectors.i:


          Array of

          is mapped to

          short

          short

          int

          int

          ushort

          unsigned short

          uint

          unsigned int

          float

          float

          double

          double

          GLenum

          unsigned int

          GLboolean

          unsigned char

          GLbitfield

          unsigned int

          GLbyte

          signed char

          GLshort

          short

          GLint

          int

          Array of

          is mapped to

          GLsizei

          int

          GLubyte

          unsigned char

          GLushort

          unsigned short

          GLuint

          unsigned int

          GLfloat

          float

          GLclampf

          float

          GLdouble

          double

          GLclampd

          double


          N o t e

        • tcl3dVectors of type char, unsigned char, GLchar and GLcharARB are not supported, because the corresponding typemaps would collide with the standard SWIG mapping for C strings. Use types GLbyte and GLubyte, if you need tcl3dVectors with element sizes of 1 byte.


          image

          image

          image

          The generated wrapper code looks like this (Example shown for GLdouble):


          static double *new_GLdouble(int nelements) {

          return (double *) calloc(nelements,sizeof(double));

          }


          static void delete_GLdouble(double *ary) { free(ary);

          }


          static int GLdouble_elemsize(double *ary) { return sizeof (ary[0]);

          }


          static double GLdouble_getitem(double *ary, int index) { return ary[index];

          }


          static void GLdouble_setitem(double *ary, int index, double value) { ary[index] = value;

          }


          static void GLdouble_setrgb(double *ary, int index,

          double r, double g, double b) { ary[index] = r;

          ary[++index] = g; ary[++index] = b;

          }


          static void GLdouble_setrgba(double *ary, int index,

          double r, double g, double b, double a) { ary[index] = r;

          ary[++index] = g; ary[++index] = b; ary[++index] = a;

          }


          static void GLdouble_setvector(double *ary, double value,

          int startIndex, int len) {

          int i;

          int endIndex = startIndex + len;

          for (i=startIndex; i<endIndex; i++) { ary[i] = value;

          }

          }


          static void GLdouble_addvector(double *ary, double value,

          int startIndex, int len) {

          int i;

          int endIndex = startIndex + len;

          for (i=startIndex; i<endIndex; i++) { ary[i] += (double) value;

          }

          }


          static void GLdouble_mulvector(double *ary, double value,

          int startIndex, int len) {

          int i;

          int endIndex = startIndex + len;

          for (i=startIndex; i<endIndex; i++) { ary[i] *= (double) value;

          }

          }


          static double *GLdouble_ind(double *ary, int incr) { return (ary + incr);

          }


          static double *GLdouble_cast(void *ary) { return (double *)ary;

          }


          image

          These low level functions are typically not used directly. They are accessible via the Tcl command tcl3dVector, with the exception of the TYPE_ind functions.

          An example for the usage of GLfloat_ind for optimised access to vectors can be found in NeHe demo Lesson37.tcl.


          File bytearray.i provides the implementation and wrapper definitions to convert Tcl binary strings (ByteArrays) into Tcl3D Vectors (tcl3dByteArray2Vector) and vice versa (tcl3dVector2ByteArray).


          Comparison of the different vector methods


          There are 4 different methods of setting vectors.


          Method 1: $vec set $index $val

          Set the elements with the tcl3dVector object method "set". Most elegant way, but also the slowest. Only useful for small vectors.


          Method 2: ${type}_setitem $vec $index $val

          Set the elements with the tcl3dVector low-level function "setitem". Not so elegant, because you need to know the type of the vector, but much faster than method 1.


          Method 3: tcl3dListToVector_$type $list $vec $len

          Set the elements with the low level functions "tcl3dListToVector_TYPE" introduced in Tcl3D

          0.3.3. Not so elegant, because you need to know the type of the tcl3dVector and you have to build a Tcl list before setting the tcl3dVector. This is the fastest way.


          Method 4: set vec [tcl3dVectorFromList $type $list]

          Set the elements with the utility function "tcl3dVectorFromList", which internally calls the low level functions "tcl3dListToVector_TYPE". You don't have to care about allocating a tcl3dVector of approriate size. This is only slightly slower than method3.


          The test program vectorspeed.tcl implements the above mentioned four different methods and shows output similar to the following lines:


          D:\tcl3d\tcl3dOgl\tests> tclsh vectorspeed.tcl Number of runs : 100

          Size of vectors: 1000

          Setting 100000 elements per method. SetMethod1: 25339.3 microseconds per iteration SetMethod2: 3637.8 microseconds per iteration SetMethod3: 659.2 microseconds per iteration SetMethod4: 736.2 microseconds per iteration


      6. Image utility module

        This module provides access to Tk photo images.


        Overview


        The following table lists the available functions of this module. For a detailed description of the functions see the Tcl3D Reference Manual [5] or the source code files as listed in section Implementation details at the end of this chapter.


        Tcl3D command

        Description

        tcl3dPhotoChans

        Return the number of channels of a Tk photo.

        tcl3dVectorToPhoto

        Copy from OpenGL raw image format into a Tk photo. The photo image must have been initialized with the appropriate size and type.

        tcl3dPhotoToVector

        Copy a Tk photo into a tcl3dVector in OpenGL raw image format. The tcl3dVector must have been allocated with the approriate size and type.

        tcl3dVectorFromPhoto

        Create a new Tcl3D Vector containing the image data of a Tk photo image. Only GL_UNSIGNED_BYTE currently supported.

        Table 4.11: tcl3dUtil: Image utility commands

        N o t e

        • The Img extension is recommended to have access to lots of image formats.


          Examples


          image

          Example 1: Read an image into a Tk photo and use it as a texture map.


          set texture [tcl3dVector GLuint 1] ; # Memory for 1 texture identifier


          proc LoadImage { imgName } {

          set retVal [catch {set phImg [image create photo -file $imgName]} err1] if { $retVal != 0 } {

          error "Error reading image $imgName ($err1)"

          } else {

          set numChans [tcl3dPhotoChans $phImg]

          if { $numChans != 3 && $numChans != 4 } {

          error "Error: Only 3 or 4 channels allowed ($numChans supplied)"

          }

          set w [image width $phImg] set h [image height $phImg]

          set texImg [tcl3dVectorFromPhoto $phImg $numChans] image delete $phImg

          }

          return [list $texImg $w $h]

          }


          proc CreateTexture {} {

          # Load an image into a tcl3dVector. set imgInfo [LoadImage "Wall.bmp"] set imgData [lindex $imgInfo 0] set imgWidth [lindex $imgInfo 1]

          set imgHeight [lindex $imgInfo 2]


          # Create the texture identifiers. glGenTextures 1 $::texture


          glBindTexture GL_TEXTURE_2D [$::texture get 0]

          glTexParameteri GL_TEXTURE_2D GL_TEXTURE_MIN_FILTER $::GL_LINEAR glTexParameteri GL_TEXTURE_2D GL_TEXTURE_MAG_FILTER $::GL_LINEAR glTexImage2D GL_TEXTURE_2D 0 3 $imgWidth $imgHeight \

          0 GL_RGBA GL_UNSIGNED_BYTE $imgData


          # Delete the image data vector.

          $imgData delete

          }


          image

          image

          Example 2: Read an image from the OpenGL framebuffer and save it with the Img library.


          proc SaveImg { imgName } { set w $::toglWidth

          set h $::toglHeight set numChans 4

          set vec [tcl3dVector GLubyte [expr $w * $h * $numChans]] glReadPixels 0 0 $w $h GL_RGBA GL_UNSIGNED_BYTE $vec

          set ph [image create photo -width $w -height $h]

          tcl3dVectorToPhoto $vec $ph $w $h $numChans

          set fmt [string range [file extension $imgName] 1 end]

          $ph write $imgName -format $fmt image delete $phImg

          $vec delete

          }


          proc ReshapeCallback { toglwin } { set ::toglWidth [$toglwin width]

          set ::toglHeight [$toglwin height]

          ...

          }


          image

          The actual size of the Togl window (::toglWidth, ::toglHeight), which is needed in command SaveImg, can be saved in a global variable when the reshape callback is executed.


          See the NeHe demo program Lesson41.tcl or any demo using textures for examples, on how to use the photo image utilities.


          Implementation details


          image

          The functionality of this module is implemented in the following files:


          Implementation files: tcl3dVector.tcl

          Header files: None

          Wrapper files: tkphoto.i

          Implementation files: tcl3dVector.tcl

          Header files: None

          Wrapper files: tkphoto.i


      7. Screen capture module

        This module implements functions for capturing window contents into either a photo image, an image file or the clipboard.


        Overview

        The following table lists the available functions of this module. For a detailed description of the functions see the Tcl3D Reference Manual [5] or the source code files as listed in section Implementation details at the end of this chapter.


        Tcl3D command

        Description

        tcl3dWidget2Img

        Copy contents of a widget and all of its sub-widgets into a photo image.

        tcl3dWidget2File

        Copy contents of a widget and all of its sub-widgets into a photo image and save the image to a file.

        tcl3dCanvas2Img

        Copy the contents of a Tk canvas into a photo image.

        tcl3dCanvas2File

        Copy the contents of a Tk canvas into a photo image and save the image to a file.

        tcl3dClipboard2Img

        Copy the contents of the Windows clipboard into a photo image.

        tcl3dClipboard2File

        Copy the contents of the Windows clipboard into a photo image and save the image to a file.

        tcl3dImg2Clipboard

        Copy a photo into the Windows clipboard.

        tcl3dWindow2Clipboard

        Copy the contents of the top level window (Alt-PrtSc) into the Windows clipboard.

        tcl3dDesktop2Clipboard

        Copy the contents of the whole desktop (PrtSc) into the Windows clipboard.

        tcl3dWindow2Img

        Copy the contents of the top level window (Alt-PrtSc) into a photo image.

        tcl3dWindow2File

        Copy the contents of the top level window (Alt-PrtSc) into a photo image and save the image to a file.

        Table 4.12: tcl3dUtil: Capture commands

        N o t e

        • All of the functionality requires the help of the Img extension.

        • Some of the functionality requires the help of the Twapi extension and is therefore available only on Windows.


          Examples


          See the demo program presentation.tcl for an example, on how to use these procedures to save screenshots of the available Tcl3D demos by right-clicking on the demo name.


          Implementation details


          image

          The functionality of this module is implemented in the following files:


          Implementation files: tcl3dUtilCapture.tcl

          Header files: None

          Wrapper files: None

          Implementation files: tcl3dUtilCapture.tcl

          Header files: None

          Wrapper files: None


      8. Timing module

        This module provides functions for timing purposes.


        Overview


        The following table lists the available functions of this module. For a detailed description of the functions see the Tcl3D Reference Manual [5] or the source code files as listed in section Implementation details at the end of this chapter.

        Tcl3D command

        Description

        tcl3dNewSwatch

        Create a new stop watch and return it’s identifier.

        tcl3dDeleteSwatch

        Delete an existing stop watch.

        tcl3dStopSwatch

        Stop a running stop watch.

        tcl3dStartSwatch

        Start a stop watch.

        tcl3dResetSwatch

        Reset a stop watch, i.e. set the time to zero seconds.

        tcl3dLookupSwatch

        Lookup a stop watch and return the elapsed seconds.

        Table 4.13: tcl3dUtil: Stop watch commands


        Examples


        See the demo program spheres.tcl for an example, on how to use these procedures to measure the rendering frame rate.


        Implementation details


        image

        The functionality of this module is implemented in the following files:


        Implementation files: tcl3dUtilStopWatch.c

        Header files: tcl3dUtilStopWatch.h

        Wrapper files: util.i

        Implementation files: tcl3dUtilStopWatch.c

        Header files: tcl3dUtilStopWatch.h

        Wrapper files: util.i


      9. Random number module

        This module provides functions to generate random numbers.


        Overview


        The following table lists the available functions of this module. For a detailed description of the functions see the Tcl3D Reference Manual [5] or the source code files as listed in section Implementation details at the end of this chapter.


        Tcl3D command

        Description

        tcl3dNewRandomGen

        Initialize a new random number generator.

        tcl3dDeleteRandomGen

        Delete a random number generator.

        tcl3dGetRandomInt

        Generate a pseudo-random integer number.

        tcl3dGetRandomFloat

        Generate a pseudo-random floating point number.

        Table 4.14: tcl3dUtil: Random number commands


        Examples


        See the demo program mandelbrot.tcl for an example, on how to use these procedures to set up random colors for fractal generation.


        Implementation details


        image

        The functionality of this module is implemented in the following files:


        Implementation files: tcl3dUtilRandom.c

        Header files: tcl3dUtilRandom.h

        Wrapper files: util.i

        Implementation files: tcl3dUtilRandom.c

        Header files: tcl3dUtilRandom.h

        Wrapper files: util.i

      10. 3D-Model and shapes module

        This module provides functions for reading 3D models in Wavefront format and creating basic shapes.


        Overview


        The following tables list the available functions of this module. For a detailed description of the functions see the Tcl3D Reference Manual [5] or the source code files as listed in section Implementation details at the end of this chapter.


        Tcl3D command

        Description

        glmUnitize

        "Unitize" a model by translating it to the origin and scaling it to fit in a unit cube around the origin.

        glmDimensions

        Calculates the dimensions (width, height, depth) of a model.

        glmScale

        Scales a model by a given amount.

        glmReverseWinding

        Reverse the polygon winding for all polygons in this model.

        glmFacetNormals

        Generates facet normals for a model.

        glmVertexNormals

        Generates smooth vertex normals for a model.

        glmLinearTexture

        Generates texture coordinates according to a linear projection of the texture map.

        glmSpheremapTexture

        Generates texture coordinates according to a spherical projection of the texture map.

        glmDelete

        Deletes a GLMmodel structure.

        glmReadOBJ

        Reads a model description from a Wavefront .OBJ file.

        glmWriteOBJ

        Writes a model description in Wavefront .OBJ format to a file.

        glmDraw

        Renders the model to the current OpenGL context using the mode specified.

        glmList

        Generates and returns a display list for the model using the mode specified.

        glmWeld

        Eliminate (weld) vectors that are within an epsilon of each other.

        Table 4.15: tcl3dUtil: Wavefront reader commands



        Tcl3D command

        Description

        tcl3dCube

        Draw a textured cube with given center and size.

        tcl3dHelix

        Draw a helix with given center, radius and number of twists.

        tcl3dSphere

        Draw a sphere with given radius precision.

        tcl3dCameraModel

        Draw a model of a simple camera.

        tcl3dTeapotModel

        Draw a teapot with quads.

        Table 4.16: tcl3dUtil: Shape commands


        Examples


        See the demo program gaugedemo.tcl for an example, on how to use the Wavefront parser functions.

        See NeHe demo program Lesson23.tcl for an example, on how to use tcl3dCube. See NeHe demo program Lesson36.tcl for an example, on how to use tcl3dHelix.

        See demo program ogl_benchmark_sphere.tcl for an example, on how to use tcl3dSphere.


        Implementation details

        The tcl3dModel.* and tcl3dModelFmtObj.* files provide a parser for reading model files in Alias/Wavefront format. The code to read and draw the models is a modified version of the parser from Nate Robin's OpenGL tutorial [19].

        image

        The tcl3dShapes.* files implement a sphere based on an algorithm found at Paul Bourke’s excellent pages [22] as well as a cube and a helix based on algorithms found in the NeHe tutorials 23 and 36 [16].


        Implementation files: tcl3dModel.c, tcl3dModelFmtObj.c, tcl3dShapesMisc.c Header files: tcl3dModel.h, tcl3dModelFmtObj.h, tcl3dShapesMisc.h Wrapper files: util.i

        Implementation files: tcl3dModel.c, tcl3dModelFmtObj.c, tcl3dShapesMisc.c Header files: tcl3dModel.h, tcl3dModelFmtObj.h, tcl3dShapesMisc.h Wrapper files: util.i


        N o t e

      11. Virtual trackball and arcball module

        This module provides functions for emulating a trackball and an arcball.


        Overview


        The following tables list the available functions of this module. For a detailed description of the functions see the Tcl3D Reference Manual [5] or the source code files as listed in section Implementation details at the end of this chapter.


        The trackball module implements the following commands:


        Tcl3D command

        Description

        tcl3dTbInit

        Call this procedure.

        initialization

        procedure

        before

        any

        other

        trackball

        tcl3dTbReshape

        Call this procedure from the reshape callback.

        tcl3dTbMatrix

        Get the trackball matrix rotation.

        tcl3dTbStartMotion

        Begin trackball movement.

        tcl3dTbStopMotion

        Stop trackball movement.

        tcl3dTbMotion

        Call this procedure from the motion callback.

        tcl3dTbAnimate

        Call with parameter 1 (or $::GL_TRUE), if you want the trackball to continue spinning after the mouse button has been released. Call with parameter 0 (or $::GL_FALSE), if you want the trackball to stop spinning after the mouse button has been released.

        Table 4.17: tcl3dUtil: Trackball commands


        The ArcBall module implements the following commands:


        Tcl3D command

        Description

        tcl3dNewArcBall

        Create new ArcBall with given width and height.

        tcl3dDeleteArcBall

        Delete an ArcBall.

        tcl3dSetArcBallBounds

        Update mouse bounds for ArcBall. Call this procedure from the reshape callback.

        tcl3dArcBallClick

        Update start vector and prepare for dragging.

        tcl3dArcBallDrag

        Update end vector and get rotation as Quaternion.

        Table 4.18: tcl3dUtil: ArcBall commands

        Examples


        See the demo program ftglDemo.tcl for an example, on how to use the trackball procedures. See the NeHe demo program Lesson48.tcl for an example, on how to use the ArcBall procedures.


        Implementation details


        image

        The functionality of the trackball module is implemented in the following files:


        Implementation files: tcl3dUtilTrackball.c, tcl3dUtilTrackball.tcl

        Header files: tcl3dUtilTrackball.h

        Wrapper files: util.i

        Implementation files: tcl3dUtilTrackball.c, tcl3dUtilTrackball.tcl

        Header files: tcl3dUtilTrackball.h

        Wrapper files: util.i


        image

        The functionality of the ArcBall module is implemented in the following files:


        Implementation files: tcl3dUtilArcBall.c

        Header files: tcl3dUtilArcBall.h

        Wrapper files: util.i

        Implementation files: tcl3dUtilArcBall.c

        Header files: tcl3dUtilArcBall.h

        Wrapper files: util.i


      12. C based utilities for demo applications

        This sub-module implements C based utility functions for some of the demo applications.


        Overview


        tcl3dDemoOglLogo implements an animated 3-dimensional OpenGL logo.

        It is used in demo animlogo.tcl in directory LibrarySpecificDemos/tcl3dOgl.


        tcl3dDemoReadRedBookImg implements a parser for the simple image file format used in some of the RedBook demos.

        It is used in demos colormatrix.tcl, colortable.tcl, convolution.tcl, histogram.tcl and

        minmax.tcl in directory TutorialsAndBooks/RedBook.


        tcl3dHeightmap implements a converter from a Tk photo image into a heightmap. It is used in NeHe demo Lesson45.tcl in directory TutorialsAndBooks/NeHe.


        Implementation details


        image

        The functionality of the OpenGL logo animation is implemented in the following files:


        Implementation files: tcl3dDemoOglLogo.c

        Header files: tcl3dDemoOglLogo.h

        Wrapper files: util.i

        Implementation files: tcl3dDemoOglLogo.c

        Header files: tcl3dDemoOglLogo.h

        Wrapper files: util.i


        image

        The functionality of the RedBook image parser module is implemented in the following files:


        Implementation files: tcl3dDemoReadRedBookImg.c Header files: tcl3dDemoReadRedBookImg.h Wrapper files: util.i

        Implementation files: tcl3dDemoReadRedBookImg.c Header files: tcl3dDemoReadRedBookImg.h Wrapper files: util.i


        The functionality of the heightmap module is implemented in the following files:

        image

        Implementation files: heightmap.i, tcl3dDemoHeightMap.tcl

        Header files: None

        Wrapper files: heightmap.i


        4.4 tcl3dCg: Wrapper for NVidia’s Cg shading language

        4.4 tcl3dCg: Wrapper for NVidia’s Cg shading language


        This module wraps NVidia’s Cg [7] library based on version 2.2.0017 and adds some Cg related utility procedures.


        This is an optional module.

        Requirements for this module: The Cg library and header files.

        Runtime libraries are included in the Tcl3D distribution.


        image

        The master SWIG file for wrapping the Cg library is tcl3dCg.i.


        Implementation files: tcl3dCgQuery.tcl, tcl3dCgUtil.tcl

        Header files: All files in subdirectory Cg

        Wrapper files: cg.i

        Implementation files: tcl3dCgQuery.tcl, tcl3dCgUtil.tcl

        Header files: All files in subdirectory Cg

        Wrapper files: cg.i


        The wrapping for this module is based on the unmodified Cg header files.


        Cg utility module


        Tcl3D command

        Description

        tcl3dCgGetVersion

        Get the version of the wrapped Cg library.

        tcl3dCgResetError

        Reset the Cg error condition.

        tcl3dCgGetError

        Check, if a Cg related error has occured.

        tcl3dCgGetProfileList

        Get a list of Cg profile names.

        tcl3dCgFindProfile

        Find a supported Cg profile by name.

        tcl3dCgFindProfileByNum

        Find a supported Cg profile by it's numerical value.

        tcl3dCgPrintProgramInfo

        Print the Cg program information onto standard output.

        Table 4.19: tcl3dCg utility commands


        See the demo programs contained in directory LibrarySpecificDemos/tcl3dCg for examples, on how to use the Cg functions.


        4.5 tcl3dSDL: Wrapper for the Simple DirectMedia Library

        4.5 tcl3dSDL: Wrapper for the Simple DirectMedia Library


        This module wraps the SDL [8] library based on version 1.2.9 and adds some SDL related utility procedures.


        N o t e

        • Currently only the functions related to joystick and CD-ROM handling have been wrapped and tested.


          This is an optional module.

          Requirements for this module: The SDL library and header files.

          Libraries and header files are included in the Tcl3D distribution.


          The master SWIG file for wrapping the Simple DirectMedia library is tcl3dSDL.i.

          Implementation files: tcl3dSDLQuery.tcl, tcl3dSDLUtil.tcl Header files: All files in subdirectory include Wrapper files: sdl.i

          Implementation files: tcl3dSDLQuery.tcl, tcl3dSDLUtil.tcl Header files: All files in subdirectory include Wrapper files: sdl.i


          image

          The wrapping for this module is based on the unmodified SDL header files.


          SDL utility module


          Tcl3D command

          Description

          tcl3dSDLGetVersion

          Get the version of the wrapped SDL library.

          tcl3dSDLGetFocusName

          Convert a SDL focus state bitfield into a string representation.

          tcl3dSDLGetButtonName

          Convert a SDL button state bitfield into a string representation.

          tcl3dSDLGetHatName

          Convert SDL hat related enumerations into a string representation.

          tcl3dSDLGetEventName

          Convert SDL event related enumerations into a string representation.

          tcl3dSDLFrames2MSF

          Convert CD frames into minutes/seconds/frames.

          tcl3dSDLGetTrackTypeName

          Convert SDL CD track type enumerations into a string representation.

          tcl3dSDLGetCdStatusName

          Convert SDL CD status enumerations into a string representation.

          Table 4.20: tcl3dSDL utility commands


          See the demo programs contained in directory LibrarySpecificDemos/tcl3dSDL for examples, on how to use the SDL functions.


          4.6 tcl3dFTGL: Wrapper for the OpenGL Font Rendering Library

          4.6 tcl3dFTGL: Wrapper for the OpenGL Font Rendering Library


          This module wraps the FTGL [9] library based on version 2.1.3 RC5 and adds some FTGL related utility procedures.

          The FTGL library depends on the Freetype2 library [10].


          This is an optional module.

          Requirements for this module: The FTGL and Freetype2 library and header files.

          Libraries and header files are included in the Tcl3D distribution.


          image

          The master SWIG file for wrapping the OpenGL Font Rendering library is tcl3dFTGL.i.


          Implementation files: tcl3dFTGLQuery.tcl, tcl3dFTGLUtil.tcl Header files: All files in subdirectory include Wrapper files: ftgl.i

          Implementation files: tcl3dFTGLQuery.tcl, tcl3dFTGLUtil.tcl Header files: All files in subdirectory include Wrapper files: ftgl.i


          The wrapping for this module is based on the unmodified FTGL header files.


          FTGL utility module


          Tcl3D command

          Description

          tcl3dFTGLGetVersion

          Get the version of the wrapped FTGL library.

          tcl3dFTGLGetBBox

          Get bounding box of a string.

          Table 4.21: tcl3dFTGL utility commands

          See the demo programs contained in directory LibrarySpecificDemos/tcl3dFTGL for examples, on how to use the FTGL functions.


          4.7 tcl3dGl2ps: Wrapper for the OpenGL To Postscript Library

          4.7 tcl3dGl2ps: Wrapper for the OpenGL To Postscript Library


          This module wraps Christophe Geuzaine’s GL2PS [11] library based on version 1.3.5 and adds some GL2PS related utility procedures.


          N o t e

        • Gl2PS currently does not support textures.


          This is an optional module.

          image

          Requirements for this module: None, all files are contained in the Tcl3D distribution. The master SWIG file for wrapping the Gl2ps library is tcl3dGl2ps.i.

          Implementation files: gl2ps.c, tcl3dGl2psQuery.tcl, tcl3dGl2psUtil.tcl

          Header files: gl2ps.h

          Wrapper files: gl2ps.i

          Implementation files: gl2ps.c, tcl3dGl2psQuery.tcl, tcl3dGl2psUtil.tcl

          Header files: gl2ps.h

          Wrapper files: gl2ps.i


          The wrapping for this module is based on the unmodified GL2PS implementation and header files.


          Gl2ps utility module


          Tcl3D command

          Description

          tcl3dGl2psGetVersion

          Get the version of the wrapped GL2PS library.

          tcl3dGl2psCreatePdf

          Create a PDF file from current Togl window content.

          Table 4.22: tcl3dGl2ps utility commands


          See NeHe demo Lesson02.tcl or the benchmarking demo sphere.tcl in directory LibrarySpecificDemos/tcl3dOgl for an example, on how to use the GL2PS functions for PDF export.


          4.8 tcl3dOde: Wrapper for the Open Dynamics Engine

          4.8 tcl3dOde: Wrapper for the Open Dynamics Engine


          This module wraps the ODE [12] library based on version 0.7 and adds some ODE related utility procedures.


          N o t e

        • This module is still work in progress. It’s interface may change in the future.


          This is an optional module.

          Requirements for this module: The ODE library and header files.

          Libraries and header files are included in the Tcl3D distribution.


          image

          The master SWIG file for wrapping the Open Dynamics Engine library is tcl3dOde.i.


          Implementation files: tcl3dOdeQuery.tcl, tcl3dOdeUtil.tcl

          Header files: All files in subdirectory ode

          Wrapper files: ode.i

          Implementation files: tcl3dOdeQuery.tcl, tcl3dOdeUtil.tcl

          Header files: All files in subdirectory ode

          Wrapper files: ode.i


          The wrapping for this module is based on the unmodified ODE header files.

          ODE utility module


          Tcl3D command

          Description

          tcl3dOdeGetVersion

          Get the version of the wrapped ODE library.

          Table 4.23: tcl3dOde utility commands


          See the demo programs contained in directory LibrarySpecificDemos/tcl3Ode for examples, on how to use the ODE functions.


          4.9 tcl3dOsg: Wrapper for the OpenSceneGraph library

          4.9 tcl3dOsg: Wrapper for the OpenSceneGraph library


          This module wraps the OpenSceneGraph [13] library based on version 2.8.2 and adds some OSG related utility procedures.


          N o t e

        • This is the first release of the OpenSceneGraph wrapper. It is far from being finished or error free and work in progress. It’s interface may change in the future.

        • Check out the Tcl3D homepage for more up-to-date information.


          This is an optional module.

          Requirements for this module: The OSG library and header files.

          image

          Libraries and header files are included in the Tcl3D distribution.


          Implementation files: tcl3dOsg*.tcl

          Header files: All files in subdirectory include

          Wrapper files: osg*.i, tcl3dOsg*.i

          Implementation files: tcl3dOsg*.tcl

          Header files: All files in subdirectory include

          Wrapper files: osg*.i, tcl3dOsg*.i


          The wrapping for this module is based on the unmodified OSG header files.


          OSG utility module


          Tcl3D command

          Description

          tcl3dOsgGetVersion

          Get the version of the wrapped OSG library.

          tcl3dOsgKeysym

          Convert a keysym into decimal and vice versa.

          tcl3dOsgGetBitmap

          Get the bitmap image of a node type.

          tcl3dOsgVecPrint

          Print the contents of an osg::Vec* class.

          tcl3dOsgMatPrint

          Print the contents of an osg::Matrix* class.

          tcl3dOsgBBoxPrint

          Print the contents of an osg::BoundingBox* class.

          tcl3dOsgBSpherePrint

          Print the contents of an osg::BoundingSphere* class.

          tcl3dOsgVecArrayPrint

          Print an array of vectors.

          tcl3dOsgScalarArrayPrint

          Print an array of scalars.

          tcl3dOsgObjectArrayPrint

          Print an array of objects.

          tcl3dOsgGetVisitorTypeName

          Get visitor type name.

          tcl3dOsgGetTraversalModeName

          Get traversal mode name.

          tcl3dOsgSendButtonPress tcl3dOsgSendButtonRelease tcl3dOsgSendMouseMotion tcl3dOsgSendKeyPress tcl3dOsgSendKeyRelease tcl3dOsgSendWindowResize

          Procedures to transfer the corresponding Tk event to the OSG event queue (osgGA::EventQueue).

          tcl3dOsgAddTrackballBindings

          Add OS independent mouse bindings for trackball usage.

          Table 4.24: tcl3dOsg utility commands


          See the demo programs contained in directory demos/OpenSceneGraph for examples, on how to use the OSG functions.


          4.10 tcl3dGauges: Tcl3D package for displaying gauges

          4.10 tcl3dGauges: Tcl3D package for displaying gauges


          This package implements the following gauges: airspeed, altimeter, compass, tiltmeter.


          This is an optional module.

          Requirements for this module: None, all files are contained in the Tcl3D distribution. The gauge package has been implemented by Victor G. Bonilla.

          See the demo programs gaugedemo.tcl and gaugetest.tcl for examples, on how to use the gauges.

          5 Miscellaneous Tcl3D information

          5 Miscellaneous Tcl3D information


          This chapter contains miscellaneous information about Tcl3D:

        • License information

        • Programming hints

        • Open issues

        • Known bugs

        • Starpack internals

        • OpenGL deprecation mode


          5.1 License information

          5.1 License information


          The SWIG wrapper files as well as the C and Tcl utility files of all modules are copyrighted by Paul Obermeier and distributed under the BSD license. See below for exceptions regarding single files and the external libraries.


          The Tcl3D utility library files (see below for exceptions) are copyrighted by Paul Obermeier and distributed under the BSD license.

          The following files of the Tcl3D utility library have differing copyrights:

        • The original Wavefront parser code is copyrighted by Nate Robins.

        • The original GLUT shape code is copyrighted by Mark Kilgard.

        • The original code of tcl3dSphere is copyrighted by Paul Bourke.

        • The original code of tcl3dHelix is copyrighted by Dario Corno.

        • The original code of tcl3dArcBall is copyrighted by Tatewake.com.

        • The original code of tcl3dTrackball is copyrighted by Gavin Bell et al.


          The Tcl3D gauge library is copyrighted by Victor G. Bonilla and distributed under the BSD license.


          The original Togl widget is copyrighted by Brian Paul and Benjamin Bederson and distributed under the BSD license (see http://sourceforge.net/projects/togl). The modified Tcl3D version of Togl is copyrighted by Paul Obermeier and distributed under the BSD license.


          See the following table of wrapped, unmodified libraries for their license conditions.


          Library

          License

          More information

          GLEW

          Modified BSD license

          http://glew.sourceforge.net/glew.txt

          Cg

          Redistributable license

          http://developer.nvidia.com/object/cg_toolkit.html (see file license.pdf in Cg installation)

          FTGL

          LGPL

          http://sourceforge.net/projects/ftgl/

          Freetype

          Freetype License (BSD style)

          http://www.freetype.org/FTL.TXT

          GL2PS

          LGPL

          See file COPYING.GL2PS in directory tcl3dGl2ps

          ODE

          BSD

          http://www.ode.org/ode-license.html

          OSG

          OpenSceneGraph Public License (LGPL style)

          http://www.openscenegraph.org/projects/osg/attachment

          /wiki/Legal/LICENSE.txt

          SDL

          LGPL

          http://www.libsdl.org/license-lgpl.php

          Table 5.1: License information of wrapped libraries

          5.2 Programming hints

          5.2 Programming hints


          Hint 1:

          Most OpenGL examples written in C use the immediate mode. As Tcl is a scripted language and each OpenGL call has to go through the wrapper interface, it’s almost always a bad idea (in terms of speed) to translate these examples one-by-one. Using display lists or vertex arrays does not add much complexity to your Tcl3D program, but enhances performance significantly. Try the Spheres.tcl or ogl_benchmark_sphere.tcl demo for an example, how display lists or vertex arrays can speed up your Tcl3D application.

          Also note, that immediate mode and display lists are marked deprecated in OpenGL 3.1.


          Hint 2:

          Do not use global variables GL_VERSION_X_Y (ex. [info exists GL_VERSION_1_3]) to check the OpenGL version supported on your computer. This does not work, because these variables are all defined independently of the underlying OpenGL implementation. Use the utility functions tcl3dHaveVersion and tcl3dHaveExtension instead.


          Hint 3:

          Error: expected integer but got "GL_REPEAT"


          Some OpenGL functions expect an integer or floating point value, which is often given in C code examples with an enumeration, as shown in the next example:


          extern void glTexParameteri ( GLenum target, GLenum pname, GLint param );


          It is called in C typically as follows:

          glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_REPEAT); glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST);


          As the 3rd parameter is not of type GLenum, you have to specify the numerical value in Tcl: glTexParameteri GL_TEXTURE_2D GL_TEXTURE_WRAP_S $::GL_REPEAT glTexParameteri GL_TEXTURE_2D GL_TEXTURE_MAG_FILTER $::GL_NEAREST


          If called with the enumeration name:

          glTexParameteri GL_TEXTURE_2D GL_TEXTURE_WRAP_S GL_REPEAT

          you will get the above error message.


          Hint 4:

          Error: expected floating-point number but got “_08201905_p_float”.


          This error message indicates, that a tcl3dVector has been specified as parameter to a function, which expects a Tcl list. This often happens, when using one of the glMultMatrix commands. Use a sequence like shown below to convert the tcl3dVector into a Tcl list before supplying it to the function:


          set matAsList [tcl3dVectorToList $mat 16] glMultMatrixf $matAsList


          Hint 5:

          Error: Package tcl3dcg: couldn't load library "C:/Tcl/lib/tcl3d/tcl3dCg/tcl3dCg.dll": this library or a dependent library could not be found in library path


          This typically indicates that the dependent library or libraries (ex. cg.dll or cgGL.dll) are not found, i.e. they are not in a directory contained in your Path environment variable.


          Error: Package tcl3dcg: couldn't load library "C:/Tcl/lib/tcl3d/tcl3dCg/tcl3dCg.dll":

          permission denied


          This typically indicates that the dependent library or libraries (ex. cg.dll or cgGL.dll) were found, but you do not have the permissions to execute the library.


          These errors may occur with the following Tcl3D modules:


          Tcl 3D module

          Affected libraries

          tcl3dCg

          cg.dll cgGL.dll

          tcl3dFTGL

          libftgl.dll freetype6.dll

          tcl3dOde

          ode.dll

          tcl3dOsg

          osg.dll, osgDB.dll, ...

          tcl3dSDL

          SDL.dll


          Although the examples shown in this hint use Windows specific library names, the above mentioned errors may occur on Unix systems as well.


          Hint 6:

          The OpenGL extension library OglExt used in Tcl3D versions before 0.4 for wrapping OpenGL functions and the currently used GLEW library have an important difference:

          OpenGL functions not available in the installed OpenGL driver have been ignored by the OglExt library, i.e. transformed into a no-op. The disadvantage of this behaviour was, that you did not get any feedback about not available functions in your OpenGL driver implementation.

          With GLEW you will get a core dump, when trying to use such a function, because the function pointer is NULL. You should therefore always check either the OpenGL version implemented in your driver (tcl3dOglHaveVersion), the availability of the extensions you intend to use (tcl3dOglHaveExtension), or to be absolutely sure, check the availability of each OpenGL function in your initialization code (tcl3dOglHaveFunc).

          Starting with Tcl3D version 0.4.1 the utility procedure tcl3dSetSafeMode can be used to avoid core dumps and to get information about which OpenGL functions are not available in your driver.

          Use the demo tcl3dInfo.tcl to get information about the supported OpenGL functions of your installed OpenGL driver.


          Hint 7:

          The demo applications are using a procedure called Cleanup to remove or unset demo data. This procedure is only needed when running the demo from the presentation framework. Do not put Cleanup into the exit procedure ExitProg, because an after handler might still be running in the presentation framework. Cleanup is not needed if running a demo application as a standalone script.


          5.3 Open issues

          5.3 Open issues


        • GLU callbacks are currently not supported. This implies, that tesselation does not work, because this functionality relies heavily on the usage of C callback functions.

        • There is currently no possibility to specify a color map for OpenGL indexed mode. As color maps depend on the underlying windowing system, this feature must be handled by the Togl widget.


          N o t e :

          The open issues list is considered as obsolete with OpenGL versions greater than 3.2:

        • The tiltmeter widget from the tcl3dGauge package is not working correctly with Tcl versions less than 8.4.7, because of a bug in the namespace implementation.

        • Picking with depth values does not work correctly, as depth is returned as an unsigned int, mapping the internal floating-point depth values [0.0 .. 1.0] to the range [0 .. 232 –1]. As Tcl only supports signed integers, some depth values are incorrectly transferred into the Tcl commands.

        • SWIG versions up to 1.3.24 had an annoying (but not critical) bug in the Tcl library file swigtcl8.swg: Please check, if your version has a line “printf (“Searching %s\n”, key);” in function SWIG_Tcl_GetConstant, and delete this line, if existent. swigtcl8.swg can be found in /usr/lib/swig1.3/tcl or /usr/share/swig/VERSION/tcl on Linux or in the lib/tcl subdirectory of your SWIG Windows installation.

        • SWIG version 1.3.21 (as delivered with SuSE 9.3) does not correctly wrap the ODE library.

        • The PDF files generated with Gl2ps are not displayed correctly with the Preview program on a Mac. Acrobat Reader displays them correctly.

        • tcl3dOglGetVersion and tcl3dOglGetPackageInfo dump core on Mac OSX, if no Togl window has been created. On other systems, the function returns an empty string in that case. See also the note about glGetString in chapter 4.2.


5.5 Starpack internals

5.5 Starpack internals


For an introduction to Tclkits, starkits and starpacks see Jean-Claude Wippler’s homepage at http://www.equi4.com/.


      1. Starpack issue #1

        image

        If shipping external libraries with your starpack, you have to copy them to the file system, before they can be used. A convenient place is the directory containing the starpack.


        # Check if all necessary external libraries exists in the directory

        # containing the starpack. Copy them to the filesystem, if necessary. set tcl3dExecDir [file dirname $::starkit::topdir]

        set tcl3dDllList [glob -nocomplain -dir [file join $starkit::topdir extlibs] \

        *[info sharedlibextension]*]


        foreach starkitName $ tcl3dDllList {

        set osName [file join $ tcl3dExecDir [file tail $starkitName]] if { ! [file exists $osName] } {

        set retVal [catch { file copy -force -- $starkitName $ tcl3dExecDir }] puts "Copying DLL $starkitName to directory $ tcl3dExecDir"

        if { $retVal != 0 } {

        error "Error copying DLL $starkitName to directory $ tcl3dExecDir"

        }

        }

        }


        This aforementioned solution seems to be the best possible solution today, but has the following two disadvantages:


        • Windows user will typically place the starpack onto the desktop. Starting the starpack inflates the desktop with lots of DLL‘s.

        • On Linux/Unix the current directory typically is not included in the LD_LIBRARY_PATH variable.


          That's why the starpacks are distributed in it's own folder, and the Unix distributions come with an additional start shell script: tcl3dsh-OS-VERSION.sh

          #!/bin/sh

          # Startup script for tcl3dsh, the Tcl3D starpack.


          # Unix LD_LIBRARY_PATH=".:$LD_LIBRARY_PATH"

          # IRIX LD_LIBRARYN32_PATH=".:$LD_LIBRARYN32_PATH"

          # Darwin DYLD_LIBRARY_PATH=".:$DYLD_LIBRARY_PATH"


          export LD_LIBRARY_PATH export LD_LIBRARYN32_PATH export DYLD_LIBRARY_PATH


          ./tcl3dsh-OS-0.5.0 $*


          image

      2. Starpack issue #2

        Some of the external libraries need files for initialization, ex. the FTGL library needs the name of a TrueType font file to construct it‘s OpenGL commands. This font file has to be on the real filesystem, so that the FTGL library can find it, and not in the virtual filesystem of the starpack.


        Tcl3D supports a utility procedure tcl3dGetExtFile, which you should use, if intending to use a Tcl3D script - depending on such a library - in a starpack. See chapter 4.3.3 for a description of the starpack related file utilities.


        A typical usage is shown in the following code segment:


        set fontfile [file join [file dirname [info script]] "Vera.ttf"]

        # tcl3dGetExtFile is available only in versions 0.3.1 and up.

        # You may check availability of command first, if running scripts with older

        # Tcl3D versions.

        if { [info proc tcl3dGetExtFile] eq "tcl3dGetExtFile" } {

        # Get the font file in a starpack independent way. set fontfile [tcl3dGetExtFile $fontfile]

        }


        5.6 OpenGL deprecation mode

        5.6 OpenGL deprecation mode

        The next table shows the release history of OpenGL versions with short comments regarding the introduction of new features.


        Version

        Release date

        New features

        OpenGL 1.0

        01/1992

        First release based on SGI‘s IRIS GL.

        OpenGL 1.1

        01/1997

        Textures and texture formats on GPU hardware.

        OpenGL 1.2

        03/1998

        Volume textures, packed pixels, normal rescaling, image processing.

        OpenGL 1.2.1

        10/1998

        Multi-textures.

        OpenGL 1.3

        08/2001

        Cubemap texture, multi-sampling, texture unit combine operations.

        OpenGL 1.4

        07/2002

        Hardware shadowing support, fog coordinates, automatic mipmap generation.

        Version

        Release date

        New features

        OpenGL

        1.5

        07/2003

        Vertex buffer objects, occlusion queries, extended shadowing functions.

        OpenGL

        2.0

        09/2004

        User-programmable shaders. OpenGL Shading Language (GLSL).

        OpenGL

        2.1

        07/2006

        Pixel buffer objects, sRGB textures, non-square matrices. GLSL 1.20.

        OpenGL

        3.0

        07/2008

        Frame buffer objects, hardware instancing, vertex array objects. GLSL 1.30.

        Introduction of a deprecation mechanism.

        OpenGL

        3.1

        03/2009

        Texture Buffer Objects, Uniform Buffer Objects. GLSL 1.40. Removal of legacy functionality.

        OpenGL

        3.2

        08/2009

        Geometry Shader, Sync and Fence objects. GLSL 1.50.

        OpenGL

        3.3

        03/2010

        Backport of OpenGL 4.0 functionality for use on previous GPU HW. GLSL 3.30.

        OpenGL

        4.0

        03/2010

        Shader subroutines, 64-bit floating point support. GLSL 4.00.

        OpenGL

        4.1

        07/2010

        OpenGL ES compatibility, GLSL 4.10.

        Table 5.2: OpenGL release timeline


        Starting with OpenGL 3.1 the functionality of the fixed-function pipeline was declared deprecated. About 65% of all existing OpenGL functions have been declared deprecated, as can be seen in the following table. Note that this table only takes the core functions into account, no OpenGL extension functions.


        OpenGL version

        Number of functions

        Number of deprecated functions

        OpenGL 1.1

        336

        272

        OpenGL 1.2

        4

        1

        OpenGL 1.3

        46

        37

        OpenGL 1.4

        47

        38

        OpenGL 1.5

        19

        0

        OpenGL 2.0

        93

        36

        OpenGL 2.1

        6

        0

        OpenGL 3.0

        55

        20

        OpenGL 3.1

        4

        0

        OpenGL 3.2

        3

        0

        OpenGL 3.3

        0

        0

        OpenGL 4.0

        5

        0

        OpenGL 4.1

        0

        0

        Total

        618

        404

        Table 5.3: Deprecated OpenGL functions


        The deprecated functions can be easily determined with the Tcl3D utility procedure tcl3dOglGetFuncDeprecated. The following example script prints out all deprecated functions:

        foreach f [tcl3dOglGetFuncList] {

        set depr [tcl3dOglGetFuncDeprecated $f] if { $depr ne "0.0" } {

        puts "Deprecated since OpenGL version $depr : $f"

        }

        }


        Output:

        Deprecated since OpenGL version 3.1 : glAccum Deprecated since OpenGL version 3.1 : glAlphaFunc

        Deprecated since OpenGL version 3.1 : glAreTexturesResident Deprecated since OpenGL version 3.1 : glArrayElement Deprecated since OpenGL version 3.1 : glBegin

        ...


        image

        The next table contains an overview of deprecated functions sorted into categories. See the OpenGL 4.0 API Qick Reference Card for further details. It is available from the OpenGL website.


        Category

        Examples

        Vertex Specification

        glBegin, glEnd, glVertex, glNormal, glColor, glTexCoord

        Vertex Arrays

        glVertexPointer, glEnableClientState, glArrayElement

        Display Lists

        glNewList, glCallList, glGenLists, glListBase

        Lighting

        glMaterial, glLight, glLightModel, glShadeModel

        Texturing

        glTexEnv, glGetTexEnv, glBitmap

        Matrix operations

        glLoadMatrix, glMultMatrix, glTranslate, glRotate

        Raster operations

        glDrawPixels, glCopyPixels, glPixelTransfer, glRasterPos

        State

        glPushAttrib, glPushClientAttrib, glPosAttrib

        Fog and Clipping

        glFog, glClipPlane

        Evaluation

        glMap, glMapGrid, glEvalCoord, glEvalMesh

        Selection and Feedback

        glInitNames, glLoadName, glFeedbackBuffer, glPassThrough

        Convolution filters

        glConvolutionFilter2D, glConvolutionParameter

        ColorTables

        glColorTable, glCopyColorTable, glGetColorTable

        Table 5.4: Deprecation categories


        The deprecated functions are still supported by the OpenGL drivers. Typically these operate in the so-called Compatibility Profile, where all functionality of the fixed-function pipeline is still available. You have to expilicitly switch to the OpenGL core profile by using the extension WGL/GLX_ARB_create_context.


        N o t e :

        This extension functionality is available via the Togl command line -coreprofile.


        For the deprecated matrix functions, replacement functions have been integrated into the OpenGL module of Tcl3D.


        All functions have the same signature, with the exception, that the Tcl3D functions have an additional parameter at the end for returning the calculated matrix:


        void gluPerspective (GLdouble fovy, GLdouble aspect, GLdouble zNear, GLdouble zFar)

        void tcl3dPerspective (double fovy, double aspect, double zNear, double zFar, float *res)

        Deprecated function

        Tcl3dOgl function

        Viewing related functions

        glFrustum

        tcl3dFrustum

        glOrtho

        tcl3dOrtho

        gluPerspective

        tcl3dPerspective

        gluLookAt

        tcl3dLookAt

        Modelling related functions

        glRotate[f|d]

        tcl3dRotate[f|d]

        glTranslate[f|d]

        tcl3dTranslate[f|d]

        glScale[f|d]

        tcl3dScale[f|d]

        glLoadIdentity

        tcl3dMatfIdentity, tcl3dMatdIdentity

        glMultMatrix[f|d]

        tcl3dMatfMult[f|d]

        glLoadMatrix[f|d]

        No replacement, use glUniformMatrix* functions. instead

        glMatrixMode

        No replacement.

        glPushMatrix

        No replacement.

        glPopMatrix

        No replacement.

        Table 5.5: Tcl3D replacement functions

        6 Demo applications

        6 Demo applications


        More than 200 Tcl3D applications for testing and demonstration purposes are currently available. Most of these applications were converted from existing demonstration programs written in C/C++ found on the web. A detailed list of all demos is available online on the Tcl3D homepage at http://www.tcl3d.org/demos/ or in the Tcl3D Demo Manual.


        The Tcl3D demo applications are divided into 4 categories:


image

The next figure shows an excerpt from the demo hierarchy.


Tcl3D Demo Hierarchy

Tcl3D Demo Hierarchy

image

Figure 6.1: Tcl3D demo hierarchy

7 Release notes

7 Release notes


This chapter shows the release and feature history of Tcl3D both graphically and in text form. It also contains a list of obsolete functions.


7.1 Release history

7.1 Release history


image

Tcl3D Version 0.1 Tcl3D Version 0.2



Released 2005/05/29 as TclOgl: Basic OpenGL wrapping, Togl widget with Tcl callbacks.


Released 2006/01/07: Major rewrite and support of new libraries: OpenGL 2.0, OpenGL extensions, Cg, SDL, gauges. Domain www.tcl3d.org created.


Tcl-Level Tcl-Level


Tcl3D Demos and Applications Tcl3D Demos and Applications


tcl3dUtil

Tcl-based Utilities


tcl3dUtil

Tcl-based Utilities


tcl3dGauges

Tcl Extension Package



SWIG generated Tcl interfaces


tcl3dTogl

OpenGL Widget

tcl3dTogl

OpenGL Widget

Tcl-Interface


tcl3dUtil

C-based Utilities

tcl3dOgl

Basic OpenGL

tcl3dOglExt

Extended OpenGL

tcl3dCg

Cg Shading

tcl3dSDL

Joystick

tcl3dUtil

C-based Utilities

tcl3dOgl

Basic OpenGL

tcl3dOglExt

Extended OpenGL

tcl3dCg

Cg Shading

tcl3dSDL

Joystick

SWIG generated Tcl interfaces


Tcl-Interface



tcl3dUtil

C-based Utilities


tcl3dOgl

Basic OpenGL


C/C++-Level


tcl3dTogl

OpenGL Widget

tcl3dTogl

OpenGL Widget

C/C++-Level


Tcl3D Version 0.3 Tcl3D Version 0.3.1



Released 2006/02/12: Enhanced font handling in Togl. Library FTGL added. Mac OS X support supplied by Daniel Steffen.


Released 2006/06/16: Support for GL2PS and ODE (alpha) added. Starpack versions.


Tcl-Level Tcl-Level


Tcl3D Demos and Applications Tcl3D Demos and Applications


tcl3dUtil

Tcl-based Utilities


tcl3dGauges

Tcl Extension Package


tcl3dUtil

Tcl-based Utilities


tcl3dGauges

Tcl Extension Package



SWIG generated Tcl interfaces


tcl3dUtil

C-based Utilities

tcl3dOgl

Basic OpenGL

tcl3dOglExt

Extended OpenGL

tcl3dCg

Cg Shading

tcl3dSDL

Joystick and CD

tcl3dFTGL

Font Rendering


C/C++-Level


tcl3dTogl

OpenGL Widget (Better font handling)

tcl3dTogl

OpenGL Widget (Better font handling)

Tcl-Interface


SWIG generated Tcl interfaces


tcl3dUtil

C-based Utilities

tcl3dOgl

Basic OpenGL

tcl3dOglExt

Extended OpenGL

tcl3dCg

Cg Shading

tcl3dSDL

Joystick and CD

tcl3dFTGL

Font Rendering

tcl3dGl2ps

OpenGL to PS/PDF

tcl3dOde

Physics Engine

C/C++-Level


Tcl-Interface


tcl3dTogl

OpenGL Widget

tcl3dTogl

OpenGL Widget


Tcl3D Version 0.3.2 Tcl3D Version 0.3.3



Released 2007/02/25: Demo cleanup and first official Mac OS X support. Windowing system specifics incorporated into Togl widget. New module tcl3dDemoUtil.


Released 2008/09/14: Bug fixes, minor enhancements and several new demos.


Tcl-Level Tcl-Level


Tcl3D Demos and Applications Tcl3D Demos and Applications


tcl3dUtil

Tcl-based Utilities


tcl3dGauges

Tcl Extension Package


tcl3dUtil

Tcl-based Utilities


tcl3dGauges

Tcl Extension Package



SWIG generated Tcl interfaces


tcl3dUtil

C-based Utilities

tcl3dOgl

Basic OpenGL

tcl3dOglExt

Extended OpenGL

tcl3dCg

Cg Shading

tcl3dSDL

Joystick and CD

tcl3dFTGL

Font Rendering

tcl3dGl2ps

OpenGL to PS/PDF

tcl3dOde

Physics Engine

tcl3dDemoUtil

C utilities for demos

C/C++-Level


tcl3dTogl

OpenGL Widget

tcl3dTogl

OpenGL Widget

Tcl-Interface


SWIG generated Tcl interfaces


tcl3dUtil

C-based Utilities

tcl3dOgl

Basic OpenGL

tcl3dOglExt

Extended OpenGL

tcl3dCg

Cg Shading

tcl3dSDL

Joystick and CD

tcl3dFTGL

Font Rendering

tcl3dGl2ps

OpenGL to PS/PDF

tcl3dOde

Physics Engine

tcl3dDemoUtil

C utilities for demos

C/C++-Level


Tcl-Interface


tcl3dTogl

OpenGL Widget

tcl3dTogl

OpenGL Widget


Tcl3D Version 0.4.0

image

Released 2008/12/30: OpenGL wrapping based on GLEW 1.5.1. Support of OpenGL 3.0. Reorganization of Tcl3D core module.


Tcl-Level


Tcl3D Demos and Applications


tcl3dOgl tcl3dGauges

Tcl-based Utilities Tcl Extension Package


SWIG generated Tcl interfaces Tcl-Interface


tcl3dOgl tcl3dOgl tcl3dOgl

C-based Utilities OpenGL 3.0 and extensions Togl Widget


C/C++-Level


Tcl3D Version 0.4.1

image

Released 2009/08/23: New module tcl3dOsg wrapping the OpenSceneGraph library.


Tcl-Level


Tcl3D Demos and Applications


tcl3dOgl tcl3dGauges

Tcl-based Utilities Tcl Extension Package


SWIG generated Tcl interfaces Tcl-Interface


tcl3dOgl tcl3dOgl tcl3dOgl

C-based Utilities OpenGL 3.0 and extensions Togl Widget


C/C++-Level


Tcl3D Version 0.4.2

image

Released 2010/03/28: OpenGL wrapping based on GLEW 1.5.3. Support of OpenGL 3.2. Updated Cg and Gl2ps modules. Advanced OpenGL information functions.


Tcl-Level


Tcl3D Demos and Applications


tcl3dOgl tcl3dGauges

Tcl-based Utilities Tcl Extension Package


SWIG generated Tcl interfaces Tcl-Interface


tcl3dOgl tcl3dOgl tcl3dOgl

C-based Utilities OpenGL 3.2 and extensions Togl Widget


C/C++-Level


Tcl3D Version 0.4.3

image

Released 2010/07/31: OpenGL wrapping based on GLEW 1.5.4. Support of OpenGL 3.3 and 4.0. Utility functions for fixed function pipeline replacement. Updated FTGL module.


Tcl-Level


Tcl3D Demos and Applications


tcl3dOgl tcl3dGauges

Tcl-based Utilities Tcl Extension Package


SWIG generated Tcl interfaces Tcl-Interface


tcl3dOgl tcl3dOgl tcl3dOgl

C-based Utilities OpenGL 4.0 and extensions Togl Widget


C/C++-Level


Tcl3D Version 0.5.0

image

Released 2010/12/31: Development based on Tcl/Tk 8.5.8. OpenGL wrapping based on GLEW 1.5.7. Support of OpenGL 4.1. Togl supports selection of OpenGL core profile.


Tcl-Level


Tcl3D Demos and Applications


tcl3dOgl tcl3dGauges

Tcl-based Utilities Tcl Extension Package


SWIG generated Tcl interfaces Tcl-Interface


tcl3dOgl tcl3dOgl tcl3dOgl

C-based Utilities OpenGL 4.1 and extensions Togl Widget


tcl3dCg tcl3dSDL tcl3dFTGL

Cg Shading Joystick and CD Font Rendering


tcl3dGl2ps tcl3dOde tcl3dOsg

OpenGL to PS/PDF Physics Engine OpenSceneGraph


C/C++-Level

image

image

image

image

image

tcl3dCg

Cg Shading

tcl3dSDL

Joystick and CD

tcl3dFTGL

Font Rendering

tcl3dGl2ps

OpenGL to PS/PDF

tcl3dOde

Physics Engine

tcl3dCg

Cg Shading

tcl3dSDL

Joystick and CD

tcl3dFTGL

Font Rendering

tcl3dGl2ps

OpenGL to PS/PDF

tcl3dOde

Physics Engine

tcl3dCg

Cg Shading

tcl3dSDL

Joystick and CD

tcl3dFTGL

Font Rendering

tcl3dGl2ps

OpenGL to PS/PDF

tcl3dOde

Physics Engine

tcl3dOsg

OpenSceneGraph

tcl3dCg

Cg Shading

tcl3dSDL

Joystick and CD

tcl3dFTGL

Font Rendering

tcl3dGl2ps

OpenGL to PS/PDF

tcl3dOde

Physics Engine

tcl3dOsg

OpenSceneGraph

tcl3dCg

Cg Shading

tcl3dSDL

Joystick and CD

tcl3dFTGL

Font Rendering

tcl3dGl2ps

OpenGL to PS/PDF

tcl3dOde

Physics Engine

tcl3dOsg

OpenSceneGraph

tcl3dCg

Cg Shading

tcl3dSDL

Joystick and CD

tcl3dFTGL

Font Rendering

tcl3dGl2ps

OpenGL to PS/PDF

tcl3dOde

Physics Engine

tcl3dOsg

OpenSceneGraph

tcl3dCg

Cg Shading

tcl3dSDL

Joystick and CD

tcl3dFTGL

Font Rendering

tcl3dGl2ps

OpenGL to PS/PDF

tcl3dOde

Physics Engine

tcl3dOsg

OpenSceneGraph

tcl3dCg

Cg Shading

tcl3dSDL

Joystick and CD

tcl3dFTGL

Font Rendering

tcl3dGl2ps

OpenGL to PS/PDF

tcl3dOde

Physics Engine

tcl3dOsg

OpenSceneGraph

Figure 7.1: Tcl3D graphical release history

The following table shows the Tcl3D releases in relation to official OpenGL releases.


image

OpenGL version Release date Tcl3D version Wrapped OpenGL

version

Wrapped file

OpenGL 1.0 01/1992

OpenGL 1.1 01/1997

OpenGL version

Release date

Tcl3D version

Wrapped OpenGL version

Wrapped file

OpenGL 1.2

03/1998

OpenGL 1.2.1

10/1998

OpenGL 1.3

08/2001

OpenGL 1.4

07/2002

OpenGL 1.5

07/2003

OpenGL 2.0

09/2004

05/2005

Tcl3D 0.1.0

OpenGL 1.1

gl.h

01/2006

Tcl3D 0.2.0

OpenGL 2.0

OglExt

OpenGL 2.1

07/2006

OpenGL 3.0

07/2008

12/2008

Tcl3D 0.4.0

OpenGL 3.0

GLEW 1.5.1

OpenGL 3.1

03/2009

OpenGL 3.2

08/2009

03/2010

Tcl3D 0.4.2

OpenGL 3.2

GLEW 1.5.3

OpenGL 3.3

03/2010

OpenGL 4.0

03/2010

07/2010

Tcl3D 0.4.3

OpenGL 4.0

GLEW 1.5.4

OpenGL 4.1

07/2010

12/2010

Tcl3D 0.5.0

OpenGL 4.1

GLEW 1.5.7

Table 7.1: Tcl3D release timeline



7.2 Release details

7.2 Release details


Version 0.5.0 (2010/12/31): Tcl/Tk updated to version 8.5 (using ttk and dicts).


+ Windows 7 64-bit : VS 2008 Express (32-bit)

+ SuSE Linux 10.2 32-bit (2.6.18) : gcc 4.1.2

+ SuSE Linux 10.2 64-bit (2.6.18) : gcc 4.1.2

+ Mac OSX 10.4.11 : gcc 4.0.1

+ Tcl/Tk 8.4.18

+ SWIG 1.3.40

Version 0.4.2 (2010/03/28): Bug fix and maintenance release.

- Enhancements / New features:

+ GLEW version updated to 1.5.3. OpenGL support now up to 3.2.

+ Cg version updated to 2.2.0017 (Cg 2.2 February 2010 release).

+ Gl2ps version updated to 1.3.5.

+ Starpack related:

+ New utility functions:

tcl3dOglGetGlewVersion, tcl3dCameraModel, tcl3dTeapotModel.

+ New OpenGL information and query functions:

tcl3dOglGetVersionList, tcl3dOglIsFuncWrapped, tcl3dOglGetFuncSignature, tcl3dOglGetFuncVersion, tcl3dOglGetEnumVersion, tcl3dOglGetFuncDeprecated, tcl3dOglGetUrl, tcl3dOglGetVersionFuncs, tcl3dOglGetVersionEnums.




7.3 Obsolete functions

7.3 Obsolete functions


The following table shows all obsolete functions. Most of these functions have just been renamed to get a more consistent naming scheme.

The obsolete functions are still available, but may be removed in future versions.

Version

Old Name

New Name


0.3.2

tcl3dCheckCgError

tcl3dCgGetError

tcl3dGetCgProfileList

tcl3dCgGetProfileList

tcl3dFindCgProfile

tcl3dCgFindProfile

tcl3dFindCgProfileByNum

tcl3dCgFindProfileByNum

tcl3dPrintCgProgramInfo

tcl3dCgPrintProgramInfo

tcl3dHeightMapFromPhoto

tcl3dDemoUtilHeightMapFromPhoto

tcl3dReadImage

tcl3dReadRedBookImage

tcl3dCreatePdf

tcl3dGl2psCreatePdf

tcl3dInit

tcl3dOglExtInit

tcl3dCheckGlError

tcl3dOglGetError

tcl3dPhoto2Vector

tcl3dPhotoToVector


0.3.3

tcl3dHaveExtension

tcl3dOglHaveExtension

tcl3dHaveVersion

tcl3dOglHaveVersion

tcl3dGetVersions

tcl3dOglGetVersions

tcl3dGetExtensions

tcl3dOglGetExtensions

tcl3dGetStates

tcl3dOglGetStates

tcl3dVector2Photo

tcl3dVectorToPhoto

0.4.0


tcl3dOglExtInit

Still existent for backwards compatibility, but functionality not needed anymore.

0.4.1

TYPE_convert

TYPE_cast


0.4.2

tcl3dOglGetFuncSignatureList

Use tcl3dOglGetFuncSignature instead.

tcl3dOglGetFuncVersionList

Use tcl3dOglGetFuncVersion instead.

tcl3dOglGetStates

No replacement function.

Table 7.2: List of obsolete functions

8 References

8 References


Tcl3D specific references:

  1. Tcl3D homepage: http://www.tcl3d.org/

  2. Tcl3D page on the Tclers Wiki: http://wiki.tcl.tk/15278

  3. Tcl3D discussion page on the Tclers Wiki: http://wiki.tcl.tk/16057

  4. Tcl3D “Demo of the month” page on the Tclers Wiki: http://wiki.tcl.tk/17771

  5. Tcl3D Reference Manual: http://www.tcl3d.org/html/docs.html



    Libraries wrapped with Tcl3D:

  6. Togl page at SourceForge: http://sourceforge.net/projects/togl/

  7. Cg download: http://developer.nvidia.com/object/cg_toolkit.html

  8. SDL download: http://www.libsdl.org/

  9. FTGL download: http://sourceforge.net/projects/ftgl/

  10. Freetype download: http://www.freetype.org/

  11. GL2PS download: http://www.geuz.org/gl2ps/

  12. ODE download: http://www.ode.org/

  13. OSG download: http://www.openscenegraph.org/

  14. GLEW: http://glew.sourceforge.net/

  15. GLsdk library: http://oss.sgi.com/projects/ogl-sample/sdk.html



    Demos used in Tcl3D:

  16. NeHe’s tutorials: http://nehe.gamedev.net/

  17. Kevin Harris’ code samples: http://www.codesampler.com/oglsrc.htm

  18. Vahid Kazemi’s GameProgrammer page: http://www.gameprogrammer.org/

  19. Nate Robins OpenGL tutorials: http://www.xmission.com/~nate/tutors.html

  20. The Redbook sources: http://www.opengl-redbook.com/source/


  21. OpenGL GLUT demos: http://www.opengl.org/resources/code/samples/glut_examples/demos/demos.html


  22. Paul Bourke’s textured sphere: http://local.wasp.uwa.edu.au/~pbourke/texture/spheremap/

    Nopper's OpenGL core profile demos: http://nopper.tv/opengl.html

    Nopper's OpenGL core profile demos: http://nopper.tv/opengl.html



  23. Tools needed for Tcl3D development:

  24. SWIG (Simplified Wrapper and Interface Generator): http://www.swig.org/

  25. ActiveTcl (Batteries included distribution): http://www.activestate.com/

  26. Starpack Wiki page: http://wiki.tcl.tk/3663



    Documentation:

  27. Woo, Neider, Davis: OpenGL Programming Guide, Addison-Wesley, “The Redbook”

  28. OpenGL Wiki page: http://wiki.tcl.tk/2237

  29. OpenGL Extension Registry: http://www.opengl.org/registry/



    Miscellaneous:

  30. Roger E Critchlow’s Frustum: http://www.elf.org/pub/frustum01.zip

  31. Paul Obermeier's Portable Software: http://www.posoft.de/