Isis OpenGL interface Isis software documentation

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:
(set colbuf (pack [0.4 0.7 0.2] c-float)) (glColor3fv colbuf) (free colbuf)


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:

(update-glu-callback-slot callback-slot isis-procedure) # for GLU callbacks (update-glut-callback-slot callback-slot isis-procedure) # for GLUT callbacks

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:

(set reshape (proc (w h) (print "Window resized to: " [w h] newline))) (glutReshapeFunc glut_reshape) (update-glut-callback-slot glut_reshape_slot reshape)
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:

glut_create_menu glut_display glut_reshape glut_keyboard glut_mouse glut_motion glut_passive_motion glut_entry glut_visibility glut_idle glut_timer glut_menu_state glut_special glut_spaceball_motion glut_spaceball_rotate glut_spaceball_button glut_button_box glut_dials glut_tablet_motion glut_tablet_button glut_menu_status glut_overlay_display glu_tess_begin glu_tess_begin_data glu_tess_edge_flag glu_tess_edge_flag_data glu_tess_vertex glu_tess_vertex_data glu_tess_end glu_tess_end_data glu_tess_combine glu_tess_combine_data glu_tess_error glu_tess_error_data glu_quadric_error glu_nurbs_error

Below is the list of callback slots corresponding to each of the middleman functions:

glut_create_menu_slot glut_display_slot glut_reshape_slot glut_keyboard_slot glut_mouse_slot glut_motion_slot glut_passive_motion_slot glut_entry_slot glut_visibility_slot glut_idle_slot glut_timer_slot glut_menu_state_slot glut_special_slot glut_spaceball_motion_slot glut_spaceball_rotate_slot glut_spaceball_button_slot glut_button_box_slot glut_dials_slot glut_tablet_motion_slot glut_tablet_button_slot glut_menu_status_slot glut_overlay_display_slot glu_tess_begin_slot glu_tess_begin_data_slot glu_tess_edge_flag_slot glu_tess_edge_flag_data_slot glu_tess_vertex_slot glu_tess_vertex_data_slot glu_tess_end_slot glu_tess_end_data_slot glu_tess_combine_slot glu_tess_combine_data_slot glu_tess_error_slot glu_tess_error_data_slot glu_quadric_error_slot glu_nurbs_error_slot


A simple example

(set disp (proc () (begin (glClear GL_COLOR_BUFFER_BIT) (glBegin GL_TRIANGLES) (glColor3f 0.0 0.0 1.0) (glVertex2i 0 0) (glColor3f 0.0 1.0 0.0) (glVertex2i 200 200) (glColor3f 1.0 0.0 0.0) (glVertex2i 20 200) (glEnd) (glFlush)))) (set reshape (proc (w h) (begin (glViewport 0 0 w h) (glMatrixMode GL_PROJECTION) (glLoadIdentity) (glOrtho 0.0 (real w) 0.0 (real h) -1.0 1.0) (glScalef 1.0 -1.0 1.0) (glTranslatef 0.0 (* -1.0 (real h)) 0.0)))) (set progname (pack "simple.isis" c-char)) (set mainargc (pack [1] c-int)) (set mainargv (pack [progname] c-pointer)) (glutInit mainargc mainargv) (glutCreateWindow "single triangle") (glutDisplayFunc glut_display) (glutReshapeFunc glut_reshape) (update-glut-callback-slot glut_display_slot disp) (update-glut-callback-slot glut_reshape_slot reshape) (glutMainLoop)


Other examples

  • Bezier surface
  • Teapots


    OpenGL Utility routines

    In addition to basic OpenGL functionality, several utility routines written directly in Isis are available that help simplify things like drawing simple shapes, creating and manipulating texture maps, and rendering texture-mapped text.

    GLUT utilities

    (glut-init progname) # initialize GLUT (glut-create-window name size position doublebuf?) # create GLUT window (glut-create-sub-window name size position doublebuf?) # create GLUT sub-window glut-init initializes GLUT with the given program name. glut-create-window creates a simple RGB GLUT window with the given name, size, position, and double buffering mode (True or False) and returns the window id. glut-create-sub-window creates a sub-window inside the specified window.

    GL format RGBA image buffers

    (gl-new-image chans [xsize ysize]) # create an interleaved image (gl-transfer-convert-rgba inbuf outbuf) # convert any image to rgba gl-new-image creates a new interleaved byte-sampled Isis image buffer of the given size. Such an image buffer would be appropriate for use in functions like glDrawPixels or glTexImage2D. Up to 4 channels may be specified, where the individual channels represent red, green, blue, and alpha (opacity) data, respectively.

    gl-transfer-convert-rgba will convert an arbitrary image into RGBA format. inbuf should be a byte-sampled buffer consisting of between 1 and 4 channels. outbuf should be a 4-channel byte-sampled buffer, perhaps one allocated with gl-new-image. The output image is formed differently depending on the number of channels in the input image. If the input has only 1 channel (intensity), that channel is duplicated into the first three channels of the output, and the output alpha channel is filled with 255. If the input has 2 channels (intensity and alpha), the second channel is used as the output alpha channel. If the input has 3 channels (RGB), they are duplicated into the first 3 channels of the output, and the alpha channel is again filled with 255. If the input has 4 channels (RGB with alpha), it is transferred without any change.

    2D Drawing utilities

    (gl-draw-rectangle pos size) (gl-draw-textured-rectangle pos size texture texpos texsize) (gl-draw-regular-polygon pos size sides) (gl-draw-textured-regular-polygon pos size sides texture texpos texsize) (gl-draw-line pointlist) (gl-draw-points pointlist) (gl-transform-object scale rotation position) These routines are used by Macaroni to render various types of primitive 2D objects, but they may be used directly as well. Positions, scales, and sizes should always be lists of 2 real numbers. pos locates the lower left corner of a rectangle, or the center of a regular polygon. size specifies the size of the rectangle, or the horizontal and vertical extent of a regular polygon. texture should be an OpenGL texture object. texpos and texsize indicate the origin of the texture and the size of the texture on the object (using the same coordinate system and units as the object position and size). sides should be an integer number of sides for the polygon (you can make circles by specifying a large number of sides). pointlist should be a list of vertices, each a list containing 2 real numbers. rotation should be given in degrees and should be a real number.

    Texture mapped fonts and text

    (gl-load-font fontname fontheight) # load a texture map font (gl-draw-text text font fixed? cscale lscale pos) (gl-measure-text text font fixed? cscale lscale) gl-load-font loads a texture map font. fontname should be a string and fontheight an integer. The return value is a font information structure that may be used in a
    Macaroni text object or in a call to gl-draw-text. gl-draw-text accepts a string of text to draw, a font (obtained from gl-load-font), a boolean indicating whether to use fixed character spacing, real number character spacing and line spacing scale factors, and a place to start drawing (the lower left corner of the first line of text). gl-measure-text can be used to measure the size of a block of text before actually drawing it (to determine an appropriate starting position).

    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.

    Texture mapping utilities

    (gl-create-texture) (gl-delete-texture texture) (gl-set-texture-parameters texture wrap? interpolate?) (gl-generate-texture-image texture image scale internal-format) (gl-find-texture-size size) (gl-set-texture-image texture image internal-format) (gl-update-texture-image texture image position) These routines help you create and manipulate GL texture objects. gl-create-texture creates and returns a new GL texture object, to be used as the texture argument in other routines. gl-delete-texture deallocates the specified texture. gl-set-texture-parameters changes the wrapping and interpolation modes (specified as booleans) of the given texture object.

    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.


    Requirements:
    Scripts: (load "opengl-utilities.isis")
    Libraries: -lisis_gl -lisis_glu -lisis_glut -lisis_glx
    -lGL -lGLU -lglut -lX11
    Headers: isis_gl.h
    isis_glu.h
    isis_glut.h
    isis_glx.h
    Binders: bind_gl_library(script);
    bind_glu_library(script);
    bind_glut_library(script);
    bind_glx_library(script);
    Other: Open GL must be installed on the system.