Togl C API

Contents

Compling and linking C Togl Functions

All Togl functions are found in the Togl header file.

#include "togl.h"

For portability, you should include the togl.h header before any other OpenGL headers so it will compile on Microsoft Windows.

Before calling any Togl functions, you need to initialize it. Regardless if you're using stubs (by defining USE_TOGL_STUBS) or not, the following code will properly initialize togl: 

if (Tcl_InitStubs(interp, "8.1", 0) == NULL
|| Togl_InitStubs(interp, "2.0", 0) == NULL) {
    /* fail */
}

If you are using a prebuilt binary distribution, you should be sure to define USE_TOGL_STUBS beforehand.

See the source for the demo programs in the Togl source distribution for working examples.

Linking

If you are using a prebuilt binary, be sure to link against the stub library. On Microsoft Windows, link against Toglstub20.lib opengl32.lib user32.lib gdi32.lib, on Apple Mac OS X, link against -lToglstub2.0 -framework OpenGL, on other platforms, link against -lToglstub2.0 -lGLU -lGL -lm.

If building your own Togl package, you can use the stubs interface or link in the Tcl and Tk libraries as well. If using the stubs interface, link as shown above. Otherwise: on Microsoft Windows, link against Togl20.lib tk84.lib tcl84.lib opengl32.lib user32.lib gdi32.lib, on Apple Mac OS X, link against -lTogl2.0 -framework Tk -framework Tcl -framework OpenGL, on other platforms, link against -lTogl2.0 -ltk8.4 -ltcl8.4 -lGLU -lGL -lm.

Setup and Initialization Functions

int Togl_Init(Tcl_Interp *interp)
Initializes the Togl module. This is typically called from the Tk_Main() function or other Tcl package initialization function that is directly linked to the Togl (shared) library. It is also indirectly called via Tcl's package require Togl command.
const char *Togl_InitStubs(Tcl_Interp *interp, const char *version, int exact)
Loads the Togl package into the given interpreter and initializes it. version should be "2.0" or higher. This is typically called from C/C++ code that accesses Togl's C API and has installed Togl into the standard TCL hierarchy. See the Tcl InitStubs(3) or the Tk TkInitStubs(3) manual pages for more information.

Drawing-related Commands

void Togl_PostRedisplay(Togl *togl)
Signals that the widget should be redrawn. When Tk is next idle, the displaycommand callback will be invoked.
void Togl_SwapBuffers(const Togl *togl)
Swaps the front and back color buffers for a double-buffered widget. glFlush() is executed if the window is single-buffered. So this call works for both single- and double-buffered contexts. This is typically called in the displaycommand callback function.
void Togl_MakeCurrent(const Togl *togl)
Sets the current rendering context to the given widget. This is done automatically before any Togl callback functions is called. So the call is only needed if you have multiple widgets with separate OpenGL contexts. If the argument is NULL, then the rendering context is cleared and subsequent OpenGL commands will fail.
Bool Togl_SwapInterval(const Togl *togl, int interval)
Returns 1 (true) if sucessful. Attempts to change the maximum refresh rate by setting the minimum number of cycles between successive swap buffers. For benchmarking purposes, you should set the swap interval to 0.

Query Functions

char *Togl_Ident(const Togl *togl)
Returns a pointer to the identification string associated with a Togl widget or NULL if there's no identifier string.
int Togl_Width(const Togl *togl)
Returns the width of the given Togl widget. Typically called in the reshapecommand callback function.
int Togl_Height(const Togl *togl)
Returns the height of the given Togl widget. Typically called in the reshapecommand callback function.
Tcl_Interp *Togl_Interp(const Togl *togl)
Returns the Tcl interpreter associated with the given Togl widget.
Tk_Window Togl_TkWin(const Togl *togl)
Returns the Tk window associated with the given Togl widget.
Togl_FuncPtr Togl_GetProcAddr(const char *funcname)
Platform-independent way to get OpenGL function pointers from a function name. Note that in Windows (WGL) versions that "the extension function addresses are unique for each pixel format. All rendering contexts of a given pixel format share the same extension function addresses." And on *nix (GLX/X11) platforms, "the function pointers returned are context independent" (Linux ABI documentation). The Mac OS X (AGL) platform acts like a *nix platform.
int Togl_ContextTag(const Togl *t)
Returns an integer that represents the context tag. All Togl widgets with the same context tag share display lists.
Bool Togl_UpdatePending(const Togl *t)
Returns 1 (true) if the window should be redrawn. See Togl_PostRedisplay.

Color Index Mode Functions

These functions are only used for color index mode.

unsigned long Togl_AllocColor(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(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(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.

Font Functions

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

GLuint Togl_LoadBitmapFont(Togl *togl, const char *fontname)
Load the named font as a set of glBitmap display lists. fontname may be any of the font description styles accepted by the Tk font command. For maximum portability, one of the standard Tk fonts, Courier, Times, and Helvetica, should be used. Unicode fonts are treated as if they have only have an 8-bit index (so poorly). After Togl_LoadBitmapFont() has been called, returning fontbase, you can render a string s with:
glListBase(fontbase);
glCallLists(strlen(s), GL_BYTE, s);
Zero is returned if this function fails.
int Togl_UnloadBitmapFont(Togl *togl, Tcl_Obj *toglfont)
Destroys the bitmap display lists created by by Togl_LoadBitmapFont().
int Togl_WriteChars(const Togl *togl, const Tcl_Obj *toglfont, const char *str, int len)
int Togl_WriteObj(const Togl *togl, const Tcl_Obj *toglfont, Tcl_Obj *obj)
Tcl_Obj interface to Tcl_WriteChars.

Client Data Functions

void Togl_SetClientData(Togl *togl, ClientData clientData)
clientData is a pointer to an arbitrary user data structure. Each Togl struct has such a pointer. This function sets the Togl widget's client data pointer.
ClientData Togl_GetClientData(const Togl *togl)
clientData is a pointer to an arbitrary user data structure. Each Togl struct has such a pointer. This function returns the Togl widget's client data pointer.

Overlay Functions

These functions are modelled after GLUT's overlay sub-API.

void Togl_UseLayer(Togl *togl, int layer)
Select the layer into which subsequent OpenGL rendering will be directed. layer may be either TOGL_OVERLAY or TOGL_NORMAL.
void Togl_ShowOverlay(Togl *togl)
Display the overlay planes, if any.
void Togl_HideOverlay(Togl *togl)
Hide the overlay planes, if any.
void Togl_PostOverlayRedisplay(Togl *togl)
Signal that the overlay planes should be redraw. When Tk is next idle, the overlaydisplaycommand callback will be invoked.
int Togl_ExistsOverlay(Togl *togl)
Returns 1 if overlay planes exist, 0 otherwise.
int Togl_GetOverlayTransparentValue(const Togl *togl)
Returns the color index of the overlay's transparent pixel value.
int Togl_IsMappedOverlay(const Togl *togl)
Returns 1 if the overlay planes are currently displayed, 0 otherwise.
unsigned long Togl_AllocColorOverlay(const Togl *togl, float red, float green, float blue)
Allocate a color in the overlay planes. Red, green, and blue are values in [0,1]. Return the color index or -1 if the allocation fails.
void Togl_FreeColorOverlay(const Togl *togl, unsigned long index)
Free a color which was allocated with Togl_AllocColorOverlay().

Stereo Functions

Togl abstracts part of the stereo drawing process to seamlessly support quad-buffered stereo as well as various alternative stereo formats.

void Togl_DrawBuffer(Togl *togl, GLenum mode)
Switch to OpenGL draw buffer. Should be one of GL_BACK_LEFT, GL_BACK_RIGHT, GL_FRONT_LEFT, or GL_FRONT_RIGHT. It is not possible to draw in the left and right buffers at the same time in the alternate stereo modes.
void Togl_Clear(const Togl *togl, GLbitfield mask)
Replacement for OpenGL's glClear that takes into account the alternate stereo mode.
void Togl_Frustum(const Togl *togl, GLfloat left, GLfloat right, GLfloat bottom, GLfloat top, GLfloat near, GLfloat far)
eyeOffset is the distance from the center line and is negative for the left eye and positive for right eye. eyeDist and eyeOffset need to be in the same units as your model space. In physical space, eyeDist might be 30 inches from the screen and eyeDist would be +/- 1.25 inch (for a total interocular distance of 2.5 inches). So you need to convert those values.
void Togl_Ortho(const Togl *togl, GLfloat left, GLfloat right, GLfloat bottom, GLfloat top, GLfloat near, GLfloat far)
eyeOffset is the distance from the center line and is negative for the left eye and positive for right eye. eyeDist and eyeOffset need to be in the same units as your model space. In physical space, eyeDist might be 30 inches from the screen and eyeDist would be +/- 1.25 inch (for a total interocular distance of 2.5 inches). So you need to convert those values.
int Togl_NumEyes(const Togl *togl)

Stereo Example

This code works for quad-buffered stereo, as well as the other stereo modes. 

if (Togl_NumEyes(togl) == 1) {
    Togl_DrawBuffer(togl, GL_BACK);
    Togl_Clear(togl);
    glMatrixMode(GL_PROJECTION);
    glLoadIdentity();
    Togl_Frustum(togl, left, right, bottom, top, near, far);
    glMatrixMode(GL_MODELVIEW);
    draw image
} else {
    Togl_DrawBuffer(togl, GL_BACK_LEFT);
    Togl_Clear(togl);
    glMatrixMode(GL_PROJECTION);
    glLoadIdentity();
    Togl_Frustum(togl, left, right, bottom, top, near, far);
    glMatrixMode(GL_MODELVIEW);
    draw left-eye image
    Togl_DrawBuffer(togl, GL_BACK_RIGHT);
    Togl_Clear(togl);
    glMatrixMode(GL_PROJECTION);
    glLoadIdentity();
    Togl_Frustum(togl, left, right, bottom, top, near, far);
    glMatrixMode(GL_MODELVIEW);
    draw right-eye image
}
Togl_SwapBuffers(togl);

Image Functions

int Togl_TakePhoto(Togl *togl, Tk_PhotoHandle photo)
Take a photo image of the current Togl window and place it in the given photo object. If the window is partially obscured, either by other windows or by the edges of the display, the results are undefined in the obscured region.

Conversion Functions

These functions aid the programmer when writing Togl callback functions.

int Togl_GetToglFromObj(Tcl_Interp *interp, Tcl_Obj *obj, Togl **toglPtr)
Attempt to return a Togl structure "toglPtr" from the Tcl object "obj".
int Togl_GetToglFromName(Tcl_Interp *interp, const char *cmdName, Togl **toglPtr)
Attempt to return a Togl structure "toglPtr" from the Tcl command name "cmdName".
Hosted by SourceForge.net Logo