# Downloading and Installing Togl

## Contents

- Prerequisites
- Downloading
- Installing
  - X11 usage
  - Microsoft Windows usage
  - Mac OS X usage
- Version History

## Prerequisites

You should have Tcl and Tk installed on your computer. Togl works with Tcl/Tk version 8.1 and up (all recent testing has been with version 8.4). The Mac OS X version requires version 8.4 (note: versions 8.4.12 and 8.4.13 have a bug when unmapping Togl widgets).

You must also have OpenGL or Mesa (a free alternative to OpenGL with the same API) installed on your computer.

And one should be familiar with Tcl, Tk, OpenGL, and C programming to use Togl effectively.

## Downloading Togl

Togl can be downloaded from the SourceForge Files page.

Several prebuilt binary distributions are available as well as a source distribution.

## Installing Togl

### Installing prebuild binaries

Prebuilt binaries provide a Togl2.1 directory, the togl.h, togl_ws.h and toglDecls.h include files, and the togl stub library (libToglstub2.1.a or Toglstub20.lib, etc). The Togl2.1 directory needs to copied into one of the directories on Tcl's package path (type `puts $auto_path` in the Tcl interpreter to see the list of directories). If you have C code that needs to access Togl's subroutines directly, place the include file in the same place as Tcl's include file and the stub library in the same place as Tcl's stub library.

### Installing from source

Togl uses the Tcl Extension Architecture to be able to build on the same platforms Tcl can be built on. In addition to the Togl source, you will need to have the Tcl and Tk source distributions because not all installations have the needed Tcl and Tk internal header files.

How you link with Togl depends on how you're planning to use it. There are basically three ways of using Togl with your application:

- Install the Togl shared library and pkgIndex.tcl file (using `make install`) and link to the Togl stubs library with your executable or shared library. In this case you must call Togl_InitStubs() (and probably Tcl_InitStubs() — Tk_InitStubs is only needed if you call Tk functions). This is the way the included Togl examples are built.
- Link to the Togl shared library or "compile in" the Togl object files with your executable or shared library. In this case you must call Togl_Init() from your C code to initialize Togl.
- Install the Togl shared library and pkgIndex.tcl file (using `make install`) and then load it using Tcl commands or Tcl_PkgRequire(). Then use Tcl commands to create and manipulate the Togl widget.

Since Togl is compiled into a shared library using the Tcl/Tk stubs-interface, the same binary can be used with any version of Tck/Tk from 8.1 and up. See `README.stubs` for more info.

Specific platform notes follow:

#### Unix/X11 usage

Unix/X systems only need the public Tcl/Tk include files. Just `configure`, `make`, and optionally `make install`.

#### Microsoft Windows usage

Microsoft Windows platforms need `tkWinInt.h` and other internal Tk header files. So you need a Tcl/Tk source distribution in addition to the Togl distribution (or copy over the various include files).

Here's the minimal way to build Togl with Tcl/Tk using the gcc that is distributed as part of the cygwin tools (Microsoft's compilers work too):

>     VER=8.4.12
>     SRCDIR=`pwd`

>     cd $SRCDIR/tcl$VER/win
>     env 'CC=gcc -mno-cygwin' ./configure --enable-threads
>     make libtclstub84.a

>     cd $SRCDIR/tk$VER/win
>     env 'CC=gcc -mno-cygwin' ./configure --enable-threads
>     make libtkstub84.a

>     cd $SRCDIR/Togl2.1
>     env 'CC=gcc -mno-cygwin' ./configure --with-tcl=../tcl$VER/win --with-tk=../tk$VER/win

>     make

The resulting `Togl21.dll` and `pkgIndex.tcl` should be installed into your Tcl installation just like any other package.

If you change all of the above `make`'s to `make install` instead, then the Togl package is installed correctly.

#### Mac OS X usage

These special instructions are for building the Aqua version of Togl. Mac OS X needs `tkMacOSXInt.h` and other internal Tk header files. Unfortunately, the Tcl and Tk frameworks that Apple distributes are missing the internal headers. So you need a Tcl/Tk source distribution in addition to the Togl distribution (or copy over the various include files). You would probably want a newer version of Tcl and Tk anyway because each minor revision of 8.4 has many Aqua bug fixes.

Here's one way to build Tcl, Tk, and Togl on Mac OS X (assuming they are all in the same directory) to install in your home directory:

>     VER=8.4.12

>     mkdir -p ~/bin
>     make -C tcl$VER/macosx install PREFIX="${HOME}" INSTALL_PATH="${HOME}/Library/Frameworks"
>     make -C tk$VER/macosx install PREFIX="${HOME}" INSTALL_PATH="${HOME}/Library/Frameworks" APPLICATION_INSTALL_PATH="${HOME}/Applications"

>     cd Togl2.1
>     ./configure --prefix="${HOME}"
>     make install

## Version History

### Version 1.0 — March, 1996

- Initial version

### Version 1.1 (never officially released)

- Added Togl_LoadBitmapFont function
- Fixed a few bugs

### Version 1.2 — November, 1996

- added swapbuffers and makecurrent Tcl commands
- more bug fixes
- upgraded to suport Tcl 7.6 and Tk 4.2
- added stereo and overlay plane support
- added Togl_Get/SetClientData() functions
- added Togl_DestroyFunc()

### Version 1.3 — May 2, 1997

- fixed a bug in Togl_Configure()
- fixed a compilation problem in using Tcl_PkgProvide() with Tcl < 7.4
- new overlay functions: Togl_ExistsOverlay, Togl_GetOverlayTransparentValue, Togl_IsMappedOverlay, Togl_AllocColorOverlay, Togl_FreeColorOverlay
- added X11 functions: Togl_Display, Togl_Screen, Togl_ScreenNumber, Togl_Colormap
- added Togl_DumpToEpsFile function
- fixed a C++ compilation problem
- more robust overlay code
- added timers (Togl_TimerFunc) from Peter Dern and Elmar Gerwalin

### Version 1.4 — September 17, 1997

- ported to Microsoft Windows NT (Robert Casto)
- updated for Tcl/Tk 8.0
- added many config flags (-redsize, -depthsize, etc) (Matthias Ott)
- added Togl_Set*Func() functions to reassign callback functions (Matthias Ott)
- added Togl_ResetDefaultCallbacks() and Togl_ClientData() functions (Greg Couch)

### Version 1.5 — September 18, 1998

- fixed a few Unix and Microsoft Windows compilation bugs
- added Ben Evan's SGI stereo functions
- multiple expose events now reduced to one redraw
- destroying Togl widgets caused problems, patched by Adrian J. Chung
- added Togl_TkWin() function
- updated for Tcl/Tk 8.0p2
- added gears demo from Philip Quaife
- added `-sharelist` and `-sharecontext` config flags
- fixed a few overlay update bugs
- added `-indirect` config flag

### Version 1.6 — May 7, 2003

- added Togl_SetTimerFunc function
- updated for Tcl/Tk 8.0.5 and 8.1
- context sharing added for Microsoft Windows
- Macintosh support (by Paul Thiessen)
- Tcl/Tk stubs support — see README.tcl (by Jonas Beskow)

### Version 1.7 — January 6, 2006

- added Mac OS X support
- enabled asking for quad-buffered stereo pixel formats on all platforms (use -oldstereo on SGIs for splitscreen stereo — C API changed too)
- configuring the cursor is no longer slow
- added `-pixelformat` config flag
- added setgrid support (unfortunately many window managers can't cope with 1x1 pixel grid)
- only free context when last reference is gone
- switched to TEA-based configure (instead of editting make files)

### Version 2.0 — April 22, 2008

- stubified C API
- replaced EPS support with TK photo image support
- simplified C API by requiring callback command options
- Added command arguments for create, destroy, etc. callbacks, so there is a -createcommand option to the togl command (etc.). (and removed Togl_*Func from the C API)
- added togl instance commands that call C API — see documentation
- use Tcl objects internally
- use Tcl object interface for callbacks
- vertical sync control
- fix thread safety in anticipation that OpenGL drivers may someday be thread safe
- added simple stereo rendering interface
- revised font C API
- updated font support for Tk 8.4 on all platforms
- updated documentation
- prebuilt binaries

### Version 2.1 — December 2009

- incorporate the part of the X11R6 Xmu library that Togl uses so it will work on (Linux) systems that don't have the Xmu shared library
- Mac OS X Aqua delete context bug fix
- multisampling support
- pbuffer support (Unix/X11, Microsoft Windows, Mac OS X)
- Ability to copy context state
- row interleaved stereo support

### Future plans

Patches for the following are especially welcome:

- Tk 8.5 fonts
- Aqua Cocoa support (Tk 8.6b2)
- OpenGL 3 contexts
- EGL support
- RGB overlays
- Tcl access to colormap manipulation
- NVidia consumer stereo support