OpenGLUT Input API Proposal

Note:

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

Scope

Motivation

Features

• Support for multiple keyboard, mouse and joystick input devices.
• Support for dynamic connection and disconnection of devices.
• Support for input device state query.
• Support for analog joystick buttons.

Window Event Callback Handlers

Keyboard

Set the application callback for connection or disconnection of a keyboard.

Parameters

• func an application specific keyboard connection event handler
• state is either GLUT_CONNECT or GLUT_DISCONNECT

Support for multiple keyboards is provided by means of the current keyboard context which can be optionally queried or set by the application.

void glutKeyboardKey( void (*func)(unsigned int key, int state))

Set the application callback for a keyboard up or down event.

Parameters

• func an application specific keyboard key event handler
• key the key that has been pressed or released, including special keys
• state GLUT_UP or GLUT_DOWN

Notes

• All connected keyboards use the same event handler
• The event relates to the current keyboard context
• The keycode is either an ASCII code or a special key such as GLUT_KEY_F1
• The mouse position can be queried as needed, rather than being passed along with each keyboard event

This form of keyboard handling consolidates the two GLUT API calls: glutKeyboardFunc and glutSpecialFunc.

Mouse

Set the application callback for a conection or disconnection of a mouse.

Parameters

• func application specific mouse connection event handler
• state GLUT_CONNECT or GLUT_DISCONNECT

Support for multiple mice is provided by means of the current mouse context which can be optionally queried or set by the application.

void glutMouseButton( void (*func)(unsigned int button, int state, int x, int y))

Set the application callback for a mouse button event.

Parameters

• func application specific mouse button event handler
• button GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON or GLUT_RIGHT_BUTTON
• state GLUT_UP or GLUT_DOWN
• x and y window-relative mouse position

void glutMouseMotion( void (*func)(int x, int y))

Set the application callback for a mouse motion event.

Parameters

• func application specific mouse motion event handler
• x and y window-relative mouse position

Joystick

Set the application callback for a conection or disconnection of a joystick.

Parameters

• func application specific joystick connection event handler
• state either GLUT_CONNECT or GLUT_DISCONNECT

void glutJoystickButton( void (*func)(unsigned int button, int state))

Set the application callback for a joystick button event.

Parameters

• func application specific joystick button event handler
• button GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON or GLUT_RIGHT_BUTTON
• state GLUT_UP or GLUT_DOWN

State Query

int glutGetKey(unsigned int param)

Return GLUT_DOWN for a key held down in the current keyboard, GLUT_UP otherwise.

Parameters

• param ASCII key code, or a special key such as GLUT_KEY_F1

int glutGetButton(unsigned int param)

Return GLUT_DOWN for a mouse button held down in the current mouse or joystick, GLUT_UP otherwise.

Parameters

• param GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON or GLUT_RIGHT_BUTTON
• param GLUT_JOYSTICK_BUTTON_1, GLUT_JOYSTICK_BUTTON_2, ...

int glutGetPosition(unsigned int param)

Return the x or y position of the current mouse, relative to current window.

Parameters

• param GLUT_POSITION_X or GLUT_POSITION_Y

GLdouble glutGetAxis(unsigned int param)

Return the value of a joystick axis or button.

Parameters

• param GLUT_JOYSTICK_BUTTON_1, GLUT_JOYSTICK_BUTTON_2, ...
• param GLUT_AXIS_1, GLUT_AXIS_2, ...

Notes

• For digital buttons, returns 1.0 for joystick buttons held down in the current joystick context, 0.0 otherwise.

• For analog buttons, returns a number in the range [0.0,1.0] with 0.0 for unpressed, 1.0 held down completely.

• For analog axes, returns a number in the range [-1.0,1.0] with 0.0 being neutral.

Input Context

Get or set the current keyboard input context.

int glutGetMouse()
void glutSetMouse(int mouse);

Get or set the current mouse input context.

int glutGetJoystick()
void glutSetJoystick(int joystick);

Get or set the current joystick input context.

Version

Feedback