OpenGLUT 0.6.3 development - OpenGLUT: OpenGLUT 1.0 Input API Proposal
Keywords: OpenGLUT, FreeGLUT, OpenGL, GLUT, X11, Windows, Programming, Documentation, Download, Development, Sourceforge

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

# OpenGLUT 1.0 Input API Proposal

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

## Scope

This proposal is limited to the scope of the OpenGLUT input handling API including keyboard, mouse and joysticks.

## Motivation

There are several aspects of OpenGLUT input handling that can be improved. GLUT evolved over time retaining backwards compatibility, introducing some degree of duplication and inconvenience. The GLUT abstraction of joysticks has been superceded by technical advances - USB, additional axes and analog (non-binary) buttons. Another limitation of the GLUT API is support for only one keyboard, one mouse and one joystick.

## Window Event Callback Handlers

### Keyboard

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

`void glutKeyboardConnect( void (*func)(int state) )`

Parameters

- func an application specific keyboard connect event handler
- state is either GLUT_CONNECT or GLUT_DISCONNECT

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

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 the ASCII code, or a special key such as GLUT_KEY_F1
- The mouse position should be queried if needed, rather than passes with every event

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

### Mouse

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

`void glutMouseConnect( void (*func)(int state) )`

Parameters

- func an application specific mouse connect event handler
- state is either GLUT_CONNECT or GLUT_DISCONNECT

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

Parameters

- func an application specific keyboard key event handler
- button the button that has been pressed or released
- state GLUT_UP or GLUT_DOWN
- x and y is the position of the mouse press or release

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

Parameters

- func an application specific keyboard key event handler
- state GLUT_DOWN if any button is being held, otherwise GLUT_UP
- x and y is the position of the mouse

## Joystick

`void glutJoystickConnect( void (*func)(int state) )`

Parameters

- func an application specific joystick connect event handler
- state is either GLUT_CONNECT or GLUT_DISCONNECT

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

Parameters

- func an application specific keyboard key event handler
- button the button that has been pressed or released
- state GLUT_UP or GLUT_DOWN

## State Query

Keypress, mouse button and joystick button state transitions are communicated to OpenGLUT windows as GLUT_UP or GLUT_DOWN events. It is also useful to know about keys or buttons currently being held down. Analog inputs such as joystick axes are more conveniently treated as continuously changing state, rather than individual events.

`int glutGetKey(unsigned int param)`

Parameters

- param is either an ASCII key code, or a special key such as GLUT_KEY_F1

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

`int glutGetButton(unsigned int param)`

Parameters

- param is either GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON or GLUT_RIGHT_BUTTON

Returns GLUT_DOWN for a mouse button held down in the current mouse context, GLUT_UP otherwise.

Parameters

- param is either GLUT_POSITION_X or GLUT_POSITION_Y

Returns the x or y position of the current mouse context.

`GLdouble glutGetAxis(unsigned int param)`

Parameters

- param is either GLUT_JOYSTICK_BUTTON_1, GLUT_JOYSTICK_BUTTON_2, ...
- param is either GLUT_AXIS_1, GLUT_AXIS_2, ...

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 with down completely.

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

## Input Context

For applications supporting multiple keyboards, mice or joysticks.

Get the current input context, in order to identify the individual device.

Set the current input context, for querying state of specific devices.

`int glutGetKeyboard()
void glutSetKeyboard(int keyboard);`

`int glutGetMouse()
void glutSetMouse(int mouse);`

`int glutGetJoystick()
void glutSetJoystick(int joystick);`

## Feedback

Feedback, comments or suggestions can be directed either to the mail list or discussion forum.
OpenGLUT Development @ Sourceforge
Homepage | Summary | Files | CVS | Forums | Lists | Bugs | RFE
Generated on Tue Oct 5 18:44:32 2004 for OpenGLUT by doxygen 1.3.8
The OpenGLUT project is hosted by sourceforge.net.