# Using the Togl Widget

## Contents

- Using Togl With Your Application
- Examples
- Tcl API
- C API

## Using Togl With Your Application

First, double check that you have all of the prerequisites and that you have compiled and installed Togl.

Then, Togl acts like any other extension package — to load it, you use the Tcl `package` command:

> `package require Togl 2.0`

After that, you can create a Togl widget just like any other Tk widget.

## Examples

There are eight working examples:

> double.tcl | — compares single vs double buffering with two Togl widgets
> texture.tcl | — lets you play with texture mapping options
> index.tcl | — example of using color index mode
> overlay.tcl | — example of using overlay planes (requires overlay hardware)
> stereo.tcl | — stereo example
> gears.tcl | — spinning gears example
> multisample.tcl | — multisampling example
> pbuffer.tcl | — pbuffer (off-screen rendering) example

Each example consists of two files: a Tcl script for the user interface, and a Tcl C package that does the OpenGL drawing. To compile the examples, type `make examples` in the Togl source directory. The C packages are compiled into shared libraries that are loaded into the Tcl interpreter as Tcl/Tk-extensions. The examples are started by running the corrsponding Tcl script: just type `./double.tcl` (or `./texture.tcl` etc.) or run under one of the Tcl interpreters, i.e., `tclsh` or `wish`. For example:

> `tclsh84 double.tcl`

Other examples that use Tcl for OpenGL drawing can be found in the Tcl3D demos.

### Togl callbacks

All of the examples have similar structure. First they create the user interface with one or more Togl widgets. Each Togl widget is configured with the desired pixel format and several callback commands (not all are needed):

`-createcommand` | Called when Togl widget is mapped — when it is safe to initialize the OpenGL context.
`-reshapecommand` | Called when the Togl widget is resized — when the OpenGL context's viewport needs to be changed.
`-displaycommand` | Called when the contents of the Togl widget needs to be redrawn. Redraws are normally delayed to be when the Tcl event loop is idle (see the togl widget's `postredisplay` command), or as the result of an explict call to the togl's widgets `render` command.
`-destroycommand` | Called when the Togl widget is destroyed. While OpenGL frees display lists and other resources, sometimes there's some associated state that is no longer needed.
`-timercommand` | Called every n milliseconds as given by the `-time` option.
`-overlaydisplaycommand` | Called when the overlay planes needs to be redrawn. The overlay planes are created and reshaped at the same time as the main OpenGL context.

Typically, only `-createcommand`, `-reshapecommand` and `-displaycommand` are used.