OpenGLUT Documentation
Introduction | Documentation | Examples | Proposals | Authors | Copying | Todo | Bugs | Links

OpenGLUT Device API Proposal

This is a proposal for the purpose of discussion and discussion. This API is not currently implemented in OpenGLUT.


This proposal has essentially the same motivations as the Input proposal. Ultimately, ideas from both proposals could be combined to produce the best solution to updating the support for Input Devices in OpenGLUT.

The design here is a bit different, and generalizes even further to treat the Mouse, Keyboard, Joystick, or any other input device as being essentially equivalent. Each of them is just an Input Device with some number of boolean inputs and some number of analog or range inputs. Furthermore, a Device can also be capable of output, such as beeps, LEDs, and Force Feedback. Hence, the generic name Device instead of Input Device.

Input and output data comes in three general types: 1) Binary: This includes Keys, Buttons and LEDs. 2) Analog: This includes joystick axes, tablet/touch coordinates, and analog "buttons". (Any exmaples of analog output?) 3) Stream data: This encompasses anything with multiple values, such as a device with an LCD letter/number display, or a force feedback joystick.

All input for binary sensors is classified as Button input, including Keyboard keys. However, it is usefule to have a seperate callback for keyboards that return translated data intended for text input. A game may work best to get keyboard button data, but text input should get key data which includes upper/lower case and special multi-key character input.

All analog input is classified as Valuator events (X11 influenced terminology) and include axes, mouse positional data, and analog buttons.

Outputs are not yet covered in this description, and neither is the more complex group of stream data I/O, which should incorporate ForceFeedback Joysticks.

Core Keyboard and Mouse Input

The standard keyboard and mouse functions remain as currently defined, and assumes the system maintains a single core keyboard and mouse at a time. A specific keyboard or mouse can be directly opened via this API. Keyboard events include standard and special keys, and may include additional OEM buttons.

Accessing Devices

int glutOpenDevice(char *name);


Returns an integer device identifier, or zero if unsuccessful. It may be useful to have pre-defined static device ID's for the core keyboard and mouse. Once a device is opened, it will be monitored, and can be polled for data using glutGetDeviceValuator() or glutGetDeviceButton().

void glutCloseDevice(int device);


Window Event Callback Handlers

Each Device callback receives the device identifier as the first argument. This allows one callback to handle multiple devices. However, each device's callback is defined independently.

void glutDeviceStatusFunc( int device, void (*func)(int device, int state))


The device Status callback is similar to the Input proposal's Connect callback, but allows for additional types of state events.

void glutDeviceButtonFunc(int device, void (*func)(int device, unsigned int button, int state))


This form of button/key handling consolidates the several GLUT API calls, including the dials/spaceball/tablet devices: glutKeyboardFunc, glutKeyboardUpFunc, glutSpecialFunc, glutSpecialUpFunc; glutSpaceballButtonFunc, glutButtonBoxFunc, glutTabletButtonFunc, and parts of glutJoystickFunc and glutMouseFunc.

void glutDeviceValuatorFunc( int device, void ( *func )( int dev, int num_vals, int *valuators, int *vals ) )


This form of axis/position handling consolidates the several GLUT API calls, including the dials/spaceball/tablet devices: glutMotionFunc, glutPassiveMotionFunc, glutSpaceballMotionFunc, glutSpaceballRotateFunc, glutDialsFunc, glutTabletMotionFunc, and parts of glutJoystickFunc and glutMouseFunc.

void glutDeviceKeyFunc(int device, void (*func)(int device, unsigned int key, int state))


Although a Keyboard can easily be classified as a generic multi- button input device, normal keyboard usage makes it valuable to receive translated data. For keyboards, this handler is sent data as it would appear for standard typing input: letters are both upper and lower case, and multi-key inputs (i.e. dead keys) are sent as a single event.

State Query

int glutGetDeviceButton(int device, unsigned int button)


int glutGetDeviceValuator(int device, int valuator)


Returns the valuator status, such as mouse coordinates. For axes that are normals in the -1 to 1 range, the result is mapped to range INT_MIN to INT_MAX, just as with glGetIntegerv().

Gldouble glutGetDeviceValuatorDouble(int device, int valuator)

Same as above, but returns a double.

char *glutGetDeviceButtonName(int device, unsigned int button) char *glutGetDeviceValuatorName(int device, int valuator)


These functions return the name of the input item, and should represent the items use. For many devices, the name can be mapped to names in the HID specs. For simple devices, this can be "X" or "Y". Keyboard Special keys should have names like "Shift", "F12", etc. The names of input items could be set by user defined action maps, as in DirectInput.

Input Context

The following functions are included from the Input API proposal. The Joystick get/set is not included because it is never considered a single core device the way Mouse and Keyboard input is, and the device ID context easily handles multiple Joysticks.

Get or Set the current core keyboard or pointer device.

int glutGetKeyboard()
void glutSetKeyboard(int keyboard);

int glutGetMouse()
void glutSetMouse(int mouse);

OpenGLUT Development @ Sourceforge
Homepage | Summary | Files | CVS | Forums | Lists | Bugs | RFE

Generated on Sat Feb 5 01:47:28 2005 for OpenGLUT by doxygen
The OpenGLUT project is hosted by