OpenGLUT Device API Proposal

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

Motivation

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);

Parameters

name The name of the device. The interpretation of the device name is not yet defined, but should support a defined set of standard names such as Mouse0, Mouse1, etc.

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);

Parameters

device The integer device ID returned by a call to glutOpenDevice().

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))

Parameters

device is the integer device identifier, which is also passed to the handler so that one callback can manage multiple devices.
func an application specific event handler
state is either GLUT_CONNECT or GLUT_DISCONNECT, and may be extended to other events, like GLUT_RESET, or DEVICE_LOST (still connected, but another process GRABBED it, etc.).

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))

Parameters

device is the integer device identifier, which is also passed to the handler so that one callback can manage
func an application specific device key/button handler
button the button (or key) that has been pressed or released. For keyboards, standard and special keys are all included.
state GLUT_UP or GLUT_DOWN

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 ) )

Parameters

device is the integer device identifier, which is also passed to the handler so that one callback can manage
func an application specific device key/button handler
num_values the number of valuator state changes being reported
valuators an array of valuator identifiers.
values an arry of values for the listed valuators. Note: The *valuators list could be dropped, and just report all valuators, or include an int first_valuator, and always report consecutive valuators.

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))

Parameters

device is the integer device identifier, which is also passed to the handler so that one callback can manage
func an application specific device key/button handler
key the key that has been pressed or released. For keyboards, standard and special keys are all included.
state GLUT_UP or GLUT_DOWN

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)

Parameters

device is the integer device identifier.
button is the button ID. For keyboards, the ID is either an ASCII key code, or a special key such as GLUT_KEY_F1. For mice, GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON and GLUT_RIGHT_BUTTON will be valid.

int glutGetDeviceValuator(int device, int valuator)

Parameters

device is the integer device identifier.
valuator is the valuator number. For mice and simple joysticks, X-Axis is 0 and Y-Axis is 1, and can have matching #defines for readability, such as GLUT_POSITION_X or GLUT_AXIS_X, etc.

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)

Parameters

device is the integer device identifier.
button is the button ID.
valuator is the valuator ID.

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);

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