Togl - a Tk OpenGL widget

Introduction

• color-index mode support including color allocation functions
• support for requesting stencil, accumulation, alpha buffers, etc
• multiple OpenGL drawing widgets
• OpenGL extension testing from Tcl

Togl is copyrighted by Brian Paul (brianp@ssec.wisc.edu) and Benjamin Bederson (bederson@cs.unm.edu). See the LICENSE file for details.

The Togl WWW page is available from:

• Wisconsin at http://www.ssec.wisc.edu/~brianp/Togl.html
• New Mexico at http://www.cs.unm.edu/~bederson/Togl.html

Prerequisites

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

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

Getting Togl

• Wisconsin at ftp://iris.ssec.wisc.edu/pub/misc/Togl-1.0.tar.gz
• New Mexico at ftp://ftp.cs.unm.edu/pub/bederson/Togl-1.0.tar.gz

• Host: iris.ssec.wisc.edu
• Login: anonymous
• Password: your email address
• Directory: pub/misc
• File: Togl-1.0.tar.gz

Using Togl With Your Application

C Togl Functions

#include "togl.h"

int Togl_Init( Tcl_Interp *interp )

Initializes the Togl module. This is typically called from the Tk_Main() callback function.

void Togl_CreateFunc( Togl_Callback *proc )

void Togl_DisplayFunc( Togl_Callback *proc )

void Togl_ReshapeFunc( Togl_Callback *proc )

Register C functions to be called by Tcl/Tk when a widget is realized, must be redrawn, or is resized, respectively.

Each C callback must be of the form:

	void callback( struct Togl *togl )
	{
	   ...your code...
	}

void Togl_CreateCommand( char *cmd_name, Togl_CmdProc *cmd_proc )

Used to create a new Togl sub-command. The C function which implements the command must be of the form:

	int callback( struct Togl *togl, int argc, char *argv[] )
	{
	   ...your code...
	   return TCL_OK or TCL_ERROR;
	}
	

void Togl_PostRedisplay( struct Togl *togl )

Signals that the widget should be redrawn. When Tk is next idle the user's C render callback will be invoked. This is typically called from within a Togl sub-command which was registered with Togl_CreateCommand().

void Togl_SwapBuffers( struct Togl *togl )

Swaps the front and back color buffers for a double-buffered widget. glFlush() is executed if the window is single-buffered. This is typically called in the rendering function which was registered with Togl_DisplayFunc().

char *Togl_Ident( struct Togl *togl )

Returns a pointer to the identification string associated with an Togl widget or NULL if there's no identifier string.

int Togl_Width( struct Togl *togl )

Returns the width of the given Togl widget. Typically called in the function registered with Togl_ReshapeFunc().

int Togl_Height( struct Togl *togl )

Returns the height of the given Togl widget. Typically called in the function registered with Togl_ReshapeFunc().

Tcl_Interp *Togl_Interp( struct Togl *togl )

Returns the Tcl interpreter associated with the given Togl widget.

unsigned long Togl_AllocColor( struct Togl *togl, float red, float green, float blue )

Allocate a color from a read-only colormap. Given a color specified by red, green, and blue return a colormap index (aka pixel value) whose entry most closely matches the red, green, blue color. Red, green, and blue are values in [0,1]. This function is only used in color index mode when the -privatecmap option is false.

void Togl_FreeColor( struct Togl *togl, unsigned long index )

Free a color in a read-only colormap. Index is a value which was returned by the Togl_AllocColor() function. This function is only used in color index mode when the -privatecmap option is false.

void Togl_SetColor( struct Togl *togl, int index, float red, float green, float blue )

Load the colormap entry specified by index with the given red, green and blue values. Red, green, and blue are values in [0,1]. This function is only used in color index mode when the -privatecmap option is true.

Tcl Togl commands

togl pathName [options]

Creates a new togl widget with name pathName and an optional list of configuration options. Options include:

Option		Default	Comments
---------------	------- --------------------------------------------------
-width		400	Width of widget in pixels.
-height		400	Height of widget in pixels.

-ident		""	A user identification string ignored by togltk.  This
			can be useful in your C callback functions to determine
			which Togl widget is the caller.

-rgba		true	If true, use RGB(A) mode
			If false, use Color Index mode

-double		false	If false, request a single buffered window
			If true, request double buffered window

-depth		false	If true, request a depth buffer

-accum		false	If true, request an accumulation buffer

-alpha		false	If true and -rgba is true, request an alpha channel

-stencil	false	If true, request a stencil buffer

-privatecmap	false	Only applicable in color index mode.
			If false, use a shared read-only colormap.
			If true, use a private read/write colormap.

pathName configure

Returns all configuration records for the named togl widget.

pathName configure -option

Returns configuration information for the specifed option which may be one of:

-width

Returns the width configuration of the widget in the form:

-width width Width W w

where W is the default width in pixels and w is the current width in pixels

-height

Returns the height configuration of the widget in the form:

-height height Height H h

where H is the default height in pixels and h is the current height in pixels

-extensions

Returns a list of OpenGL extensions available. For example: GL_EXT_polygon_offset GL_EXT_vertex_array

pathName configure -option value

Reconfigure an togl widget. option may be one of:

-width

Resize the widget to value pixels wide

-height

Resize the widget to value pixels high

pathName render

Causes the render callback function to be called for pathName.

Demo programs

• double - compares single vs double buffering with two Togl widgets
• texture - lets you play with texture mapping options (note that Mesa doesn't support some of them)
• index - demo of using color index mode

To compile the demos, edit the Makefile, then type "make". The Makefile currently works with IRIX.

To run a demo just type "double" or "texture" or "index".