Jump to content

LIBTK.LIB

From EDM2

LIBTK.LIB is the import library for the OS/2 OpenGL Toolkit (TK), distributed with the IBM OS/2 Developer's Toolkit. The TK library is a minimal windowing and event-loop layer written specifically to support the sample programs in the OpenGL Programming Guide ("Red Book"). It abstracts OpenGL window creation, the display-mode selection, and the event dispatch loop so that OpenGL sample code can be written portably across platforms without a full UI toolkit.

File size in the OS/2 Warp 4.52 Toolkit 4.5: 4,096 bytes (2000-10-16). Source DLL: LIBTK.DLL.

LIBTK is the predecessor of GLUT on OS/2. From OS/2 Warp 4 onward it was supplemented by GLUT (the GL Utility Toolkit), but TK remained in the Toolkit for compatibility with Red Book examples and older OpenGL ports.

Concepts

Term Meaning
Display mode A bitmask of flags (RGB/color-index, depth buffer, stencil, double/single buffer, accumulation buffer) describing the required OpenGL rendering context attributes. Set before creating the window.
Display mode ID A platform-specific identifier for a pre-enumerated display mode. Used as an alternative to the flags-based mode selection.
Display mode policy Controls what happens if the exact requested mode is not available: exact match only, or nearest available.
Expose callback Called when part of the window needs to be redrawn (e.g. after it was obscured). Equivalent to WM_PAINT in PM.
Reshape callback Called when the window is resized. The callback receives the new width and height and should call glViewport.
Display callback The main rendering callback. Called by tkExec on each frame to redraw the scene.
Idle callback Called by tkExec when no other events are pending. Used for animation.
TK primitives Built-in 3D objects (box, sphere, cone, cylinder, torus, cube) available in solid (lit, with normals) and wire-frame forms.

API Summary

LIBTK.LIB exports 63 symbols (clean names) grouped into seven functional areas:

Group Functions Description
Window / display mode tkInitWindow, tkCloseWindow, tkInitPosition, tkInitDisplayMode, tkInitDisplayModeID, tkInitDisplayModePolicy, tkGetCurrentConfig, tkGetDisplayMode, tkGetDisplayModeID, tkGetDisplayModePolicy Window lifecycle and display mode selection
Event loop tkExec, tkQuit Run and stop the TK event loop
Callbacks tkExposeFunc, tkReshapeFunc, tkDisplayFunc, tkKeyDownFunc, tkMouseDownFunc, tkMouseUpFunc, tkMouseMoveFunc, tkIdleFunc Register event handler functions
Input tkGetMouseLoc Query current mouse position
Buffer / color tkSwapBuffers, tkSetRGBMap, tkSetOneColor, tkSetFogRamp, tkSetGreyRamp, tkGetColorMapSize Buffer swap and color map management
Fonts and strings tkCreateBitmapFont, tkCreateFilledFont, tkCreateOutlineFont, tkCreateStrokeFont, tkDrawStr Raster and stroke font rendering
3D primitives tkSolidBox, tkSolidCone, tkSolidCube, tkSolidCylinder, tkSolidSphere, tkSolidTorus, tkWireBox, tkWireCone, tkWireCube, tkWireCylinder, tkWireSphere, tkWireTorus Built-in OpenGL geometry
Misc tkRGBImageLoad, tkGetSystem, tkClipBoard PPM image loading, platform query, clipboard

Window and Display Mode

Initialization order

The TK window creation sequence follows a strict order:

  1. Call tkInitDisplayMode to set the required rendering context attributes.
  2. Optionally call tkInitPosition to specify the initial window position and size.
  3. Call tkInitWindow to create the window and the OpenGL rendering context.
  4. Register callbacks.
  5. Call tkExec to enter the event loop.

Functions

tkInitDisplayMode(ulMode)
Sets the desired OpenGL display mode as a bitmask of TK_* flags before window creation. Common flags:
  • TK_RGB — RGB color mode (as opposed to color-index mode)
  • TK_INDEX — color-index mode
  • TK_DOUBLE — double-buffered rendering
  • TK_SINGLE — single-buffered rendering
  • TK_DEPTH — depth (Z) buffer
  • TK_STENCIL — stencil buffer
  • TK_ACCUM — accumulation buffer
  • TK_ALPHA — destination alpha channel
  • TK_DIRECT — request a direct (hardware) rendering context
tkInitDisplayModeID(id)
Alternative to tkInitDisplayMode: selects the display mode by a platform-specific mode ID obtained from tkGetDisplayModeID.
tkInitDisplayModePolicy(ulPolicy)
Sets the policy for selecting a display mode when an exact match is not available:
  • TK_MINIMUM_CRITERIA — accept the first mode that meets all requested criteria
  • TK_EXACT_MATCH — fail if the exact mode is not available
tkGetDisplayMode()
Returns the display mode flags actually selected after window creation. May differ from the requested mode if the policy allowed a fallback.
tkGetDisplayModeID()
Returns the platform-specific display mode ID actually selected.
tkGetDisplayModePolicy()
Returns the current policy setting.
tkGetCurrentConfig(pConfig)
Fills a TK_Config structure with the actual configuration of the created rendering context: color depths, buffer presence, and direct/indirect status. Useful for querying what was actually allocated after tkInitWindow.
tkInitPosition(x, y, width, height)
Specifies the initial position and size of the window in screen pixels. Must be called before tkInitWindow.
tkInitWindow(pszTitle)
Creates the OS/2 PM window and the OpenGL rendering context. pszTitle is the window title bar string. Returns TRUE on success. The window is associated with the current thread's message queue.
tkCloseWindow()
Destroys the TK window and its rendering context, releasing all associated OpenGL resources.

Event Loop

tkExec()
Enters the TK event loop. Does not return until tkQuit is called. On each iteration the loop:
  1. Dispatches pending PM window messages (resize, keyboard, mouse).
  2. Calls the idle callback (if registered) when the message queue is empty.
  3. Calls the display callback when a redraw is needed.
tkQuit()
Posts a quit request to the TK event loop, causing tkExec to return. Typically called from a key callback (e.g. when the user presses Escape).

Callbacks

All callbacks are registered as function pointers. Pass NULL to unregister a callback.

tkExposeFunc(pfnExpose)
Registers a callback invoked when the window is exposed (uncovered). Signature: void expose(int width, int height).
tkReshapeFunc(pfnReshape)
Registers a callback invoked when the window is resized. Signature: void reshape(int width, int height). The callback should call glViewport(0, 0, width, height) and recalculate the projection matrix.
tkDisplayFunc(pfnDisplay)
Registers the main rendering callback. Signature: void display(void). Called by tkExec whenever a redraw is needed (after expose, reshape, or when tkSwapBuffers triggers the next frame).
tkKeyDownFunc(pfnKeyDown)
Registers a key-press callback. Signature: void keydown(int key, GLenum mask). key is a TK_* key constant; mask carries modifier state (TK_SHIFT, TK_CONTROL).
tkMouseDownFunc(pfnMouseDown)
Registers a mouse-button-press callback. Signature: void mousedown(int x, int y, GLenum mask). mask carries button state (TK_LEFTBUTTON, TK_MIDDLEBUTTON, TK_RIGHTBUTTON).
tkMouseUpFunc(pfnMouseUp)
Registers a mouse-button-release callback. Same signature as tkMouseDownFunc.
tkMouseMoveFunc(pfnMouseMove)
Registers a mouse-motion callback. Called whenever the mouse moves within the window. Signature: void mousemove(int x, int y, GLenum mask).
tkIdleFunc(pfnIdle)
Registers an idle callback. Signature: void idle(void). Called by tkExec when the message queue is empty. Used for continuous animation: the idle function typically updates the scene state and then calls tkSwapBuffers or requests a redisplay.

Input

tkGetMouseLoc(pX, pY)
Returns the current mouse cursor position within the TK window in *pX and *pY. Coordinates are in window pixels with origin at the lower-left corner (OpenGL convention).
tkGetSystem()
Returns a platform identifier. On OS/2, returns TK_OS2PM.

Buffer and Color Management

tkSwapBuffers()
Swaps the front and back buffers in a double-buffered rendering context. Equivalent to glXSwapBuffers on X11. Called at the end of each frame's display callback.
tkSetRGBMap(size, pMap)
Loads a color map (palette) for color-index mode rendering. size is the number of entries; pMap is an array of RGB triplet floats (0.0–1.0 each).
tkSetOneColor(index, r, g, b)
Sets a single color map entry at index to the given RGB values (0.0–1.0).
tkSetFogRamp(density, startIndex)
Loads a fog ramp into the color map starting at startIndex. The ramp grades from the fog color toward white over density steps.
tkSetGreyRamp()
Loads a linear grey ramp into the color map.
tkGetColorMapSize()
Returns the number of entries in the hardware color map.

Fonts and String Rendering

TK provides four font types for rendering text with OpenGL. All font functions operate in the current OpenGL coordinate system.

tkCreateBitmapFont(font)
Creates a bitmap (raster) font. Renders with glBitmap; cannot be rotated or scaled. font selects from the predefined TK font IDs (TK_BITMAP_8_BY_13, TK_BITMAP_9_BY_15, TK_BITMAP_TIMES_ROMAN_10, TK_BITMAP_TIMES_ROMAN_24, TK_BITMAP_HELVETICA_10, TK_BITMAP_HELVETICA_12, TK_BITMAP_HELVETICA_18).
tkCreateFilledFont(font)
Creates a filled (polygon) font rendered using filled OpenGL polygons. Can be transformed with the modelview matrix.
tkCreateOutlineFont(font)
Creates an outline font rendered as unfilled polygon outlines.
tkCreateStrokeFont(font)
Creates a stroke font rendered as line segments.
tkDrawStr(font, pszString)
Renders pszString at the current raster or world-space position using the font object returned by one of the tkCreate*Font functions.

Image Loading

tkRGBImageLoad(pszFilename)
Loads an RGB image file (SGI .rgb / PPM format) and returns a pointer to a TK_RGBImageRec structure containing the image dimensions and pixel data in RGB byte triples. The data can be passed directly to glTexImage2D. The caller is responsible for freeing the structure.

Clipboard

tkClipBoard()
Copies the current window contents to the OS/2 clipboard as a bitmap. Provided as a convenience for capturing OpenGL renderings from Red Book sample programs.

3D Primitives

TK provides twelve built-in 3D objects, each in solid and wire-frame form. Solid objects include surface normals and are suitable for lit scenes. Wire-frame objects use GL_LINE_LOOP primitives.

All primitives are centered at the world-space origin.

Solid function Wire function Object Parameter
tkSolidBox(width, height, depth) tkWireBox(width, height, depth) Axis-aligned box Half-extents in X, Y, Z
tkSolidCube(size) tkWireCube(size) Cube Edge length
tkSolidSphere(radius, slices, stacks) tkWireSphere(radius, slices, stacks) UV sphere Radius; longitude/latitude divisions
tkSolidCone(base, height, slices, stacks) tkWireCone(base, height, slices, stacks) Cone Base radius, height; subdivisions
tkSolidCylinder(radius, height, slices, stacks) tkWireCylinder(radius, height, slices, stacks) Cylinder Radius, height; subdivisions
tkSolidTorus(innerRadius, outerRadius, sides, rings) tkWireTorus(innerRadius, outerRadius, sides, rings) Torus (donut) Inner/outer radii; ring/side divisions

Usage

IBM VisualAge C++ / ILINK

icc -O2 -Gm -c hello.c
ilink /PM:PM hello.obj os2386.lib opengl.lib libtk.lib

OpenWatcom (wlink)

wcl386 -bt=os2 -mf -c hello.c
wlink system os2_pm file hello.obj library os2386.lib library opengl.lib library libtk.lib

EMX/GCC

gcc -Zomf -c hello.c
gcc -Zomf -o hello.exe hello.o os2386.lib opengl.lib libtk.lib

Include files

Header Contents
tk.h All TK prototypes; TK_* display mode flags; TK_* key and button constants; TK_Config, TK_RGBImageRec structures; font ID constants.
gl\gl.h Core OpenGL API (required; include before tk.h).
gl\glu.h GLU utility library (optional; used in many Red Book samples).

Minimal Red Book "hello" window

#include <gl\gl.h>
#include <tk.h>

static void display(void)
{
    glClear(GL_COLOR_BUFFER_BIT);
    glBegin(GL_TRIANGLES);
        glColor3f(1.0f, 0.0f, 0.0f); glVertex2f(-0.5f, -0.5f);
        glColor3f(0.0f, 1.0f, 0.0f); glVertex2f( 0.5f, -0.5f);
        glColor3f(0.0f, 0.0f, 1.0f); glVertex2f( 0.0f,  0.5f);
    glEnd();
    tkSwapBuffers();
}

static void reshape(int w, int h)
{
    glViewport(0, 0, w, h);
    glMatrixMode(GL_PROJECTION);
    glLoadIdentity();
    glOrtho(-1.0, 1.0, -1.0, 1.0, -1.0, 1.0);
    glMatrixMode(GL_MODELVIEW);
}

static void keydown(int key, GLenum mask)
{
    if (key == TK_ESCAPE) tkQuit();
}

int main(void)
{
    tkInitDisplayMode(TK_RGB | TK_DOUBLE | TK_DEPTH);
    tkInitPosition(100, 100, 400, 400);
    tkInitWindow("Hello OpenGL");
    tkDisplayFunc(display);
    tkReshapeFunc(reshape);
    tkKeyDownFunc(keydown);
    tkExec();
    return 0;
}

Relationship to GLUT

Feature TK (LIBTK) GLUT
Window creation tkInitWindow glutCreateWindow
Display mode TK_DOUBLE) GLUT_DOUBLE)
Event loop tkExec glutMainLoop
Display callback tkDisplayFunc glutDisplayFunc
Reshape callback tkReshapeFunc glutReshapeFunc
Idle callback tkIdleFunc glutIdleFunc
Keyboard callback tkKeyDownFunc glutKeyboardFunc
Mouse callback tkMouseDownFunc glutMouseFunc
Primitives tkSolidSphere etc. glutSolidSphere etc.
Multiple windows No Yes
Menus No Yes (glutCreateMenu)
Sub-windows No Yes
Timer callback No Yes (glutTimerFunc)
Image loading tkRGBImageLoad No (use external lib)
Clipboard tkClipBoard No

GLUT is preferred for new OpenGL applications. TK should be used only when porting older Red Book samples that reference the TK API directly.

Version History

Version OS/2 release Date Notes
1.0 OS/2 Warp 3 with OpenGL 1995 Initial OS/2 port of the SGI/IRIX TK library packaged with the OS/2 OpenGL release. Covers window creation, event loop, callbacks, 3D primitives.
1.x OS/2 Warp 4 1996 Added tkClipBoard, display mode policy functions (tkInitDisplayModePolicy, tkGetDisplayModePolicy), tkRGBImageLoad.
1.x OS/2 Warp 4.52 Developer's Toolkit 4.5 2000 Final IBM release. File size: 4,096 bytes (2000-10-16). Source DLL: LIBTK.DLL.

See Also

Retrieved from "https://www.edm2.com/index.php?title=LIBTK.LIB&oldid=92127"