Auxiliary Library

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)



	GLint x, y;
	x = event->data[AUX_MOUSEX];

	y = event->data[AUX_MOUSEY];

	...


}

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

[email protected]