CS 248: Introduction to Computer Graphics

Pat Hanrahan


Auxiliary Library

Put this in your compile line:
-I/usr/class/cs248/support/inc

Put this in your link line:

-L/usr/class/cs248/support/lib -laux -lX11 -lGL

Put this at the top of your source files:

#include <aux.h>

A copy of this document is available at:

/usr/class/cs248/support/docs/libaux.html

Examples of code using this library can be found in:

/usr/class/cs248/support/sample/libaux

The source for this library can be found in:

/usr/class/cs248/support/src/libaux


C Specification

void auxInitDisplayMode (GLenum mask);

void auxInitPosition (int x, int y, int width, int height);

GLenum auxInitWindow(char *titleString);

void auxCloseWindow(void);

void auxQuit(void);

void auxSwapBuffers(void);

void auxMainLoop(void (*displayFunc)(void));

void auxReshapeFunc(void (*function)(GLsizei, GLsizei));

void auxIdleFunc(void (*func)(void));

void auxKeyDownFunc(int key, void (*function)(void));

void auxKeyUpFunc(int key, void (*function)(void));

void auxMouseFunc(int button, int mode, void (*function)(AUX_EVENTREC *));

void auxGetMouseLoc(int *x, int *y);

void auxPrintString(char *string);


Notes

Copyright Information
This library is adapted from the auxiliary library provided with the OpenGL Programming Guide via ftp. See pages vii-viii of the book for information regarding the original version of this library.

Disclaimers

Although the library is written using X11 and OpenGL, and therefore should be portable to any system having both OpenGL and X11, CS248 will only provide support for SGI systems running IRIX 5.3. You are encouraged, however, to port the library to other systems.

Although the library is adapted from the auxiliary library found in the OpenGL Programming Guide, there are some differences from the specification found in Appendix E of the book. Some of these differences are at the hands of the authors of the book, and some of them are at the hands of CS248. We suggest that you use this documentation rather than the one found in the book.

Caveats

Your window system may have key repeat on. This means that when you hold a key down for a while, the auxiliary library will get events saying that the key keeps on getting pressed down and released. To avoid this, you can turn key repeat on and off. You may either go to the Desktop option in Toolchest in the upper left hand corner of your screen and select Customize->Keyboard; or else from a shell command line, you may type:
xset r [ on / off ]


auxInitDisplayMode

void auxInitDisplayMode(GLenum mask);

Tells auxInitWindow() whether to create an RGBA or color-index window, or a single- or double-buffered window. You can also specify that the window have an associated depth, stencil, and/or accumulation buffer. The mask is a bitwise ORed combination of AUX_RGBA or AUX_INDEX, AUX_SINGLE or AUX_DOUBLE, and any of the buffer-enabling flags: AUX_DEPTH, AUX_STENCIL, or AUX_ACCUM.

Function Index


auxInitPosition

void auxInitPosition(int x, int y, int width, int height);

Tells auxInitWindow() where to position a window on the screen. The arguments (x, y) indicates the location of the lower left corner of the window, and the width and height indicate the window's size (in pixels). If x and y are negative, then the window will be placed manually.

Function Index


auxInitWindow

GLenum auxInitWindow(char *titleString);

Opens a window with the characteristics specified by auxInitDisplayMode() and auxInitPosition(). The string titleString appears in the title bar, if your window system does that sort of thing. Also, the Escape key is bound to auxQuit(). GL_TRUE is returned if successful, otherwise GL_FALSE is returned.

Function Index


auxCloseWindow

void auxCloseWindow(void);

Closes the window that was opened with auxInitWindow().

Function Index


auxQuit

void auxQuit(void);

Closes the window that was opened with auxInitWindow(), quits the program, and does general system cleanup.

Function Index


auxSwapBuffers

void auxSwapBuffers(void);

Swaps the front and back buffer of the window, if the window was declared with GL_DOUBLE in auxInitDisplayMode(). The front buffer is the buffer from which the screen is refreshed, and the back buffer is the buffer into which drawing commands take effect.

Function Index


auxMainLoop

void auxMainLoop(void (*displayFunc)(void));

Specifies the function, displayFunc that's called when the window needs to be updated. displayFunc should redraw the objects in your scene.

Function Index


auxReshapeFunc

void auxReshapeFunc(void (*function)(GLsizei, GLsizei));

Specifies the function that's called whenever the window is resized, moved, or exposed. The argument function is a pointer to a function that expects two arguments, the new width and height of the window. With this auxiliary library, the window is automatically redrawn after every reshaping event using the function specified in auxMainLoop().

Function Index


auxIdleFunc

void auxIdleFunc(void (*func)(void));

Specifies the function, func, to be executed if no other events are pending. If zero is passed in, execution of func is disabled.

Function Index


auxKeyDownFunc

void auxKeyDownFunc(int key, void (*function));

Specifies the function, function, that's called when the keyboard key indicated by key is pressed down. Use one of the defined auxiliary constants for key: AUX_A through AUX_Z, AUX_a through AUX_z, AUX_0 through AUX_9, AUX_LEFT, AUX_RIGHT, AUX_UP, AUX_DOWN (the arrow keys), AUX_SPACE, AUX_RETURN, AUX_ESCAPE, AUX_SHIFT_L, AUX_SHIFT_R, AUX_CONTROL_L, AUX_CONTROL_R, AUX_ALT_L, or AUX_ALT_R. With this auxiliary library, the window is automatically redrawn after every processed key event using the function specified in auxMainLoop().

Function Index


auxKeyUpFunc

void auxKeyUpFunc(int key, void (*function));

Specifies the function, function, that's called when the keyboard key indicated by key is released up. Use one of the defined auxiliary constants for key: AUX_A through AUX_Z, AUX_a through AUX_z, AUX_0 through AUX_9, AUX_LEFT, AUX_RIGHT, AUX_UP, AUX_DOWN (the arrow keys), AUX_SPACE, AUX_RETURN, AUX_SHIFT_L, AUX_SHIFT_R, AUX_CONTROL_L, AUX_CONTROL_R, AUX_ALT_L, or AUX_ALT_R. With this auxiliary library, the window is automatically redrawn after every processed key event using the function specified in auxMainLoop().

Function Index


auxMouseFunc

void auxMouseFunc(int button, int mode, void (*function)(AUX_EVENTREC *));

Specifies the function, function, that's called when the mouse registers an event indicated by button and mode.

The button argument can be AUX_NOBUTTON, AUX_LEFTBUTTON, AUX_MIDDLEBUTTON, or AUX_RIGHTBUTTON (assuming a right-handed setup).

When mode is AUX_MOUSELOC, function is called when a mouse movement occurs with the mouse in the state indicated by button. AUX_NOBUTTON corresponds to no button being pressed, AUX_LEFTBUTTON corresponds to the left button being pressed, AUX_MIDDLEBUTTON corresponds to the middle button being pressed, and AUX_RIGHTBUTTON corresponds to the right button being pressed.

When the mode argument is AUX_MOUSEDOWN or AUX_MOUSEUP, function is called when the button indicated by button is pressed or released.

If there are several unprocessed mouse events pending, this auxiliary library skips all of them until it gets to the last mouse event, and calls function using the last unprocessed mouse event.

The function must take one argument, which is a pointer to a structure of type AUX_EVENTREC.

To determine the pointer coordinates at the time of the event, you might define function like this:

void function(AUX_EVENTREC *event)

{
}

Function Index


auxGetMouseLoc

void auxGetMouseLoc(int *x, int *y);

Returns in (x, y) the coordinates of the mouse's current position relative to the window's coordinate system. (0, 0) refers to the top left corner of the window. A negative x or y, or an x greater than the screen width, or a y greater than the screen height indicates that the mouse is outside the window's boundaries.

Function Index


auxPrintString

void auxPrintString(char *string);

Prints string starting at the position specified by the GL raster position using a preloaded font. Use glRasterPos*() to specify the raster position.

Function Index

hanrahan@cs.stanford.edu

Copyright © 1996 Pat Hanrahan