Togl Tcl API

Togl Tcl command
Togl widget commands
Togl configuration options

Togl Tcl command

The togl command creates a new Tk widget, a Tcl command, whose name is pathName. This command may be used to invoke various operations on the widget.

togl pathName [options]

If no options are given, a 400 by 400 pixel RGB window is created. This command may be used to invoke various operations on the widget.

Togl widget commands

The following commands are possible for an existing togl widget:

Configuration commands

pathName cget -option: Return current value of given configuration option.

pathName configure pathName configure -option: If no option is given, then return information about all configuration options. Otherwise, return configuration information for given option. All configuration information consists of five values: the configuration option name, the option database name, the option database class, the default value, and the current value.

pathName configure -option value: Reconfigure a Togl widget. option may be any one of the options listed below.

pathName contexttag: Returns an integer that represents the context tag. All Togl widgets with the same context tag share display lists.

Extensions command

pathName extensions

Returns a list of OpenGL extensions available. For example:


if {[lsearch [pathName extensions] GL_EXT_bgra] != -1]} {
    ....
}

would check if the GL_EXT_bgra extension were supported.

Rendering commands

pathName postredisplay: Cause the displaycommand callback to be called the next time the event loop is idle.

pathName render: Causes the displaycommand callback to be called for pathName.

pathName swapbuffers: Causes front/back buffers to be swapped if in double buffer mode. And flushs the OpenGL command buffer if in single buffer mode. (So this is appropriate to call after every frame is drawn.)

pathName makecurrent: Make the widget specified by pathName and its OpenGL context the current ones. This is implicitly called before any callback command is invoked.

pathName copycontextto toPathName mask: Copy a subset of the OpenGL context state from pathName to toPathName according the given mask. The mask is an integer corresponding to the same values as glPushAttrib.

Image commands

pathName takephoto imagename: Copy the contents of the togl window into the given Tk photo image. Transparency values are copied and should be fully opaque for windows without alpha bitplanes.

These functions provide an interface to the simple bitmap font capabilities that every OpenGL implementation provides. Better font support is found in other packages, e.g., Tcl3D or with different C APIs.

pathName loadbitmapfont font: font can be any of font descriptions listed in the Tk font command. It returns a togl font object.

pathName unloadbitmapfont toglfont: Releases the OpenGL resources needed by the toglfont.

pathName write toglfont [-pos xyzw] [-color rgba] string: Write the given string in the given toglfont, optionally at a particular position, xyzw and color, rgba. xyzw is either a 2, 3, or 4 element list of numbers. rgba is either a 3 or 4 element list of numbers.

Overlay Commands

pathName uselayer layer: This is a variation on the makecurrent command that makes the overlay OpenGL context current if layer is 2 and makes the normal OpenGL context current if layer is 1.

pathName showoverlay: Turn on drawing in the overlay planes.

pathName hideoverlay: Turn off drawing in the overlay planes.

pathName postredisplayoverlay: Cause the overlay OpenGL context to be redrawn the next time the Tcl event loop is idle.

pathName renderoverlay: Causes the overlaydisplaycommand callback to be called for pathName.

pathName existsoverlay: Return true if togl widget has overlay planes.

pathName ismappedoverlay: Return true if overlay planes are shown.

pathName getoverlaytransparentvalue: Return overlay plane's transparent pixel value.

OpenGL (Stereo) Commands

These commands exist to support stereo rendering. Just replace select OpenGL calls with the Togl versions and stereo rendering will magically work. And don't forget to update the stereo options.

pathName drawbuffer mode: Replaces calls to glDrawBuffer. The mode is an integer.

pathName clear mask: Replaces calls to glClear. The mask is an integer.

pathName frustum left right bottom top near far: Replaces calls to glFrustum.

pathName ortho left right bottom top near far: Replaces calls to glOrtho.

pathName numeyes: Returns numbers of eyes — basically, 2 for stereo views and 1 for all others, except some stereo views only need one eye from OpenGL.

Togl configuration options

Togl's configuration options can be separated into several categories: geometry, pixel format, and other. The pixel format related options can only be set at widget creation time. The other options can be changed dynamically by the pathName configure command (see above).

Drawing callbacks

Option	Default	Comments
`-createcommand`	{}	Can be abbreviated `-create`.
`-displaycommand`	{}	Can be abbreviated `-display`.
`-reshapecommand`	{}	Can be abbreviated `-reshape`.
`-destroycommand`	{}	Can be abbreviated `-destroy`.
`-overlaydisplaycommand`	{}	Can be abbreviated `-overlaydisplay`.

Geometry Options

Option	Default	Comments
`-width`	400	Set width of widget in pixels. It may have any of the forms accepted by Tk_GetPixels.
`-height`	400	Set height of widget in pixels. It may have any of the forms accepted by Tk_GetPixels(3).
`-setgrid`	0	Turn on gridded geometry management for togl widget's toplevel window and specify the geometry of the grid. See the manual pages for Tk's wm(n) and Tk_SetGrid(3) for more information. Unlike the text widget, the same value is used for both width and height increments.

Timer Options

Option	Default	Comments
`-time`	1	Specifies the interval, in milliseconds, for calling the timer callback function which was registered with -timercommand.
`-timercommand`	{}	Can be abbreviated `-timer`.

Stereo Options

Option	Default	Comments
`-eyeseparation`	2.0	Set the distance between the eyes in viewing coordinates.
`-convergence`	30.0	Set the distance to the screen from the eye in viewing coordinates (the distance at which the eyes converge).

You'd think these values would be given in physical units, but there's no single right way to convert to viewing coordinates from physical units. So if you're willing to use Tk's idea of the horizontal size of a window in millimeters (not always correct), you could convert the average eye separation of 63 mm to your viewing coordinates, and use that value as the eye separation.

Miscellaneous Options

Option	Default	Comments
`-cursor`	""	Set the cursor in the widget window.
`-swapinterval`	1	Set the minimum swap interval measure in video frame periods. The default is 1 for for non-tearing artifacts when swapping buffers. Use a value of 0 when benchmarking frame rates.
`-ident`	""	A user identification string. This is used match widgets for the `-sharecontext` and the `-sharelist` options (see below). This is also useful in your callback functions to determine which Togl widget is the caller.

Pixel Format Options

The following options can only be given when the togl widget is created — that is, unlike other options, the togl widget can not be reconfigured with different values for the following options after it is created.

Option	Default	Comments
`-rgba`	true	If true, use RGB(A) mode, otherwise use Color Index mode.
`-redsize`	1	Minimum number of bits in red component.
`-greensize`	1	Minimum number of bits in green component.
`-bluesize`	1	Minimum number of bits in blue component.
`-alpha`	1	If true and `-rgba` is true, request an alpha channel.
`-alphasize`	1	Minimum number of bits in alpha component.

`-double`	false	If true, request a double-buffered window, otherwise request a single-buffered window.

`-depth`	false	If true, request a depth buffer.
`-depthsize`	1	Minimum number of bits in depth buffer.

`-accum`	false	If true, request an accumulation buffer.
`-accumredsize`	1	Minimum number of bits in accumulation buffer red component.
`-accumgreensize`	1	Minimum number of bits in accumulation buffer green component.
`-accumbluesize`	1	Minimum number of bits in accumulation buffer blue component.
`-accumalphasize`	1	Minimum number of bits in accumulation buffer alpha component.

`-stencil`	false	If true, request a stencil buffer.
`-stencilsize`	1	Minimum number of bits in stencil component.

`-auxbuffers`	0	Desired number of auxiliary buffers.

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

`-overlay`	false	If true, request overlay planes.

`-stereo`	mode	See the stereo information for details about the various modes. Stereo parameters are changed with the stereo options. When using a non-native stereo mode, the OpenGL glDrawBuffer, glClear, glFrustum, and glOrtho calls must be replaced with the Togl Tcl or C versions.

`-pbuffer`	false	If true, request off-screen framebuffer memory for the graphics. The resulting togl widget should not be managed.
`-largestpbuffer`	false	If true, when asking for a pbuffer of a given size and there isn't enough framebuffer memory available, fallback to the largest size available.

`-multisample`	false	If true, request an multisampled rendering context.
`-indirect`	false	If present, request an indirect rendering context. A direct rendering context is normally requested. Only significant on Unix/X11.
`-sharelist`	""	Togl identification string or window path name of an existing Togl widget with which to share display lists. If it is not possible to share display lists between the two togl widgets (depends on the graphics driver and the particular formats), it fails.
`-sharecontext`	""	Togl identification string or window path name of an existing Togl widget with which to share the OpenGL context. Note: all other pixel format options are ignored.
`-pixelformat`	0	Set the pixel format to the (platform-dependent) given value. This is a backdoor into choosing a particular pixel format that was determined by other means.