Togl Tcl API

Contents


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.

Font commands

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.

Get Togl at SourceForge.net. Fast, secure and Free Open Source software downloads Valid HTML 4.01 Transitional