Togl C API

Contents

Compiling 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 Toglstub21.lib opengl32.lib user32.lib gdi32.lib, on Mac OS X, link against -lToglstub2.1 -framework OpenGL, on other platforms, link against -lToglstub2.1 -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 Togl21.lib tk84.lib tcl84.lib opengl32.lib user32.lib gdi32.lib, on Mac OS X, link against -lTogl2.1 -framework Tk -framework Tcl -framework OpenGL, on other platforms, link against -lTogl2.1 -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. If successful, the return value is TCL_OK.
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 True if successful. 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.
int Togl_CopyContext(const Togl *from, const Togl *to, unsigned int mask)
Copy a subset of the OpenGL context state from from one context to another using the mask parameter who values are the same as glPushAttrib. The return value is TCL_OK if the context was copied.

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 Microsoft 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 True if the window should be redrawn. See Togl_PostRedisplay.
Bool Togl_HasRGBA(const Togl *t)
Return True if Togl widget has a RBGA color buffer. False means that the widget is using a color index buffer.
Bool Togl_IsDoubleBuffered(const Togl *t)
Return True if Togl widget is double buffered.
Bool Togl_HasDepthBuffer(const Togl *t)
Return True if Togl widget is has a depth buffer.
Bool Togl_HasAccumulationBuffer(const Togl *t)
Return True if Togl widget has an accumulation buffer.
Bool Togl_HasDestinationAlpha(const Togl *t)
Return True if Togl widget has a destination alpha buffer.
Bool Togl_HasStencilBuffer(const Togl *t)
Return True if Togl widget has a stencil buffer.
int Togl_StereoMode(const Togl *t)
Return current stereo mode. See ??
Bool Togl_HasMultisample(const Togl *t)
Return True if Togl widget has a multisample buffer.

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.

Tcl_Obj *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). If successful, a Togl BitmapFont object is returned. NULL is returned on failure.
int Togl_UnloadBitmapFont(Togl *togl, Tcl_Obj *toglfont)
Destroys the bitmap display lists created by by Togl_LoadBitmapFont(). If successful, the return value is TCL_OK.
int Togl_WriteChars(const Togl *togl, const Tcl_Obj *toglfont, const char *string, int length) Draw the given string. If the given length is zero, then it is computed using strlen. Returns the length of the drawn string.
int Togl_WriteObj(const Togl *togl, const Tcl_Obj *toglfont, Tcl_Obj *obj)
Tcl_Obj interface to Tcl_WriteChars.

Client Data Functions

Each Togl structure has a pointer to an arbitrary client data structure.

void Togl_SetClientData(Togl *togl, ClientData clientData)
Set the Togl widget's client data pointer to clientData.
ClientData Togl_GetClientData(const Togl *togl)
Return the Togl widget's client data pointer.

Overlay Functions

These functions are modeled 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. The stereo viewing parameters, eyeseparation and convergence need to be set with the Togl's stereo options.

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)
Replacement for OpenGL's glFrustum that takes into account the alternate stereo mode.
void Togl_Ortho(const Togl *togl, GLfloat left, GLfloat right, GLfloat bottom, GLfloat top, GLfloat near, GLfloat far)
Replacement for OpenGL's glOrtho that takes into account the alternate stereo mode.
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. If successful, the return value is TCL_OK.

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". If successful, the return value is TCL_OK.
int Togl_GetToglFromName(Tcl_Interp *interp, const char *cmdName, Togl **toglPtr)
Attempt to return a Togl structure "toglPtr" from the Tcl command name "cmdName". If successful, the return value is TCL_OK.
Get Togl at SourceForge.net. Fast, secure and Free Open Source software downloads Valid HTML 4.01 Transitional