Using our C functions might work like this :

# Tcl code to create some arrays and add them

set a [new_double 200] set b [new_double 200] set c [new_double 200]

# Fill a and b with some values

for {set i 0} {$i < 200} {incr i 1} { set_double $a $i 0.0 set_double $b $i $i

}

# Add them and store result in c vector_add $a $b $c 200

The functions get_double and set_double can be used to access individual elements of an array. To convert from Tcl lists to C arrays, one could write a few functions in Tcl such as the following :

# Tcl Procedure to turn a list into a C array proc Tcl2Array {l} {

set len [llength $l] set a [new_double $len] set i 0

foreach item $l {

set_double $a $i $item incr i 1

}

return $a

}

# Tcl Procedure to turn a C array into a Tcl List proc Array2Tcl {a size} {

set l {}

for {set i 0} {$i < size} {incr i 1} { lappend $l [get_double $a $i]

}

return $l

}

While not optimal, one could use these to turn a Tcl list into a C representation. The C representation could be used repeatedly in a variety of C functions without having to repeatedly convert from strings (Of course, if the Tcl list changed one would want to update the C version). Likewise, it is relatively simple to go back from C into Tcl. This is not the only way to manage arrays--typemaps can be used as well. The SWIG library file ‘array.i’ also contains a variety of pre-written helper functions for managing different kinds of arrays.

Building a simple OpenGL module

In this example, we consider building a SWIG module out of the OpenGL graphics library. The OpenGL library consists of several hundred functions for building complex 3D images. By wrapping this library, we will be able to play with it interactively from a Tcl interpreter.

Version 1.1, June 24, 1997

Required files

To build an OpenGL module, you will need to have some variant of OpenGL installed on your machine. If unavailable, the Mesa graphics library is an OpenGL clone that runs on most machines that support X11. We will use the “GL/gl.h”, “GL/glu.h”, and the GL Auxilliary libraries.

Wrapping gl.h

The first step is to build an interface from the gl.h file. To do this, follow these steps :

•Copy the file gl.h to a file gl.i which will become the interface.

•Edit the gl.i file by taking out unneeded C preprocessor directives and any other clutter that you find.

•Put the following code at the beginning of the gl.i file

// gl.i : SWIG file for OpenGL %module gl

%{

#include <GL/gl.h> %}

... Rest of edited gl.h file here ...

A critical part of this first step is making sure you have the proper set of typedefs in the gl.i file. The first part of the file should include definitions such as the following :

typedef unsigned int GLenum; typedef unsigned char GLboolean; typedef unsigned int GLbitfield; typedef signed char GLbyte; typedef short GLshort;

typedef int GLint; typedef int GLsizei;

typedef unsigned char GLubyte; typedef unsigned short GLushort; typedef unsigned int GLuint; typedef float GLfloat;

typedef float GLclampf; typedef double GLdouble; typedef double GLclampd; typedef void GLvoid;

Wrapping glu.h

Next we write a module for the glu library. The procedure is essentially identical to gl.h--that is, we’ll copy the header file and edit it slightly. In this case, glu.h contains a few functions involving function pointers and arrays. These may generate errors or warnings. As a result, we can simply edit those declarations out. Fortunately, there aren’t many declarations like this. If access is required later, the problem can often be fixed with typemaps and helper functions. The final glu.i file will look something like this :

%module glu %{

#include <GL/glu.h>

Version 1.1, June 24, 1997

%}

... rest of edited glu.h file here ...

Given these two files, we have a fairly complete OpenGL package. Unfortunately, we still don’t have any mechanism for opening a GL window and creating images. To to this, we can wrap the OpenGL auxilliary library which contains functions to open windows and draw various kinds of objects (while not the most powerful approach, it is the simplest to implement and works on most machines).

Wrapping the aux library

Wrapping the aux library follows exactly the same procedure as before. You will create a file glaux.i such as the following :

// File :glaux.i %module glaux %{

#include “glaux.h” %}

... Rest of edited glaux.h file ...

A few helper functions

Finally, to make our library a little easier to use, we need to have a few functions to handle arrays since quite a few OpenGL calls use them as arguments. Small 4 element arrays are particularly useful so we’ll create a few helper functions in a file called help.i.

// help.i : OpenGL helper functions

%inline %{

GLfloat *newfv4(GLfloat a,GLfloat b,GLfloat c,GLfloat d) { GLfloat *f;

f = (GLfloat *) malloc(4*sizeof(GLfloat)); f[0] = a; f[1] = b; f[2] = c; f[3] = d; return f;

}

void setfv4(GLfloat *fv, GLfloat a, GLfloat b, GLfloat c, GLfloat d) { fv[0] = a; fv[1] = b; fv[2] = c; fv[3] = d;

}

%}

%name(delfv4) void free(void *);

An OpenGL package

Whew, we’re almost done now. The last thing to do is to package up all of our interface files into a single file called opengl.i.

//

// opengl.i. SWIG Interface file for OpenGL %module opengl

Version 1.1, June 24, 1997

To build the module, we can simply run SWIG as follows :

or

unix > swig -tcl -lwish.i opengl.i # Build a statically linked wish executable

Compile the file opengl_wrap.c with your C compiler and link with Tcl, Tk, and OpenGL to create the final module.

Using the OpenGL module

The module is now used by writing a Tcl script such as the following :

load ./opengl.so

auxInitDisplayMode [expr {$AUX_SINGLE | $AUX_RGBA | $AUX_DEPTH}] auxInitPosition 0 0 500 500

auxInitWindow "Lit-Sphere"

# set up material properties

set mat_specular [newfv4 1.0 1.0 1.0 1.0] set mat_shininess [newfv4 50.0 0 0 0]

set light_position [newfv4 1.0 1.0 1.0 0.0]

glMaterialfv $GL_FRONT $GL_SPECULAR $mat_specular glMaterialfv $GL_FRONT $GL_SHININESS $mat_shininess glLightfv $GL_LIGHT0 $GL_POSITION $light_position glEnable $GL_LIGHTING

glEnable $GL_LIGHT0 glDepthFunc $GL_LEQUAL glEnable $GL_DEPTH_TEST

#Set up view glClearColor 0 0 0 0 glColor3f 1.0 1.0 1.0

glMatrixMode $GL_PROJECTION glLoadIdentity

glOrtho -1 1 -1 1 -1 1 glMatrixMode $GL_MODELVIEW glLoadIdentity

#Draw it

glClear $GL_COLOR_BUFFER_BIT glClear $GL_DEPTH_BUFFER_BIT auxSolidSphere 0.5

# Clean up

delfv4 $mat_specular delfv4 $mat_shininess delfv4 $light_position

In our interpreted interface, it is possible to interactively change parameters and see the effects of

Version 1.1, June 24, 1997