Up: Classes   [Index]

GLUTApplication

GLUTApplication Class

The GLUTApplication class provides a class library interface to the GLUT application programming interface, which is a platform-independent window API for OpenGL programs.

The GLUT API uses C functions to handle window system events. This is the simplest approach to adding event handlers. Ctalk does not, itself, use any GLUT or OpenGL functions, so it is normally safe to use Ctalk methods within a window callback, as in this example. 

#include <ctalk/ctalkGLUTdefs.h>

GLUTApplication new teapotApp;

float angle = 0.0f;

void mydisplay (void) {       /* This callback updates the display. */
  glEnable (GL_NORMALIZE);
  glEnable(GL_DEPTH_TEST);
  glClearColor(0.0, 0.0, 0.0, 1.0);
  glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
  glPolygonMode(GL_FRONT_AND_BACK, GL_LINE);
  glLineWidth (1.0f);

  glLoadIdentity ();
  glColor4f (0.0f, 0.0f, 1.0f, 1.0f);

  glRotatef (angle, 0.0f, 1.0f, 0.0f);
  glRotatef (10.0f, 1.0f, 0.0f, 0.0f);

  teapotApp teapot 3.0, 0;    /* Method call within the callback. */

  glutSwapBuffers ();
}

void animation (void) {  /* Callback to update the animation state. */
  angle += 0.2f;
  if (angle >= 360.0f)
    angle = 0.0f;
  glutPostRedisplay();
}

int main (int argc, char **argv) {

  teapotApp initGLUT(argc, argv);
  teapotApp initWindow (640, 480);
  teapotApp createMainWindow ("teapotApp -- GLUTApplication Class");
  teapotApp defineDisplayFn mydisplay;
  teapotApp defineIdleFn animation;
  teapotApp installCallbackFns;
  teapotApp run;
  
}

If you save the example in a file called teapotApp.ca, you can build this program with the following command on Linux/UNIX systems. 


  $ ctcc -x teapotApp.ca -o teapotApp

To build the example on Apple OS X machines, you need to link it with the GLUT application framework. Refer to the discussion below for more information.

You can also use the OpenGL API within methods. This lets programs use C functions, methods, and the GLUT and OpenGL APIs together with few restrictions. The GLUTApplication class does not, at least at this time, support all of the functions that the GLUT API provides, but the API is flexible enough that you can extend it if necessary

Apple OS X Machines

OS X machines include GLUT as an application framework, which Ctalk does not support directly. Ctalk provides the platform independent ctalkGLUTdefs.h include file, which you can use to add the GLUT definitions to programs, by adding a statement like this one to the program. 


#include <ctalk/ctalkGLUTdefs.h>

Then you need to link the program with the framework to produce an executable. Normally you would use a series of commands like these. 


  $ ctalk -I /usr/X11R6/include teapotApp.ca -o teapotApp.i
  $ gcc -framework GLUT teapotApp.i -o teapotApp -lctalk -lreadline \
        -L/usr/X11R6/lib -lGL -lGLU

This example isn’t meant to be definitive. You might need to experiment to find the right build configuration for a particular OS X machine.

There is more platform specific information in the example programs and README file in the demos/glut subdirectory.

The GLUTApplication class doesn’t provide a guide to the very involved subject of programming with the GLUT and OpenGL APIs. There are many references and tutorials available on the Internet and in bookstores that teach OpenGL programming.

Instance Methods

createMainWindow (String title)

Create the main window. The argument, a String contains the window’s title.

cone (Float base, Float height, Integer slices, Integer stacks, Integer fill)

Draw a cone with a base of size base, height height, with slices longitudinal slices and stacks lateral slices. If fill is True, draw a filled cone; otherwise, draw a wireframe cone.

cube (Float size, Integer fill)

Draw a cube with sides of size length. If fill is True, draw a filled cube; otherwise draw a wirefame cube.

defineAnimationFn (Symbol fn)
defineButtonBoxFn (Symbol fn)
defineDialsFn (Symbol fn)
defineDisplayFn (Symbol fn)
defineEntryFn (Symbol fn)
defineIdleFn (Symbol fn)
defineKeyboardFn (Symbol fn)
defineMenuStateFn (Symbol fn)
defineMenuStatusFn (Symbol fn)
defineMotionFn (Symbol fn)
defineMouseFn (Symbol fn)
defineOverlayDisplayFn (Symbol fn)
definePassiveMotionFn (Symbol fn)
defineSpaceballMotionFn (Symbol fn)
defineSpaceballRotateFn (Symbol fn)
defineSpecialFn (Symbol fn)
defineTabletButtonFn (Symbol fn)
defineTabletMotionFn (Symbol fn)
defineVisibilityFn (Symbol fn)
defineTimerFn (Integer msec, Symbol fn, Integer argValue)

Define callback functions for window system events. The argument is the name of the C function that handles the event. Refer to the method’s documentation and the GLUT API’s documentation for information about each callback function’s parameters.

Note: defineAnimationFn and defineTimerFn both use the glutTimerFunc () callback, so the actual callback is the last function defined (before calling installCallBackFns).

The difference is that defineAnimationFn executes its callback 24 times per second, while defineTimerFn uses an application defined interval, and takes three arguments: the timer interval in milliseconds, the name of the callback function, and an integer that is passed to the callback function as an argument.

defineReshapeFn (Symbol fn)

Defines the function used to reshape the window’s 3D viewing space. The default is an orthographic projection, 5 grid units wide on each axis. If you need to duplicate the default viewing area in a program, here is the code that defines it. The variables ‘width’ and ‘height’ are provided by the GLUT application as arguments to the reshape function. 


void defualt_reshape_fn (int width, int height) {
  float ar = (float)width / (float)height;
  glViewport(0, 0, w, h);
  glMatrixMode(GL_PROJECTION);
  glLoadIdentity();
  glOrtho (-5.0 * ar, 5.0 * ar, -5.0, 5.0, 5.0, -5.0);
  glMatrixMode(GL_MODELVIEW);
  glLoadIdentity();
}
dodecahedron (Integer fill)

Draw a dodecahedron. If fill is True, draw a solid dodecahedron; otherwise draw a wireframe dodecahedron.

fullScreen (void)

Resize the main window so that it occupies the entire screen. A call to reshape (the method, not the callback) or position returns the window to its normal state.

icosahedron (Integer fill)

Draw a icosahedron. If fill is True, draw a solid icosahedron; otherwise draw a wireframe icosahedron.

initGlut (Integer argc, Array argv)

Initialize the GLUT window system. If there are any GLUT specific command line arguments, this method parses them and uses then uses the options to configure the window system. This method also calls Application method parseArgs, so the command line arguments are available in the cmdLineArg instance variable (an Array). See Application.

initWindow (Integer width, Integer height)
initWindow (Integer xOrg, Integer yOrg, Integer width, Integer height)

Initialize the main window’s size or, with four arguments, its size and position.

installCallBackFns (void)

Install the callback functions defined by previous calls to define*Fn methods.

octahedron (Integer fill)

Draw a octahedron. If fill is True, draw a solid octahedron; otherwise draw a wireframe octahedron.

tetrahedron (Integer fill)

Draw a tetrahedron. If fill is True, draw a solid tetrahedron; otherwise draw a wireframe tetrahedron.

run (void)

Enter the GLUT API’s main event loop. When this method returns, the program typically exits. Note: GLUT does not provide any events to terminate program. To exit a program normally, use C’s exit (3) function and on_exit(3) (or onexit(3)) to handle any program specific exit processing.

sphere (Float radius, Integer slices, Integer stacks, Integer fill)

Draw a sphere with radius with slices longitudinal sections and stacks lateral sections. If fill is True, draw a filled sphere; otherwise draw a wireframe sphere.

teapot (Integer fill)

Draw the classic teapot demonstration. If fill is True, draw a solid teapot; otherwise draw a wireframe teapot.

torus (Float inner_radius, Float outer_radius, Integer size, Integer rings, Integer fill)

Draw a torus with the inner and outer radii given by the arguments, with a section size and rendered in rings sections. If fill is True, draw a solid torus; otherwise draw a wireframe torus.

windowID (String window_title)

Return an Integer with the X window ID of the window with the title window_title. Note: Some OS’s, like OSX/Darwin, don’t use Xlib to draw windows; in that case, this method won’t be able to provide a lower level window ID.

xpmToTexture (char **xpm_data, Integer width_out, Integer height_out, Symbol texture_data_out)
xpmToTexture (char **xpm_data, Integer alpha, Integer width_out, Integer height_out, Symbol texture_data_out)

Translates a XPM pixmap into an OpenGL texture. The argument xpm_data is the pixmap’s char *pixmap_name[] declaration. If no alpha argument is given, then ‘1.0’ is used to create an opaque texture. Alpha values can range from 0.0 (completely transparent) - 1.0 (completely opaque).

The method sets the arguments width_out, height_out, and texel_data_out with the height, width and data of the texture.

The resulting texture has the format GL_RGBA and the data type GL_UNSIGNED_INT_8_8_8_8, so you can create a 2D texture from a pixmap with statements like these. 


Integer new xpmWidth;
Integer new xpmHeight;
Symbol new texData;

/*
 *  Note that the xpm_data argument should not normally need a
 *  translation from C.
 */
myGLUTApp xpmToTexture xpm_data, xpmWidth, xpmHeight, texData;
glTexImage2D (GL_TEXTURE_2D, 0, GL_RGBA, xpmWidth, xpmHeight, 0,
              GL_RGBA, GL_UNSIGNED_INT_8_8_8_8, texData);

The xpmToTexture method does not do any setup of the OpenGL texture environment. For basic textures, OpenGL works better with textures that have a geometry that is an even multiple of 2; e.g., 128x128 or 256x256 pixels.

Individual applications can add parameters for interpolation, blending, mipmap creation, and material rendering based on the program’s requirements, though.

The Ctalk library only stores the data for one texture at a time, so if a program uses multiple textures, it should save the texture data to a separate Symbol, in orderq to avoid regenerating the texture each time it’s used.

For an example of how to draw with textures, refer to the texture.ca and texblend.ca programs in the Ctalk distribution’s demos/glut subdirectory.

Up: Classes   [Index]