Isis OpenGL interface

OpenGL is a very popular library of 2D and 3D computer graphics
software. It is designed to work independent of operating system,
window system, or graphics hardware configuration. For more
information on OpenGL, go to the official OpenGL web site. To
learn how to program with OpenGL, the OpenGL Programming Guide
published by Addison Wesley is considered the best reference.

This Isis interface library provides full support for every aspect of
OpenGL, including the GL, GLU, GLUT, and GLX libraries. The interface
routines are efficient and direct. Callbacks are also fully
supported.

The functions available in Isis are identical to their counterparts in
C. The function names, argument types, return types, and constants
are exactly the same. Therefore, if you know how to use OpenGL in
C, you can start writing OpenGL scripts in Isis immediately. The only
difference is in the way strings and callbacks are handled, and this
explained below.

Obviously, OpenGL must be installed on your system in order for
anything to work. If you are unsure, check with your system
administrator.

This library also provides a number of utility
routines, written directly in Isis, for simplifying things like
drawing simple shapes, creating and manipulating texture maps, and
rendering texture-mapped text.

Function names

Every function in the GL, GLU, GLUT, and GLX libraries is available in
Isis under the exact same name and expects exactly the same arguments
(see next section for more info on type conversion). For example,
this OpenGL C function:

void glColor3f (GLfloat red, GLfloat green, GLfloat blue);

would be called in Isis like this:

(glColor3f 0.3 0.7 1.0)

In general, calling a function with no arguments will display a short
help message about the arguments that it expects (unless, of course,
it actually expects no arguments).

-> (glColor3f)
** glColor3f: Expects 3 arguments.
** red, green, blue

Constants

Every constant in OpenGL is defined in Isis under the same name. For
example, the OpenGL constants GL_COLOR_BUFFER_BIT and
GL_TRIANGLES can be used in Isis just like in C:

(glClear GL_COLOR_BUFFER_BIT)
(glBegin GL_TRIANGLES)

Argument and return types

When you call an OpenGL interface function in Isis, the arguments you
pass will be converted to the types expected by the actual OpenGL C
function. Similarly, the return value of the C function will be
converted to the most appropriate Isis type.

If the OpenGL function expects a string (a pointer to characters), you
may pass a regular Isis string. Similarly, if the OpenGL function
returns a pointer to characters, then it will be converted to an Isis
string (list of characters).

Otherwise, if the OpenGL function expects a pointer to data of any
other type, you must pass an Isis address that points to data of the
corresponding C type. Similarly, if the OpenGL function returns a
pointer, it is returned in Isis as an address. The utilities in the
memory manipulation library can
be used to convert between Isis lists and arrays of the appropriate C
type.

The table below shows the correspondence between types used by OpenGL,
C, and Isis.

OpenGL type

C type

Isis type

GLbyte

c-char

Integer

GLshort

c-short

GLint

c-int

GLsizei

c-int

GLubyte

c-uchar

GLushort

c-ushort

GLuint

c-uint

GLenum

c-uint

GLbitfield

c-uint

GLfloat

c-float

Real

GLclampf

c-float

GLdouble

c-double

GLclampd

c-double

GLboolean

c-uchar

Boolean

pointers

c-pointer

Address

For example, take the following OpenGL C function:

int glutCreateWindow(char *title);

This function expects a pointer to characters. Therefore, you can
pass a regular Isis string, like this:

(glutCreateWindow "single triangle")

Now take this OpenGL C function:

void glColor3fv (GLfloat *v);

This function expects a pointer to data of type GLfloat,
which from the table above, we know corresponds to the C type
c-float. Therefore, you need to use pack to create
an array of floats to pass to the function. If you do not
intend to use the array after the function is called, be sure to free
it. Here is an example:

Callbacks

Some OpenGL functions use callbacks. Since OpenGL cannot directly
invoke Isis procedures, there needs to be a "middleman" C function
that will invoke the actual Isis callback procedure. Therefore,
registering a callback in Isis requires identifying both the Isis
callback procedure and the "middleman" C function.

Middleman C functions have already been defined for every possible
OpenGL callback, and addresses of these functions are bound in Isis
(see table below). When you register a callback, you must pass the
address of the appropriate middleman C function directly to OpenGL.
Then you must tell that middleman C function which Isis procedure it
should call by updating its "callback slot" (see table below). Use
these functions to update callback slots:

For example, suppose you want to set the window reshape callback in
GLUT. As described in the OpenGL documentation, the reshape function
should take two arguments: a width and height. Here is an example of
how to define the callback procedure and register it with OpenGL:

First, the reshape Isis procedure is created. Then, the
address of the appropriate middleman C function (found in the table
below) is registered directly with OpenGL. Then the callback slot for
that middleman C function (also found in the table below) is updated
to the Isis reshape procedure.

The addresses of the middleman C functions are defined in Isis under
the names listed below:

These fonts have been developed especially for Isis. They are
typically stored in the fonts subdirectory of the Isis root
directory on your system. gl-load-font will automatically
search for fonts there. Check the directory for a full list of what's
available.

gl-generate-texture-image loads an arbitrary Isis image into
the specified texture object. A scale factor (a list of 2 real
numbers) indicates how the image should be scaled before creating a
texture from it. Normally you would pass [1.0 1.0], but you
could provide smaller scale factors if texture memory is limited.

internal-format specifies the format of the image in internal
texture memory (read about them on the man page for
glTexImage2D()). In most cases you will want it to be just
GL_RGBA or GL_RGB, depending on the number of
channels.

gl-find-texture-size accepts an image size and returns the
closest valid texture size that will hold the entire image.
gl-set-texture-image loads the given image directly into the
texture. It must be an interleaved byte-sampled image (such as one
created with gl-new-image) with valid texture dimensions
(usually the horizontal and vertical sizes must be powers of 2).
gl-update-texture-image updates a portion of the texture with
the given image, starting at the given position. Again it must be a
4-channel interleaved image, but it need not have valid texture
dimensions.